@winspan/claude-forge 3.6.27 → 3.6.43

package/dist/pipeline/execution-engine.js

@@ -0,0 +1,227 @@
+/**
+ * Execution Engine - 执行引擎（状态机驱动）
+ *
+ * 核心职责：
+ * 1. 管理节点状态转换（pending → in_progress → retrying → blocked|done）
+ * 2. 集成 Verifier + Diagnosis + Strategy Selector
+ * 3. 下发节点指令包（via PreToolUse）
+ * 4. 校验完成条件并推进（via PostToolUse）
+ */
+import { CompletionVerifier } from './completion-verifier.js';
+import { DiagnosisService } from './diagnosis-service.js';
+import { StrategySelector } from './strategy-selector.js';
+import { logger } from '../utils/logger.js';
+import { randomUUID } from 'crypto';
+// ── Execution Engine 实现 ───────────────────────────────────────────────
+export class ExecutionEngine {
+    storage;
+    aiProvider;
+    verifier = new CompletionVerifier();
+    diagnosisService;
+    strategySelector = new StrategySelector();
+    constructor(storage, aiProvider) {
+        this.storage = storage;
+        this.aiProvider = aiProvider;
+        this.diagnosisService = new DiagnosisService(aiProvider);
+    }
+    /**
+     * 获取当前活跃的执行计划
+     */
+    getActivePlan(projectPath) {
+        return this.storage.repositories.pipelinePlans.getByProjectPath(projectPath);
+    }
+    /**
+     * 获取当前执行中的节点
+     */
+    getCurrentNode(plan) {
+        const nodes = this.storage.repositories.planNodes.getByPlanId(plan.plan_id);
+        return nodes.find(n => n.status === 'in_progress') || null;
+    }
+    /**
+     * 获取下一个待执行的节点
+     */
+    getNextPendingNode(plan) {
+        const nodes = this.storage.repositories.planNodes.getByPlanId(plan.plan_id);
+        for (const node of nodes) {
+            if (node.status !== 'pending')
+                continue;
+            // 检查依赖是否满足
+            const dependenciesMet = (node.dependencies ?? []).every(depId => {
+                const depNode = nodes.find(n => n.node_id === depId);
+                return depNode?.status === 'done';
+            });
+            if (dependenciesMet) {
+                return node;
+            }
+        }
+        return null;
+    }
+    /**
+     * 生成节点指令包（PreToolUse 注入）
+     */
+    generateInstructionPackage(node) {
+        const completionSummary = node.completion_rules
+            .filter(r => r.required)
+            .map(r => `- ${r.description}`)
+            .join('\n');
+        let retryContext;
+        if (node.attempt_count > 0) {
+            retryContext = `这是第 ${node.attempt_count + 1} 次尝试。`;
+        }
+        return {
+            node_id: node.node_id,
+            title: node.title,
+            instruction: node.instruction,
+            completion_summary: completionSummary,
+            retry_context: retryContext,
+        };
+    }
+    /**
+     * 处理 PostToolUse 事件，推进状态机
+     */
+    async handlePostToolUse(plan, node, event) {
+        // 1. 校验完成条件
+        const verifyResult = await this.verifier.verify(node.completion_rules, plan.project_path);
+        logger.debug(`[ExecutionEngine] 节点 ${node.title} 验证结果: ${verifyResult.passed}, ` +
+            `缺失项: ${verifyResult.missing_items.length}`);
+        // 2. 记录本次尝试
+        await this.recordAttempt(node, verifyResult);
+        // 3. 验证通过 → 推进到下一个节点
+        if (verifyResult.passed) {
+            return await this.advanceToNextNode(plan, node);
+        }
+        // 4. 验证失败 → 诊断 + 选策略 + 重试
+        return await this.handleVerificationFailure(plan, node, event, verifyResult);
+    }
+    /**
+     * 记录节点执行尝试
+     */
+    async recordAttempt(node, verifyResult) {
+        const attemptId = randomUUID();
+        const now = new Date().toISOString();
+        this.storage.repositories.nodeAttempts.create({
+            attempt_id: attemptId,
+            node_id: node.node_id,
+            strategy_id: node.current_strategy_id || 'default',
+            attempt_number: node.attempt_count + 1,
+            started_at: now,
+            ended_at: now,
+            status: verifyResult.passed ? 'passed' : 'failed',
+            verification_result: {
+                passed: verifyResult.passed,
+                missing_items: verifyResult.missing_items,
+                diagnostics: verifyResult.diagnostics,
+                next_action: verifyResult.next_action,
+            },
+        });
+    }
+    /**
+     * 推进到下一个节点
+     */
+    async advanceToNextNode(plan, completedNode) {
+        // 更新当前节点状态为 done
+        this.storage.repositories.planNodes.updateStatus(completedNode.node_id, 'done');
+        // 更新策略池统计（成功）
+        if (completedNode.current_strategy_id) {
+            const updatedPool = this.strategySelector.updateStrategyStats(completedNode.strategy_pool, completedNode.current_strategy_id, true);
+            this.storage.repositories.planNodes.updateStrategyPool(completedNode.node_id, updatedPool);
+        }
+        // 查找下一个待执行节点
+        const nextNode = this.getNextPendingNode(plan);
+        if (!nextNode) {
+            // 所有节点完成
+            this.storage.repositories.pipelinePlans.updateStatus(plan.plan_id, 'completed');
+            logger.info(`[ExecutionEngine] Pipeline ${plan.plan_id} 已完成`);
+            return {
+                advanced: true,
+                system_message: `Pipeline 已完成！所有节点执行成功。`,
+            };
+        }
+        // 启动下一个节点
+        this.storage.repositories.planNodes.updateStatus(nextNode.node_id, 'in_progress');
+        logger.info(`[ExecutionEngine] 节点推进: ${completedNode.title} → ${nextNode.title}`);
+        return {
+            advanced: true,
+            next_node_id: nextNode.node_id,
+            system_message: `节点「${completedNode.title}」已完成，开始执行「${nextNode.title}」。`,
+        };
+    }
+    /**
+     * 处理验证失败
+     */
+    async handleVerificationFailure(plan, node, event, verifyResult) {
+        // 获取最近的工具调用记录
+        const recentEvents = this.getRecentToolCalls(plan.session_id, 20);
+        // 调用诊断服务
+        const diagnosis = await this.diagnosisService.diagnose({
+            node,
+            verification_result: verifyResult,
+            recent_tool_calls: recentEvents,
+            attempt_count: node.attempt_count,
+        });
+        logger.info(`[ExecutionEngine] 诊断结果: ${diagnosis.failure_category}, ` +
+            `证据: ${diagnosis.evidence.slice(0, 100)}`);
+        // 选择下一个策略
+        const attemptedStrategyIds = new Set(this.storage.repositories.nodeAttempts
+            .getByNodeId(node.node_id)
+            .map(a => a.strategy_id));
+        const nextStrategy = this.strategySelector.select(node.strategy_pool, diagnosis, attemptedStrategyIds);
+        if (!nextStrategy) {
+            // 策略池耗尽 → blocked
+            return await this.blockNode(plan, node, verifyResult, diagnosis);
+        }
+        // 更新节点状态为 retrying
+        this.storage.repositories.planNodes.updateStatus(node.node_id, 'retrying');
+        this.storage.repositories.planNodes.updateAttempt(node.node_id, nextStrategy.strategy_id, node.attempt_count + 1);
+        logger.info(`[ExecutionEngine] 节点「${node.title}」进入重试，策略: ${nextStrategy.name}`);
+        // 生成重试指令
+        const retryMessage = this.buildRetryMessage(node, verifyResult, nextStrategy);
+        return {
+            advanced: false,
+            system_message: retryMessage,
+        };
+    }
+    /**
+     * 阻塞节点
+     */
+    async blockNode(plan, node, verifyResult, diagnosis) {
+        this.storage.repositories.planNodes.updateStatus(node.node_id, 'blocked');
+        this.storage.repositories.pipelinePlans.updateStatus(plan.plan_id, 'failed');
+        logger.error(`[ExecutionEngine] 节点「${node.title}」已阻塞，策略池耗尽`);
+        const blockMessage = `[Pipeline 已阻断] 节点「${node.title}」执行失败，所有策略已尝试。\n\n` +
+            `诊断结果: ${diagnosis.failure_category}\n` +
+            `证据: ${diagnosis.evidence}\n\n` +
+            `缺失项:\n${verifyResult.missing_items.map((item) => `- ${item}`).join('\n')}`;
+        return {
+            advanced: false,
+            blocking: true,
+            system_message: blockMessage,
+        };
+    }
+    /**
+     * 构建重试指令
+     */
+    buildRetryMessage(node, verifyResult, strategy) {
+        let message = `[Forge:重试] 节点「${node.title}」验证未通过，正在使用策略「${strategy.name}」重试。\n\n`;
+        message += `缺失项:\n${verifyResult.missing_items.map((item) => `- ${item}`).join('\n')}\n\n`;
+        if (strategy.method.instruction_suffix) {
+            message += `策略提示:\n${strategy.method.instruction_suffix}\n\n`;
+        }
+        if (strategy.method.provide_template) {
+            message += `参考模板:\n${strategy.method.provide_template}\n\n`;
+        }
+        message += `请根据以上信息修复问题，完成后再次执行完成信号。`;
+        return message;
+    }
+    /**
+     * 获取最近的工具调用记录
+     */
+    getRecentToolCalls(sessionId, limit) {
+        const events = this.storage.queryEvents({
+            session_id: sessionId,
+            limit,
+        });
+        return events.reverse(); // 按时间正序
+    }
+}
+//# sourceMappingURL=execution-engine.js.map

