@zhuan-ai/zhuanspec 2.15.7 → 2.16.2

package/dist/core/hooks/deviation-check.js

@@ -68,16 +68,6 @@ const USER_CORRECTION_KEYWORDS = [
     'should use', 'should follow', 'optimize this', 'needs optimization',
     'can be optimized', 'better to',
 ];
-// Edit intent keywords — bilingual, for Apply phase scope check
-const EDIT_INTENT_KEYWORDS = [
-    // 中文
-    '修改', '改', '新增', '添加', '增加', '删除', '移除', '重构',
-    '优化', '更新', '替换', '重写', '实现', '完成', '做一下',
-    // English
-    'add', 'change', 'edit', 'update', 'refactor', 'remove', 'delete',
-    'replace', 'rewrite', 'implement', 'fix', 'create', 'write',
-    'modify', 'revise', 'adjust',
-];
 // Requirement-change keywords — 命中后升级为硬拦截（T2 需求变更场景）
 // 与 USER_CORRECTION_KEYWORDS 互斥：这类 prompt 不是在说 AI 做错，而是在追加/变更需求
 const REQUIREMENT_CHANGE_KEYWORDS = [
@@ -126,19 +116,20 @@ export async function deviationCheckHook(options) {
         || options.prompt
         || '';
     const trigger = options.trigger || 'pre-tool';
+    // v2.15.16 Sprint 3：UserPromptSubmit 职责已由 user-input-hook 接管，
+    // deviation-check 仅服务 pre-tool（Write/Edit 拦截）与 resume（session 恢复扫描）。
+    // Codex Ambient Suggestions 警报及独立的 isCodexInternalPrompt 检测由 user-input-hook 负责。
     const output = await runDeviationCheck(filePath, trigger, promptText, options);
     const durationMs = Date.now() - startTime;
-    const hookEvent = trigger === 'post-prompt' ? 'UserPromptSubmit' : 'PreToolUse';
+    const hookEvent = 'PreToolUse';
     await recordHookTrigger('deviation-check', hookEvent, output.continue, {
         toolName,
         filePath,
         message: output.systemMessage,
         durationMs,
     });
-    // Both Claude Code and Codex consume the same JSON envelope. Emit JSON for
-    // post-prompt (additionalContext must reach the host) or when explicitly
-    // requested via --json. See openai/codex#14754 for protocol parity.
-    const useJson = options.json || trigger === 'post-prompt';
+    // --json toggles JSON mode explicitly; PreToolUse default emits systemMessage + exit code.
+    const useJson = options.json === true;
     if (useJson) {
         const jsonOutput = output.hookSpecificOutput
             ? { ...output, hookSpecificOutput: { hookEventName: hookEvent, ...output.hookSpecificOutput } }
@@ -158,6 +149,25 @@ export async function deviationCheckHook(options) {
         }
     }
 }
+/**
+ * 识别 Codex CLI/App 由 Ambient Suggestions 等后台特性发出的系统内部 prompt。
+ * 这类 prompt 并非用户真实输入，不应触发纠偏/需求变更/范围检查。
+ *
+ * 参考：openai/codex#18541 —— Ambient Suggestions 会调用 UserPromptSubmit 钩子
+ * 但不调用对应的 Stop 钩子，且目前无法在项目级关闭。
+ */
+export function isCodexInternalPrompt(prompt) {
+    if (!prompt)
+        return false;
+    const head = prompt.slice(0, 400);
+    // 已知签名（随 Codex 版本可能扩展，新发现请加在这里）
+    const signatures = [
+        /Generate\s+\d+\s+to\s+\d+\s+ambient\s+suggestions/i,
+        /recent\s+Codex\s+threads\s+from\s+this\s+(?:local\s+)?project/i,
+        /ambient\s+suggestions\s+for\s+this\s+local\s+project/i,
+    ];
+    return signatures.some((re) => re.test(head));
+}
 async function readStdin() {
     return new Promise((resolve) => {
         let data = '';
@@ -184,11 +194,8 @@ async function runDeviationCheck(filePath, trigger, promptText, _options) {
             phase = phase || 'idle';
         }
     }
-    // No change bound or idle phase → allow, post-prompt silences itself to avoid noise
+    // No change bound or idle phase → allow
     if (!changeId || phase === 'idle') {
-        if (trigger === 'post-prompt') {
-            return { continue: true };
-        }
         const msg = !changeId
             ? '✓ 当前无绑定变更，正常工作流'
             : `✓ 变更 [${changeId}] 处于 idle 阶段，正常工作流`;
@@ -232,137 +239,10 @@ async function runDeviationCheck(filePath, trigger, promptText, _options) {
             systemMessage: '✓ Resume deviation check passed',
         };
     }
-    // Post-prompt check: inject proposal context for 2-dimension consistency check in Apply phase.
-    if (phase === 'apply' && trigger === 'post-prompt') {
-        // Skip if no proposal exists
-        if (!await FileSystemUtils.fileExists(proposalPath)) {
-            return { continue: true };
-        }
-        const lowerPrompt = promptText.toLowerCase();
-        // Detect correction/pitfall keywords
-        const correctionFound = USER_CORRECTION_KEYWORDS.some(kw => lowerPrompt.includes(kw.toLowerCase()));
-        // Detect edit intent
-        const hasEditIntent = EDIT_INTENT_KEYWORDS.some(kw => lowerPrompt.includes(kw.toLowerCase()));
-        // Detect requirement-change intent（T2）：独立于 hasEditIntent，命中后升级为硬拦截
-        const hasRequirementChange = REQUIREMENT_CHANGE_KEYWORDS.some(kw => lowerPrompt.includes(kw.toLowerCase()));
-        // No action needed if purely read-only and no correction / requirement-change signal
-        if (!hasEditIntent && !correctionFound && !hasRequirementChange) {
-            return { continue: true };
-        }
-        // Load proposal for context injection
-        const proposalContent = await FileSystemUtils.readFile(proposalPath);
-        const proposalSummary = extractProposalSummary(proposalContent, 1500);
-        // === 纠偏命中：硬拦截 + 写标记文件 + 记录 correction-log ===
-        if (correctionFound) {
-            try {
-                // 确保 changeDir 存在
-                if (!fs.existsSync(changeDir)) {
-                    fs.mkdirSync(changeDir, { recursive: true });
-                }
-                // 写入待处理标记（含 TTL 时间戳）
-                const pendingMarker = path.join(changeDir, '.pending-correction');
-                fs.writeFileSync(pendingMarker, JSON.stringify({
-                    createdAt: Date.now(),
-                    prompt: promptText.slice(0, 500),
-                    changeId,
-                }, null, 2), 'utf-8');
-                // 追写 .correction-log（JSONL，用于后续 Stop hook 沉淀询问）
-                const logPath = path.join(changeDir, '.correction-log');
-                const logEntry = JSON.stringify({
-                    ts: new Date().toISOString(),
-                    event: 'detected',
-                    promptPreview: promptText.slice(0, 200),
-                });
-                fs.appendFileSync(logPath, logEntry + '\n', 'utf-8');
-            }
-            catch {
-                // 文件操作失败不阻断拦截
-            }
-            // NOTE: 返回 continue: true（而非 false），确保 additionalContext
-            // 能注入到下一轮对话中，让主 Agent 用 askUserQuestion 展示四选一。
-            // 代码编辑由 pre-tool hook（检测 .pending-correction 标记）兜底拦截。
-            return {
-                continue: true,
-                systemMessage: '⚠️ 检测到用户纠偏信号——已注入纠偏四选一上下文，请主 Agent 用 askUserQuestion 向用户展示选项。',
-                hookSpecificOutput: {
-                    additionalContext: buildCorrectionOptionsContext(proposalSummary, changeId),
-                    options: [
-                        'A. 需求变更 — 先更新 proposal/tasks/specs，再改代码',
-                        'B. Bug 修复豁免 — 直接改代码，本次不更新 Spec',
-                        'C. 纯设计细节 — 不改 Spec 不改代码，仅口头澄清',
-                        'D. 取消本次修改',
-                    ],
-                },
-            };
-        }
-        // === 需求变更（T2）硬拦截：复用 .pending-correction，但标记 reason=requirement-change ===
-        // 与纠偏互斥：仅当没命中纠偏词但命中需求变更词时进入
-        if (hasRequirementChange) {
-            try {
-                if (!fs.existsSync(changeDir)) {
-                    fs.mkdirSync(changeDir, { recursive: true });
-                }
-                const pendingMarker = path.join(changeDir, '.pending-correction');
-                fs.writeFileSync(pendingMarker, JSON.stringify({
-                    createdAt: Date.now(),
-                    prompt: promptText.slice(0, 500),
-                    changeId,
-                    reason: 'requirement-change',
-                }, null, 2), 'utf-8');
-                const logPath = path.join(changeDir, '.correction-log');
-                const logEntry = JSON.stringify({
-                    ts: new Date().toISOString(),
-                    event: 'detected',
-                    reason: 'requirement-change',
-                    promptPreview: promptText.slice(0, 200),
-                });
-                fs.appendFileSync(logPath, logEntry + '\n', 'utf-8');
-            }
-            catch {
-                // 文件操作失败不阻断拦截
-            }
-            // NOTE: 同样返回 continue: true，确保 additionalContext 能注入到对话中。
-            // 代码编辑由 pre-tool hook（检测 .pending-correction 标记）兜底拦截。
-            return {
-                continue: true,
-                systemMessage: '⚠️ 检测到需求变更信号——已注入需求变更上下文，请主 Agent 用 askUserQuestion 向用户确认。',
-                hookSpecificOutput: {
-                    additionalContext: buildRequirementChangeContext(proposalSummary, changeId),
-                    options: [
-                        'A. 确认需求变更 — 先更新 proposal/tasks/specs，再改代码',
-                        'D. 取消本次需求变更',
-                    ],
-                },
-            };
-        }
-        // 仅有编辑意图时：保持原有两维度一致性软提示
-        const reverseSyncFiles = [
-            '`proposal.md`（更新变更原因/影响范围）',
-            '`tasks.md`（新增或调整对应任务）',
-            '`specs/*/spec.md`（更新受影响的 spec 需求条目）',
-            '`design.md`（如存在，更新技术设计决策）',
-        ].join('、');
-        let additionalContext = '## ⚠️ ZhuanSpec Apply 阶段一致性检测\n\n';
-        additionalContext += `**当前变更提案摘要：**\n${proposalSummary}\n\n`;
-        additionalContext += `**处理以下用户请求前，请先做两维度一致性检测：**\n\n`;
-        additionalContext += `- **维度1（范围）**：用户请求涉及的文件/功能是否在提案中明确提及？\n`;
-        additionalContext += `  - 在提案范围内 → 正常实施\n`;
-        additionalContext += `  - **超出提案范围** → 先告知用户，执行 Reverse Sync：依次更新 ${reverseSyncFiles}，经用户确认后再实施代码\n\n`;
-        additionalContext += `- **维度2（逻辑一致性）**：用户请求的逻辑调整是否与提案设计意图一致？\n`;
-        additionalContext += `  - 一致 → 正常实施\n`;
-        additionalContext += `  - **逻辑有偏差** → 说明偏差点，同样执行 Reverse Sync 更新所有相关提案文件（${reverseSyncFiles}），经用户确认后再实施\n\n`;
-        return {
-            continue: true,
-            systemMessage: '✓ ZhuanSpec: Apply 阶段一致性检测已注入上下文',
-            hookSpecificOutput: {
-                additionalContext,
-            },
-        };
-    }
     // Propose phase → block all code modifications (Iron Law 1: No Spec No Code)
     // But check if we can transition to Apply phase
     if (phase === 'propose') {
-        // UserPromptSubmit(post-prompt) 和 resume 无 filePath 上下文，静默放行，仅 pre-tool 做拦截
+        // resume trigger 无 filePath 上下文，静默放行，仅 pre-tool 做拦截
         if (trigger !== 'pre-tool') {
             return { continue: true };
         }
@@ -485,34 +365,6 @@ async function runDeviationCheck(filePath, trigger, promptText, _options) {
                 }
             }
         }
-        // === Task completion gate for Apply→Review transition ===
-        if (trigger === 'post-prompt') {
-            const lowerPrompt = promptText.toLowerCase();
-            const reviewTransitionKeywords = [
-                'review', '审查', '进入review', 'review阶段', '代码审查',
-                'zhuanspec review', '/review', '开始review',
-            ];
-            const isReviewTransition = reviewTransitionKeywords.some(kw => lowerPrompt.includes(kw));
-            if (isReviewTransition && await FileSystemUtils.fileExists(tasksPath)) {
-                try {
-                    const tasksContent = await FileSystemUtils.readFile(tasksPath);
-                    const uncompleted = tasksContent.match(/^- \[ \] .+$/gm) || [];
-                    if (uncompleted.length > 0) {
-                        return {
-                            continue: false,
-                            stopReason: 'Task completion gate: uncompleted tasks block Review transition',
-                            systemMessage: `⚠️ BLOCKED: Cannot transition to Review — ${uncompleted.length} tasks uncompleted in tasks.md.\n\nUncompleted tasks:\n${uncompleted.map(t => `  ${t.trim()}`).join('\n')}\n\nPlease complete all tasks before entering Review, or use \`zhuanspec review <id> --force\` to override.`,
-                            hookSpecificOutput: {
-                                additionalContext: `Task completion gate blocked Apply→Review transition. ${uncompleted.length} uncompleted tasks found.`,
-                            },
-                        };
-                    }
-                }
-                catch {
-                    // If tasks.md read fails, allow transition
-                }
-            }
-        }
         let estimatedFiles = [];
         let currentTaskFiles = [];
         let estimatedSymbols = [];
@@ -581,10 +433,6 @@ ZhuanSpec Iron Law 3: Reverse Sync - When deviation is found, update proposal fi
             },
         };
     }
