soloforge 1.0.0

package/dist/adapters/claude_code/tools.js

@@ -0,0 +1,758 @@
+import { z } from "zod";
+import { classify } from "../../engine/classifier.js";
+import { expand } from "../../engine/intent_expander.js";
+import { generateVerifyCommands } from "../../engine/verifier.js";
+import { evolve } from "../../engine/evolver.js";
+import { planTask } from "../../engine/task_planner.js";
+import { analyzeImpact } from "../../engine/impact_analyzer.js";
+import { reviewCode } from "../../engine/code_reviewer.js";
+import { DebtTracker } from "../../engine/debt_tracker.js";
+import { generateScaffold } from "../../engine/scaffolder.js";
+import { deliver } from "../../engine/delivery.js";
+import { checkConflicts } from "../../engine/change_coordinator.js";
+import { getTeamStatus } from "../../engine/team_awareness.js";
+import { checkContractChanges } from "../../engine/contract_guard.js";
+import { onboard } from "../../engine/onboarding.js";
+import { realGitOps } from "../../engine/git_deps.js";
+import { auditKnowledge, addKnowledge, updateKnowledge } from "../../engine/knowledge_manager.js";
+import { checkFeasibility } from "../../engine/feasibility_checker.js";
+import { debugError } from "../../engine/debugger.js";
+import { generateReport } from "../../engine/observability.js";
+import { analyzeMigration } from "../../engine/migration_guard.js";
+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";
+// ── Zod Schema 定义 ──
+const ClassifySchema = {
+    intent: z.string().describe("开发者意图描述"),
+    project_path: z.string().optional().describe("项目路径（默认当前目录）"),
+};
+const ExpandSchema = {
+    task_id: z.string().describe("sf_classify 返回的任务 ID"),
+    clarification_answers: z.array(z.string()).optional().describe("对澄清问题的回答"),
+};
+const VerifySchema = {
+    task_id: z.string().describe("任务 ID"),
+    changed_files: z.array(z.string()).describe("本次修改的文件列表"),
+};
+const LearnSchema = {
+    task_id: z.string().describe("任务 ID"),
+    result: z.enum(["success", "failure"]).describe("执行结果"),
+    failure_type: z.enum(["deterministic", "fixable", "scope_insufficient"]).optional().describe("失败类型"),
+    verify_output: z.object({
+        build_passed: z.boolean(),
+        tests_passed: z.boolean(),
+        acceptance_results: z.record(z.string(), z.boolean()).optional(),
+    }).optional().describe("验证输出"),
+};
+const StatusSchema = {
+    task_id: z.string().optional().describe("任务 ID（不传则查当前任务）"),
+    action: z.enum(["current", "recent", "resume", "cancel"]).optional().describe("操作类型"),
+};
+const PlanSchema = {
+    task_id: z.string().describe("sf_classify 返回的任务 ID"),
+};
+const AnalyzeSchema = {
+    task_id: z.string().describe("sf_expand 返回的任务 ID（需要先执行 expand）"),
+};
+const ReviewSchema = {
+    task_id: z.string().describe("任务 ID"),
+    changed_files: z.array(z.string()).describe("本次修改的文件列表"),
+    file_contents: z.record(z.string(), z.string()).optional().describe("变更文件的当前内容（key=文件路径，value=文件内容），不传则自动读取"),
+};
+const ScaffoldSchema = {
+    task_id: z.string().describe("sf_classify 返回的任务 ID（task_type 应为 scaffold）"),
+};
+const DeliverSchema = {
+    task_id: z.string().describe("任务 ID"),
+    changed_files: z.array(z.string()).optional().describe("变更文件列表（不传则使用任务记录中的文件）"),
+    skip_push: z.boolean().optional().describe("跳过推送"),
+    skip_pr: z.boolean().optional().describe("跳过 PR 创建"),
+};
+const CoordCheckSchema = {
+    task_id: z.string().optional().describe("任务 ID（用于获取变更文件列表）"),
+    branch: z.string().optional().describe("指定分支（不传则使用当前分支）"),
+};
+const TeamStatusSchema = {
+    since: z.string().optional().describe("起始日期（ISO 格式，默认 7 天前）"),
+    include_knowledge: z.boolean().optional().describe("包含知识库更新信息"),
+};
+const ContractCheckSchema = {
+    task_id: z.string().describe("任务 ID"),
+    changed_files: z.array(z.string()).optional().describe("变更文件列表（不传则从任务记录获取）"),
+};
+const OnboardSchema = {
+    step: z.enum(["project_overview", "code_tour", "knowledge_review", "first_task"]).optional().describe("当前引导步骤"),
+    reset: z.boolean().optional().describe("重置引导会话"),
+};
+const FeasibilityCheckSchema = {
+    task_id: z.string().describe("任务 ID（需要已完成 classify）"),
+};
+const DebugSchema = {
+    error_output: z.string().describe("错误输出文本"),
+    task_id: z.string().optional().describe("关联任务 ID"),
+};
+const ObservabilitySchema = {
+    period_days: z.number().optional().describe("报告周期天数（默认 30）"),
+};
+const MigrationCheckSchema = {
+    content: z.string().describe("迁移文件内容（SQL/DDL）"),
+    filename: z.string().describe("文件名（如 V001__create_users.sql）"),
+};
+const TestGuideSchema = {
+    changed_files: z.array(z.string()).describe("变更文件列表"),
+};
+const TestQualitySchema = {
+    content: z.string().describe("测试文件内容"),
+    filename: z.string().describe("测试文件名"),
+};
+const DependencyScanSchema = {
+    content: z.string().describe("依赖声明文件内容（package.json / pom.xml / build.gradle）"),
+    filename: z.string().describe("文件名"),
+};
+// ── 工具注册 ──
+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 {
+                return await handler(args);
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) }) }],
+                    isError: true,
+                };
+            }
+        });
+    }
+    // ── sf_classify ──
+    registerSafeTool("sf_classify", "分析开发者意图，返回任务类型、风险、复杂度和执行策略", ClassifySchema, async (args) => {
+        // 检查是否存在进行中的任务
+        const existing = await taskContext.getCurrentTask();
+        if (existing && !["done", "failed"].includes(existing.status)) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            warning: "存在未完成的任务",
+                            existing_task_id: existing.task_id,
+                            existing_status: existing.status,
+                            existing_intent: existing.intent,
+                            hint: "调用 sf_status action=cancel 取消旧任务，或继续完成它",
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        // 创建任务上下文
+        const ctx = await taskContext.create(args.intent, config.product_profile);
+        const input = { intent: args.intent, project_path: projectPath };
+        const classification = classify(input);
+        // 存储分类结果
+        await taskContext.setClassification(ctx.task_id, classification);
+        // 转换到膨胀阶段
+        await taskContext.updateStatus(ctx.task_id, "expanding");
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        task_id: ctx.task_id,
+                        ...classification,
+                    }, null, 2),
+                }],
+        };
+    });
+    // ── sf_expand ──
+    registerSafeTool("sf_expand", "将意图膨胀为结构化 prompt，包含 scope、验收标准和知识匹配。当存在计划时自动注入当前阶段上下文和输出模板", ExpandSchema, async (args) => {
+        const ctx = await taskContext.load(args.task_id);
+        if (!ctx || !ctx.classification) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在或尚未分类，请先调用 sf_classify" }) }],
+                isError: true,
+            };
+        }
+        // 构建计划上下文（如果存在计划）
+        let planContext;
+        if (ctx.planning && ctx.planning.sub_tasks.length > 0 && ctx.planning.current_step_index < ctx.planning.sub_tasks.length) {
+            const currentStep = ctx.planning.sub_tasks[ctx.planning.current_step_index];
+            const previousOutputs = {};
+            // 读取前序步骤的产出文件（P3: 产物系统）
+            for (let i = 0; i < ctx.planning.current_step_index; i++) {
+                const step = ctx.planning.sub_tasks[i];
+                if (step.output_path) {
+                    try {
+                        const fs = await import("node:fs/promises");
+                        const content = await fs.readFile(step.output_path, "utf-8");
+                        previousOutputs[step.title] = content;
+                    }
+                    catch {
+                        // 文件不存在则跳过
+                    }
+                }
+            }
+            planContext = { current_step: currentStep, previous_outputs: previousOutputs };
+        }
+        const expansion = await expand({
+            intent: ctx.intent,
+            classification: ctx.classification,
+            projectPath,
+            config,
+            knowledgeIndex,
+            clarificationAnswers: args.clarification_answers,
+            plan_context: planContext,
+        });
+        expansion.task_id = args.task_id;
+        // 存储膨胀结果
+        await taskContext.setExpansion(args.task_id, expansion);
+        // 转换到执行阶段
+        await taskContext.updateStatus(args.task_id, "executing");
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(expansion, null, 2),
+                }],
+        };
+    });
+    // ── sf_verify ──
+    registerSafeTool("sf_verify", "根据变更文件生成验证命令（构建、测试、验收检查），由 Claude Code Bash 执行", VerifySchema, async (args) => {
+        const ctx = await taskContext.load(args.task_id);
+        if (!ctx) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在" }) }],
+                isError: true,
+            };
+        }
+        // 转换到验证阶段
+        await taskContext.updateStatus(args.task_id, "verifying");
+        const acceptanceItems = ctx.expansion
+            ? [...ctx.expansion.acceptance.automated, ...ctx.expansion.acceptance.manual]
+            : [];
+        const verifyResult = generateVerifyCommands(config, args.changed_files, acceptanceItems);
+        verifyResult.task_id = args.task_id;
+        // 记录变更文件
+        await taskContext.setExecution(args.task_id, args.changed_files);
+        // 存储验证结果
+        await taskContext.setVerification(args.task_id, verifyResult);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(verifyResult, null, 2),
+                }],
+        };
+    });
+    // ── sf_learn ──
+    registerSafeTool("sf_learn", "从任务执行结果中提取知识，低置信度暂存，高置信度直接入库", LearnSchema, async (args) => {
+        const ctx = await taskContext.load(args.task_id);
+        if (!ctx) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在" }) }],
+                isError: true,
+            };
+        }
+        // 如适用，记录失败
+        if (args.result === "failure" && args.failure_type) {
+            await taskContext.setExecution(args.task_id, [], {
+                attempt: (ctx.execution?.attempt_count ?? 0) + 1,
+                type: args.failure_type,
+                message: args.verify_output
+                    ? `build=${args.verify_output.build_passed} tests=${args.verify_output.tests_passed}`
+                    : "unknown failure",
+                timestamp: new Date().toISOString(),
+            });
+        }
+        // 转换到学习阶段
+        await taskContext.updateStatus(args.task_id, "learning");
+        const learnResult = await evolve({
+            taskContext: ctx,
+            result: args.result,
+            verifyOutput: args.verify_output,
+            failureType: args.failure_type,
+            retryCount: ctx.execution?.attempt_count ?? 0,
+        }, projectPath);
+        // 确定最终状态: 重试或完成
+        const attemptCount = (ctx.execution?.attempt_count ?? 0) + (args.result === "failure" ? 1 : 0);
+        const maxAttempts = ctx.execution?.max_attempts ?? 3;
+        if (args.result === "failure" && attemptCount < maxAttempts && args.failure_type !== "deterministic") {
+            // 可重试: 转换到重试阶段
+            await taskContext.updateStatus(args.task_id, "retrying");
+            learnResult.retry_hint = `第 ${attemptCount}/${maxAttempts} 次尝试失败，${args.failure_type === "scope_insufficient" ? "需要扩大范围" : "请修复后重试"}`;
+        }
+        else {
+            // 最终: 转换到完成（或所有重试耗尽后标记为失败）
+            const finalStatus = args.result === "failure" ? "failed" : "done";
+            await taskContext.updateStatus(args.task_id, finalStatus);
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(learnResult, null, 2),
+                }],
+        };
+    });
+    // ── sf_status ──
+    registerSafeTool("sf_status", "查询当前任务状态、列出近期任务、恢复中断任务或取消任务", StatusSchema, async (args) => {
+        const action = args.action || "current";
+        switch (action) {
+            case "current": {
+                const ctx = args.task_id
+                    ? await taskContext.load(args.task_id)
+                    : await taskContext.getCurrentTask();
+                if (!ctx) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({ message: "当前无活跃任务" }) }],
+                    };
+                }
+                const resumable = taskContext.isResumable(ctx);
+                const result = {
+                    task_id: ctx.task_id,
+                    intent: ctx.intent,
+                    status: ctx.status,
+                    created_at: ctx.created_at,
+                    resumable,
+                };
+                if (resumable) {
+                    result.resume_hint = taskContext.getResumeHint(ctx);
+                }
+                if (ctx.classification) {
+                    result.task_type = ctx.classification.task_type;
+                    result.risk = ctx.classification.risk;
+                    result.strategy = ctx.classification.strategy;
+                }
+                if (ctx.execution) {
+                    result.changed_files = ctx.execution.changed_files;
+                    result.attempt_count = ctx.execution.attempt_count;
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case "recent": {
+                const recent = await taskContext.listRecent(10);
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ tasks: recent }, null, 2) }],
+                };
+            }
+            case "resume": {
+                if (!args.task_id) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({ error: "恢复任务需要 task_id" }) }],
+                        isError: true,
+                    };
+                }
+                const ctx = await taskContext.load(args.task_id);
+                if (!ctx) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({ error: "任务不存在" }) }],
+                        isError: true,
+                    };
+                }
+                if (!taskContext.isResumable(ctx)) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({ error: `任务状态 ${ctx.status} 不可恢复`, status: ctx.status }) }],
+                        isError: true,
+                    };
+                }
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                task_id: ctx.task_id,
+                                intent: ctx.intent,
+                                status: ctx.status,
+                                resume_hint: taskContext.getResumeHint(ctx),
+                                classification: ctx.classification,
+                                expansion: ctx.expansion ? {
+                                    scope: ctx.expansion.scope,
+                                    matched_patterns: ctx.expansion.matched_patterns,
+                                } : undefined,
+                                execution: ctx.execution ? {
+                                    changed_files: ctx.execution.changed_files,
+                                    attempt_count: ctx.execution.attempt_count,
+                                } : undefined,
+                            }, null, 2),
+                        }],
+                };
+            }
+            case "cancel": {
+                if (!args.task_id) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({ error: "取消任务需要 task_id" }) }],
+                        isError: true,
+                    };
+                }
+                const cancelled = await taskContext.cancel(args.task_id);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({ task_id: args.task_id, cancelled }),
+                        }],
+                };
+            }
+            default:
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: `未知操作: ${action}` }) }],
+                    isError: true,
+                };
+        }
+    });
+    // ── sf_plan ──
+    registerSafeTool("sf_plan", "将复杂意图拆解为子任务列表。支持知识驱动的 pipeline_procedure 流程（自动绑定模板）和仓库边界拆分两种策略。仅在 complexity=high 时有效", PlanSchema, async (args) => {
+        const ctx = await taskContext.load(args.task_id);
+        if (!ctx?.classification) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在或尚未分类" }) }],
+                isError: true,
+            };
+        }
+        const result = planTask({
+            intent: ctx.intent,
+            classification: ctx.classification,
+            config,
+            knowledgeIndex,
+        });
+        result.task_id = args.task_id;
+        await taskContext.setPlanning(args.task_id, result);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── 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) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: "任务没有多阶段计划，请先调用 sf_plan" }) }],
+                isError: true,
+            };
+        }
+        const plan = ctx.planning;
+        const previousStep = plan.sub_tasks[plan.current_step_index];
+        const previousStepTitle = previousStep?.title ?? "未知";
+        const nextIndex = plan.current_step_index + 1;
+        if (nextIndex >= plan.sub_tasks.length) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({
+                            task_id: args.task_id,
+                            previous_step: previousStepTitle,
+                            current_step_index: plan.current_step_index,
+                            total_steps: plan.sub_tasks.length,
+                            is_completed: true,
+                            message: `所有 ${plan.sub_tasks.length} 个阶段已完成`,
+                        }, null, 2) }],
+            };
+        }
+        // 推进阶段索引
+        plan.current_step_index = nextIndex;
+        await taskContext.setPlanning(args.task_id, plan);
+        const nextStep = plan.sub_tasks[nextIndex];
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        task_id: args.task_id,
+                        previous_step: previousStepTitle,
+                        current_step_index: nextIndex,
+                        current_step: {
+                            id: nextStep.id,
+                            title: nextStep.title,
+                            output_path: nextStep.output_path,
+                        },
+                        total_steps: plan.sub_tasks.length,
+                        is_completed: false,
+                        message: `阶段推进: ${previousStepTitle} → ${nextStep.title}`,
+                    }, null, 2),
+                }],
+        };
+    });
+    // ── sf_analyze ──
+    registerSafeTool("sf_analyze", "分析意图的影响范围，对比声明范围，提示是否需要扩大作用域。建议性，不强制", AnalyzeSchema, async (args) => {
+        const ctx = await taskContext.load(args.task_id);
+        if (!ctx?.expansion) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: "任务尚未膨胀，请先调用 sf_expand" }) }],
+                isError: true,
+            };
+        }
+        const result = await analyzeImpact({
+            intent: ctx.intent,
+            classification: ctx.classification,
+            expansion: ctx.expansion,
+            config,
+            projectPath,
+        });
+        result.task_id = args.task_id;
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── sf_review ──
+    registerSafeTool("sf_review", "审查代码变更的质量、安全、性能和技术债务。hotfix 场景可跳过。建议性，不强制修复", ReviewSchema, async (args) => {
+        const ctx = await taskContext.load(args.task_id);
+        if (!ctx) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在" }) }],
+                isError: true,
+            };
+        }
+        const tracker = new DebtTracker(projectPath);
+        const result = await reviewCode({
+            changedFiles: args.changed_files,
+            projectPath,
+            config,
+            classification: ctx.classification,
+            fileContents: args.file_contents,
+            knowledgeIndex,
+            uncertainty_triggers: ctx.expansion?.uncertainty_triggers,
+        }, tracker);
+        result.task_id = args.task_id;
+        await taskContext.setCodeReview(args.task_id, result);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── 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) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在或尚未分类" }) }],
+                isError: true,
+            };
+        }
+        if (ctx.classification.task_type !== "scaffold") {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "sf_scaffold 仅适用于 scaffold 类型任务",
+                            current_type: ctx.classification.task_type,
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        const result = await generateScaffold({
+            intent: ctx.intent,
+            classification: ctx.classification,
+            config,
+            projectPath,
+        });
+        result.task_id = args.task_id;
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── sf_deliver ──
+    registerSafeTool("sf_deliver", "验收后自动提交代码、推送、创建 PR 和生成变更日志", DeliverSchema, async (args) => {
+        const ctx = await taskContext.load(args.task_id);
+        if (!ctx) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在" }) }],
+                isError: true,
+            };
+        }
+        const result = await deliver({
+            taskContext: ctx,
+            config,
+            knowledgeIndex,
+            projectPath,
+            gitOps: realGitOps,
+            skipPush: args.skip_push,
+            skipPr: args.skip_pr,
+        });
+        await taskContext.setDelivery(args.task_id, result);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── sf_coord_check ──
+    registerSafeTool("sf_coord_check", "预测性冲突检测和跨仓库协调提示，检查分支状态、本地变更和潜在冲突", CoordCheckSchema, async (args) => {
+        const result = await checkConflicts({
+            projectPath,
+            config,
+            branch: args.branch,
+            gitOps: realGitOps,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── sf_team_status ──
+    registerSafeTool("sf_team_status", "查询团队活动流、成员工作负载、过期分支和知识库更新状态", TeamStatusSchema, async (args) => {
+        const result = await getTeamStatus({
+            projectPath,
+            config,
+            since: args.since,
+            gitOps: realGitOps,
+            knowledgeIndex: args.include_knowledge ? knowledgeIndex : undefined,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── sf_contract_check ──
+    registerSafeTool("sf_contract_check", "检测 API 契约变更（路由、DTO 字段等），评估破坏性影响和跨服务依赖", ContractCheckSchema, async (args) => {
+        let changedFiles = args.changed_files;
+        if (!changedFiles) {
+            const ctx = await taskContext.load(args.task_id);
+            changedFiles = ctx?.execution?.changed_files ?? [];
+        }
+        const result = await checkContractChanges({
+            changedFiles,
+            projectPath,
+            config,
+            gitOps: realGitOps,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── sf_onboard ──
+    registerSafeTool("sf_onboard", "新人分步引导：项目概览 → 代码导览 → 知识回顾 → 首个任务建议", OnboardSchema, async (args) => {
+        const result = await onboard({
+            config,
+            projectPath,
+            knowledgeIndex,
+            gitOps: realGitOps,
+            currentStep: args.step,
+            reset: args.reset,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── sf_feasibility_check ──
+    registerSafeTool("sf_feasibility_check", "分析任务可行性：可行/风险/不可行三档评估，纯建议不阻断流程", FeasibilityCheckSchema, async (args) => {
+        const ctx = await taskContext.load(args.task_id);
+        if (!ctx?.classification) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: "任务不存在或未完成分类，请先调用 sf_classify" }) }],
+                isError: true,
+            };
+        }
+        const result = checkFeasibility(ctx.classification, config);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── sf_debug ──
+    registerSafeTool("sf_debug", "智能排障：解析错误 → 追踪调用链 → 根因分析 → 修复方案 → 测试建议", DebugSchema, async (args) => {
+        const projectScope = [
+            ...config.scope.backend,
+            ...config.scope.frontend,
+        ];
+        const result = debugError(args.error_output, args.task_id || `debug-${Date.now()}`, projectScope);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── sf_observability ──
+    registerSafeTool("sf_observability", "系统可观测：运行指标、成本估算、告警检测、周期报告", ObservabilitySchema, async (args) => {
+        const stateDir = taskContext.getStateDir();
+        const result = await generateReport(stateDir, args.period_days);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── 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 ──
+    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 ──
+    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 ──
+    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 ──
+    registerSafeTool("sf_debt_report", "生成技术债务报告：按分类/严重度聚合、30 天趋势、优先级排序 Top 5", {}, async () => {
+        const tracker = new DebtTracker(projectPath);
+        const result = await generateDebtReport(tracker);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── Self-maintenance tools (only registered when running inside SoloForge's own project) ──
+    if (options?.isSelfProject) {
+        // ── 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 ──
+        const KnowledgeAddSchema = {
+            title: z.string().describe("知识条目标题（英文 kebab-case，如 payment-rules）"),
+            type: z.enum(["pattern", "procedure", "pipeline_procedure", "domain", "acceptance_template", "review_rule"]).describe("知识类型"),
+            scope: z.array(z.string()).describe("适用范围（如 [backend]、[frontend]、[backend, frontend]）"),
+            when_triggers: z.string().describe("触发关键词（逗号分隔）"),
+            decision_rules: z.string().optional().describe("决策规则（每行一条）"),
+            save_to_drafts: z.boolean().optional().describe("是否保存为草稿（默认 true，需人工 review 后移入正式目录）"),
+            auto_enrich: z.boolean().optional().describe("是否返回行业最佳实践探索指引（默认 true，宿主 AI 将自动执行探索并填充内容）"),
+        };
+        registerSafeTool("sf_knowledge_add", "新增知识条目。默认保存为草稿到 .soloforge/knowledge/drafts/，人工确认后移入正式目录", KnowledgeAddSchema, async (args) => {
+            const result = await addKnowledge({
+                title: args.title,
+                type: args.type,
+                scope: args.scope,
+                when_triggers: args.when_triggers,
+                decision_rules: args.decision_rules,
+                save_to_drafts: args.save_to_drafts,
+                auto_enrich: args.auto_enrich,
+            }, config);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        });
+        // ── sf_knowledge_update ──
+        const KnowledgeUpdateSchema = {
+            entry_name: z.string().describe("要更新的知识条目名称（如 payment-rules）"),
+            when_triggers: z.string().optional().describe("新的触发关键词（替换现有）"),
+            add_decision_rules: z.array(z.string()).optional().describe("追加的决策规则"),
+            add_acceptance_criteria: z.array(z.string()).optional().describe("追加的验收项"),
+            status: z.enum(["active", "deprecated"]).optional().describe("更新条目状态"),
+        };
+        registerSafeTool("sf_knowledge_update", "更新已有知识条目：追加规则、更新触发词、标记废弃。自动创建备份", KnowledgeUpdateSchema, async (args) => {
+            const result = await updateKnowledge({
+                entry_name: args.entry_name,
+                updates: {
+                    when_triggers: args.when_triggers,
+                    add_decision_rules: args.add_decision_rules,
+                    add_acceptance_criteria: args.add_acceptance_criteria,
+                    status: args.status,
+                },
+            }, knowledgeIndex, config);
+            // 重载知识索引
+            if (result.success) {
+                await knowledgeIndex.reload();
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        });
+    } // end isSelfProject guard
+}
+//# sourceMappingURL=tools.js.map