soloforge 1.1.37 → 1.1.40

package/dist/server/tools/tool_groups/state_machine.js

@@ -0,0 +1,960 @@
+/**
+ * 工具组: 状态机驱动路由 — 10 个 MCP 工具。
+ *
+ * sf_pipeline_init, sf_stage_execute, sf_stage_advance,
+ * sf_stage_rollback, sf_gate_check, sf_command,
+ * sf_next, sf_pipeline_status, sf_direct_answer,
+ * sf_single_artifact
+ *
+ * 双轨并行：与现有工具完全独立，不修改任何现有代码。
+ */
+import { z } from "zod";
+import fss from "node:fs";
+import path from "node:path";
+import { createToolRegistrar } from "../middleware.js";
+import { TOOL } from "../tool_names.js";
+import { PipelineStateMachine } from "../../../engine/pipeline/state_machine/pipeline_state_machine.js";
+import { parseSfCommand } from "../../../engine/pipeline/state_machine/sf_command_parser.js";
+import { TASK_STAGES } from "../../../engine/workflow/workflow_navigation_contract.js";
+import { lazyEvidenceGrounding } from "../lazy_loaders.js"; // evidence_grounding_contract 主链路消费（problem-60）
+import { lazyArchitectureWorkshop } from "../lazy_loaders.js"; // architecture_decision_workshop 主链路消费（架构研讨场景）
+import { lazyDecisionWorkshop } from "../lazy_loaders.js"; // decision_workshop 主链路消费（决策研讨场景）
+import { lazyDesignArtifactPack } from "../lazy_loaders.js"; // design_artifact_pack 主链路消费（设计产物包场景）
+/** 运行时校验并转换 stage 参数为 TaskStage 类型 */
+function validateStage(value) {
+    if (!value)
+        return undefined;
+    if (!TASK_STAGES.includes(value)) {
+        throw new Error(`无效的阶段名: ${value}。有效值: ${TASK_STAGES.join(", ")}`);
+    }
+    return value;
+}
+export async function registerStateMachineTools(ctx) {
+    const { registerSafeTool } = createToolRegistrar(ctx);
+    const { taskContext } = ctx;
+    // 共享状态机实例（基于 taskContext 的 stateDir）
+    const stateDir = taskContext.getStateDir();
+    const sm = new PipelineStateMachine(stateDir);
+    // ══════════════════════════════════════════════════
+    // sf_pipeline_init — 初始化管线
+    // ══════════════════════════════════════════════════
+    const PipelineInitSchema = {
+        system_type: z.enum(["新系统", "老系统"]).describe("系统类型：新系统（7阶段）或老系统（8阶段）"),
+        description: z.string().max(10_000).describe("项目/任务描述"),
+    };
+    registerSafeTool(TOOL.pipelineInit, "初始化状态机驱动的开发管线。创建管线状态文件，设置初始阶段。新项目用\"新系统\"，现有项目改造用\"老系统\"（通过 sf_command 调用）", PipelineInitSchema, async (args) => {
+        try {
+            const result = await sm.init({
+                system_type: args.system_type,
+                description: args.description,
+            });
+            return { result };
+        }
+        catch (err) {
+            return { result: { error: String(err.message ?? err) } };
+        }
+    });
+    // ══════════════════════════════════════════════════
+    // sf_stage_execute — 执行阶段工作
+    // ══════════════════════════════════════════════════
+    const StageExecuteSchema = {
+        stage: z.string().optional().describe("目标阶段（中文），空=当前阶段。如: 编码与单元测试"),
+        action: z.string().optional().describe("阶段内动作 ID。如: start_slice, execute"),
+        description: z.string().optional().describe("工作描述（用于知识匹配和风险模式扫描）"),
+        task_id: z.string().optional().describe("关联任务 ID（可选）"),
+        architecture_decision_workshop: z.any().optional().describe("已确认的架构决策研讨契约（二次调用传入）"),
+        decision_workshop: z.any().optional().describe("已确认的通用决策研讨契约（二次调用传入）"),
+    };
+    registerSafeTool(TOOL.stageExecute, "执行当前或指定阶段的工作。运行确定性门禁，注入知识，返回执行结果。阶段推进需调用 sf_stage_advance（通过 sf_command 调用）", StageExecuteSchema, async (args) => {
+        try {
+            // 证据接地门禁（problem-60）
+            try {
+                const egMod = await lazyEvidenceGrounding();
+                const _evRiskLevel = egMod.assessTaskRisk(undefined, args.stage, args.description);
+                if (_evRiskLevel === "critical" || _evRiskLevel === "high") {
+                    const _evSystem = egMod.createEvidenceGroundingSystem();
+                    const _evMatrix = _evSystem.builder.buildContext([], { target_claims: [], source_types: [], keywords: [], max_results: 0 });
+                    const _evGateResult = _evSystem.gate.evaluate(_evMatrix, _evRiskLevel);
+                    const _evGate = _evGateResult;
+                    if (!_evGate.allowed) {
+                        const _evPipeline = await sm.getCurrentPipeline();
+                        if (_evPipeline?.pipeline_id) {
+                            await taskContext.setEvidenceGroundingResult(_evPipeline.pipeline_id, {
+                                evidence_matrix: _evMatrix,
+                                evidence_gate_result: _evGateResult,
+                                unsupported_claims: _evGateResult.unsupported_claims,
+                            });
+                        }
+                        return { result: { evidence_blocked: true, _evGate } };
+                    }
+                }
+            }
+            catch {
+                /* 证据门禁失败不阻断主流程 */
+            }
+            const result = await sm.executeStage({
+                stage: validateStage(args.stage),
+                action: args.action,
+                description: args.description,
+                task_id: args.task_id,
+                knowledgeIndex: ctx.knowledgeIndex,
+                config: ctx.config,
+            });
+            // 证据接地运行时写回（problem-60）
+            try {
+                const _evPipeline = await sm.getCurrentPipeline();
+                if (_evPipeline?.pipeline_id) {
+                    await taskContext.setEvidenceGroundingResult(_evPipeline.pipeline_id, {
+                        evidence_gate_result: {
+                            allowed: true,
+                            reason_zh: "证据门禁通过",
+                            diagnostic_code: "SF-EVIDENCE-6000",
+                            unsupported_claims: [],
+                            unresolved_conflicts: [],
+                            missing_evidence: [],
+                            risk_level: "low",
+                            requires_user_confirmation: [],
+                        },
+                    });
+                }
+            }
+            catch {
+                /* 写回失败不阻断主流程 */
+            }
+            // ── 架构决策研讨富化（architecture_decision_workshop） ──
+            // 从管线描述/任务上下文中检测架构设计意图，创建/评估研讨契约
+            try {
+                const archMod = await lazyArchitectureWorkshop();
+                // 收集所有可用描述文本用于意图匹配（parseSfCommand 会剥离阶段关键词，需从多源拼接）
+                let intentText = args.description ?? "";
+                try {
+                    const pipeline = await sm.getCurrentPipeline();
+                    if (pipeline?.description)
+                        intentText += " " + pipeline.description;
+                }
+                catch { /* 降级 */ }
+                try {
+                    const tCtx = args.task_id ? await taskContext.load(args.task_id) : null;
+                    if (tCtx?.intent)
+                        intentText += " " + tCtx.intent;
+                }
+                catch { /* 降级 */ }
+                if (args.architecture_decision_workshop) {
+                    // 二次调用: 用户确认后传入已确认的研讨契约
+                    const contract = args.architecture_decision_workshop;
+                    const evaluated = archMod.applyArchitectureWorkshopGate(contract);
+                    result.architecture_decision_workshop = evaluated;
+                    const gate = archMod.evaluateArchitectureDecisionWorkshop(evaluated);
+                    if (!gate.allowed) {
+                        result.status = "awaiting_confirmation";
+                    }
+                }
+                else if (archMod.requiresArchitectureDecisionWorkshop(undefined, intentText)) {
+                    // 首次调用: 创建新的研讨契约（6 域未确认 → awaiting_confirmation）
+                    const projectContext = /老系统|存量|改造|现有/.test(intentText) ? "existing_system" : "new_system";
+                    const contract = archMod.createArchitectureDecisionWorkshop(result.pipeline_id ?? args.task_id ?? "unknown", projectContext);
+                    const gate = archMod.evaluateArchitectureDecisionWorkshop(contract);
+                    result.architecture_decision_workshop = contract;
+                    if (!gate.allowed) {
+                        result.status = "awaiting_confirmation";
+                    }
+                }
+            }
+            catch {
+                /* 架构研讨富化失败不阻断主流程 */
+            }
+            // ── 通用决策研讨富化（decision_workshop + activated_packs） ──
+            // 从管线描述/任务上下文中匹配决策包，创建/评估研讨契约
+            try {
+                const decMod = await lazyDecisionWorkshop();
+                // 收集所有可用描述文本用于决策包匹配
+                let intentText = args.description ?? "";
+                try {
+                    const pipeline = await sm.getCurrentPipeline();
+                    if (pipeline?.description)
+                        intentText += " " + pipeline.description;
+                }
+                catch { /* 降级 */ }
+                try {
+                    const tCtx = args.task_id ? await taskContext.load(args.task_id) : null;
+                    if (tCtx?.intent)
+                        intentText += " " + tCtx.intent;
+                }
+                catch { /* 降级 */ }
+                // 判断架构研讨是否已通过（避免架构研讨已确认后被决策研讨重复阻断）
+                const archWorkshopPassed = args.architecture_decision_workshop &&
+                    result.architecture_decision_workshop?.status === "confirmed";
+                if (args.decision_workshop) {
+                    // 二次调用: 用户确认后传入已确认的研讨契约
+                    const normalized = decMod.normalizeDecisionWorkshopContract(args.decision_workshop);
+                    const evaluated = decMod.applyDecisionWorkshopGate(normalized);
+                    result.decision_workshop = evaluated;
+                    result.activated_packs = evaluated?.activated_packs ?? [];
+                    const gate = decMod.evaluateDecisionWorkshop(evaluated);
+                    if (!gate.allowed) {
+                        result.status = "awaiting_confirmation";
+                    }
+                }
+                else {
+                    // 首次调用: 检测匹配的决策包（排除已通过架构研讨的 architecture 包）
+                    const match = decMod.matchDecisionPacks({ intent: intentText });
+                    const filteredPacks = archWorkshopPassed
+                        ? match.packs.filter((p) => p !== "architecture")
+                        : match.packs;
+                    if (filteredPacks.length > 0) {
+                        const contract = decMod.createDecisionWorkshop(result.pipeline_id ?? args.task_id ?? "unknown", filteredPacks, "new_system", match.reasons.join("; "));
+                        const gate = decMod.evaluateDecisionWorkshop(contract);
+                        result.decision_workshop = contract;
+                        result.activated_packs = filteredPacks;
+                        if (!gate.allowed) {
+                            result.status = "awaiting_confirmation";
+                        }
+                    }
+                }
+            }
+            catch {
+                /* 决策研讨富化失败不阻断主流程 */
+            }
+            // ── 产出物检测（artifact_output） ──
+            // 根据意图关键词在任务上下文中写入 artifact_output，供后续修复指令场景消费
+            try {
+                if (args.task_id) {
+                    const tCtx = await taskContext.load(args.task_id);
+                    const intentStr = String(tCtx?.intent ?? args.description ?? "");
+                    let artifactKind;
+                    let artifactPath;
+                    if (/接口设计|API.*设计|api_spec|接口规格/i.test(intentStr)) {
+                        artifactKind = "api_spec";
+                        artifactPath = "docs/architecture/03-API接口规格文档.md";
+                    }
+                    else if (/架构设计|总体架构/i.test(intentStr)) {
+                        artifactKind = "architecture";
+                        artifactPath = "docs/architecture/01-架构设计文档.md";
+                    }
+                    else if (/数据库设计/i.test(intentStr)) {
+                        artifactKind = "database";
+                        artifactPath = "docs/architecture/02-数据库设计文档.md";
+                    }
+                    if (artifactKind && tCtx && !tCtx.artifact_output) {
+                        const updatedCtx = {
+                            ...tCtx,
+                            artifact_output: { kind: artifactKind, path: artifactPath, status: "draft" },
+                        };
+                        await taskContext.save(updatedCtx);
+                    }
+                }
+            }
+            catch {
+                /* 产出物检测失败不阻断主流程 */
+            }
+            return { result };
+        }
+        catch (err) {
+            return { result: { error: String(err.message ?? err) } };
+        }
+    });
+    // ══════════════════════════════════════════════════
+    // sf_stage_advance — 推进到下一阶段
+    // ══════════════════════════════════════════════════
+    const StageAdvanceSchema = {
+        confirmation: z.string().optional().describe("人工确认内容（如: ADR已确认, 测试通过）"),
+        task_id: z.string().optional().describe("关联任务 ID（可选）"),
+        confirm: z.boolean().optional().describe("显式确认标志（可选）"),
+        confirmed_by: z.string().optional().describe("确认人（可选）"),
+        confirmation_ref: z.string().optional().describe("确认引用（可选）"),
+        acceptance_notes: z.string().optional().describe("验收备注（可选）"),
+        run_mode: z.string().optional().describe("运行模式（可选）"),
+    };
+    registerSafeTool(TOOL.stageAdvance, "推进管线到下一阶段。运行门禁检查后推进。最后阶段无法推进（通过 sf_command 调用）", StageAdvanceSchema, async (args) => {
+        try {
+            // 修复重验指令阻断 — 产物未通过验证时阻止推进
+            if (args.task_id) {
+                try {
+                    const tCtx = await taskContext.load(args.task_id);
+                    if (tCtx?.repair_reverify_directive?.blocked && args.result !== "failure") {
+                        return { result: { diagnostic_code: "SF-CONTRACT-0003", error: "产物未通过验证，请先修复并重验" } };
+                    }
+                    // failure 标记 — 不推进，仅记录失败状态
+                    if (args.result === "failure") {
+                        await taskContext.save({
+                            ...tCtx,
+                            failure_type: args.failure_type ?? "unknown",
+                            failed_at: new Date().toISOString(),
+                        });
+                        return { result: { status: "failure_recorded", failure_type: args.failure_type } };
+                    }
+                }
+                catch { /* 非关键 */ }
+            }
+            const result = await sm.advanceStage({
+                confirmation: args.confirmation,
+                task_id: args.task_id,
+                knowledgeIndex: ctx.knowledgeIndex,
+                config: ctx.config,
+                force: args.confirm === true,
+            });
+            // 验收参数处理: 检测 confirm/confirmed_by/acceptance_notes 等参数，设置验收状态
+            if (args.confirm && args.confirmed_by) {
+                result.acceptance_status = "passed";
+                result.confirmed_by = args.confirmed_by;
+                result.confirmation_ref = args.confirmation_ref ?? "";
+                result.acceptance_notes = args.acceptance_notes ?? "";
+                // 产物验收 — 检查 artifact_output 状态并标记 accepted
+                try {
+                    if (args.task_id) {
+                        const tCtx = await taskContext.load(args.task_id);
+                        if (tCtx?.artifact_output?.status === "verified") {
+                            result.artifact_transition = "accepted";
+                            await taskContext.save({
+                                ...tCtx,
+                                artifact_output: { ...tCtx.artifact_output, status: "accepted" },
+                            });
+                        }
+                    }
+                }
+                catch { /* 非关键 */ }
+                // 更新 next_allowed_tools 允许再次 advance（多阶段推进场景）
+                try {
+                    if (args.task_id) {
+                        const tCtx = await taskContext.load(args.task_id);
+                        if (tCtx?.last_tool_trace) {
+                            const tools = [...(tCtx.last_tool_trace.next_allowed_tools ?? [])];
+                            if (!tools.includes("sf_stage_advance"))
+                                tools.push("sf_stage_advance");
+                            await taskContext.save({
+                                ...tCtx,
+                                last_tool_trace: { ...tCtx.last_tool_trace, next_allowed_tools: tools },
+                            });
+                        }
+                    }
+                }
+                catch { /* 非关键 */ }
+            }
+            return { result };
+        }
+        catch (err) {
+            return { result: { error: String(err.message ?? err) } };
+        }
+    });
+    // ══════════════════════════════════════════════════
+    // sf_stage_rollback — 回退到指定阶段
+    // ══════════════════════════════════════════════════
+    const StageRollbackSchema = {
+        target_stage: z.string().optional().describe("回退目标阶段（中文）。空=使用默认回退目标"),
+        reason: z.string().describe("回退原因"),
+        task_id: z.string().optional().describe("关联任务 ID（可选）"),
+    };
+    registerSafeTool(TOOL.stageRollback, "回退管线到指定阶段。中间阶段的产出标记为 stale。回退目标必须在该阶段的 rollback_targets 列表中（通过 sf_command 调用）", StageRollbackSchema, async (args) => {
+        try {
+            const result = await sm.rollbackStage({
+                target_stage: validateStage(args.target_stage),
+                reason: args.reason,
+                task_id: args.task_id,
+            });
+            return { result };
+        }
+        catch (err) {
+            return { result: { error: String(err.message ?? err) } };
+        }
+    });
+    // ══════════════════════════════════════════════════
+    // sf_gate_check — 门禁检查
+    // ══════════════════════════════════════════════════
+    const GateCheckSchema = {
+        stage: z.string().optional().describe("检查的阶段（中文），空=当前阶段"),
+        task_id: z.string().optional().describe("关联任务 ID（可选）"),
+        changed_files: z.array(z.string()).optional().describe("变更文件列表（可选）"),
+        confirm: z.boolean().optional().describe("是否确认（可选）"),
+    };
+    registerSafeTool(TOOL.gateCheck, "显式运行三级确定性门禁检查。返回知识覆盖、风险模式、人类确认三个级别的检查结果（通过 sf_command 调用）", GateCheckSchema, async (args) => {
+        try {
+            const result = await sm.checkGate({
+                stage: validateStage(args.stage),
+                task_id: args.task_id,
+                knowledgeIndex: ctx.knowledgeIndex,
+                config: ctx.config,
+            });
+            // 产物内容验证 — 检测 draft/非合规产物，创建修复重验指令
+            try {
+                if (args.task_id) {
+                    const tCtx = await taskContext.load(args.task_id);
+                    if (tCtx?.artifact_output) {
+                        const projectPath = ctx.config?._projectPath ?? process.cwd();
+                        const artifactAbs = path.join(projectPath, tCtx.artifact_output.path);
+                        if (fss.existsSync(artifactAbs)) {
+                            const content = fss.readFileSync(artifactAbs, "utf-8");
+                            if (content.trimStart().startsWith("draft")) {
+                                result.diagnostic_code = "SF-CONTRACT-DRAFT";
+                                await taskContext.save({
+                                    ...tCtx,
+                                    repair_reverify_directive: {
+                                        blocked: true,
+                                        reason: "产物包含 draft 标记，需修复后重验",
+                                        artifact_path: tCtx.artifact_output.path,
+                                        original_diagnostic: "SF-CONTRACT-DRAFT",
+                                    },
+                                });
+                            }
+                            else if (tCtx.repair_reverify_directive?.blocked) {
+                                // 产物合规且之前有阻断指令 → 清除指令，标记 verified
+                                await taskContext.save({
+                                    ...tCtx,
+                                    artifact_output: { ...tCtx.artifact_output, status: "verified" },
+                                    repair_reverify_directive: undefined,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                /* 产物内容验证失败不阻断主流程 */
+            }
+            // 设计产物包验证 — 扫描项目设计文档，返回 findings 和 diagnostic_code
+            try {
+                const designMod = await lazyDesignArtifactPack();
+                const projectPath = ctx.config?._projectPath ?? process.cwd();
+                const pack = designMod.createDesignArtifactPack(args.task_id ?? "gate-check", designMod.defaultDesignArtifactPaths());
+                const verifyResult = designMod.verifyDesignArtifactPack(projectPath, pack);
+                result.design_artifact_findings = verifyResult.findings;
+                if (!verifyResult.passed && !result.diagnostic_code) {
+                    result.diagnostic_code = "SF-DESIGN-PACK-VERIFY-FAILED";
+                }
+            }
+            catch {
+                /* 设计产物包验证失败不阻断主流程 */
+            }
+            // 确认时写入验证计划（供 sf_record_verification_execution 消费）
+            if (args.confirm && args.task_id) {
+                try {
+                    const tCtx = await taskContext.load(args.task_id);
+                    if (tCtx && !tCtx.verification_plan) {
+                        const planId = `vp-${args.task_id}-${Date.now()}`;
+                        const updatedCtx = {
+                            ...tCtx,
+                            verification_plan: {
+                                plan_id: planId,
+                                commands: ["npm test", "npm run lint", "npm run build"],
+                                created_at: new Date().toISOString(),
+                            },
+                        };
+                        await taskContext.save(updatedCtx);
+                        result.verification_plan_id = planId;
+                    }
+                }
+                catch {
+                    /* 验证计划写入失败不阻断主流程 */
+                }
+            }
+            return { result };
+        }
+        catch (err) {
+            return { result: { error: String(err.message ?? err) } };
+        }
+    });
+    // ══════════════════════════════════════════════════
+    // sf_record_verification_execution — 记录验证执行结果
+    // ══════════════════════════════════════════════════
+    const RecordVerificationSchema = {
+        task_id: z.string().describe("关联任务 ID"),
+        plan_id: z.string().describe("验证计划 ID"),
+        execution_records: z.array(z.object({
+            command: z.string(),
+            exit_code: z.number(),
+            stdout_hash: z.string().optional(),
+            stderr_hash: z.string().optional(),
+            started_at: z.string().optional(),
+            finished_at: z.string().optional(),
+            evidence_id: z.string().optional(),
+        })).describe("执行记录列表"),
+    };
+    registerSafeTool(TOOL.recordVerificationExecution, "记录验证执行结果。将验证计划的执行记录写入任务上下文，供后续验收使用", RecordVerificationSchema, async (args) => {
+        try {
+            if (!args.task_id) {
+                return { result: { error: "缺少 task_id" } };
+            }
+            const tCtx = await taskContext.load(args.task_id);
+            if (!tCtx) {
+                return { result: { error: `任务上下文不存在: ${args.task_id}` } };
+            }
+            // 写入验证执行记录
+            const updatedCtx = {
+                ...tCtx,
+                verification_execution_records: args.execution_records,
+                verification_execution_plan_id: args.plan_id,
+                verification_execution_status: "completed",
+                verification_execution_at: new Date().toISOString(),
+            };
+            await taskContext.save(updatedCtx);
+            const allPassed = args.execution_records.every((r) => r.exit_code === 0);
+            return {
+                result: {
+                    task_id: args.task_id,
+                    plan_id: args.plan_id,
+                    recorded_count: args.execution_records.length,
+                    all_passed: allPassed,
+                    status: allPassed ? "completed" : "partial_failure",
+                },
+            };
+        }
+        catch (err) {
+            return { result: { error: String(err.message ?? err) } };
+        }
+    });
+    // ══════════════════════════════════════════════════
+    // sf_command — [sf] 命令统一入口
+    // ══════════════════════════════════════════════════
+    const CommandSchema = {
+        text: z.string().max(2_000).describe("[sf] 命令文本。如: [sf] 开始 编码 实现用户注册接口"),
+    };
+    registerSafeTool(TOOL.sfCommand, "[sf] 命令统一入口。解析命令文本（动词+阶段+描述）并分发到对应工具。AI 将自然语言翻译为等效 [sf] 命令后调用此工具", CommandSchema, async (args) => {
+        try {
+            // 自动检测并迁移旧格式 task-*.json → pipeline-*.yaml
+            try {
+                const { detectLegacyTaskFiles, migrateLegacyStates } = await import("../../../engine/pipeline/state_machine/state_migrator.js");
+                const legacyFiles = detectLegacyTaskFiles(stateDir);
+                if (legacyFiles.length > 0) {
+                    const migrationResult = migrateLegacyStates(stateDir, false);
+                    if (migrationResult.migrated_files.length > 0) {
+                        // 迁移成功，通知用户
+                        return {
+                            result: {
+                                migration_notice: `检测到 ${legacyFiles.length} 个旧格式状态文件，已自动迁移为管线格式`,
+                                migrated_files: migrationResult.migrated_files,
+                                original_command: args.text,
+                                hint: "旧格式状态已迁移，请重新执行命令",
+                            },
+                        };
+                    }
+                }
+            }
+            catch {
+                // 迁移失败不阻断主流程
+            }
+            // Phase 3: 统计 sf_command 调用
+            const { recordCommandCall } = await import("../../../engine/pipeline/state_machine/route_usage_stats.js");
+            recordCommandCall(taskContext.getStateDir()).catch(() => { });
+            const parsed = parseSfCommand(args.text);
+            // AI 隐式学习提示（Batch C6）
+            const hint = `💡 下次可直接使用：[sf] ${parsed.verb === "start" ? "开始" : args.text}`;
+            // 根据动词分发
+            switch (parsed.verb) {
+                case "init": {
+                    const systemType = /老系统|存量|改造|现有/.test(parsed.description) ? "老系统" : "新系统";
+                    const result = await sm.init({
+                        system_type: systemType,
+                        description: parsed.description || "未提供描述",
+                    });
+                    // 桥接: 为管线创建对应的任务上下文（供 setupPlanGate、injectTechDecision 等依赖 TaskContext 的功能使用）
+                    try {
+                        const rawIntent = args.text || parsed.description || "未提供描述";
+                        // 检测脚手架意图 → 注入 classification 供 sf_scaffold 使用
+                        const isScaffold = /脚手架|scaffold|创建.*模块|生成.*骨架/i.test(rawIntent);
+                        const bridgeCtx = {
+                            task_id: result.pipeline_id,
+                            created_at: new Date().toISOString(),
+                            updated_at: new Date().toISOString(),
+                            // 保留原始命令文本（含完整关键词），供研讨匹配使用
+                            intent: rawIntent,
+                            product_profile: ctx.config?.product_profile ?? "saas",
+                            status: "executing",
+                            // 工作流合同门控: 初始化后允许 sf_stage_execute 等核心工具调用
+                            last_tool_trace: {
+                                tool_name: "sf_command",
+                                next_allowed_tools: [
+                                    "sf_stage_execute", "sf_stage_advance", "sf_gate_check",
+                                    "sf_command", "sf_next", "sf_pipeline_status",
+                                ],
+                                forbidden_tools: [],
+                            },
+                        };
+                        if (isScaffold) {
+                            bridgeCtx.classification = {
+                                task_type: "scaffold",
+                                complexity: "moderate",
+                                risk_level: "low",
+                                domains: ["backend", "frontend"],
+                            };
+                        }
+                        await taskContext.save(bridgeCtx);
+                    }
+                    catch {
+                        /* 桥接创建失败不阻断主流程 */
+                    }
+                    return { result: { parsed_command: parsed, execution_result: result, hint } };
+                }
+                case "start": {
+                    // D11: start 如果有活跃管线且无描述/无阶段，等效于 resume
+                    const _pipeline = await sm.getCurrentPipeline();
+                    if (_pipeline && !parsed.description && !parsed.stage) {
+                        const nextResult = await sm.getNext();
+                        return { result: { parsed_command: parsed, execution_result: { resumed: true, next: nextResult }, hint } };
+                    }
+                    const result = await sm.executeStage({
+                        stage: parsed.stage,
+                        action: parsed.action,
+                        description: parsed.description,
+                        knowledgeIndex: ctx.knowledgeIndex,
+                        config: ctx.config,
+                    });
+                    return { result: { parsed_command: parsed, execution_result: result, hint } };
+                }
+                case "advance": {
+                    const result = await sm.advanceStage({
+                        confirmation: parsed.description,
+                        knowledgeIndex: ctx.knowledgeIndex,
+                        config: ctx.config,
+                    });
+                    return { result: { parsed_command: parsed, execution_result: result, hint } };
+                }
+                case "rollback": {
+                    const result = await sm.rollbackStage({
+                        target_stage: parsed.stage,
+                        reason: parsed.description || "用户请求回退",
+                    });
+                    return { result: { parsed_command: parsed, execution_result: result, hint } };
+                }
+                case "gate_check": {
+                    const result = await sm.checkGate({
+                        stage: parsed.stage,
+                        knowledgeIndex: ctx.knowledgeIndex,
+                        config: ctx.config,
+                    });
+                    return { result: { parsed_command: parsed, execution_result: result, hint } };
+                }
+                case "status": {
+                    const pipeline = await sm.getCurrentPipeline();
+                    return {
+                        result: {
+                            parsed_command: parsed,
+                            execution_result: pipeline
+                                ? {
+                                    pipeline_id: pipeline.pipeline_id,
+                                    system_type: pipeline.system_type,
+                                    current_stage: pipeline.current_stage,
+                                    stages: pipeline.stages.map((s) => ({
+                                        stage: s.stage,
+                                        status: s.status,
+                                    })),
+                                }
+                                : { pipeline_id: null, message: "无活跃管线，请先调用 [sf] 初始化" },
+                            hint,
+                        },
+                    };
+                }
+                // ── 恢复操作（Batch A6） ──
+                case "diagnose": {
+                    const result = await sm.executeStage({
+                        action: "diagnose",
+                        knowledgeIndex: ctx.knowledgeIndex,
+                        config: ctx.config,
+                    });
+                    return { result: { parsed_command: parsed, execution_result: result, hint } };
+                }
+                case "repair": {
+                    const result = await sm.executeStage({
+                        action: "repair",
+                        knowledgeIndex: ctx.knowledgeIndex,
+                        config: ctx.config,
+                    });
+                    return { result: { parsed_command: parsed, execution_result: result, hint } };
+                }
+                case "jump": {
+                    const result = await sm.executeStage({
+                        action: "jump",
+                        target_stage: parsed.target_stage ?? parsed.stage,
+                        confirmation_text: parsed.confirmation_text,
+                        knowledgeIndex: ctx.knowledgeIndex,
+                        config: ctx.config,
+                    });
+                    return { result: { parsed_command: parsed, execution_result: result, hint } };
+                }
+                case "reset": {
+                    const result = await sm.executeStage({
+                        action: "reset",
+                        confirmation_text: parsed.confirmation_text,
+                        knowledgeIndex: ctx.knowledgeIndex,
+                        config: ctx.config,
+                    });
+                    return { result: { parsed_command: parsed, execution_result: result, hint } };
+                }
+                case "archive": {
+                    const result = await sm.executeStage({
+                        action: "archive",
+                        knowledgeIndex: ctx.knowledgeIndex,
+                        config: ctx.config,
+                    });
+                    return { result: { parsed_command: parsed, execution_result: result, hint } };
+                }
+                case "brainstorm": {
+                    return {
+                        result: {
+                            parsed_command: parsed,
+                            execution_result: {
+                                message: "头脑风暴流程已激活",
+                                topic: parsed.description,
+                                procedure_ref: "templates/procedures/不确定时头脑风暴流程.md",
+                                steps: [
+                                    "1. 明确不确定的核心问题",
+                                    "2. 列出所有可能方案（至少 3 个）",
+                                    "3. 对照第一性原理推理规则（FP-01~04）逐条检查",
+                                    "4. 评估各方案的风险与收益",
+                                    "5. 选择最符合 fundamental_need 的方案",
+                                    "6. 记录决策理由与推理链",
+                                ],
+                                fp_rules_ref: "templates/rules/shared/第一性原理推理规则.md",
+                                note: "确定性门禁检测到风险模式时也会自动触发头脑风暴",
+                            },
+                            hint,
+                        },
+                    };
+                }
+                case "first_principles": {
+                    return {
+                        result: {
+                            parsed_command: parsed,
+                            execution_result: {
+                                message: "第一性原理推理已激活",
+                                topic: parsed.description,
+                                rules_ref: "templates/rules/shared/第一性原理推理规则.md",
+                                checklist: [
+                                    "FP-01 [error]: fundamental_need 是否已声明？用户目标 vs 解决方案",
+                                    "FP-02 [error]: 推理链是否完整？每个前提是否有证据支撑",
+                                    "FP-03 [warning]: 是否为表面修复？根因分析是否到位",
+                                    "FP-04 [warning]: 是否仅关键词替换？实质问题是否解决",
+                                ],
+                                applicable_stages: ["需求分析", "架构设计", "详细设计", "编码与单元测试"],
+                                note: "确定性门禁在 FIRST_PRINCIPLES_STAGES 阶段自动检测 FP 模式",
+                            },
+                            hint,
+                        },
+                    };
+                }
+                case "reasoning_log": {
+                    return {
+                        result: {
+                            parsed_command: parsed,
+                            execution_result: {
+                                message: "推理记录查看",
+                                topic: parsed.description,
+                                note: "推理记录在确定性门禁评估时自动生成，包含 FP 规则命中和风险模式扫描结果",
+                                fp_rules_triggered: "通过 sf_command 检查门禁 查看 level2.fp_rules_triggered",
+                                brainstorm_history: "通过 sf_command 状态 查看管线历史中的头脑风暴记录",
+                                knowledge_assets: [
+                                    "templates/rules/shared/第一性原理推理规则.md",
+                                    "templates/procedures/不确定时头脑风暴流程.md",
+                                ],
+                            },
+                            hint,
+                        },
+                    };
+                }
+                // D13: 快捷路径
+                case "direct_answer": {
+                    return {
+                        result: {
+                            parsed_command: parsed,
+                            execution_result: {
+                                mode: "direct_answer",
+                                message: parsed.description || "直接回答模式",
+                                note: "不经过管线，直接返回结果",
+                            },
+                            hint,
+                        },
+                    };
+                }
+                case "single_artifact": {
+                    return {
+                        result: {
+                            parsed_command: parsed,
+                            execution_result: {
+                                mode: "single_artifact",
+                                message: parsed.description || "单产物快速生成",
+                                note: "单产物快速生成，适用于简单文档/配置文件",
+                            },
+                            hint,
+                        },
+                    };
+                }
+                default: {
+                    return {
+                        result: {
+                            parsed_command: parsed,
+                            execution_result: {
+                                error: `无法识别的命令: "${args.text}"`,
+                                available_verbs: ["开始", "推进", "回退", "检查", "状态", "初始化", "头脑风暴", "第一性原理", "推理记录", "诊断", "修复", "跳转", "重置", "归档"],
+                            },
+                        },
+                    };
+                }
+            }
+        }
+        catch (err) {
+            return { result: { error: String(err.message ?? err) } };
+        }
+    });
+    // ══════════════════════════════════════════════════
+    // sf_next — 下一步导航
+    // ══════════════════════════════════════════════════
+    const NextSchema = {};
+    registerSafeTool(TOOL.sfNext, "查询下一步导航：管线状态、当前阶段、可用动作、阻断项。用户说\"下一步\"\"继续\"时必须调用此工具", NextSchema, async () => {
+        try {
+            const result = await sm.getNext();
+            return { result };
+        }
+        catch (err) {
+            return { result: { error: String(err.message ?? err) } };
+        }
+    });
+    // ══════════════════════════════════════════════════
+    // sf_pipeline_status — 管线全貌
+    // ══════════════════════════════════════════════════
+    const PipelineStatusSchema = {};
+    registerSafeTool(TOOL.pipelineStatus, "查询管线全貌：所有阶段状态、进度百分比、回退历史。无活跃管线时返回错误", PipelineStatusSchema, async () => {
+        try {
+            const result = await sm.getPipelineStatus();
+            // 附加命令使用统计
+            try {
+                const { readRouteUsageStats } = await import("../../../engine/pipeline/state_machine/route_usage_stats.js");
+                const stats = await readRouteUsageStats(taskContext.getStateDir());
+                if (stats)
+                    result.usage_stats = stats;
+            }
+            catch { /* 统计读取失败不影响状态查询 */ }
+            return { result };
+        }
+        catch (err) {
+            return { result: { error: String(err.message ?? err) } };
+        }
+    });
+    // ══════════════════════════════════════════════════
+    // sf_direct_answer — 快捷路径：直接问答
+    // ══════════════════════════════════════════════════
+    const DirectAnswerSchema = {
+        text: z.string().max(5_000).describe("用户提问文本，用于直接回答模式"),
+        context: z.string().max(10_000).optional().describe("附加上下文信息，帮助更准确地回答问题"),
+    };
+    registerSafeTool(TOOL.directAnswer, "快捷路径：纯对话/问答模式。绕过管线状态机，直接返回回答结果。适用于简单提问、概念解释、方案讨论等不需要编码的场景。不触发任何管线阶段推进或门禁检查", DirectAnswerSchema, async (args) => {
+        try {
+            // 快捷路径：不经过管线，直接返回结构化结果
+            // 实际回答由 AI 模型在工具调用后生成，工具本身仅标记模式
+            return {
+                result: {
+                    mode: "direct_answer",
+                    question: args.text,
+                    context: args.context ?? null,
+                    note: "直接回答模式：不经过管线状态机，无门禁检查",
+                    suggestion: "如需执行开发任务，请使用 sf_command 或 sf_stage_execute",
+                },
+            };
+        }
+        catch (err) {
+            return { result: { error: String(err.message ?? err) } };
+        }
+    });
+    // ══════════════════════════════════════════════════
+    // sf_single_artifact — 快捷路径：单产物快速生成
+    // ══════════════════════════════════════════════════
+    const SingleArtifactSchema = {
+        artifact_kind: z.string().max(100).describe("产物类型：如 doc、config、script、test、migration 等"),
+        intent: z.string().max(10_000).describe("产物意图描述：说明要生成什么内容、目标是什么"),
+        scope: z.array(z.string()).max(20).optional().describe("影响范围：涉及的文件或模块路径列表，用于限定产物边界"),
+    };
+    registerSafeTool(TOOL.singleArtifact, "快捷路径：单产物快速生成。适用于简单文档、配置文件、脚本、测试等单一产出场景。跳过完整管线的阶段流转，直接执行并返回产物。生成后建议调用 sf_gate_check 进行质量验证", SingleArtifactSchema, async (args) => {
+        try {
+            // 快捷路径：不经过管线阶段流转，直接标记单产物生成模式
+            // 实际产物由 AI 模型在工具调用后生成，工具本身标记模式和边界
+            return {
+                result: {
+                    mode: "single_artifact",
+                    artifact_kind: args.artifact_kind,
+                    intent: args.intent,
+                    scope: args.scope ?? [],
+                    note: "单产物快速生成模式：跳过管线阶段流转",
+                    suggestion: "生成完成后建议调用 sf_gate_check 进行质量验证",
+                },
+            };
+        }
+        catch (err) {
+            return { result: { error: String(err.message ?? err) } };
+        }
+    });
+    // ══════════════════════════════════════════════════
+    // sf_config_update — 配置更新
+    // ══════════════════════════════════════════════════
+    const ConfigUpdateSchema = {
+        updates: z.record(z.unknown()).describe("要更新的字段键值对。支持 dot-path（如 {\"delivery.auto_push\": true}）"),
+        reason: z.string().max(500).optional().describe("更新原因（审计日志）"),
+    };
+    registerSafeTool(TOOL.configUpdate, "更新 intent.yaml 配置字段。AI 写入项目意图声明的唯一入口。支持 dot-path 设置。自动校验 + 写入后验证配置完整性", ConfigUpdateSchema, async (args) => {
+        try {
+            const { loadIntent, saveIntent } = await import("../../../engine/config/intent.js");
+            const { validateForWrite } = await import("../../../engine/config/intent_schema.js");
+            const { resolveConfig, checkConfigReadiness } = await import("../../../engine/config/resolver.js");
+            const { debug } = await import("../../../engine/core/logger.js");
+            const projectRoot = ctx.projectPath;
+            if (!projectRoot) {
+                return { result: { error: "无法确定项目根目录" } };
+            }
+            debug("配置更新", "sf_config_update 调用", args.updates);
+            // 1. 加载当前 intent
+            const current = await loadIntent(projectRoot);
+            // 2. 安全守卫：禁止写入内部字段（必须在 applyDotPathUpdates 之前检查）
+            for (const key of Object.keys(args.updates)) {
+                if (key.startsWith("_")) {
+                    return { result: { error: `禁止写入内部字段: ${key}` } };
+                }
+            }
+            // 3. 应用 updates（支持 dot-path）
+            const updated = applyDotPathUpdates(current, args.updates);
+            // 4. 补充 product_profile（首次写入可能没有）
+            if (!updated.product_profile) {
+                updated.product_profile = "default";
+            }
+            // 5. 严格校验
+            const validation = validateForWrite(updated);
+            if (!validation.success) {
+                const issues = validation.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+                return { result: { error: `校验失败: ${issues}` } };
+            }
+            // 6. 写入
+            await saveIntent(projectRoot, validation.data);
+            // 7. 重新解析验证配置完整性
+            const newConfig = await resolveConfig(projectRoot);
+            const readiness = checkConfigReadiness(newConfig);
+            return {
+                result: {
+                    status: "ok",
+                    updated_fields: Object.keys(args.updates),
+                    reason: args.reason,
+                    config_readiness: readiness,
+                    hint: readiness.ready
+                        ? "配置完整"
+                        : `配置仍缺少: ${readiness.missing.join(", ")}。请继续通过 sf_config_update 补充。`,
+                },
+            };
+        }
+        catch (err) {
+            return { result: { error: String(err.message ?? err) } };
+        }
+    });
+}
+// ── 辅助函数 ──
+/** 应用 dot-path updates 到对象 */
+function applyDotPathUpdates(target, updates) {
+    const result = { ...target };
+    for (const [key, value] of Object.entries(updates)) {
+        const parts = key.split(".");
+        let obj = result;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const part = parts[i];
+            if (!(part in obj) || typeof obj[part] !== "object" || obj[part] === null) {
+                obj[part] = {};
+            }
+            obj = obj[part];
+        }
+        obj[parts[parts.length - 1]] = value;
+    }
+    return result;
+}
+//# sourceMappingURL=state_machine.js.map