soloforge 1.2.8 → 1.2.9

package/dist/engine/knowledge_manager.d.ts

@@ -1,16 +1,27 @@
 import type { KnowledgeIndexManager } from "../knowledge/index_manager.js";
 import type { ProjectConfig, KnowledgeEntry } from "../types.js";
+/** 审计发现项 */
 export interface AuditFinding {
+    /** 发现项 ID */
     id: string;
+    /** 严重程度 */
     severity: "info" | "warning" | "critical";
+    /** 问题类别: stale=陈旧, duplicate=重复, format=格式, coverage=覆盖, completeness=完整度, design_drift=设计漂移 */
     category: "stale" | "duplicate" | "format" | "coverage" | "completeness" | "design_drift";
+    /** 关联的知识条目名称 */
     entry_name: string;
+    /** 问题描述 */
     message: string;
+    /** 修复建议 */
     suggestion: string;
 }
+/** 审计结果 */
 export interface AuditResult {
+    /** 非废弃状态的条目总数 */
     total_entries: number;
+    /** 审计发现列表 */
     findings: AuditFinding[];
+    /** 各类别发现数量统计 */
     summary: {
         stale: number;
         duplicate: number;
@@ -19,58 +30,120 @@ export interface AuditResult {
         completeness: number;
         design_drift: number;
     };
+    /** 审计时间 */
     audited_at: string;
 }
+/**
+ * 审计知识库健康度。
+ * 检查五个维度: 陈旧条目、重复触发词、格式规范、类型覆盖、内容完整度。
+ * @param knowledgeIndex - 知识索引管理器
+ * @param config - 项目配置
+ * @returns 审计结果，包含发现项和统计摘要
+ */
 export declare function auditKnowledge(knowledgeIndex: KnowledgeIndexManager, config: ProjectConfig): Promise<AuditResult>;
+/** 新增知识条目的输入参数 */
 export interface AddKnowledgeInput {
+    /** 知识条目标题 */
     title: string;
+    /** 知识条目类型 */
     type: KnowledgeEntry["type"];
+    /** 作用域列表 */
     scope: string[];
+    /** 触发条件描述 */
     when_triggers: string;
+    /** 决策规则（可选） */
     decision_rules?: string;
+    /** 是否保存为草稿（默认 true） */
     save_to_drafts?: boolean;
+    /** 是否自动丰富内容（默认 true） */
     auto_enrich?: boolean;
 }
+/** 自动丰富指南的步骤 */
 export interface EnrichmentStep {
+    /** 步骤编号 */
     step_number: number;
+    /** 步骤描述 */
     action: string;
+    /** 搜索查询关键词 */
     search_queries?: string[];
+    /** 关注领域 */
     focus_areas: string[];
 }
+/** 自动丰富指南 */
 export interface EnrichmentGuide {
+    /** 关联的知识条目名称 */
     entry_name: string;
+    /** 知识类型 */
     type: KnowledgeEntry["type"];
+    /** 概述 */
     overview: string;
+    /** 丰富步骤列表 */
     steps: EnrichmentStep[];
+    /** 权威来源列表 */
     authoritative_sources: string[];
+    /** 完整度阈值要求 */
     completeness_thresholds: Array<{
         field: string;
         minimum: number;
     }>;
+    /** 更新调用模板 */
     update_call_template: string;
 }
+/** 新增知识条目的结果 */
 export interface AddKnowledgeResult {
+    /** 是否成功 */
     success: boolean;
+    /** 文件路径 */
     file_path: string;
+    /** 是否为草稿 */
     is_draft: boolean;
+    /** 结果消息 */
     message: string;
+    /** 自动丰富指南（可选） */
     enrichment_guide?: EnrichmentGuide;
 }
+/**
+ * 新增知识条目。
+ * 根据类型生成对应的模板内容，保存到草稿目录或正式目录。
+ * @param input - 新增知识条目输入
+ * @param config - 项目配置
+ * @returns 新增结果，包含文件路径和消息
+ */
 export declare function addKnowledge(input: AddKnowledgeInput, config: ProjectConfig): Promise<AddKnowledgeResult>;
+/** 更新知识条目的输入参数 */
 export interface UpdateKnowledgeInput {
+    /** 知识条目名称 */
     entry_name: string;
+    /** 更新内容 */
     updates: {
+        /** 更新触发条件 */
         when_triggers?: string;
+        /** 新增决策规则 */
         add_decision_rules?: string[];
+        /** 新增验收标准 */
         add_acceptance_criteria?: string[];
+        /** 更新状态 */
         status?: KnowledgeEntry["status"];
     };
 }
+/** 更新知识条目的结果 */
 export interface UpdateKnowledgeResult {
+    /** 是否成功 */
     success: boolean;
+    /** 文件路径 */
     file_path: string;
+    /** 备份路径 */
     backup_path: string;
+    /** 结果消息 */
     message: string;
 }
+/**
+ * 更新已有的知识条目。
+ * 更新前自动创建备份，支持修改触发条件、状态、决策规则和验收标准。
+ * @param input - 更新输入参数
+ * @param knowledgeIndex - 知识索引管理器
+ * @param config - 项目配置
+ * @returns 更新结果，包含文件路径和备份路径
+ */
 export declare function updateKnowledge(input: UpdateKnowledgeInput, knowledgeIndex: KnowledgeIndexManager, config: ProjectConfig): Promise<UpdateKnowledgeResult>;
 //# sourceMappingURL=knowledge_manager.d.ts.map

package/dist/engine/knowledge_manager.d.ts.map

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

package/dist/engine/knowledge_manager.js

@@ -3,13 +3,21 @@ import fss from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
 import { KnowledgeWriter } from "../knowledge/writer.js";
+/**
+ * 审计知识库健康度。
+ * 检查五个维度: 陈旧条目、重复触发词、格式规范、类型覆盖、内容完整度。
+ * @param knowledgeIndex - 知识索引管理器
+ * @param config - 项目配置
+ * @returns 审计结果，包含发现项和统计摘要
+ */
 export async function auditKnowledge(knowledgeIndex, config) {
+    console.error("[soloForge] 知识审计: 开始审计知识库健康度");
     const { global: globalEntries, project: projectEntries } = knowledgeIndex.getAllEntries();
     const all = [...globalEntries, ...projectEntries];
     const findings = [];
     const now = Date.now();
     let findingId = 0;
-    // 1. Stale entries: last_used_at > 90 days or usage_count === 0
+    // 1. 陈旧条目: 超过 90 天未使用或从未被匹配
     for (const entry of all) {
         if (entry.status === "deprecated")
             continue;
@@ -37,7 +45,7 @@ export async function auditKnowledge(knowledgeIndex, config) {
             }
         }
     }
-    // 2. Duplicate: similar when triggers
+    // 2. 重复检查: 相似触发词
     for (let i = 0; i < all.length; i++) {
         for (let j = i + 1; j < all.length; j++) {
             if (all[i].type !== all[j].type)
@@ -55,7 +63,7 @@ export async function auditKnowledge(knowledgeIndex, config) {
             }
         }
     }
-    // 3. Format: missing required frontmatter fields + schema validation
+    // 3. 格式检查: 缺失必需的 frontmatter 字段 + Schema 验证
     for (const entry of all) {
         if (entry.status === "deprecated")
             continue;
@@ -76,7 +84,7 @@ export async function auditKnowledge(knowledgeIndex, config) {
                 suggestion: `补充 ${issues.join("、")} 字段`,
             });
         }
