@zhuan-ai/zhuanspec 2.15.7 → 2.16.2

package/dist/core/corrections/select-candidates.js

@@ -0,0 +1,357 @@
+/**
+ * Pending corrections candidate selection.
+ *
+ * 责任：把 `zhuanspec/changes/<id>/metrics/user_inputs.json` 里的纠偏 prompt 加工成
+ * "可读、去毛刺、去重、带建议分类" 的候选清单，给 review 阶段的踩坑沉淀决策使用。
+ *
+ * 不写文件、不改 progress.json，只做"读 + 计算 + 返回结构"。
+ */
+import path from 'path';
+import { promises as fs } from 'fs';
+import { USER_CORRECTION_KEYWORDS, REQUIREMENT_CHANGE_KEYWORDS, PITFALL_KEYWORDS, BEST_PRACTICE_KEYWORDS, IMPLICIT_CONVENTION_KEYWORDS, } from '../hooks/deviation-check.js';
+// ---------- Internals ----------
+/**
+ * 规范化字符串——用于过滤与去重的"语义指纹"。
+ * 1) 转小写（英文）
+ * 2) 把中英文标点 / 空白合并成单空格
+ * 3) trim
+ * 注意：保留中文字符本身（不做拼音/分词），只去标点和空白。
+ */
+function normalize(text) {
+    return text
+        .toLowerCase()
+        // 中英文标点 + 各类空白统一替换为空格
+        .replace(/[\s\p{P}\p{S}]+/gu, ' ')
+        .trim();
+}
+/** 纯确认/招呼类 prompt，不具备沉淀价值 */
+const TRIVIAL_ACK_SET = new Set([
+    '是', '是的', '好', '好的', '嗯', '嗯嗯', '对', '行', '可以', '确认',
+    '同意', '继续', '没问题', '明白', '了解', '知道了', '收到', '辛苦', '辛苦了',
+    'ok', 'okay', 'k', 'yes', 'y', 'yep', 'yeah', 'sure', 'fine', 'cool',
+    'go', 'go on', 'plan approved', 'continue', 'thanks', 'thx',
+]);
+/** 拟用文件名 slug 长度上限 */
+const SLUG_MAX_LEN = 48;
+function toKebabSlug(text) {
+    // 取规范化后的前若干字 → 把空格转 -，并去掉非字母数字中文
+    const base = normalize(text);
+    // 仅保留字母数字 / 中文 / 空格，再把空格转 -
+    const cleaned = base.replace(/[^a-z0-9\u4e00-\u9fa5\s]/g, '').replace(/\s+/g, '-');
+    return cleaned.slice(0, SLUG_MAX_LEN).replace(/^-+|-+$/g, '') || 'untitled';
+}
+function formatDate(ts) {
+    // user_inputs.timestamp 已经是北京时间字符串 "YYYY-MM-DD HH:mm:ss"
+    if (ts && /^\d{4}-\d{2}-\d{2}/.test(ts))
+        return ts.slice(0, 10).replace(/-/g, '');
+    const now = new Date();
+    const yyyy = now.getFullYear();
+    const mm = String(now.getMonth() + 1).padStart(2, '0');
+    const dd = String(now.getDate()).padStart(2, '0');
+    return `${yyyy}${mm}${dd}`;
+}
+function buildPreview(text, maxLen = 200) {
+    const oneLine = text.replace(/\s+/g, ' ').trim();
+    if (oneLine.length <= maxLen)
+        return oneLine;
+    return oneLine.slice(0, maxLen - 1) + '…';
+}
+function detectKeywords(text) {
+    const lower = text.toLowerCase();
+    const hits = new Set();
+    for (const kw of USER_CORRECTION_KEYWORDS) {
+        if (lower.includes(kw.toLowerCase()))
+            hits.add(kw);
+    }
+    if (hits.size > 0) {
+        return { hits: Array.from(hits).slice(0, 6), isRequirementChange: false };
+    }
+    const reqHits = new Set();
+    for (const kw of REQUIREMENT_CHANGE_KEYWORDS) {
+        if (lower.includes(kw.toLowerCase()))
+            reqHits.add(kw);
+    }
+    if (reqHits.size > 0) {
+        return { hits: Array.from(reqHits).slice(0, 6), isRequirementChange: true };
+    }
+    return { hits: [], isRequirementChange: false };
+}
+const BEST_PRACTICE_HINTS = [
+    '后续', '之后都', '都要这么', '必须', '一律', '统一', '永远', '今后',
+    'always', 'going forward', 'from now on',
+];
+const TROUBLESHOOTING_HINTS = ['错了', '不对', '有问题', 'bug', 'wrong', 'incorrect'];
+function classifyCandidate(text, hits, isReqChange) {
+    const lower = text.toLowerCase();
+    // 1) 命中显式 PITFALL → troubleshooting
+    if (PITFALL_KEYWORDS.some((k) => lower.includes(k.toLowerCase())))
+        return 'troubleshooting';
+    // 2) 显式纠错动词 → troubleshooting（覆盖大多数纠偏 prompt）
+    if (TROUBLESHOOTING_HINTS.some((k) => lower.includes(k.toLowerCase())))
+        return 'troubleshooting';
+    // 3) 显式约定关键词
+    if (IMPLICIT_CONVENTION_KEYWORDS.some((k) => lower.includes(k.toLowerCase())))
+        return 'implicit-conventions';
+    // 4) 显式最佳实践 / 长期生效 hint
+    if (BEST_PRACTICE_KEYWORDS.some((k) => lower.includes(k.toLowerCase())))
+        return 'best-practices';
+    if (BEST_PRACTICE_HINTS.some((k) => lower.includes(k.toLowerCase())))
+        return 'best-practices';
+    // 5) 需求变更类 → 暂归 best-practices（"决策类输出归并到 best-practices/"）
+    if (isReqChange)
+        return 'best-practices';
+    // 6) 命中纠偏关键词但没显式陷阱词 → 默认踩坑
+    if (hits.length > 0)
+        return 'troubleshooting';
+    return 'troubleshooting';
+}
+function isTrivialAck(text) {
+    const norm = normalize(text);
+    if (norm.length === 0)
+        return true;
+    if (TRIVIAL_ACK_SET.has(norm))
+        return true;
+    // 仅由若干个字符 + 标点构成的极短 prompt（如 "好。"、"!!" 已被 normalize 干掉标点）
+    if (norm.length <= 2)
+        return true;
+    return false;
+}
+/**
+ * 从 user_inputs.json 抽取候选 raw entries。
+ * - Level 1: correctionSignal.kind === 'hard' && postBaseline === true
+ * - Level 2: 条目缺 correctionSignal → 用 summary 关键词扫描兜底
+ */
+async function loadRawEntries(cwd, changeId) {
+    const userInputsPath = path.join(cwd, 'zhuanspec', 'changes', changeId, 'metrics', 'user_inputs.json');
+    let raw;
+    try {
+        raw = await fs.readFile(userInputsPath, 'utf8');
+    }
+    catch {
+        return { entries: [], level: null, notice: `user_inputs.json 不存在或不可读：${userInputsPath}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { entries: [], level: null, notice: 'user_inputs.json 解析失败（JSON 损坏），请人工检查。' };
+    }
+    const inputs = Array.isArray(parsed.inputs) ? parsed.inputs : [];
+    if (inputs.length === 0)
+        return { entries: [], level: null };
+    const hasSignal = inputs.some((i) => i && typeof i === 'object' && 'correctionSignal' in i);
+    const level = hasSignal ? 1 : 2;
+    const out = [];
+    for (const entry of inputs) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const inputId = entry['inputId'] || undefined;
+        const timestamp = entry['timestamp'] || undefined;
+        const phase = entry['phase'] || undefined;
+        const fullPrompt = entry['fullPrompt'] || '';
+        const summary = entry['summary'] || '';
+        const text = (fullPrompt || summary || '').toString();
+        if (level === 1) {
+            const sig = entry['correctionSignal'];
+            const postBaseline = entry['postBaseline'] === true;
+            if (!sig || sig.kind !== 'hard' || !postBaseline)
+                continue;
+            out.push({
+                inputId,
+                timestamp,
+                phase,
+                text,
+                fromLevel: 1,
+                signalKeywords: Array.isArray(sig.matchedKeywords) ? sig.matchedKeywords : [],
+                isRequirementChange: sig.isRequirementChange === true,
+            });
+        }
+        else {
+            // Level 2: 用 summary 推断
+            const lower = (summary || text).toLowerCase();
+            const hitCorrection = USER_CORRECTION_KEYWORDS.some((k) => lower.includes(k.toLowerCase()));
+            const hitReq = REQUIREMENT_CHANGE_KEYWORDS.some((k) => lower.includes(k.toLowerCase()));
+            if (!hitCorrection && !hitReq)
+                continue;
+            out.push({ inputId, timestamp, phase, text, fromLevel: 2, isRequirementChange: hitReq && !hitCorrection });
+        }
+    }
+    return { entries: out, level };
+}
+// ---------- Public API ----------
+/**
+ * 从 change 目录抽取并加工纠偏候选。
+ */
+export async function selectCorrectionCandidates(cwd, changeId) {
+    const { entries, level, notice } = await loadRawEntries(cwd, changeId);
+    const totalRaw = entries.length;
+    const accepted = [];
+    const dropped = [];
+    // 已接受候选的 normalized 文本，用于做"完全相等 / 子串包含"去重
+    const acceptedNormalized = [];
+    for (let i = 0; i < entries.length; i++) {
+        const e = entries[i];
+        const rawIndex = i + 1;
+        const preview = buildPreview(e.text || '');
+        // Step 1: 空内容
+        if (!e.text || e.text.trim().length === 0) {
+            dropped.push({ rawIndex, inputId: e.inputId, timestamp: e.timestamp, reason: 'empty', preview });
+            continue;
+        }
+        // Step 2: trivial 确认
+        if (isTrivialAck(e.text)) {
+            dropped.push({ rawIndex, inputId: e.inputId, timestamp: e.timestamp, reason: 'trivial-acknowledgement', preview });
+            continue;
+        }
+        // Step 3: 关键词命中 + 长度兜底
+        const { hits: detectedHits, isRequirementChange: detectedReq } = detectKeywords(e.text);
+        const matchedKeywords = e.signalKeywords && e.signalKeywords.length > 0 ? e.signalKeywords : detectedHits;
+        const isReqChange = e.isRequirementChange ?? detectedReq;
+        const norm = normalize(e.text);
+        if (norm.length < 6 && matchedKeywords.length === 0) {
+            dropped.push({ rawIndex, inputId: e.inputId, timestamp: e.timestamp, reason: 'too-short-no-keyword', preview });
+            continue;
+        }
+        // Step 4: 去重——完全相等 或 子串包含（短的被吸收）
+        let dupRefIdx;
+        let dupReason;
+        for (const prev of acceptedNormalized) {
+            if (prev.norm === norm) {
+                dupRefIdx = prev.idx;
+                dupReason = 'duplicate-of';
+                break;
+            }
+            // 子串包含：当前是已接受的真子串（且当前更短至少 4 字）
+            if (norm.length >= 4 && prev.norm.includes(norm) && norm.length < prev.norm.length) {
+                dupRefIdx = prev.idx;
+                dupReason = 'subset-of';
+                break;
+            }
+            // 反向：当前比已接受的长，且包含已接受 → 替换语义；保守处理：仅在长包含短时把短的标记为 subset。
+            // 不修改已接受集，避免编号漂移。
+        }
+        if (dupRefIdx && dupReason) {
+            dropped.push({
+                rawIndex,
+                inputId: e.inputId,
+                timestamp: e.timestamp,
+                reason: dupReason,
+                refIndex: dupRefIdx,
+                preview,
+            });
+            continue;
+        }
+        // Step 5: 收编为有效候选
+        const idx = accepted.length + 1;
+        const suggestedCategory = classifyCandidate(e.text, matchedKeywords, isReqChange);
+        const slug = toKebabSlug(e.text);
+        const suggestedFilename = `${formatDate(e.timestamp)}-${slug}.md`;
+        accepted.push({
+            index: idx,
+            inputId: e.inputId,
+            timestamp: e.timestamp,
+            phase: e.phase,
+            text: e.text,
+            preview,
+            matchedKeywords,
+            isRequirementChange: isReqChange,
+            suggestedCategory,
+            suggestedFilename,
+        });
+        acceptedNormalized.push({ idx, norm });
+    }
+    return { changeId, level, totalRaw, candidates: accepted, dropped, notice };
+}
+/**
+ * 把候选结果渲染成 markdown，用于落到 review/pending-corrections.md。
+ */
+export function renderPendingCorrectionsMarkdown(result) {
+    const { changeId, level, totalRaw, candidates, dropped, notice } = result;
+    const droppedByReason = {
+        trivial: dropped.filter((d) => d.reason === 'trivial-acknowledgement').length,
+        empty: dropped.filter((d) => d.reason === 'empty').length,
+        short: dropped.filter((d) => d.reason === 'too-short-no-keyword').length,
+        duplicate: dropped.filter((d) => d.reason === 'duplicate-of' || d.reason === 'subset-of').length,
+    };
+    const lines = [];
+    lines.push(`# Pending Corrections — ${changeId}`);
+    lines.push('');
+    lines.push(`> 由 \`zhuanspec progress list-corrections\` 生成。review 阶段「踩坑沉淀」请基于此清单做选择性沉淀决策，禁止靠最近 N 条做盲选。`);
+    lines.push('');
+    lines.push(`- **数据源**: ${level === 1 ? 'Level 1 — user_inputs.correctionSignal' : level === 2 ? 'Level 2 — summary 关键词推断' : '无（user_inputs.json 缺失或无候选）'}`);
+    lines.push(`- **原始条目**: ${totalRaw}`);
+    lines.push(`- **有效候选**: ${candidates.length}`);
+    lines.push(`- **已过滤**: ${dropped.length}（trivial=${droppedByReason.trivial}、空=${droppedByReason.empty}、过短=${droppedByReason.short}、去重=${droppedByReason.duplicate}）`);
+    if (notice) {
+        lines.push('');
+        lines.push(`> ⚠️ ${notice}`);
+    }
+    lines.push('');
+    if (candidates.length === 0) {
+        lines.push('## 候选列表');
+        lines.push('');
+        lines.push('（无有效候选，可直接在 review 步骤 0 选 "跳过"。）');
+        lines.push('');
+    }
+    else {
+        lines.push('## 候选列表');
+        lines.push('');
+        for (const c of candidates) {
+            lines.push(`### ${c.index}. ${c.preview.length > 60 ? c.preview.slice(0, 57) + '…' : c.preview}`);
+            lines.push('');
+            lines.push(`- **拟分类**: \`${c.suggestedCategory}\``);
+            lines.push(`- **拟用文件名**: \`${c.suggestedCategory}/${c.suggestedFilename}\``);
+            if (c.timestamp)
+                lines.push(`- **时间**: ${c.timestamp}`);
+            if (c.phase)
+                lines.push(`- **phase**: ${c.phase}`);
+            if (c.inputId)
+                lines.push(`- **inputId**: ${c.inputId}`);
+            if (c.matchedKeywords.length > 0)
+                lines.push(`- **关键词命中**: ${c.matchedKeywords.join(', ')}`);
+            if (c.isRequirementChange)
+                lines.push('- **类型**: 需求变更（非 AI 做错）');
+            lines.push('');
+            lines.push('```');
+            // 全文截断 800 字，避免超长 prompt 把清单撑爆
+            const body = (c.text || '').length > 800 ? c.text.slice(0, 797) + '…' : c.text;
+            lines.push(body);
+            lines.push('```');
+            lines.push('');
+        }
+    }
+    if (dropped.length > 0) {
+        lines.push('## 已过滤候选（不沉淀）');
+        lines.push('');
+        lines.push('| 原始# | 原因 | 引用候选# | 摘要 |');
+        lines.push('|------:|------|----------:|------|');
+        for (const d of dropped) {
+            const reasonLabel = d.reason === 'duplicate-of'
+                ? '重复'
+                : d.reason === 'subset-of'
+                    ? '子串包含'
+                    : d.reason === 'trivial-acknowledgement'
+                        ? '纯确认/无内容'
+                        : d.reason === 'too-short-no-keyword'
+                            ? '过短且未命中关键词'
+                            : '空';
+            const ref = d.refIndex ? `#${d.refIndex}` : '—';
+            const safePreview = (d.preview || '').replace(/\|/g, '\\|');
+            lines.push(`| ${d.rawIndex} | ${reasonLabel} | ${ref} | ${safePreview} |`);
+        }
+        lines.push('');
+    }
+    lines.push('## 操作指引');
+    lines.push('');
+    lines.push('在 review 阶段，主 agent 会用 `askUserQuestion` 询问以下三选项：');
+    lines.push('');
+    lines.push('- **A. 全部沉淀**：将上述 N 条有效候选全部交给 `@skill:zhuanspec:knowledge` 沉淀。');
+    lines.push('- **B. 选择性沉淀**：回复编号清单（例如 `1,3,5`），仅沉淀指定候选。');
+    lines.push('- **C. 跳过**：本轮不沉淀，仅运行 `zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved`。');
+    lines.push('');
+    lines.push('> 注意：「拟分类 / 拟用文件名」仅为启发式建议，最终由 skill 模式 B 的分类决策树确认。');
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=select-candidates.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,17 +134,42 @@ 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,
         '',
-        '询问方式：',
-        '> "这次改动是否值得记录为项目知识？（回复是/否）"',
+        '🔴 **硬性流程（顺序不可跳）**：',
+        '1. 先向用户询问「这次改动是否值得记录为项目知识？（是/否）」。',
+        '2. 用户回复「是」后，**必须调用 \`@skill:zhuanspec:knowledge\`（模式 A）**，由 skill 严格按以下顺序执行：',
+        '   - 4.1 **列候选清单**（不写入任何文件）',
+        '   - 4.2 **调用 \`askUserQuestion\` 多选确认**（A全部 / B选择性 / C跳过）',
+        '   - 4.3 按用户选择写入，未选中的条目一律不写',
+        '   - 4.4 输出摘要',
+        '3. 用户回复「否」时，本次不写入任何知识文件。',
+        '',
+        '🔴 **红线（违反等同于绕过质量门禁）**：',
+        `- **禁止绕过 skill 直接 Write/Edit 创建 \`zhuanspec/knowledge/\` 下的任何文件**；${knowledgeRef}。`,
+        '- **禁止默认全沉淀**：不允许 AI 自行判定 "哪些内容值得沉淀" 后一次性写入多个文件。',
+        '- **禁止跳过询问**：未调用 askUserQuestion 完成多选确认前，不得启动任何写入动作。',
         '',
-        `用户确认后，**必须调用 \`@skill:zhuanspec:knowledge\` （模式 A）** 完成写入，由 skill 统一完成分类决策树、去重扫描、Front Matter 模板套用、index.md 更新。`,
-        `**禁止绕过 skill 直接 Write/Edit 创建 \`zhuanspec/knowledge/\` 下的任何文件**；${knowledgeRef}。`,
-        '如果本次只是常规代码修改，忽略此提示即可。',
+        '如果本次只是常规代码修改，忽略此提示即可（用户回复「否」也会跳过）。',
     ].join('\n');
     return {
         continue: true,

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