minimal-agent 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "最小化 Agent 系统 —— 10 工具 + 插件系统 + workflow DSL + 自动压缩 + OpenAI 兼容 + Ink TUI；NodeNext + tsc 原地编译，dev 用 Bun .ts、install 用 Node .js（学习/教学用）",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",

package/plugins/workflow-runner/src/jsonPayload.js

@@ -0,0 +1,89 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/jsonPayload.ts —— 从 LLM 文本里提取纯 JSON 负载
+ * ------------------------------------------------------------
+ *  根因（为什么需要这个文件）：
+ *    "思考型"模型（MiniMax-M2/M3、DeepSeek-R1 系等）即使在 strict json_schema 下，
+ *    仍会把 <think>…</think> 思维链**直接写进 content 字段**（不是 reasoning_content）。
+ *    src/llm/client.ts 故意原样保留这段思维链（主循环下一轮工具调用要靠它接上下文，
+ *    见 client.ts:200-205 注释），所以"剥离思维链"不能放进通用 transport——否则会
+ *    破坏主循环。剥离必须发生在「契约要求纯 JSON」的边界，也就是 workflow 的
+ *    output_schema 解析处。本模块就是那个边界的唯一实现，被两个解析点共享：
+ *      - stepExecutors/llm.ts（llm + output_schema 单轮）
+ *      - miniReAct.ts（agent 节点 / llm+context_files / onError:recover 三处子循环）
+ *    放一处、两边 import，杜绝"只修一个解析点、另一个继续炸"的漂移。
+ *
+ *  处理顺序（保守、纯函数、可单测）：
+ *    1. 去掉所有 <think>…</think> 块（多行、可多个、大小写不敏感）。
+ *       **必须先做**：思维链里常出现 { } [ ]（模型在"想" JSON 长什么样），
+ *       若不先剥，下面"找首个 JSON 起点"会错锚到思维链里的括号。
+ *    2. 兜底：只有起始 <think>、收尾 </think> 被 length 截断 → 砍掉从 <think> 起的全部。
+ *    3. 从剩余文本定位首个 { 或 [，配平括号截取到对应收尾。
+ *       这一步天然容忍 ```json 代码围栏与 JSON 前后的散文（只取配平的那一段），
+ *       所以不需要单独的"去围栏"正则（也就避免了误伤 JSON 字符串里的反引号）。
+ *    4. 找不到任何 JSON 起点 → 原样返回 trim 后文本，交调用方 JSON.parse 报
+ *       "honest error"（保留原文前若干字符便于排查）。
+ * ============================================================
+ */
+/**
+ * 从可能掺杂思维链 / 代码围栏 / 前后散文的文本里提取最可能的 JSON 负载字符串。
+ * 不做 JSON.parse（解析与错误信息留给调用方，便于各自定制报错文案）。
+ */
+export function extractJsonPayload(raw) {
+    // 1. 去成对的思维链块
+    let s = raw.replace(/<think>[\s\S]*?<\/think>/gi, '');
+    // 2. 截断兜底：有起始无收尾（被 max tokens 截断）→ 丢弃从 <think> 起的尾巴
+    if (/<think>/i.test(s) && !/<\/think>/i.test(s)) {
+        s = s.slice(0, s.search(/<think>/i));
+    }
+    s = s.trim();
+    // 3. 定位首个 JSON 起点并配平截取
+    const start = firstJsonStart(s);
+    if (start === -1)
+        return s; // 没有 JSON：原样返回，交调用方报错
+    const end = matchBalanced(s, start);
+    return end === -1 ? s.slice(start) : s.slice(start, end + 1);
+}
+/** 首个 { 或 [ 的下标（取更靠前者）；都没有返回 -1。 */
+function firstJsonStart(s) {
+    const obj = s.indexOf('{');
+    const arr = s.indexOf('[');
+    if (obj === -1)
+        return arr;
+    if (arr === -1)
+        return obj;
+    return Math.min(obj, arr);
+}
+/**
+ * 从 start（{ 或 [）配平到对应的 } 或 ]，返回收尾下标；找不到返回 -1。
+ * 跳过字符串字面量内部的括号与转义，避免被 JSON 值里的 } / ] 误导。
+ */
+function matchBalanced(s, start) {
+    const open = s[start];
+    const close = open === '{' ? '}' : ']';
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (let i = start; i < s.length; i++) {
+        const c = s[i];
+        if (inStr) {
+            if (esc)
+                esc = false;
+            else if (c === '\\')
+                esc = true;
+            else if (c === '"')
+                inStr = false;
+            continue;
+        }
+        if (c === '"')
+            inStr = true;
+        else if (c === open)
+            depth++;
+        else if (c === close) {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}

package/plugins/workflow-runner/src/miniReAct.js

@@ -31,6 +31,7 @@
  * ============================================================
  */
 import { chat, executeTool, } from '../../../src/plugin-sdk.js';
+import { extractJsonPayload } from './jsonPayload.js';
 /**
  * 执行一次 ReAct 子循环。**边跑边 yield UI 事件（stage_change / text / reasoning /
  * tool_start / tool_end），同时 return 最终 StepResult**——让 recover / agent 节点 /
@@ -49,6 +50,18 @@ export async function* runMiniReAct(args) {
     const maxTurns = args.maxTurns ?? 10;
     // 工作消息列表：拷贝一份，避免污染调用方
     const conv = [...messages];
+    // schema 模式：把 schema 写进 system（同 llm.ts）。保证 provider 不支持 response_format
+    // 而被 client.ts 退化掉时，模型仍知道确切字段结构、不至于瞎猜字段名。
+    if (output_schema) {
+        const hint = `\n\n最终只输出匹配以下 JSON Schema 的 JSON 对象本身（不要解释、不要 markdown 代码块）：\n${JSON.stringify(output_schema)}`;
+        const sysIdx = conv.findIndex((m) => m.role === 'system');
+        if (sysIdx >= 0) {
+            conv[sysIdx] = { ...conv[sysIdx], content: `${conv[sysIdx].content ?? ''}${hint}` };
+        }
+        else {
+            conv.unshift({ role: 'system', content: hint.trimStart() });
+        }
+    }
     let finalText = '';
     /** 上一轮是否仍有 tool_calls（用于检测 "用尽轮数还在调工具" 这一退出态） */
     let lastTurnHadToolCalls = false;
@@ -162,9 +175,11 @@ export async function* runMiniReAct(args) {
     }
     // ---- 5. 输出处理 ----
     if (output_schema) {
+        // 同 llm.ts：先剥 <think> 思维链/围栏/前后散文再 parse（见 jsonPayload.ts 头注）。
+        const payload = extractJsonPayload(finalText);
         let parsed;
         try {
-            parsed = JSON.parse(finalText);
+            parsed = JSON.parse(payload);
         }
         catch (e) {
             throw new Error(`miniReAct: output_schema 要求 JSON 但解析失败: ${e.message}\n收到: ${finalText.slice(0, 200)}`);

package/plugins/workflow-runner/src/runner.js

@@ -22,6 +22,7 @@
  * ============================================================
  */
 import { getWorkingDir } from '../../../src/plugin-sdk.js';
+import { dlog } from '../../../src/utils/debugLog.js';
 import { evalExpr, interpolate } from './expressions.js';
 import { runRecovery } from './recovery.js';
 import { execAgentStep } from './stepExecutors/agent.js';
@@ -131,6 +132,7 @@ async function* runSteps(steps, vars, ctx, state) {
             }
         }
         const kind = stepKind(step);
+        dlog('wf', `step ${i + 1}/${steps.length} START ${step.id} (${kind})`);
         yield {
             type: 'workflow_step_start',
             id: step.id,
@@ -509,6 +511,7 @@ export async function* runWorkflow(def, inputs, ctx) {
         max: def.steps.length,
         message: `▶ workflow ${def.name}`,
     };
+    let succeeded = false;
     try {
         const halted = yield* runSteps(def.steps, vars, runCtx, state);
         if (halted)
@@ -523,9 +526,15 @@ export async function* runWorkflow(def, inputs, ctx) {
             message: `✓ workflow ${def.name} 完成`,
         };
         yield { type: 'workflow_done', name: def.name, vars: vars.snapshot() };
+        succeeded = true;
     }
     finally {
-        await state.cleanup();
+        // 只在「干净跑完」时清现场；halt / 中断 / 抛错都**保留** .minimal-agent-workflow/
+        // （current.json / inputs.json / vars.json / progress.md，含失败那步的 ✗ 行）供事后排查
+        // ——这正是这些文件的设计目的（workflowState.ts 头注）；失败时删掉等于自废武功。
+        // 残留不会永久堆积：下次同名 workflow 的 init() 会先 rm，/new 也按 .minimal-agent-* 前缀统一清。
+        if (succeeded)
+            await state.cleanup();
     }
 }
 /**

package/plugins/workflow-runner/src/stepExecutors/llm.js

@@ -22,6 +22,7 @@
  */
 import { ALL_TOOLS, chat, } from '../../../../src/plugin-sdk.js';
 import { interpolate } from '../expressions.js';
+import { extractJsonPayload } from '../jsonPayload.js';
 import { runMiniReAct } from '../miniReAct.js';
 const LLM_STEP_SYSTEM_PLAIN = '你正在被一个 workflow 调用。只输出本步骤要求的内容本身，不要寒暄、不要列要求复述、不要工具调用语法。';
 const LLM_STEP_SYSTEM_SCHEMA = `你正在被一个 workflow 调用。
@@ -68,8 +69,17 @@ export async function* execLlmStep(step, vars, ctx) {
     }
     // ===== END NEW =====
     const useSchema = step.output_schema !== undefined;
+    // schema 模式：把 schema 直接写进 system prompt。这样无论 provider 是否支持
+    // response_format.json_schema（火山 GLM 等不支持、会被 client.ts 退化掉 response_format），
+    // 模型都知道确切字段名与结构 —— 退化路径也能产出正确形状的 JSON，而非瞎猜字段。
+    const schemaHint = useSchema
+        ? `\n\n最终只输出匹配以下 JSON Schema 的 JSON 对象本身（不要解释、不要 markdown 代码块）：\n${JSON.stringify(step.output_schema)}`
+        : '';
     const messages = [
-        { role: 'system', content: useSchema ? LLM_STEP_SYSTEM_SCHEMA : LLM_STEP_SYSTEM_PLAIN },
+        {
+            role: 'system',
+            content: (useSchema ? LLM_STEP_SYSTEM_SCHEMA : LLM_STEP_SYSTEM_PLAIN) + schemaHint,
+        },
         { role: 'user', content: prompt },
     ];
     const responseFormat = useSchema
@@ -103,10 +113,13 @@ export async function* execLlmStep(step, vars, ctx) {
     }
     const trimmed = text.trim();
     if (useSchema) {
-        // strict structured output：解析 JSON 后整个对象作为 raw
+        // strict structured output：解析 JSON 后整个对象作为 raw。
+        // 思考型模型即便在 strict 下仍会把 <think>…</think> 写进 content（见 jsonPayload.ts
+        // 头注与 src/llm/client.ts:200），故先剥思维链/前后散文再 parse；报错仍带原文便于排查。
+        const payload = extractJsonPayload(text);
         let parsed;
         try {
-            parsed = JSON.parse(trimmed);
+            parsed = JSON.parse(payload);
         }
         catch (e) {
             throw new Error(`step ${step.id}: output_schema 要求 JSON 输出但解析失败: ${e.message}\n收到: ${trimmed.slice(0, 200)}`);

package/plugins/workflow-runner/src/stepExecutors/skill.js

@@ -96,6 +96,12 @@ export async function* execSkillStep(step, vars, ctx) {
             throw new Error('用户中断');
         if (ev.type === 'error')
             throw new Error(ev.error);
+        // 子 skill 内部那次 runQuery 的 turn_done 是它自己的终结标记，不是整个 workflow 的终结。
+        // 不外泄——否则把 turn_done 当终结的消费者（-p --output-format json / gateway broker）
+        // 会在 workflow 中途（如 critic 步之后、verify 步之前）误判结束、漏掉后续步骤。
+        // workflow 的对外收口由 index.ts::runWorkflowFromCommand 末尾统一补发。
+        if (ev.type === 'turn_done')
+            continue;
         yield ev;
     }
     const trimmed = text.trim();

package/src/llm/client.js

@@ -16,6 +16,30 @@
  *  本文件不依赖任何 npm 包（fetch 是 Bun/Node 20+ 内置）。
  * ============================================================
  */
+import { dlog } from '../utils/debugLog.js';
+/**
+ * 记住"这个 baseURL::model 不支持 response_format.json_schema"，避免每次都先撞 400。
+ * 单进程内有效；每个 -p 子进程是全新进程 → 首个结构化调用吃一次 400 再退化，可接受。
+ */
+const rfUnsupported = new Set();
+/** 调试日志用的请求自增号（vote 并发多 voter 时靠它在日志里区分是哪一路）。 */
+let reqCounter = 0;
+/**
+ * 判断一个 400 是否在抱怨 response_format（json_schema）不被支持。
+ * 各 provider 文案不一（火山 GLM：`json_schema is not supported by this model`），
+ * 故宽松匹配："提到 response_format" 且 "出现 not support / unsupported / not valid / invalid"。
+ */
+function isResponseFormatUnsupported(status, errText) {
+    if (status !== 400)
+        return false;
+    const t = errText.toLowerCase();
+    if (!t.includes('response_format'))
+        return false;
+    return (t.includes('not support') || // 命中 "not supported"
+        t.includes('unsupported') ||
+        t.includes('not valid') ||
+        t.includes('invalid'));
+}
 /**
  * 调用 LLM 并以流的形式 yield 事件。
  *
@@ -61,38 +85,65 @@ export async function* chat(args) {
     // 3. 构造请求体
     // 逃生开关：极个别 provider 不认 stream_options 会 400，可用 MINIMAL_AGENT_DISABLE_USAGE=1 关掉。
     const includeUsage = process.env.MINIMAL_AGENT_DISABLE_USAGE !== '1';
-    const body = {
-        model: provider.model,
-        messages: cleanedMessages,
-        tools: openaiTools.length > 0 ? openaiTools : undefined,
-        stream: true,
-        // stream_options.include_usage：让 provider 在流末附带真实 prompt_tokens，
-        // 供上层自动压缩判断用；provider 不支持时 usagePromptTokens 保持 undefined，上层 fallback 本地估算。
-        ...(includeUsage ? { stream_options: { include_usage: true } } : {}),
-        // tool_choice: 'auto' 是默认值，可不写；某些 provider 必须显式
-        tool_choice: openaiTools.length > 0 ? 'auto' : undefined,
-        // ADR-05: structured output；缺省 undefined 不出现在 body（JSON.stringify 自动剥离）
-        response_format: responseFormat,
-    };
-    // 3. 发请求（fetch 在 Bun/Node 20+ 内置）
     const url = `${provider.baseURL.replace(/\/$/, '')}/chat/completions`;
-    const resp = await fetch(url, {
+    // response_format 能力探测：部分 OpenAI 兼容 provider（如火山 GLM 系）不支持
+    // response_format.type=json_schema，会回 400。已知不支持的 model 直接跳过，
+    // 撞到 400 则退化重试（去掉 response_format，靠 prompt 内嵌 schema + 上层 extractJsonPayload 容错解析）。
+    const rfKey = `${provider.baseURL}::${provider.model}`;
+    const wantResponseFormat = responseFormat !== undefined && !rfUnsupported.has(rfKey);
+    const postChat = (withResponseFormat) => fetch(url, {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${provider.apiKey}`,
         },
-        body: JSON.stringify(body),
+        body: JSON.stringify({
+            model: provider.model,
+            messages: cleanedMessages,
+            tools: openaiTools.length > 0 ? openaiTools : undefined,
+            stream: true,
+            // stream_options.include_usage：让 provider 在流末附带真实 prompt_tokens，
+            // 供上层自动压缩判断用；provider 不支持时 usagePromptTokens 保持 undefined，上层 fallback 本地估算。
+            ...(includeUsage ? { stream_options: { include_usage: true } } : {}),
+            // tool_choice: 'auto' 是默认值，可不写；某些 provider 必须显式
+            tool_choice: openaiTools.length > 0 ? 'auto' : undefined,
+            // ADR-05: structured output；缺省 undefined 不出现在 body（JSON.stringify 自动剥离）
+            response_format: withResponseFormat ? responseFormat : undefined,
+        }),
         signal,
     });
-    // 4. 错误处理：把 HTTP 错误尽量翻译成可读消息
+    // 3. 发请求（fetch 在 Bun/Node 20+ 内置）
+    const reqId = ++reqCounter;
+    dlog('llm', `req#${reqId} POST →`, {
+        model: provider.model,
+        rf: wantResponseFormat,
+        msgs: cleanedMessages.length,
+        tools: openaiTools.length,
+    });
+    let resp = await postChat(wantResponseFormat);
+    // 4. 错误处理：先处理 "json_schema 不支持" 的退化重试，再翻译其它 HTTP 错误
     if (!resp.ok) {
         const errText = await resp.text().catch(() => '');
-        throw new Error(`LLM 请求失败 [${resp.status} ${resp.statusText}]：${errText.slice(0, 500)}`);
+        if (wantResponseFormat && isResponseFormatUnsupported(resp.status, errText)) {
+            // 记住该 model 不支持，单进程内后续结构化调用直接跳过 response_format（不再撞 400）。
+            rfUnsupported.add(rfKey);
+            console.warn(`[minimal-agent] provider model "${provider.model}" 不支持 response_format.json_schema，` +
+                `已退化为 prompt 引导 + 容错解析（结构化输出的硬保证降级为尽力而为）。`);
+            resp = await postChat(false);
+            if (!resp.ok) {
+                const e2 = await resp.text().catch(() => '');
+                throw new Error(`LLM 请求失败 [${resp.status} ${resp.statusText}]：${e2.slice(0, 500)}`);
+            }
+        }
+        else {
+            throw new Error(`LLM 请求失败 [${resp.status} ${resp.statusText}]：${errText.slice(0, 500)}`);
+        }
     }
     if (!resp.body) {
         throw new Error('LLM 响应没有 body（provider 可能不支持流式？）');
     }
+    // fetch 已返回且 ok：若日志卡在这条之前 = fetch 阶段挂起（无超时）；卡在这条之后无 done = 流中途挂起。
+    dlog('llm', `req#${reqId} streaming begin (status ${resp.status})`);
     // 5. SSE 解析：把 ReadableStream 切成一行行 "data: ..." 然后 JSON.parse
     const reader = resp.body.getReader();
     const decoder = new TextDecoder();
@@ -129,6 +180,7 @@ export async function* chat(args) {
                 const dataStr = line.slice(5).trim(); // 去掉 "data:" 前缀
                 if (dataStr === '[DONE]') {
                     // 流结束标记；带出真实 prompt_tokens（provider 不返回时为 undefined，上层 fallback 本地估算）
+                    dlog('llm', `req#${reqId} done [DONE]`, { stopReason, promptTokens: usagePromptTokens });
                     yield { type: 'done', stopReason, promptTokens: usagePromptTokens };
                     return;
                 }
@@ -203,6 +255,7 @@ export async function* chat(args) {
             }
         }
         // 如果流没显式发 [DONE]，也补一个 done；同样带出 promptTokens
+        dlog('llm', `req#${reqId} done (stream end, no [DONE])`, { stopReason, promptTokens: usagePromptTokens });
         yield { type: 'done', stopReason, promptTokens: usagePromptTokens };
     }
     finally {

package/src/ui/hooks/useChat.js

@@ -26,6 +26,7 @@ import { ALL_TOOLS } from '../../tools/index.js';
 import { setAskHandler, } from '../../askBridge.js';
 import { clearFileState } from '../../tools/shared/fileState.js';
 import { runWithPlugins } from '../../plugins/pluginRunner.js';
+import { dlog } from '../../utils/debugLog.js';
 /**
  * reasoningPreview 环形 buffer 容量（字符）。
  * LiveArea 现在多行显示思维链尾部（最近 N 行），需要喂饱足够文本；
@@ -201,6 +202,10 @@ export function useChat(args) {
             return new Promise((resolve, reject) => {
                 askResolverRef.current?.reject(new Error('被新的提问取代'));
                 askResolverRef.current = { resolve, reject };
+                dlog('ui', 'ask handler INVOKED (等待用户答题)', {
+                    n: questions.length,
+                    headers: questions.map((q) => q.header),
+                });
                 setPendingAsk(questions);
                 const onAbort = () => {
                     if (!askResolverRef.current)
@@ -223,6 +228,7 @@ export function useChat(args) {
         const r = askResolverRef.current;
         askResolverRef.current = null;
         setPendingAsk(null);
+        dlog('ui', 'ask ANSWERED (继续执行)', { selected: answers.map((a) => a.selected) });
         r?.resolve(answers);
     }, []);
     // mount 时异步读 active session（默认 'default'，注册表里有就用注册值）。
@@ -267,6 +273,7 @@ export function useChat(args) {
         setRunningToolsMap(new Map());
         const ac = new AbortController();
         abortRef.current = ac;
+        dlog('ui', 'turn START', { input: trimmed.slice(0, 80) });
         try {
             for await (const ev of runWithPlugins(trimmed, {
                 provider: args.provider,
@@ -293,13 +300,17 @@ export function useChat(args) {
                     scheduleToolBump: toolBumpFlush.schedule,
                     cancelToolBump: toolBumpFlush.cancel,
                     bump,
+                    // 工作流进度逐步可见（持久暗色行）
+                    emitProgressLine: ephemeralLine,
                 });
             }
         }
         catch (e) {
             setError(`未捕获异常：${e.message}`);
+            dlog('ui', 'turn THREW', { err: e.message });
         }
         finally {
+            dlog('ui', 'turn END (finally)');
             setIsLoading(false);
             cancelAllThrottles();
             resetTurnState();
@@ -514,6 +525,27 @@ export function useChat(args) {
     };
 }
 export function handleEvent(ev, setters) {
+    // ---- 工作流进度事件（WorkflowEvent，不在 LoopEvent union 里）----
+    // 渲染成持久的暗色行落进 scrollback：跑到哪一步、成功/失败/跳过都看得见，
+    // 且出错后仍停留在屏幕上 —— 解决"工作流执行过程不可见、不知道停在哪"。
+    const wf = ev;
+    switch (wf.type) {
+        case 'workflow_start':
+            setters.emitProgressLine?.(`▶ 工作流 ${wf.name} 开始（共 ${wf.totalSteps} 步）`);
+            return;
+        case 'workflow_step_start':
+            setters.emitProgressLine?.(`  ▶ ${(wf.index ?? 0) + 1}/${wf.total ?? '?'} ${wf.id} (${wf.kind})`);
+            return;
+        case 'workflow_step_end':
+            setters.emitProgressLine?.(`  ${wf.ok ? '✓' : '✗'} ${wf.id}${wf.error ? `：${wf.error}` : ''}`);
+            return;
+        case 'workflow_step_skipped':
+            setters.emitProgressLine?.(`  ⊘ ${wf.id}：${wf.reason ?? ''}`);
+            return;
+        case 'workflow_done':
+            setters.emitProgressLine?.(`✓ 工作流 ${wf.name} 完成`);
+            return;
+    }
     // 收口到 LoopEvent：未识别的 PluginEvent type 走 default no-op
     const e = ev;
     switch (e.type) {

package/src/utils/debugLog.js

@@ -0,0 +1,52 @@
+/**
+ * ============================================================
+ *  src/utils/debugLog.ts —— 文件调试日志（环境变量开关，默认全程 no-op）
+ * ------------------------------------------------------------
+ *  为什么需要：TUI（Ink）独占 stdout/stderr，console.log 在 TUI 里看不见、还会搅乱画面；
+ *  而"卡死/不响应"这类问题恰恰无法靠正常退出来事后检查。把关键生命周期点**同步追加**到
+ *  一个磁盘文件，进程即便随后挂死，日志也已落盘——文件的最后一行就指向卡住的位置。
+ *
+ *  用法：
+ *    MINIMAL_AGENT_DEBUG_LOG=D:\tmp\ma-debug.log bun run start
+ *    然后复现问题，把该文件最后几十行发来即可定位。
+ *
+ *  设计：
+ *    - 未设环境变量 → dlog() 直接 return，零开销、零行为改变（不影响 npm/dev/绿色版任何路径）。
+ *    - 用 appendFileSync（同步）：宁可慢一点也要保证"挂死前那一行确实写进了磁盘"。
+ *    - 任何写日志的异常都吞掉，绝不让"记日志"反过来影响主流程。
+ * ============================================================
+ */
+import { appendFileSync } from 'node:fs';
+const LOG_PATH = process.env.MINIMAL_AGENT_DEBUG_LOG;
+/** 调试日志是否开启（供调用方决定要不要算开销较大的 data）。 */
+export function isDebugLogOn() {
+    return !!LOG_PATH;
+}
+/**
+ * 追加一行调试日志：`<ISO 时间> [tag] msg {data}`。
+ * 未开启（无 MINIMAL_AGENT_DEBUG_LOG）时立即返回。
+ */
+export function dlog(tag, msg, data) {
+    if (!LOG_PATH)
+        return;
+    try {
+        const ts = new Date().toISOString();
+        const line = data !== undefined
+            ? `${ts} [${tag}] ${msg} ${safeJson(data)}\n`
+            : `${ts} [${tag}] ${msg}\n`;
+        appendFileSync(LOG_PATH, line);
+    }
+    catch {
+        // 记日志失败绝不影响主流程
+    }
+}
+/** 安全 JSON：循环引用 / 超长都不抛、不撑爆日志。 */
+function safeJson(v) {
+    try {
+        const s = JSON.stringify(v);
+        return s.length > 600 ? `${s.slice(0, 600)}…` : s;
+    }
+    catch {
+        return String(v);
+    }
+}

package/workflows/plan.yaml

@@ -1,26 +1,40 @@
 # ============================================================
-#  workflows/plan.yaml —— 复刻 Claude Code「plan」流程（Analyze→Verify→Synthesize→Critic→Gate）
+#  workflows/plan.yaml —— 复刻 Claude Code「plan」流程（Clarify→Analyze→Verify→Synthesize→Critic→Gate）
 # ------------------------------------------------------------
-#  把 Ultracode 动态工作流的多阶段编进确定性 DAG，全用现有 StepKind（不改引擎）：
-#    Analyze   : analyze(agent 只读探索) → extract_findings(llm 固化成可验证 claims) → clarify_depth(AskUserQuestion 人机交互)
-#    Verify    : verify_findings(type:vote 红队对抗——对每条 finding 反向提问证伪，存活的才进下游)
-#    Synthesize: draft_plan(agent 综合"通过验证的结论"+用户选择，写 ./PLAN.md)
-#    Critic    : critic_plan(skill:adversarial-review 反向提问审稿，把审稿意见追加进 ./PLAN.md)
-#    Gate      : verify(assert 守门，确认 ./PLAN.md 确实生成)
-#  非交互宿主(-p/gateway)下 AskUserQuestion 自动选推荐项、vote 走 LLM，整条流程照常跑完。
+#  设计目标：① 跨基座模型稳（弱模型也能跑完，不依赖强 agent 多轮工具循环）；
+#            ② 提问只在「开头一次性」发生，之后全自主无打断，直到产出可提交的 PLAN.md。
+#  全用现有 StepKind（不改引擎）：
+#    Clarify   : clarify_depth(AskUserQuestion 开头一次性问深度——全流程唯一的人机交互点)
+#    Analyze   : analyze(agent 只读探索) → extract_findings(llm+schema 固化成可验证 claims)
+#    Verify    : verify_findings(type:vote 红队对每条 finding 反向提问证伪，存活的才进下游)
+#    Synthesize: draft_plan(llm 纯文本出计划正文) → read_existing_plan + write_plan(tool 确定性落盘)
+#    Critic    : critic_plan(skill:adversarial-review 反向提问审稿，追加进 PLAN.md)
+#    Gate      : verify(assert 守门确认 PLAN.md 生成)
 # ------------------------------------------------------------
-#  注：critic 阶段用 skill: 节点 dogfood 仓库自带的 adversarial-review skill —— 演示
-#  「同一套对抗审查方法既能 standalone（/adversarial-review）用、也能在 workflow 里被复用」。
-#  skill 双源查找（cwd 优先、packageRoot fallback）；万一异地 cwd 缺该 skill，
+#  模型兼容性要点（为什么这样切分——上一版在火山 GLM-5.1 上两处翻车的根治）：
+#    1. 写盘用 "llm 出正文 + tool:Write 落盘" 而非 agent。原 agent+Write 写法在弱模型上
+#       会反复调 Write 触发 miniReAct 重复检测 halt；真因还叠加 Write 的"覆盖前须先 Read"
+#       守卫——PLAN.md 已存在时首个 Write 被拒、模型重试同参 Write→3 次→halt。
+#       故 write 前置一个 tool:Read（onError:continue，首跑文件不存在则略过）满足守卫。
+#    2. 结构化输出(extract_findings / vote)由 client.ts 自动退化：provider 不支持
+#       response_format.json_schema(火山 GLM)时去掉它、靠 prompt 内嵌 schema + 容错解析。
+#    3. 仍是 agent 的只剩 analyze（只读探索）与 critic（审稿，onError:continue 兜底），
+#       它们在弱模型上最坏只是 halt/跳过，不破坏已产出的计划。
+# ------------------------------------------------------------
+#  提问节奏：唯一提问点 clarify_depth 放最前——问完之后全程自主无打断。任务专属、
+#  本工作流没问的点（受众/时长/范围等）由 draft 自做合理默认假设并在正文开头列出，
+#  绝不中途打断（契合"明确有优劣自动判断、只有真取舍才问、开头问完即自主"）。
+# ------------------------------------------------------------
+#  注：critic 用 skill: 节点 dogfood 仓库自带的 adversarial-review skill。
+#  skill 双源查找（cwd 优先、packageRoot fallback）；异地 cwd 缺该 skill 时
 #  critic 的 onError:continue 兜底——审稿出岔不应推翻已写好的计划。
 # ============================================================
 name: plan
 description: |
-  受工作流指导 + 红队对抗验证 + 反向提问审稿 + 人机交互的动态计划流程。
-  Analyze(探索+固化+问深度) → Verify(vote 红队证伪候选结论) → Synthesize(综合通过验证的结论写 PLAN.md)
-  → Critic(反向提问审稿，把意见追加进 PLAN.md) → Gate(assert 守门确认文件生成)。
-  minimal-agent 的旗舰演示。
-version: "0.2"
+  受工作流指导 + 红队对抗验证 + 反向提问审稿的动态计划流程（跨模型稳、开头一次性提问后全自主）。
+  Clarify(开头问深度) → Analyze(探索+固化) → Verify(vote 红队证伪) → Synthesize(出正文+落盘)
+  → Critic(反向提问审稿追加) → Gate(assert 守门)。minimal-agent 的旗舰演示。
+version: "0.3"
 
 inputs:
   - name: goal
@@ -29,6 +43,26 @@ inputs:
     description: "要做的事 / 目标"
 
 steps:
+  # ===================== Clarify（开头唯一提问点）=====================
+  # [Clarify] 一次性问"计划深度"（这是真有取舍、无统一最优的点；第一项=推荐，非交互自动选它）。
+  #   放最前：问完之后全程自主。其它任务专属细节(受众/时长/范围)由 draft 自做合理默认并列出，
+  #   不再中途打断——契合"明确有优劣自动判断、只有真取舍才问"。
+  - id: clarify_depth
+    tool: AskUserQuestion
+    args:
+      questions:
+        - header: "计划深度"
+          question: "希望这份实现计划做到多详细？"
+          options:
+            - label: "详细分步 (推荐)"
+              description: "拆成可执行的有序步骤，每步说清动作、涉及文件与验收点"
+            - label: "快速概览"
+              description: "只给高层方向与关键决策，不展开到每一步"
+            - label: "带风险/回滚评估"
+              description: "在详细分步之外，额外标注每步风险与回滚方案"
+    capture:
+      content: depth_answer
+
   # ===================== Analyze =====================
   # [Analyze-1] 只读探索：agent 自主用 Read/Grep/Glob 摸清现状（不写盘、不副作用）
   - id: analyze
@@ -40,7 +74,7 @@ steps:
     capture:
       content: analysis
 
-  # [Analyze-2] 固化成可验证 claims：llm 单轮 + output_schema，把笔记抽成数组（供 vote 逐条验证）
+  # [Analyze-2] 固化成可验证 claims：llm 单轮 + output_schema（provider 不支持时由 client.ts 自动退化）
   - id: extract_findings
     llm: |
       从下面的调研笔记中抽取「候选关键事实」与「未决问题」，原样保留信息、不要新增臆测。
@@ -63,27 +97,9 @@ steps:
       findings: findings
       open_questions: open_questions
 
-  # [Analyze-3] 人机交互：直接用 AskUserQuestion 问「计划深度」（第一项=推荐，非交互自动选它）
-  - id: clarify_depth
-    tool: AskUserQuestion
-    args:
-      questions:
-        - header: "计划深度"
-          question: "希望这份实现计划做到多详细？"
-          options:
-            - label: "详细分步 (推荐)"
-              description: "拆成可执行的有序步骤，每步说清动作、涉及文件与验收点"
-            - label: "快速概览"
-              description: "只给高层方向与关键决策，不展开到每一步"
-            - label: "带风险/回滚评估"
-              description: "在详细分步之外，额外标注每步风险与回滚方案"
-    capture:
-      content: depth_answer
-
   # ===================== Verify =====================
-  # [Verify] 红队对抗：vote 节点对每条 finding 反向提问证伪（voter 默认倾向 refuted=true）
-  #          refuted 票数 >= threshold 的 finding 被驳回，只有存活的进下游 —— 杜绝未证实结论污染计划。
-  #          注：voter 偏向证伪，存活集可能偏少甚至为空；下游 draft_plan 对此做了 graceful degrade（见其提示）。
+  # [Verify] 红队对抗：vote 对每条 finding 反向提问证伪（voter 默认倾向 refuted=true）；
+  #          存活集可能偏少甚至为空，draft 对此 graceful degrade（见其提示）。
   - id: verify_findings
     type: vote
     input: "findings"
@@ -99,11 +115,12 @@ steps:
       total: total_count
 
   # ===================== Synthesize =====================
-  # [Synthesize] 综合产出：agent 用"通过验证的结论"+用户选择落盘 ./PLAN.md，遇取舍可再问用户
+  # [Synthesize-1] 生成计划正文：llm 纯文本（不开工具、不提问）——确定性、跨模型稳，
+  #   彻底避开"agent 反复调 Write"的弱模型死循环。
   - id: draft_plan
-    agent: |
-      综合下列输入，为目标「${inputs.goal}」写一份中文实现计划，用 Write 落到 ./PLAN.md
-      （目录不存在先创建）。
+    llm: |
+      综合下列输入，为目标「${inputs.goal}」写一份**中文实现计划的完整 markdown 正文**
+      （直接输出正文本身：不要寒暄、不要复述要求、不要用代码围栏包裹整篇）。
 
       —— 通过红队对抗验证的结论（${kept_count}/${total_count} 条存活）——
       ${verified_findings}
@@ -115,21 +132,32 @@ steps:
       ${depth_answer}
 
       要求：
-      - 计划详细程度遵循用户上面的选择；
-      - 关于上面"存活结论"为空的两种情形请分别处理：若原本就没抽出 finding，按目标从头调研；
-        若是被红队全部驳回（存活 0 但 total>0），别盲信被否的结论，用 Read/Grep/Glob 重新取证后再写；
-      - 若遇方案取舍或关键信息模糊、继续做风险大，调 AskUserQuestion 让用户拍板
-        （每题第一个选项放推荐并在 label 末尾标「(推荐)」），据回答继续；
-      - 写完用 Read 自检 ./PLAN.md 内容确实落好了再收尾。
-    allowed_tools: [Read, Grep, Glob, Write, AskUserQuestion]
+      - 详细程度遵循用户选择的深度；
+      - "存活结论"为空时不要硬编：按目标常识给出合理的计划骨架；
+      - 凡需按需求拍板、但本工作流未询问的点（如受众/时长/范围），**自行做合理默认假设并继续**，
+        在正文开头用「## 假设（如需调整请告知）」一节列出假设，**绝不中断提问**。
     capture:
-      content: plan_text
+      # llm 步（无 output_schema）的 raw 只有 {text,result}，没有 content（那是 tool 步的字段）。
+      # 用错字段会 capture 到 undefined → 下游 Write 写 0 字节（已被端到端测试抓到）。
+      text: plan_text
+
+  # [Synthesize-2] 满足 Write 的"覆盖前须先 Read"守卫：PLAN.md 已存在则先 Read；
+  #   首跑文件不存在 → Read 报错 → onError:continue 略过（不影响后续 Write 新建）。
+  - id: read_existing_plan
+    tool: Read
+    args:
+      file_path: ./PLAN.md
+    onError: continue
+
+  # [Synthesize-3] 落盘：tool:Write 确定性写入（不经 agent 循环，弱模型也稳）
+  - id: write_plan
+    tool: Write
+    args:
+      file_path: ./PLAN.md
+      content: "${plan_text}"
 
   # ===================== Critic =====================
-  # [Critic] 反向提问审稿：dogfood 仓库自带的 adversarial-review skill —— 同一套对抗审查
-  #          方法，既能 standalone（/adversarial-review）用，也能在 workflow 里被 skill: 复用。
-  #          产出由 skill 子 agent 直接 Edit/Write 追加进 ./PLAN.md（不 capture——下游无人消费）。
-  #          onError:continue —— 审稿出岔（含异地 cwd 缺 skill）不应推翻已写好的计划。
+  # [Critic] 反向提问审稿：dogfood 仓库自带 adversarial-review skill；onError:continue 兜底
   - id: critic_plan
     skill: adversarial-review
     maxTurns: 25
@@ -145,4 +173,4 @@ steps:
   - id: verify
     type: assert
     condition: 'fileExists("./PLAN.md")'
-    onFail: "计划文件 ./PLAN.md 未生成，检查 draft_plan 步是否成功用 Write 落盘"
+    onFail: "计划文件 ./PLAN.md 未生成，检查 draft_plan/write_plan 步是否成功"