-        // 3b. Schema validation: read raw file for deeper checks
+        // 3b. Schema 验证: 读取原始文件进行深度检查
         const schemaIssues = await validateFormatSchema(entry);
         for (const issue of schemaIssues) {
             findings.push({
@@ -89,7 +97,7 @@ export async function auditKnowledge(knowledgeIndex, config) {
             });
         }
     }
-    // 4. Coverage: check knowledge types have entries
+    // 4. 覆盖度检查: 确保各知识类型都有条目
     const requiredTypes = ["pattern", "procedure", "domain", "review_rule"];
     for (const type of requiredTypes) {
         const count = all.filter((e) => e.type === type && e.status !== "deprecated").length;
@@ -104,7 +112,7 @@ export async function auditKnowledge(knowledgeIndex, config) {
             });
         }
     }
-    // 5. Completeness: check rule/AC counts against type thresholds
+    // 5. 完整度检查: 检查规则/验收项数量是否达到类型阈值
     for (const entry of all) {
         if (entry.status === "deprecated")
             continue;
@@ -143,6 +151,7 @@ export async function auditKnowledge(knowledgeIndex, config) {
         completeness: findings.filter((f) => f.category === "completeness").length,
         design_drift: 0,
     };
+    console.error(`[soloForge] 知识审计: 完成，共 ${findings.length} 项发现`);
     return {
         total_entries: all.filter((e) => e.status !== "deprecated").length,
         findings,
@@ -150,19 +159,27 @@ export async function auditKnowledge(knowledgeIndex, config) {
         audited_at: new Date().toISOString(),
     };
 }
+/**
+ * 新增知识条目。
+ * 根据类型生成对应的模板内容，保存到草稿目录或正式目录。
+ * @param input - 新增知识条目输入
+ * @param config - 项目配置
+ * @returns 新增结果，包含文件路径和消息
+ */
 export async function addKnowledge(input, config) {
+    console.error(`[soloForge] 知识管理: 新增知识条目「${input.title}」[${input.type}]`);
     const knowledgeDir = getProjectKnowledgeDir(config);
-    const fileName = `${input.title}.md`;
-    // Determine save location
+    const fileName = `${path.basename(input.title)}.md`; // basename 防止路径穿越
+    // 确定保存位置
     const typeDir = getTypeDirectory(input.type);
     const draftsDir = path.join(knowledgeDir, "drafts");
     const targetDir = input.save_to_drafts !== false
         ? draftsDir
         : path.join(knowledgeDir, typeDir);
-    // Ensure directory exists
+    // 确保目录存在
     await fs.mkdir(targetDir, { recursive: true });
     const filePath = path.join(targetDir, fileName);
-    // Check if file already exists
+    // 检查文件是否已存在
     if (fss.existsSync(filePath)) {
         return {
             success: false,
@@ -171,12 +188,13 @@ export async function addKnowledge(input, config) {
             message: `文件已存在: ${filePath}，请使用 sf_knowledge_update 更新`,
         };
     }
-    // Generate content
+    // 生成内容
     const content = generateKnowledgeContent(input);
     await fs.writeFile(filePath, content, "utf-8");
     const enrichment_guide = input.auto_enrich !== false
         ? buildEnrichmentGuide(input)
         : undefined;
+    console.error(`[soloForge] 知识管理: 知识条目已保存到 ${filePath}`);
     return {
         success: true,
         file_path: filePath,
@@ -187,11 +205,21 @@ export async function addKnowledge(input, config) {
         enrichment_guide,
     };
 }
+/**
+ * 更新已有的知识条目。
+ * 更新前自动创建备份，支持修改触发条件、状态、决策规则和验收标准。
+ * @param input - 更新输入参数
+ * @param knowledgeIndex - 知识索引管理器
+ * @param config - 项目配置
+ * @returns 更新结果，包含文件路径和备份路径
+ */
 export async function updateKnowledge(input, knowledgeIndex, config) {
+    console.error(`[soloForge] 知识管理: 更新知识条目「${input.entry_name}」`);
     const entry = knowledgeIndex.getEntry(input.entry_name)
         ?? knowledgeIndex.getAllEntries().global.find((e) => e.name === input.entry_name)
         ?? knowledgeIndex.getAllEntries().project.find((e) => e.name === input.entry_name);
     if (!entry) {
+        console.error(`[soloForge] 知识管理: 未找到知识条目「${input.entry_name}」`);
         return {
             success: false,
             file_path: "",
@@ -202,6 +230,7 @@ export async function updateKnowledge(input, knowledgeIndex, config) {
     const filePath = entry.file_path;
     // 维度6: 知识目录隔离 — 禁止更新 core/ 只读目录中的条目
     if (KnowledgeWriter.isCorePath(filePath)) {
+        console.error(`[soloForge] 知识管理: 「${input.entry_name}」位于 core/ 只读目录，禁止自动更新`);
         return {
             success: false,
             file_path: filePath,
@@ -217,15 +246,15 @@ export async function updateKnowledge(input, knowledgeIndex, config) {
             message: `文件不存在: ${filePath}`,
         };
     }
-    // Read and parse
+    // 读取并解析文件
     const raw = await fs.readFile(filePath, "utf-8");
     const { data: frontmatter, content: body } = matter(raw);
-    // Create backup
+    // 创建备份
     const backupDir = path.join(path.dirname(filePath), ".backups");
     await fs.mkdir(backupDir, { recursive: true });
     const backupPath = path.join(backupDir, `${entry.name}-${Date.now()}.md`);
     await fs.writeFile(backupPath, raw, "utf-8");
-    // Apply updates
+    // 应用更新
     let updated = false;
     if (input.updates.when_triggers) {
         frontmatter.when = input.updates.when_triggers;
@@ -268,9 +297,10 @@ export async function updateKnowledge(input, knowledgeIndex, config) {
             message: "未提供任何更新内容",
         };
     }
-    // Write updated file
+    // 写入更新后的文件
     const output = matter.stringify(newBody, frontmatter);
     await fs.writeFile(filePath, output, "utf-8");
+    console.error(`[soloForge] 知识管理: 知识条目「${input.entry_name}」已更新，备份: ${backupPath}`);
     return {
         success: true,
         file_path: filePath,
@@ -278,8 +308,10 @@ export async function updateKnowledge(input, knowledgeIndex, config) {
         message: `知识条目已更新: ${filePath}\n备份: ${backupPath}`,
     };
 }
-// ── Format Schema ──
+// ── 格式 Schema ──
+/** 规范的 frontmatter 字段顺序 */
 const CANONICAL_FM_ORDER = ["name", "type", "when", "scope", "products"];
+/** 各知识类型的格式规范定义 */
 const FORMAT_SCHEMA = {
     pattern: {
         required_headings: ["## 决策规则", "## 验收项"],
@@ -302,6 +334,7 @@ const FORMAT_SCHEMA = {
         required_headings: [],
     },
 };
+/** 各知识类型的完整度阈值（字段名、匹配正则、最小数量） */
 const COMPLETENESS_THRESHOLDS = {
     pattern: [
         { field: "决策规则", pattern: /^- /gm, minimum: 5 },
@@ -321,9 +354,21 @@ const COMPLETENESS_THRESHOLDS = {
         { field: "规则", pattern: /^## [A-Z]+-\d+/gm, minimum: 5 },
     ],
 };
+/**
+ * 统计正则匹配数量。
+ * @param body - 文本内容
+ * @param pattern - 正则表达式
+ * @returns 匹配数量
+ */
 function countPattern(body, pattern) {
     return (body.match(pattern) ?? []).length;
 }
+/**
+ * 验证知识条目的格式 Schema 规范。
+ * 检查 frontmatter 字段顺序、when 字段风格、body 必需标题。
+ * @param entry - 知识条目
+ * @returns 格式问题列表
+ */
 async function validateFormatSchema(entry) {
     const results = [];
     if (!entry.file_path || !fss.existsSync(entry.file_path))
@@ -336,7 +381,7 @@ async function validateFormatSchema(entry) {
         return results;
     }
     const { data: fm, content: body } = matter(raw);
-    // Check frontmatter field order
+    // 检查 frontmatter 字段顺序
     const fmKeys = Object.keys(fm);
     const orderIssues = [];
     for (let i = 0; i < CANONICAL_FM_ORDER.length; i++) {
@@ -352,7 +397,7 @@ async function validateFormatSchema(entry) {
             suggestion: `标准顺序: ${CANONICAL_FM_ORDER.join(" → ")}`,
         });
     }
-    // Check when style: first comma-separated segment should be ≤ 10 Chinese chars
+    // 检查 when 字段风格: 第一个逗号分隔段应 ≤ 10 个中文字符
     const whenStr = fm.when ?? "";
     const firstSegment = whenStr.split(/[,\s，]/)[0] ?? "";
     const chineseCharCount = (firstSegment.match(/[一-鿿]/g) ?? []).length;
@@ -362,7 +407,7 @@ async function validateFormatSchema(entry) {
             suggestion: "when 应为纯关键词逗号分隔，如: 数据导出, CSV, Excel, 批量导出",
         });
     }
-    // Check body headings
+    // 检查 body 标题
     const schema = FORMAT_SCHEMA[entry.type];
     if (schema) {
         for (const heading of schema.required_headings) {
@@ -386,7 +431,13 @@ async function validateFormatSchema(entry) {
     }
     return results;
 }
-// ── Helpers ──
+// ── 辅助函数 ──
+/**
+ * 计算两个关键词字符串的重叠度。
+ * @param a - 第一个关键词字符串
+ * @param b - 第二个关键词字符串
+ * @returns 重叠度（0-1），1 表示完全重叠
+ */
 function keywordOverlap(a, b) {
     const wordsA = new Set(a.toLowerCase().split(/[,\s，]+/).filter(Boolean));
     const wordsB = new Set(b.toLowerCase().split(/[,\s，]+/).filter(Boolean));
@@ -399,6 +450,11 @@ function keywordOverlap(a, b) {
     }
     return overlap / Math.min(wordsA.size, wordsB.size);
 }
+/**
+ * 根据知识类型获取存储目录名。
+ * @param type - 知识条目类型
+ * @returns 目录名
+ */
 function getTypeDirectory(type) {
     const map = {
         pattern: "patterns/temp",
@@ -410,6 +466,11 @@ function getTypeDirectory(type) {
     };
     return map[type] ?? "procedures";
 }
+/**
+ * 生成知识条目的 frontmatter 文本。
+ * @param input - 新增知识条目输入
+ * @returns frontmatter 文本
+ */
 function generateFrontmatter(input) {
     return `---
 name: ${input.title}
@@ -419,6 +480,12 @@ scope: [${input.scope.join(", ")}]
 products: ["*"]
 ---`;
 }
+/**
+ * 生成知识条目的完整内容（frontmatter + body）。
+ * 根据类型选择对应的 body 生成器。
+ * @param input - 新增知识条目输入
+ * @returns 完整的 Markdown 文件内容
+ */
 function generateKnowledgeContent(input) {
     const fm = generateFrontmatter(input);
     const generators = {
@@ -432,6 +499,11 @@ function generateKnowledgeContent(input) {
     const gen = generators[input.type] ?? generators.pattern;
     return `${fm}\n\n${gen()}\n`;
 }
+/**
+ * 生成 pattern 类型知识条目的 body 内容。
+ * @param input - 新增知识条目输入
+ * @returns body 文本
+ */
 function generatePatternBody(input) {
     const rules = input.decision_rules
         ? input.decision_rules.split("\n").filter(Boolean).map((r) => `- ${r}`).join("\n")
@@ -442,6 +514,11 @@ ${rules}
 ## 验收项
 - [AC-01] (待补充验收标准)`;
 }
+/**
+ * 生成 domain 类型知识条目的 body 内容。
+ * @param input - 新增知识条目输入
+ * @returns body 文本
+ */
 function generateDomainBody(input) {
     const rules = input.decision_rules
         ? input.decision_rules.split("\n").filter(Boolean).map((r) => `${r}`).join("\n\n")
@@ -458,6 +535,11 @@ ${rules}
 ## 关联模式
 - (待补充关联模式)`;
 }
+/**
+ * 生成 procedure 类型知识条目的 body 内容。
+ * @param input - 新增知识条目输入
+ * @returns body 文本
+ */
 function generateProcedureBody(input) {
     return `## 适用场景
 (待补充适用场景描述)
@@ -471,6 +553,11 @@ function generateProcedureBody(input) {
 ## 注意事项
 - (待补充注意事项)`;
 }
+/**
+ * 生成 pipeline_procedure 类型知识条目的 body 内容。
+ * @param input - 新增知识条目输入
+ * @returns body 文本
+ */
 function generatePipelineBody(input) {
     return `# ${input.title}
 
@@ -483,6 +570,11 @@ function generatePipelineBody(input) {
 (待补充阶段描述)
 工具：sf_verify`;
 }
+/**
+ * 生成 review_rule 类型知识条目的 body 内容。
+ * @param input - 新增知识条目输入
+ * @returns body 文本
+ */
 function generateReviewRuleBody(input) {
     const code = input.title.toUpperCase().replace(/-/g, "").slice(0, 3);
     return `## ${code}-01: (待补充规则标题)
@@ -491,6 +583,11 @@ severity: warning
 scope: ${input.scope.join(", ")}
 description: (待补充规则描述)`;
 }
+/**
+ * 生成 acceptance_template 类型知识条目的 body 内容。
+ * @param input - 新增知识条目输入
+ * @returns body 文本
+ */
 function generateAcceptanceBody(input) {
     return `# ${input.title}
 
@@ -500,10 +597,20 @@ function generateAcceptanceBody(input) {
 ## 2. (待补充章节标题)
 (待补充内容)`;
 }
-// ── Enrichment Guide ──
+// ── 自动丰富指南 ──
+/**
+ * 从标题中提取可读的主题名称。
+ * @param title - 知识条目标题（含连字符/下划线）
+ * @returns 格式化后的主题名称
+ */
 function extractTopicFromTitle(title) {
     return title.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
+/**
+ * 根据知识类型构建对应的自动丰富指南。
+ * @param input - 新增知识条目输入
+ * @returns 自动丰富指南
+ */
 function buildEnrichmentGuide(input) {
     const builders = {
         pattern: () => buildPatternGuide(input),
@@ -515,6 +622,11 @@ function buildEnrichmentGuide(input) {
     };
     return builders[input.type]();
 }
+/**
+ * 构建 pattern 类型的自动丰富指南。
+ * @param input - 新增知识条目输入
+ * @returns 丰富指南
+ */
 function buildPatternGuide(input) {
     const topic = extractTopicFromTitle(input.title);
     return {
@@ -559,6 +671,11 @@ function buildPatternGuide(input) {
         update_call_template: `sf_knowledge_update(entry_name="${input.title}", add_decision_rules=[规则1, 规则2, ...], add_acceptance_criteria=[标准1, 标准2, ...])`,
     };
 }
+/**
+ * 构建 domain 类型的自动丰富指南。
+ * @param input - 新增知识条目输入
+ * @returns 丰富指南
+ */
 function buildDomainGuide(input) {
     const topic = extractTopicFromTitle(input.title);
     return {
@@ -609,6 +726,11 @@ function buildDomainGuide(input) {
         update_call_template: `sf_knowledge_update(entry_name="${input.title}", add_decision_rules=[业务规则1, 业务规则2, ...])`,
     };
 }
+/**
+ * 构建 procedure 类型的自动丰富指南。
+ * @param input - 新增知识条目输入
+ * @returns 丰富指南
+ */
 function buildProcedureGuide(input) {
     const topic = extractTopicFromTitle(input.title);
     return {
@@ -657,6 +779,11 @@ function buildProcedureGuide(input) {
         update_call_template: `sf_knowledge_update(entry_name="${input.title}", add_decision_rules=[步骤内容, 注意事项, ...])`,
     };
 }
+/**
+ * 构建 pipeline_procedure 类型的自动丰富指南。
+ * @param input - 新增知识条目输入
+ * @returns 丰富指南
+ */
 function buildPipelineGuide(input) {
     const topic = extractTopicFromTitle(input.title);
     return {
@@ -698,6 +825,11 @@ function buildPipelineGuide(input) {
         update_call_template: `sf_knowledge_update(entry_name="${input.title}", add_decision_rules=[阶段定义1, 阶段定义2, ...])`,
     };
 }
+/**
+ * 构建 review_rule 类型的自动丰富指南。
+ * @param input - 新增知识条目输入
+ * @returns 丰富指南
+ */
 function buildReviewRuleGuide(input) {
     const topic = extractTopicFromTitle(input.title);
     return {
@@ -741,6 +873,11 @@ function buildReviewRuleGuide(input) {
         update_call_template: `sf_knowledge_update(entry_name="${input.title}", add_decision_rules=[规则定义1, 规则定义2, ...])`,
     };
 }
+/**
+ * 构建 acceptance_template 类型的自动丰富指南。
+ * @param input - 新增知识条目输入
+ * @returns 丰富指南
+ */
 function buildAcceptanceGuide(input) {
     const topic = extractTopicFromTitle(input.title);
     return {
@@ -784,6 +921,11 @@ function buildAcceptanceGuide(input) {
         update_call_template: `sf_knowledge_update(entry_name="${input.title}", add_acceptance_criteria=[验收项1, 验收项2, ...])`,
     };
 }
+/**
+ * 获取项目知识库目录路径。
+ * @param config - 项目配置
+ * @returns 知识库目录的绝对路径
+ */
 function getProjectKnowledgeDir(config) {
     const projectDir = config._projectPath ?? process.cwd();
     return path.join(projectDir, ".soloforge", "knowledge");