minimal-agent 0.6.9 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.6.9",
+  "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/skills/adversarial-review/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: adversarial-review
+description: 质疑一个结论 / 计划 / 既有评审 / 设计方案是否站得住脚——默认怀疑、逼出证据，把发现分成「真问题 / 误报 / 待澄清」。注意：若用户只是想给代码找冗余 / 反模式 / 做常规质量改进，用 /simplify 而非本 skill。
+triggers: 对抗审查、反向提问、红队、挑战这个结论、验证某结论或方案是否站得住脚、哪些是误报哪些是真问题、审稿、复核这个判断
+---
+
+# /adversarial-review —— 对抗式审查（反向提问，默认怀疑）
+
+## 目的
+
+验证一个**结论 / 计划 / 既有评审 / 设计方案 / 一段代码**是否站得住脚时，别让模型（或你自己）
+轻易点头。人和 LLM 面对「这个对吗？」都有**迎合反射**——倾向于附和、补论据、越夸越顺。
+本 skill 的目的：用「反向提问」把这种迎合反射**翻转成怀疑反射**，再用举证纪律把怀疑落到实处，
+最终把发现诚实地分成 🔴 真问题 / ⚪ 误报 / 🟡 待澄清。
+
+## 方法一：把问题转成「表面反向的提问」（扳机）
+
+**永远不要问「X 对不对 / X 是否正确」，要问「X 是不是错的 / X 哪里站不住脚」。**
+
+为什么仅仅换个问法就有用？因为**举证责任被翻转**了：
+
+- 问「X 对吗？」→ 回答者可以**零成本附和**（"对的、挺好"），不费力就能交差，迎合反射全开。
+- 问「X 错在哪？」→ 回答者**必须先假设它有错**，然后去枚举失败场景、找反例、回现场核对才能回答；
+  哪怕最后发现 X 其实成立，那也是**认真攻击过之后**的结论，而不是反射性点头。
+
+类比面试：问「你会不会用 X？」对方反射答「会」；但问「你是不是其实不会 X？」对方被迫拿出
+真凭实据来反驳你——被逼着深度思考、自证清白。对抗审查就是把**每一次判断**都塞进后一种问法里。
+
+> ⚠️ 「换问法」只是扳机，不是终点。光把问法反过来，模型同样可能编出**看似合理却牵强**的
+> 假问题来"完成证伪任务"，那是在制造新的误报。所以扳机必须接上「方法二：举证纪律」。
+
+## 方法二：举证纪律（引擎）
+
+反向提问扣动扳机后，每条判断都要过这三关，否则不算数：
+
+1. **拆成原子主张**：把审查对象切成一条条**能被单独证伪**的主张。整段"感觉对"没意义，可攻击的最小单元才有。
+2. **举证责任在主张方**：每条主张默认**未被证实**，靠具体反例 / 现场核对 / 可查依据来支撑或推翻。判定一律附证据，不附证据的判定本身就是错的。
+3. **去现场，不凭记忆**：涉及代码 / 事实的主张，一律 Read / Grep 核对原文。用脑内印象当证据是制造误报的头号来源。
+
+**误报和漏报一样有害。** 把成立的主张硬说成问题，和放过真问题一样是审查失败——这与「默认怀疑」同等重要。
+
+## 反向提问转换示例（按情况直接套用）
+
+把用户原本（或心里）的「迎合式问法」翻成「反向式问法」，再走方法二的纪律：
+
+| 你想确认的事（迎合式 ❌） | 反向提问的问法（✅ 套这个） |
+|---|---|
+| 这个方案对吗？ | 这个方案**是不是错的**？它在什么输入 / 场景 / 规模下会崩？哪一步的假设最可能不成立？ |
+| 这份代码评审准吗？ | 这份评审里**哪些是误报、哪些是真问题**？逐条去现场核对它说的代码是否真这样。 |
+| 我刚写的这段代码没问题吧？ | 这段代码**哪里有 bug**？给我一个能让它出错的具体输入 / 边界 / 并发时序。 |
+| X 这个事实成立吗？ | X **在什么情况下是假的**？反例是什么？它的依据经得起核对吗？ |
+| 该选方案 A 吗？ | 选 A **会在什么场景下变成错误决定**？A 比 B 差在哪？A 的隐藏代价是什么？ |
+| 这个回答 / 总结完整吗？ | 这个回答**漏了什么**？哪个边界 / 失败路径 / 反例没覆盖？ |
+| 这个重构安全吗？ | 这个重构**会悄悄破坏什么**？哪些调用方 / 测试 / 契约依赖了被改掉的行为？ |
+| 文档 / 注释和代码一致吗？ | 文档**哪一句和代码对不上**？逐句拿去和实现核对，找出已经过时（stale）的描述。 |
+
+**worked example（评审复核——最常见场景）**
+
+输入：「上一阶段的改动，代码评审说有以下 N 个问题，是不是误报？」
+
+- ❌ 迎合式追问「这些问题对吗？」→ 模型容易逐条附和"是的这是问题"，等于没审。
+- ✅ 反向式追问：「这 N 条里**哪些是误报、哪些是真问题，为什么**？每条都 Read 对应文件去现场核对它
+  描述的代码是否属实；拿得出反例/实证的才标 🔴 真问题，只是'觉得没充分说明'但推不倒的标 🟡 待澄清，
+  确认其实成立的标 ⚪ 误报并给出它为何成立。」
+- 效果：模型被迫**为每条结论举证**（无论判真还是判误报），迎合空间被挤掉——这正是本 skill 要的。
+
+## Quick Reference
+
+| 步骤 | 操作 |
+|------|------|
+| 1 | 用 Read 读取被审查对象（结论/计划/评审/设计/代码）；必要时 Grep/Glob 取证，去现场核对而非凭记忆 |
+| 2 | 把对象拆成一条条**独立、可被单独证伪**的原子主张 |
+| 3 | 对每条问「哪里站不住脚」（见下方拷问清单），强迫找反例与证据 |
+| 4 | 给每条分类：🔴 真问题 / ⚪ 误报 / 🟡 待澄清 |
+| 5 | 每条都附**证据**与**为什么**（凭什么这么判，证据指向哪里）；没证据就别下 🔴 结论 |
+
+## 第 3 步：对每条主张的拷问清单
+
+逐条追问，任意一条命中就标记下来：
+
+- **证据不足？** —— 它的依据是什么？依据本身可靠吗，还是空口断言？
+- **把假设当事实？** —— 哪些是已验证的事实，哪些只是"应该是这样"的假设被当成了前提？
+- **想当然 / 跳步？** —— 推导链有没有缺环？"因为 A 所以 C"中间的 B 被默认了吗？
+- **有反例？** —— 能不能举出一个让它崩掉的具体场景、输入、边界条件？
+- **被现有代码/事实推翻？** —— 去 Grep/Read 核对，它描述的代码真长这样吗？实现真按它说的走吗？
+
+### 证明不了 ≠ 错
+
+一段文本里很多成立的主张本就不会附带完整证据——**省略不等于错误**。所以：
+
+- 你能拿出反例 / 找到被现有代码推翻的实证 → 标 **🔴 真问题**。
+- 你只是觉得它"没充分举证"、但也举不出反例 → 标 **🟡 待澄清**，并写明「缺哪个证据才能判定」，**不要**直接判 🔴。
+
+把「主张错误」与「主张未充分举证」混为一谈，是这类审查最常见的误报来源。
+
+## 输出格式
+
+三类同等呈现，不预设哪类一定有内容（真问题为 0 条是合法且常见的结论）：
+
+```
+## 对抗审查结果
+
+### 🔴 真问题（拿得出反例/实证的）
+1. [主张/位置] 这条为什么站不住脚 → 证据（文件:行 / 反例 / 事实）→ 影响
+2. ...
+（若无：「真问题：0 条——下方列出已尝试的攻击角度」）
+
+### ⚪ 误报（曾被怀疑、但其实成立）
+1. [主张/位置] 原审查/结论怀疑的点 → 为什么它其实成立 → 证据
+2. ...
+
+### 🟡 待澄清（未充分举证、但也推不倒）
+1. [主张/位置] 缺什么证据才能判定 → 需要用户/作者补充什么
+2. ...
+
+### 结论
+一句话定调：整体站得住脚 / 有 N 个真问题需修 / 关键前提待澄清。
+```
+
+## 注意事项
+
+- **误报和漏报一样有害**（已在核心段强调，这里重申落地）。不要为了"显得严格"就把成立的结论硬说成问题——驳回一条主张同样要给证据，凭感觉拍砖等于制造新的误报。
+- **找不到真问题就如实说**。如果对象本身扎实、你认真攻击后确实推不倒它，就直说"未发现真问题"，并**列出你尝试过的反驳角度**（找过哪些反例、核对过哪些代码、质疑过哪些假设），证明你是真的攻击过、而非偷懒放水。
+- **去现场，别凭记忆**。涉及代码/事实的主张，一律 Read/Grep 核对原文，不要用脑内印象当证据。
+- **边界**：本 skill 用于质疑「结论 / 计划 / 既有评审 / 设计是否站得住脚」。若用户只是想给代码找冗余 / 反模式 / 做常规质量改进，那是 /simplify 的活，不要套用这里的「默认有罪」框架。

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,28 +1,40 @@
 # ============================================================
