soloforge 1.0.0 → 1.1.1

package/README.md

@@ -10,8 +10,11 @@ SoloForge 是一个 [MCP (Model Context Protocol)](https://modelcontextprotocol.
 # 全局安装
 npm install -g soloforge
 
-# 或直接使用
+# 或直接使用（不安装）
 npx soloforge init
+
+# 更新到最新版本
+npm update -g soloforge
 ```
 
 `init` 命令会生成项目配置（`.soloforge/config.yaml`）、初始化知识模板、并为你的 AI 工具生成适配配置。

package/dist/adapters/claude_code/claude_md.d.ts

@@ -1,3 +1,2 @@
-import type { ProjectConfig } from "../../types.js";
-export declare function generateClaudeMd(config: ProjectConfig): string;
+export declare function generateClaudeMd(config: import("../../types.js").ProjectConfig): string;
 //# sourceMappingURL=claude_md.d.ts.map

package/dist/adapters/claude_code/claude_md.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude_md.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/claude_md.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CA6E9D"}
+{"version":3,"file":"claude_md.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/claude_md.ts"],"names":[],"mappings":"AAEA,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,gBAAgB,EAAE,aAAa,GAAG,MAAM,CAEvF"}

package/dist/adapters/claude_code/claude_md.js

@@ -1,79 +1,5 @@
+import { generateWorkflowRules } from "../shared/workflow_template.js";
 export function generateClaudeMd(config) {
-    return `# SoloForge 集成规则
-
-## 强制工作流
-
-当收到开发指令时（非纯对话/提问），必须按以下顺序执行:
-
-### 步骤 1: 分类
-调用 \`sf_classify\` 工具，传入用户意图和当前项目路径。
-
-### 步骤 1.5: 任务拆解（建议）
-如果分类结果 complexity=high 且 strategy=full_pipeline，调用 \`sf_plan\` 查看拆解建议。
-如果 \`sf_plan\` 返回多阶段计划（sub_tasks > 1），则按阶段执行:
-1. 调用 \`sf_expand\` 获取当前阶段指令（自动注入模板和前序产出）
-2. 执行该阶段任务
-3. 调用 \`sf_plan_advance\` 推进到下一阶段
-4. 重复直到所有阶段完成
-
-### 步骤 2: 根据分类结果执行
-- task_type = "scaffold" → 调用 \`sf_scaffold\` 生成代码骨架，然后填充业务逻辑
-- strategy = "full_pipeline" → 调用 \`sf_expand\`，然后按 expand 的 prompt 执行
-- strategy = "quick_fix" → 调用 \`sf_expand\`（简化版），然后执行
-- strategy = "skip_soloForge" → 直接处理，不调用 SoloForge 工具
-
-### 步骤 2.5: 影响分析（建议）
-执行 \`sf_expand\` 后，可选择调用 \`sf_analyze\` 查看影响范围分析。如果提示范围不足，可扩大作用域或确认范围。
-
-### 步骤 3: 代码修改后验证
-所有代码修改完成后，调用 \`sf_verify\` 获取验证命令。
-通过 Bash 工具执行 \`sf_verify\` 返回的验证命令。
-
-### 步骤 3.5: 代码审查（建议）
-验证通过后，可选择调用 \`sf_review\` 进行代码审查。hotfix 场景自动跳过。
-审查结果包含质量、安全、性能、架构、技术债务五个维度。支持知识驱动审查规则。技术债务自动记录，不强制修复。
-
-### 步骤 3.6: 契约检查（建议）
-如果变更涉及 API 路由、DTO、接口文件，可调用 \`sf_contract_check\` 检测破坏性变更和跨服务影响。
-
-### 步骤 4: 学习
-验证完成后（无论通过或失败），调用 \`sf_learn\` 传入验证结果。
-如果 \`sf_learn\` 返回 \`retry_hint\`，表示需要修复后重试，回到步骤 3 重新验证。
-
-### 步骤 5: 结果汇报
-向开发者展示:
-- 验证结果摘要
-- 自动化验收通过/失败项
-- 需人工确认的项（如有）
-
-### 步骤 5.5: 变更协调检查（建议）
-推送前可调用 \`sf_coord_check\` 检查潜在冲突和跨仓库影响。
-
-### 步骤 5.6: 自动交付（可选）
-调用 \`sf_deliver\` 自动提交代码、推送、创建 PR 和生成变更日志。
-新人加入项目时，使用 \`sf_onboard\` 进行分步引导。
-需要查看团队状态时，调用 \`sf_team_status\`。
-
-### 步骤 5.7: 知识维护（可选）
-定期调用 \`sf_knowledge_audit\` 审计知识库健康度。
-发现需要新增的知识条目时，调用 \`sf_knowledge_add\` 生成草稿（默认保存到 drafts/，需人工确认）。
-需要更新已有条目时，调用 \`sf_knowledge_update\`（自动创建备份）。
-
-## 任务管理
-
-使用 \`sf_status\` 工具管理任务生命周期:
-- \`sf_status action=current\` — 查看当前任务状态
-- \`sf_status action=recent\` — 列出近期任务
-- \`sf_status action=resume task_id=xxx\` — 恢复中断的任务
-- \`sf_status action=cancel task_id=xxx\` — 取消未完成的任务
-
-对话中断后，先用 \`sf_status action=current\` 检查是否有未完成任务。
-
-## 项目信息
-
-- 产品: ${config.product_profile}
-- 后端: ${config.tech_stack.backend.framework} ${config.tech_stack.backend.version}
-- 前端: ${config.tech_stack.frontend.framework} ${config.tech_stack.frontend.version}
-`;
+    return generateWorkflowRules(config) + "\n";
 }
 //# sourceMappingURL=claude_md.js.map

