soloforge 1.4.16 → 2.0.0

package/dist/knowledge/index_manager.js

@@ -3,17 +3,45 @@ import fss from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
 import YAML from "yaml";
-import { debugLog } from "../engine/debug_log.js";
+import { debugLog } from "../engine/core/logger.js";
 import { getProjectKnowledgeDir, getGlobalPatternsDir } from "./loader.js";
 import { checkKnowledgeHealth, persistHealthChanges } from "./health_checker.js";
 import { detectConflicts } from "./conflict_detector.js";
-import { getContractDecision } from "../engine/template_asset_contract_registry.js";
-import { recordConsumptionTrace } from "../engine/consumption_trace_store.js";
-import { readSyncManifest, resolveAuthoritativeIdentity } from "../engine/template_init_sync.js";
-import { isSameOrDescendantPath } from "../engine/path_scope_utils.js";
+import { getContractDecision } from "../engine/templates/template_asset_contract_registry.js";
+import { recordConsumptionTrace } from "../engine/templates/consumption_trace_store.js";
+import { readSyncManifest, resolveAuthoritativeIdentity } from "../engine/templates/template_init_sync.js";
+import { isSameOrDescendantPath } from "../engine/core/path_scope_utils.js";
 import crypto from "node:crypto";
 /** 跳过的目录名集合 */
 const SKIP_DIRS = new Set(["node_modules", ".git", ".hg", ".svn", "__pycache__", ".DS_Store"]);
+/**
+ * asset_kind → type 标准化映射表。
+ * 将旧 asset_kind 枚举值映射到 KnowledgeEntry.type 的 9 值枚举。
+ * 未知值返回原始输入（不阻断）。
+ */
+const ASSET_KIND_TO_TYPE = {
+    pattern: "pattern",
+    procedure: "procedure",
+    pipeline: "pipeline_procedure",
+    workflow: "pipeline_procedure",
+    checklist: "checklist",
+    artifact_template: "artifact_template",
+    acceptance_template: "artifact_template",
+    review_rule: "review_rule",
+    hard_rule: "governance_rule",
+    domain_knowledge: "domain",
+    product_profile: "domain",
+};
+/**
+ * 标准化知识资产类型：将旧 asset_kind 值映射到统一的 type 枚举。
+ * @param raw - 原始 type 或 asset_kind 字符串
+ * @returns 标准化后的类型，未知值返回原始输入
+ */
+export function normalizeType(raw) {
+    return ASSET_KIND_TO_TYPE[raw] ?? raw;
+}
+/** 索引 schema 版本号 — 增量变更时递增 */
+export const INDEX_SCHEMA_VERSION = 1;
 /** 监听的文件系统事件类型集合 */
 const WATCH_EVENTS = new Set(["add", "change", "unlink", "unlinkDir"]);
 /**
@@ -30,7 +58,18 @@ export class KnowledgeIndexManager {
     watchingStarted = false;
     watchEnabled;
     closed = false;
+    rebuildInProgress = false;
+    pendingRebuild = false;
     filePathToEntryMap = new Map();
+    // P1-C1: 倒排索引 — 避免查询时 O(n) 全扫描，索引化后查询为 O(k) 集合运算
+    invertedIndex = {
+        byScope: new Map(),
+        byProduct: new Map(),
+        byType: new Map(),
+        byStage: new Map(),
+        activeIds: new Set(),
+        byId: new Map(),
+    };
     /**
      * 创建知识索引管理器实例。
      * @param config - 项目配置对象
@@ -39,7 +78,7 @@ export class KnowledgeIndexManager {
     constructor(config, options = {}) {
         this.config = config;
         this.watchEnabled = options.watch ?? true;
-        this.index = { version: 1, built_at: "", global_entries: [], project_entries: [] };
+        this.index = { version: INDEX_SCHEMA_VERSION, built_at: "", global_entries: [], project_entries: [] };
     }
     /**
      * 构建知识索引。
@@ -47,19 +86,45 @@ export class KnowledgeIndexManager {
      *              首次构建时启动文件监听。
      */
     async build() {
-        debugLog("索引管理器: 开始构建知识索引...");
-        this.index.built_at = new Date().toISOString();
-        const globalEntries = await this.scanDirectory(getGlobalPatternsDir());
-        const projectEntries = await this.scanDirectory(getProjectKnowledgeDir(this.config));
-        // 合同门禁: 过滤内部资产泄漏到用户项目的情况
-        this.index.global_entries = this.filterByContractGate(globalEntries);
-        this.index.project_entries = this.filterByContractGate(projectEntries);
-        this.rebuildEntryMap();
-        if (!this.watchingStarted && this.watchEnabled) {
-            await this.startWatching();
-            this.watchingStarted = true;
-        }
-        debugLog(`索引管理器: 索引构建完成 — 全局 ${globalEntries.length} 条，项目 ${projectEntries.length} 条。`);
+        if (this.rebuildInProgress) {
+            debugLog("索引管理器: build 正在进行中，跳过重复调用");
+            return;
+        }
+        this.rebuildInProgress = true;
+        try {
+            debugLog("索引管理器: 开始构建知识索引...");
+            this.index.built_at = new Date().toISOString();
+            const globalEntries = await this.scanDirectory(getGlobalPatternsDir());
+            const projectEntries = await this.scanDirectory(getProjectKnowledgeDir(this.config));
+            // 合同门禁: 过滤内部资产泄漏到用户项目的情况
+            this.index.global_entries = await this.filterByContractGate(globalEntries);
+            this.index.project_entries = await this.filterByContractGate(projectEntries);
+            this.rebuildEntryMap();
+            if (!this.watchingStarted && this.watchEnabled) {
+                await this.startWatching();
+                this.watchingStarted = true;
+            }
+            debugLog(`索引管理器: 索引构建完成 — 全局 ${globalEntries.length} 条，项目 ${projectEntries.length} 条。`);
+            // 自动执行一次健康检查（不阻塞调用方）
+            this.checkHealth().then((issues) => {
+                if (issues.length > 0) {
+                    debugLog(`索引管理器: 自动健康检查完成 — 发现 ${issues.length} 个问题。`);
+                }
+            }).catch((e) => {
+                debugLog("索引管理器: 自动健康检查失败 —", e);
+            });
+        }
+        finally {
+            this.rebuildInProgress = false;
+            // 重建期间收到的事件排阔回放
+            if (this.pendingRebuild) {
+                this.pendingRebuild = false;
+                debugLog("索引管理器: 检测到排队事件，触发增量重建。");
+                void this.build().catch((e) => {
+                    debugLog("索引管理器: 排队重建失败 —", e);
+                });
+            }
+        }
     }
     /**
      * 关闭索引管理器，停止文件监听并清理资源。
@@ -70,6 +135,10 @@ export class KnowledgeIndexManager {
             clearTimeout(this.rebuildTimer);
             this.rebuildTimer = null;
         }
+        if (this.persistUsedTimer) {
+            clearTimeout(this.persistUsedTimer);
+            this.persistUsedTimer = null;
+        }
         if (this.watcher) {
             await this.watcher.close();
             this.watcher = null;
@@ -98,7 +167,7 @@ export class KnowledgeIndexManager {
      * 同步资产: 验证 hash 一致性和合同注册，不通过则拒绝。
      * 用户自建文件: 通过 user schema 放行，不以 "unregistered path = pass" 绕过。
      */