-#  workflows/plan.yaml —— 复刻 Claude Code「plan」流程的动态工作流
+#  workflows/plan.yaml —— 复刻 Claude Code「plan」流程（Clarify→Analyze→Verify→Synthesize→Critic→Gate）
 # ------------------------------------------------------------
-#  旗舰演示 AskUserQuestion + 「受工作流指导的有界 TAOR」+ 人机交互：
-#    探索（agent 只读调研） → 澄清（直接用工具问用户，带推荐项）
-#      → 产出计划（agent 综合上下文落盘，遇取舍再回头问用户拍板） → 守门 assert。
-#
-#  与 adaptive-research 的区别：那条线演示「指导 + 随机应变」的旋钮，
-#  这条线把「交互（向用户提问）」也编进确定性骨架里 —— 既有 agent 节点的自主，
-#  又有 tool: AskUserQuestion 节点的「停下来问人」，二者共骑同一座 askBridge。
-#
-#  非交互宿主（-p / gateway / 子进程）下没有 UI handler，AskUserQuestion
-#  会自动选每题首项（约定=推荐项），整条流程照常跑完、绝不挂起。
+#  设计目标：① 跨基座模型稳（弱模型也能跑完，不依赖强 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 生成)
+# ------------------------------------------------------------
+#  模型兼容性要点（为什么这样切分——上一版在火山 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: |
-  受工作流指导 + 可向用户提问 + 有界 TAOR 的动态计划流程。
-  - 先用有界子 agent 只读调研目标，梳理关键事实与未决点（不写盘、不副作用）；
-  - 再用 AskUserQuestion 直接问用户「计划要做到多详细」（带推荐项的单选）；
-  - 然后子 agent 综合调研与用户选择产出中文实现计划落到 ./PLAN.md，
-    遇到取舍 / 模糊点可再调 AskUserQuestion 让用户拍板；
-  - 最后 assert 守门，确认 PLAN.md 确实生成。
-  这是 minimal-agent 的旗舰演示：把「探索→澄清→（带推荐的）选择→产出计划」
-  编成确定性骨架，每个 agent 节点内是有界 TAOR，交互骑在 tool_call 回路上。
-version: "0.1"
+  受工作流指导 + 红队对抗验证 + 反向提问审稿的动态计划流程（跨模型稳、开头一次性提问后全自主）。
+  Clarify(开头问深度) → Analyze(探索+固化) → Verify(vote 红队证伪) → Synthesize(出正文+落盘)
+  → Critic(反向提问审稿追加) → Gate(assert 守门)。minimal-agent 的旗舰演示。
+version: "0.3"
 
 inputs:
   - name: goal
