minimal-agent 0.7.0 → 0.8.0

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 步是否成功"