-    filterByContractGate(entries) {
+    async filterByContractGate(entries) {
         const filtered = [];
         const blocked = [];
         // 加载同步清单，区分同步资产与用户自建文件
@@ -123,19 +192,19 @@ export class KnowledgeIndexManager {
                 // 同步资产: 从权威注册表按目标 relativePath 反向解析身份
                 // 不信任 manifest 中用户可编辑的 source_contract_path/source_asset_id
                 if (!knowledgeRelPath) {
-                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: normalized, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "同步条目无法解析 knowledge 相对路径", task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: normalized, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "同步条目无法解析 knowledge 相对路径", task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                     blocked.push(`[身份] ${entry.name} — 同步条目无法解析 knowledge 相对路径`);
                     continue;
                 }
                 const authId = resolveAuthoritativeIdentity(knowledgeRelPath);
                 if (!authId) {
-                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: normalized, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "同步条目无权威目标映射", task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: normalized, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "同步条目无权威目标映射", task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                     blocked.push(`[身份] ${entry.name} — 无权威目标映射: ${knowledgeRelPath}`);
                     continue;
                 }
                 // manifest source_contract_path 与权威映射不一致
                 if (syncEntry.source_contract_path !== authId.source_contract_path) {
-                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: authId.source_contract_path, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: `manifest source_contract_path 篡改: manifest=${syncEntry.source_contract_path} authoritative=${authId.source_contract_path}`, task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: authId.source_contract_path, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: `manifest source_contract_path 篡改: manifest=${syncEntry.source_contract_path} authoritative=${authId.source_contract_path}`, task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                     blocked.push(`[身份] ${entry.name} — source_contract_path 不一致`);
                     continue;
                 }
@@ -143,26 +212,30 @@ export class KnowledgeIndexManager {
                 // manifest source_asset_id 与权威合同不一致
                 const authAssetId = decision.contract?.asset_id ?? "";
                 if (syncEntry.source_asset_id !== authAssetId) {
-                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: authId.source_contract_path, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: `manifest source_asset_id 篡改: manifest=${syncEntry.source_asset_id} authoritative=${authAssetId}`, task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: authId.source_contract_path, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: `manifest source_asset_id 篡改: manifest=${syncEntry.source_asset_id} authoritative=${authAssetId}`, task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                     blocked.push(`[身份] ${entry.name} — source_asset_id 不一致`);
                     continue;
                 }
                 if (decision.decision === "unregistered") {
-                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: authId.source_contract_path, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "同步资产在权威注册表中 unregistered", task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: authId.source_contract_path, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "同步资产在权威注册表中 unregistered", task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                     blocked.push(`[身份] ${entry.name} — 权威注册表 unregistered`);
                     continue;
                 }
                 if (decision.decision === "denied") {
-                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: authId.source_contract_path, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: `内部资产: ${decision.contract?.asset_visibility ?? "denied"}`, task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: authId.source_contract_path, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: `内部资产: ${decision.contract?.asset_visibility ?? "denied"}`, task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                     blocked.push(`[内部] ${entry.name} — 同步资产被合同拒绝`);
                     continue;
                 }
                 // hash 比对: 权威来源 hash（不信任 manifest source_hash）
-                if (fss.existsSync(normalized)) {
-                    const fileContent = fss.readFileSync(normalized, "utf-8");
+                let fileContent;
+                try {
+                    fileContent = await fs.readFile(normalized, "utf-8");
+                }
+                catch { /* 文件不存在时跳过 hash 比对 */ }
+                if (fileContent !== undefined) {
                     const currentHash = this.bodyHash(fileContent, normalized);
                     if (currentHash !== authId.source_hash) {
-                        recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: authId.source_contract_path, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "source_hash"], matched_reason: `同步资产 body hash 不一致（权威来源验证）: authoritative=${authId.source_hash} actual=${currentHash}`, task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                        recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: authId.source_contract_path, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "source_hash"], matched_reason: `同步资产 body hash 不一致（权威来源验证）: authoritative=${authId.source_hash} actual=${currentHash}`, task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                         blocked.push(`[篡改] ${entry.name} — body hash 不一致: authoritative=${authId.source_hash} actual=${currentHash}`);
                         continue;
                     }
@@ -172,12 +245,12 @@ export class KnowledgeIndexManager {
                     const projectStack = this.getProjectTechStack();
                     const matches = decision.contract.applicable_tech_stack.some(s => projectStack.some(ps => ps.toLowerCase().includes(s.toLowerCase()) || s.toLowerCase().includes(ps.toLowerCase())));
                     if (!matches) {
-                        recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: authId.source_contract_path, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: `技术栈不适配: 资产需 ${decision.contract.applicable_tech_stack.join(",")}，项目为 ${projectStack.join(",")}`, task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                        recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: authId.source_contract_path, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: `技术栈不适配: 资产需 ${decision.contract.applicable_tech_stack.join(",")}，项目为 ${projectStack.join(",")}`, task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                         blocked.push(`[技术栈] ${entry.name} — 资产需 ${decision.contract.applicable_tech_stack.join(",")}，项目为 ${projectStack.join(",")}`);
                         continue;
                     }
                 }
-                recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: authId.source_contract_path, contract_decision: "allowed", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "同步资产通过权威来源身份验证", task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString(), declared_consumer: decision.contract?.mainline_consumer });
+                recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: authId.source_contract_path, contract_decision: "allowed", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "同步资产通过权威来源身份验证", task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString(), declared_consumer: decision.contract?.mainline_consumer });
                 filtered.push(entry);
             }
             else {
@@ -187,13 +260,13 @@ export class KnowledgeIndexManager {
                     // 文件路径命中内置注册资产 — 即使 manifest 缺失也不得降级为用户自建
                     const decision = getContractDecision(templateRelPath);
                     if (decision.decision === "denied") {
-                        recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: templateRelPath, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: `内部资产（manifest 缺失）: ${decision.contract?.asset_visibility ?? "denied"}`, task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                        recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: templateRelPath, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: `内部资产（manifest 缺失）: ${decision.contract?.asset_visibility ?? "denied"}`, task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                         blocked.push(`[内部] ${entry.name} — 资产可见性不允许索引`);
                         continue;
                     }
                     if (decision.decision === "unregistered") {
                         // toTemplateRelPath 已验证非 unregistered，此分支理论上不可达
-                        recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: normalized, contract_decision: "allowed", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "用户自建文件", task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                        recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: normalized, contract_decision: "allowed", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "用户自建文件", task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                         filtered.push(entry);
                         continue;
                     }
@@ -202,11 +275,15 @@ export class KnowledgeIndexManager {
                         const authId = resolveAuthoritativeIdentity(knowledgeRelPath);
                         if (authId) {
                             // 权威 hash 校验（不依赖 manifest）
-                            if (fss.existsSync(normalized)) {
-                                const fileContent = fss.readFileSync(normalized, "utf-8");
-                                const currentHash = this.bodyHash(fileContent, normalized);
+                            let hashFileContent;
+                            try {
+                                hashFileContent = await fs.readFile(normalized, "utf-8");
+                            }
+                            catch { /* 文件不存在时跳过 hash 校验 */ }
+                            if (hashFileContent !== undefined) {
+                                const currentHash = this.bodyHash(hashFileContent, normalized);
                                 if (currentHash !== authId.source_hash) {
-                                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: templateRelPath, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "source_hash"], matched_reason: `已注册内置资产 manifest 缺失且 body hash 不一致: authoritative=${authId.source_hash} actual=${currentHash}`, task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: templateRelPath, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "source_hash"], matched_reason: `已注册内置资产 manifest 缺失且 body hash 不一致: authoritative=${authId.source_hash} actual=${currentHash}`, task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                                     blocked.push(`[篡改] ${entry.name} — manifest 缺失且 body hash 不一致`);
                                     continue;
                                 }
@@ -216,29 +293,29 @@ export class KnowledgeIndexManager {
                                 const projectStack = this.getProjectTechStack();
                                 const matches = decision.contract.applicable_tech_stack.some(s => projectStack.some(ps => ps.toLowerCase().includes(s.toLowerCase()) || s.toLowerCase().includes(ps.toLowerCase())));
                                 if (!matches) {
-                                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: templateRelPath, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: `技术栈不适配（manifest 缺失）`, task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: templateRelPath, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: `技术栈不适配（manifest 缺失）`, task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                                     blocked.push(`[技术栈] ${entry.name} — 资产需 ${decision.contract.applicable_tech_stack.join(",")}`);
                                     continue;
                                 }
                             }
-                            recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: templateRelPath, contract_decision: "allowed", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "已注册内置资产通过权威 hash 校验（manifest 缺失）", task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString(), declared_consumer: decision.contract?.mainline_consumer });
+                            recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: templateRelPath, contract_decision: "allowed", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "已注册内置资产通过权威 hash 校验（manifest 缺失）", task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString(), declared_consumer: decision.contract?.mainline_consumer });
                             filtered.push(entry);
                             continue;
                         }
                     }
                     // 已注册但权威来源文件缺失 → fail-closed: 必须阻断
                     if (templateRelPath) {
-                        recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: templateRelPath, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision"], matched_reason: `已注册内置资产 ${templateRelPath} 权威来源文件缺失`, task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                        recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: templateRelPath, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision"], matched_reason: `已注册内置资产 ${templateRelPath} 权威来源文件缺失`, task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                         blocked.push(`[权威缺失] ${entry.name} — 已注册模板 ${templateRelPath} 权威来源不存在`);
                         continue;
                     }
                     // knowledgeRelPath 也为 null → fail-closed: 无法确认权威身份时阻断