@@ -31,19 +43,10 @@ inputs:
     description: "要做的事 / 目标"
 
 steps:
-  # 1. 探索：agent 只读调研，自主用 Read/Grep/Glob 梳理事实与未决点（不写盘）
-  - id: research
-    agent: |
-      只读调研目标「${inputs.goal}」相关的代码 / 资料：用 Read、Grep、Glob 工具
-      （不要写文件、不要执行副作用命令）摸清现状，梳理出 3-6 条关键事实
-      以及 1-3 个仍然未决 / 需要用户拍板的点。
-      用简洁的中文 markdown 列点整理后直接作为你的最终回答返回，供后续步骤参考。
-    allowed_tools: [Read, Grep, Glob]
-    capture:
-      content: findings
-
-  # 2. 澄清：直接用 AskUserQuestion 工具问用户「计划深度」（演示 tool 节点交互）
-  #    第一个选项是推荐项（label 末尾标「(推荐)」），非交互宿主会自动选它。
+  # ===================== Clarify（开头唯一提问点）=====================
+  # [Clarify] 一次性问"计划深度"（这是真有取舍、无统一最优的点；第一项=推荐，非交互自动选它）。
+  #   放最前：问完之后全程自主。其它任务专属细节(受众/时长/范围)由 draft 自做合理默认并列出，
+  #   不再中途打断——契合"明确有优劣自动判断、只有真取舍才问"。
   - id: clarify_depth
     tool: AskUserQuestion
     args:
@@ -60,31 +63,114 @@ steps:
     capture:
       content: depth_answer
 