package/dist/pipeline/execution-engine.js.map

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

package/dist/pipeline/index.d.ts

@@ -37,11 +37,18 @@ export declare class PipelineEngine {
     private blockedProjects;
     /**
      * PreToolUse 处理：如果有活跃 Pipeline，注入阶段指令
+     *
+     * @param event - Forge 事件对象，包含项目路径、会话 ID 等上下文
+     * @returns 需要注入的指令文本，无活跃 Pipeline 时返回 null
      */
     handlePreToolUse(event: ForgeEvent): Promise<string | null>;
     private _handlePreToolUse;
     /**
      * PostToolUse 处理：跟踪进度，检查阶段推进
+     *
+     * @param event - Forge 事件对象
+     * @param qualityGate - 可选的质量门禁引擎，用于代码审查
+     * @returns 包含进度消息、质量检查结果、系统消息等的对象
      */
     handlePostToolUse(event: ForgeEvent, qualityGate?: QualityGateEngine): Promise<{
         message: string | null;
@@ -60,6 +67,8 @@ export declare class PipelineEngine {
      * 路由到 DynamicNodeExecutor，处理节点推进和状态更新
      */
     private _handlePostToolUseDynamic;
+    /** 节点推进后的状态更新与消息构建 */
+    private handleDynamicAdvance;
     /**
      * 将当前 Pipeline 状态写入项目根目录 CLAUDE.md（上次工作续接章节）
      * 每次阶段推进时调用，确保跨会话后 Claude 能快速恢复上下文
@@ -67,14 +76,31 @@ export declare class PipelineEngine {
     private persistPipelineStateToClaude;
     /**
      * 启动新 Pipeline
+     *
+     * @param requirement - 用户需求描述
+     * @param projectPath - 项目根目录路径
+     * @param sessionId - 会话 ID
+     * @param analysis - 可选的意图分析结果，未提供时使用默认值
+     * @returns 创建的 Pipeline 对象
      */
     startPipeline(requirement: string, projectPath: string, sessionId: string, analysis?: IntentAnalysis): Promise<Pipeline>;
     /**
      * 生成统一执行计划（动态流水线唯一事实来源）
+     *
+     * @param requirement - 用户需求描述
+     * @param projectPath - 项目根目录路径
+     * @param sessionId - 会话 ID
+     * @param analysis - 意图分析结果
+     * @param template - 可选的流水线模板
+     * @param templateRoute - 可选的模板路由结果
+     * @returns 规范化的执行计划对象
      */
     buildExecutionPlan(requirement: string, projectPath: string, sessionId: string, analysis: IntentAnalysis, template?: PipelineTemplate, templateRoute?: import('./types.js').TemplateRouteResult | null): Promise<CanonicalExecutionPlan>;
     /**
-     * 从统一执行计划启动动态 Pipeline。
+     * 从统一执行计划启动动态 Pipeline
+     *
+     * @param plan - 规范化的执行计划对象
+     * @returns 创建的 Pipeline 对象
      */
     startPipelineFromPlan(plan: CanonicalExecutionPlan): Promise<Pipeline>;
     private materializeDynamicPipeline;

package/dist/pipeline/index.d.ts.map

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

package/dist/pipeline/index.js

@@ -58,6 +58,9 @@ export class PipelineEngine {
     });
     /**
      * PreToolUse 处理：如果有活跃 Pipeline，注入阶段指令
+     *
+     * @param event - Forge 事件对象，包含项目路径、会话 ID 等上下文
+     * @returns 需要注入的指令文本，无活跃 Pipeline 时返回 null
      */
     async handlePreToolUse(event) {
         return this.pipelineLock.runExclusive(event.project_path, () => this._handlePreToolUse(event)) ?? null;
@@ -100,6 +103,10 @@ export class PipelineEngine {
     }
     /**
      * PostToolUse 处理：跟踪进度，检查阶段推进
+     *
+     * @param event - Forge 事件对象
+     * @param qualityGate - 可选的质量门禁引擎，用于代码审查
+     * @returns 包含进度消息、质量检查结果、系统消息等的对象
      */
     async handlePostToolUse(event, qualityGate) {
         const result = await this.pipelineLock.runExclusive(event.project_path, () => this._handlePostToolUse(event, qualityGate));
@@ -164,77 +171,7 @@ export class PipelineEngine {
             return { message: null, systemMessage: result.systemMessage, blocking: true };
         }
         if (result.advanced) {
-            const completedNodeId = currentNodeId;
-            // 更新已完成节点状态（包含产物输出）
-            if (completedNodeId) {
-                await this.storage.repositories.dynamicPipelines.updateNodeStatus(completedNodeId, 'completed', result.nodeOutput // 传入产物输出
-                );
-            }
-            if (result.newPhase) {
-                // 推进到下一节点
-                await this.storage.repositories.dynamicPipelines.updateNodeStatus(result.newPhase, 'in_progress');
-                await this.storage.repositories.dynamicPipelines.updateCurrentNode(pipeline.id, result.newPhase);
-                // 更新 bridge pipeline 的 phase 和 tasks
-                const nextNode = dynPipeline.nodes.find(n => n.id === result.newPhase);
-                if (nextNode) {
-                    pipeline.phase = nextNode.nodeTypeId;
-                }
-                pipeline.tasks = pipeline.tasks.map(t => {
-                    if (t.id === completedNodeId)
-                        return { ...t, status: 'completed' };
-                    if (t.id === result.newPhase)
-                        return { ...t, status: 'in_progress' };
-                    return t;
-                });
-                this.activePipelines.set(event.project_path, pipeline);
-                // 清除指纹缓存，确保新节点指令能正常注入
-                this.lastInstructionKey.delete(event.project_path);
-                this.emptyPhaseNotified.delete(`${event.project_path}:${pipeline.phase}`);
-                // 更新 CLAUDE.md 续接状态
-                this.persistPipelineStateToClaude(pipeline, event.project_path);
-                // 获取下一节点的指令，通过 systemMessage 步进式告知 Claude Code
-                const updatedDynPipeline = await this.storage.repositories.dynamicPipelines.getById(pipeline.id);
-                const nextInstruction = updatedDynPipeline
-                    ? this.dynamicNodeExecutor.getInstruction(updatedDynPipeline)
-                    : null;
-                const completedNodeType = dynPipeline.nodes.find(n => n.id === completedNodeId)?.nodeTypeId ?? completedNodeId;
-                const advanceSystemMessage = nextInstruction
-                    ? `[Forge Pipeline] ✅ 节点「${completedNodeType}」已完成，产物验证通过。\n\n下一步任务：\n${nextInstruction}`
-                    : result.systemMessage;
-                return {
-                    message: `[Forge Pipeline:Dynamic] 🔄 节点推进：${nextNode?.nodeTypeId ?? result.newPhase}`,
-                    gapMessage: result.gapMessage,
-                    qualityLevel: result.qualityLevel,
-                    advanceReason: result.advanceReason,
-                    systemMessage: advanceSystemMessage,
-                };
-            }
-            else {
-                // newPhase 为 undefined 表示所有节点已完成
-                await this.storage.repositories.dynamicPipelines.close(pipeline.id, 'completed');
-                this.activePipelines.delete(event.project_path);
-                this.clearBlocked(event.project_path);
-                this.dynamicNodeExecutor.cleanup(pipeline.id);
-                const totalNodes = dynPipeline.nodes.length;
-                const completedNodes = totalNodes; // 全部完成
-                let reportMessage = `[Forge Pipeline:Dynamic] ✅ 动态流水线已完成所有节点！
-📋 需求：${pipeline.requirement}
-📊 统计：
-  • 总节点数：${totalNodes}
-  • 已完成：${completedNodes}`;
-                if (qualityGate) {
-                    try {
-                        const reportGenerator = new PipelineReportGenerator(qualityGate.getIssueTracker(), this.dynamicNodeExecutor);
-                        const markdown = reportGenerator.generate(pipeline);
-                        reportGenerator.persist(pipeline.projectPath, markdown);
-                        reportMessage = `${reportMessage}\n\n${markdown}`;
-                    }
-                    catch (err) {
-                        logger.warn(`[Pipeline:Dynamic] ⚠️  动态流水线完成报告生成失败：${err}`);
-                    }
-                }
-                return { message: reportMessage };
-            }
+            return this.handleDynamicAdvance(pipeline, dynPipeline, event, qualityGate, result, currentNodeId);
         }
         // 非推进时定期更新 CLAUDE.md
         const eventCount = this.dynamicNodeExecutor.exportState(`${pipeline.id}:${currentNodeId ?? ''}`).eventCount;
@@ -244,6 +181,67 @@ export class PipelineEngine {
         // 透传 systemMessage（产物重试指令等）
         return { message: null, systemMessage: result.systemMessage, qualityLevel: result.qualityLevel };
     }
+    /** 节点推进后的状态更新与消息构建 */
+    async handleDynamicAdvance(pipeline, dynPipeline, event, qualityGate, result, completedNodeId) {
+        if (completedNodeId) {
+            await this.storage.repositories.dynamicPipelines.updateNodeStatus(completedNodeId, 'completed', result.nodeOutput);
+        }
+        if (result.newPhase) {
+            await this.storage.repositories.dynamicPipelines.updateNodeStatus(result.newPhase, 'in_progress');
+            await this.storage.repositories.dynamicPipelines.updateCurrentNode(pipeline.id, result.newPhase);
+            const nextNode = dynPipeline.nodes.find(n => n.id === result.newPhase);
+            if (nextNode) {
+                pipeline.phase = nextNode.nodeTypeId;
+            }
+            pipeline.tasks = pipeline.tasks.map(t => {
+                if (t.id === completedNodeId)
+                    return { ...t, status: 'completed' };
+                if (t.id === result.newPhase)
+                    return { ...t, status: 'in_progress' };
+                return t;
+            });
+            this.activePipelines.set(event.project_path, pipeline);
+            this.lastInstructionKey.delete(event.project_path);
+            this.emptyPhaseNotified.delete(`${event.project_path}:${pipeline.phase}`);
+            this.persistPipelineStateToClaude(pipeline, event.project_path);
+            const updatedDynPipeline = await this.storage.repositories.dynamicPipelines.getById(pipeline.id);
+            const nextInstruction = updatedDynPipeline ? this.dynamicNodeExecutor.getInstruction(updatedDynPipeline) : null;
+            const completedNodeType = dynPipeline.nodes.find(n => n.id === completedNodeId)?.nodeTypeId ?? completedNodeId;
+            const advanceSystemMessage = nextInstruction
+                ? `[Forge Pipeline] ✅ 节点「${completedNodeType}」已完成，产物验证通过。\n\n下一步任务：\n${nextInstruction}`
+                : result.systemMessage;
+            return {
+                message: `[Forge Pipeline:Dynamic] 🔄 节点推进：${nextNode?.nodeTypeId ?? result.newPhase}`,
+                gapMessage: result.gapMessage,
+                qualityLevel: result.qualityLevel,
+                advanceReason: result.advanceReason,
+                systemMessage: advanceSystemMessage,
+            };
+        }
+        // 所有节点已完成
+        await this.storage.repositories.dynamicPipelines.close(pipeline.id, 'completed');
+        this.activePipelines.delete(event.project_path);
+        this.clearBlocked(event.project_path);
+        this.dynamicNodeExecutor.cleanup(pipeline.id);
+        const totalNodes = dynPipeline.nodes.length;
+        let reportMessage = `[Forge Pipeline:Dynamic] ✅ 动态流水线已完成所有节点！
+📋 需求：${pipeline.requirement}
+📊 统计：
+  • 总节点数：${totalNodes}
+  • 已完成：${totalNodes}`;
+        if (qualityGate) {
+            try {
+                const reportGenerator = new PipelineReportGenerator(qualityGate.getIssueTracker(), this.dynamicNodeExecutor);
+                const markdown = reportGenerator.generate(pipeline);
+                reportGenerator.persist(pipeline.projectPath, markdown);
+                reportMessage = `${reportMessage}\n\n${markdown}`;
+            }
+            catch (err) {
+                logger.warn(`[Pipeline:Dynamic] ⚠️  动态流水线完成报告生成失败：${err}`);
+            }
+        }
+        return { message: reportMessage };
+    }
     /**
      * 将当前 Pipeline 状态写入项目根目录 CLAUDE.md（上次工作续接章节）
      * 每次阶段推进时调用，确保跨会话后 Claude 能快速恢复上下文
@@ -299,6 +297,12 @@ ${taskSummary}
     }
     /**
      * 启动新 Pipeline
+     *
+     * @param requirement - 用户需求描述
+     * @param projectPath - 项目根目录路径
+     * @param sessionId - 会话 ID
+     * @param analysis - 可选的意图分析结果，未提供时使用默认值
+     * @returns 创建的 Pipeline 对象
      */
     async startPipeline(requirement, projectPath, sessionId, analysis) {
         logger.info(`[Pipeline] 启动中（模式：dynamic）："${requirement}"`);
@@ -316,6 +320,14 @@ ${taskSummary}
     }
     /**
      * 生成统一执行计划（动态流水线唯一事实来源）
+     *
+     * @param requirement - 用户需求描述
+     * @param projectPath - 项目根目录路径
+     * @param sessionId - 会话 ID
+     * @param analysis - 意图分析结果
+     * @param template - 可选的流水线模板
+     * @param templateRoute - 可选的模板路由结果
+     * @returns 规范化的执行计划对象
      */
     async buildExecutionPlan(requirement, projectPath, sessionId, analysis, template, templateRoute) {
         const goal = {
@@ -331,7 +343,10 @@ ${taskSummary}
         });
     }
     /**
-     * 从统一执行计划启动动态 Pipeline。
+     * 从统一执行计划启动动态 Pipeline
+     *
+     * @param plan - 规范化的执行计划对象
+     * @returns 创建的 Pipeline 对象
      */
     async startPipelineFromPlan(plan) {
         logger.info(`[Pipeline:Dynamic] 🚀 启动动态流水线："${plan.requirement}" | 项目=${plan.projectPath} | source=${plan.source}`);