@zhuan-ai/zhuanspec 2.15.7 → 2.16.0

package/dist/core/configurators/codex.js

@@ -13,12 +13,22 @@
  *
  *   ~/.codex/ (or $CODEX_HOME)
  *     config.toml   - Per-project [projects."…"] trusted_level = "trusted"
- *                     block (wrapped in TRUST markers keyed by absolute path)
+ *                     block (wrapped in TRUST markers keyed by absolute path).
+ *                     Also receives [hooks.state."<abs>:<event>:<i>:<j>"]
+ *                     entries grafted from other already-trusted projects,
+ *                     wrapped in HOOK_STATE markers keyed by config.toml path.
  *
  * Codex does **not** load project-scoped hooks/subagents unless the project
  * is explicitly marked trusted in the global config (see openai/codex#14601),
  * so we opportunistically write that trust entry during `zhuanspec init`.
  *
+ * Codex CLI >= 0.129 additionally requires each hook's content hash to be
+ * pre-approved (openai/codex#20321) or the user sees "N hooks need review".
+ * The `trusted_hash` in `[hooks.state.<key>]` depends only on normalised hook
+ * *content* (event + matcher + command), not on the key path, so we clone a
+ * previously approved hash to the current project's key to skip the manual
+ * review prompt in fresh workspaces.
+ *
  * Idempotency:
  *   - Hooks block is regenerated inside ZHUANSPEC markers on every run.
  *   - Trust entries are keyed by absolute path; repeated runs no-op.
@@ -28,7 +38,7 @@ import path from 'path';
 import os from 'os';
 import { promises as fs } from 'fs';
 import { FileSystemUtils } from '../../utils/file-system.js';
-import { getCodexHooksTomlBlock } from '../templates/codex-hooks-template.js';
+import { getCodexHooksTomlBlock, getCodexDefaultHookSlots } from '../templates/codex-hooks-template.js';
 import { getCodexAgentTomls, } from '../templates/codex-agents-template.js';
 import { getCodexSkillFiles } from '../templates/codex-skills-template.js';
 import { CodexSlashCommandConfigurator } from './slash/codex.js';
@@ -51,6 +61,18 @@ function buildTrustMarkers(projectPath) {
         end: `# <!-- ZHUANSPEC:TRUST:END path=${projectPath} -->`,
     };
 }
+/**
+ * Build the per-path HOOK_STATE marker pair for the global config.toml.
+ * Keyed by the **project config.toml absolute path** (not the project dir)
+ * so it aligns with the prefix of each `[hooks.state."<config-path>:..."]`
+ * key that Codex records.
+ */
+function buildHookStateMarkers(projectConfigTomlPath) {
+    return {
+        start: `# <!-- ZHUANSPEC:HOOK_STATE:START path=${projectConfigTomlPath} -->`,
+        end: `# <!-- ZHUANSPEC:HOOK_STATE:END path=${projectConfigTomlPath} -->`,
+    };
+}
 export class CodexConfigurator {
     name = 'Codex';
     /** Codex reads AGENTS.md for project instructions (no dedicated CODEX.md). */
@@ -80,6 +102,7 @@ export class CodexConfigurator {
         const skillsWritten = await this.mirrorSkills(projectPath);
         const configTomlPath = await this.writeProjectConfigToml(codexDir, agentFiles);
         const { globalConfigPath, trustEntryAdded } = await this.ensureGlobalTrustEntry(projectPath);
+        const hookTrust = await this.ensureHookTrustSeed(globalConfigPath, configTomlPath);
         const conflictingGlobalHooksJson = await this.detectGlobalHooksJsonConflict();
         // Codex CLI >= 0.117 no longer scans `~/.codex/prompts/`; delete any
         // ZhuanSpec-managed prompt left behind by pre-2.12.5 installs so the
@@ -94,6 +117,7 @@ export class CodexConfigurator {
             trustEntryAdded,
             conflictingGlobalHooksJson,
             legacyPromptsCleaned,
+            hookTrust,
         };
     }
     /**
@@ -292,5 +316,213 @@ export class CodexConfigurator {
         const block = this.buildTrustBlock(projectPath);
         return `${before}${block}${after}`;
     }
+    /**
+     * Graft `[hooks.state."<key>"] trusted_hash = "sha256:..."` entries for the
+     * current project from any other project that the user has already approved
+     * via Codex's `/hooks` TUI. The grafted block is wrapped in HOOK_STATE
+     * markers keyed by `configTomlPath` so it stays idempotent across runs and
+     * coexists with HOOK_STATE blocks for sibling projects in the same file.
+     *
+     * Strategy:
+     *   - Strip our own existing block first to avoid self-referencing seeds.
+     *   - Scan remaining `[hooks.state."<path>:<event>:<grp>:<hdl>"]` tables;
+     *     index their `trusted_hash` by the `<event>:<grp>:<hdl>` suffix so the
+     *     same logical hook in any other project can serve as a seed.
+     *   - For each ZhuanSpec default slot:
+     *       * If a native (unmanaged) entry already owns the same key in this
+     *         project, skip to avoid TOML duplicate-key errors.
+     *       * Else if a seed exists, emit a managed entry pointing the user's
+     *         project key at the known-good hash.
+     *       * Else record the slot in `skippedNoSeed` so callers can surface a
+     *         "please approve once in Codex" hint.
+     *
+     * Failures are non-fatal: any unexpected error is swallowed and reported
+     * via an empty result with `seedAvailable=false`, since hook trust is a
+     * UX optimisation — missing it just means the user sees the regular
+     * Codex review prompt.
+     */
+    async ensureHookTrustSeed(globalConfigPath, configTomlPath) {
+        const slots = getCodexDefaultHookSlots();
+        const empty = {
+            written: [],
+            skippedNoSeed: slots.map(slotSuffix),
+            skippedNative: [],
+            seedAvailable: false,
+        };
+        try {
+            let existing = '';
+            if (await FileSystemUtils.fileExists(globalConfigPath)) {
+                existing = await FileSystemUtils.readFile(globalConfigPath);
+            }
+            // 1. Strip our own block so we don't seed from ourselves and so the
+            //    "native conflict" check only sees user/legacy entries.
+            const stripped = stripHookStateBlock(existing, configTomlPath);
+            // 2. Build seed map (suffix → first hash seen anywhere except this project).
+            const allEntries = parseHookStateEntries(stripped);
+            const seedBySuffix = new Map();
+            const nativeOwnedSuffixes = new Set();
+            for (const entry of allEntries) {
+                const split = splitHookStateKey(entry.key);
+                if (!split)
+                    continue;
+                if (split.pathPart === configTomlPath) {
+                    // Native (unmanaged) entry already exists for this project's slot.
+                    nativeOwnedSuffixes.add(split.suffix);
+                    continue;
+                }
+                if (!seedBySuffix.has(split.suffix)) {
+                    seedBySuffix.set(split.suffix, entry.hash);
+                }
+            }
+            const seedAvailable = seedBySuffix.size > 0;
+            // 3. Plan per-slot writes.
+            const written = [];
+            const skippedNoSeed = [];
+            const skippedNative = [];
+            const blockEntries = [];
+            for (const slot of slots) {
+                const suffix = slotSuffix(slot);
+                if (nativeOwnedSuffixes.has(suffix)) {
+                    skippedNative.push(suffix);
+                    continue;
+                }
+                const seed = seedBySuffix.get(suffix);
+                if (!seed) {
+                    skippedNoSeed.push(suffix);
+                    continue;
+                }
+                const fullKey = `${configTomlPath}:${suffix}`;
+                blockEntries.push({ key: fullKey, hash: seed });
+                written.push(suffix);
+            }
+            // 4. Persist. When nothing to write, ensure any stale managed block is
+            //    removed (e.g. user revoked all hooks elsewhere); otherwise replace.
+            const finalContent = blockEntries.length === 0
+                ? stripped
+                : insertHookStateBlock(stripped, configTomlPath, buildHookStateBlockBody(configTomlPath, blockEntries));
+            if (finalContent !== existing) {
+                await FileSystemUtils.writeFile(globalConfigPath, finalContent);
+            }
+            return { written, skippedNoSeed, skippedNative, seedAvailable };
+        }
+        catch {
+            // Non-fatal: hook trust seeding is a UX optimisation.
+            return empty;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Hook trust seed helpers (module-private).
+//
+// These intentionally avoid pulling in a TOML parser dependency — we only
+// need to read/write a tightly scoped subset of `~/.codex/config.toml`
+// (`[hooks.state."..."]` tables with a single `trusted_hash` value) and
+// must round-trip the rest of the user's file byte-for-byte.
+// ---------------------------------------------------------------------------
+/** `<event>:<group>:<handler>` suffix used both for seed lookup and key building. */
+function slotSuffix(slot) {
+    return `${slot.eventSnake}:${slot.groupIndex}:${slot.handlerIndex}`;
+}
+/**
+ * Parse `[hooks.state."<key>"] trusted_hash = "..."` entries from a TOML
+ * blob using a line walker (no full TOML grammar needed).
+ */
+function parseHookStateEntries(content) {
+    const lines = content.split('\n');
+    const entries = [];
+    const headerRe = /^\[hooks\.state\."((?:[^"\\]|\\.)+)"\]\s*$/;
+    const hashRe = /^trusted_hash\s*=\s*"([^"]+)"\s*$/;
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(headerRe);
+        if (!m)
+            continue;
+        const rawKey = m[1];
+        // Walk forward until the next table header or EOF, capturing trusted_hash.
+        for (let j = i + 1; j < lines.length; j++) {
+            const trimmed = lines[j].trim();
+            if (trimmed === '' || trimmed.startsWith('#'))
+                continue;
+            if (trimmed.startsWith('['))
+                break;
+            const h = trimmed.match(hashRe);
+            if (h) {
+                entries.push({ key: unescapeTomlBasic(rawKey), hash: h[1] });
+                break;
+            }
+        }
+    }
+    return entries;
+}
+/**
+ * Split a hook-state key (`<config-toml-path>:<event>:<grp>:<hdl>`) into its
+ * path prefix and 3-field suffix. Handles paths containing `:` (Windows
+ * drives, etc.) by splitting on the **last** three colons.
+ */
+function splitHookStateKey(key) {
+    const parts = key.split(':');
+    if (parts.length < 4)
+        return null;
+    const suffix = parts.slice(-3).join(':');
+    const pathPart = parts.slice(0, parts.length - 3).join(':');
+    if (!pathPart)
+        return null;
+    return { pathPart, suffix };
+}
+/** Reverse TOML basic-string escapes for `\\\\` and `\\"` (sufficient for paths). */
+function unescapeTomlBasic(raw) {
+    return raw.replace(/\\\\/g, '\\').replace(/\\"/g, '"');
+}
+/** Forward TOML basic-string escape — mirrors `escapeBasic` used elsewhere. */
+function escapeTomlBasic(raw) {
+    return raw.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/** Build the body (between markers) of the HOOK_STATE managed block. */
+function buildHookStateBlockBody(configTomlPath, entries) {
+    const { start, end } = buildHookStateMarkers(configTomlPath);
+    const tables = entries.map((e) => [`[hooks.state."${escapeTomlBasic(e.key)}"]`, `trusted_hash = "${e.hash}"`].join('\n'));
+    const header = [
+        '# ZhuanSpec hook trust seeds — grafted from previously approved projects.',
+        '# Managed block; regenerated by `zhuanspec init/update`. Do not edit by hand.',
+    ].join('\n');
+    return [start, header, '', tables.join('\n\n'), end].join('\n');
+}
+/** Remove our marker-wrapped HOOK_STATE block for `configTomlPath` from `content`. */
+function stripHookStateBlock(content, configTomlPath) {
+    const { start, end } = buildHookStateMarkers(configTomlPath);
+    const startIdx = content.indexOf(start);
+    if (startIdx === -1)
+        return content;
+    const endIdx = content.indexOf(end, startIdx + start.length);
+    if (endIdx === -1)
+        return content;
+    const blockStart = startIdx;
+    let blockEnd = endIdx + end.length;
+    // Consume the trailing newline written together with the block so we
+    // don't leave an orphan blank line behind. Leave any leading newline
+    // intact so `insertHookStateBlock` produces a stable, idempotent layout.
+    if (content[blockEnd] === '\n')
+        blockEnd += 1;
+    return content.substring(0, blockStart) + content.substring(blockEnd);
+}
+/**
+ * Insert (or replace) the HOOK_STATE managed block for `configTomlPath` in
+ * `content`. When a previous block exists, it's swapped in-place to keep the
+ * file order stable. Otherwise the block is appended to EOF; we adjust the
+ * separator so a follow-up `strip + insert` round-trip produces byte-for-byte
+ * the same result (idempotency).
+ */
+function insertHookStateBlock(content, configTomlPath, block) {
+    const { start, end } = buildHookStateMarkers(configTomlPath);
+    const startIdx = content.indexOf(start);
+    if (startIdx !== -1) {
+        const endIdx = content.indexOf(end, startIdx + start.length);
+        if (endIdx !== -1) {
+            const before = content.substring(0, startIdx);
+            const after = content.substring(endIdx + end.length);
+            return `${before}${block}${after}`;
+        }
+    }
+    const separator = content.length === 0 || content.endsWith('\n') ? '' : '\n';
+    return `${content}${separator}${block}\n`;
 }
 //# sourceMappingURL=codex.js.map

package/dist/core/hooks/collect-knowledge.js

@@ -8,8 +8,56 @@
  * Design principle: no keyword matching, no auto-save — the LLM decides.
  */
 import path from 'path';
+import { promises as fs } from 'fs';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { detectHookHost, sanitizeCodexEnvelope } from '../../utils/hook-host.js';
+/** Level 2 兼容用的关键词（与 deviation-check 中 USER_CORRECTION_KEYWORDS/REQUIREMENT_CHANGE_KEYWORDS 保持同步） */
+const FALLBACK_CORRECTION_KEYWORDS = ['不对', '错了', '不是这样', '改成', '重做', '错误', '有问题', '有 bug'];
+const FALLBACK_REQUIREMENT_KEYWORDS = ['需求改', '需求变更', '需求调整', '新增需求', '补充需求'];
+async function readCorrectionStats(cwd, changeId) {
+    if (!changeId)
+        return null;
+    const userInputsPath = path.join(cwd, 'zhuanspec', 'changes', changeId, 'metrics', 'user_inputs.json');
+    try {
+        const raw = await fs.readFile(userInputsPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        const inputs = Array.isArray(parsed.inputs) ? parsed.inputs : [];
+        if (inputs.length === 0)
+            return { level: 3, hardCorrectionCount: 0, requirementChangeCount: 0 };
+        const hasSignal = inputs.some((i) => i && typeof i === 'object' && 'correctionSignal' in i);
+        if (hasSignal) {
+            let hard = 0;
+            let req = 0;
+            for (const entry of inputs) {
+                const sig = entry['correctionSignal'];
+                const postBaseline = entry['postBaseline'] === true;
+                if (!sig || sig.kind !== 'hard' || !postBaseline)
+                    continue;
+                if (sig.isRequirementChange)
+                    req += 1;
+                else
+                    hard += 1;
+            }
+            return { level: 1, hardCorrectionCount: hard, requirementChangeCount: req };
+        }
+        // Level 2: 按 summary 关键词推断
+        let hard2 = 0;
+        let req2 = 0;
+        for (const entry of inputs) {
+            const summary = String(entry['summary'] || '').toLowerCase();
+            if (!summary)
+                continue;
+            if (FALLBACK_REQUIREMENT_KEYWORDS.some((k) => summary.includes(k.toLowerCase())))
+                req2 += 1;
+            else if (FALLBACK_CORRECTION_KEYWORDS.some((k) => summary.includes(k.toLowerCase())))
+                hard2 += 1;
+        }
+        return { level: 2, hardCorrectionCount: hard2, requirementChangeCount: req2 };
+    }
+    catch {
+        return null;
+    }
+}
 export async function collectKnowledgeHook(options) {
     let stdinData = {};
     try {
@@ -61,6 +109,8 @@ export async function runCollectKnowledge(filePath) {
     const cwd = process.cwd();
     const knowledgeDir = path.join(cwd, 'zhuanspec', 'knowledge');
     const hasKnowledge = await FileSystemUtils.directoryExists(knowledgeDir);
+    // 读纠偏统计（三级 fallback，读失败不阻断主流程）
+    const stats = await readCorrectionStats(cwd, changeId);
     const knowledgeRef = hasKnowledge
         ? '参考 `zhuanspec/knowledge/` 下已有文件的格式（统一 Front Matter + 三类分目录）'
         : '将写入 `zhuanspec/knowledge/troubleshooting/`、`best-practices/` 或 `implicit-conventions/` 对应目录（仅此三类）';
@@ -84,9 +134,25 @@ export async function runCollectKnowledge(filePath) {
             '⚠️ **去重要求**：保存前先读取 `zhuanspec/knowledge/` 下已有文件，',
             '若已有同类记录，跳过或追加到已有文件，不要重复新建。',
         ];
+    // 纠偏累计提示（基于 user_inputs.json）
+    //
+    // 阈值选择的启发式意图：
+    //   - hardCorrectionCount >= 2：一次纠偏不提示避免打扰，两次及以上视为"稳定坑"，优先沉淀
+    //   - requirementChangeCount >= 1：需求变更对设计决策影响通常较大，出现一次即提示
+    // 本处仅做"是否优先沉淀"的强度提示，具体三类目录分类一律交给 @skill:zhuanspec:knowledge 的分类决策树，不在本 hook 做分类预判。
+    const correctionHints = [];
+    if (stats && stats.level <= 2) {
+        if (stats.hardCorrectionCount >= 2) {
+            correctionHints.push(`⚠️ 本次 apply 已累计 ${stats.hardCorrectionCount} 次纠偏（数据源 Level ${stats.level}），若本次改动是对其中某条纠偏的解决，**请优先沉淀**（具体分类交由 @skill:zhuanspec:knowledge 决定）。`);
+        }
+        if (stats.requirementChangeCount >= 1) {
+            correctionHints.push(`⚠️ 本次 apply 涉及 ${stats.requirementChangeCount} 次需求变更，若本次改动属于其中的设计决策负载，**建议优先沉淀为项目知识**（具体分类交由 @skill:zhuanspec:knowledge 决定）。`);
+        }
+    }
     const additionalContext = [
         `💡 **知识沉淀提示**（针对刚才对 \`${filePath || '该文件'}\` 的改动）`,
         '',
+        ...(correctionHints.length > 0 ? [...correctionHints, ''] : []),
         ...phaseGuide,
         '',
         '询问方式：',

package/dist/core/hooks/deviation-check.d.ts

@@ -15,7 +15,7 @@ interface DeviationCheckOptions {
     json?: boolean;
     file?: string;
     tool?: string;
-    trigger?: 'pre-tool' | 'post-prompt' | 'resume';
+    trigger?: 'pre-tool' | 'resume';
     prompt?: string;
 }
 declare const PITFALL_KEYWORDS: string[];
@@ -24,6 +24,14 @@ declare const IMPLICIT_CONVENTION_KEYWORDS: string[];
 declare const USER_CORRECTION_KEYWORDS: string[];
 declare const REQUIREMENT_CHANGE_KEYWORDS: string[];
 export declare function deviationCheckHook(options: DeviationCheckOptions): Promise<void>;
+/**
+ * 识别 Codex CLI/App 由 Ambient Suggestions 等后台特性发出的系统内部 prompt。
+ * 这类 prompt 并非用户真实输入，不应触发纠偏/需求变更/范围检查。
+ *
+ * 参考：openai/codex#18541 —— Ambient Suggestions 会调用 UserPromptSubmit 钩子
+ * 但不调用对应的 Stop 钩子，且目前无法在项目级关闭。
+ */
+export declare function isCodexInternalPrompt(prompt: string): boolean;
 /**
  * 从提案中提取类名 / 标识符等符号，用于 L2 符号级匹配。
  * 识别规则：
@@ -33,5 +41,22 @@ export declare function deviationCheckHook(options: DeviationCheckOptions): Prom
  *  - 排除全小写且无下划线的短词（避免与英文动词擞车）
  */
 declare function parseEstimatedSymbols(proposalPath: string): Promise<string[]>;
+export declare function extractProposalSummary(content: string, maxLength: number): string;
+/**
+ * 构造纠偏四选一上下文（注入给主 agent）
+ * 要求主 agent：
+ *  1. 停止任何 Edit/Write
+ *  2. 用 askUserQuestion 让用户四选一
+ *  3. 按选择走对应路径
+ *  4. 路径完成后运行 resolve-correction 清理标记
+ */
+export declare function buildCorrectionOptionsContext(proposalSummary: string, changeId: string): string;
+/**
+ * 构造需求变更（T2）硬拦截的上下文。
+ * 与 buildCorrectionOptionsContext 的区别：
+ *  - 仅提供 A / D 两个选项（需求变更必然要先改 Spec，无 Bug 豁免路径）
+ *  - 文案强调“新增/变更功能范围”而非“AI 做错”
+ */
+export declare function buildRequirementChangeContext(proposalSummary: string, changeId: string): string;
 export { PITFALL_KEYWORDS, USER_CORRECTION_KEYWORDS, BEST_PRACTICE_KEYWORDS, IMPLICIT_CONVENTION_KEYWORDS, REQUIREMENT_CHANGE_KEYWORDS, parseEstimatedSymbols };
 //# sourceMappingURL=deviation-check.d.ts.map