minimal-agent 0.8.2 → 0.10.0

package/plugins/ralph-wiggum/plugin.js

@@ -1,280 +0,0 @@
-/**
- * ============================================================
- *  plugins/ralph-wiggum/plugin.ts —— ralph-wiggum 真·插件入口
- * ------------------------------------------------------------
- *  把原 src/plugins/pluginRunner.ts 的 do-while 循环驱动整段搬来。
- *  对外通过 PluginApi.runCommand 暴露 /ralph-loop。
- *
- *  循环契约：
- *    - 每轮把 history 重置成进入循环前的快照（fresh context）
- *    - 用 GoalState.composeContext() 拼 PLAN/BUILD/VERIFY/HEAL 阶段信息
- *    - 跑 runQuery
- *    - 检测 <promise>DONE</promise> → runVerification → 通过则退出
- *    - 检测 <PROMISE>NEED_REPLAN</PROMISE> → forceSetPhase(PLAN)
- *    - executeStopHook 是咨询式：block 才把 reason 注入下一轮，pass 不退出
- *
- *  终止（独占）：sentinel + verify 通过 / 达 max-iterations / abort / 安全天花板
- *
- *  Windows 上 hooks/stop-hook.sh 不可用，但循环不依赖 hook，功能完整，
- *  只是 hook 的咨询通道失效。
- * ============================================================
- */
-import { fileURLToPath } from 'node:url';
-import { dirname } from 'node:path';
-import { runQuery, getWorkingDir, } from '../../src/plugin-sdk.js';
-import { parseVerifyArgs, runVerification } from '../../src/infra/verification.js';
-import { GoalState, Phase } from './src/goalState.js';
-import { makeCompletionMatcher, hasNeedReplanSentinel, hasNeedGoalRevisionSentinel, extractLearnings, } from './src/sentinels.js';
-import { executeStopHook } from './src/stopHookRunner.js';
-const PLUGIN_NAME = 'ralph-wiggum';
-const DEFAULT_MAX_ITERATIONS = 50;
-const SAFETY_CEILING = 200;
-const PLUGIN_ROOT = dirname(fileURLToPath(import.meta.url));
-function extractMaxIterations(args) {
-    const match = args.match(/--max-iterations\s+(\d+)/i);
-    return match ? parseInt(match[1], 10) : undefined;
-}
-/** 解析 --completion-promise "TEXT"（带引号优先）或 --completion-promise TOKEN。 */
-function extractCompletionPromise(args) {
-    const quoted = args.match(/--completion-promise\s+"([^"]*)"/i);
-    if (quoted)
-        return quoted[1].trim() || undefined;
-    const token = args.match(/--completion-promise\s+(\S+)/i);
-    return token ? token[1].trim() || undefined : undefined;
-}
-/** 从 args 里剥掉控制 flag，得到喂给 LLM 的"干净目标文本"（避免 --verify 等泄漏进 prompt）。 */
-function stripControlFlags(args) {
-    return args
-        .replace(/--max-iterations\s+\d+/gi, '')
-        .replace(/--completion-promise\s+"[^"]*"/gi, '')
-        .replace(/--completion-promise\s+\S+/gi, '')
-        .replace(/--verify\s+"[^"]*"/gi, '')
-        .replace(/--verify\s+\S+/gi, '')
-        .replace(/\s{2,}/g, ' ')
-        .trim();
-}
-async function* runRalphLoop(args, ctx) {
-    const { provider, history, signal } = ctx;
-    const maxIter = Math.min(extractMaxIterations(args) ?? DEFAULT_MAX_ITERATIONS, SAFETY_CEILING);
-    // 没有 args（用户只敲 /ralph-loop）→ 留个最小 goal placeholder，避免 GoalState.init 拒空串
-    // 控制 flag（--max-iterations / --verify / --completion-promise）都从原始 args 解析，
-    // userGoal 才用剥过的干净文本，避免 flag 泄漏进喂给 LLM 的 prompt
-    const userGoal = stripControlFlags(args) || '(未提供目标)';
-    yield {
-        type: 'plugin_progress',
-        pluginId: PLUGIN_NAME,
-        current: 0,
-        max: maxIter,
-        message: 'Ralph Wiggum copy-task loop 启动',
-    };
-    const checks = parseVerifyArgs(args);
-    // 完成哨兵判定器：不传 --completion-promise 只认写死集合 DONE|COMPLETE|GOAL_COMPLETE，
-    // 传了则在写死集合基础上叠加自定义短语（超集，向后兼容）
-    const completePhrase = extractCompletionPromise(args);
-    const isComplete = makeCompletionMatcher(completePhrase);
-    // sessionTag = 插件名 → 多插件可并发不打架，/new 也能扫到清掉
-    const goalState = new GoalState(getWorkingDir(), PLUGIN_NAME);
-    await goalState.reset();
-    await goalState.init(userGoal, checks);
-    await goalState.appendProgress(`=== Loop 启动 === 目标: ${userGoal.slice(0, 120)}...`);
-    // 进循环前快照 history —— 每轮 runQuery 前用它重置，保证 fresh context
-    const baseHistory = history.slice();
-    let iterationCount = 0;
-    let consecutiveFailures = 0;
-    let currentInput = userGoal;
-    let finalAssistantMsg = null;
-    try {
-        do {
-            iterationCount++;
-            if (iterationCount > maxIter) {
-                await goalState.forceSetPhase(Phase.DONE, `达到迭代上限 ${maxIter}`);
-                await goalState.appendLearning(`[迭代上限] 循环在 ${iterationCount - 1} 轮后强制终止，可能目标过大或陷入死循环`);
-                yield {
-                    type: 'error',
-                    error: `Loop 已达迭代上限 ${maxIter}，自动停止`,
-                    code: 'max_turns',
-                };
-                return;
-            }
-            if (signal?.aborted) {
-                yield { type: 'interrupted' };
-                return;
-            }
-            yield {
-                type: 'plugin_progress',
-                pluginId: PLUGIN_NAME,
-                current: iterationCount,
-                max: maxIter,
-            };
-            // fresh context：清空 history，重置为入循环前的快照
-            history.length = 0;
-            history.push(...baseHistory);
-            const freshContext = goalState.composeContext(iterationCount);
-            const enhancedInput = `${freshContext}\n\n${currentInput}`;
-            yield* runQuery(enhancedInput, {
-                provider,
-                history,
-                signal,
-                maxTurns: ctx.maxTurns,
-                sessionState: ctx.sessionState,
-            });
-            if (signal?.aborted) {
-                yield { type: 'interrupted' };
-                return;
-            }
-            // 从本轮 history 抓最后一个 assistant 消息（runQuery 已 push 进去）
-            const lastAssistantIdx = (() => {
-                for (let i = history.length - 1; i >= 0; i--) {
-                    if (history[i].role === 'assistant')
-                        return i;
-                }
-                return -1;
-            })();
-            finalAssistantMsg =
-                lastAssistantIdx >= 0 ? history[lastAssistantIdx] : null;
-            const lastAssistantText = finalAssistantMsg
-                ? typeof finalAssistantMsg.content === 'string'
-                    ? finalAssistantMsg.content
-                    : JSON.stringify(finalAssistantMsg.content)
-                : '';
-            // 每轮提取 <learning> 并落盘，让经验跨 fresh-context 迭代存活
-            for (const lesson of extractLearnings(lastAssistantText)) {
-                await goalState.appendLearning(`[迭代 ${iterationCount}] ${lesson}`);
-            }
-            if (isComplete(lastAssistantText)) {
-                // 哨兵：可能来自任意阶段（包括 iter 1 的 PLAN），用 force 跳到 VERIFY
-                await goalState.forceSetPhase(Phase.VERIFY, '检测到完成哨兵，进入验证');
-                await goalState.appendProgress(`迭代 ${iterationCount}: 检测到完成哨兵，运行验证门...`);
-                if (checks.length > 0) {
-                    const vResult = await runVerification(checks);
-                    if (!vResult.passed) {
-                        consecutiveFailures++;
-                        await goalState.appendLearning(`[迭代 ${iterationCount}] 声称完成但验证未通过: ${vResult.summary}`);
-                        // 验证未通过不是致命错误：降级为 warning（不映射 stop_reason），
-                        // 再补一条进度保活进度条，避免 UI 误以为循环停了
-                        yield {
-                            type: 'warning',
-                            message: `⚠️ 验证未通过: ${vResult.summary}。继续尝试...`,
-                        };
-                        yield {
-                            type: 'plugin_progress',
-                            pluginId: PLUGIN_NAME,
-                            current: iterationCount,
-                            max: maxIter,
-                            message: '验证未通过，回到构建修复',
-                        };
-                        // 跨平台决策记录（不再只靠 POSIX stop-hook）
-                        await goalState.recordDecision({
-                            iteration: iterationCount,
-                            phase: Phase.VERIFY,
-                            summary: '验证门',
-                        }, ['判定完成', '回退继续'], '回退继续', vResult.summary.slice(0, 200));
-                        if (consecutiveFailures >= 3) {
-                            await goalState.forceSetPhase(Phase.HEAL, `连续 ${consecutiveFailures} 次验证失败`);
-                        }
-                        else {
-                            // 语义诚实：VERIFY→BUILD 不是合法边，用 force 而非借合法边
-                            await goalState.forceSetPhase(Phase.BUILD, '验证未通过，回到构建修复');
-                        }
-                        continue;
-                    }
-                    await goalState.appendProgress(`✅ 验证通过: ${vResult.summary}`);
-                }
-                await goalState.setPhase(Phase.DONE, 'goal complete & verified');
-                // 成功路径决策记录（vResult 定义在 checks.length>0 块内、此处作用域不可见，
-                // 故 reasoning 统一写 '目标完成'，不引用 vResult）
-                await goalState.recordDecision({
-                    iteration: iterationCount,
-                    phase: Phase.VERIFY,
-                    summary: '验证门',
-                }, ['判定完成', '回退继续'], '判定完成', '目标完成');
-                yield {
-                    type: 'plugin_progress',
-                    pluginId: PLUGIN_NAME,
-                    current: iterationCount,
-                    max: maxIter,
-                    message: '✅ 完成并通过验证',
-                };
-                return;
-            }
-            // NEED_GOAL_REVISION 逃生门：目标本身不可达，干净终止请人工修订
-            // （区别于 NEED_REPLAN —— 那是换方案，这是换目标）
-            if (hasNeedGoalRevisionSentinel(lastAssistantText)) {
-                await goalState.forceSetPhase(Phase.DONE, 'agent 报告目标本身需修订');
-                await goalState.appendLearning('[NEED_GOAL_REVISION] Agent 认为目标本身有问题，需人工修订');
-                await goalState.recordDecision({
-                    iteration: iterationCount,
-                    phase: goalState.currentPhase,
-                    summary: 'NEED_GOAL_REVISION',
-                }, ['继续硬上', '停止请人工改目标'], '停止请人工改目标', '目标本身不可达');
-                yield {
-                    type: 'warning',
-                    message: '🛑 Agent 判断目标本身需要人工修订，循环已停止。请检查并调整目标后重试。',
-                };
-                return;
-            }
-            if (hasNeedReplanSentinel(lastAssistantText)) {
-                await goalState.forceSetPhase(Phase.PLAN, 'agent 请求重新规划');
-                await goalState.appendLearning('[NEED_REPLAN] Agent 认为当前方案不可行，需要重新规划');
-                await goalState.appendProgress('Agent 请求 NEED_REPLAN，回 PLAN 阶段');
-                await goalState.recordDecision({
-                    iteration: iterationCount,
-                    phase: goalState.currentPhase,
-                    summary: 'NEED_REPLAN',
-                }, ['继续当前方案', '回 PLAN 重规划'], '回 PLAN 重规划', 'agent 认为方案不可行');
-                consecutiveFailures = 0;
-                continue;
-            }
-            // PLAN 阶段跑过一轮还没哨兵，认为规划已完成，自动推进 BUILD
-            if (goalState.currentPhase === Phase.PLAN && iterationCount >= 2) {
-                await goalState.setPhase(Phase.BUILD, '规划阶段已完成，进入构建');
-            }
-            // Stop-hook 咨询式调用：block 才把 reason 注入下一轮 prompt
-            // pass / 报错都不再终止循环；终止由 sentinel/maxIter/abort/NEED_REPLAN 独占
-            const hookResult = await executeStopHook(PLUGIN_ROOT, lastAssistantText);
-            if (hookResult.decision === 'block' && hookResult.reason) {
-                currentInput = hookResult.reason;
-                consecutiveFailures = 0;
-                await goalState.recordDecision({
-                    iteration: iterationCount,
-                    phase: goalState.currentPhase,
-                    summary: 'stop-hook 反馈',
-                }, ['继续循环', '终止'], '继续循环', hookResult.reason.slice(0, 200));
-                if (hookResult.systemMessage) {
-                    baseHistory.push({
-                        role: 'user',
-                        content: `[Plugin Stop Hook] ${hookResult.systemMessage}`,
-                    });
-                }
-                await goalState.appendProgress(`迭代 ${iterationCount}: Stop hook block，注入反馈继续`);
-            }
-            else {
-                await goalState.appendProgress(`迭代 ${iterationCount}: 无哨兵 / hook pass，继续下一轮`);
-            }
-        } while (true);
-    }
-    finally {
-        // 收尾：把循环里临时累积的 history 还原成 baseHistory + 最后一轮 assistant
-        // 这样 TUI 上看到的就是"一次问答"，而不是 N 轮重复
-        history.length = 0;
-        history.push(...baseHistory);
-        if (finalAssistantMsg) {
-            history.push(finalAssistantMsg);
-        }
-        await goalState.cleanup();
-    }
-}
-const api = {
-    async *runCommand(commandName, args, ctx) {
-        if (commandName === 'ralph-loop') {
-            yield* runRalphLoop(args, ctx);
-            return;
-        }
-        // 其它命令（help / cancel-ralph）→ 不接管，让框架走声明式 fallback
-        yield {
-            type: 'error',
-            error: `ralph-wiggum: 命令 /${commandName} 未由 plugin.ts 接管`,
-        };
-    },
-};
-export default api;