package/dist/adapters/claude_code/claude_md.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude_md.js","sourceRoot":"","sources":["../../../src/adapters/claude_code/claude_md.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,gBAAgB,CAAC,MAAqB;IACpD,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAwED,MAAM,CAAC,eAAe;QACtB,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO;QACxE,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,IAAI,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,OAAO;CACjF,CAAC;AACF,CAAC"}
+{"version":3,"file":"claude_md.js","sourceRoot":"","sources":["../../../src/adapters/claude_code/claude_md.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAEvE,MAAM,UAAU,gBAAgB,CAAC,MAA8C;IAC7E,OAAO,qBAAqB,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;AAC9C,CAAC"}

package/dist/adapters/claude_code/server.d.ts

@@ -1,10 +1,26 @@
 import type { ProjectConfig } from "../../types.js";
 import { KnowledgeIndexManager } from "../../knowledge/index_manager.js";
 import { TaskContextManager } from "../../engine/task_context.js";
+/**
+ * MCP Server 启动模块。
+ * @description 创建 SoloForge MCP 服务器实例，注册所有工具，通过 stdio 传输与 Claude Code 通信。
+ *              负责进程生命周期管理：优雅关闭（SIGTERM/SIGINT）、客户端断开检测（SIGPIPE）、
+ *              未捕获异常处理，确保资源正确释放。
+ */
+/**
+ * Server 依赖项接口。
+ * @description 封装 MCP 服务器运行所需的全部依赖。
+ */
 export interface ServerDeps {
     config: ProjectConfig;
     knowledgeIndex: KnowledgeIndexManager;
     taskContext: TaskContextManager;
 }
+/**
+ * 启动 SoloForge MCP 服务器。
+ * @description 创建 McpServer 实例，注册工具，通过 stdio 传输连接 Claude Code，
+ *              并设置信号处理和异常处理以确保优雅关闭。
+ * @param deps - 服务器依赖项（配置、知识索引、任务上下文）
+ */
 export declare function startServer(deps: ServerDeps): Promise<void>;
 //# sourceMappingURL=server.d.ts.map

package/dist/adapters/claude_code/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/server.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc,EAAE,qBAAqB,CAAC;IACtC,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAcD,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDjE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/server.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc,EAAE,qBAAqB,CAAC;IACtC,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAqBD;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA0DjE"}

package/dist/adapters/claude_code/server.js

@@ -3,6 +3,13 @@ import path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { registerTools } from "./tools.js";
+/**
+ * 检查当前项目是否为 SoloForge 自身项目（内部方法）。
+ * @description 通过检查 package.json 中的 name 字段判断是否为 SoloForge 自身。
+ *              SoloForge 自身项目会额外注册知识维护工具（sf_knowledge_audit/add/update）。
+ * @param config - 项目配置对象
+ * @returns 是否为 SoloForge 自身项目
+ */
 function isSoloForgeProject(config) {
     const projectPath = config._projectPath || process.cwd();
     try {
@@ -15,6 +22,12 @@ function isSoloForgeProject(config) {
         return false;
     }
 }
+/**
+ * 启动 SoloForge MCP 服务器。
+ * @description 创建 McpServer 实例，注册工具，通过 stdio 传输连接 Claude Code，
+ *              并设置信号处理和异常处理以确保优雅关闭。
+ * @param deps - 服务器依赖项（配置、知识索引、任务上下文）
+ */
 export async function startServer(deps) {
     const { config, knowledgeIndex, taskContext } = deps;
     const server = new McpServer({
@@ -27,6 +40,7 @@ export async function startServer(deps) {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     let shuttingDown = false;
+    // 优雅关闭：关闭知识索引监听器和传输层，防止重复触发
     const shutdown = async () => {
         if (shuttingDown)
             return;
@@ -43,10 +57,11 @@ export async function startServer(deps) {
     };
     process.on("SIGTERM", shutdown);
     process.on("SIGINT", shutdown);
+    // 客户端（Claude Code）断开连接，触发优雅退出
     process.on("SIGPIPE", () => {
-        // 客户端断开连接，优雅退出
         shutdown();
     });
+    // 捕获未处理的同步异常，确保资源释放后退出
     process.on("uncaughtException", async (err) => {
         console.error("SoloForge 未捕获异常:", err);
         try {
@@ -59,6 +74,7 @@ export async function startServer(deps) {
         }
         process.exit(1);
     });
+    // 捕获未处理的 Promise 拒绝，确保资源释放后退出
     process.on("unhandledRejection", async (reason) => {
         console.error("SoloForge 未处理的 Promise 拒绝:", reason);
         try {

package/dist/adapters/claude_code/server.js.map

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

package/dist/adapters/claude_code/tools.d.ts

@@ -2,14 +2,45 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { ProjectConfig } from "../../types.js";
 import type { KnowledgeIndexManager } from "../../knowledge/index_manager.js";
 import type { TaskContextManager } from "../../engine/task_context.js";
+/**
+ * MCP 工具注册模块。
+ * @description 将 SoloForge 的全部功能封装为 MCP 工具，注册到 McpServer 实例。
+ *              每个工具通过统一的错误处理包装器（registerSafeTool）注册，确保异常不会导致服务崩溃。
+ *              工具分为三类：核心流程工具（classify/expand/verify/learn/status）、
+ *              辅助工具（plan/review/scaffold/deliver 等）、自维护工具（knowledge_audit/add/update）。
+ *              自维护工具仅在 SoloForge 自身项目中注册。
+ */
+/**
+ * SoloForge 核心依赖项。
+ * @description 封装所有 MCP 工具共享的依赖：项目配置、知识索引和任务上下文。
+ */
 export interface SoloForgeDeps {
+    /** 项目配置对象 */
     config: ProjectConfig;
+    /** 知识索引管理器 */
     knowledgeIndex: KnowledgeIndexManager;
+    /** 任务上下文管理器 */
     taskContext: TaskContextManager;
 }
+/**
+ * 工具注册选项。
+ */
 export interface RegisterToolsOptions {
-    /** When true, registers self-maintenance tools (sf_knowledge_audit/add/update) */
+    /** 是否为 SoloForge 自身项目（true 时注册自维护工具） */
     isSelfProject?: boolean;
 }
+/**
+ * 注册所有 SoloForge MCP 工具。
+ * @description 核心注册函数，将全部 MCP 工具注册到指定的 McpServer 实例。
+ *              包含：sf_classify、sf_expand、sf_verify、sf_learn、sf_status、
+ *              sf_plan、sf_plan_advance、sf_analyze、sf_review、sf_scaffold、
+ *              sf_deliver、sf_coord_check、sf_team_status、sf_contract_check、
+ *              sf_onboard、sf_feasibility_check、sf_debug、sf_observability、
+ *              sf_migration_check、sf_test_guide、sf_test_quality、sf_dependency_scan、
+ *              sf_debt_report，以及条件注册的 sf_knowledge_audit/add/update。
+ * @param server - MCP 服务器实例
+ * @param deps - SoloForge 核心依赖项
+ * @param options - 注册选项（控制自维护工具是否注册）
+ */
 export declare function registerTools(server: McpServer, deps: SoloForgeDeps, options?: RegisterToolsOptions): void;
 //# sourceMappingURL=tools.d.ts.map

package/dist/adapters/claude_code/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AA0BvE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc,EAAE,qBAAqB,CAAC;IACtC,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAkHD,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAy3B1G"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/adapters/claude_code/tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AA2BvE;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,aAAa;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc;IACd,cAAc,EAAE,qBAAqB,CAAC;IACtC,eAAe;IACf,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAuHD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAk5B1G"}

package/dist/adapters/claude_code/tools.js

@@ -23,6 +23,7 @@ import { generateTestGuide } from "../../engine/test_generator.js";
 import { analyzeTestQuality } from "../../engine/test_quality.js";
 import { scanDependencies } from "../../engine/dependency_scanner.js";
 import { generateDebtReport } from "../../engine/debt_reporter.js";
+import { exploreSolutions } from "../../engine/exploration.js";
 // ── Zod Schema 定义 ──
 const ClassifySchema = {
     intent: z.string().describe("开发者意图描述"),
@@ -111,11 +112,28 @@ const DependencyScanSchema = {
     content: z.string().describe("依赖声明文件内容（package.json / pom.xml / build.gradle）"),
     filename: z.string().describe("文件名"),
 };
+const ExploreSchema = {
+    domain_query: z.string().describe("技术选型领域关键词（如：分布式锁、流式处理、复杂表单状态管理、缓存策略）"),
+    task_id: z.string().optional().describe("关联任务 ID（可选，用于关联项目上下文）"),
+};
 // ── 工具注册 ──
+/**
+ * 注册所有 SoloForge MCP 工具。
+ * @description 核心注册函数，将全部 MCP 工具注册到指定的 McpServer 实例。
+ *              包含：sf_classify、sf_expand、sf_verify、sf_learn、sf_status、
+ *              sf_plan、sf_plan_advance、sf_analyze、sf_review、sf_scaffold、
+ *              sf_deliver、sf_coord_check、sf_team_status、sf_contract_check、
+ *              sf_onboard、sf_feasibility_check、sf_debug、sf_observability、
+ *              sf_migration_check、sf_test_guide、sf_test_quality、sf_dependency_scan、
+ *              sf_debt_report，以及条件注册的 sf_knowledge_audit/add/update。
+ * @param server - MCP 服务器实例
+ * @param deps - SoloForge 核心依赖项
+ * @param options - 注册选项（控制自维护工具是否注册）
+ */
 export function registerTools(server, deps, options) {
     const { config, knowledgeIndex, taskContext } = deps;
     const projectPath = config._projectPath || process.cwd();
-    // 统一错误处理包装器
+    // 统一错误处理包装器，捕获工具执行中的异常并返回结构化错误响应
     function registerSafeTool(name, desc, schema, handler) {
         server.tool(name, desc, schema, async (args) => {
             try {
@@ -129,7 +147,7 @@ export function registerTools(server, deps, options) {
             }
         });
     }
-    // ── sf_classify ──
+    // ── sf_classify: 意图分类入口，创建任务上下文并返回分类结果 ──
     registerSafeTool("sf_classify", "分析开发者意图，返回任务类型、风险、复杂度和执行策略", ClassifySchema, async (args) => {
         // 检查是否存在进行中的任务
         const existing = await taskContext.getCurrentTask();
@@ -166,7 +184,7 @@ export function registerTools(server, deps, options) {
                 }],
         };
     });
-    // ── sf_expand ──
+    // ── sf_expand: 意图膨胀，生成结构化 prompt 并注入计划上下文 ──
     registerSafeTool("sf_expand", "将意图膨胀为结构化 prompt，包含 scope、验收标准和知识匹配。当存在计划时自动注入当前阶段上下文和输出模板", ExpandSchema, async (args) => {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx || !ctx.classification) {
@@ -217,7 +235,7 @@ export function registerTools(server, deps, options) {
                 }],
         };
     });
-    // ── sf_verify ──
+    // ── sf_verify: 生成验证命令（构建、测试、验收检查） ──
     registerSafeTool("sf_verify", "根据变更文件生成验证命令（构建、测试、验收检查），由 Claude Code Bash 执行", VerifySchema, async (args) => {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx) {
@@ -226,8 +244,6 @@ export function registerTools(server, deps, options) {
                 isError: true,
             };
         }
-        // 转换到验证阶段
-        await taskContext.updateStatus(args.task_id, "verifying");
         const acceptanceItems = ctx.expansion
             ? [...ctx.expansion.acceptance.automated, ...ctx.expansion.acceptance.manual]
             : [];
@@ -235,6 +251,8 @@ export function registerTools(server, deps, options) {
         verifyResult.task_id = args.task_id;
         // 记录变更文件
         await taskContext.setExecution(args.task_id, args.changed_files);
+        // 生成验证命令成功后再转换状态，避免操作失败导致任务卡在 verifying
+        await taskContext.updateStatus(args.task_id, "verifying");
         // 存储验证结果
         await taskContext.setVerification(args.task_id, verifyResult);
         return {
@@ -244,7 +262,7 @@ export function registerTools(server, deps, options) {
                 }],
         };
     });
-    // ── sf_learn ──
+    // ── sf_learn: 从执行结果中提取知识，支持重试循环控制 ──
     registerSafeTool("sf_learn", "从任务执行结果中提取知识，低置信度暂存，高置信度直接入库", LearnSchema, async (args) => {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx) {
@@ -293,7 +311,7 @@ export function registerTools(server, deps, options) {
                 }],
         };
     });
-    // ── sf_status ──
+    // ── sf_status: 任务状态查询（current/recent/resume/cancel） ──
     registerSafeTool("sf_status", "查询当前任务状态、列出近期任务、恢复中断任务或取消任务", StatusSchema, async (args) => {
         const action = args.action || "current";
         switch (action) {
@@ -399,7 +417,7 @@ export function registerTools(server, deps, options) {
                 };
         }
     });
-    // ── sf_plan ──
+    // ── sf_plan: 复杂意图任务拆解为子任务列表 ──
     registerSafeTool("sf_plan", "将复杂意图拆解为子任务列表。支持知识驱动的 pipeline_procedure 流程（自动绑定模板）和仓库边界拆分两种策略。仅在 complexity=high 时有效", PlanSchema, async (args) => {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx?.classification) {
@@ -420,7 +438,7 @@ export function registerTools(server, deps, options) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_plan_advance ──
+    // ── sf_plan_advance: 推进多阶段计划到下一步 ──
     registerSafeTool("sf_plan_advance", "将多阶段计划推进到下一步。完成当前阶段后调用，自动更新 current_step_index 并返回下一阶段信息", PlanSchema, async (args) => {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx?.planning || ctx.planning.sub_tasks.length === 0) {
@@ -468,7 +486,7 @@ export function registerTools(server, deps, options) {
                 }],
         };
     });
-    // ── sf_analyze ──
+    // ── sf_analyze: 影响范围分析，建议是否扩大作用域 ──
     registerSafeTool("sf_analyze", "分析意图的影响范围，对比声明范围，提示是否需要扩大作用域。建议性，不强制", AnalyzeSchema, async (args) => {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx?.expansion) {
@@ -489,7 +507,7 @@ export function registerTools(server, deps, options) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_review ──
+    // ── sf_review: 代码审查（质量、安全、性能、技术债务） ──
     registerSafeTool("sf_review", "审查代码变更的质量、安全、性能和技术债务。hotfix 场景可跳过。建议性，不强制修复", ReviewSchema, async (args) => {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx) {
@@ -514,7 +532,7 @@ export function registerTools(server, deps, options) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_scaffold ──
+    // ── sf_scaffold: 生成标准化代码骨架 ──
     registerSafeTool("sf_scaffold", "根据项目模板生成标准化代码骨架（Controller/Service/DTO/测试等）。仅在 task_type=scaffold 时使用", ScaffoldSchema, async (args) => {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx?.classification) {
@@ -546,7 +564,7 @@ export function registerTools(server, deps, options) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_deliver ──
+    // ── sf_deliver: 自动提交、推送、创建 PR ──
     registerSafeTool("sf_deliver", "验收后自动提交代码、推送、创建 PR 和生成变更日志", DeliverSchema, async (args) => {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx) {
@@ -569,7 +587,7 @@ export function registerTools(server, deps, options) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_coord_check ──
+    // ── sf_coord_check: 预测性冲突检测和跨仓库协调 ──
     registerSafeTool("sf_coord_check", "预测性冲突检测和跨仓库协调提示，检查分支状态、本地变更和潜在冲突", CoordCheckSchema, async (args) => {
         const result = await checkConflicts({
             projectPath,
@@ -581,7 +599,7 @@ export function registerTools(server, deps, options) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_team_status ──
+    // ── sf_team_status: 团队活动流和工作负载查询 ──
     registerSafeTool("sf_team_status", "查询团队活动流、成员工作负载、过期分支和知识库更新状态", TeamStatusSchema, async (args) => {
         const result = await getTeamStatus({
             projectPath,
@@ -594,7 +612,7 @@ export function registerTools(server, deps, options) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_contract_check ──
+    // ── sf_contract_check: API 契约变更检测 ──
     registerSafeTool("sf_contract_check", "检测 API 契约变更（路由、DTO 字段等），评估破坏性影响和跨服务依赖", ContractCheckSchema, async (args) => {
         let changedFiles = args.changed_files;
         if (!changedFiles) {
@@ -611,7 +629,7 @@ export function registerTools(server, deps, options) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_onboard ──
+    // ── sf_onboard: 新人分步引导 ──
     registerSafeTool("sf_onboard", "新人分步引导：项目概览 → 代码导览 → 知识回顾 → 首个任务建议", OnboardSchema, async (args) => {
         const result = await onboard({
             config,
@@ -625,7 +643,7 @@ export function registerTools(server, deps, options) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_feasibility_check ──
+    // ── sf_feasibility_check: 任务可行性评估 ──
     registerSafeTool("sf_feasibility_check", "分析任务可行性：可行/风险/不可行三档评估，纯建议不阻断流程", FeasibilityCheckSchema, async (args) => {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx?.classification) {
@@ -639,7 +657,7 @@ export function registerTools(server, deps, options) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_debug ──
+    // ── sf_debug: 智能排障（解析错误 → 根因分析 → 修复方案） ──
     registerSafeTool("sf_debug", "智能排障：解析错误 → 追踪调用链 → 根因分析 → 修复方案 → 测试建议", DebugSchema, async (args) => {
         const projectScope = [
             ...config.scope.backend,
@@ -650,7 +668,7 @@ export function registerTools(server, deps, options) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_observability ──
+    // ── sf_observability: 系统可观测和运行报告 ──
     registerSafeTool("sf_observability", "系统可观测：运行指标、成本估算、告警检测、周期报告", ObservabilitySchema, async (args) => {
         const stateDir = taskContext.getStateDir();
         const result = await generateReport(stateDir, args.period_days);
@@ -658,35 +676,35 @@ export function registerTools(server, deps, options) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_migration_check ──
+    // ── sf_migration_check: 数据库迁移安全性分析 ──
     registerSafeTool("sf_migration_check", "分析数据库迁移文件安全性：检测破坏性操作（DROP/DELETE/TRUNCATE）并生成回滚建议", MigrationCheckSchema, async (args) => {
         const result = analyzeMigration(args.content, args.filename);
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_test_guide ──
+    // ── sf_test_guide: 基于变更文件生成测试指引 ──
     registerSafeTool("sf_test_guide", "根据变更文件类型生成测试指引：推荐测试类型、场景、Mock 点和断言模板", TestGuideSchema, async (args) => {
         const result = generateTestGuide(args.changed_files, [], config);
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_test_quality ──
+    // ── sf_test_quality: 测试文件质量五维评分 ──
     registerSafeTool("sf_test_quality", "评估测试文件质量：断言密度、边界覆盖、命名、重复率、场景覆盖五维评分", TestQualitySchema, async (args) => {
         const result = analyzeTestQuality(args.content, args.filename);
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_dependency_scan ──
+    // ── sf_dependency_scan: 依赖漏洞扫描 ──
     registerSafeTool("sf_dependency_scan", "扫描依赖声明文件漏洞：已知 CVE 规则匹配、未锁定版本检测、支持 npm/maven/gradle", DependencyScanSchema, async (args) => {
         const result = scanDependencies(args.content, args.filename);
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── sf_debt_report ──
+    // ── sf_debt_report: 技术债务报告生成 ──
     registerSafeTool("sf_debt_report", "生成技术债务报告：按分类/严重度聚合、30 天趋势、优先级排序 Top 5", {}, async () => {
         const tracker = new DebtTracker(projectPath);
         const result = await generateDebtReport(tracker);
@@ -694,16 +712,33 @@ export function registerTools(server, deps, options) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    // ── Self-maintenance tools (only registered when running inside SoloForge's own project) ──
+    // ── sf_explore: 自主技术选型与方案证伪 ──
+    registerSafeTool("sf_explore", "自主技术选型引擎：行业基准对比 + 四维权重矩阵 + 最优解宣誓 + 方案证伪 + A/B 决策诱导。禁止凭空捏造，必须基于行业标准", ExploreSchema, async (args) => {
+        let classification;
+        if (args.task_id) {
+            const ctx = await taskContext.load(args.task_id);
+            classification = ctx?.classification;
+        }
+        const result = exploreSolutions({
+            domain_query: args.domain_query,
+            projectConfig: config,
+            classification,
+            knowledgeIndex,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── 自维护工具（仅在 SoloForge 自身项目中注册） ──
     if (options?.isSelfProject) {
-        // ── sf_knowledge_audit ──
+        // ── sf_knowledge_audit: 知识库健康审计 ──
         registerSafeTool("sf_knowledge_audit", "审计知识库：识别过时条目、重复触发词、格式缺失、覆盖缺口。定期执行或手动触发", {}, async () => {
             const result = await auditKnowledge(knowledgeIndex, config);
             return {
                 content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             };
         });
-        // ── sf_knowledge_add ──
+        // ── sf_knowledge_add: 新增知识条目（默认保存为草稿） ──
         const KnowledgeAddSchema = {
             title: z.string().describe("知识条目标题（英文 kebab-case，如 payment-rules）"),
             type: z.enum(["pattern", "procedure", "pipeline_procedure", "domain", "acceptance_template", "review_rule"]).describe("知识类型"),
@@ -727,7 +762,7 @@ export function registerTools(server, deps, options) {
                 content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             };
         });
-        // ── sf_knowledge_update ──
+        // ── sf_knowledge_update: 更新已有知识条目（自动创建备份） ──
         const KnowledgeUpdateSchema = {
             entry_name: z.string().describe("要更新的知识条目名称（如 payment-rules）"),
             when_triggers: z.string().optional().describe("新的触发关键词（替换现有）"),