soloforge 1.2.7 → 1.2.9

package/dist/knowledge/health_checker.js

@@ -3,6 +3,15 @@ import fss from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
 import YAML from "yaml";
+/**
+ * 检查知识条目的健康状态。
+ * @description 遍历所有知识条目，检测两类健康问题：
+ *              1. 90 天未使用的活跃条目自动标记为 pending_review
+ *              2. 创建 7 天后仍零使用的活跃条目自动标记为 pending_review
+ *              直接修改条目的 status 字段并返回问题列表。
+ * @param entries - 待检查的知识条目列表
+ * @returns 包含健康问题信息的数组，每项包含问题条目和问题类型（stale_90d 或 zero_usage）
+ */
 export function checkKnowledgeHealth(entries) {
     const issues = [];
     const now = Date.now();
@@ -25,10 +34,22 @@ export function checkKnowledgeHealth(entries) {
             }
         }
     }
+    if (issues.length > 0) {
+        console.error(`[soloForge] 健康检查: 发现 ${issues.length} 个健康问题。`);
+    }
     return issues;
 }
-// 将健康检查导致的状态变更持久化到磁盘
+/**
+ * 将健康检查导致的状态变更持久化到磁盘。
+ * @description 遍历所有健康检查发现的问题条目，将其 status 和 updated_at 写回对应的文件。
+ *              支持 Markdown（frontmatter）和 YAML 两种格式。使用原子写入（先写 .tmp 再 rename）。
+ *              单文件写入失败不影响其他文件的处理。
+ * @param issues - 健康检查返回的问题列表
+ */
 export async function persistHealthChanges(issues) {
+    if (issues.length === 0)
+        return;
+    console.error(`[soloForge] 健康检查: 持久化 ${issues.length} 条状态变更...`);
     for (const { entry } of issues) {
         if (!entry.file_path || !fss.existsSync(entry.file_path))
             continue;
@@ -55,7 +76,9 @@ export async function persistHealthChanges(issues) {
         }
         catch {
             // 单文件写入失败不影响其他文件
+            console.error(`[soloForge] 健康检查: 写入文件失败 — ${entry.file_path}`);
         }
     }
+    console.error("[soloForge] 健康检查: 状态变更持久化完成。");
 }
 //# sourceMappingURL=health_checker.js.map

package/dist/knowledge/health_checker.js.map

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

package/dist/knowledge/index_manager.d.ts

@@ -1,18 +1,80 @@
 import type { ProjectConfig, KnowledgeEntry } from "../types.js";
