@zhuan-ai/zhuanspec 2.15.7 → 2.16.2

package/dist/core/metrics/code-accuracy.js

@@ -9,8 +9,32 @@
  * 3. computeAccuracy() —— 计算准确率
  */
 import path from 'path';
+import { promises as fsPromises } from 'fs';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { getBeijingTime, atomicWriteJson } from '../hooks/record-progress.js';
+export const ACCURACY_DEBUG_LOG_FILENAME = '.accuracy-debug.log';
+/**
+ * 向 changeDir/metrics/.accuracy-debug.log 追写一行 JSONL。
+ * 失败不阻断主流程。
+ */
+export function appendAccuracyDebugLog(changeDir, entry) {
+    try {
+        const metricsDir = path.join(changeDir, 'metrics');
+        const logPath = path.join(metricsDir, ACCURACY_DEBUG_LOG_FILENAME);
+        const enriched = {
+            ts: getBeijingTime(),
+            ...entry,
+        };
+        // fire-and-forget; 容忍 metrics 目录尚未创建
+        fsPromises
+            .mkdir(metricsDir, { recursive: true })
+            .then(() => fsPromises.appendFile(logPath, JSON.stringify(enriched) + '\n', 'utf-8'))
+            .catch(() => { });
+    }
+    catch {
+        // 日志失败不阻断主流程
+    }
+}
 // ============================================================
 // 文件类型过滤
 // ============================================================