-                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: normalized, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision"], matched_reason: "无法解析权威身份，fail-closed 阻断", task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: normalized, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision"], matched_reason: "无法解析权威身份，fail-closed 阻断", task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                     blocked.push(`[权威未知] ${entry.name} — 无法解析权威身份，安全阻断`);
                 }
                 else {
                     // 完全不在知识目录映射范围内 → 用户自建文件
-                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: normalized, contract_decision: "allowed", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "用户自建文件", task_id_or_route: "filterByContractGate", consumed_at: new Date().toISOString() });
+                    recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: normalized, contract_decision: "allowed", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "用户自建文件", task_id_or_pipeline_id: "filterByContractGate", consumed_at: new Date().toISOString() });
                     filtered.push(entry);
                 }
             }
@@ -270,10 +347,12 @@ export class KnowledgeIndexManager {
             const rel = absPath.substring(globalDir.length + 1);
             return `templates/patterns/${rel}`;
         }
-        // 项目知识目录下的文件: 仅映射为 templates/knowledge/... 后检查注册表
-        if (absPath.includes("/knowledge/")) {
-            const idx = absPath.indexOf("/knowledge/");
-            const rel = absPath.substring(idx + 1); // knowledge/rules/...
+        // 项目知识目录下的文件: 映射为 templates/... 后检查注册表
+        // 使用与 toKnowledgeRelPath 相同的精确标记，避免误匹配其他 /knowledge/ 段
+        const knowledgeMarker = "/.soloforge/knowledge/";
+        const knowledgeIdx = absPath.indexOf(knowledgeMarker);
+        if (knowledgeIdx >= 0) {
+            const rel = absPath.substring(knowledgeIdx + knowledgeMarker.length); // domain/... or procedures/... etc.
             const templatePath = `templates/${rel}`;
             // 检查该路径是否在权威合同注册表中（即来自内置模板同步）
             const decision = getContractDecision(templatePath);
@@ -317,6 +396,7 @@ export class KnowledgeIndexManager {
             dirs.push(projectDir);
         if (dirs.length === 0)
             return;
+        // eslint-disable-next-line @typescript-eslint/consistent-type-imports -- 动态导入需要 typeof import() 类型声明
         let chokidar;
         try {
             chokidar = await import("chokidar");
@@ -339,17 +419,24 @@ export class KnowledgeIndexManager {
             this.watchEnabled = false;
             const failedWatcher = this.watcher;
             this.watcher = null;
-            void failedWatcher?.close().catch(() => { });
+            void failedWatcher?.close().catch((e) => { debugLog(`索引管理器: 关闭监听器失败 — ${String(e)}`); });
             const err = error;
             debugLog(`索引管理器: 文件监听失败，已降级为手动重建模式 — ${err.code ?? "UNKNOWN"} ${err.message ?? ""}`.trim());
         });
         this.watcher.on("all", (event, filePath) => {
             if (!WATCH_EVENTS.has(event))
                 return;
+            if (this.rebuildInProgress) {
+                // 重建期间不丢弃事件，设置标志待重建完成后重新触发
+                this.pendingRebuild = true;
+                return;
+            }
             if (this.rebuildTimer)
                 clearTimeout(this.rebuildTimer);
             this.rebuildTimer = setTimeout(() => {
-                this.applyIncrementalUpdate(event, filePath).catch(() => { });
+                this.applyIncrementalUpdate(event, filePath).catch((e) => {
+                    debugLog("索引管理器: 增量更新失败 —", e);
+                });
                 this.rebuildTimer = null;
             }, 300);
         });
@@ -363,6 +450,41 @@ export class KnowledgeIndexManager {
         for (const entry of [...this.index.project_entries, ...this.index.global_entries]) {
             this.filePathToEntryMap.set(entry.file_path, entry);
         }
+        this.rebuildInvertedIndex();
+    }
+    /**
+     * P1-C1: 重建倒排索引（每次 build / 增量更新后调用）。
+     * 索引键: scope/product/type/stage → 条目 id 集合；activeIds 仅含 status="active"。
+     */
+    rebuildInvertedIndex() {
+        this.invertedIndex.byScope.clear();
+        this.invertedIndex.byProduct.clear();
+        this.invertedIndex.byType.clear();
+        this.invertedIndex.byStage.clear();
+        this.invertedIndex.activeIds.clear();
+        this.invertedIndex.byId.clear();
+        const addToIndex = (idx, key, id) => {
+            let set = idx.get(key);
+            if (!set) {
+                set = new Set();
+                idx.set(key, set);
+            }
+            set.add(id);
+        };
+        for (const entry of [...this.index.project_entries, ...this.index.global_entries]) {
+            this.invertedIndex.byId.set(entry.id, entry);
+            if (entry.status === "active") {
+                this.invertedIndex.activeIds.add(entry.id);
+            }
+            for (const s of entry.scope ?? [])
+                addToIndex(this.invertedIndex.byScope, s, entry.id);
+            for (const p of entry.products ?? [])
+                addToIndex(this.invertedIndex.byProduct, p, entry.id);
+            if (entry.type)
+                addToIndex(this.invertedIndex.byType, entry.type, entry.id);
+            for (const st of entry.stages ?? [])
+                addToIndex(this.invertedIndex.byStage, st, entry.id);
+        }
     }
     /**
      * 应用增量更新（内部方法）。
@@ -376,7 +498,6 @@ export class KnowledgeIndexManager {
             return;
         this.index.built_at = new Date().toISOString();
         const globalDir = getGlobalPatternsDir();
-        const projectDir = getProjectKnowledgeDir(this.config);
         const isGlobal = isSameOrDescendantPath(filePath, globalDir);
         const entries = isGlobal ? this.index.global_entries : this.index.project_entries;
         if (event === "unlink" || event === "unlinkDir") {
@@ -384,13 +505,15 @@ export class KnowledgeIndexManager {
             if (idx !== -1)
                 entries.splice(idx, 1);
             this.filePathToEntryMap.delete(filePath);
+            // P1-C1: 增量重建倒排索引，保持查询路径一致
+            this.rebuildInvertedIndex();
             debugLog(`索引管理器: 文件已删除，移除索引条目 — ${filePath}`);
             return;
         }
         try {
             const newEntries = await this.parseFile(filePath);
             // 增量更新也必须通过合同门禁
-            const filtered = this.filterByContractGate(newEntries);
+            const filtered = await this.filterByContractGate(newEntries);
             for (const newEntry of filtered) {
                 const existingIdx = entries.findIndex((e) => e.file_path === filePath);
                 if (existingIdx !== -1) {
@@ -401,6 +524,8 @@ export class KnowledgeIndexManager {
                 }
                 this.filePathToEntryMap.set(filePath, newEntry);
             }
+            // P1-C1: 增量重建倒排索引
+            this.rebuildInvertedIndex();
             debugLog(`索引管理器: 文件变更已更新 — ${filePath}`);
         }
         catch {
@@ -448,52 +573,94 @@ export class KnowledgeIndexManager {
      */
     query(filters) {
         debugLog("知识索引: 查询知识条目");
-        const all = [...this.index.project_entries, ...this.index.global_entries];
-        const scopeSet = new Set(filters.scope ?? []);
-        const productSet = new Set(filters.products ?? []);
-        let results = all
-            .filter((e) => e.status === "active")
-            .filter((e) => {
-            if (!filters.scope?.length)
-                return true;
-            return e.scope.some((s) => scopeSet.has(s) || s === "shared" || s === "*");
-        })
-            .filter((e) => {
-            if (!filters.products?.length)
-                return true;
-            return e.products.some((p) => productSet.has(p) || p === "*");
-        })
-            .filter((e) => {
-            if (!filters.type)
-                return true;
-            return e.type === filters.type;
-        })
-            .filter((e) => {
-            if (!filters.route)
-                return true;
-            if (!e.routes || e.routes.length === 0)
-                return true;
-            // 只过滤声明了标准 IntentRoute 名称的条目
-            const standardRoutes = ["skip_chat", "direct_answer", "artifact_generation",
-                "source_extraction", "code_change", "analysis", "review", "acceptance",
-                "planning", "operation"];
-            const hasStandardRoutes = e.routes.some((r) => standardRoutes.includes(r) || r === "*");
-            if (!hasStandardRoutes)
-                return true;
-            return e.routes.includes(filters.route) || e.routes.includes("*");
-        })
-            .filter((e) => {
-            if (!filters.keywords?.length)
-                return true;
-            const score = this.keywordScore(e, filters.keywords);
-            return score > 0;
-        });
+        // P1-C1: 倒排索引路径 — 通过集合运算收集候选 id，避免 O(n) 全扫描
+        const candidateSets = [];
+        // status=active 是基础约束
+        candidateSets.push(this.invertedIndex.activeIds);
+        if (filters.scope?.length) {
+            const scopeIds = new Set();
+            for (const s of filters.scope) {
+                const set = this.invertedIndex.byScope.get(s);
+                if (set)
+                    for (const id of set)
+                        scopeIds.add(id);
+            }
+            // shared / * 视为通配，命中所有
+            const sharedSet = this.invertedIndex.byScope.get("shared");
+            if (sharedSet)
+                for (const id of sharedSet)
+                    scopeIds.add(id);
+            const wildcardSet = this.invertedIndex.byScope.get("*");
+            if (wildcardSet)
+                for (const id of wildcardSet)
+                    scopeIds.add(id);
+            candidateSets.push(scopeIds);
+        }
+        if (filters.products?.length) {
+            const productIds = new Set();
+            for (const p of filters.products) {
+                const set = this.invertedIndex.byProduct.get(p);
+                if (set)
+                    for (const id of set)
+                        productIds.add(id);
+            }
+            const wildcardSet = this.invertedIndex.byProduct.get("*");
+            if (wildcardSet)
+                for (const id of wildcardSet)
+                    productIds.add(id);
+            candidateSets.push(productIds);
+        }
+        if (filters.type) {
+            const typeSet = this.invertedIndex.byType.get(filters.type);
+            candidateSets.push(typeSet ?? new Set());
+        }
+        if (filters.stages?.length) {
+            const stageIds = new Set();
+            for (const st of filters.stages) {
+                const set = this.invertedIndex.byStage.get(st);
+                if (set)
+                    for (const id of set)
+                        stageIds.add(id);
+            }
+            const wildcardStage = this.invertedIndex.byStage.get("*");
+            if (wildcardStage)
+                for (const id of wildcardStage)
+                    stageIds.add(id);
+            // stages 字段缺失视为不限定，纳入候选
+            for (const [id, entry] of this.invertedIndex.byId) {
+                if (!entry.stages || entry.stages.length === 0)
+                    stageIds.add(id);
+            }
+            candidateSets.push(stageIds);
+        }
+        // 取所有集合的交集
+        let candidateIds = candidateSets[0];
+        for (let i = 1; i < candidateSets.length; i++) {
+            const next = candidateSets[i];
+            candidateIds = new Set([...candidateIds].filter((id) => next.has(id)));
+        }
+        // keywords 仍走线性扫描（评分无法用集合表达），但仅在候选集内进行
+        let results;
         if (filters.keywords?.length) {
-            results.sort((a, b) => {
-                const scoreA = this.keywordScore(a, filters.keywords);
-                const scoreB = this.keywordScore(b, filters.keywords);
-                return scoreB - scoreA;
-            });
+            const scored = [];
+            for (const id of candidateIds) {
+                const entry = this.invertedIndex.byId.get(id);
+                if (!entry)
+                    continue;
+                const score = this.keywordScore(entry, filters.keywords);
+                if (score > 0)
+                    scored.push({ entry, score });
+            }
+            scored.sort((a, b) => b.score - a.score);
+            results = scored.map((s) => s.entry);
+        }
+        else {
+            results = [];
+            for (const id of candidateIds) {
+                const entry = this.invertedIndex.byId.get(id);
+                if (entry)
+                    results.push(entry);
+            }
         }
         return results.slice(0, filters.limit ?? 5);
     }
@@ -502,6 +669,8 @@ export class KnowledgeIndexManager {
      * @description 增加指定条目的 usage_count 并更新 last_used_at 时间戳。
      * @param entryIds - 要标记的条目 ID 列表
      */
+    persistUsedTimer = null;
+    static PERSIST_USED_DEBOUNCE_MS = 2000;
     markUsed(entryIds) {
         const idSet = new Set(entryIds);
         const now = new Date().toISOString();
@@ -512,6 +681,54 @@ export class KnowledgeIndexManager {
             }
         }
         debugLog(`索引管理器: 已标记 ${entryIds.length} 条知识为已使用。`);
+        // 防抖持久化：2 秒延迟，合并短时间内的多次 markUsed 调用
+        if (this.persistUsedTimer)
+            clearTimeout(this.persistUsedTimer);
+        this.persistUsedTimer = setTimeout(() => {
+            this.persistUsedTimer = null;
+            this.persistMarkUsedChanges().catch((e) => {
+                debugLog("索引管理器: 持久化 markUsed 变更失败 —", e);
+            });
+        }, KnowledgeIndexManager.PERSIST_USED_DEBOUNCE_MS);
+    }
+    /**
+     * 将 markUsed 导致的 last_used_at / usage_count 变更持久化到磁盘。
+     * @description 遍历所有项目条目，将 last_used_at 和 usage_count 写回对应的 Markdown/YAML 文件。
+     *              使用原子写入（先写 .tmp 再 rename）。单文件写入失败不影响其他文件。
+     */
+    async persistMarkUsedChanges() {
+        const changed = [...this.index.project_entries, ...this.index.global_entries]
+            .filter(e => e.file_path && fss.existsSync(e.file_path));
+        if (changed.length === 0)
+            return;
+        debugLog(`索引管理器: 持久化 ${changed.length} 条 markUsed 变更...`);
+        for (const entry of changed) {
+            try {
+                const ext = path.extname(entry.file_path);
+                if (ext === ".md") {
+                    const raw = await fs.readFile(entry.file_path, "utf-8");
+                    const { data, content } = matter(raw);
+                    data.last_used_at = entry.last_used_at;
+                    data.usage_count = entry.usage_count;
+                    const tmpPath = `${entry.file_path}.tmp`;
+                    await fs.writeFile(tmpPath, matter.stringify(content, data), "utf-8");
+                    await fs.rename(tmpPath, entry.file_path);
+                }
+                else if (ext === ".yaml" || ext === ".yml") {
+                    const raw = await fs.readFile(entry.file_path, "utf-8");
+                    const data = YAML.parse(raw);
+                    data.last_used_at = entry.last_used_at;
+                    data.usage_count = entry.usage_count;
+                    const tmpPath = `${entry.file_path}.tmp`;
+                    await fs.writeFile(tmpPath, YAML.stringify(data), "utf-8");
+                    await fs.rename(tmpPath, entry.file_path);
+                }
+            }
+            catch {
+                debugLog("索引管理器: 写入文件失败 — " + entry.file_path);
+            }
+        }
+        debugLog("索引管理器: markUsed 变更持久化完成。");
     }
     /**
      * 根据 ID 获取知识条目。
@@ -520,8 +737,10 @@ export class KnowledgeIndexManager {
      */
     getEntry(id) {
         debugLog("知识索引: 获取条目 — " + id);
-        return (this.index.project_entries.find((e) => e.id === id) ||
-            this.index.global_entries.find((e) => e.id === id));
+        // P1-C1: 优先走倒排索引 O(1)，fallback 到线性扫描（兼容旧路径）
+        return this.invertedIndex.byId.get(id)
+            ?? this.index.project_entries.find((e) => e.id === id)
+            ?? this.index.global_entries.find((e) => e.id === id);
     }
     /**
      * 获取所有知识条目（按来源分组）。
@@ -542,6 +761,8 @@ export class KnowledgeIndexManager {
         debugLog("知识索引: 内存添加条目 — " + entry.name);
         this.index.project_entries.push(entry);
         this.filePathToEntryMap.set(entry.file_path, entry);
+        // 重建倒排索引，确保 query() 能找到新条目
+        this.rebuildInvertedIndex();
     }
     /**
      * 重新加载知识索引。
@@ -575,10 +796,19 @@ export class KnowledgeIndexManager {
      * @returns 匹配的关键词数量
      */
     keywordScore(entry, keywords) {
-        const text = ` ${entry.name} ${entry.when} `.toLowerCase();
+        const text = `${entry.name} ${entry.triggers?.join(" ") ?? ""}`.toLowerCase();
         return keywords.filter((kw) => {
             const lowerKw = kw.toLowerCase();
-            return text.includes(` ${lowerKw} `) || text.startsWith(`${lowerKw} `) || text.endsWith(` ${lowerKw}`);
+            // 空格分词匹配（英文）
+            const spacedText = ` ${text} `;
+            if (spacedText.includes(` ${lowerKw} `) || text.startsWith(`${lowerKw} `) || text.endsWith(` ${lowerKw}`)) {
+                return true;
+            }
+            // 中文无空格场景：直接子串匹配
+            if (text.includes(lowerKw)) {
+                return true;
+            }
+            return false;
         }).length;
     }
     /**
@@ -612,22 +842,30 @@ export class KnowledgeIndexManager {
      */
     parseEntry(data, filePath, body) {
         return {
-            id: data.id || data.name || path.basename(filePath, path.extname(filePath)),
+            id: typeof data.id === "string" ? data.id : typeof data.name === "string" ? data.name : path.basename(filePath, path.extname(filePath)),
             file_path: filePath,
-            name: data.name || path.basename(filePath, path.extname(filePath)),
-            type: data.type || data.asset_kind || this.inferType(filePath),
-            when: data.when || (Array.isArray(data.primary_triggers) ? data.primary_triggers.join(", ") : data.primary_triggers) || "",
+            name: typeof data.name === "string" ? data.name : path.basename(filePath, path.extname(filePath)),
+            type: normalizeType(typeof data.type === "string" ? data.type : typeof data.asset_kind === "string" ? data.asset_kind : this.inferType(filePath)),
+            // triggers 优先取 data.triggers，其次 primary_triggers，最后拆分 when
+            triggers: Array.isArray(data.triggers) ? data.triggers
+                : Array.isArray(data.primary_triggers) && data.primary_triggers.length > 0 ? data.primary_triggers
+                    : typeof data.when === "string" && data.when.trim() ? data.when.split(/,\s*/).map((s) => s.trim()).filter(Boolean)
+                        : [],
             body: body || undefined,
-            scope: data.scope || ["shared"],
-            products: data.products || ["*"],
-            tech_stack: data.tech_stack,
-            last_used_at: data.last_used_at,
-            created_at: data.created_at || new Date().toISOString().split("T")[0],
-            updated_at: data.updated_at || new Date().toISOString().split("T")[0],
-            usage_count: data.usage_count || 0,
-            confidence: data.confidence ?? 1.0,
-            routes: Array.isArray(data.routes) ? data.routes : data.routes ? [data.routes] : ["*"],
-            status: data.status || "active",
+            scope: Array.isArray(data.scope) ? data.scope : ["shared"],
+            products: Array.isArray(data.products) ? data.products : ["*"],
+            tech_stack: typeof data.tech_stack === "string" ? data.tech_stack : undefined,
+            last_used_at: typeof data.last_used_at === "string" ? data.last_used_at : undefined,
+            created_at: typeof data.created_at === "string" ? data.created_at : new Date().toISOString().split("T")[0],
+            updated_at: typeof data.updated_at === "string" ? data.updated_at : new Date().toISOString().split("T")[0],
+            usage_count: typeof data.usage_count === "number" ? data.usage_count : 0,
+            confidence: typeof data.confidence === "number" ? data.confidence : 1.0,
+            status: (typeof data.status === "string" ? data.status : typeof data.lifecycle_status === "string" ? data.lifecycle_status : filePath.includes("/gates/") ? "active" : "draft"),
+            stages: Array.isArray(data.stages)
+                ? data.stages.filter((s) => typeof s === "string")
+                : typeof data.stages === "string"
+                    ? data.stages.split(",").map((s) => s.trim()).filter(Boolean)
+                    : undefined,
         };
     }
     /**
@@ -650,6 +888,14 @@ export class KnowledgeIndexManager {
             return "governance_rule";
         if (parts.includes("review_rules"))
             return "review_rule";
+        if (parts.includes("artifacts"))
+            return "artifact_template";
+        if (parts.includes("checklists"))
+            return "checklist";
+        if (parts.includes("gates"))
+            return "governance_rule";
+        if (parts.includes("internal") && parts.includes("rules"))
+            return "governance_rule";
         return "pattern";
     }
     /**
@@ -717,6 +963,8 @@ export class KnowledgeIndexManager {
         for (const entry of dirEntries) {
             if (SKIP_DIRS.has(entry.name))
                 continue;
+            if (entry.isSymbolicLink())
+                continue;
             const fullPath = path.join(dir, entry.name);
             if (entry.isDirectory()) {
                 results.push(...(await this.walkFiles(fullPath, maxDepth, currentDepth + 1)));