+/**
+ * 知识索引构建选项。
+ */
+export interface KnowledgeIndexOptions {
+    /** 是否启用文件监听，默认 true */
+    watch?: boolean;
+}
+/**
+ * 知识索引管理器。
+ * @description 负责扫描、解析、索引知识文件（Markdown 和 YAML），
+ *              支持增量更新（文件监听）和按条件查询。
+ *              同时提供健康检查和冲突检测功能。
+ */
 export declare class KnowledgeIndexManager {
     private config;
     private index;
     private watcher;
     private rebuildTimer;
     private watchingStarted;
+    private watchEnabled;
+    private closed;
     private filePathToEntryMap;
-    constructor(config: ProjectConfig);
+    /**
+     * 创建知识索引管理器实例。
+     * @param config - 项目配置对象
+     * @param options - 索引构建选项
+     */
+    constructor(config: ProjectConfig, options?: KnowledgeIndexOptions);
+    /**
+     * 构建知识索引。
+     * @description 扫描全局和项目知识目录，解析所有知识文件并建立索引。
+     *              首次构建时启动文件监听。
+     */
     build(): Promise<void>;
+    /**
+     * 关闭索引管理器，停止文件监听并清理资源。
+     */
     close(): Promise<void>;
+    /**
+     * 启动文件监听（内部方法）。
+     * @description 使用 chokidar 监听全局和项目知识目录的文件变更，
+     *              变更后 300ms 防抖执行增量更新。
+     */
     private startWatching;
+    /**
+     * 重建文件路径到条目的映射（内部方法）。
+     */
     private rebuildEntryMap;
+    /**
+     * 应用增量更新（内部方法）。
+     * @description 根据文件系统事件对索引进行增量更新：
+     *              删除事件移除条目，新增/修改事件重新解析并更新条目。
+     * @param event - 文件系统事件类型
+     * @param filePath - 变更的文件路径
+     */
     private applyIncrementalUpdate;
+    /**
+     * 解析单个知识文件（内部方法）。
+     * @description 根据文件扩展名选择解析器：Markdown 使用 gray-matter 解析 frontmatter，
+     *              YAML 使用 YAML.parse 解析。
+     * @param filePath - 文件路径
+     * @returns 解析后的知识条目数组
+     */
     private parseFile;
+    /**
+     * 按条件查询知识条目。
+     * @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: {
         scope?: string[];
         products?: string[];
@@ -20,24 +82,91 @@ export declare class KnowledgeIndexManager {
         keywords?: string[];
         limit?: number;
     }): KnowledgeEntry[];
+    /**
+     * 标记知识条目为已使用。
+     * @description 增加指定条目的 usage_count 并更新 last_used_at 时间戳。
+     * @param entryIds - 要标记的条目 ID 列表
+     */
     markUsed(entryIds: string[]): void;
+    /**
+     * 根据 ID 获取知识条目。
+     * @param id - 条目 ID
+     * @returns 匹配的知识条目，未找到则返回 undefined
+     */
     getEntry(id: string): KnowledgeEntry | undefined;
+    /**
+     * 获取所有知识条目（按来源分组）。
+     * @returns 包含全局和项目知识条目的对象
+     */
     getAllEntries(): {
         global: KnowledgeEntry[];
         project: KnowledgeEntry[];
     };
+    /**
+     * 在内存中添加知识条目。
+     * @param entry - 要添加的知识条目
+     */
     addEntryInMemory(entry: KnowledgeEntry): Promise<void>;
+    /**
+     * 重新加载知识索引。
+     * @description 完全重建索引，重新扫描所有知识文件。
+     */
     reload(): Promise<void>;
+    /**
+     * 执行知识健康检查和冲突检测。
+     * @description 检查所有知识条目的健康状态（过期、零使用），
+     *              对活跃项目条目执行冲突检测，并将状态变更持久化到磁盘。
+     * @returns 包含健康问题和冲突的数组
+     */
     checkHealth(): Promise<Array<{
         entry: KnowledgeEntry;
         issue: string;
     }>>;
+    /**
+     * 计算关键词匹配分数（内部方法）。
+     * @description 在条目的 name 和 when 字段中搜索关键词，返回匹配数。
+     * @param entry - 知识条目
+     * @param keywords - 关键词列表
+     * @returns 匹配的关键词数量
+     */
     private keywordScore;
+    /**
+     * 扫描目录中的知识文件（内部方法）。
+     * @description 递归遍历目录，解析所有 .md 和 .yaml/.yml 文件。
+     * @param dir - 要扫描的目录路径
+     * @returns 解析后的知识条目数组
+     */
     private scanDirectory;
+    /**
+     * 将原始数据解析为知识条目（内部方法）。
+     * @description 从 frontmatter/解析数据中提取字段，缺失字段使用默认值。
+     * @param data - 解析后的 frontmatter 或 YAML 数据
+     * @param filePath - 文件路径
+     * @param body - Markdown 正文内容（可选）
+     * @returns 解析后的知识条目
+     */
     private parseEntry;
+    /**
+     * 根据文件路径推断知识条目类型（内部方法）。
+     * @description 根据路径中包含的目录名推断条目类型。
+     * @param filePath - 文件路径
+     * @returns 推断出的知识条目类型
+     */
     private inferType;
     /**
-     * Export capability registry governance rules as review_rule entries for knowledge audit.
+     * 导出能力注册表的治理规则为 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: Array<{
         policy_id: string;
@@ -55,6 +184,15 @@ export declare class KnowledgeIndexManager {
         scope: string;
         content: string;
     }>;
+    /**
+     * 递归遍历目录获取文件列表（内部方法）。
+     * @description 递归遍历目录，收集所有 .md 和 .yaml/.yml 文件路径。
+     *              自动跳过 SKIP_DIRS 中定义的系统目录。
+     * @param dir - 要遍历的目录
+     * @param maxDepth - 最大递归深度，默认 10
+     * @param currentDepth - 当前递归深度
+     * @returns 文件路径数组
+     */
     private walkFiles;
 }
 //# sourceMappingURL=index_manager.d.ts.map

