soloforge 1.1.42 → 1.1.44

package/dist/context/knowledge/index_manager.js

@@ -0,0 +1,1024 @@
+/**
+ * Index Manager — 知识配置层模块。
+ *
+ * 职责边界：
+ * - 负责：normalizeType 等 知识配置层职责
+ * - 不负责：不属于本模块的职责由对应模块承担
+ *
+ * 被谁调用：上层模块按需调用
+ * 调用谁：promises、node:fs、node:path、gray-matter、yaml、index
+ *
+ * 数据流：输入 → normalizeType 处理 → 输出
+ * 持久化：读写本地文件（详见代码内路径）
+ */
+import fs from "node:fs/promises";
+import fss from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import YAML from "yaml";
+import { debugLog } from "../../shared/logger.js";
+import { getProjectKnowledgeDir, getGlobalPatternsDir, getBuiltinKnowledgeDir } from "./loader.js";
+import { checkKnowledgeHealth, persistHealthChanges } from "./health_checker.js";
+import { detectConflicts, detectMetadataConflicts } from "./conflict_detector.js";
+import { getContractDecision } from "../../domain/asset_registry/template_asset_contract_registry.js";
+import { recordConsumptionTrace } from "../../context/templates/consumption_trace_store.js";
+import { isSameOrDescendantPath } from "../../shared/path_scope_utils.js";
+/** 跳过的目录名集合 */
+const SKIP_DIRS = new Set(["node_modules", ".git", ".hg", ".svn", "__pycache__", ".DS_Store"]);
+/**
+ * type 字段值标准化映射表。
+ * 将 frontmatter 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",
+};
+/** KIM-006修复：合法 type 枚举值集合，用于运行时校验 */
+const VALID_TYPES = new Set([
+    "pattern", "procedure", "domain", "acceptance_template", "review_rule",
+    "governance_rule", "pipeline_procedure", "artifact_template", "checklist",
+]);
+/**
+ * 标准化知识资产类型：将旧 asset_kind 值映射到统一的 type 枚举。
+ * KIM-006修复：如果值不是合法枚举则 fallback 到默认值 "pattern"，而非 as 强制断言。
+ *
+ * KIM-007说明：normalizeType 的映射范围是字段值（来自 frontmatter 中的 type），
+ * 与 inferType 的映射范围（文件路径目录名）是互补关系，不是重叠：
+ * - normalizeType: "acceptance_template" → "artifact_template"（值归一化），兼防历史 asset_kind 风格值
+ * - inferType: "patterns" → "pattern", "domain" → "domain" 等（路径目录名）
+ * 两者输入域不同，无法统一为单一映射表。parseEntry 中优先使用 normalizeType，
+ * 仅当 frontmatter 中无 type 字段时才 fallback 到 inferType。
+ *
+ * @param raw - 原始 type 或 asset_kind 字符串
+ * @returns 标准化后的类型，不合法值 fallback 到 "pattern"
+ */
+export function normalizeType(raw) {
+    const mapped = ASSET_KIND_TO_TYPE[raw];
+    if (mapped)
+        return mapped;
+    // 运行时校验：确保返回值是合法枚举
+    if (VALID_TYPES.has(raw))
+        return raw;
+    // 不合法的值 fallback 到默认类型
+    debugLog(`normalizeType: 未知类型 "${raw}" → fallback 到 "pattern"`);
+    return "pattern";
+}
+/** 索引 schema 版本号 — 增量变更时递增 */
+export const INDEX_SCHEMA_VERSION = 1;
+/** 监听的文件系统事件类型集合 */
+const WATCH_EVENTS = new Set(["add", "change", "unlink", "unlinkDir"]);
+/**
+ * 知识索引管理器。
+ * @description 负责扫描、解析、索引知识文件（Markdown 和 YAML），
+ *              支持增量更新（文件监听）和按条件查询。
+ *              同时提供健康检查和冲突检测功能。
+ *
+ *              使用计数持久化说明：
+ *              markUsed 采用 500ms 防抖延迟写入磁盘，平衡 IO 频率与数据丢失风险。
+ *              SIGKILL / OOM 等不可拦截信号无法防范，500ms 是可接受的权衡窗口。
+ *              beforeExit / SIGTERM / SIGINT 信号已注册刷新回调，尽量减少正常退出时的丢失。
+ */
+export class KnowledgeIndexManager {
+    config;
+    index;
+    watcher = null;
+    rebuildTimer = null;
+    watchingStarted = false;
+    watchEnabled;
+    closed = false;
+    rebuildInProgress = false;
+    pendingRebuild = false;
+    filePathToEntryMap = new Map();
+    /** KIM-001修复：进程退出刷新句柄，close 时移除监听器 */
+    _flushHandle;
+    // P1-C1: 倒排索引 — 避免查询时 O(n) 全扫描，索引化后查询为 O(k) 集合运算
+    invertedIndex = {
+        byScope: new Map(),
+        byProduct: new Map(),
+        byType: new Map(),
+        byDomain: new Map(),
+        activeIds: new Set(),
+        byId: new Map(),
+        byKeyword: new Map(),
+    };
+    /**
+     * 创建知识索引管理器实例。
+     * @param config - 项目配置对象
+     * @param options - 索引构建选项
+     */
+    constructor(config, options = {}) {
+        this.config = config;
+        this.watchEnabled = options.watch ?? true;
+        this.index = { version: INDEX_SCHEMA_VERSION, built_at: "", global_entries: [], project_entries: [], builtin_entries: [] };
+        // KIM-001修复：注册进程退出处理，防止防抖窗口内使用计数丢失
+        this._flushHandle = () => this.flushPendingUsageUpdates();
+        process.on("beforeExit", this._flushHandle);
+        process.on("SIGTERM", this._flushHandle);
+        process.on("SIGINT", this._flushHandle);
+    }
+    /**
+     * 构建知识索引。
+     * @description 扫描全局和项目知识目录，解析所有知识文件并建立索引。
+     *              首次构建时启动文件监听。
+     */
+    async build() {
+        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));
+            // 内置知识直接从 SoloForge templates/knowledge/ 读取，不复制到项目目录
+            const builtinEntries = await this.scanDirectory(getBuiltinKnowledgeDir());
+            // 合同门禁: 过滤内部资产泄漏到用户项目的情况
+            this.index.global_entries = await this.filterByContractGate(globalEntries);
+            this.index.project_entries = await this.filterByContractGate(projectEntries);
+            // 内置资产走简化门禁（只检查可见性和技术栈，不做 hash 比对）
+            this.index.builtin_entries = await this.filterBuiltinEntries(builtinEntries);
+            this.rebuildEntryMap();
+            if (!this.watchingStarted && this.watchEnabled) {
+                await this.startWatching();
+                this.watchingStarted = true;
+            }
+            debugLog(`索引管理器: 索引构建完成 — 全局 ${globalEntries.length} 条，项目 ${projectEntries.length} 条，内置 ${builtinEntries.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);
+                });
+            }
+        }
+    }
+    /**
+     * 关闭索引管理器，停止文件监听并清理资源。
+     */
+    async close() {
+        this.closed = true;
+        if (this.rebuildTimer) {
+            clearTimeout(this.rebuildTimer);
+            this.rebuildTimer = null;
+        }
+        if (this.persistUsedTimer) {
+            clearTimeout(this.persistUsedTimer);
+            this.persistUsedTimer = null;
+        }
+        // KIM-001修复：移除进程退出监听器，防止已关闭实例的回调执行
+        process.off("beforeExit", this._flushHandle);
+        process.off("SIGTERM", this._flushHandle);
+        process.off("SIGINT", this._flushHandle);
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = null;
+        }
+        debugLog("索引管理器: 已关闭。");
+    }
+    /**
+     * 合同门禁过滤 — 项目目录和全局目录下的条目。
+     * 内置知识资产不再复制到项目目录，所以项目/全局目录下的条目都是用户自建的，直接放行。
+     */
+    async filterByContractGate(entries) {
+        const filtered = [];
+        for (const entry of entries) {
+            if (!entry.file_path) {
+                filtered.push(entry);
+                continue;
+            }
+            recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: entry.file_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() });
+            filtered.push(entry);
+        }
+        return filtered;
+    }
+    /**
+     * 内置资产门禁过滤 — 从 SoloForge templates/knowledge/ 直接读取的条目。
+     * 只检查合同可见性和技术栈适用性，不做 hash 比对（直接读源头，无需防篡改）。
+     */
+    async filterBuiltinEntries(entries) {
+        const filtered = [];
+        const blocked = [];
+        for (const entry of entries) {
+            if (!entry.file_path) {
+                filtered.push(entry);
+                continue;
+            }
+            const normalized = entry.file_path.replace(/\\/g, "/");
+            // 从绝对路径提取 templates/knowledge/ 下的相对路径
+            const relPath = this.toBuiltinRelPath(normalized);
+            if (!relPath) {
+                // 不在 templates/knowledge/ 下（理论上不会出现），直接放行
+                filtered.push(entry);
+                continue;
+            }
+            const templatePath = `templates/${relPath}`;
+            const decision = getContractDecision(templatePath);
+            // 可见性检查
+            if (decision.decision === "denied") {
+                recordConsumptionTrace({ consumer: "knowledge_index", asset_id: entry.name, asset_path: templatePath, contract_decision: "denied", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: `内置资产可见性不允许索引: ${decision.contract?.asset_visibility ?? "denied"}`, task_id_or_pipeline_id: "filterBuiltinEntries", consumed_at: new Date().toISOString() });
+                blocked.push(`[内部] ${entry.name} — 可见性不允许索引`);
+                continue;
+            }
+            // 技术栈适用性检查
+            if (decision.contract?.applicable_tech_stack && decision.contract.applicable_tech_stack.length > 0) {
+                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: templatePath, 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: "filterBuiltinEntries", 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: templatePath, contract_decision: "allowed", fields_consumed: ["asset_path", "contract_decision", "entry_type"], matched_reason: "内置资产通过可见性和技术栈检查", task_id_or_pipeline_id: "filterBuiltinEntries", consumed_at: new Date().toISOString(), declared_consumer: decision.contract?.mainline_consumer });
+            filtered.push(entry);
+        }
+        if (blocked.length > 0) {
+            debugLog(`知识索引: 内置资产门禁过滤 ${blocked.length} 条:`);
+            for (const b of blocked)
+                debugLog(`  ${b}`);
+        }
+        return filtered;
+    }
+    /** 从绝对路径提取 templates/ 下的相对路径 */
+    toBuiltinRelPath(absPath) {
+        const marker = "/templates/";
+        const idx = absPath.indexOf(marker);
+        if (idx < 0)
+            return null;
+        return absPath.substring(idx + marker.length);
+    }
+    getProjectTechStack() {
+        const stack = [];
+        const b = this.config.tech_stack?.backend;
+        const f = this.config.tech_stack?.frontend;
+        if (b?.lang)
+            stack.push(b.lang.toLowerCase());
+        if (b?.framework)
+            stack.push(b.framework.toLowerCase());
+        if (f?.lang)
+            stack.push(f.lang.toLowerCase());
+        if (f?.framework)
+            stack.push(f.framework.toLowerCase());
+        return stack;
+    }
+    /**
+     * 启动文件监听（内部方法）。
+     * @description 使用 chokidar 监听全局和项目知识目录的文件变更，
+     *              变更后 300ms 防抖执行增量更新。
+     */
+    async startWatching() {
+        if (!this.watchEnabled || this.closed)
+            return;
+        const dirs = [];
+        const globalDir = getGlobalPatternsDir();
+        const projectDir = getProjectKnowledgeDir(this.config);
+        if (fss.existsSync(globalDir))
+            dirs.push(globalDir);
+        if (fss.existsSync(projectDir))
+            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");
+        }
+        catch {
+            debugLog("索引管理器: chokidar 未安装，跳过文件监听。");
+            return;
+        }
+        if (this.closed || !this.watchEnabled)
+            return;
+        if (this.watcher) {
+            await this.watcher.close();
+        }
+        this.watcher = chokidar.watch(dirs, {
+            ignoreInitial: true,
+            persistent: true,
+            awaitWriteFinish: { stabilityThreshold: 500 },
+        });
+        this.watcher.on("error", (error) => {
+            this.watchEnabled = false;
+            const failedWatcher = this.watcher;
+            this.watcher = null;
+            void failedWatcher?.close().catch((e) => { debugLog(`索引管理器: 关闭监听器失败 — ${String(e)}`); });
+            const err = error;
+            debugLog(`索引管理器: 文件监听失败，已降级为手动重建模式 — ${err.code ?? "UNKNOWN"} ${err.message ?? ""}`.trim());
+        });
+        // KIM-003修复：使用 Set 累积防抖窗口内的所有变更文件，防止批量操作（如 git checkout）丢失事件
+        const pendingFiles = new Set();
+        this.watcher.on("all", (event, filePath) => {
+            if (!WATCH_EVENTS.has(event))
+                return;
+            if (this.rebuildInProgress) {
+                // 重建期间不丢弃事件，设置标志待重建完成后重新触发
+                this.pendingRebuild = true;
+                return;
+            }
+            pendingFiles.add(filePath);
+            if (this.rebuildTimer)
+                clearTimeout(this.rebuildTimer);
+            this.rebuildTimer = setTimeout(() => {
+                this.rebuildTimer = null;
+                const files = [...pendingFiles];
+                pendingFiles.clear();
+                // 批量处理所有累积的变更文件
+                for (const fp of files) {
+                    this.applyIncrementalUpdate("change", fp).catch((e) => {
+                        debugLog("索引管理器: 增量更新失败 —", e);
+                    });
+                }
+                debugLog(`索引管理器: 防抖批量处理 ${files.length} 个变更文件。`);
+            }, 300);
+        });
+        debugLog("索引管理器: 文件监听已启动。");
+    }
+    /**
+     * 重建文件路径到条目的映射（内部方法）。
+     */
+    rebuildEntryMap() {
+        this.filePathToEntryMap.clear();
+        for (const entry of [...this.index.project_entries, ...this.index.global_entries, ...this.index.builtin_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.byDomain.clear();
+        this.invertedIndex.activeIds.clear();
+        this.invertedIndex.byId.clear();
+        this.invertedIndex.byKeyword.clear();
+        for (const entry of [...this.index.project_entries, ...this.index.global_entries, ...this.index.builtin_entries]) {
+            this.invertedIndex.byId.set(entry.id, entry);
+            if (entry.status === "active") {
+                this.invertedIndex.activeIds.add(entry.id);
+            }
+            for (const s of entry.scope ?? [])
+                this.addToIndex(this.invertedIndex.byScope, s, entry.id);
+            for (const p of entry.products ?? [])
+                this.addToIndex(this.invertedIndex.byProduct, p, entry.id);
+            if (entry.type)
+                this.addToIndex(this.invertedIndex.byType, entry.type, entry.id);
+            // 域索引：从 entry.domain 数组填充 byDomain 倒排索引
+            for (const d of entry.domain ?? [])
+                this.addToIndex(this.invertedIndex.byDomain, d, entry.id);
+            // KIM-002修复：提取关键词并建立倒排索引（关键词来自 name 和 triggers）
+            this.indexKeywordsForEntry(entry);
+        }
+    }
+    /**
+     * 向倒排索引添加映射关系（通用辅助方法）。
+     */
+    addToIndex(idx, key, id) {
+        let set = idx.get(key);
+        if (!set) {
+            set = new Set();
+            idx.set(key, set);
+        }
+        set.add(id);
+    }
+    /**
+     * KIM-002修复：为单个条目提取关键词并填充到 byKeyword 倒排索引。
+     * 关键词来源：name 的空格分词、triggers 的空格分词。
+     * 中文场景：对 name 做所有长度 >= 2 的子串索引（因中文无空格分词）。
+     */
+    indexKeywordsForEntry(entry) {
+        const text = `${entry.name} ${entry.triggers?.join(" ") ?? ""}`.toLowerCase();
+        // 空格分词（英文及混合场景）
+        const words = text.split(/\s+/).filter(w => w.length >= 2);
+        for (const word of words) {
+            this.addToIndex(this.invertedIndex.byKeyword, word, entry.id);
+        }
+        // 中文子串索引：对 name 生成所有长度 >= 2 的子串
+        // 避免对 triggers 重复索引（triggers 已经通过空格分词覆盖）
+        const nameLower = entry.name.toLowerCase();
+        if (/[一-鿿]/.test(nameLower)) {
+            for (let start = 0; start < nameLower.length; start++) {
+                for (let end = start + 2; end <= nameLower.length; end++) {
+                    const substr = nameLower.substring(start, end);
+                    this.addToIndex(this.invertedIndex.byKeyword, substr, entry.id);
+                }
+            }
+        }
+    }
+    /**
+     * 应用增量更新（内部方法）。
+     * @description 根据文件系统事件对索引进行增量更新：
+     *              删除事件移除条目，新增/修改事件重新解析并更新条目。
+     * @param event - 文件系统事件类型
+     * @param filePath - 变更的文件路径
+     */
+    async applyIncrementalUpdate(event, filePath) {
+        if (!/\.(md|ya?ml)$/.test(filePath))
+            return;
+        this.index.built_at = new Date().toISOString();
+        const globalDir = getGlobalPatternsDir();
+        const builtinDir = getBuiltinKnowledgeDir();
+        let entries;
+        if (isSameOrDescendantPath(filePath, globalDir)) {
+            entries = this.index.global_entries;
+        }
+        else if (isSameOrDescendantPath(filePath, builtinDir)) {
+            entries = this.index.builtin_entries;
+        }
+        else {
+            entries = this.index.project_entries;
+        }
+        if (event === "unlink" || event === "unlinkDir") {
+            const idx = entries.findIndex((e) => e.file_path === filePath);
+            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 isBuiltin = isSameOrDescendantPath(filePath, builtinDir);
+            const filtered = isBuiltin
+                ? await this.filterBuiltinEntries(newEntries)
+                : await this.filterByContractGate(newEntries);
+            for (const newEntry of filtered) {
+                const existingIdx = entries.findIndex((e) => e.file_path === filePath);
+                if (existingIdx !== -1) {
+                    entries[existingIdx] = newEntry;
+                }
+                else {
+                    entries.push(newEntry);
+                }
+                this.filePathToEntryMap.set(filePath, newEntry);
+            }
+            // P1-C1: 增量重建倒排索引
+            this.rebuildInvertedIndex();
+            debugLog(`索引管理器: 文件变更已更新 — ${filePath}`);
+        }
+        catch {
+            // 跳过解析失败的文件
+            debugLog(`索引管理器: 解析文件失败 — ${filePath}`);
+        }
+    }
+    /**
+     * 解析单个知识文件（内部方法）。
+     * @description 根据文件扩展名选择解析器：Markdown 使用 gray-matter 解析 frontmatter，
+     *              YAML 使用 YAML.parse 解析。
+     * @param filePath - 文件路径
+     * @returns 解析后的知识条目数组
+     */
+    async parseFile(filePath) {
+        const entries = [];
+        try {
+            if (filePath.endsWith(".md")) {
+                const raw = await fs.readFile(filePath, "utf-8");
+                const { data, content } = matter(raw);
+                entries.push(this.parseEntry(data, filePath, content));
+            }
+            else if (filePath.endsWith(".yaml") || filePath.endsWith(".yml")) {
+                const content = await fs.readFile(filePath, "utf-8");
+                const data = YAML.parse(content);
+                entries.push(this.parseEntry(data, filePath));
+            }
+        }
+        catch {
+            // 跳过格式异常的文件
+        }
+        return entries;
+    }
+    /**
+     * 按条件查询知识条目。
+     * @description 支持按 scope、products、type 过滤，以及按 keywords 关键词匹配和排序。
+     *              只返回 status 为 active 的条目，默认限制返回 5 条。
+     * @param filters - 查询过滤条件
+     * @param filters.scope - 作用域过滤列表
+     * @param filters.products - 产品过滤列表
+     * @param filters.type - 条目类型过滤
+     * @param filters.keywords - 关键词列表（用于模糊匹配 name 和 when 字段）
+     * @param filters.limit - 最大返回条数，默认 5
+     * @returns 匹配的知识条目数组
+     */
+    query(filters) {
+        debugLog("知识索引: 查询知识条目");
+        // 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());
+        }
+        // 域过滤（domain 字段缺失视为不限定，纳入候选，等价原 stages:["*"] 通配语义）
+        if (filters.domain?.length) {
+            const domainIds = new Set();
+            for (const d of filters.domain) {
+                const set = this.invertedIndex.byDomain.get(d);
+                if (set)
+                    for (const id of set)
+                        domainIds.add(id);
+            }
+            // domain 字段缺失视为不限定，纳入候选
+            for (const [id, entry] of this.invertedIndex.byId) {
+                if (!entry.domain || entry.domain.length === 0)
+                    domainIds.add(id);
+            }
+            candidateSets.push(domainIds);
+        }
+        // 取所有集合的交集
+        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)));
+        }
+        // KIM-002修复：关键词匹配已改为 O(1) 倒排索引查找，不再需要 O(k) 线性扫描
+        let results;
+        if (filters.keywords?.length) {
+            // 对每个查询关键词，通过 byKeyword 倒排索引 O(1) 查找匹配的条目 id 集合
+            // 然后统计每个 id 被命中的次数作为评分
+            const scoreMap = new Map();
+            for (const kw of filters.keywords) {
+                const lowerKw = kw.toLowerCase();
+                // 先尝试精确词匹配（空格分词后的单词）
+                const exactSet = this.invertedIndex.byKeyword.get(lowerKw);
+                if (exactSet) {
+                    for (const id of exactSet) {
+                        scoreMap.set(id, (scoreMap.get(id) ?? 0) + 1);
+                    }
+                }
+                // 中文子串匹配：查找所有以 lowerKw 为子串的关键词桶
+                if (/[一-鿿]/.test(lowerKw)) {
+                    for (const [indexedKw, ids] of this.invertedIndex.byKeyword) {
+                        if (indexedKw !== lowerKw && indexedKw.includes(lowerKw)) {
+                            for (const id of ids) {
+                                scoreMap.set(id, (scoreMap.get(id) ?? 0) + 1);
+                            }
+                        }
+                    }
+                }
+                else {
+                    // 英文场景：也对包含该词的关键词桶做子串匹配（兼容复合词场景）
+                    // 仅当精确匹配未命中时才做子串匹配，减少不必要的扫描
+                    if (!exactSet) {
+                        for (const [indexedKw, ids] of this.invertedIndex.byKeyword) {
+                            if (indexedKw !== lowerKw && (indexedKw.includes(lowerKw) || lowerKw.includes(indexedKw))) {
+                                for (const id of ids) {
+                                    scoreMap.set(id, (scoreMap.get(id) ?? 0) + 1);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            // 交集约束：只保留同时在 candidateIds 中的条目
+            const scored = [];
+            for (const [id, score] of scoreMap) {
+                if (!candidateIds.has(id))
+                    continue;
+                const entry = this.invertedIndex.byId.get(id);
+                if (entry && 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);
+    }
+    /**
+     * 标记知识条目为已使用。
+     * @description 增加指定条目的 usage_count 并更新 last_used_at 时间戳。
+     * @param entryIds - 要标记的条目 ID 列表
+     */
+    persistUsedTimer = null;
+    static PERSIST_USED_DEBOUNCE_MS = 500;
+    markUsed(entryIds) {
+        const idSet = new Set(entryIds);
+        const now = new Date().toISOString();
+        for (const entry of [...this.index.project_entries, ...this.index.global_entries, ...this.index.builtin_entries]) {
+            if (idSet.has(entry.id)) {
+                entry.usage_count = (entry.usage_count ?? 0) + 1;
+                entry.last_used_at = now;
+            }
+        }
+        debugLog(`索引管理器: 已标记 ${entryIds.length} 条知识为已使用。`);
+        // 防抖持久化：500ms 延迟，合并短时间内的多次 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);
+    }
+    /**
+     * KIM-001修复：刷新待持久化的 markUsed 变更。
+     * 在进程退出信号和 beforeExit 时调用，确保防抖窗口内的使用计数不丢失。
+     *
+     * 注意：此回调对 SIGKILL / OOM 无效（不可拦截信号），500ms 防抖窗口内的数据仍可能丢失。
+     * 这是内存防抖方案的固有限制，500ms 窗口是 IO 频率与数据安全的平衡点。
+     */
+    flushPendingUsageUpdates() {
+        if (this.persistUsedTimer) {
+            clearTimeout(this.persistUsedTimer);
+            this.persistUsedTimer = null;
+            // 同步写入，进程即将退出时无法等待 Promise
+            const entries = [...this.index.project_entries, ...this.index.global_entries, ...this.index.builtin_entries]
+                .filter(e => e.file_path && fss.existsSync(e.file_path));
+            for (const entry of entries) {
+                try {
+                    const ext = path.extname(entry.file_path);
+                    if (ext === ".md") {
+                        const raw = fss.readFileSync(entry.file_path, "utf-8");
+                        const { data, content } = matter(raw);
+                        data.last_used_at = entry.last_used_at;
+                        data.usage_count = entry.usage_count;
+                        fss.writeFileSync(entry.file_path, matter.stringify(content, data), "utf-8");
+                    }
+                    else if (ext === ".yaml" || ext === ".yml") {
+                        const raw = fss.readFileSync(entry.file_path, "utf-8");
+                        const data = YAML.parse(raw);
+                        data.last_used_at = entry.last_used_at;
+                        data.usage_count = entry.usage_count;
+                        fss.writeFileSync(entry.file_path, YAML.stringify(data), "utf-8");
+                    }
+                }
+                catch { /* 静默失败，进程退出时尽力而为 */ }
+            }
+        }
+    }
+    /**
+     * 将 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, ...this.index.builtin_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 获取知识条目。
+     * @param id - 条目 ID
+     * @returns 匹配的知识条目，未找到则返回 undefined
+     */
+    getEntry(id) {
+        debugLog("知识索引: 获取条目 — " + 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);
+    }
+    /**
+     * 获取所有知识条目（按来源分组）。
+     * @returns 包含全局和项目知识条目的对象
+     */
+    getAllEntries() {
+        debugLog("知识索引: 获取所有条目");
+        return {
+            global: this.index.global_entries,
+            project: this.index.project_entries,
+            builtin: this.index.builtin_entries,
+        };
+    }
+    /**
+     * 在内存中添加知识条目。
+     * @param entry - 要添加的知识条目
+     */
+    async addEntryInMemory(entry) {
+        debugLog("知识索引: 内存添加条目 — " + entry.name);
+        this.index.project_entries.push(entry);
+        this.filePathToEntryMap.set(entry.file_path, entry);
+        // 重建倒排索引，确保 query() 能找到新条目
+        this.rebuildInvertedIndex();
+    }
+    /**
+     * 重新加载知识索引。
+     * @description 完全重建索引，重新扫描所有知识文件。
+     */
+    async reload() {
+        debugLog("索引管理器: 重新加载索引...");
+        await this.build();
+    }
+    /**
+     * 执行知识健康检查和冲突检测。
+     * @description 检查所有知识条目的健康状态（过期、零使用），
+     *              对活跃项目条目执行冲突检测和元数据冲突检测，
+     *              并将状态变更持久化到磁盘。
+     *              CROSS-003修复：新增 detectMetadataConflicts 调用，检测 scope 交叉但 products 互斥的条目。
+     * @returns 包含健康问题和冲突的数组
+     */
+    async checkHealth() {
+        debugLog("索引管理器: 执行健康检查...");
+        const all = [...this.index.project_entries, ...this.index.global_entries, ...this.index.builtin_entries];
+        // 偏差 5 修复：新项目（<30天）放宽零使用降级阈值，避免初期知识被误降级
+        const projectAgeMs = this.estimateProjectAgeMs();
+        const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
+        const healthOptions = projectAgeMs < THIRTY_DAYS_MS
+            ? { zero_usage_threshold_ms: 90 * 24 * 60 * 60 * 1000 } // 新项目：90天
+            : undefined;
+        const issues = checkKnowledgeHealth(all, healthOptions);
+        const activeProject = this.index.project_entries.filter((e) => e.status === "active");
+        issues.push(...detectConflicts(activeProject));
+        // CROSS-003修复：调用 detectMetadataConflicts，将元数据冲突纳入健康报告
+        const metadataConflicts = detectMetadataConflicts(all.filter((e) => e.status === "active"));
+        if (metadataConflicts.length > 0) {
+            // 去重：同一 entry+issue 组合只保留一条
+            const seen = new Set();
+            for (const mc of metadataConflicts) {
+                const key = `${mc.entry.id}:${mc.issue}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    issues.push({ entry: mc.entry, issue: mc.issue });
+                }
+            }
+            debugLog(`索引管理器: 元数据冲突检测发现 ${metadataConflicts.length / 2} 对冲突。`);
+        }
+        await persistHealthChanges(issues);
+        debugLog(`索引管理器: 健康检查完成 — 发现 ${issues.length} 个问题。`);
+        return issues;
+    }
+    /**
+     * 估算项目年龄（毫秒）。
+     * 取最早的知识条目创建时间作为项目起点。
+     * 无条目时返回 Infinity，视为极老项目，不触发新项目保护。
+     */
+    estimateProjectAgeMs() {
+        const all = [...this.index.project_entries, ...this.index.global_entries, ...this.index.builtin_entries];
+        if (all.length === 0)
+            return Infinity;
+        const earliest = all.reduce((min, e) => {
+            const t = new Date(e.created_at).getTime();
+            return t < min ? t : min;
+        }, Infinity);
+        return earliest === Infinity ? Infinity : Date.now() - earliest;
+    }
+    /**
+     * 扫描目录中的知识文件（内部方法）。
+     * @description 递归遍历目录，解析所有 .md 和 .yaml/.yml 文件。
+     * @param dir - 要扫描的目录路径
+     * @returns 解析后的知识条目数组
+     */
+    async scanDirectory(dir) {
+        const entries = [];
+        try {
+            await fs.access(dir);
+        }
+        catch {
+            return entries;
+        }
+        const files = await this.walkFiles(dir);
+        for (const file of files) {
+            const parsed = await this.parseFile(file);
+            entries.push(...parsed);
+        }
+        return entries;
+    }
+    /**
+     * 将原始数据解析为知识条目（内部方法）。
+     * @description 从 frontmatter/解析数据中提取字段，缺失字段使用默认值。
+     * @param data - 解析后的 frontmatter 或 YAML 数据
+     * @param filePath - 文件路径
+     * @param body - Markdown 正文内容（可选）
+     * @returns 解析后的知识条目
+     */
+    parseEntry(data, filePath, body) {
+        return {
+            id: typeof data.id === "string" ? data.id : typeof data.name === "string" ? data.name : path.basename(filePath, path.extname(filePath)),
+            file_path: filePath,
+            name: typeof data.name === "string" ? data.name : path.basename(filePath, path.extname(filePath)),
+            type: normalizeType(typeof data.type === "string" ? data.type : this.inferType(filePath)),
+            triggers: Array.isArray(data.triggers) ? data.triggers : [],
+            body: body || undefined,
+            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"),
+            domain: Array.isArray(data.domain)
+                ? data.domain.filter((s) => typeof s === "string")
+                : typeof data.domain === "string"
+                    ? data.domain.split(",").map((s) => s.trim()).filter(Boolean)
+                    : undefined,
+            verification_layer: (typeof data.verification_layer === "string" ? data.verification_layer : undefined),
+            probe: typeof data.probe === "string" ? data.probe : undefined,
+            probe_path: typeof data.probe_path === "string" ? data.probe_path : undefined,
+        };
+    }
+    /**
+     * 根据文件路径推断知识条目类型（内部方法）。
+     * @description 根据路径中包含的目录名推断条目类型。
+     *              KIM-007说明：inferType 与 normalizeType 的职责不同，不应合并：
+     *              - normalizeType: 将 frontmatter 中的 type 字段值映射到标准枚举（字段级映射）
+     *              - inferType: 当 frontmatter 中 type/asset_kind 缺失时，根据文件路径目录名推断类型（路径级推断）
+     *              两者是互补关系，parseEntry 中优先使用 normalizeType，仅当两者都无法命中时才 fallback 到 inferType。
+     * @param filePath - 文件路径
+     * @returns 推断出的知识条目类型
+     */
+    inferType(filePath) {
+        const parts = filePath.split(path.sep);
+        if (parts.includes("patterns"))
+            return "pattern";
+        if (parts.includes("procedures"))
+            return "procedure";
+        if (parts.includes("domain"))
+            return "domain";
+        if (parts.includes("acceptance_templates"))
+            return "acceptance_template";
+        if (parts.includes("governance"))
+            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";
+    }
+    /**
+     * 导出能力注册表的治理规则为 review_rule 条目，用于知识审计。
+     * @description 将能力治理规则转换为可在知识索引中查询的条目格式。
+     * @param caps - 能力规则数组
+     * @param caps.policy_id - 策略 ID
+     * @param caps.name - 策略名称
+     * @param caps.state - 策略状态
+     * @param caps.owner_module - 所属模块
+     * @param caps.evidence - 证据描述
+     * @param caps.promotion_conditions - 晋级条件列表
+     * @param caps.demotion_conditions - 降级条件列表
+     * @param caps.evidence_requirements - 证据要求列表
+     * @param caps.reason - 原因说明
+     * @returns 格式化后的治理规则条目数组
+     */
+    exportGovernanceRules(caps) {
+        debugLog("知识索引: 导出治理规则 — 条数: " + caps.length);
+        return caps.map((cap) => ({
+            name: `${cap.policy_id}: ${cap.name}`,
+            type: "governance_rule",
+            scope: cap.owner_module,
+            content: [
+                `# ${cap.policy_id}: ${cap.name}`,
+                ``,
+                `状态: ${cap.state}`,
+                `模块: ${cap.owner_module}`,
+                `证据: ${cap.evidence}`,
+                ``,
+                `## 晋级条件`,
+                ...cap.promotion_conditions.map((c) => `- ${c}`),
+                ``,
+                `## 降级条件`,
+                ...cap.demotion_conditions.map((c) => `- ${c}`),
+                ``,
+                `## 证据要求`,
+                ...cap.evidence_requirements.map((e) => `- ${e}`),
+                ``,
+                `## 原因`,
+                cap.reason,
+            ].join("\n"),
+        }));
+    }
+    /**
+     * 递归遍历目录获取文件列表（内部方法）。
+     * @description 递归遍历目录，收集所有 .md 和 .yaml/.yml 文件路径。
+     *              自动跳过 SKIP_DIRS 中定义的系统目录。
+     * @param dir - 要遍历的目录
+     * @param maxDepth - 最大递归深度，默认 10
+     * @param currentDepth - 当前递归深度
+     * @returns 文件路径数组
+     */
+    async walkFiles(dir, maxDepth = 10, currentDepth = 0) {
+        if (currentDepth >= maxDepth)
+            return [];
+        const results = [];
+        let dirEntries;
+        try {
+            dirEntries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return results;
+        }
+        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)));
+            }
+            else if (/\.(md|ya?ml)$/.test(entry.name)) {
+                results.push(fullPath);
+            }
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=index_manager.js.map