package/plugins/ralph-wiggum/src/goalState.js

@@ -1,258 +0,0 @@
-import { mkdir, appendFile, writeFile, unlink, rmdir } from 'node:fs/promises';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-export var Phase;
-(function (Phase) {
-    Phase["PLAN"] = "plan";
-    Phase["BUILD"] = "build";
-    Phase["VERIFY"] = "verify";
-    Phase["HEAL"] = "heal";
-    Phase["DONE"] = "done";
-})(Phase || (Phase = {}));
-const VALID_PHASES = new Set(Object.values(Phase));
-/**
- * 阶段转移表使用说明（诚实注释）：
- *
- * 这张表里的 event 名（plan_complete / tests_failing / all_pass 等）是**描述性的**，
- * 阶段实际由驱动（plugin.ts）用启发式推进或 `forceSetPhase` 直接设置——
- * **不是 LLM 驱动的事件状态机**。
- *
- * `setPhase` 只用这张表做「目标阶段是否可达」的合法性校验：
- * 只要 PHASE_TRANSITIONS[from] 的 values 里包含 to，就视为合法，跟传入的 `reason` 字符串无关。
- * `reason` 仅是给人看的日志文本，不参与任何匹配或校验。
- *
- * 想跳过校验强制切阶段，用 `forceSetPhase`。
- */
-const PHASE_TRANSITIONS = {
-    [Phase.PLAN]: {
-        plan_complete: Phase.BUILD,
-        stuck: Phase.PLAN,
-    },
-    [Phase.BUILD]: {
-        task_complete: Phase.VERIFY,
-        need_replan: Phase.PLAN,
-        tests_failing: Phase.HEAL,
-    },
-    [Phase.VERIFY]: {
-        all_pass: Phase.BUILD,
-        failures: Phase.HEAL,
-        goal_complete: Phase.DONE,
-    },
-    [Phase.HEAL]: {
-        fixed: Phase.VERIFY,
-        cannot_fix_locally: Phase.PLAN,
-    },
-    [Phase.DONE]: {},
-};
-function isLegalTransition(from, to) {
-    if (from === to)
-        return true;
-    const allowed = PHASE_TRANSITIONS[from];
-    if (!allowed)
-        return false;
-    return Object.values(allowed).includes(to);
-}
-const LEARNINGS_TAIL_LINES = 20;
-/** 每个阶段给 LLM 的一行行动指令（fresh-context 下 LLM 看不到 SKILL.md，靠这个 steer 行为）。 */
-const PHASE_DIRECTIVES = {
-    [Phase.PLAN]: '分析任务、拆解步骤、识别风险与未知项；先想清楚再动手。',
-    [Phase.BUILD]: '按计划实现，一次只聚焦一个子任务，落到具体文件改动。',
-    [Phase.VERIFY]: '运行测试 / 检查输出 / 核对验收标准，用证据确认，别凭感觉。',
-    [Phase.HEAL]: '已多次验证失败：停止猜测，定位根因（读报错、加日志、做最小复现）再修，避免回归。',
-    [Phase.DONE]: '目标已达成。',
-};
-export class GoalState {
-    dir;
-    constructor(workspaceDir, sessionTag) {
-        const suffix = sessionTag ? `-${sessionTag}` : '';
-        this.dir = join(workspaceDir, `.minimal-agent${suffix}`);
-    }
-    async reset() {
-        const files = ['goal.md', 'completion.md', 'phase.md', 'progress.md', 'learnings.md', 'decisions.md'];
-        for (const f of files) {
-            try {
-                await unlink(join(this.dir, f));
-            }
-            catch {
-            }
-        }
-    }
-    async init(goal, criteria) {
-        await mkdir(this.dir, { recursive: true });
-        const files = {
-            goal: `# 不可变目标 (IMMUTABLE GOAL)\n\n${goal}\n`,
-            completion: JSON.stringify(criteria, null, 2),
-            phase: Phase.PLAN,
-            progress: '',
-            learnings: '',
-            decisions: '',
-        };
-        for (const [name, content] of Object.entries(files)) {
-            const path = join(this.dir, `${name}.md`);
-            if (!existsSync(path)) {
-                await writeFile(path, content);
-            }
-        }
-    }
-    get goal() {
-        try {
-            return readFileSync(join(this.dir, 'goal.md'), 'utf8').trim();
-        }
-        catch {
-            return '';
-        }
-    }
-    get completionCriteria() {
-        try {
-            const raw = readFileSync(join(this.dir, 'completion.md'), 'utf8').trim();
-            return JSON.parse(raw);
-        }
-        catch {
-            return [];
-        }
-    }
-    get currentPhase() {
-        try {
-            const raw = readFileSync(join(this.dir, 'phase.md'), 'utf8').trim();
-            if (VALID_PHASES.has(raw)) {
-                return raw;
-            }
-        }
-        catch {
-        }
-        return Phase.PLAN;
-    }
-    /**
-     * 切换阶段。`reason` 是给人看的日志文本，不参与校验。
-     * 校验只看 from→to 是否在 PHASE_TRANSITIONS 表里有路径（任意 event 通向 to 即合法）。
-     * 想绕开 FSM 用 forceSetPhase。
-     */
-    async setPhase(phase, reason) {
-        if (!VALID_PHASES.has(phase)) {
-            throw new Error(`Invalid phase: ${phase}`);
-        }
-        const current = this.currentPhase;
-        if (!isLegalTransition(current, phase)) {
-            throw new Error(`非法阶段切换: ${current} → ${phase}。该目标阶段不在 PHASE_TRANSITIONS[${current}] 的可达集合内，需要走 forceSetPhase。`);
-        }
-        await writeFile(join(this.dir, 'phase.md'), phase);
-        await this.appendProgress(`PHASE → ${phase}: ${reason}`);
-    }
-    async forceSetPhase(phase, reason) {
-        if (!VALID_PHASES.has(phase)) {
-            throw new Error(`Invalid phase: ${phase}`);
-        }
-        await writeFile(join(this.dir, 'phase.md'), phase);
-        await this.appendProgress(`PHASE → ${phase}: ${reason}`);
-    }
-    async appendProgress(line) {
-        const timestamp = new Date().toLocaleTimeString('en-US', { hour12: false });
-        await appendFile(join(this.dir, 'progress.md'), `[${timestamp}] ${line}\n`);
-    }
-    tailProgress(n) {
-        try {
-            const content = readFileSync(join(this.dir, 'progress.md'), 'utf8');
-            const lines = content.trim().split('\n').filter(Boolean);
-            return lines.slice(-n).join('\n');
-        }
-        catch {
-            return '';
-        }
-    }
-    async appendLearning(lesson) {
-        await appendFile(join(this.dir, 'learnings.md'), `- ${lesson}\n`);
-    }
-    get learnings() {
-        try {
-            const raw = readFileSync(join(this.dir, 'learnings.md'), 'utf8').trim();
-            if (!raw)
-                return '';
-            const lines = raw.split('\n').filter(Boolean);
-            return lines.slice(-LEARNINGS_TAIL_LINES).join('\n');
-        }
-        catch {
-            return '';
-        }
-    }
-    async recordDecision(ctx, options, chosen, reasoning) {
-        const entry = {
-            iteration: ctx.iteration,
-            phase: ctx.phase,
-            contextSummary: ctx.summary,
-            options,
-            chosen,
-            reasoning,
-        };
-        const line = JSON.stringify(entry);
-        await appendFile(join(this.dir, 'decisions.md'), `${line}\n`);
-    }
-    summarizeDecisions(maxEntries = 5) {
-        try {
-            const content = readFileSync(join(this.dir, 'decisions.md'), 'utf8');
-            const lines = content.trim().split('\n').filter(Boolean);
-            const entries = [];
-            for (const line of lines.slice(-maxEntries * 2)) {
-                try {
-                    entries.push(JSON.parse(line));
-                }
-                catch {
-                }
-            }
-            const sliced = entries.slice(-maxEntries);
-            // 无有效条目（文件存在但为空）时也统一返回占位文本
-            if (sliced.length === 0)
-                return '(无决策记录)';
-            return sliced
-                .map((e) => `迭代 ${e.iteration}（${e.phase}）: 在 [${e.options.join(', ')}] 中选择了 **${e.chosen}**，原因：${e.reasoning.slice(0, 80)}`)
-                .join('\n');
-        }
-        catch {
-            return '(无决策记录)';
-        }
-    }
-    composeContext(iteration) {
-        const sections = [];
-        // 不可变目标段：去掉 NEED_GOAL_REVISION 提示（已移到通信协议段统一说明）
-        sections.push(`# 不可变目标 (IMMUTABLE GOAL)\n${this.goal}\n⚠️ 你不能修改或扩大上述目标。`);
-        // 当前阶段 + 对应的一行行动指令
-        sections.push(`# 当前阶段: ${this.currentPhase.toUpperCase()}\n${PHASE_DIRECTIVES[this.currentPhase]}`);
-        // 与循环驱动的通信协议：哨兵约定 + learning 标记
-        sections.push([
-            '# 与循环驱动的通信协议（务必遵守）',
-            '- 任务**真正完成**时输出 `<promise>DONE</promise>`，驱动会运行验证门确认。',
-            '- 当前方案走不通、要换打法（目标不变）时输出 `<PROMISE>NEED_REPLAN</PROMISE>`。',
-            '- **目标本身**有问题、不改目标就无法完成时输出 `<PROMISE>NEED_GOAL_REVISION</PROMISE>`，驱动会停止并请人工修订。',
-            '- 踩到的坑 / 教训用 `<learning>一句话</learning>` 标记，驱动会自动存档供后续迭代参考。',
-            '⚠️ 切勿为逃出循环而谎报完成——只有陈述完全为真时才输出完成哨兵。',
-        ].join('\n'));
-        const lrn = this.learnings;
-        if (lrn) {
-            sections.push(`# 关键教训（必须遵守，避免重复踩坑）\n${lrn}`);
-        }
-        const decisions = this.summarizeDecisions(3);
-        if (decisions !== '(无决策记录)') {
-            sections.push(`# 历史关键决策（请参考，避免重复试错）\n${decisions}`);
-        }
-        const recentProgress = this.tailProgress(10);
-        if (recentProgress) {
-            sections.push(`# 最近进度\n${recentProgress}`);
-        }
-        sections.push(`---\n\n# 本轮任务 (迭代 ${iteration})`);
-        return sections.join('\n\n---\n\n');
-    }
-    async cleanup() {
-        const files = ['goal.md', 'completion.md', 'phase.md', 'progress.md', 'learnings.md', 'decisions.md'];
-        for (const f of files) {
-            try {
-                await unlink(join(this.dir, f));
-            }
-            catch {
-            }
-        }
-        try {
-            await rmdir(this.dir);
-        }
-        catch {
-        }
-    }
-}

