speccore 6.6.0 → 6.10.0

package/dist/core/global-knowledge.d.ts

@@ -0,0 +1,25 @@
+/**
+ * global-knowledge — 全局知识沉淀引擎
+ *
+ * 设计哲学：不追求完美文档，追求"能检索到"
+ *
+ * 工作流程：
+ *   1. sync-global 完成后，扫描迭代所有 specs 文档
+ *   2. 为全局层构建 RAG 索引（聚合所有迭代的技术内容）
+ *   3. 生成轻量级 GLOBAL/SUMMARY.md（AI 概览，可手动修改）
+ *   4. 刷新知识图谱
+ *
+ * 输出：
+ *   .speccore/GLOBAL/SUMMARY.md          ← 全局概览（轻量，可手动改）
+ *   .speccore/cache/rag-index.json       ← 全局 RAG 索引（聚合所有迭代）
+ */
+export interface GlobalKnowledgeOptions {
+    iteration?: string;
+    cwd?: string;
+}
+/**
+ * 全局知识沉淀主入口
+ * sync-global 完成后调用
+ */
+export declare function syncGlobalKnowledge(options?: GlobalKnowledgeOptions): Promise<void>;
+//# sourceMappingURL=global-knowledge.d.ts.map

package/dist/core/global-knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-knowledge.d.ts","sourceRoot":"","sources":["../../src/core/global-knowledge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,MAAM,WAAW,sBAAsB;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CA8E7F"}