package/dist/knowledge/index_manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index_manager.d.ts","sourceRoot":"","sources":["../../src/knowledge/index_manager.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAkB,MAAM,aAAa,CAAC;AAQjF,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,OAAO,CAA4D;IAC3E,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,kBAAkB,CAA0C;gBAExD,MAAM,EAAE,aAAa;IAK3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B,OAAO,CAAC,aAAa;IA+BrB,OAAO,CAAC,eAAe;YAOT,sBAAsB;YAiCtB,SAAS;IAkBvB,KAAK,CAAC,OAAO,EAAE;QACb,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,cAAc,EAAE;IAoCpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI;IAWlC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAOhD,aAAa,IAAI;QAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QAAC,OAAO,EAAE,cAAc,EAAE,CAAA;KAAE;IAOlE,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAItD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvB,WAAW,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAY7E,OAAO,CAAC,YAAY;YAQN,aAAa;IAgB3B,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,SAAS;IAWjB;;OAEG;IACH,qBAAqB,CAAC,IAAI,EAAE,KAAK,CAAC;QAChC,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,oBAAoB,EAAE,MAAM,EAAE,CAAC;QAC/B,mBAAmB,EAAE,MAAM,EAAE,CAAC;QAC9B,qBAAqB,EAAE,MAAM,EAAE,CAAC;QAChC,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,GAAG,KAAK,CAAC;QACT,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,iBAAiB,CAAC;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;YA2BY,SAAS;CAsBxB"}
+{"version":3,"file":"index_manager.d.ts","sourceRoot":"","sources":["../../src/knowledge/index_manager.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAkB,MAAM,aAAa,CAAC;AAWjF;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,uBAAuB;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,OAAO,CAA4D;IAC3E,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,YAAY,CAAU;IAC9B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,kBAAkB,CAA0C;IAEpE;;;;OAIG;gBACS,MAAM,EAAE,aAAa,EAAE,OAAO,GAAE,qBAA0B;IAMtE;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B;;;;OAIG;YACW,aAAa;IAyC3B;;OAEG;IACH,OAAO,CAAC,eAAe;IAOvB;;;;;;OAMG;YACW,sBAAsB;IAoCpC;;;;;;OAMG;YACW,SAAS;IAkBvB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,OAAO,EAAE;QACb,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,cAAc,EAAE;IAqCpB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI;IAYlC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAQhD;;;OAGG;IACH,aAAa,IAAI;QAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QAAC,OAAO,EAAE,cAAc,EAAE,CAAA;KAAE;IAQxE;;;OAGG;IACG,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5D;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAK7B;;;;;OAKG;IACG,WAAW,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAc7E;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAQpB;;;;;OAKG;YACW,aAAa;IAgB3B;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;IAoBlB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAWjB;;;;;;;;;;;;;;OAcG;IACH,qBAAqB,CAAC,IAAI,EAAE,KAAK,CAAC;QAChC,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,oBAAoB,EAAE,MAAM,EAAE,CAAC;QAC/B,mBAAmB,EAAE,MAAM,EAAE,CAAC;QAC9B,qBAAqB,EAAE,MAAM,EAAE,CAAC;QAChC,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,GAAG,KAAK,CAAC;QACT,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,iBAAiB,CAAC;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IA4BF;;;;;;;;OAQG;YACW,SAAS;CAsBxB"}

package/dist/knowledge/index_manager.js

@@ -6,32 +6,59 @@ import YAML from "yaml";
 import { getProjectKnowledgeDir, getGlobalPatternsDir } from "./loader.js";
 import { checkKnowledgeHealth, persistHealthChanges } from "./health_checker.js";
 import { detectConflicts } from "./conflict_detector.js";
+/** 跳过的目录名集合 */
 const SKIP_DIRS = new Set(["node_modules", ".git", ".hg", ".svn", "__pycache__", ".DS_Store"]);
+/** 监听的文件系统事件类型集合 */
 const WATCH_EVENTS = new Set(["add", "change", "unlink", "unlinkDir"]);
+/**
+ * 知识索引管理器。
+ * @description 负责扫描、解析、索引知识文件（Markdown 和 YAML），
+ *              支持增量更新（文件监听）和按条件查询。
+ *              同时提供健康检查和冲突检测功能。
+ */
 export class KnowledgeIndexManager {
     config;
     index;
     watcher = null;
     rebuildTimer = null;
     watchingStarted = false;
+    watchEnabled;
+    closed = false;
     filePathToEntryMap = new Map();
-    constructor(config) {
+    /**
+     * 创建知识索引管理器实例。
+     * @param config - 项目配置对象
+     * @param options - 索引构建选项
+     */
+    constructor(config, options = {}) {
         this.config = config;
+        this.watchEnabled = options.watch ?? true;
         this.index = { version: 1, built_at: "", global_entries: [], project_entries: [] };
     }
+    /**
+     * 构建知识索引。
+     * @description 扫描全局和项目知识目录，解析所有知识文件并建立索引。
+     *              首次构建时启动文件监听。
+     */
     async build() {
+        console.error("[soloForge] 索引管理器: 开始构建知识索引...");
         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 = globalEntries;
         this.index.project_entries = projectEntries;
         this.rebuildEntryMap();
-        if (!this.watchingStarted) {
-            this.startWatching();
+        if (!this.watchingStarted && this.watchEnabled) {
+            await this.startWatching();
             this.watchingStarted = true;
         }
+        console.error(`[soloForge] 索引管理器: 索引构建完成 — 全局 ${globalEntries.length} 条，项目 ${projectEntries.length} 条。`);
     }
+    /**
+     * 关闭索引管理器，停止文件监听并清理资源。
+     */
     async close() {
+        this.closed = true;
         if (this.rebuildTimer) {
             clearTimeout(this.rebuildTimer);
             this.rebuildTimer = null;
@@ -40,8 +67,16 @@ export class KnowledgeIndexManager {
             await this.watcher.close();
             this.watcher = null;
         }
+        console.error("[soloForge] 索引管理器: 已关闭。");
     }
-    startWatching() {
+    /**
+     * 启动文件监听（内部方法）。
+     * @description 使用 chokidar 监听全局和项目知识目录的文件变更，
+     *              变更后 300ms 防抖执行增量更新。
+     */
+    async startWatching() {
+        if (!this.watchEnabled || this.closed)
+            return;
         const dirs = [];
         const globalDir = getGlobalPatternsDir();
         const projectDir = getProjectKnowledgeDir(this.config);
@@ -51,35 +86,52 @@ export class KnowledgeIndexManager {
             dirs.push(projectDir);
         if (dirs.length === 0)
             return;
-        import("chokidar").then(async ({ watch }) => {
-            if (this.watcher) {
-                await this.watcher.close();
-            }
-            this.watcher = watch(dirs, {
-                ignoreInitial: true,
-                persistent: true,
-                awaitWriteFinish: { stabilityThreshold: 500 },
-            });
-            this.watcher.on("all", (event, filePath) => {
-                if (!WATCH_EVENTS.has(event))
-                    return;
-                if (this.rebuildTimer)
-                    clearTimeout(this.rebuildTimer);
-                this.rebuildTimer = setTimeout(() => {
-                    this.applyIncrementalUpdate(event, filePath).catch(() => { });
-                    this.rebuildTimer = null;
-                }, 300);
-            });
-        }).catch(() => {
-            // chokidar 可选 — 热重载已禁用
+        let chokidar;
+        try {
+            chokidar = await import("chokidar");
+        }
+        catch {
+            console.error("[soloForge] 索引管理器: 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("all", (event, filePath) => {
+            if (!WATCH_EVENTS.has(event))
+                return;
+            if (this.rebuildTimer)
+                clearTimeout(this.rebuildTimer);
+            this.rebuildTimer = setTimeout(() => {
+                this.applyIncrementalUpdate(event, filePath).catch(() => { });
+                this.rebuildTimer = null;
+            }, 300);
         });
+        console.error("[soloForge] 索引管理器: 文件监听已启动。");
     }
+    /**
+     * 重建文件路径到条目的映射（内部方法）。
+     */
     rebuildEntryMap() {
         this.filePathToEntryMap.clear();
         for (const entry of [...this.index.project_entries, ...this.index.global_entries]) {
             this.filePathToEntryMap.set(entry.file_path, entry);
         }
     }
+    /**
+     * 应用增量更新（内部方法）。
+     * @description 根据文件系统事件对索引进行增量更新：
+     *              删除事件移除条目，新增/修改事件重新解析并更新条目。
+     * @param event - 文件系统事件类型
+     * @param filePath - 变更的文件路径
+     */
     async applyIncrementalUpdate(event, filePath) {
         if (!/\.(md|ya?ml)$/.test(filePath))
             return;
@@ -93,6 +145,7 @@ export class KnowledgeIndexManager {
             if (idx !== -1)
                 entries.splice(idx, 1);
             this.filePathToEntryMap.delete(filePath);
+            console.error(`[soloForge] 索引管理器: 文件已删除，移除索引条目 — ${filePath}`);
             return;
         }
         try {
@@ -107,11 +160,20 @@ export class KnowledgeIndexManager {
                 }
                 this.filePathToEntryMap.set(filePath, newEntry);
             }
+            console.error(`[soloForge] 索引管理器: 文件变更已更新 — ${filePath}`);
         }
         catch {
             // 跳过解析失败的文件
+            console.error(`[soloForge] 索引管理器: 解析文件失败 — ${filePath}`);
         }
     }
+    /**
+     * 解析单个知识文件（内部方法）。
+     * @description 根据文件扩展名选择解析器：Markdown 使用 gray-matter 解析 frontmatter，
+     *              YAML 使用 YAML.parse 解析。
+     * @param filePath - 文件路径
+     * @returns 解析后的知识条目数组
+     */
     async parseFile(filePath) {
         const entries = [];
         try {
@@ -131,7 +193,20 @@ export class KnowledgeIndexManager {
         }
         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) {
+        console.error("[soloForge] 知识索引: 查询知识条目");
         const all = [...this.index.project_entries, ...this.index.global_entries];
         const scopeSet = new Set(filters.scope ?? []);
         const productSet = new Set(filters.products ?? []);
@@ -167,6 +242,11 @@ export class KnowledgeIndexManager {
         }
         return results.slice(0, filters.limit ?? 5);
     }
+    /**
+     * 标记知识条目为已使用。
+     * @description 增加指定条目的 usage_count 并更新 last_used_at 时间戳。
+     * @param entryIds - 要标记的条目 ID 列表
+     */
     markUsed(entryIds) {
         const idSet = new Set(entryIds);
         const now = new Date().toISOString();
@@ -176,31 +256,69 @@ export class KnowledgeIndexManager {
                 entry.last_used_at = now;
             }
         }
+        console.error(`[soloForge] 索引管理器: 已标记 ${entryIds.length} 条知识为已使用。`);
     }
+    /**
+     * 根据 ID 获取知识条目。
+     * @param id - 条目 ID
+     * @returns 匹配的知识条目，未找到则返回 undefined
+     */
     getEntry(id) {
+        console.error("[soloForge] 知识索引: 获取条目 — " + id);
         return (this.index.project_entries.find((e) => e.id === id) ||
             this.index.global_entries.find((e) => e.id === id));
     }
+    /**
+     * 获取所有知识条目（按来源分组）。
+     * @returns 包含全局和项目知识条目的对象
+     */
     getAllEntries() {
+        console.error("[soloForge] 知识索引: 获取所有条目");
         return {
             global: this.index.global_entries,
             project: this.index.project_entries,
         };
     }
+    /**
+     * 在内存中添加知识条目。
+     * @param entry - 要添加的知识条目
+     */
     async addEntryInMemory(entry) {
+        console.error("[soloForge] 知识索引: 内存添加条目 — " + entry.name);
         this.index.project_entries.push(entry);
+        this.filePathToEntryMap.set(entry.file_path, entry);
     }
+    /**
+     * 重新加载知识索引。
+     * @description 完全重建索引，重新扫描所有知识文件。
+     */
     async reload() {
+        console.error("[soloForge] 索引管理器: 重新加载索引...");
         await this.build();
     }
+    /**
+     * 执行知识健康检查和冲突检测。
+     * @description 检查所有知识条目的健康状态（过期、零使用），
+     *              对活跃项目条目执行冲突检测，并将状态变更持久化到磁盘。
+     * @returns 包含健康问题和冲突的数组
+     */
     async checkHealth() {
+        console.error("[soloForge] 索引管理器: 执行健康检查...");
         const all = [...this.index.project_entries, ...this.index.global_entries];
         const issues = checkKnowledgeHealth(all);
         const activeProject = this.index.project_entries.filter((e) => e.status === "active");
         issues.push(...detectConflicts(activeProject));
         await persistHealthChanges(issues);
+        console.error(`[soloForge] 索引管理器: 健康检查完成 — 发现 ${issues.length} 个问题。`);
         return issues;
     }
+    /**
+     * 计算关键词匹配分数（内部方法）。
+     * @description 在条目的 name 和 when 字段中搜索关键词，返回匹配数。
+     * @param entry - 知识条目
+     * @param keywords - 关键词列表
+     * @returns 匹配的关键词数量
+     */
     keywordScore(entry, keywords) {
         const text = ` ${entry.name} ${entry.when} `.toLowerCase();
         return keywords.filter((kw) => {
@@ -208,6 +326,12 @@ export class KnowledgeIndexManager {
             return text.includes(` ${lowerKw} `) || text.startsWith(`${lowerKw} `) || text.endsWith(` ${lowerKw}`);
         }).length;
     }
+    /**
+     * 扫描目录中的知识文件（内部方法）。
+     * @description 递归遍历目录，解析所有 .md 和 .yaml/.yml 文件。
+     * @param dir - 要扫描的目录路径
+     * @returns 解析后的知识条目数组
+     */
     async scanDirectory(dir) {
         const entries = [];
         try {
@@ -223,6 +347,14 @@ export class KnowledgeIndexManager {
         }
         return entries;
     }
+    /**
+     * 将原始数据解析为知识条目（内部方法）。
+     * @description 从 frontmatter/解析数据中提取字段，缺失字段使用默认值。
+     * @param data - 解析后的 frontmatter 或 YAML 数据
+     * @param filePath - 文件路径
+     * @param body - Markdown 正文内容（可选）
+     * @returns 解析后的知识条目
+     */
     parseEntry(data, filePath, body) {
         return {
             id: data.name || path.basename(filePath, path.extname(filePath)),
@@ -242,6 +374,12 @@ export class KnowledgeIndexManager {
             status: data.status || "active",
         };
     }
+    /**
+     * 根据文件路径推断知识条目类型（内部方法）。
+     * @description 根据路径中包含的目录名推断条目类型。
+     * @param filePath - 文件路径
+     * @returns 推断出的知识条目类型
+     */
     inferType(filePath) {
         const parts = filePath.split(path.sep);
         if (parts.includes("patterns"))
@@ -259,9 +397,22 @@ export class KnowledgeIndexManager {
         return "pattern";
     }
     /**
-     * Export capability registry governance rules as review_rule entries for knowledge audit.
+     * 导出能力注册表的治理规则为 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) {
+        console.error("[soloForge] 知识索引: 导出治理规则 — 条数: " + caps.length);
         return caps.map((cap) => ({
             name: `${cap.policy_id}: ${cap.name}`,
             type: "governance_rule",
@@ -287,6 +438,15 @@ export class KnowledgeIndexManager {
             ].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 [];