-  # 3. 产出计划：agent 综合 findings + 用户选择落盘 ./PLAN.md，
-  #    遇取舍/模糊点可再调 AskUserQuestion 让用户拍板（带推荐项），写完用 Read 自检。
-  - id: draft_plan
+  # ===================== Analyze =====================
+  # [Analyze-1] 只读探索：agent 自主用 Read/Grep/Glob 摸清现状（不写盘、不副作用）
+  - id: analyze
     agent: |
-      综合下面两份输入，为目标「${inputs.goal}」写一份中文实现计划，
-      用 Write 工具落到 ./PLAN.md（目录不存在就先创建）。
+      只读调研目标「${inputs.goal}」相关的代码 / 资料：用 Read、Grep、Glob 工具
+      （不要写文件、不要执行副作用命令）摸清现状，整理出 3-6 条候选关键事实
+      以及 1-3 个仍未决 / 需用户拍板的点，用简洁中文 markdown 列点返回。
+    allowed_tools: [Read, Grep, Glob]
+    capture:
+      content: analysis
 
-      —— 调研结论（findings）——
-      ${findings}
+  # [Analyze-2] 固化成可验证 claims：llm 单轮 + output_schema（provider 不支持时由 client.ts 自动退化）
+  - id: extract_findings
+    llm: |
+      从下面的调研笔记中抽取「候选关键事实」与「未决问题」，原样保留信息、不要新增臆测。
+      调研笔记：
+      ${analysis}
+    output_schema:
+      type: object
+      additionalProperties: false
+      required: [findings, open_questions]
+      properties:
+        findings:
+          type: array
+          items: { type: string }
+          description: "每条独立成句的候选关键事实（便于逐条对抗验证）"
+        open_questions:
+          type: array
+          items: { type: string }
+          description: "仍需进一步验证 / 用户拍板的点"
+    capture:
+      findings: findings
+      open_questions: open_questions
+
+  # ===================== Verify =====================
+  # [Verify] 红队对抗：vote 对每条 finding 反向提问证伪（voter 默认倾向 refuted=true）；
+  #          存活集可能偏少甚至为空，draft 对此 graceful degrade（见其提示）。
+  - id: verify_findings
+    type: vote
+    input: "findings"
+    voters_count: 3
+    threshold: 2
+    rules: |
+      判断这条「调研结论」是否站得住脚。不要问"它对不对"，要问"它哪里是错的"：
+      是否证据不足、把假设当事实、想当然、会被反例或现有代码/资料推翻。
+      只有当你找不到任何合理反驳、且它确有依据时，才认定成立（refuted=false）。
+    capture:
+      survived: verified_findings
+      kept: kept_count
+      total: total_count
+
+  # ===================== Synthesize =====================
+  # [Synthesize-1] 生成计划正文：llm 纯文本（不开工具、不提问）——确定性、跨模型稳，
+  #   彻底避开"agent 反复调 Write"的弱模型死循环。
+  - id: draft_plan
+    llm: |
+      综合下列输入，为目标「${inputs.goal}」写一份**中文实现计划的完整 markdown 正文**
+      （直接输出正文本身：不要寒暄、不要复述要求、不要用代码围栏包裹整篇）。
+
+      —— 通过红队对抗验证的结论（${kept_count}/${total_count} 条存活）——
+      ${verified_findings}
 
-      —— 用户对计划深度的选择 ——
+      —— 仍未决的问题 ——
+      ${open_questions}
+
+      —— 用户选择的计划深度 ——
       ${depth_answer}
 
       要求：
-      - 计划详细程度遵循用户上面的选择；
-      - 若过程中遇到方案取舍或关键信息模糊、继续做风险大，调用 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；onError:continue 兜底
+  - id: critic_plan
+    skill: adversarial-review
+    maxTurns: 25
+    input: |
+      对当前目录下的 ./PLAN.md 做一次对抗审查（先用 Read 读它）。审完用 Edit / Write 在文件
+      末尾追加一节 "## 审稿意见（反向提问对抗审查）"，按 skill 的输出格式分
+      「🔴 真问题 / ⚪ 误报 / 🟡 待澄清」三类列出并附结论（真问题为 0 条也如实写）。
+      只新增这一节，不要重写或删改计划正文。
+    onError: continue
 
-  # 4. 守门：确认计划文件确实生成，否则给出中文排查提示
+  # ===================== Gate =====================
+  # [Gate] 守门：确认计划文件确实生成
   - id: verify
     type: assert
     condition: 'fileExists("./PLAN.md")'
-    onFail: "计划文件 ./PLAN.md 未生成，检查 draft_plan 步是否成功用 Write 落盘"
+    onFail: "计划文件 ./PLAN.md 未生成，检查 draft_plan/write_plan 步是否成功"