package/plugins/ralph-wiggum/src/sentinels.js

@@ -1,76 +0,0 @@
-/**
- * ============================================================
- *  plugins/ralph-wiggum/src/sentinels.ts —— LLM 输出哨兵协议
- * ------------------------------------------------------------
- *  Ralph 通过"在回答里输出特定标签"与循环驱动（plugin.ts）通信：
- *
- *    <promise>DONE</promise> / <promise>COMPLETE</promise> / <promise>GOAL_COMPLETE</promise>
- *    （或用户经 `--completion-promise "<短语>"` 指定的自定义短语）
- *      → 当前轮 LLM 认为目标完成；驱动进入验证门（--verify）确认后才真正退出。
- *
- *    <PROMISE>NEED_REPLAN</PROMISE>
- *      → 当前方案走不通、需要换打法（**目标不变**）；驱动强转回 PLAN 阶段。
- *
- *    <PROMISE>NEED_GOAL_REVISION</PROMISE>
- *      → **目标本身**有问题，无法在不改目标的前提下完成；驱动**干净终止**，请人工修订目标
- *        （区别于 NEED_REPLAN：那是换方案，这是换目标）。
- *
- *    <learning>一句话</learning>（可多次）
- *      → LLM 主动记录的踩坑 / 教训；驱动**每轮**提取并追加到 learnings.md，
- *        让经验跨 fresh-context 迭代存活——这是 Ralph 能收敛的关键。
- *
- *  哨兵集中在这里方便审计与扩展；匹配全部 case-insensitive。
- *  ⚠️ rich 插件路径下 commands/ralph-loop.md 的 prompt body **不会**喂给 LLM
- *     （pluginRunner 命中 runCommand 即接管），故以上协议由 GoalState.composeContext
- *     注入 prompt，本文件只负责"解析 LLM 回吐的标签"。
- * ============================================================
- */
-/** 写死的完成短语集合（不带 --completion-promise 时只认这三个，逐字节兼容旧行为）。 */
-const BUILTIN_COMPLETE_RE = /<promise>(?:COMPLETE|DONE|GOAL_COMPLETE)<\/promise>/i;
-const NEED_REPLAN_RE = /<PROMISE>NEED_REPLAN<\/PROMISE>/i;
-const NEED_GOAL_REVISION_RE = /<PROMISE>NEED_GOAL_REVISION<\/PROMISE>/i;
-const LEARNING_RE = /<learning>([\s\S]*?)<\/learning>/gi;
-/** 转义正则元字符，让用户自定义的 promise 短语按字面量匹配（含空格 / 标点也安全）。 */
-function escapeRegExp(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-/**
- * 构造完成哨兵判定器。
- * - 不传 / 空白 customPhrase → 只认写死集合（与旧行为逐字节一致）。
- * - 传 customPhrase → 写死集合 ∪ `<promise><customPhrase></promise>`（**超集**，向后兼容）。
- *   customPhrase 内外空白裁剪；正则元字符转义；标签内允许首尾空白；大小写不敏感。
- *
- * 设计：始终接受写死集合，所以即便用户设了自定义短语，LLM 输出 `<promise>DONE</promise>`
- *      仍然有效——composeContext 因此可以无脑教 LLM 用 DONE，不必知道自定义短语是什么。
- */
-export function makeCompletionMatcher(customPhrase) {
-    const phrase = customPhrase?.trim();
-    if (!phrase) {
-        return (text) => BUILTIN_COMPLETE_RE.test(text);
-    }
-    const customRe = new RegExp(`<promise>\\s*${escapeRegExp(phrase)}\\s*<\\/promise>`, 'i');
-    return (text) => BUILTIN_COMPLETE_RE.test(text) || customRe.test(text);
-}
-/** 旧调用兼容：等价于 makeCompletionMatcher()(text)，只认写死集合。 */
-export function hasCompleteSentinel(text) {
-    return BUILTIN_COMPLETE_RE.test(text);
-}
-export function hasNeedReplanSentinel(text) {
-    return NEED_REPLAN_RE.test(text);
-}
-export function hasNeedGoalRevisionSentinel(text) {
-    return NEED_GOAL_REVISION_RE.test(text);
-}
-/**
- * 提取 LLM 本轮输出里所有 `<learning>…</learning>` 文本。
- * 多空白折叠成单空格、去首尾、丢弃空项；无标签返回空数组。
- */
-export function extractLearnings(text) {
-    const out = [];
-    for (const m of text.matchAll(LEARNING_RE)) {
-        const lesson = m[1].replace(/\s+/g, ' ').trim();
-        if (lesson)
-            out.push(lesson);
-    }
-    return out;
-}