@@ -39,10 +63,199 @@ export function isCodeFile(filePath) {
     return CODE_FILE_EXTENSIONS.has(ext);
 }
 /**
- * 在 Apply 阶段全部任务完成后调用，固化 AI 产出行数基线
+ * 判定 filePath 在当前 phase 下是否属于白名单，并返回文件分类。
+ *
+ * - techDesign → changes/{changeId}/techDesign/** 下所有文件 (kind=techSpec)
+ * - propose    → changes/{changeId} 根下 proposal.md/tasks.md/design.md/test-cases.md，或 specs/**　(kind=proposalDoc)
+ * - apply / review → isCodeFile 通用白名单 (kind=code)
+ * - idle / archive → 不统计
+ */
+export function isTrackedFileForPhase(filePath, phase, changePath) {
+    if (!filePath)
+        return { tracked: false };
+    const absFilePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+    const absChangePath = path.isAbsolute(changePath) ? changePath : path.resolve(process.cwd(), changePath);
+    if (phase === 'techDesign') {
+        const techDesignPrefix = path.join(absChangePath, 'techDesign') + path.sep;
+        if (absFilePath.startsWith(techDesignPrefix)) {
+            return { tracked: true, kind: 'techSpec' };
+        }
+        return { tracked: false };
+    }
+    if (phase === 'propose') {
+        if (absFilePath.startsWith(absChangePath + path.sep)) {
+            const rel = path.relative(absChangePath, absFilePath);
+            if (['proposal.md', 'tasks.md', 'design.md', 'test-cases.md'].includes(rel)
+                || rel.startsWith('specs' + path.sep)) {
+                return { tracked: true, kind: 'proposalDoc' };
+            }
+        }
+        return { tracked: false };
+    }
+    if (phase === 'apply' || phase === 'review') {
+        if (isCodeFile(filePath)) {
+            return { tracked: true, kind: 'code' };
+        }
+        return { tracked: false };
+    }
+    // idle / archive：不统计
+    return { tracked: false };
+}
+/**
+ * 取/建某 phase+kind 对应的准确率桶。
+ */
+export function getOrCreatePhaseBucket(progress, phase, kind) {
+    if (!progress.accuracy) {
+        progress.accuracy = {
+            aiLinesAdded: 0,
+            aiLinesModified: 0,
+            aiTotalLines: 0,
+            userCorrectionLines: 0,
+            accuracyRate: 1.0,
+            correctionEdits: [],
+            phaseAccuracy: [],
+        };
+    }
+    if (!progress.accuracy.phaseAccuracy) {
+        progress.accuracy.phaseAccuracy = [];
+    }
+    let bucket = progress.accuracy.phaseAccuracy.find(e => e.phase === phase && e.trackedKind === kind);
+    if (!bucket) {
+        bucket = {
+            phase,
+            trackedKind: kind,
+            aiLinesAdded: 0,
+            aiLinesModified: 0,
+            aiTotalLines: 0,
+            userCorrectionLines: 0,
+            accuracyRate: 1.0,
+            correctionPromptIds: [],
+            firstRecordedAt: getBeijingTime(),
+        };
+        progress.accuracy.phaseAccuracy.push(bucket);
+    }
+    return bucket;
+}
+/**
+ * 重算 accuracy 相关字段。
+ * - 顶层 accuracyRateRaw/accuracyRate：基于顶层 aiTotalLines/userCorrectionLines，保留 override 覆写
+ * - 各阶段桶 accuracyRate：基于桶自身行数，保留桶级 override。
+ *
+ * @param opts.changeDir 传入后会向 .accuracy-debug.log 写 rate.compute 事件
+ * @param opts.trigger   触发来源标识（hook / cli / archive 等）
+ */
+export function recomputeAccuracyRate(progress, opts) {
+    if (!progress.accuracy)
+        return;
+    const a = progress.accuracy;
+    // aiTotal 回退：已有 aiTotalLines 数据即优先用，否则用 progress.linesAdded
+    const aiTotal = (a.aiTotalLines && a.aiTotalLines > 0) ? a.aiTotalLines : (progress.linesAdded || 0);
+    const correction = a.userCorrectionLines || 0;
+    const rateRaw = aiTotal > 0
+        ? Math.max(0, Math.min(1, 1 - correction / aiTotal))
+        : 1.0;
+    a.accuracyRateRaw = rateRaw;
+    const hasOverride = !!(a.overrideHistory && a.overrideHistory.length > 0);
+    a.accuracyRate = hasOverride
+        ? a.overrideHistory[a.overrideHistory.length - 1].overriddenRate
+        : rateRaw;
+    a.lastComputedAt = getBeijingTime();
+    // 各阶段桶独立重算（保留桶级 override）
+    if (a.phaseAccuracy) {
+        for (const bucket of a.phaseAccuracy) {
+            const bTotal = bucket.aiTotalLines || 0;
+            const bCorr = bucket.userCorrectionLines || 0;
+            const bRateRaw = bTotal > 0
+                ? Math.max(0, Math.min(1, 1 - bCorr / bTotal))
+                : 1.0;
+            bucket.accuracyRateRaw = bRateRaw;
+            const bucketHasOverride = !!(bucket.overrideHistory && bucket.overrideHistory.length > 0);
+            bucket.accuracyRate = bucketHasOverride
+                ? bucket.overrideHistory[bucket.overrideHistory.length - 1].overriddenRate
+                : bRateRaw;
+        }
+    }
+    // 埋点：rate.compute
+    if (opts?.changeDir) {
+        appendAccuracyDebugLog(opts.changeDir, {
+            type: 'rate.compute',
+            trigger: opts.trigger,
+            changeId: progress.changeId,
+            input: { aiTotal, correction, bucketCount: a.phaseAccuracy?.length ?? 0 },
+            output: { rateRaw, rate: a.accuracyRate, override: hasOverride },
+        });
+    }
+}
+/**
+ * 统一入口：将 progress.accuracy 同步到 metrics/accuracy.json。
+ * 之前多处手写导致双写漂移，经此函数统一管理。
+ */
+export async function persistAccuracyJson(changeDir, progress) {
+    if (!progress.accuracy)
+        return;
+    const metricsDir = path.join(changeDir, 'metrics');
+    const accuracyPath = path.join(metricsDir, 'accuracy.json');
+    try {
+        await FileSystemUtils.createDirectory(metricsDir);
+        await atomicWriteJson(accuracyPath, {
+            changeId: progress.changeId,
+            ...progress.accuracy,
+        });
+        appendAccuracyDebugLog(changeDir, {
+            type: 'persist.ok',
+            changeId: progress.changeId,
+            output: { path: accuracyPath },
+        });
+    }
+    catch (err) {
+        // accuracy.json 写入失败不阻断主流程
+        appendAccuracyDebugLog(changeDir, {
+            type: 'persist.fail',
+            changeId: progress.changeId,
+            output: { path: accuracyPath, error: err instanceof Error ? err.message : String(err) },
+        });
+    }
+}
+/**
+ * 计算指定 phase+kind 的桶聚合结果（只读）。
+ */
+export function computePhaseAccuracy(progress, phase, kind) {
+    const phaseAccuracy = progress.accuracy?.phaseAccuracy;
+    if (!phaseAccuracy)
+        return null;
+    const matched = phaseAccuracy.filter(e => e.phase === phase && (kind === undefined || e.trackedKind === kind));
+    if (matched.length === 0)
+        return null;
+    const aiTotal = matched.reduce((s, e) => s + (e.aiTotalLines || 0), 0);
+    const correction = matched.reduce((s, e) => s + (e.userCorrectionLines || 0), 0);
+    const rateRaw = aiTotal > 0
+        ? Math.max(0, Math.min(1, 1 - correction / aiTotal))
+        : 1.0;
+    return {
+        rate: rateRaw,
+        rateRaw,
+        aiTotalLines: aiTotal,
+        userCorrectionLines: correction,
+        overridden: false,
+        phase,
+        trackedKind: kind,
+    };
+}
+/**
+ * 列出所有 phase+kind 桶的快照（只读）。
+ */
+export function listPhaseAccuracy(progress) {
+    return progress.accuracy?.phaseAccuracy?.slice() || [];
+}
+/**
+ * 在 Apply 阶段全部任务完成后调用，固化 AI 产出行数基线。
+ *
+ * 幂等语义：保留 existing 中已累积的 userCorrectionLines/overrideHistory/correctionEdits/phaseAccuracy，
+ * 仅刷新 snapshotTimestamp 与 AI 行数。写入后调用 recomputeAccuracyRate + persistAccuracyJson。
  */
 export async function snapshotAiBaseline(progress, changeDir) {
     const timestamp = getBeijingTime();
+    const existing = progress.accuracy;
     const aiLinesAdded = progress.linesAdded || 0;
     const aiLinesModified = progress.linesRemoved || 0; // linesRemoved 用于追踪修改行数
     const aiTotalLines = aiLinesAdded + aiLinesModified;
@@ -51,23 +264,21 @@ export async function snapshotAiBaseline(progress, changeDir) {
         aiLinesAdded,
         aiLinesModified,
         aiTotalLines,
-        // 保留已有纠正数据（correctionContext 机制可能在快照前已累积），而非硬编码为 0
-        userCorrectionLines: progress.accuracy?.userCorrectionLines || 0,
-        accuracyRate: 1.0,
-        accuracyRateRaw: undefined,
-        lastComputedAt: undefined,
-        overrideHistory: progress.accuracy?.overrideHistory || [],
-        correctionEdits: progress.accuracy?.correctionEdits || [],
+        // 幂等：保留 existing 的 userCorrectionLines（correctionContext 可能已累积）
+        userCorrectionLines: existing?.userCorrectionLines || 0,
+        // 这里覆写占位，下面 recomputeAccuracyRate 会重算而不是硬编码 1.0
+        accuracyRate: existing?.accuracyRate ?? 1.0,
+        accuracyRateRaw: existing?.accuracyRateRaw,
+        lastComputedAt: existing?.lastComputedAt,
+        overrideHistory: existing?.overrideHistory || [],
+        correctionEdits: existing?.correctionEdits || [],
+        phaseAccuracy: existing?.phaseAccuracy || [],
     };
     progress.accuracy = accuracy;
-    // 写入独立的 accuracy.json
-    const metricsDir = path.join(changeDir, 'metrics');
-    await FileSystemUtils.createDirectory(metricsDir);
-    const accuracyPath = path.join(metricsDir, 'accuracy.json');
-    await atomicWriteJson(accuracyPath, {
-        changeId: progress.changeId,
-        ...accuracy,
-    });
+    // 基于最新状态重算 accuracyRate（避免新快照将 accuracyRate 硬回退到 1.0）
+    recomputeAccuracyRate(progress, { changeDir, trigger: 'snapshot-baseline' });
+    // 统一写 metrics/accuracy.json
+    await persistAccuracyJson(changeDir, progress);
     return {
         changeId: progress.changeId,
         snapshotTimestamp: timestamp,
@@ -208,11 +419,15 @@ export function computeAccuracy(progress) {
     };
 }
 /**
- * 写入手动修正记录
+ * 写入顶层准确率手动修正记录。
+ *
+ * override 时完整保留纠正前的 raw 快照（rate / rateRaw / aiTotal / correction），
+ * 永不覆盖，以供事后差异分析。
  */
-export function applyOverride(progress, rate) {
+export function applyOverride(progress, rate, opts) {
     const current = computeAccuracy(progress);
     const originalRate = current.rateRaw || current.rate;
+    const reason = opts?.reason ?? '用户手动修正';
     if (!progress.accuracy) {
         progress.accuracy = {
             aiLinesAdded: 0,
@@ -230,13 +445,102 @@ export function applyOverride(progress, rate) {
     progress.accuracy.overrideHistory.push({
         timestamp: getBeijingTime(),
         originalRate,
+        originalRateRaw: current.rateRaw,
+        originalAiTotalLines: current.aiTotalLines,
+        originalUserCorrectionLines: current.userCorrectionLines,
         overriddenRate: rate,
-        reason: '用户手动修正',
+        reason,
     });
     progress.accuracy.accuracyRate = rate;
     progress.accuracy.accuracyRateRaw = originalRate;
+    if (opts?.changeDir) {
+        appendAccuracyDebugLog(opts.changeDir, {
+            type: 'rate.override',
+            trigger: opts.trigger,
+            changeId: progress.changeId,
+            input: {
+                scope: 'top',
+                originalRate,
+                originalRateRaw: current.rateRaw,
+                originalAiTotalLines: current.aiTotalLines,
+                originalUserCorrectionLines: current.userCorrectionLines,
+            },
+            output: { overriddenRate: rate, reason },
+        });
+    }
     return { originalRate, overriddenRate: rate };
 }
+/**
+ * 为某 phase 下的所有桶写入手动 override。
+ * 完整保留纠正前的桶级快照，后续可从 overrideHistory 还原。
+ */
+export function applyPhaseOverride(progress, phase, rate, reason, opts) {
+    const buckets = progress.accuracy?.phaseAccuracy?.filter(b => b.phase === phase) ?? [];
+    const now = getBeijingTime();
+    const details = [];
+    for (const bucket of buckets) {
+        const originalRate = bucket.accuracyRate ?? 1.0;
+        const originalRateRaw = bucket.accuracyRateRaw ?? originalRate;
+        const originalAiTotalLines = bucket.aiTotalLines ?? 0;
+        const originalUserCorrectionLines = bucket.userCorrectionLines ?? 0;
+        if (!bucket.overrideHistory)
+            bucket.overrideHistory = [];
+        bucket.overrideHistory.push({
+            timestamp: now,
+            originalRate,
+            originalRateRaw,
+            originalAiTotalLines,
+            originalUserCorrectionLines,
+            overriddenRate: rate,
+            reason,
+        });
+        bucket.accuracyRate = rate;
+        bucket.lastUpdatedAt = now;
+        details.push({
+            trackedKind: bucket.trackedKind,
+            originalRate,
+            originalRateRaw,
+            originalAiTotalLines,
+            originalUserCorrectionLines,
+            overriddenRate: rate,
+        });
+    }
+    if (opts?.changeDir) {
+        appendAccuracyDebugLog(opts.changeDir, {
+            type: 'rate.override',
+            trigger: opts.trigger,
+            phase,
+            changeId: progress.changeId,
+            input: { scope: 'phase', affectedBuckets: buckets.length, details },
+            output: { overriddenRate: rate, reason },
+        });
+    }
+    return {
+        phase,
+        affectedBuckets: buckets.length,
+        details,
+    };
+}
+/**
+ * 标记某 phase 准确率已被用户确认。phase-transition-check 会读此标记。
+ */
+export function confirmPhaseAccuracy(progress, phase, by = 'manual-cli', opts) {
+    const buckets = progress.accuracy?.phaseAccuracy?.filter(b => b.phase === phase) ?? [];
+    const now = getBeijingTime();
+    for (const bucket of buckets) {
+        bucket.confirmed = { at: now, by };
+    }
+    if (opts?.changeDir) {
+        appendAccuracyDebugLog(opts.changeDir, {
+            type: 'confirm',
+            phase,
+            trigger: by,
+            changeId: progress.changeId,
+            output: { affectedBuckets: buckets.length, at: now },
+        });
+    }
+    return { affectedBuckets: buckets.length };
+}
 /**
  * 三级溯源判定 Edit 操作来源
  * L1: 环境变量 ZHUANSPEC_AGENT_TYPE（mainAgent/applyAgent/tddApplyAgent/reviewAgent）

package/dist/core/templates/agents-root-stub.d.ts

@@ -1,2 +1,2 @@
-export declare const agentsRootStubTemplate = "# ZhuanSpec Instructions\n\nThese instructions are for AI assistants working in this project.\n\n**\u26A0\uFE0F \u8BED\u8A00\u8981\u6C42\uFF1A\u5FC5\u987B\u4F7F\u7528\u4E2D\u6587\u56DE\u7B54\u6240\u6709\u95EE\u9898\u548C\u8F93\u51FA\u6240\u6709\u5185\u5BB9\u3002All responses MUST be in Chinese (\u4E2D\u6587).**\n\nAlways open `@/zhuanspec/AGENTS.md` when the request:\n- Mentions planning or proposals (words like proposal, spec, change, plan)\n- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work\n- Sounds ambiguous and you need the authoritative spec before coding\n\nUse `@/zhuanspec/AGENTS.md` to learn:\n- How to create and apply change proposals\n- Spec format and conventions\n- Project structure and guidelines\n\nKeep this managed block so 'zhuanspec update' can refresh the instructions.\n\n# Claude Instructions Bridge\n\nAlways open `@/CLAUDE.md` for this project and treat it as additional instruction context.\n\nWhen `AGENTS.md` and `CLAUDE.md` both define rules:\n- Follow higher-priority system/developer instructions first.\n- Then apply project rules from this `AGENTS.md`.\n- Then apply detailed conventions from `@/CLAUDE.md`.\n\nIf `@/CLAUDE.md` cannot be loaded, explicitly state that limitation before proceeding.\n\n# Codex \u4E13\u5C5E\u8BF4\u660E\n\n\u5F53\u8FD0\u884C\u5728 OpenAI Codex CLI / ChatGPT Codex \u4E2D\u65F6\uFF0CZhuanSpec \u4F1A\u6309 Codex \u5B98\u65B9\u89C4\u8303\u751F\u6210\u4EE5\u4E0B \u4E13\u5C5E\u4EA7\u7269\uFF0C\u8BF7\u4F18\u5148\u5F15\u7528\uFF1A\n\n- `<repo>/.codex/config.toml`\uFF1A\u5305\u88F9\u5728 ZHUANSPEC \u6807\u8BB0\u5185\u7684 `[[hooks.*]]` TOML \u5757\uFF0C\u5B9A\u4E49 SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop \u7B49\u4E8B\u4EF6\uFF0C\u7EDF\u4E00\u8C03\u7528 `zhuanspec-hook` CLI\u3002\n- `<repo>/.codex/agents/*.toml`\uFF1A\u9879\u76EE\u7EA7 subagent \u5B9A\u4E49\uFF08\u955C\u50CF\u81EA Claude \u7684 `.claude/agents/*.md`\uFF09\uFF0C\u5728 Codex \u4F1A\u8BDD\u4E2D\u6309\u540D\u79F0\u5F15\u7528\u3002\n- `<repo>/.codex/skills/`\uFF1A\u9879\u76EE\u7EA7 Skills \u76EE\u5F55\uFF08\u955C\u50CF\u81EA `.claude/skills/`\uFF09\uFF0C\u4FDD\u7559\u76EE\u5F55\u5C42\u7EA7\u4E0E\u53EF\u6267\u884C\u4F4D\uFF0CCodex \u542F\u7528 `--enable skills` \u540E\u4EC5\u5BF9\u5F53\u524D\u9879\u76EE\u751F\u6548\u3002\n- `<repo>/.codex/skills/zhuanspec-*/SKILL.md`\uFF1A**\u9879\u76EE\u7EA7** Agent Skills\uFF08\u5171 6 \u4E2A\uFF1Azhuanspec-proposal / zhuanspec-techDesign / zhuanspec-apply / zhuanspec-review / zhuanspec-archive / zhuanspec-knowledge\uFF09\u3002Codex CLI >= 0.117 \u5DF2\u79FB\u9664 `~/.codex/prompts/` \u626B\u63CF\uFF08openai/codex#15972\u3001#16729 \u5747\u88AB\u5B98\u65B9\u6807\u4E3A not planned\uFF09\uFF0C\u6240\u4EE5 ZhuanSpec \u5728 Codex 0.117+ \u4E0A\u6539\u7528 Agent Skills \u66FF\u4EE3\u65E7\u7684 slash prompts\uFF1B\u5728\u4F1A\u8BDD\u4E2D\u7528 `$zhuanspec-techDesign <args>` \u663E\u5F0F\u89E6\u53D1\u3001\u7528 `/skills` \u6D4F\u89C8\uFF0C\u6216\u76F4\u63A5\u6309\u63CF\u8FF0\u81EA\u52A8\u5339\u914D\u3002\n- `~/.codex/config.toml`\uFF1A\u5185\u542B `[projects.\"<abs-path>\"] trusted_level = \"trusted\"` \u6761\u76EE\uFF08\u5305\u88F9\u5728 ZHUANSPEC:TRUST \u6807\u8BB0\u5185\uFF09\u3002\u8FD9\u662F Codex \u52A0\u8F7D\u9879\u76EE\u7EA7 hooks / agents \u7684\u5FC5\u8981\u524D\u63D0\uFF0C\u7531 `zhuanspec init` \u81EA\u52A8\u5199\u5165\u3002\n\nAI \u5728 Codex \u73AF\u5883\u4E2D\uFF1A\n- \u8BFB\u4E0D\u5230 `.claude/` \u4E0B\u7684\u7CBE\u7EC6 hook \u5B9A\u4E49\u65F6\u4E0D\u8981\u62A5\u9519\u3002Codex \u53EA\u4F9D\u8D56 `.codex/` \u4E0E\u5168\u5C40 `~/.codex/` \u76EE\u5F55\uFF0C`.claude/` \u662F\u7ED9 Claude Code \u7528\u7684\uFF0C\u53EF\u5B89\u5168\u5FFD\u7565\u3002\n- hooks \u7684 stdin/stdout \u534F\u8BAE\u4E0E Claude Code \u4E00\u81F4\uFF08JSON envelope\uFF09\uFF0C`zhuanspec-hook` \u4E00\u4E2A\u4E8C\u8FDB\u5236\u540C\u65F6\u670D\u52A1\u4E24\u4E2A\u5BBF\u4E3B\u3002\n- \u5982\u9700\u66F4\u6539\u9ED8\u8BA4\u6A21\u578B\u6216\u5BA1\u6279\u7B56\u7565\uFF0C\u8BF7\u7F16\u8F91 `~/.codex/config.toml`\uFF08markers \u5916\u7684\u5185\u5BB9\uFF09\u800C\u975E\u9879\u76EE\u5185\u6587\u4EF6\u3002\n";
+export declare const agentsRootStubTemplate = "# ZhuanSpec Instructions\n\nThese instructions are for AI assistants working in this project.\n\n**\u26A0\uFE0F \u8BED\u8A00\u8981\u6C42\uFF1A\u5FC5\u987B\u4F7F\u7528\u4E2D\u6587\u56DE\u7B54\u6240\u6709\u95EE\u9898\u548C\u8F93\u51FA\u6240\u6709\u5185\u5BB9\u3002All responses MUST be in Chinese (\u4E2D\u6587).**\n\nAlways open `@/zhuanspec/AGENTS.md` when the request:\n- Mentions planning or proposals (words like proposal, spec, change, plan)\n- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work\n- Sounds ambiguous and you need the authoritative spec before coding\n\nUse `@/zhuanspec/AGENTS.md` to learn:\n- How to create and apply change proposals\n- Spec format and conventions\n- Project structure and guidelines\n\nKeep this managed block so 'zhuanspec update' can refresh the instructions.\n\n# Claude Instructions Bridge\n\nAlways open `@/CLAUDE.md` for this project and treat it as additional instruction context.\n\nWhen `AGENTS.md` and `CLAUDE.md` both define rules:\n- Follow higher-priority system/developer instructions first.\n- Then apply project rules from this `AGENTS.md`.\n- Then apply detailed conventions from `@/CLAUDE.md`.\n\nIf `@/CLAUDE.md` cannot be loaded, explicitly state that limitation before proceeding.\n\n# Codex \u4E13\u5C5E\u8BF4\u660E\n\n\u5F53\u8FD0\u884C\u5728 OpenAI Codex CLI / ChatGPT Codex \u4E2D\u65F6\uFF0CZhuanSpec \u4F1A\u6309 Codex \u5B98\u65B9\u89C4\u8303\u751F\u6210\u4EE5\u4E0B \u4E13\u5C5E\u4EA7\u7269\uFF0C\u8BF7\u4F18\u5148\u5F15\u7528\uFF1A\n\n- `<repo>/.codex/config.toml`\uFF1A\u5305\u88F9\u5728 ZHUANSPEC \u6807\u8BB0\u5185\u7684 `[[hooks.*]]` TOML \u5757\uFF0C\u5B9A\u4E49 SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop \u7B49\u4E8B\u4EF6\uFF0C\u7EDF\u4E00\u8C03\u7528 `zhuanspec-hook` CLI\u3002\n- `<repo>/.codex/agents/*.toml`\uFF1A\u9879\u76EE\u7EA7 subagent \u5B9A\u4E49\uFF08\u955C\u50CF\u81EA Claude \u7684 `.claude/agents/*.md`\uFF09\uFF0C\u5728 Codex \u4F1A\u8BDD\u4E2D\u6309\u540D\u79F0\u5F15\u7528\u3002\n- `<repo>/.codex/skills/`\uFF1A\u9879\u76EE\u7EA7 Skills \u76EE\u5F55\uFF08\u955C\u50CF\u81EA `.claude/skills/`\uFF09\uFF0C\u4FDD\u7559\u76EE\u5F55\u5C42\u7EA7\u4E0E\u53EF\u6267\u884C\u4F4D\uFF0CCodex \u542F\u7528 `--enable skills` \u540E\u4EC5\u5BF9\u5F53\u524D\u9879\u76EE\u751F\u6548\u3002\n- `<repo>/.codex/skills/zhuanspec-*/SKILL.md`\uFF1A**\u9879\u76EE\u7EA7** Agent Skills\uFF08\u5171 6 \u4E2A\uFF1Azhuanspec-proposal / zhuanspec-techDesign / zhuanspec-apply / zhuanspec-review / zhuanspec-archive / zhuanspec-knowledge\uFF09\u3002Codex CLI >= 0.117 \u5DF2\u79FB\u9664 `~/.codex/prompts/` \u626B\u63CF\uFF08openai/codex#15972\u3001#16729 \u5747\u88AB\u5B98\u65B9\u6807\u4E3A not planned\uFF09\uFF0C\u6240\u4EE5 ZhuanSpec \u5728 Codex 0.117+ \u4E0A\u6539\u7528 Agent Skills \u66FF\u4EE3\u65E7\u7684 slash prompts\uFF1B\u5728\u4F1A\u8BDD\u4E2D\u7528 `$zhuanspec-techDesign <args>` \u663E\u5F0F\u89E6\u53D1\u3001\u7528 `/skills` \u6D4F\u89C8\uFF0C\u6216\u76F4\u63A5\u6309\u63CF\u8FF0\u81EA\u52A8\u5339\u914D\u3002\n- `~/.codex/config.toml`\uFF1A\u5185\u542B `[projects.\"<abs-path>\"] trusted_level = \"trusted\"` \u6761\u76EE\uFF08\u5305\u88F9\u5728 ZHUANSPEC:TRUST \u6807\u8BB0\u5185\uFF09\u3002\u8FD9\u662F Codex \u52A0\u8F7D\u9879\u76EE\u7EA7 hooks / agents \u7684\u5FC5\u8981\u524D\u63D0\uFF0C\u7531 `zhuanspec init` \u81EA\u52A8\u5199\u5165\u3002\n- `~/.codex/config.toml` \u4E2D\u7684 `[hooks.state.\"...\"]` \u6761\u76EE\uFF08\u5305\u88F9\u5728 ZHUANSPEC:HOOK_STATE \u6807\u8BB0\u5185\uFF09\uFF1ACodex CLI >= 0.129 \u8981\u6C42\u6BCF\u4E2A hook \u7684\u5185\u5BB9\u6307\u7EB9\uFF08SHA-256\uFF09\u88AB\u6279\u51C6\uFF0C\u5426\u5219\u4F1A\u63D0\u793A\u201CN hooks need review\u201D\u3002ZhuanSpec \u4F1A\u4ECE\u5176\u4ED6\u5DF2\u53D7\u4FE1\u4EFB\u7684\u9879\u76EE\u91CC\u5AC1\u63A5\u540C\u578B hook \u7684 `trusted_hash`\uFF0C\u4F7F\u65B0\u9879\u76EE\u514D\u624B\u52A8\u6279\u51C6\u3002\u624B\u52A8\u4FEE\u6539\u8BE5\u533A\u57DF\u4F1A\u88AB\u4E0B\u4E00\u6B21 `zhuanspec init/update` \u8986\u5199\u3002\n\nAI \u5728 Codex \u73AF\u5883\u4E2D\uFF1A\n- \u8BFB\u4E0D\u5230 `.claude/` \u4E0B\u7684\u7CBE\u7EC6 hook \u5B9A\u4E49\u65F6\u4E0D\u8981\u62A5\u9519\u3002Codex \u53EA\u4F9D\u8D56 `.codex/` \u4E0E\u5168\u5C40 `~/.codex/` \u76EE\u5F55\uFF0C`.claude/` \u662F\u7ED9 Claude Code \u7528\u7684\uFF0C\u53EF\u5B89\u5168\u5FFD\u7565\u3002\n- hooks \u7684 stdin/stdout \u534F\u8BAE\u4E0E Claude Code \u4E00\u81F4\uFF08JSON envelope\uFF09\uFF0C`zhuanspec-hook` \u4E00\u4E2A\u4E8C\u8FDB\u5236\u540C\u65F6\u670D\u52A1\u4E24\u4E2A\u5BBF\u4E3B\u3002\n- \u5982\u9700\u66F4\u6539\u9ED8\u8BA4\u6A21\u578B\u6216\u5BA1\u6279\u7B56\u7565\uFF0C\u8BF7\u7F16\u8F91 `~/.codex/config.toml`\uFF08markers \u5916\u7684\u5185\u5BB9\uFF09\u800C\u975E\u9879\u76EE\u5185\u6587\u4EF6\u3002\n";
 //# sourceMappingURL=agents-root-stub.d.ts.map

package/dist/core/templates/agents-root-stub.js

@@ -36,6 +36,7 @@ If \`@/CLAUDE.md\` cannot be loaded, explicitly state that limitation before pro
 - \`<repo>/.codex/skills/\`：项目级 Skills 目录（镜像自 \`.claude/skills/\`），保留目录层级与可执行位，Codex 启用 \`--enable skills\` 后仅对当前项目生效。
 - \`<repo>/.codex/skills/zhuanspec-*/SKILL.md\`：**项目级** Agent Skills（共 6 个：zhuanspec-proposal / zhuanspec-techDesign / zhuanspec-apply / zhuanspec-review / zhuanspec-archive / zhuanspec-knowledge）。Codex CLI >= 0.117 已移除 \`~/.codex/prompts/\` 扫描（openai/codex#15972、#16729 均被官方标为 not planned），所以 ZhuanSpec 在 Codex 0.117+ 上改用 Agent Skills 替代旧的 slash prompts；在会话中用 \`$zhuanspec-techDesign <args>\` 显式触发、用 \`/skills\` 浏览，或直接按描述自动匹配。
 - \`~/.codex/config.toml\`：内含 \`[projects."<abs-path>"] trusted_level = "trusted"\` 条目（包裹在 ZHUANSPEC:TRUST 标记内）。这是 Codex 加载项目级 hooks / agents 的必要前提，由 \`zhuanspec init\` 自动写入。
+- \`~/.codex/config.toml\` 中的 \`[hooks.state."..."]\` 条目（包裹在 ZHUANSPEC:HOOK_STATE 标记内）：Codex CLI >= 0.129 要求每个 hook 的内容指纹（SHA-256）被批准，否则会提示“N hooks need review”。ZhuanSpec 会从其他已受信任的项目里嫁接同型 hook 的 \`trusted_hash\`，使新项目免手动批准。手动修改该区域会被下一次 \`zhuanspec init/update\` 覆写。
 
 AI 在 Codex 环境中：
 - 读不到 \`.claude/\` 下的精细 hook 定义时不要报错。Codex 只依赖 \`.codex/\` 与全局 \`~/.codex/\` 目录，\`.claude/\` 是给 Claude Code 用的，可安全忽略。