@zhuan-ai/zhuanspec 2.16.6 → 2.17.0

package/dist/core/hooks/post-archive.js

@@ -3,7 +3,7 @@ import { FileSystemUtils } from '../../utils/file-system.js';
 import { readdirSync, rmSync } from 'fs';
 import chalk from 'chalk';
 import { getBeijingTime, getBeijingTimeForFilename } from './record-progress.js';
-import { scanKnowledgeEntries, rebuildIndexContent, } from './knowledge-index.js';
+import { scanKnowledgeEntries, rebuildIndexContent, parseDeprecatesDeclaration, parseFrontMatter, findEntryFileById, setEntryStatus, } from './knowledge-index.js';
 export async function postArchiveHook(options) {
     const output = await runPostArchiveHook(options.archived || '');
     if (options.json) {
@@ -33,6 +33,15 @@ async function runPostArchiveHook(archivedChange) {
     if (knowledgeResult.implicitConventions > 0) {
         console.log(chalk.gray(`    - 隐式约定：${knowledgeResult.implicitConventions} 条`));
     }
+    // 1.5 失效闭环：解析归档文档 deprecates 声明，把对应知识标 deprecated（必须在 reindex 之前，
+    //     reindex 时 scanKnowledgeEntries 才能读到新 status，rebuildIndexContent 才会把它移出三分区）。
+    const deprecation = await markDeprecatedKnowledge(zhuanspecDir, archivedChange, knowledgeDir);
+    if (deprecation.deprecatedFiles.length > 0) {
+        console.log(chalk.gray(`  → 标记失效知识：${deprecation.deprecatedFiles.length} 条 deprecated`));
+    }
+    if (deprecation.notFoundIds.length > 0) {
+        console.log(chalk.yellow(`    ⚠ ${deprecation.notFoundIds.length} 条 deprecates 声明未找到对应知识：${deprecation.notFoundIds.join(', ')}`));
+    }
     // 2. Reindex 三分区（修复：archive 前的 refreshBusinessTemplateFromRemote 会用远端 index.md
     //    覆盖本地，导致 review/knowledge skill 期间 appendIndexEntry 的登记行丢失。
     //    这里基于本地 troubleshooting/ best-practices/ implicit-conventions/ 实际文件重建三分区，
@@ -47,6 +56,11 @@ async function runPostArchiveHook(archivedChange) {
     console.log(chalk.gray(`    - troubleshooting=${scan.entries.filter((e) => e.category === 'troubleshooting').length}, ` +
         `best-practices=${scan.entries.filter((e) => e.category === 'best-practices').length}, ` +
         `implicit-conventions=${scan.entries.filter((e) => e.category === 'implicit-conventions').length}`));
+    if (scan.errors.length > 0) {
+        console.log(chalk.red(`    ✗ Front Matter 严重缺失 ${scan.errors.length} 条（YAML 格式缺 id/title）：`));
+        for (const e of scan.errors)
+            console.log(chalk.red(`      ${e}`));
+    }
     if (scan.warnings.length > 0) {
         console.log(chalk.yellow(`    ⚠ Front Matter 不完整 ${scan.warnings.length} 条，建议补齐关键词/适用场景`));
     }
@@ -61,17 +75,50 @@ async function runPostArchiveHook(archivedChange) {
         console.log(chalk.gray(`    - 已清理：${tempFilesCleaned} 个`));
     }
     const totalEntries = knowledgeResult.bestPractices + knowledgeResult.implicitConventions;
-    console.log(chalk.green(`✅ 知识收集完成：共 ${totalEntries} 条记录`));
+    console.log(chalk.green(`✅ 知识草稿生成完成：共 ${totalEntries} 条候选`));
+    // 若有待精炼草稿，注入精炼提示让主 agent 调 @skill:zhuanspec:knowledge 处理
+    const additionalContext = totalEntries > 0
+        ? buildRefinementPrompt(archivedChange, knowledgeResult, knowledgeDir)
+        : undefined;
     return {
         continue: true,
-        systemMessage: `Post-archive: knowledge updated for ${archivedChange}, ${knowledgeResult.bestPractices} best practices, ${knowledgeResult.implicitConventions} implicit conventions, ${tempFilesCleaned} temp files cleaned`,
+        systemMessage: `Post-archive: ${totalEntries} knowledge candidates staged to .pending/ for ${archivedChange}, ${tempFilesCleaned} temp files cleaned`,
         hookSpecificOutput: {
             bestPracticesCollected: knowledgeResult.bestPractices,
             implicitConventionsCollected: knowledgeResult.implicitConventions,
             tempFilesCleaned,
+            additionalContext,
         },
     };
 }
+/**
+ * 生成精炼提示，注入主 agent 上下文，
+ * 引导其调用 @skill:zhuanspec:knowledge 对草稿进行 LLM 精炼后合并入正式库。
+ */
+function buildRefinementPrompt(archivedChange, result, knowledgeDir) {
+    const pendingDir = path.join(knowledgeDir, '.pending');
+    const lines = [
+        `📋 **知识精炼提示**（归档 ${archivedChange} 完成后自动触发）`,
+        '',
+        `从归档文档中提取到 **${result.bestPractices + result.implicitConventions} 条**知识候选：`,
+        result.bestPractices > 0 ? `  - best-practices 候选：${result.bestPractices} 条` : '',
+        result.implicitConventions > 0 ? `  - implicit-conventions 候选：${result.implicitConventions} 条` : '',
+        '',
+        `草稿文件已暂存至：\`${pendingDir}\``,
+        '',
+        '🔴 **请按以下流程精炼草稿（不可跳过）**：',
+        '1. 读取 `.pending/` 下的草稿文件，理解候选内容。',
+        '2. 调用 `@skill:zhuanspec:knowledge`（模式 A），将候选内容精炼为：',
+        '   - 标准 YAML front matter（含 id / trigger / severity / status）',
+        '   - 三段正文：`## 适用场景` → `## 规则` → `## 反例/正例`',
+        '3. 若知识库中已有同 `id` 条目，追加 `source_change` 记录，**不新建文件**。',
+        '4. 精炼完成后删除 `.pending/` 下对应草稿。',
+        '',
+        '⚠️ **降级策略**：若当前无条件调用 skill（如会话已结束），草稿文件将保留，',
+        '下次 session 开始时由 context-load hook 重新提示精炼。',
+    ].filter((l) => l !== undefined);
+    return lines.join('\n');
+}
 /**
  * Extract knowledge records from change directory (proposal.md, tasks.md, design.md, specs/*.md)
  * and save to knowledge subdirectories
@@ -124,45 +171,44 @@ async function collectChangeKnowledge(zhuanspecDir, archivedChange, knowledgeDir
         return result;
     }
     try {
-        // Create knowledge subdirectories（仅三类：best-practices / implicit-conventions / troubleshooting；
-        // troubleshooting 由 zhuanspec:knowledge skill 单独写入，此处不做归档提取）
-        const bestPracticesDir = path.join(knowledgeDir, 'best-practices');
-        const implicitConventionsDir = path.join(knowledgeDir, 'implicit-conventions');
-        await FileSystemUtils.createDirectory(bestPracticesDir);
-        await FileSystemUtils.createDirectory(implicitConventionsDir);
-        // Define regex patterns for each knowledge type (Chinese and English)
-        // 原“决策类”关键字统一归入 best-practices
+        // 草稿暂存目录：knowledge/.pending/
+        // 不直接落正式库，由后续 LLM 精炼（@skill:zhuanspec:knowledge）合并为结构化条目
+        const pendingDir = path.join(knowledgeDir, '.pending');
+        await FileSystemUtils.createDirectory(pendingDir);
+        // 正则模式：原”决策类”关键字统一归入 best-practices
         const patterns = {
             bestPractices: /^##\s+(最佳实践|Best\s+Practice|Best\s+Practices|推荐做法|建议|注意事项|决策|Decision|技术决策|架构决策)[\s\S]*?(?=^##[^#]|$)/gm,
             implicitConventions: /^##\s+(隐式约定|Implicit\s+Convention|默认行为|约定|惯例|约定事项)[\s\S]*?(?=^##[^#]|$)/gm,
         };
-        const targetDirs = {
-            bestPractices: bestPracticesDir,
-            implicitConventions: implicitConventionsDir,
-        };
-        // Extract and save each knowledge type
         for (const [type, pattern] of Object.entries(patterns)) {
             const matches = combinedContent.matchAll(pattern);
-            const entries = [];
+            const candidates = [];
             for (const match of matches) {
                 const content = match[0].trim();
                 if (content.length > 50) {
-                    entries.push(content);
+                    candidates.push(content);
                 }
             }
-            if (entries.length > 0) {
+            if (candidates.length > 0) {
                 const timestamp = getBeijingTimeForFilename();
-                const fileName = `${archivedChange}-${type}-${timestamp}.md`;
-                const filePath = path.join(targetDirs[type], fileName);
-                const typeLabel = type === 'bestPractices' ? 'Best Practices' : 'Implicit Conventions';
-                const doc = `# ${typeLabel} from ${archivedChange}
-
-Extracted on: ${getBeijingTime()}
-
-${entries.join('\n\n---\n\n')}
-`;
+                const typeLabel = type === 'bestPractices' ? 'best-practices' : 'implicit-conventions';
+                // 草稿文件名带 .pending 标记，区别于正式库文件
+                const fileName = `${archivedChange}-${typeLabel}-${timestamp}.pending.md`;
+                const filePath = path.join(pendingDir, fileName);
+                const doc = [
+                    `# [PENDING] ${typeLabel} from ${archivedChange}`,
+                    '',
+                    `> 此文件为归档自动提取的原始草稿，需经 @skill:zhuanspec:knowledge 精炼后合并入正式知识库。`,
+                    `> 提取时间：${getBeijingTime()}`,
+                    `> 目标分类：knowledge/${typeLabel}/`,
+                    '',
+                    '---',
+                    '',
+                    candidates.join('\n\n---\n\n'),
+                    '',
+                ].join('\n');
                 await FileSystemUtils.writeFile(filePath, doc);
-                result[type] = entries.length;
+                result[type] = candidates.length;
             }
         }
         return result;
@@ -171,6 +217,59 @@ ${entries.join('\n\n---\n\n')}
         return result;
     }
 }
+/**
+ * 解析归档的 tasks.md / proposal.md 中的 deprecates 声明，将命中的知识文件标 deprecated。
+ * 全程容错：解析/改写失败不抛错、不阻断归档；未命中 id 仅记入 notFoundIds。
+ */
+async function markDeprecatedKnowledge(zhuanspecDir, archivedChange, knowledgeDir) {
+    const result = { declaredIds: [], deprecatedFiles: [], notFoundIds: [] };
+    const archiveDir = path.join(zhuanspecDir, 'changes', 'archive', archivedChange);
+    const sourceFiles = [
+        path.join(archiveDir, 'tasks.md'),
+        path.join(archiveDir, 'proposal.md'),
+    ];
+    let combined = '';
+    for (const filePath of sourceFiles) {
+        if (await FileSystemUtils.fileExists(filePath)) {
+            try {
+                combined += `\n${await FileSystemUtils.readFile(filePath)}`;
+            }
+            catch {
+                // 忽略读失败
+            }
+        }
+    }
+    if (!combined.trim())
+        return result;
+    result.declaredIds = parseDeprecatesDeclaration(combined);
+    for (const id of result.declaredIds) {
+        try {
+            const file = await findEntryFileById(knowledgeDir, id);
+            if (!file) {
+                result.notFoundIds.push(id);
+                continue;
+            }
+            const changed = await setEntryStatus(file, 'deprecated');
+            if (changed) {
+                result.deprecatedFiles.push(path.relative(knowledgeDir, file));
+                continue;
+            }
+            // setEntryStatus 返回 false 有两种情形：已是 deprecated（幂等成功）/ 旧散文式无法改写。
+            // 复核当前 status 区分：已失效视为成功（记入 deprecatedFiles），否则归入 notFound。
+            const fm = parseFrontMatter(await FileSystemUtils.readFile(file));
+            if (fm.isYaml && fm.status === 'deprecated') {
+                result.deprecatedFiles.push(path.relative(knowledgeDir, file));
+            }
+            else {
+                result.notFoundIds.push(id);
+            }
+        }
+        catch {
+            result.notFoundIds.push(id);
+        }
+    }
+    return result;
+}
 /**
  * Cleanup temporary files from zhuanspec directory
  */

package/dist/core/hooks/review-hooks.js

@@ -14,8 +14,11 @@
  */
 import path from 'path';
 import fs from 'fs';
+import { execSync } from 'child_process';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { getBeijingTime } from './record-progress.js';
+import { GitRepoDetector } from '../../utils/git-repo-detector.js';
+import { resolveZhuanSpecRoot } from '../../utils/resolve-root.js';
 // Output file paths for skill results
 const CODE_REVIEW_OUTPUT = 'code-review-result.json';
 const UNIT_TEST_OUTPUT = 'unit-test-result.json';
@@ -306,14 +309,168 @@ export async function specConsistencyResultCheck(changeId, skillOutput) {
 // ============================================================
 // Basic Consistency Analysis Fallback
 // ============================================================
+function normalizeComparisonPath(filePath) {
+    return filePath.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '').trim();
+}
+function buildScenarioKeywords(text) {
+    const normalized = text.toLowerCase();
+    const keywords = new Set();
+    normalized
+        .split(/[\s\-_/\uff0c\u3001]+/)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 3)
+        .forEach((part) => keywords.add(part));
+    normalized.match(/[a-z0-9_]{4,}/g)?.forEach((part) => keywords.add(part));
+    normalized.match(/[0-9]{2,}/g)?.forEach((part) => keywords.add(part));
+    const chineseSegments = normalized.match(/[\u4e00-\u9fff0-9]+/g) || [];
+    for (const segment of chineseSegments) {
+        if (segment.length <= 1)
+            continue;
+        keywords.add(segment);
+        const maxWindow = Math.min(segment.length, 6);
+        for (let window = 2; window <= maxWindow; window++) {
+            for (let start = 0; start <= segment.length - window; start++) {
+                keywords.add(segment.slice(start, start + window));
+            }
+        }
+    }
+    return Array.from(keywords);
+}
+function pathMatchesScope(candidatePath, scopePath) {
+    const candidate = normalizeComparisonPath(candidatePath);
+    const scope = normalizeComparisonPath(scopePath);
+    if (!candidate || !scope) {
+        return false;
+    }
+    return candidate === scope
+        || candidate.endsWith(`/${scope}`)
+        || scope.endsWith(`/${candidate}`)
+        || candidate.startsWith(`${scope}/`)
+        || scope.startsWith(`${candidate}/`);
+}
+function extractProposalScopePaths(content) {
+    const seen = new Set();
+    const scopePaths = [];
+    const addScopePath = (raw) => {
+        const normalized = normalizeComparisonPath(raw.replace(/[`'"*[\]()]/g, '').trim());
+        if (!normalized || seen.has(normalized)) {
+            return;
+        }
+        seen.add(normalized);
+        scopePaths.push(normalized);
+    };
+    const filePattern = /(?:^|[\s`'"([\]|])([a-zA-Z0-9_\-./]+\.(?:ts|tsx|js|jsx|java|py|go|rs|md|json|yaml|yml|sql|kt|scala|c|cpp|cs|sh|xml|html|css|scss|vue|svelte))(?:[\s`'")\]|,]|$)/gm;
+    let match;
+    while ((match = filePattern.exec(content)) !== null) {
+        addScopePath(match[1]);
+    }
+    const lines = content.split('\n');
+    let inAffectedSection = false;
+    for (const line of lines) {
+        if (/影响范围|Affected code|Affected files|Impact/i.test(line) && line.startsWith('#')) {
+            inAffectedSection = true;
+            continue;
+        }
+        if (inAffectedSection && line.startsWith('#')) {
+            inAffectedSection = false;
+        }
+        if (inAffectedSection && line.trim().startsWith('-')) {
+            const bulletMatch = line.match(/-\s*(.+)/);
+            if (bulletMatch) {
+                addScopePath(bulletMatch[1]);
+            }
+        }
+    }
+    return scopePaths;
+}
+function buildChangedFileSearchText(repoPath, filePath) {
+    const relativePath = normalizeComparisonPath(path.relative(repoPath, filePath));
+    const parts = [normalizeComparisonPath(filePath), relativePath];
+    try {
+        const diffText = execSync(`git diff --no-color --unified=0 HEAD -- "${relativePath}"`, {
+            cwd: repoPath,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+        }).trim();
+        if (diffText) {
+            parts.push(diffText);
+        }
+    }
+    catch {
+        // Ignore diff read errors and fall back to current file content only.
+    }
+    try {
+        const fileContent = fs.readFileSync(filePath, 'utf-8');
+        if (fileContent.trim()) {
+            parts.push(fileContent);
+        }
+    }
+    catch {
+        // Skip unreadable files.
+    }
+    return parts.join('\n').toLowerCase();
+}
+async function getTouchedFilesForConsistencyAnalysis(workspaceRoot, changeDir) {
+    const cwd = process.cwd();
+    const currentRepo = GitRepoDetector.findParentGitRepo(cwd);
+    // Keep the original behavior first: if cwd is already inside a git repo,
+    // use that repo directly and do not change the matching logic.
+    if (currentRepo) {
+        return GitRepoDetector.getGitDiff(currentRepo).changedFiles.map((filePath) => ({
+            filePath,
+            searchText: buildChangedFileSearchText(currentRepo, filePath),
+        }));
+    }
+    // Fallback only when cwd itself cannot resolve git diff:
+    // use proposal scope to find the corresponding child repository below.
+    const proposalPath = path.join(changeDir, 'proposal.md');
+    let scopePaths = [];
+    try {
+        const proposalContent = await FileSystemUtils.readFile(proposalPath);
+        scopePaths = extractProposalScopePaths(proposalContent);
+    }
+    catch {
+        return [];
+    }
+    if (scopePaths.length === 0) {
+        return [];
+    }
+    const childRepos = GitRepoDetector.findChildGitRepos(workspaceRoot, 3);
+    const matchedResults = childRepos
+        .map((repoPath) => GitRepoDetector.getGitDiff(repoPath))
+        .filter((result) => result.changedFiles.length > 0)
+        .filter(({ repoPath, changedFiles }) => changedFiles.some((filePath) => {
+        const workspaceRelative = normalizeComparisonPath(path.relative(workspaceRoot, filePath));
+        const repoRelative = normalizeComparisonPath(path.relative(repoPath, filePath));
+        const repoName = normalizeComparisonPath(path.relative(workspaceRoot, repoPath));
+        return scopePaths.some((scopePath) => pathMatchesScope(workspaceRelative, scopePath)
+            || pathMatchesScope(repoRelative, scopePath)
+            || pathMatchesScope(repoName, scopePath));
+    }));
+    const candidates = [];
+    const seen = new Set();
+    for (const result of matchedResults) {
+        for (const filePath of result.changedFiles) {
+            if (seen.has(filePath)) {
+                continue;
+            }
+            seen.add(filePath);
+            candidates.push({
+                filePath,
+                searchText: buildChangedFileSearchText(result.repoPath, filePath),
+            });
+        }
+    }
+    return candidates;
+}
 /**
  * Run basic consistency analysis when spec-consistency-result.json is missing.
  * Reads specs/ under the change directory, extracts Requirements/Scenarios,
  * searches touched files for keyword matches, and writes a basic result.
  */
 async function runBasicConsistencyAnalysis(changeId) {
-    const cwd = process.cwd();
-    const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
+    const workspaceRoot = resolveZhuanSpecRoot();
+    const changeDir = path.join(workspaceRoot, 'zhuanspec', 'changes', changeId);
     const specsDir = path.join(changeDir, 'specs');
     // Check if specs directory exists
     if (!await FileSystemUtils.directoryExists(specsDir)) {
@@ -332,16 +489,38 @@ async function runBasicConsistencyAnalysis(changeId) {
             const lines = content.split('\n');
             let currentSection = '';
             let currentReq = null;
+            let currentScenario = null;
             let reqCounter = 0;
             let scenarioCounter = 0;
+            const flushScenario = () => {
+                if (!currentReq || !currentScenario) {
+                    return;
+                }
+                const bodyText = currentScenario.bodyLines.join(' ').trim();
+                currentReq.scenarios.push({
+                    id: currentScenario.id,
+                    description: currentScenario.description,
+                    matchText: bodyText
+                        ? `${currentScenario.description}\n${bodyText}`
+                        : currentScenario.description,
+                });
+                currentScenario = null;
+            };
             for (const line of lines) {
-                if (line.match(/^##\s+(ADDED|Added|\u65b0\u589e)/i))
+                if (line.match(/^##\s+(ADDED|Added|\u65b0\u589e)/i)) {
+                    flushScenario();
                     currentSection = 'ADDED';
-                else if (line.match(/^##\s+(MODIFIED|Modified|\u4fee\u6539)/i))
+                }
+                else if (line.match(/^##\s+(MODIFIED|Modified|\u4fee\u6539)/i)) {
+                    flushScenario();
                     currentSection = 'MODIFIED';
-                else if (line.match(/^##\s+(REMOVED|Removed|\u5220\u9664)/i))
+                }
+                else if (line.match(/^##\s+(REMOVED|Removed|\u5220\u9664)/i)) {
+                    flushScenario();
                     currentSection = 'REMOVED';
+                }
                 else if (line.match(/^###\s+(Requirement|\u9700\u6c42)[\uff1a:]/i)) {
+                    flushScenario();
                     const reqName = line.replace(/^###\s+(Requirement|\u9700\u6c42)[\uff1a:]\s+/i, '').trim();
                     if (currentSection === 'ADDED' || currentSection === 'MODIFIED') {
                         reqCounter++;
@@ -353,34 +532,26 @@ async function runBasicConsistencyAnalysis(changeId) {
                     }
                 }
                 else if (line.match(/^####\s+(Scenario|\u573a\u666f)[\uff1a:]/i) && currentReq) {
+                    flushScenario();
                     scenarioCounter++;
                     const scenarioDesc = line.replace(/^####\s+(Scenario|\u573a\u666f)[\uff1a:]\s+/i, '').trim();
-                    currentReq.scenarios.push({ id: `SC-${scenarioCounter}`, description: scenarioDesc });
+                    currentScenario = { id: `SC-${scenarioCounter}`, description: scenarioDesc, bodyLines: [] };
+                }
+                else if (currentScenario && !line.match(/^#{1,4}\s/)) {
+                    const trimmed = line.trim();
+                    if (trimmed) {
+                        currentScenario.bodyLines.push(trimmed);
+                    }
                 }
             }
+            flushScenario();
         }
         if (allRequirements.length === 0) {
             return null;
         }
-        // Get touched files from git
         let touchedFiles = [];
         try {
-            const { execSync } = await import('child_process');
-            const diffOutput = execSync('git diff --name-only HEAD', {
-                cwd,
-                encoding: 'utf-8',
-                stdio: ['pipe', 'pipe', 'ignore'],
-            });
-            touchedFiles = diffOutput.split('\n').map(f => f.trim()).filter(f => f.length > 0);
-            const statusOutput = execSync('git status --porcelain', {
-                cwd,
-                encoding: 'utf-8',
-                stdio: ['pipe', 'pipe', 'ignore'],
-            });
-            const statusFiles = statusOutput.split('\n')
-                .map(l => l.replace(/^\s*[A-Z?]+\s+/, '').trim())
-                .filter(f => f.length > 0);
-            touchedFiles = [...new Set([...touchedFiles, ...statusFiles])];
+            touchedFiles = await getTouchedFilesForConsistencyAnalysis(workspaceRoot, changeDir);
         }
         catch {
             // No git info available
@@ -393,34 +564,18 @@ async function runBasicConsistencyAnalysis(changeId) {
         for (const req of allRequirements) {
             const scenarios = req.scenarios.length > 0
                 ? req.scenarios
-                : [{ id: `${req.id}-implicit`, description: req.name }];
+                : [{ id: `${req.id}-implicit`, description: req.name, matchText: req.name }];
             for (const scenario of scenarios) {
                 totalScenarios++;
-                const keywords = scenario.description
-                    .toLowerCase()
-                    .split(/[\s\-_/\uff0c\u3001]+/)
-                    .filter(w => w.length > 3);
+                const keywords = buildScenarioKeywords(scenario.matchText);
                 let found = false;
                 let matchedFile = '';
                 for (const file of touchedFiles) {
-                    const fileLower = file.toLowerCase();
-                    if (keywords.some(kw => fileLower.includes(kw))) {
+                    if (keywords.some(kw => file.searchText.includes(kw))) {
                         found = true;
-                        matchedFile = file;
+                        matchedFile = file.filePath;
                         break;
                     }
-                    try {
-                        const fullPath = path.isAbsolute(file) ? file : path.join(cwd, file);
-                        const fileContent = await FileSystemUtils.readFile(fullPath);
-                        if (keywords.some(kw => fileContent.toLowerCase().includes(kw))) {
-                            found = true;
-                            matchedFile = file;
-                            break;
-                        }
-                    }
-                    catch {
-                        // Skip unreadable files
-                    }
                 }
                 if (found) {
                     coveredCount++;

package/dist/core/hooks/summarize.js

@@ -271,6 +271,37 @@ async function runSummarize() {
         ].join('\n');
         systemMessage += `\n⚠️ 检测到 ${n} 次用户纠偏未沉淀——请先运行 zhuanspec progress list-corrections ${changeId}，再用 askUserQuestion 三选项决策，用户选「全部/选择性沉淀」后必须调用 @skill:zhuanspec:knowledge 而非自行 Write。\n`;
     }
+    // === 对话经验自动沉淀：检测 resolutionSignal，注入精炼提示 ===
+    // 触发条件：apply 阶段 + user_inputs.json 有 resolutionSignal.detected=true + 未问过
+    let resolutionAdditionalContext;
+    if (phase === 'apply' && progressData?.askedResolutionSaved !== true) {
+        try {
+            const userInputPath = path.join(metricsDir, 'user_inputs.json');
+            if (await FileSystemUtils.fileExists(userInputPath)) {
+                const raw = JSON.parse(await FileSystemUtils.readFile(userInputPath));
+                const resolved = (raw.inputs ?? []).filter((i) => i.resolutionSignal?.detected === true);
+                if (resolved.length > 0) {
+                    // 汇总命中关键词和上下文片段，供精炼 prompt 参考
+                    const allKeywords = [...new Set(resolved.flatMap((i) => i.resolutionSignal?.matchedKeywords ?? []))];
+                    const snippets = resolved
+                        .map((i) => i.resolutionSignal?.context ?? '')
+                        .filter(Boolean)
+                        .slice(0, 3) // 最多取 3 条上下文
+                        .join('\n---\n');
+                    resolutionAdditionalContext = buildResolutionExtractionPrompt(changeId, allKeywords, snippets);
+                    // 写回 progress.json 防止重复触发
+                    if (await FileSystemUtils.fileExists(progressPath)) {
+                        const full = JSON.parse(await FileSystemUtils.readFile(progressPath));
+                        full.askedResolutionSaved = true;
+                        await atomicWriteJson(progressPath, full);
+                    }
+                }
+            }
+        }
+        catch {
+            // 读取失败不阻断主流程
+        }
+    }
     // === Task 0 路径 1：Stop 时按核心产出齐备度自动打 phase baseline ===
     // 幂等：已打标则跳过；先到先得（auto-file-complete 优于 auto-stop）
     try {
@@ -295,12 +326,16 @@ async function runSummarize() {
     catch {
         // baseline 打标失败不阻断 summarize 主流程
     }
+    // 合并纠偏沉淀提示和对话经验提示（两者都有时换行分隔）
+    const mergedAdditionalContext = [pitfallAdditionalContext, resolutionAdditionalContext]
+        .filter(Boolean)
+        .join('\n\n---\n\n') || undefined;
     return {
         continue: true,
         systemMessage,
         hookSpecificOutput: {
             hookEventName: 'Stop',
-            additionalContext: pitfallAdditionalContext,
+            additionalContext: mergedAdditionalContext,
             waveCompleted: currentWave?.waveId,
             nextTask,
             allTasksComplete,
@@ -432,4 +467,61 @@ async function isPhaseOutputsComplete(phase, changeDir, allTasksComplete) {
     }
     return false;
 }
+/**
+ * 生成对话经验精炼提示，注入主 agent 上下文。
+ * 不弹 askUserQuestion——直接给 LLM 提取指令，由 LLM 自判断值不值得沉淀。
+ */
+function buildResolutionExtractionPrompt(changeId, keywords, contextSnippets) {
+    return [
+        '## 🔍 对话经验自动沉淀（Stop hook 触发）',
+        '',
+        `检测到本次会话（change: \`${changeId}\`）中存在"问题已解决/找到根因"信号。`,
+        keywords.length > 0 ? `命中关键词：${keywords.map((k) => `\`${k}\``).join('、')}` : '',
+        '',
+        '**请从本次完整对话历史中提取隐性知识，按以下步骤执行（不可跳步）：**',
+        '',
+        '### Step 1：判断是否值得沉淀',
+        '- ✅ **值得**：非显而易见的 bug、有迷惑性的报错、排查路径有参考价值、跨次复现的隐式约定',
+        '- ❌ **不值得**：拼写错误、本地配置笔误、偶发网络问题、已有知识库覆盖的内容',
+        '- 若不值得，直接输出「本次问题不适合沉淀（原因：xxx）」，**不写任何文件，流程结束**。',
+        '',
+        '### Step 2：若值得，调用 @skill:zhuanspec:knowledge（模式 B）写入以下格式',
+        '',
+        '目标目录：`zhuanspec/knowledge/troubleshooting/`',
+        '',
+        '```yaml',
+        '---',
+        'id: ts-{YYYYMMDD}-{2-3词摘要}       # 如 ts-20260602-yaml-parse-null',
+        'category: troubleshooting',
+        'title: {一句话描述问题现象}',
+        'trigger:',
+        '  keywords: [关键报错词, 涉及模块, 操作动作]',
+        '  paths: ["**/涉及路径/**"]         # 可选',
+        'severity: high | medium | low       # 按复现难度和影响范围',
+        'confidence: 0.7~1.0                 # 自评把握度',
+        `source_change: ${changeId}`,
+        'status: active',
+        '---',
+        '',
+        '## 适用场景',
+        '遇到 {具体症状描述} 时。',
+        '',
+        '## 根因',
+        '{一句话说清根本原因，不带背景叙事}',
+        '',
+        '## 排查路径',
+        '1. {第一步排查动作} → {结论}',
+        '2. {第二步} → {结论}',
+        '',
+        '## 解法',
+        '{可直接复制使用的最终解法}',
+        '```',
+        '',
+        '### 红线',
+        '- 禁止绕过 skill 直接 Write/Edit 知识文件。',
+        '- 禁止在没有明确根因的情况下强行沉淀。',
+        '- 知识库已有同 id 条目时，追加 source_change，不新建文件。',
+        ...(contextSnippets ? ['', '### 参考上下文片段（来自本次对话检测到解决信号的 prompt）', '```', contextSnippets, '```'] : []),
+    ].filter((l) => l !== undefined).join('\n');
+}
 //# sourceMappingURL=summarize.js.map

package/dist/core/hooks/user-input-hook.d.ts

@@ -27,6 +27,17 @@ export interface CorrectionSignal {
     matchedKeywords: string[];
     isRequirementChange?: boolean;
 }
+/**
+ * 对话经验解决信号：检测用户在对话中表达"问题已解决/找到根因"的语义。
+ * 用于 Stop hook 触发对话经验自动沉淀流程。
+ */
+export interface ResolutionSignal {
+    detected: boolean;
+    /** 命中的关键词（最多 4 个，用于 Stop hook 判断置信度） */
+    matchedKeywords: string[];
+    /** 截断的关键上下文（<=300 字），供 Stop hook 注入精炼 prompt 时参考 */
+    context: string;
+}
 /**
  * 用户对四选一的最终选择。由 `zhuanspec progress resolve-correction` 回写。
  */
@@ -49,6 +60,7 @@ interface UserInputOutput {
         options?: string[];
     };
 }
+export declare function buildResolutionSignal(content: string): ResolutionSignal;
 /**
  * Main hook function - records user input
  */