@winspan/claude-forge 3.0.0 → 3.1.0

package/dist/pipeline/phase-manager.js

@@ -1,961 +0,0 @@
-import { PHASE_LABELS, nextPhase } from './types.js';
-import { logger } from '../utils/logger.js';
-import { cacheRegistry } from '../core/cache-registry.js';
-import { CheckpointManager } from './checkpoint.js';
-import { ArtifactEnforcement } from './artifact-enforcement.js';
-import fsPromises from 'fs/promises';
-import path from 'path';
-import { TIME, CACHE, PHASE_DETECTION } from '../constants.js';
-export class PhaseManager {
-    store;
-    checkpointManager;
-    artifactEnforcement;
-    knowledgeContext = cacheRegistry.register('phase:knowledge', { max: CACHE.PHASE_MANAGER_MAX, ttl: TIME.DAY });
-    totalPhaseEventCounts = cacheRegistry.register('phase:eventCounts', { max: CACHE.PHASE_MANAGER_MAX, ttl: TIME.DAY });
-    /** 追踪每个 pipeline:phase 已见过的工具类别（逗号分隔字符串，节省内存） */
-    phaseToolsSeen = cacheRegistry.register('phase:toolsSeen', { max: CACHE.PHASE_MANAGER_MAX, ttl: TIME.DAY });
-    phaseFixAttempts = cacheRegistry.register('phase:fixAttempts', { max: CACHE.PHASE_MANAGER_MAX, ttl: TIME.DAY });
-    /** 追踪每个 pipeline:phase 的 Write/Edit 调用次数 */
-    phaseWriteEditCounts = cacheRegistry.register('phase:writeEditCounts', { max: CACHE.PHASE_MANAGER_MAX, ttl: TIME.DAY });
-    /** 追踪每个 pipeline:phase 最近 5 次工具调用 */
-    recentTools = cacheRegistry.register('phase:recentTools', { max: CACHE.PHASE_MANAGER_MAX, ttl: TIME.DAY });
-    /** 质量门禁去重缓存：已通过的 pipeline:phase 不再重复检查（24h TTL） */
-    gatePassedCache = cacheRegistry.register('phase:gatePassed', { max: CACHE.PHASE_MANAGER_MAX, ttl: TIME.DAY });
-    /** 活动阈值触发标记：标记为 true 的 pipeline:phase 跳过质量门禁直接推进 */
-    activityThresholdTriggered = cacheRegistry.register('phase:thresholdTriggered', { max: CACHE.PHASE_MANAGER_MAX, ttl: TIME.DAY });
-    /** 产物门禁阻断缓存：记录被阻断的 pipeline:phase，用于注入提示 */
-    artifactGateBlocked = cacheRegistry.register('phase:artifactBlocked', { max: CACHE.PHASE_MANAGER_MAX, ttl: TIME.HOUR });
-    static MAX_FIX_ATTEMPTS = 2;
-    static EMPTY_PHASE_ADVANCE_THRESHOLD = 3;
-    constructor(store) {
-        this.store = store;
-        this.checkpointManager = new CheckpointManager();
-        this.artifactEnforcement = new ArtifactEnforcement();
-    }
-    /**
-     * Pipeline 关闭时清理所有相关缓存，防止内存泄漏
-     */
-    cleanup(pipelineId) {
-        const phases = ['analyze', 'design', 'profile', 'code', 'test', 'review'];
-        for (const phase of phases) {
-            const key = `${pipelineId}:${phase}`;
-            this.phaseToolsSeen.delete(key);
-            this.totalPhaseEventCounts.delete(key);
-            this.phaseFixAttempts.delete(key);
-            this.phaseWriteEditCounts.delete(key);
-            this.recentTools.delete(key);
-            this.gatePassedCache.delete(key);
-            this.activityThresholdTriggered.delete(key);
-            this.artifactGateBlocked.delete(key);
-            // 清理阶段 checkpoint
-            this.checkpointManager.cleanup(pipelineId, phase).catch(err => {
-                logger.debug(`[Pipeline] checkpoint 清理失败 ${pipelineId}:${phase}：${err}`);
-            });
-        }
-        this.knowledgeContext.delete(pipelineId);
-        this.artifactEnforcement.cleanup(pipelineId);
-        logger.debug(`[Pipeline] 已清理 PhaseManager 缓存：${pipelineId.slice(0, 8)}`);
-    }
-    /**
-     * 注入知识库内容到特定 Pipeline
-     */
-    setKnowledgeContext(pipelineId, knowledge) {
-        this.knowledgeContext.set(pipelineId, knowledge);
-    }
-    /**
-     * 获取产物门禁提示（供 stage-scheduler 注入到 AI 上下文）
-     */
-    getArtifactGateReminder(pipelineId, phase) {
-        const key = `${pipelineId}:${phase}`;
-        return this.artifactGateBlocked.get(key) || null;
-    }
-    /**
-     * 清除产物门禁提示（AI 看到提示后清除，避免重复注入）
-     */
-    clearArtifactGateReminder(pipelineId, phase) {
-        const key = `${pipelineId}:${phase}`;
-        this.artifactGateBlocked.delete(key);
-    }
-    /**
-     * ESC 恢复：恢复指定 key 的 phaseToolsSeen（由 PipelineEngine 在从 DB 加载时调用）
-     */
-    restoreToolsSeen(key, tools) {
-        this.phaseToolsSeen.set(key, [...tools].join(','));
-    }
-    /**
-     * ESC 恢复：恢复指定 key 的 totalPhaseEventCounts（由 PipelineEngine 在从 DB 加载时调用）
-     */
-    restoreEventCount(key, count) {
-        this.totalPhaseEventCounts.set(key, count);
-    }
-    /**
-     * 恢复指定 key 的阶段推进状态（daemon_state 持久化）
-     */
-    restorePhaseState(key, state) {
-        if (state.toolsSeen && state.toolsSeen.length > 0) {
-            this.phaseToolsSeen.set(key, state.toolsSeen.join(','));
-        }
-        if (typeof state.eventCount === 'number') {
-            this.totalPhaseEventCounts.set(key, state.eventCount);
-        }
-        if (typeof state.fixAttempts === 'number') {
-            this.phaseFixAttempts.set(key, state.fixAttempts);
-        }
-        if (typeof state.writeEditCount === 'number') {
-            this.phaseWriteEditCounts.set(key, state.writeEditCount);
-        }
-        if (state.recentTools && state.recentTools.length > 0) {
-            this.recentTools.set(key, state.recentTools.slice(-5));
-        }
-    }
-    /**
-     * 导出指定 key 的阶段推进状态（用于持久化到 daemon_state）
-     */
-    exportPhaseState(key) {
-        const toolsStr = this.phaseToolsSeen.get(key) ?? '';
-        return {
-            toolsSeen: toolsStr ? toolsStr.split(',') : [],
-            eventCount: this.totalPhaseEventCounts.get(key) ?? 0,
-            fixAttempts: this.phaseFixAttempts.get(key) ?? 0,
-            writeEditCount: this.phaseWriteEditCounts.get(key) ?? 0,
-            recentTools: this.recentTools.get(key) ?? [],
-        };
-    }
-    /**
-     * 重置指定 Pipeline 的质量门禁修复计数（新 Pipeline 启动或用户手动重试时调用）
-     */
-    resetFixAttempts(pipelineId) {
-        for (const key of [...this.phaseFixAttempts.keys()]) {
-            if (key.startsWith(`${pipelineId}:`)) {
-                this.phaseFixAttempts.delete(key);
-            }
-        }
-    }
-    // ── INodeExecutor 接口实现（别名方法） ──────────────────────────────────────
-    /**
-     * 获取当前节点指令（INodeExecutor 接口）
-     */
-    getInstruction(pipeline) {
-        return this.getPhaseInstruction(pipeline);
-    }
-    /**
-     * 恢复节点状态（INodeExecutor 接口）
-     */
-    restoreState(key, state) {
-        this.restorePhaseState(key, state);
-    }
-    /**
-     * 导出节点状态（INodeExecutor 接口）
-     */
-    exportState(key) {
-        return this.exportPhaseState(key);
-    }
-    /**
-     * 生成当前阶段的执行指令（注入 additionalContext）
-     */
-    getPhaseInstruction(pipeline) {
-        const phase = pipeline.phase;
-        if (phase === 'done')
-            return '';
-        const progress = this.store.getPhaseProgress(pipeline.id, phase);
-        // 空阶段（无任务）不注入指令，等待自愈推进跳过
-        if (progress.total === 0) {
-            logger.warn(`[Pipeline] 阶段 ${phase} 无任务，跳过指令注入，等待自愈推进`);
-            return '';
-        }
-        const phaseTasks = pipeline.tasks.filter(t => t.phase === phase);
-        const currentTask = phaseTasks.find(t => t.status === 'pending' || t.status === 'in_progress');
-        // 标记当前任务为进行中
-        if (currentTask && currentTask.status === 'pending') {
-            this.store.updateTaskStatus(currentTask.id, 'in_progress');
-        }
-        const parts = [];
-        // 状态头（单行，精简需求显示）
-        const reqShort = pipeline.requirement.length > 80
-            ? pipeline.requirement.substring(0, 80) + '…'
-            : pipeline.requirement;
-        parts.push(`[Forge] ${PHASE_LABELS[phase]}（${progress.completed}/${progress.total}）| ${reqShort}`);
-        // 当前任务（仅显示标题，不展开详情）
-        if (currentTask) {
-            parts.push(`→ 当前任务：${currentTask.title}`);
-            // 强化任务完成信号注入：必须主动执行，不可跳过
-            parts.push(`⚠️ 任务完成后必须立即执行（不可跳过）：\`echo "FORGE_TASK_DONE: ${currentTask.id}"\`\n   此命令是 Forge 进度追踪的唯一可靠来源，未执行将导致进度卡死。`);
-        }
-        // 阶段指导：注入当前阶段的具体工作指导（让 Claude 知道该做什么）
-        const directive = this.getPhaseDirective(phase, currentTask, pipeline);
-        if (directive) {
-            parts.push(`\n${directive}`);
-        }
-        // 待完成任务（仅显示前 3 个，超过则省略）
-        const pendingTasks = phaseTasks.filter(t => t.status !== 'completed');
-        if (pendingTasks.length > 1) {
-            const toShow = pendingTasks.slice(0, 3);
-            const remaining = pendingTasks.length - toShow.length;
-            parts.push(`待办：${toShow.map(t => t.title).join('、')}${remaining > 0 ? ` 等${remaining}项` : ''}`);
-        }
-        return parts.join(' ');
-    }
-    /**
-     * 根据 PostToolUse 事件判断是否推进阶段（重构版：职责分离 + 信号优先）
-     */
-    async checkAndAdvance(pipeline, event, qualityGate) {
-        const phase = pipeline.phase;
-        // 1. 工具追踪
-        this.trackToolUsage(pipeline, event);
-        // 1.5. 产物追踪（第二层防护）
-        this.artifactEnforcement.trackToolCall(pipeline.id, phase, event.tool_name || '', event.tool_input || {});
-        // 2. 空阶段自愈
-        const emptyPhaseResult = this.handleEmptyPhase(pipeline);
-        if (emptyPhaseResult)
-            return { ...emptyPhaseResult, advanceReason: 'empty_phase' };
-        // 3. 任务完成检测
-        this.detectAndMarkCompletion(pipeline, event);
-        // 4. 活动阈值检测
-        const thresholdResult = this.handleActivityThreshold(pipeline);
-        // 5. 检查阶段是否全部完成
-        const progress = this.store.getPhaseProgress(pipeline.id, phase);
-        if (progress.total === 0 || progress.completed < progress.total) {
-            return { advanced: false };
-        }
-        // 6. 产物门禁检查（第三层防护）
-        const artifactGateResult = this.artifactEnforcement.checkGate(pipeline.id, phase, pipeline.taskType, pipeline.complexity);
-        if (!artifactGateResult.passed) {
-            // 产物不足，阻止推进
-            logger.warn(`[产物门禁] ${phase} 阶段被阻断：${artifactGateResult.reason}`);
-            logger.info(`[产物门禁] 缺失类型：${artifactGateResult.missingTypes.join(', ')}，已有产物：${artifactGateResult.artifactCount} 个`);
-            // 缓存提示，供下次 AI 调用时注入
-            const key = `${pipeline.id}:${phase}`;
-            this.artifactGateBlocked.set(key, artifactGateResult.reminder || '');
-            return {
-                advanced: false,
-                artifactBlocked: true,
-                artifactReminder: artifactGateResult.reminder,
-            };
-        }
-        // 产物门禁通过
-        logger.info(`[产物门禁] ${phase} 阶段通过，产物 ${artifactGateResult.artifactCount} 个`);
-        // 7. 质量门禁（仅首次完成时触发，活动阈值触发时跳过）
-        if (qualityGate) {
-            const gateResult = await this.runQualityGateOnce(pipeline, event, qualityGate);
-            if (gateResult.blocked) {
-                return {
-                    advanced: false,
-                    qualityBlocked: true,
-                    qualityIssues: gateResult.issues,
-                    qualityLevel: gateResult.level,
-                    fixAttempts: gateResult.fixAttempts,
-                    blocking: gateResult.blocking, // ✅ Propagate hard blocking (must rule violation)
-                };
-            }
-        }
-        // 8. 阶段推进
-        const advanceReason = thresholdResult ? 'activity_threshold' : 'task_complete';
-        const advanceResult = await this.advancePhase(pipeline, thresholdResult?.message);
-        // 清理产物追踪状态
-        this.artifactEnforcement.resetPhase(pipeline.id, phase);
-        return {
-            ...advanceResult,
-            advanceReason,
-            // 活动阈值触发时，将 systemMessage 传递给调用方注入给 Claude
-            systemMessage: thresholdResult?.systemMessage,
-        };
-    }
-    /**
-     * 1. 工具追踪：记录工具类别、调用次数、最近工具
-     */
-    trackToolUsage(pipeline, event) {
-        const phase = pipeline.phase;
-        const toolName = event.tool_name || '';
-        const inputStr = event.tool_input ? JSON.stringify(event.tool_input) : '';
-        const key = `${pipeline.id}:${phase}`;
-        // 工具类别追踪
-        const toolsStr = this.phaseToolsSeen.get(key) ?? '';
-        const toolsSeenSet = toolsStr ? new Set(toolsStr.split(',')) : new Set();
-        const toolCategory = this.categorizeToolCall(toolName, inputStr);
-        if (toolCategory)
-            toolsSeenSet.add(toolCategory);
-        this.phaseToolsSeen.set(key, [...toolsSeenSet].join(','));
-        // 调用次数追踪
-        const eventCount = this.totalPhaseEventCounts.get(key) || 0;
-        this.totalPhaseEventCounts.set(key, eventCount + 1);
-        // Write/Edit 次数追踪
-        if (toolName === 'Write' || toolName === 'Edit') {
-            const writeEditCount = this.phaseWriteEditCounts.get(key) || 0;
-            this.phaseWriteEditCounts.set(key, writeEditCount + 1);
-        }
-        // 最近 5 次工具追踪
-        const recent = this.recentTools.get(key) || [];
-        recent.push(toolName);
-        if (recent.length > 5)
-            recent.shift();
-        this.recentTools.set(key, recent);
-    }
-    /**
-     * 2. 空阶段自愈：当前阶段无任务时自动推进
-     */
-    handleEmptyPhase(pipeline) {
-        const phase = pipeline.phase;
-        const progress = this.store.getPhaseProgress(pipeline.id, phase);
-        const key = `${pipeline.id}:${phase}`;
-        const eventCount = this.totalPhaseEventCounts.get(key) || 0;
-        if (progress.total === 0 && eventCount >= PhaseManager.EMPTY_PHASE_ADVANCE_THRESHOLD) {
-            logger.warn(`[Pipeline] 阶段 ${PHASE_LABELS[phase]} 无任务（phase 标签可能无效），自动推进到下一阶段`);
-            const newPh = nextPhase(phase, pipeline.plannedPhases);
-            this.store.updatePhase(pipeline.id, newPh);
-            this.phaseToolsSeen.delete(key);
-            this.gatePassedCache.delete(key);
-            this.activityThresholdTriggered.delete(key);
-            return { advanced: true, newPhase: newPh };
-        }
-        return null;
-    }
-    /**
-     * 3. 任务完成检测：优先显式信号，回退到启发式
-     */
-    detectAndMarkCompletion(pipeline, event) {
-        const phase = pipeline.phase;
-        const toolName = event.tool_name || '';
-        const inputStr = event.tool_input ? JSON.stringify(event.tool_input) : '';
-        const pendingTasks = pipeline.tasks.filter(t => t.phase === phase && (t.status === 'in_progress' || t.status === 'pending'));
-        for (const currentTask of pendingTasks) {
-            const completed = this.detectTaskCompletion(phase, toolName, inputStr, event, currentTask, pipeline.id);
-            if (completed) {
-                const artifact = this.summarizeArtifact(toolName, inputStr, event);
-                this.store.updateTaskStatus(currentTask.id, 'completed', artifact);
-                logger.info(`[Pipeline] 任务已完成：${currentTask.title} | 成果：${artifact}`);
-                break; // 每次事件只完成一个任务
-            }
-        }
-    }
-    /**
-     * 4. 活动阈值检测：达到阈值且检测到停滞后才强制完成剩余任务
-     *
-     * 改进逻辑（v1.2.4）：
-     * - 仅达到阈值不再直接强制完成，需同时满足"停滞"条件
-     * - 停滞定义：最近工具调用全为只读操作，或 Write/Edit 占比极低
-     * - 达到阈值但仍有进展时，注入提醒而非强制完成
-     */
-    handleActivityThreshold(pipeline) {
-        const phase = pipeline.phase;
-        const progress = this.store.getPhaseProgress(pipeline.id, phase);
-        const key = `${pipeline.id}:${phase}`;
-        const eventCount = this.totalPhaseEventCounts.get(key) || 0;
-        const threshold = this.getPhaseActivityThreshold(phase, pipeline.complexity);
-        // 未达到阈值或已全部完成，不处理
-        if (progress.completed >= progress.total || eventCount < threshold) {
-            return null;
-        }
-        // 达到阈值但仍有实质性进展 → 仅注入提醒，不强制完成
-        if (!this.isStagnant(pipeline)) {
-            // 仅在首次达到阈值时提醒一次（避免每次事件都重复注入）
-            const nudgeKey = `${key}:nudged`;
-            if (!this.activityThresholdTriggered.get(nudgeKey)) {
-                this.activityThresholdTriggered.set(nudgeKey, true);
-                logger.info(`[Pipeline] 活动阈值已达到（${eventCount}/${threshold}），但检测到持续进展，注入完成提醒`);
-            }
-            return null;
-        }
-        // 达到阈值 + 停滞 → 强制完成
-        logger.warn(`[Pipeline] ⚠️ 活动阈值（${threshold}）已达到且检测到停滞，强制完成 ${PHASE_LABELS[phase]} 阶段剩余任务`);
-        const remaining = pipeline.tasks.filter(t => t.phase === phase && t.status !== 'completed');
-        for (const t of remaining) {
-            this.store.updateTaskStatus(t.id, 'completed', `活动阈值+停滞检测触发（${eventCount}次工具调用，无实质性进展）`);
-        }
-        // 标记活动阈值触发，跳过质量门禁
-        this.activityThresholdTriggered.set(key, true);
-        const remainingTitles = remaining.map(t => `- ${t.title}`).join('\n');
-        const message = `[Forge 自动推进] ℹ️ ${PHASE_LABELS[phase]}阶段活动充分且检测到停滞（${eventCount} 次工具调用，近期无写入操作），自动完成剩余任务：
-
-${remainingTitles}
-
-继续下一阶段工作。`;
-        const systemMessage = `[Forge 活动阈值触发] ⚠️ ${PHASE_LABELS[phase]}阶段已达到活动阈值（${eventCount}/${threshold} 次工具调用）且检测到工作停滞（近期无 Write/Edit 操作），系统已自动完成剩余 ${remaining.length} 个任务并推进到下一阶段。
-
-已完成任务：
-${remainingTitles}
-
-请继续下一阶段的工作。如果上述任务尚未真正完成，请在新阶段中补充。`;
-        return { message, systemMessage };
-    }
-    /**
-     * 判断当前阶段是否处于停滞状态（无实质性进展）
-     *
-     * 按阶段差异化策略：
-     * - analyze/design：以阅读/思考为主，只有「超过阈值 1.5 倍且仍无任何文档写入」才算停滞
-     * - profile：以命令执行和报告产出为主，只有「超过阈值后最近连续 5 次都无 Bash/Write/Edit」才算停滞
-     * - code/test/review：以写入产出为主，只有「超过阈值后最近连续 5 次只读」或「超过阈值 1.5 倍且写入占比极低」才算停滞
-     *
-     * 通用兜底：事件数超过阈值 2 倍时无条件视为停滞（防止无限循环）
-     */
-    isStagnant(pipeline) {
-        const phase = pipeline.phase;
-        const key = `${pipeline.id}:${phase}`;
-        const recent = this.recentTools.get(key) || [];
-        const writeEditCount = this.phaseWriteEditCounts.get(key) || 0;
-        const eventCount = this.totalPhaseEventCounts.get(key) || 0;
-        const threshold = this.getPhaseActivityThreshold(phase, pipeline.complexity);
-        // 通用兜底：超过阈值 1.5 倍无条件停滞（防止无限循环）
-        if (eventCount >= threshold * 1.5) {
-            logger.info(`[Pipeline] 事件数已超过阈值 1.5 倍（${eventCount}/${threshold * 1.5}），判定为停滞`);
-            return true;
-        }
-        if (phase === 'analyze' || phase === 'design') {
-            return this.isStagnantForThinkingPhase(recent, writeEditCount, eventCount, threshold);
-        }
-        if (phase === 'profile') {
-            return this.isStagnantForProfilePhase(recent, eventCount, threshold);
-        }
-        return this.isStagnantForWritingPhase(recent, writeEditCount, eventCount, threshold);
-    }
-    /**
-     * analyze/design：允许长时间阅读和思考。
-     * 只有在完全没有任何写入产出且明显超时后，才视为停滞。
-     *
-     * 修复：如果写入量很大（超过阈值 1.5 倍），也应视为可能完成，触发推进检查
-     */
-    isStagnantForThinkingPhase(recent, writeEditCount, eventCount, threshold) {
-        // 如果有大量写入（超过阈值 1.5 倍），可能已完成但未显式确认
-        if (writeEditCount > 0 && eventCount >= Math.floor(threshold * 1.5)) {
-            logger.info(`[Pipeline] 思考阶段有大量写入（${writeEditCount} 次）且事件数超过阈值 1.5 倍，判定为可能完成`);
-            return true;
-        }
-        if (writeEditCount > 0) {
-            return false;
-        }
-        if (eventCount >= Math.floor(threshold * 1.5)) {
-            return true;
-        }
-        if (eventCount >= threshold && recent.length >= 5) {
-            const readOnlyTools = new Set(['Read', 'Grep', 'Glob']);
-            if (recent.slice(-5).every(t => readOnlyTools.has(t))) {
-                return true;
-            }
-        }
-        return false;
-    }
-    /**
-     * profile：允许 Bash 执行、报告写入混合工作流。
-     */
-    isStagnantForProfilePhase(recent, eventCount, threshold) {
-        if (eventCount < threshold || recent.length < 5) {
-            return false;
-        }
-        const productiveTools = new Set(['Bash', 'Write', 'Edit']);
-        return recent.slice(-5).every(t => !productiveTools.has(t));
-    }
-    /**
-     * code/test/review：应有持续写入产出。
-     */
-    isStagnantForWritingPhase(recent, writeEditCount, eventCount, threshold) {
-        if (eventCount >= threshold && recent.length >= 5) {
-            const readOnlyTools = new Set(['Read', 'Grep', 'Glob']);
-            if (recent.slice(-5).every(t => readOnlyTools.has(t))) {
-                return true;
-            }
-        }
-        if (eventCount >= Math.floor(threshold * 1.5) && eventCount > 0) {
-            if (writeEditCount / eventCount < PHASE_DETECTION.WRITE_EDIT_RATIO_MIN) {
-                return true;
-            }
-        }
-        return false;
-    }
-    /**
-     * 5. 质量门禁（去重版）：已通过的阶段不再重复检查，活动阈值触发时跳过
-     */
-    async runQualityGateOnce(pipeline, event, qualityGate) {
-        const phase = pipeline.phase;
-        const cacheKey = `${pipeline.id}:${phase}`;
-        // 活动阈值触发时跳过质量门禁
-        if (this.activityThresholdTriggered.get(cacheKey)) {
-            logger.info(`[Pipeline] 活动阈值触发，跳过质量门禁，直接推进`);
-            return { blocked: false, level: 'pass' };
-        }
-        // 已通过，跳过
-        if (this.gatePassedCache.has(cacheKey)) {
-            return { blocked: false, level: 'pass' };
-        }
-        // 首次检查
-        const fixKey = `${pipeline.id}:${phase}`;
-        const fixAttempts = this.phaseFixAttempts.get(fixKey) || 0;
-        const phaseTasks = pipeline.tasks.filter(t => t.phase === phase);
-        const taskContext = phaseTasks
-            .map(t => `- ${t.title}: ${t.output || '(进行中)'}`)
-            .join('\n');
-        const recentFiles = await this.getRecentlyModifiedFiles(pipeline.projectPath, 30);
-        const recentFilesNote = recentFiles.length > 0
-            ? `\n\n## 最近修改的文件（30分钟内）\n${recentFiles.map(f => `- ${f}`).join('\n')}`
-            : '';
-        const phaseContext = taskContext + recentFilesNote;
-        let gateResult = (phase === 'analyze' || phase === 'design')
-            ? await qualityGate.reviewPhaseCompletion(phase, pipeline.requirement, phaseContext)
-            : await qualityGate.reviewForPhase(event, phase);
-        if (gateResult === null && phase !== 'analyze' && phase !== 'design') {
-            gateResult = await qualityGate.reviewPhaseCompletion(phase, pipeline.requirement, phaseContext);
-        }
-        if (gateResult && gateResult.level === 'fail') {
-            const newAttempts = fixAttempts + 1;
-            this.phaseFixAttempts.set(fixKey, newAttempts);
-            const failIssues = gateResult.checks
-                .filter(c => c.level === 'fail')
-                .map(c => `[${c.category}] ${c.message}${c.suggestion ? `\n  修复建议：${c.suggestion}` : ''}`);
-            if (newAttempts >= PhaseManager.MAX_FIX_ATTEMPTS) {
-                // must 规范违反：即使达到最大修复次数，仍必须硬阻断，不得强制放行
-                if (gateResult.blocking) {
-                    logger.error(`[Pipeline] 质量门禁阶段 ${PHASE_LABELS[phase]} 达到最大修复次数，但存在 must 规范违反，继续硬阻断`);
-                    // 触发 checkpoint 回滚（best-effort，失败不影响阻断）
-                    this.checkpointManager.rollback(pipeline.id, phase, pipeline.projectPath).then(() => {
-                        logger.info(`[Pipeline] 已回滚到阶段 ${PHASE_LABELS[phase]} 起点`);
-                    }).catch(err => {
-                        logger.warn(`[Pipeline] checkpoint 回滚失败（非致命）：${err}`);
-                    });
-                    return {
-                        blocked: true,
-                        issues: failIssues,
-                        level: 'fail',
-                        fixAttempts: newAttempts,
-                        blocking: true,
-                    };
-                }
-                // should/may 规范：达到最大修复次数后强制放行
-                logger.warn(`[Pipeline] 质量门禁阶段 ${PHASE_LABELS[phase]} 已达最大修复次数（${PhaseManager.MAX_FIX_ATTEMPTS}），强制放行`);
-                this.phaseFixAttempts.delete(fixKey);
-                this.gatePassedCache.set(cacheKey, true);
-                return { blocked: false, level: 'warn' };
-            }
-            return {
-                blocked: true,
-                issues: failIssues,
-                level: 'fail',
-                fixAttempts: newAttempts,
-                blocking: gateResult.blocking, // ✅ Propagate hard blocking flag
-            };
-        }
-        // 通过或警告，标记缓存
-        if (gateResult) {
-            this.gatePassedCache.set(cacheKey, true);
-            this.phaseFixAttempts.delete(fixKey);
-        }
-        return { blocked: false, level: gateResult?.level || 'pass' };
-    }
-    /**
-     * 6. 阶段推进
-     */
-    async advancePhase(pipeline, forcedMessage) {
-        const phase = pipeline.phase;
-        const newPh = nextPhase(phase, pipeline.plannedPhases);
-        // 跨阶段补充检测
-        let gapMessage;
-        const nextProgress = this.store.getPhaseProgress(pipeline.id, newPh);
-        if (nextProgress.total === 0 && newPh !== 'done') {
-            gapMessage = `[Forge 阶段间隙] ⚠️ ${PHASE_LABELS[newPh]}阶段暂无任务，可能需要手动创建任务或等待自动推进。`;
-            logger.warn(`[Pipeline] 阶段间隙：${PHASE_LABELS[newPh]} 无任务`);
-        }
-        this.store.updatePhase(pipeline.id, newPh);
-        const oldKey = `${pipeline.id}:${phase}`;
-        this.phaseToolsSeen.delete(oldKey);
-        this.gatePassedCache.delete(oldKey);
-        this.activityThresholdTriggered.delete(oldKey);
-        // 清理旧阶段 checkpoint（阶段成功完成）
-        this.checkpointManager.cleanup(pipeline.id, phase).catch(err => {
-            logger.debug(`[Pipeline] 旧阶段 checkpoint 清理失败 ${pipeline.id}:${phase}：${err}`);
-        });
-        // 为新阶段创建 checkpoint（非阻塞，失败不影响推进）
-        if (newPh !== 'done') {
-            const newKey = `${pipeline.id}:${newPh}`;
-            this.checkpointManager.create(pipeline.id, newPh, pipeline.projectPath).then(() => {
-                logger.debug(`[Pipeline] 新阶段 checkpoint 已创建：${newKey}`);
-            }).catch(err => {
-                logger.debug(`[Pipeline] 新阶段 checkpoint 创建失败（非致命）：${err}`);
-            });
-        }
-        const phaseTasks = pipeline.tasks.filter(t => t.phase === phase);
-        const artifacts = phaseTasks
-            .map(t => `  - ${t.title}: ${t.output || '(无记录)'}`)
-            .join('\n');
-        logger.info(`[Pipeline] 阶段推进：${PHASE_LABELS[phase]} → ${PHASE_LABELS[newPh]}\n` +
-            `  完成 ${phaseTasks.length} 个任务，成果汇总：\n${artifacts}`);
-        return { advanced: true, newPhase: newPh, gapMessage: gapMessage ?? forcedMessage };
-    }
-    /**
-     * 获取项目目录中最近 N 分钟内修改的文件列表（相对路径）
-     * 用于增强质量门禁的 phaseContext，让 AI 有实际依据
-     */
-    async getRecentlyModifiedFiles(projectPath, minutes) {
-        const cutoff = Date.now() - minutes * TIME.MINUTE;
-        const result = [];
-        const ignoreDirs = new Set(['.git', 'node_modules', 'dist', '.claude-forge', '.claude']);
-        const walk = async (dir, depth) => {
-            if (depth > 4)
-                return;
-            try {
-                const entries = await fsPromises.readdir(dir, { withFileTypes: true });
-                for (const entry of entries) {
-                    if (ignoreDirs.has(entry.name))
-                        continue;
-                    const fullPath = path.join(dir, entry.name);
-                    if (entry.isDirectory()) {
-                        await walk(fullPath, depth + 1);
-                    }
-                    else if (entry.isFile()) {
-                        try {
-                            const stat = await fsPromises.stat(fullPath);
-                            if (stat.mtimeMs >= cutoff) {
-                                result.push(path.relative(projectPath, fullPath));
-                            }
-                        }
-                        catch (err) {
-                            logger.debug(`[PhaseManager] 文件状态检查失败 ${fullPath}：${err}`);
-                        }
-                    }
-                }
-            }
-            catch (err) {
-                logger.debug(`[PhaseManager] 目录读取失败 ${dir}：${err}`);
-            }
-        };
-        try {
-            await walk(projectPath, 0);
-        }
-        catch (err) {
-            logger.debug(`[PhaseManager] 文件扫描整体失败：${err}`);
-        }
-        return result.slice(0, 20); // 最多返回 20 个文件，避免 prompt 过长
-    }
-    /** 每个阶段兜底推进所需的最少工具调用次数（按复杂度动态调整） */
-    getPhaseActivityThreshold(phase, complexity) {
-        // 复杂度系数：simple 更快推进，complex 需要更多工作量
-        const multiplier = complexity === 'simple' ? 0.7 : complexity === 'complex' ? 1.8 : 1.0;
-        const base = {
-            analyze: 25, // 分析阶段以阅读为主，给予充足空间
-            design: 30, // 设计阶段需要深度思考
-            profile: 20, // 性能分析相对快速
-            code: 50, // 编码阶段工作量最大
-            test: 25, // 测试阶段需要写+执行
-            review: 25, // 审查阶段需要阅读+修改
-            done: 0,
-        };
-        return Math.round((base[phase] ?? 30) * multiplier);
-    }
-    getPhaseDirective(phase, currentTask, pipeline) {
-        const taskDesc = currentTask?.description || '';
-        const taskTitle = currentTask?.title || '';
-        switch (phase) {
-            case 'analyze':
-                return `📋 **需求分析阶段**
-
-${taskTitle ? `当前任务：${taskTitle}` : ''}
-${taskDesc}
-
-⚠️ **必须产出以下产物**：
-1. 需求分析文档（Markdown 格式）
-   - 建议路径：docs/需求分析.md 或 docs/ANALYSIS.md
-   - 必须包含：需求背景、功能点列表、技术约束、验收标准
-
-✅ **完成标准**：
-- 使用 Write 工具创建需求分析文档
-- 文档内容完整（至少包含需求背景和功能点）
-- 明确列出技术方案
-
-💡 **建议流程**：
-1. 先阅读相关代码和文档理解需求
-2. 整理需求要点和技术约束
-3. 使用 Write 工具创建文档
-4. 在文档中详细描述需求和方案`;
-            case 'design':
-                return `🏗️ **架构设计阶段**
-
-${taskTitle ? `当前任务：${taskTitle}` : ''}
-${taskDesc}
-
-⚠️ **必须产出以下产物**：
-1. 设计文档（Markdown 格式）
-   - 建议路径：docs/设计文档.md 或 docs/DESIGN.md
-   - 必须包含：系统架构、模块划分、接口设计、数据流
-
-2. 架构图（推荐）
-   - 使用 Mermaid 语法或 ASCII 图
-   - 清晰展示模块关系和数据流
-
-✅ **完成标准**：
-- 使用 Write 工具创建设计文档
-- 文档包含架构设计和接口定义
-- 设计方案清晰可落地
-
-💡 **建议流程**：
-1. 分析需求文档确定设计目标
-2. 设计系统架构和模块划分
-3. 使用 Write 工具创建设计文档
-4. 在文档中绘制架构图（Mermaid 或 ASCII）`;
-            case 'profile':
-                return `⚡ **性能分析阶段**
-
-${taskTitle ? `当前任务：${taskTitle}` : ''}
-${taskDesc}
-
-⚠️ **必须产出以下产物**：
-1. 性能分析报告（Markdown 格式）
-   - 建议路径：docs/性能分析.md 或 docs/PROFILE.md
-   - 必须包含：性能基线、瓶颈分析、优化方案
-
-✅ **完成标准**：
-- 使用 Write 工具创建性能分析报告
-- 包含具体的性能数据和分析
-- 给出明确的优化建议
-
-💡 **建议流程**：
-1. 建立性能基线（执行 profiling）
-2. 定位性能瓶颈
-3. 使用 Write 工具创建分析报告
-4. 在报告中记录数据和优化方案`;
-            case 'code':
-                return `💻 **编码实现阶段**
-
-${taskTitle ? `当前任务：${taskTitle}` : ''}
-${taskDesc}
-
-⚠️ **必须产出以下产物**：
-1. 源代码文件（.ts/.py/.go 等）
-   - 实现设计文档中的功能
-   - 代码规范、注释清晰
-
-✅ **完成标准**：
-- 使用 Write/Edit 工具创建或修改源代码
-- 代码可编译/运行
-- 实现了设计的功能
-
-💡 **建议流程**：
-1. 阅读设计文档理解实现目标
-2. 创建必要的文件和目录结构
-3. 使用 Write/Edit 工具编写代码
-4. 确保代码符合规范和最佳实践`;
-            case 'test':
-                return `🧪 **测试验证阶段**
-
-${taskTitle ? `当前任务：${taskTitle}` : ''}
-${taskDesc}
-
-⚠️ **必须产出以下产物**：
-1. 测试文件（.test.ts/.spec.py 等）
-   - 覆盖核心功能和边界情况
-   - 包含正常和异常场景
-
-2. 测试执行结果
-   - 使用 Bash 工具运行测试命令
-   - 确保所有测试通过
-
-✅ **完成标准**：
-- 使用 Write 工具创建测试文件
-- 使用 Bash 执行测试（${pipeline.techStack?.includes('Vitest') ? 'npm test 或 vitest' : pipeline.techStack?.includes('Jest') ? 'npm test 或 jest' : 'npm test'}）
-- 所有测试通过
-
-💡 **建议流程**：
-1. 分析需要测试的代码和功能
-2. 使用 Write 工具创建测试文件
-3. 编写测试用例（正常+异常场景）
-4. 使用 Bash 运行测试并确认通过`;
-            case 'review':
-                return `🔍 **代码审查阶段**
-
-${taskTitle ? `当前任务：${taskTitle}` : ''}
-${taskDesc}
-
-⚠️ **必须产出以下产物**：
-1. 审查报告（Markdown 格式）
-   - 建议路径：docs/审查报告.md 或 docs/REVIEW.md
-   - 必须包含：代码质量评估、安全检查、改进建议
-
-✅ **完成标准**：
-- 使用 Write 工具创建审查报告
-- 报告包含具体的问题和建议
-- 给出了改进方案和优先级
-
-💡 **建议流程**：
-1. 阅读所有修改的代码
-2. 检查安全性、规范性、性能
-3. 使用 Write 工具创建审查报告
-4. 在报告中列出问题、建议和改进方案
-
-📋 **审查清单**：
-- 安全性：注入、XSS、敏感信息泄露
-- 代码规范：命名、格式、注释
-- 性能：算法复杂度、资源使用`;
-            default:
-                return '';
-        }
-    }
-    /**
-     * 检测任务是否完成（重构版：信号优先 + 启发式回退）
-     */
-    detectTaskCompletion(phase, toolName, inputStr, event, currentTask, pipelineId) {
-        // 优先检测显式完成信号（FORGE_TASK_DONE），100% 准确，无需模式匹配
-        // 信号格式：echo "FORGE_TASK_DONE: <task_id>" 或文件注释 // FORGE: task_done <task_id>
-        if (toolName === 'Bash' && inputStr.includes('FORGE_TASK_DONE:')) {
-            const match = inputStr.match(/FORGE_TASK_DONE:\s*(\S+)/);
-            if (match && match[1] === currentTask.id) {
-                logger.info(`[Pipeline] 检测到显式完成信号：${currentTask.id}`);
-                return true;
-            }
-        }
-        if ((toolName === 'Write' || toolName === 'Edit') && inputStr.includes('FORGE: task_done')) {
-            const match = inputStr.match(/FORGE:\s*task_done\s+(\S+)/);
-            if (match && match[1] === currentTask.id) {
-                logger.info(`[Pipeline] 检测到显式完成信号：${currentTask.id}`);
-                return true;
-            }
-        }
-        // 回退到启发式检测（保留向后兼容）
-        switch (phase) {
-            case 'analyze':
-                // 分析阶段：有输出类工具（Write/Edit）即可，或明确的确认信号
-                if (inputStr.includes('分析完成') || inputStr.includes('需求明确') ||
-                    inputStr.includes('已分析') || inputStr.includes('analysis complete')) {
-                    return true;
-                }
-                return toolName === 'Write' || toolName === 'Edit';
-            case 'design':
-                // 设计阶段：Write/Edit 任何文件都算（放宽关键词限制）
-                // 原来要求必须包含 design/architecture 等关键词，导致实际完成了架构改动但文件名不匹配时卡死
-                if (toolName !== 'Write' && toolName !== 'Edit')
-                    return false;
-                // 宽松匹配：任何文档/配置/代码文件的写入都视为设计产出
-                const designKeywords = [
-                    'design', 'architecture', 'DECISIONS', 'README',
-                    '设计', '架构', '方案', '接口', '系统',
-                    '.md', '.yaml', '.yml', '.json', 'CLAUDE',
-                    'config', 'schema', 'plan', 'spec', 'docs/',
-                    'optimization', '优化', '计划', '文档',
-                ];
-                return designKeywords.some(kw => inputStr.includes(kw));
-            case 'profile':
-                // 性能分析阶段：执行 profiling/benchmark 或写入性能报告
-                return (toolName === 'Bash' && (inputStr.includes('profile') || inputStr.includes('benchmark') || inputStr.includes('perf'))) || (toolName === 'Write' && (inputStr.includes('profiling') || inputStr.includes('benchmark') || inputStr.includes('performance')));
-            case 'code': {
-                // 编码阶段：创建或修改了源代码文件（Write 或 Edit 均算）
-                if (toolName !== 'Write' && toolName !== 'Edit')
-                    return false;
-                const codeFilePath = event.tool_input.file_path || '';
-                // 排除测试文件、文档、构建产物
-                if (codeFilePath.includes('.test.') || codeFilePath.includes('.spec.') ||
-                    codeFilePath.includes('/node_modules/') || codeFilePath.includes('/dist/') ||
-                    codeFilePath.endsWith('.md') || codeFilePath.endsWith('.lock') ||
-                    codeFilePath.endsWith('.log')) {
-                    return false;
-                }
-                // 源代码文件（扩展后的列表，覆盖前端/后端/脚本/样式）
-                const codeExts = [
-                    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
-                    '.py', '.go', '.java', '.rs', '.rb', '.php',
-                    '.vue', '.svelte', '.astro',
-                    '.css', '.scss', '.sass', '.less',
-                    '.html', '.htm',
-                    '.sh', '.bash', '.zsh',
-                    '.c', '.cpp', '.h', '.hpp',
-                    '.cs', '.swift', '.kt',
-                    '.sql', '.graphql', '.proto',
-                ];
-                return codeExts.some(ext => codeFilePath.endsWith(ext));
-            }
-            case 'test': {
-                // 测试阶段：必须同时有测试文件写入 AND 测试执行（非 watch 模式）
-                const key = `${pipelineId}:${phase}`;
-                const toolsStr = this.phaseToolsSeen.get(key) ?? '';
-                const toolsSeenSet = toolsStr ? new Set(toolsStr.split(',')) : new Set();
-                const hasTestFile = (toolName === 'Write' || toolName === 'Edit') &&
-                    (inputStr.includes('test') || inputStr.includes('spec'));
-                const hasTestRun = toolName === 'Bash' &&
-                    (inputStr.includes('test') || inputStr.includes('vitest') || inputStr.includes('jest')) &&
-                    !inputStr.includes('--watch');
-                // 持久化标记（trackToolUsage 已更新 phaseToolsSeen）
-                if (hasTestFile)
-                    toolsSeenSet.add('test:file');
-                if (hasTestRun)
-                    toolsSeenSet.add('test:run');
-                this.phaseToolsSeen.set(key, [...toolsSeenSet].join(','));
-                return toolsSeenSet.has('test:file') && toolsSeenSet.has('test:run');
-            }
-            case 'review':
-                // 审查阶段：有代码修改（Edit）即可（质量门禁已在 checkAndAdvance 中把关）
-                return toolName === 'Edit';
-            default:
-                return false;
-        }
-    }
-    /**
-     * 将工具调用归类为粗粒度的工具类别（用于多样性判定）
-     */
-    categorizeToolCall(toolName, _inputStr) {
-        switch (toolName) {
-            case 'Read':
-            case 'Glob':
-            case 'Grep':
-                return 'explore';
-            case 'Write':
-            case 'Edit':
-                return 'write';
-            case 'Bash':
-                return 'bash';
-            case 'Agent':
-                return 'agent';
-            default:
-                return null;
-        }
-    }
-    /**
-     * 从工具调用中提取成果摘要（文件路径、命令、操作类型）
-     */
-    summarizeArtifact(toolName, inputStr, event) {
-        const input = event.tool_input;
-        switch (toolName) {
-            case 'Write':
-            case 'Read':
-            case 'Edit': {
-                const filePath = input?.file_path;
-                if (filePath) {
-                    const shortPath = filePath.split('/').slice(-3).join('/');
-                    return `${toolName} ${shortPath}`;
-                }
-                return toolName;
-            }
-            case 'Bash': {
-                const cmd = (input?.command || '').substring(0, 80);
-                return `执行命令: ${cmd}`;
-            }
-            case 'Glob':
-            case 'Grep': {
-                const pattern = input?.pattern || '';
-                return `${toolName} "${pattern.substring(0, 50)}"`;
-            }
-            case 'Agent': {
-                const desc = input?.description || input?.prompt || '';
-                return `Agent: ${desc.substring(0, 60)}`;
-            }
-            default:
-                return `${toolName}: ${inputStr.substring(0, 80)}`;
-        }
-    }
-    /**
-     * 获取 Pipeline 的阶段快照（用于复盘分析）
-     */
-    getSessionSnapshot(pipelineId) {
-        const snapshots = [];
-        const phases = ['analyze', 'design', 'profile', 'code', 'test', 'review'];
-        for (const phase of phases) {
-            const key = `${pipelineId}:${phase}`;
-            const toolCallCount = this.totalPhaseEventCounts.get(key) || 0;
-            const fixAttemptCount = this.phaseFixAttempts.get(key) || 0;
-            const writeEditCount = this.phaseWriteEditCounts.get(key) || 0;
-            // 只记录有活动的阶段
-            if (toolCallCount > 0 || fixAttemptCount > 0) {
-                snapshots.push({
-                    phase,
-                    tool_call_count: toolCallCount,
-                    write_edit_count: writeEditCount,
-                    fix_attempt_count: fixAttemptCount,
-                });
-            }
-        }
-        return snapshots;
-    }
-}
-//# sourceMappingURL=phase-manager.js.map