-    // post-prompt in non-apply phases (propose/techDesign/review/...) → silently allow
-    if (trigger === 'post-prompt') {
-        return { continue: true };
-    }
     // Default: allow
     return {
         continue: true,
@@ -664,7 +512,7 @@ async function parseEstimatedSymbols(proposalPath) {
         return [];
     }
 }
-function extractProposalSummary(content, maxLength) {
+export function extractProposalSummary(content, maxLength) {
     const patterns = [
         /^## (?:Summary|摘要|Overview|概述)[\s\S]*?(?=\n## |\n# |$)/im,
         /^## (?:What Changes|变更内容|Changes|修改内容)[\s\S]*?(?=\n## |\n# |$)/im,
@@ -736,13 +584,13 @@ function normalizePath(p) {
  *  3. 按选择走对应路径
  *  4. 路径完成后运行 resolve-correction 清理标记
  */
-function buildCorrectionOptionsContext(proposalSummary, changeId) {
+export function buildCorrectionOptionsContext(proposalSummary, changeId) {
     let ctx = '## ⚠️ ZhuanSpec Apply 阶段用户纠偏——必须四选一后再继续\n\n';
     ctx += `**当前变更提案摘要：**\n${proposalSummary}\n\n`;
     ctx += `### 必须按以下顺序执行（严禁跳步）\n\n`;
     ctx += `1. **立即停止**：不得调用任何 Edit/Write，不得启动新 Subagent\n`;
     ctx += `2. **用 askUserQuestion 向用户提出四选一**（措辞与 Hook options 一致）：\n`;
-    ctx += `   - A. 需求变更 — 先更新 proposal/tasks/specs，再改代码\n`;
+    ctx += `   - A. 先修 Spec — 先更新 proposal/tasks/specs，再改代码\n`;
     ctx += `   - B. Bug 修复豁免 — 直接改代码，本次不更新 Spec\n`;
     ctx += `   - C. 纯设计细节 — 不改 Spec 不改代码，仅口头澄清\n`;
     ctx += `   - D. 取消本次修改\n\n`;
@@ -761,13 +609,13 @@ function buildCorrectionOptionsContext(proposalSummary, changeId) {
  *  - 仅提供 A / D 两个选项（需求变更必然要先改 Spec，无 Bug 豁免路径）
  *  - 文案强调“新增/变更功能范围”而非“AI 做错”
  */
-function buildRequirementChangeContext(proposalSummary, changeId) {
+export function buildRequirementChangeContext(proposalSummary, changeId) {
     let ctx = '## ⚠️ ZhuanSpec Apply 阶段需求变更——必须先同步 Spec 再改代码\n\n';
     ctx += `**当前变更提案摘要：**\n${proposalSummary}\n\n`;
     ctx += `### 必须按以下顺序执行（严禁跳步）\n\n`;
     ctx += `1. **立即停止**：不得调用任何 Edit/Write 修改代码文件，不得启动新 Subagent\n`;
     ctx += `2. **用 askUserQuestion 向用户确认需求变更**（措辞与 Hook options 一致）：\n`;
-    ctx += `   - A. 确认需求变更 — 先更新 proposal/tasks/specs，再改代码\n`;
+    ctx += `   - A. 先修 Spec — 先更新 proposal/tasks/specs，再改代码\n`;
     ctx += `   - D. 取消本次需求变更\n\n`;
     ctx += `3. **选 A 的处理路径**：依次 Edit \`proposal.md\` → \`tasks.md\` → \`specs/<cap>/spec.md\`；\n`;
     ctx += `   全部完成后执行 \`zhuanspec progress resolve-correction ${changeId} A\` 清理标记，再重新下发代码实施任务\n`;

package/dist/core/hooks/knowledge-index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Knowledge Index Utilities
+ *
+ * 统一 zhuanspec/knowledge/index.md 的三大分区管理：
+ * - Troubleshooting / Best Practices / Implicit Conventions 三类登记
+ * - 保留 Archive Log 既有内容
+ * - 提供"增量追加"（appendIndexEntry）与"全量重建"（rebuildIndex）
+ *
+ * 被 post-archive hook（CLI 自动提取）与 `zhuanspec knowledge reindex` 命令共用。
+ */
+/** 知识库三类分类目录（不得新增） */
+export type KnowledgeCategory = 'troubleshooting' | 'best-practices' | 'implicit-conventions';
+export declare const KNOWLEDGE_CATEGORIES: readonly KnowledgeCategory[];
+/** 单条知识条目（来源于知识文件的 Front Matter 解析） */
+export interface KnowledgeEntry {
+    category: KnowledgeCategory;
+    /** 相对 knowledgeDir 的文件名，形如 `20260508-foo.md` */
+    fileName: string;
+    /** 文件标题（首行 `# xxx` 或 Front Matter 的 title 字段） */
+    title: string;
+    /** 逗号分隔关键词 */
+    keywords: string;
+    /** 适用场景：一句话"何时引用本条知识" */
+    useCase: string;
+}
+/** Front Matter 解析结果 */
+export interface KnowledgeFrontMatter {
+    title: string;
+    keywords: string;
+    useCase: string;
+    missingUseCase: boolean;
+    missingKeywords: boolean;
+}
+/**
+ * 生成默认的空 index.md 骨架（含三分区 + Archive Log）。
+ */
+export declare function buildInitialIndex(): string;
+/**
+ * 生成单条登记行。
+ * 形如：`- [标题](best-practices/xxx.md) — 关键词 · 适用场景：何时用`
+ */
+export declare function buildEntryLine(entry: KnowledgeEntry): string;
+/**
+ * 确保 index.md 含完整三分区骨架；若缺失分区则补齐（不覆盖已有条目与 Archive Log）。
+ */
+export declare function ensureSkeleton(content: string): string;
+/**
+ * 读取 index.md，缺失则按骨架初始化；返回当前文本。
+ */
+export declare function readOrInitIndex(indexPath: string): Promise<string>;
+/**
+ * 向 index.md 对应分区追加一条登记。
+ * - 已存在同一 `(category/fileName)` 引用时跳过（幂等）。
+ * - 分区缺失时自动补齐骨架。
+ *
+ * @returns true 表示新追加；false 表示已存在被跳过
+ */
+export declare function appendIndexEntry(indexPath: string, entry: KnowledgeEntry): Promise<boolean>;
+/**
+ * 从一段 markdown 文本中解析知识条目 Front Matter。
+ * 支持项目现行的 `**字段**: 值` 样式；字段可选，缺失时返回对应 missing 标记。
+ */
+export declare function parseFrontMatter(markdown: string): KnowledgeFrontMatter;
+/**
+ * 扫描结果：每类目录下发现的知识条目（含缺字段告警）。
+ */
+export interface ScanResult {
+    entries: KnowledgeEntry[];
+    warnings: string[];
+}
+/**
+ * 扫描 knowledge/{troubleshooting,best-practices,implicit-conventions}/*.md，
+ * 解析 Front Matter 组装 KnowledgeEntry 列表，遇缺字段记录 warning（不阻断）。
+ */
+export declare function scanKnowledgeEntries(knowledgeDir: string): Promise<ScanResult>;
+/**
+ * 全量重建 index.md 的三大分区（保留 Archive Log 既有内容）。
+ * 算法：
+ * 1. 读取旧 index.md，提取 `## Archive Log` 分区的全部尾部内容；
+ * 2. 用骨架 + 扫描得到的条目重新生成三分区；
+ * 3. 末尾拼回 Archive Log。
+ */
+export declare function rebuildIndexContent(scan: ScanResult, existingContent: string | null): string;
+//# sourceMappingURL=knowledge-index.d.ts.map

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

@@ -0,0 +1,270 @@
+/**
+ * Knowledge Index Utilities
+ *
+ * 统一 zhuanspec/knowledge/index.md 的三大分区管理：
+ * - Troubleshooting / Best Practices / Implicit Conventions 三类登记
+ * - 保留 Archive Log 既有内容
+ * - 提供"增量追加"（appendIndexEntry）与"全量重建"（rebuildIndex）
+ *
+ * 被 post-archive hook（CLI 自动提取）与 `zhuanspec knowledge reindex` 命令共用。
+ */
+import path from 'path';
+import { promises as fs } from 'fs';
+import { FileSystemUtils } from '../../utils/file-system.js';
+export const KNOWLEDGE_CATEGORIES = [
+    'troubleshooting',
+    'best-practices',
+    'implicit-conventions',
+];
+/** 分区标题（与 index.md 骨架保持一致） */
+const SECTION_HEADINGS = {
+    'troubleshooting': '## Troubleshooting',
+    'best-practices': '## Best Practices',
+    'implicit-conventions': '## Implicit Conventions',
+};
+const SECTION_COMMENTS = {
+    'troubleshooting': '<!-- 踩坑 / bug / 错误做法，由 @skill:zhuanspec:knowledge 模式 B 管理 -->',
+    'best-practices': '<!-- 可复用的最佳实践 / 设计决策，由 post-archive hook 与 skill 共同管理 -->',
+    'implicit-conventions': '<!-- 隐式约定 / 默认行为 / 团队惯例，由 post-archive hook 与 skill 共同管理 -->',
+};
+const ARCHIVE_LOG_HEADING = '## Archive Log';
+const INDEX_HEADER = `# Knowledge Index
+
+> 项目知识索引。AI 在进入任何阶段前应先浏览本文件，根据每条"适用场景"判断是否需要打开对应文件。
+> 入口：所有写入由 \`@skill:zhuanspec:knowledge\` 或 post-archive hook 统一完成，禁止直接 Write/Edit 本目录。
+> 索引漂移时运行 \`zhuanspec knowledge reindex --dry-run\` 查看差异。`;
+/**
+ * 生成默认的空 index.md 骨架（含三分区 + Archive Log）。
+ */
+export function buildInitialIndex() {
+    const sections = KNOWLEDGE_CATEGORIES.map((cat) => `${SECTION_HEADINGS[cat]}\n${SECTION_COMMENTS[cat]}\n`).join('\n');
+    return `${INDEX_HEADER}\n\n${sections}\n${ARCHIVE_LOG_HEADING}\n`;
+}
+/**
+ * 生成单条登记行。
+ * 形如：`- [标题](best-practices/xxx.md) — 关键词 · 适用场景：何时用`
+ */
+export function buildEntryLine(entry) {
+    const keywords = entry.keywords.trim() || '（未填写关键词）';
+    const useCase = entry.useCase.trim() || '（未填写适用场景）';
+    return `- [${entry.title}](${entry.category}/${entry.fileName}) — ${keywords} · 适用场景：${useCase}`;
+}
+/**
+ * 确保 index.md 含完整三分区骨架；若缺失分区则补齐（不覆盖已有条目与 Archive Log）。
+ */
+export function ensureSkeleton(content) {
+    let result = content;
+    // 无 `# Knowledge Index` 时视作全新文件
+    if (!/^#\s+Knowledge\s+Index/m.test(result)) {
+        return buildInitialIndex() + (result.trim() ? `\n${result.trim()}\n` : '');
+    }
+    // 逐个分区检查：缺失则插入到 `## Archive Log` 之前（保持顺序：ts / bp / ic / archive）
+    for (const cat of KNOWLEDGE_CATEGORIES) {
+        const heading = SECTION_HEADINGS[cat];
+        const headingRegex = new RegExp(`^${escapeRegex(heading)}\\s*$`, 'm');
+        if (headingRegex.test(result))
+            continue;
+        const sectionBlock = `${heading}\n${SECTION_COMMENTS[cat]}\n\n`;
+        const archiveMatch = result.match(new RegExp(`^${escapeRegex(ARCHIVE_LOG_HEADING)}`, 'm'));
+        if (archiveMatch && archiveMatch.index !== undefined) {
+            result = result.slice(0, archiveMatch.index) + sectionBlock + result.slice(archiveMatch.index);
+        }
+        else {
+            // 没有 Archive Log 分区：追加到文件末尾
+            result = `${result.trimEnd()}\n\n${sectionBlock}${ARCHIVE_LOG_HEADING}\n`;
+        }
+    }
+    return result;
+}
+/**
+ * 读取 index.md，缺失则按骨架初始化；返回当前文本。
+ */
+export async function readOrInitIndex(indexPath) {
+    if (await FileSystemUtils.fileExists(indexPath)) {
+        const raw = await FileSystemUtils.readFile(indexPath);
+        return ensureSkeleton(raw);
+    }
+    return buildInitialIndex();
+}
+/**
+ * 向 index.md 对应分区追加一条登记。
+ * - 已存在同一 `(category/fileName)` 引用时跳过（幂等）。
+ * - 分区缺失时自动补齐骨架。
+ *
+ * @returns true 表示新追加；false 表示已存在被跳过
+ */
+export async function appendIndexEntry(indexPath, entry) {
+    await FileSystemUtils.createDirectory(path.dirname(indexPath));
+    let content = await readOrInitIndex(indexPath);
+    content = ensureSkeleton(content);
+    const refPattern = `(${entry.category}/${entry.fileName})`;
+    if (content.includes(refPattern)) {
+        // 已登记 → 幂等跳过；但 content 可能因 ensureSkeleton 被补了骨架，仍需写回
+        if (content !== (await safeRead(indexPath))) {
+            await FileSystemUtils.writeFile(indexPath, content);
+        }
+        return false;
+    }
+    content = insertIntoSection(content, entry.category, buildEntryLine(entry));
+    await FileSystemUtils.writeFile(indexPath, content);
+    return true;
+}
+async function safeRead(p) {
+    try {
+        return await FileSystemUtils.readFile(p);
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * 在指定分区末尾（下一个 `## ` 标题之前）插入一行。
+ */
+function insertIntoSection(content, category, line) {
+    const heading = SECTION_HEADINGS[category];
+    const lines = content.split('\n');
+    const headingIdx = lines.findIndex((l) => l.trim() === heading);
+    if (headingIdx === -1) {
+        // ensureSkeleton 之后不应该走到这里，兜底再加一段
+        return `${content.trimEnd()}\n\n${heading}\n${line}\n`;
+    }
+    // 找到下一个 `## ` 一级分区标题位置（Archive Log 或下一个 category）
+    let nextIdx = lines.length;
+    for (let i = headingIdx + 1; i < lines.length; i++) {
+        if (/^##\s+/.test(lines[i])) {
+            nextIdx = i;
+            break;
+        }
+    }
+    // 从 headingIdx+1 到 nextIdx-1 是该分区内容；去掉尾部空行再插入新条目，保持紧凑
+    const before = lines.slice(0, nextIdx);
+    const after = lines.slice(nextIdx);
+    // 去掉分区内尾部的连续空行
+    while (before.length > headingIdx + 1 && before[before.length - 1].trim() === '') {
+        before.pop();
+    }
+    before.push(line, '');
+    return [...before, ...after].join('\n');
+}
+/**
+ * 从一段 markdown 文本中解析知识条目 Front Matter。
+ * 支持项目现行的 `**字段**: 值` 样式；字段可选，缺失时返回对应 missing 标记。
+ */
+export function parseFrontMatter(markdown) {
+    const titleMatch = markdown.match(/^#\s+(.+?)\s*$/m);
+    const title = titleMatch ? titleMatch[1].trim() : '';
+    const pick = (label) => {
+        const re = new RegExp(`\\*\\*${escapeRegex(label)}\\*\\*\\s*[:：]\\s*(.+?)\\s*$`, 'm');
+        const m = markdown.match(re);
+        return m ? m[1].trim() : '';
+    };
+    const keywords = pick('关键词');
+    const useCase = pick('适用场景');
+    return {
+        title,
+        keywords,
+        useCase,
+        missingUseCase: !useCase,
+        missingKeywords: !keywords,
+    };
+}
+/**
+ * 扫描 knowledge/{troubleshooting,best-practices,implicit-conventions}/*.md，
+ * 解析 Front Matter 组装 KnowledgeEntry 列表，遇缺字段记录 warning（不阻断）。
+ */
+export async function scanKnowledgeEntries(knowledgeDir) {
+    const entries = [];
+    const warnings = [];
+    for (const category of KNOWLEDGE_CATEGORIES) {
+        const dir = path.join(knowledgeDir, category);
+        if (!(await FileSystemUtils.directoryExists(dir)))
+            continue;
+        let files = [];
+        try {
+            files = (await fs.readdir(dir)).filter((f) => f.endsWith('.md') && !f.startsWith('.'));
+        }
+        catch {
+            continue;
+        }
+        files.sort();
+        for (const file of files) {
+            const full = path.join(dir, file);
+            let text = '';
+            try {
+                text = await FileSystemUtils.readFile(full);
+            }
+            catch {
+                warnings.push(`[WARN] 读取失败: ${category}/${file}`);
+                continue;
+            }
+            const fm = parseFrontMatter(text);
+            if (!fm.title) {
+                warnings.push(`[WARN] ${category}/${file} 缺少一级标题 (# 标题)，使用文件名兜底`);
+            }
+            if (fm.missingKeywords) {
+                warnings.push(`[WARN] ${category}/${file} 缺少 **关键词** 字段`);
+            }
+            if (fm.missingUseCase) {
+                warnings.push(`[WARN] ${category}/${file} 缺少 **适用场景** 字段（请尽快补齐）`);
+            }
+            const firstKeyword = fm.keywords ? fm.keywords.split(/[,，]/)[0].trim() : '';
+            entries.push({
+                category,
+                fileName: file,
+                title: fm.title || file.replace(/\.md$/, ''),
+                keywords: fm.keywords,
+                // 兜底：适用场景缺失时用"首关键词相关任务"
+                useCase: fm.useCase || (firstKeyword ? `涉及 ${firstKeyword} 相关任务时` : '（未填写适用场景，待补齐）'),
+            });
+        }
+    }
+    return { entries, warnings };
+}
+/**
+ * 全量重建 index.md 的三大分区（保留 Archive Log 既有内容）。
+ * 算法：
+ * 1. 读取旧 index.md，提取 `## Archive Log` 分区的全部尾部内容；
+ * 2. 用骨架 + 扫描得到的条目重新生成三分区；
+ * 3. 末尾拼回 Archive Log。
+ */
+export function rebuildIndexContent(scan, existingContent) {
+    // 1. 提取旧 Archive Log 块
+    let archiveBlock = `${ARCHIVE_LOG_HEADING}\n`;
+    if (existingContent) {
+        const archiveIdx = existingContent.indexOf(ARCHIVE_LOG_HEADING);
+        if (archiveIdx !== -1) {
+            // 从 Archive Log 标题开始到文件末尾
+            archiveBlock = existingContent.slice(archiveIdx).trimEnd() + '\n';
+        }
+    }
+    // 2. 按分类整理条目（保持扫描顺序 = 字典序）
+    const byCategory = {
+        'troubleshooting': [],
+        'best-practices': [],
+        'implicit-conventions': [],
+    };
+    for (const e of scan.entries)
+        byCategory[e.category].push(e);
+    const parts = [INDEX_HEADER, ''];
+    for (const cat of KNOWLEDGE_CATEGORIES) {
+        parts.push(SECTION_HEADINGS[cat]);
+        parts.push(SECTION_COMMENTS[cat]);
+        const list = byCategory[cat];
+        if (list.length === 0) {
+            parts.push('');
+        }
+        else {
+            parts.push('');
+            for (const e of list)
+                parts.push(buildEntryLine(e));
+            parts.push('');
+        }
+    }
+    parts.push(archiveBlock.trimEnd());
+    parts.push('');
+    return parts.join('\n');
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=knowledge-index.js.map