package/dist/core/global-knowledge.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * global-knowledge — 全局知识沉淀引擎
+ *
+ * 设计哲学：不追求完美文档，追求"能检索到"
+ *
+ * 工作流程：
+ *   1. sync-global 完成后，扫描迭代所有 specs 文档
+ *   2. 为全局层构建 RAG 索引（聚合所有迭代的技术内容）
+ *   3. 生成轻量级 GLOBAL/SUMMARY.md（AI 概览，可手动修改）
+ *   4. 刷新知识图谱
+ *
+ * 输出：
+ *   .speccore/GLOBAL/SUMMARY.md          ← 全局概览（轻量，可手动改）
+ *   .speccore/cache/rag-index.json       ← 全局 RAG 索引（聚合所有迭代）
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncGlobalKnowledge = syncGlobalKnowledge;
+const fs_extra_1 = require("fs-extra");
+const path_1 = require("path");
+const logger_1 = require("../utils/logger");
+const rag_engine_1 = require("./rag-engine");
+const knowledge_graph_1 = require("./knowledge-graph");
+/**
+ * 全局知识沉淀主入口
+ * sync-global 完成后调用
+ */
+async function syncGlobalKnowledge(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const iteration = options.iteration;
+    logger_1.logger.info('');
+    logger_1.logger.info('🌐 全局知识沉淀...');
+    // ── 1. 收集所有迭代的 specs 文档 ──
+    const specsDirs = [];
+    // 1.1 如果指定了迭代，优先扫描该迭代
+    if (iteration) {
+        const iterSpecsDir = (0, path_1.join)(cwd, `Iteration-${iteration}`, '020-specs');
+        if (await (0, fs_extra_1.pathExists)(iterSpecsDir)) {
+            specsDirs.push(iterSpecsDir);
+        }
+        // 扫描该迭代的所有任务目录
+        const tasksDir = (0, path_1.join)(cwd, `Iteration-${iteration}`, '030-tasks');
+        if (await (0, fs_extra_1.pathExists)(tasksDir)) {
+            const tasks = await (0, fs_extra_1.readdir)(tasksDir, { withFileTypes: true });
+            for (const t of tasks) {
+                if (t.isDirectory() && t.name.startsWith('Task-')) {
+                    const taskSpecsDir = (0, path_1.join)(tasksDir, t.name, '00-specs');
+                    const taskSharedDir = (0, path_1.join)(tasksDir, t.name, '_shared');
+                    if (await (0, fs_extra_1.pathExists)(taskSpecsDir))
+                        specsDirs.push(taskSpecsDir);
+                    if (await (0, fs_extra_1.pathExists)(taskSharedDir))
+                        specsDirs.push(taskSharedDir);
+                }
+            }
+        }
+    }
+    // 1.2 同时扫描全局层的现有 specs
+    const globalSpecsDir = (0, path_1.join)(cwd, '.speccore', 'GLOBAL', '020-specs');
+    if (await (0, fs_extra_1.pathExists)(globalSpecsDir)) {
+        specsDirs.push(globalSpecsDir);
+    }
+    if (specsDirs.length === 0) {
+        logger_1.logger.info('   ⚠️ 未找到 specs 文档，跳过全局知识沉淀');
+        return;
+    }
+    // ── 2. 为每个 specs 目录构建/更新 RAG 索引 ──
+    // 全局 RAG 索引：聚合所有迭代的 specs（使用独立文件名，避免覆盖任务级索引）
+    const globalScope = iteration
+        ? `GLOBAL_all_${iteration}_aggregated`
+        : 'GLOBAL_all_all_aggregated';
+    // 收集所有要索引的文件
+    const allFiles = [];
+    for (const dir of specsDirs) {
+        await collectMdFiles(dir, allFiles);
+    }
+    if (allFiles.length === 0) {
+        logger_1.logger.info('   ⚠️ 未收集到有效文档，跳过');
+        return;
+    }
+    // 用通用函数建全局 RAG 索引（保存到独立文件）
+    const index = await (0, rag_engine_1.buildRagIndex)(allFiles, globalScope);
+    await (0, rag_engine_1.saveRagIndex)(cwd, index, 'rag-index-global.json');
+    logger_1.logger.info(`   ✅ 全局 RAG 索引已更新: ${allFiles.length} 个文件, ${index.chunks.length} 个块 → rag-index-global.json`);
+    // ── 3. 生成/更新 GLOBAL/SUMMARY.md ──
+    await generateGlobalSummary(cwd, allFiles, iteration);
+    // ── 4. 刷新知识图谱 ──
+    try {
+        await (0, knowledge_graph_1.refreshKnowledgeGraph)(cwd, iteration || undefined);
+        logger_1.logger.info('   ✅ 知识图谱已刷新');
+    }
+    catch {
+        logger_1.logger.debug('知识图谱刷新失败（非关键）');
+    }
+    logger_1.logger.info('   🌐 全局知识沉淀完成');
+}
+/**
+ * 递归收集目录下的 .md 文件
+ */
+async function collectMdFiles(dir, result) {
+    if (!(await (0, fs_extra_1.pathExists)(dir)))
+        return;
+    const items = await (0, fs_extra_1.readdir)(dir, { withFileTypes: true });
+    for (const item of items) {
+        const fullPath = (0, path_1.join)(dir, item.name);
+        if (item.isDirectory() && !item.name.startsWith('.') && item.name !== 'node_modules') {
+            await collectMdFiles(fullPath, result);
+        }
+        else if (item.isFile() && item.name.endsWith('.md') && !item.name.startsWith('README')) {
+            const [content, st] = await Promise.all([
+                (0, fs_extra_1.readFile)(fullPath, 'utf-8'),
+                (0, fs_extra_1.stat)(fullPath),
+            ]);
+            if (content.trim().length > 50) {
+                result.push({ filePath: fullPath, content, mtime: st.mtimeMs });
+            }
+        }
+    }
+}
+/**
+ * 生成轻量级 GLOBAL/SUMMARY.md
+ *
+ * 不追求完美，只是聚合信息 + 提供导航。
+ * 内容：已交付功能清单、技术方案概览、API 清单、已知问题。
+ */
+async function generateGlobalSummary(cwd, files, iteration) {
+    const summaryPath = (0, path_1.join)(cwd, '.speccore', 'GLOBAL', 'SUMMARY.md');
+    await (0, fs_extra_1.ensureDir)((0, path_1.join)(cwd, '.speccore', 'GLOBAL'));
+    // 从文件内容中提取结构化信息
+    const features = [];
+    const techDecisions = [];
+    const apis = [];
+    const issues = [];
+    for (const { filePath, content } of files) {
+        const fileName = filePath.split('/').pop() || '';
+        // 提取功能点（REQ.md / REQUIREMENT.md 中的 ### 标题）
+        if (fileName.includes('REQ') || fileName.includes('REQUIREMENT')) {
+            const matches = content.matchAll(/^#{2,3}\s+(.+)$/gm);
+            for (const m of matches) {
+                const title = m[1].trim();
+                if (title && !title.match(/^(需求|概述|目录|前言|背景)/)) {
+                    features.push(title);
+                }
+            }
+        }
+        // 提取技术方案（TECH.md 中的 ### 标题）
+        if (fileName.includes('TECH')) {
+            const matches = content.matchAll(/^#{2,3}\s+(.+)$/gm);
+            for (const m of matches) {
+                const title = m[1].trim();
+                if (title && !title.match(/^(技术|概述|目录)/)) {
+                    techDecisions.push(title);
+                }
+            }
+        }
+        // 提取 API（表格中的 GET/POST/PUT/DELETE）
+        const apiMatches = content.matchAll(/\|\s*(GET|POST|PUT|DELETE|PATCH)\s*\|\s*(\/[^\s|]+)/gi);
+        for (const m of apiMatches) {
+            apis.push(`${m[1].toUpperCase()} ${m[2]}`);
+        }
+        // 提取已知问题（.issues.md 或 RISK.md）
+        if (fileName.includes('issue') || fileName.includes('RISK')) {
+            const issueMatches = content.matchAll(/^[-*]\s+(.+)$/gm);
+            for (const m of issueMatches) {
+                issues.push(m[1].trim());
+            }
+        }
+    }
+    // 去重
+    const uniqueFeatures = [...new Set(features)].slice(0, 30);
+    const uniqueTech = [...new Set(techDecisions)].slice(0, 20);
+    const uniqueApis = [...new Set(apis)].slice(0, 30);
+    const uniqueIssues = [...new Set(issues)].slice(0, 10);
+    const now = new Date().toLocaleString('zh-CN');
+    const iterInfo = iteration ? `（基于 Iteration-${iteration}）` : '';
+    const summary = `# 全局技术概览 ${iterInfo}
+
+> 📌 本文件由 \_speccore sync-global\_ 自动生成，**可手动编辑**。不完美没关系，大方向对就行。
+> 
+> 🔄 最后更新: ${now}
+
+---
+
+## 已交付功能
+
+${uniqueFeatures.length > 0
+        ? uniqueFeatures.map(f => `- ${f}`).join('\n')
+        : '_暂无功能记录_'}
+
+## 技术方案要点
+
+${uniqueTech.length > 0
+        ? uniqueTech.map(t => `- ${t}`).join('\n')
+        : '_暂无技术方案_'}
+
+## API 清单
+
+${uniqueApis.length > 0
+        ? '| 方法 | 路径 |\n| :--- | :--- |\n' + uniqueApis.map(a => {
+            const parts = a.split(' ');
+            return `| ${parts[0]} | ${parts[1] || ''} |`;
+        }).join('\n')
+        : '_暂无 API 记录_'}
+
+## 已知问题 / 风险
+
+${uniqueIssues.length > 0
+        ? uniqueIssues.map(i => `- ${i}`).join('\n')
+        : '_暂无记录_'}
+
+---
+
+## 文档索引
+
+${files.length > 0
+        ? files.map(f => {
+            const relPath = f.filePath.replace(cwd + '/', '');
+            return `- [${relPath.split('/').pop()}](${relPath})`;
+        }).join('\n')
+        : '_暂无文档_'}
+
+---
+
+*💡 提示: 运行 \`speccore refresh\` 刷新检索层，运行 \`speccore rag-index\` 查看索引状态。*
+`;
+    await (0, fs_extra_1.writeFile)(summaryPath, summary);
+    logger_1.logger.info(`   ✅ 全局概览已生成: .speccore/GLOBAL/SUMMARY.md`);
+}
+//# sourceMappingURL=global-knowledge.js.map

package/dist/core/global-knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-knowledge.js","sourceRoot":"","sources":["../../src/core/global-knowledge.ts"],"names":[],"mappings":"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"}

package/dist/core/index-guard.d.ts

@@ -0,0 +1,57 @@
+/**
+ * index-guard — 统一命令前索引新鲜度门禁
+ *
+ * 在 analyze / split / execute / change 等命令执行前，
+ * 检查所有索引层（RAG / 代码 / 知识图谱）是否过期，
+ * 返回标准化的变更摘要供 AI 展示给用户确认。
+ *
+ * 设计目标：
+ *   - 一个入口函数 ensureIndexFresh() 覆盖所有命令
+ *   - 输出标准化格式，AI 可直接展示
+ *   - 非阻塞：只 warn 不阻止执行，但明确提示需要刷新
+ */
+export interface IndexFreshnessResult {
+    /** 是否全部新鲜 */
+    allFresh: boolean;
+    /** 各层状态 */
+    layers: {
+        rag: LayerStatus;
+        code: LayerStatus;
+        graph: LayerStatus;
+    };
+    /** 标准化变更摘要（可直接展示给用户） */
+    summary: string;
+    /** 建议的刷新命令 */
+    suggestedCommand: string;
+}
+export interface LayerStatus {
+    /** 层名称 */
+    name: string;
+    /** 是否新鲜 */
+    fresh: boolean;
+    /** 变更文件数 */
+    changedCount: number;
+    /** 变更文件列表（最多显示 5 个） */
+    changedFiles: string[];
+    /** 人可读的描述 */
+    message: string;
+}
+/**
+ * 统一检查所有索引层的新鲜度
+ *
+ * 在 analyze / split / execute / change 命令入口调用。
+ * 返回标准化结果，调用方决定如何展示。
+ *
+ * @param cwd         工作目录
+ * @param command     当前执行的命令名（用于生成建议）
+ * @param iteration   迭代名（可选，自动推断）
+ */
+export declare function ensureIndexFresh(cwd: string, command: string, iteration?: string): Promise<IndexFreshnessResult>;
+/**
+ * 在命令入口输出新鲜度检查（非阻塞，只 warn）
+ *
+ * 用法：
+ *   await warnIfIndexStale(cwd, 'analyze');
+ */
+export declare function warnIfIndexStale(cwd: string, command: string, iteration?: string): Promise<IndexFreshnessResult>;
+//# sourceMappingURL=index-guard.d.ts.map

package/dist/core/index-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-guard.d.ts","sourceRoot":"","sources":["../../src/core/index-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH,MAAM,WAAW,oBAAoB;IACnC,aAAa;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW;IACX,MAAM,EAAE;QACN,GAAG,EAAE,WAAW,CAAC;QACjB,IAAI,EAAE,WAAW,CAAC;QAClB,KAAK,EAAE,WAAW,CAAC;KACpB,CAAC;IACF,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc;IACd,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU;IACV,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,KAAK,EAAE,OAAO,CAAC;IACf,YAAY;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,uBAAuB;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,oBAAoB,CAAC,CAoB/B;AAwJD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,oBAAoB,CAAC,CAM/B"}

package/dist/core/index-guard.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * index-guard — 统一命令前索引新鲜度门禁
+ *
+ * 在 analyze / split / execute / change 等命令执行前，
+ * 检查所有索引层（RAG / 代码 / 知识图谱）是否过期，
+ * 返回标准化的变更摘要供 AI 展示给用户确认。
+ *
+ * 设计目标：
+ *   - 一个入口函数 ensureIndexFresh() 覆盖所有命令
+ *   - 输出标准化格式，AI 可直接展示
+ *   - 非阻塞：只 warn 不阻止执行，但明确提示需要刷新
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureIndexFresh = ensureIndexFresh;
+exports.warnIfIndexStale = warnIfIndexStale;
+const logger_1 = require("../utils/logger");
+const rag_engine_1 = require("./rag-engine");
+const code_scanner_1 = require("./code-scanner");
+const knowledge_graph_1 = require("./knowledge-graph");
+const context_1 = require("./context");
+// ═══════════════════════════════════════════════════════════
+// 核心函数
+// ═══════════════════════════════════════════════════════════
+/**
+ * 统一检查所有索引层的新鲜度
+ *
+ * 在 analyze / split / execute / change 命令入口调用。
+ * 返回标准化结果，调用方决定如何展示。
+ *
+ * @param cwd         工作目录
+ * @param command     当前执行的命令名（用于生成建议）
+ * @param iteration   迭代名（可选，自动推断）
+ */
+async function ensureIndexFresh(cwd, command, iteration) {
+    const iterName = iteration || await (0, context_1.getDefaultIteration)(cwd);
+    // ── 并行检查三层 ──
+    const [ragStatus, codeStatus, graphStatus] = await Promise.all([
+        checkRagLayer(cwd, iterName),
+        checkCodeLayer(),
+        checkGraphLayer(cwd, iterName),
+    ]);
+    const allFresh = ragStatus.fresh && codeStatus.fresh && graphStatus.fresh;
+    const summary = formatChangeSummary(ragStatus, codeStatus, graphStatus, command);
+    const suggestedCommand = `speccore refresh`;
+    return {
+        allFresh,
+        layers: { rag: ragStatus, code: codeStatus, graph: graphStatus },
+        summary,
+        suggestedCommand,
+    };
+}
+// ═══════════════════════════════════════════════════════════
+// 各层检查
+// ═══════════════════════════════════════════════════════════
+async function checkRagLayer(cwd, iteration) {
+    try {
+        // 尝试加载 iteration 级索引
+        const ragFileName = iteration ? `rag-index-${iteration}.json` : undefined;
+        const index = await (0, rag_engine_1.loadRagIndex)(cwd, ragFileName);
+        if (!index) {
+            return {
+                name: '文档 RAG',
+                fresh: true, // 不存在不算过期，只是未建立
+                changedCount: 0,
+                changedFiles: [],
+                message: '未建立索引',
+            };
+        }
+        const { fresh, staleFiles, newFiles } = await (0, rag_engine_1.checkRagIndexFreshness)(cwd, ragFileName);
+        const changed = [...staleFiles, ...newFiles];
+        return {
+            name: '文档 RAG',
+            fresh,
+            changedCount: changed.length,
+            changedFiles: changed.slice(0, 5).map(f => f.replace(cwd + '/', '')),
+            message: fresh
+                ? '文档索引已同步'
+                : `${staleFiles.length} 个文件已变更，${newFiles.length} 个新文件待索引`,
+        };
+    }
+    catch {
+        return {
+            name: '文档 RAG',
+            fresh: true,
+            changedCount: 0,
+            changedFiles: [],
+            message: '检查失败（跳过）',
+        };
+    }
+}
+async function checkCodeLayer() {
+    try {
+        const freshness = await (0, code_scanner_1.checkCodeIndexFreshness)();
+        const staleFiles = freshness.staleFiles || [];
+        return {
+            name: '代码索引',
+            fresh: freshness.fresh,
+            changedCount: staleFiles.length,
+            changedFiles: staleFiles.slice(0, 5),
+            message: freshness.fresh
+                ? '代码索引已同步'
+                : freshness.message || `${staleFiles.length} 个文件已变更`,
+        };
+    }
+    catch {
+        return {
+            name: '代码索引',
+            fresh: true,
+            changedCount: 0,
+            changedFiles: [],
+            message: '检查失败（跳过）',
+        };
+    }
+}
+async function checkGraphLayer(cwd, iteration) {
+    try {
+        const stale = await (0, knowledge_graph_1.isGraphStale)(cwd, iteration);
+        const graph = await (0, knowledge_graph_1.loadKnowledgeGraph)(cwd);
+        const entityCount = graph ? graph.entities.length : 0;
+        return {
+            name: '知识图谱',
+            fresh: !stale,
+            changedCount: stale ? 1 : 0,
+            changedFiles: stale ? ['需求/规格/任务目录有变更'] : [],
+            message: stale
+                ? `知识图谱已过期（${entityCount} 个实体待更新）`
+                : `知识图谱已同步（${entityCount} 个实体）`,
+        };
+    }
+    catch {
+        return {
+            name: '知识图谱',
+            fresh: true,
+            changedCount: 0,
+            changedFiles: [],
+            message: '检查失败（跳过）',
+        };
+    }
+}
+// ═══════════════════════════════════════════════════════════
+// 变更摘要格式化
+// ═══════════════════════════════════════════════════════════
+/**
+ * 格式化标准化变更摘要
+ *
+ * 输出格式：
+ * ```
+ * 📋 索引状态检查（执行 {command} 前）
+ * ├── ✅ 文档 RAG：已同步
+ * ├── ⚠️  代码索引：3 个文件已变更
+ * │   ├── src/commands/analyze.ts
+ * │   ├── src/core/rag-engine.ts
+ * │   └── src/core/prompt-builder.ts
+ * └── ⚠️  知识图谱：已过期（12 个实体待更新）
+ *
+ * 💡 建议执行 `speccore refresh` 更新索引
+ * ```
+ */
+function formatChangeSummary(rag, code, graph, command) {
+    const layers = [rag, code, graph];
+    const hasChanges = layers.some(l => !l.fresh);
+    if (!hasChanges) {
+        return `📋 索引状态检查（${command}）：全部已同步 ✅`;
+    }
+    const lines = [];
+    lines.push(`📋 索引状态检查（${command} 前）`);
+    for (let i = 0; i < layers.length; i++) {
+        const layer = layers[i];
+        const connector = i === layers.length - 1 ? '└──' : '├──';
+        const icon = layer.fresh ? '✅' : '⚠️ ';
+        lines.push(`${connector} ${icon} ${layer.name}：${layer.message}`);
+        // 显示变更文件列表（最多 3 个）
+        if (!layer.fresh && layer.changedFiles.length > 0) {
+            const subConnector = i === layers.length - 1 ? '   ' : '│  ';
+            const files = layer.changedFiles.slice(0, 3);
+            for (const file of files) {
+                lines.push(`${subConnector}   • ${file}`);
+            }
+            if (layer.changedFiles.length > 3) {
+                lines.push(`${subConnector}   ... 还有 ${layer.changedFiles.length - 3} 个文件`);
+            }
+        }
+    }
+    lines.push('');
+    lines.push('💡 建议执行 `speccore refresh` 更新索引');
+    return lines.join('\n');
+}
+/**
+ * 在命令入口输出新鲜度检查（非阻塞，只 warn）
+ *
+ * 用法：
+ *   await warnIfIndexStale(cwd, 'analyze');
+ */
+async function warnIfIndexStale(cwd, command, iteration) {
+    const result = await ensureIndexFresh(cwd, command, iteration);
+    if (!result.allFresh) {
+        logger_1.logger.warn(result.summary);
+    }
+    return result;
+}
+//# sourceMappingURL=index-guard.js.map

package/dist/core/index-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-guard.js","sourceRoot":"","sources":["../../src/core/index-guard.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AAsDH,4CAwBC;AA8JD,4CAUC;AApPD,4CAAyC;AACzC,6CAAoE;AACpE,iDAAwE;AACxE,uDAAqE;AACrE,uCAAgD;AAkChD,8DAA8D;AAC9D,OAAO;AACP,8DAA8D;AAE9D;;;;;;;;;GASG;AACI,KAAK,UAAU,gBAAgB,CACpC,GAAW,EACX,OAAe,EACf,SAAkB;IAElB,MAAM,QAAQ,GAAG,SAAS,IAAI,MAAM,IAAA,6BAAmB,EAAC,GAAG,CAAC,CAAC;IAE7D,eAAe;IACf,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC7D,aAAa,CAAC,GAAG,EAAE,QAAQ,CAAC;QAC5B,cAAc,EAAE;QAChB,eAAe,CAAC,GAAG,EAAE,QAAQ,CAAC;KAC/B,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,IAAI,WAAW,CAAC,KAAK,CAAC;IAC1E,MAAM,OAAO,GAAG,mBAAmB,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IACjF,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;IAE5C,OAAO;QACL,QAAQ;QACR,MAAM,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE;QAChE,OAAO;QACP,gBAAgB;KACjB,CAAC;AACJ,CAAC;AAED,8DAA8D;AAC9D,OAAO;AACP,8DAA8D;AAE9D,KAAK,UAAU,aAAa,CAAC,GAAW,EAAE,SAAkB;IAC1D,IAAI,CAAC;QACH,qBAAqB;QACrB,MAAM,WAAW,GAAG,SAAS,CAAC,CAAC,CAAC,aAAa,SAAS,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1E,MAAM,KAAK,GAAG,MAAM,IAAA,yBAAY,EAAC,GAAG,EAAE,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO;gBACL,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,IAAI,EAAE,gBAAgB;gBAC7B,YAAY,EAAE,CAAC;gBACf,YAAY,EAAE,EAAE;gBAChB,OAAO,EAAE,OAAO;aACjB,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,MAAM,IAAA,mCAAsB,EAAC,GAAG,EAAE,WAAW,CAAC,CAAC;QACvF,MAAM,OAAO,GAAG,CAAC,GAAG,UAAU,EAAE,GAAG,QAAQ,CAAC,CAAC;QAC7C,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,KAAK;YACL,YAAY,EAAE,OAAO,CAAC,MAAM;YAC5B,YAAY,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,GAAG,GAAG,EAAE,EAAE,CAAC,CAAC;YACpE,OAAO,EAAE,KAAK;gBACZ,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,WAAW,QAAQ,CAAC,MAAM,UAAU;SAC7D,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,IAAI;YACX,YAAY,EAAE,CAAC;YACf,YAAY,EAAE,EAAE;YAChB,OAAO,EAAE,UAAU;SACpB,CAAC;IACJ,CAAC;AACH,CAAC;AAED,KAAK,UAAU,cAAc;IAC3B,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,IAAA,sCAAuB,GAAE,CAAC;QAClD,MAAM,UAAU,GAAG,SAAS,CAAC,UAAU,IAAI,EAAE,CAAC;QAC9C,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,SAAS,CAAC,KAAK;YACtB,YAAY,EAAE,UAAU,CAAC,MAAM;YAC/B,YAAY,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;YACpC,OAAO,EAAE,SAAS,CAAC,KAAK;gBACtB,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,SAAS,CAAC,OAAO,IAAI,GAAG,UAAU,CAAC,MAAM,SAAS;SACvD,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,IAAI;YACX,YAAY,EAAE,CAAC;YACf,YAAY,EAAE,EAAE;YAChB,OAAO,EAAE,UAAU;SACpB,CAAC;IACJ,CAAC;AACH,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,GAAW,EAAE,SAAkB;IAC5D,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,IAAA,8BAAY,EAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACjD,MAAM,KAAK,GAAG,MAAM,IAAA,oCAAkB,EAAC,GAAG,CAAC,CAAC;QAC5C,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACtD,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,CAAC,KAAK;YACb,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3B,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE;YAC5C,OAAO,EAAE,KAAK;gBACZ,CAAC,CAAC,WAAW,WAAW,UAAU;gBAClC,CAAC,CAAC,WAAW,WAAW,OAAO;SAClC,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,IAAI;YACX,YAAY,EAAE,CAAC;YACf,YAAY,EAAE,EAAE;YAChB,OAAO,EAAE,UAAU;SACpB,CAAC;IACJ,CAAC;AACH,CAAC;AAED,8DAA8D;AAC9D,UAAU;AACV,8DAA8D;AAE9D;;;;;;;;;;;;;;;GAeG;AACH,SAAS,mBAAmB,CAC1B,GAAgB,EAChB,IAAiB,EACjB,KAAkB,EAClB,OAAe;IAEf,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAClC,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAE9C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,aAAa,OAAO,WAAW,CAAC;IACzC,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,aAAa,OAAO,KAAK,CAAC,CAAC;IAEtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,SAAS,GAAG,CAAC,KAAK,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;QAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,GAAG,SAAS,IAAI,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAElE,mBAAmB;QACnB,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClD,MAAM,YAAY,GAAG,CAAC,KAAK,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;YAC7D,MAAM,KAAK,GAAG,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAC7C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,KAAK,CAAC,IAAI,CAAC,GAAG,YAAY,QAAQ,IAAI,EAAE,CAAC,CAAC;YAC5C,CAAC;YACD,IAAI,KAAK,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAClC,KAAK,CAAC,IAAI,CAAC,GAAG,YAAY,aAAa,KAAK,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC;YAC9E,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;IAE9C,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,gBAAgB,CACpC,GAAW,EACX,OAAe,EACf,SAAkB;IAElB,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IAC/D,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrB,eAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core/intent-cache.d.ts

@@ -11,6 +11,8 @@ import type { AskResult } from './ask-engine';
 export interface CachedIntent {
     /** 缓存的输入文本 */
     input: string;
+    /** 归一化后的输入（用于语义级缓存命中） */
+    normalizedInput: string;
     /** 匹配的 AskResult */
     result: AskResult;
     /** 来源：local / host-ai / llm */
@@ -29,7 +31,7 @@ export interface IntentCache {
     solidified: string[];
 }
 /**
- * 查询缓存：先精确匹配，再模糊匹配
+ * 查询缓存：精确 → 归一化语义 → 编辑距离模糊
  */
 export declare function getCachedIntent(input: string): Promise<AskResult | null>;
 /**

package/dist/core/intent-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intent-cache.d.ts","sourceRoot":"","sources":["../../src/core/intent-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAM9C,MAAM,WAAW,YAAY;IAC3B,cAAc;IACd,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,MAAM,EAAE,SAAS,CAAC;IAClB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACtC,+BAA+B;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AA8CD;;GAEG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CA+B9E;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAE,MAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB7G;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAGrF;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMjE;AAED;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CASrG"}
+{"version":3,"file":"intent-cache.d.ts","sourceRoot":"","sources":["../../src/core/intent-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAM9C,MAAM,WAAW,YAAY;IAC3B,cAAc;IACd,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,oBAAoB;IACpB,MAAM,EAAE,SAAS,CAAC;IAClB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACtC,+BAA+B;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAgED;;GAEG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CA6C9E;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAE,MAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB7G;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAGrF;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMjE;AAED;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CASrG"}

package/dist/core/intent-cache.js

@@ -20,9 +20,25 @@ const logger_1 = require("../utils/logger");
 // 常量
 // ═══════════════════════════════════════════════════════════
 const CACHE_PATH = '.speccore/local/intent-cache.json';
-const CACHE_VERSION = '1.0';
+const CACHE_VERSION = '1.1'; // 升级到 1.1 支持 normalizedInput
 const MAX_ENTRIES = 200;
 const FUZZY_THRESHOLD = 2; // 编辑距离阈值
+/** 停用词表 */
+const NORMALIZE_STOP_WORDS = new Set([
+    '的', '与', '和', '及', '在', '中', '对', '为', '是', '有', '从', '到',
+    'the', 'a', 'an', 'and', 'or', 'to', 'of', 'in', 'for', 'on', 'with', 'by',
+    '请', '帮我', '给我', '一下', '一个', '这个', '那个',
+]);
+/** 将输入归一化为语义键（去停用词 + 排序） */
+function normalizeInput(input) {
+    const tokens = input
+        .toLowerCase()
+        .replace(/[^\u4e00-\u9fa5a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter(t => t.length >= 2 && !NORMALIZE_STOP_WORDS.has(t))
+        .sort();
+    return tokens.slice(0, 6).join('|'); // 取前6个关键词，用 | 分隔
+}
 // ═══════════════════════════════════════════════════════════
 // 缓存读写
 // ═══════════════════════════════════════════════════════════
@@ -54,7 +70,7 @@ async function saveCache(cache) {
 // 公共 API
 // ═══════════════════════════════════════════════════════════
 /**
- * 查询缓存：先精确匹配，再模糊匹配
+ * 查询缓存：精确 → 归一化语义 → 编辑距离模糊
  */
 async function getCachedIntent(input) {
     const cache = await loadCache();
@@ -67,7 +83,20 @@ async function getCachedIntent(input) {
         logger_1.logger.info(`💾 意图缓存命中(精确): "${input.slice(0, 30)}..." → ${exact.result.summary.slice(0, 30)}`);
         return exact.result;
     }
-    // 2. 模糊匹配（编辑距离 ≤ 2，且长度比例合理）
+    // 2. 归一化语义匹配（"分析一下登录" ≈ "分析登录功能"）
+    const normalized = normalizeInput(input);
+    if (normalized) {
+        for (const entry of Object.values(cache.entries)) {
+            if (entry.normalizedInput === normalized) {
+                entry.hitCount++;
+                entry.lastUsed = new Date().toISOString();
+                await saveCache(cache);
+                logger_1.logger.info(`💾 意图缓存命中(语义): "${input.slice(0, 30)}..." ≈ "${entry.input.slice(0, 30)}..."`);
+                return entry.result;
+            }
+        }
+    }
+    // 3. 模糊匹配（编辑距离 ≤ 2，且长度比例合理）
     // 防止短字符串误匹配：如"补充测试"匹配"补充分析"（编辑距离 2 但语义完全不同）
     for (const [cachedInput, entry] of Object.entries(cache.entries)) {
         const dist = levenshtein(input, cachedInput);
@@ -92,6 +121,7 @@ async function cacheIntent(input, result, source = 'host-ai') {
     const cache = await loadCache();
     cache.entries[input] = {
         input,
+        normalizedInput: normalizeInput(input),
         result,
         source,
         hitCount: 1,