minimal-agent 0.6.7 → 0.6.8

package/README.md

@@ -1,7 +1,7 @@
 # minimal-agent
 
 > 一个**最小化但功能完整**的 AI 编程助手 —— Bun + React + TypeScript + Ink TUI 构建，
-> OpenAI 兼容、多 provider，10 个内置工具 + Skills + 插件 + Workflow DSL + 自动上下文压缩。
+> OpenAI 兼容、多 provider，11 个内置工具 + Skills + 插件 + Workflow DSL + 自动上下文压缩。
 > 为**学习与教学**而生：代码量克制、注释充分，把一个 agent「从输入到工具循环到落盘」讲透。
 
 `v0.5.1` · Runtime: **Bun**（主）/ Node ≥ 20 · License: **PolyForm Noncommercial 1.0.0**
@@ -22,7 +22,7 @@
 
 ## 特性
 
-- **10 个内置工具**：Read / Write / Edit / MultiEdit / Glob / Grep / WebSearch / WebFetch / WebBrowser / Bash
+- **11 个内置工具**：Read / Write / Edit / MultiEdit / Glob / Grep / WebSearch / WebFetch / WebBrowser / Bash / AskUserQuestion（向用户提结构化选择题，动态工作流交互底座）
 - **OpenAI 兼容**：Message 形状对齐 Chat Completions，一套代码接 MiniMax / 火山 ARK / DeepSeek / OpenAI / Moonshot…
 - **Skills 系统**：放一个 `SKILL.md` 就能扩展能力，运行时实时扫描注入 prompt，改文件即生效
 - **插件系统**：`plugins/<id>/` drop-in，自带 `/ralph-loop`（复制任务循环）与 `/workflow`（YAML DAG 执行器）
@@ -200,7 +200,7 @@ dev 下 Bun 透明回退到 `.ts` 兄弟，发布前 `tsc --build` 原地产出
 | `src/loop.ts` | `runQuery()` 主循环（AsyncGenerator）—— 系统的「心脏」 |
 | `src/llm/client.ts` | OpenAI 兼容流式客户端（text / tool_call / reasoning 三路） |
 | `src/types.ts` | 对齐 Chat Completions 的 Message / ToolCall / 事件类型 |
-| `src/tools/` | 10 个工具 + `executeTool()` 参数防线（JSON.parse → Zod → call） |
+| `src/tools/` | 11 个工具 + `executeTool()` 参数防线（JSON.parse → Zod → call） |
 | `src/context/compact.ts` | 自动上下文压缩 |
 | `src/prompts/` | system prompt 组装 + Skills 实时扫描注入 |
 | `src/plugins/` | 插件框架（discovery / 命令路由 / hook 引擎 / transcript） |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "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/src/askBridge.js

@@ -0,0 +1,61 @@
+/**
+ * ============================================================
+ *  src/askBridge.ts —— 「向人提问」的宿主交互桥（host interaction channel）
+ * ------------------------------------------------------------
+ *  动态工作流的地基：让一个**工具**（AskUserQuestion）能在执行中途停下来问用户，
+ *  拿到选择再继续。对齐上游 Claude Code 的 AskUserQuestion —— 交互不是给工作流引擎
+ *  特制的「双向生成器通道」，而是**骑在既有 tool_call → tool_result 回路上**：
+ *  「等用户」只不过是这个工具返回得慢而已。所以同一座桥同时服务于：
+ *    - 主循环 TAOR（模型自己决定何时 AskUserQuestion）
+ *    - workflow 的 `tool: AskUserQuestion` 步骤
+ *    - agent: 节点 miniReAct 把 AskUserQuestion 纳入工具白名单
+ *  → 这就是「交互 + TAOR = 动态工作流」。
+ *
+ *  为什么放在 src 根（而非 ui/ 或 tools/）：它是工具（产出问题）与宿主/UI（回答）
+ *  之间的中介，两边都要 import。放在中立位置，避免 tools → ui 的反向层级耦合。
+ *
+ *  两种宿主：
+ *    - TUI：useChat mount 时 setAskHandler() 注册一个会弹出选择界面的处理器。
+ *    - 非交互（`-p` / gateway / webchat 子进程）：没有 handler →
+ *      requestUserChoice() 自动选**推荐项（每题首项）**并在 stderr 注记，
+ *      绝不挂起（保 `-p` 单行 JSON 契约 + 子进程不卡死）。
+ * ============================================================
+ */
+let handler = null;
+/**
+ * 注册 / 注销 UI 处理器。
+ * TUI 的 useChat 在 mount 时注册、unmount 时传 null 注销。
+ * 单进程单 UI，模块级单例即可；HTTP 多租户场景以后再按 session 隔离（留 TODO）。
+ */
+export function setAskHandler(h) {
+    handler = h;
+}
+/** 是否有交互 UI 在场（测试 / 诊断用）。 */
+export function hasAskHandler() {
+    return handler !== null;
+}
+/**
+ * 向用户提问，返回答案。
+ *
+ * - 有 handler（TUI）→ 交给它弹界面、等用户。
+ * - 无 handler（非交互宿主）→ 自动选每题首项（约定=推荐），stderr 注记，不挂起。
+ */
+export async function requestUserChoice(questions, signal) {
+    if (handler)
+        return handler(questions, signal);
+    // 非交互兜底
+    return questions.map((q) => {
+        const pick = q.options[0]?.label ?? '';
+        try {
+            process.stderr.write(`[AskUserQuestion·非交互] "${q.header}" 无 UI，自动选推荐项："${pick}"\n`);
+        }
+        catch {
+            /* stderr 不可用也不阻断 */
+        }
+        return {
+            header: q.header,
+            question: q.question,
+            selected: pick ? [pick] : [],
+        };
+    });
+}

package/src/cli/streamJson.js

@@ -10,17 +10,22 @@
  *      逐行转发成 WebSocket event 帧。也是给网关预留的"流式子进程"契约。
  *
  *  约定：
- *    - stdout 只允许 jsonl 事件流（一行一个 JSON.stringify(LoopEvent)）
- *    - prompt 经 argv 或 stdin（与 print 一致）；--compact 走压缩动作（无需 prompt）
- *    - 跑完 / 中断 / 出错都先 saveContext 再退出
+ *    - stdout 只允许 jsonl 事件流（一行一个 JSON.stringify(LoopEvent)），含「问答 over wire」
+ *      的出站事件 `{type:'ask',requestId,questions}`（AskUserQuestion 在远程通道弹问题）。
+ *    - stdin 是**逐行 JSON 控制通道**（见 attachStdinChannel）：首行 `{type:'prompt',text}` 为本轮输入，
+ *      后续 `{type:'ask_answer',requestId,answers}` 回灌用户选择。兼容：首行非控制消息 → 整段当裸 prompt。
+ *      argv 也可给 prompt（此时 stdin 全部行按 ask_answer 解析）。--compact 走压缩动作（无需 prompt）。
+ *    - 跑完 / 中断 / 出错都先 saveContext 再退出（finalize 还会 unref stdin，让本轮结束后进程能退出）。
  * ============================================================
  */
+import crypto from 'node:crypto';
 import { getWorkingDir } from '../bootstrap/workingDir.js';
 import { forceCompact } from '../context/compact.js';
 import { recordRecentDir } from '../context/recentDirs.js';
 import { saveContext } from '../context/persistContext.js';
+import { setAskHandler } from '../askBridge.js';
 import { runWithPlugins } from '../plugins/pluginRunner.js';
-import { extractPromptArgs, readFromStdin } from './print.js';
+import { extractPromptArgs } from './print.js';
 /** 一行一个 JSON 事件写 stdout。EPIPE 时静默。 */
 function emitLine(ev) {
     try {
@@ -34,6 +39,79 @@ function firstUserTitle(history) {
     const u = history.find((m) => m.role === 'user');
     return u && typeof u.content === 'string' ? u.content : undefined;
 }
+/**
+ * stdin 控制通道：把 stdin 从「一次性裸 prompt」升级为**逐行 JSON 控制通道**，
+ * 支撑「问答 over wire」的入站半边。两种控制消息：
+ *   - `{ type:'prompt', text }`     —— 首行，本轮的用户输入（替代裸 prompt）
+ *   - `{ type:'ask_answer', requestId, answers }` —— AskUserQuestion 的回答，按 requestId 关联
+ *
+ * 向后兼容：首个非空行**不是** `{type:'prompt'}` 控制消息时，判定为 legacy 模式 ——
+ * 整段 stdin 当裸 prompt 读到 EOF（保 `echo "x" | minimal-agent -p --output-format stream-json` 仍可用，
+ * legacy 下天然无交互、一次性）。argv 已给 prompt 时，stdin 全部行都按 ask_answer 解析。
+ *
+ * 返回 prompt 的 Promise；同时把 ask_answer 路由给 onAskAnswer。stdin 全程保持打开，
+ * 直到子进程结束（broker 在 turn 末 end stdin）。
+ */
+export function attachStdinChannel(opts) {
+    const input = opts.input ?? process.stdin;
+    return new Promise((resolvePrompt) => {
+        let promptResolved = false;
+        const resolveOnce = (text) => {
+            if (promptResolved)
+                return;
+            promptResolved = true;
+            resolvePrompt(text);
+        };
+        if (opts.argvPrompt !== undefined)
+            resolveOnce(opts.argvPrompt);
+        // 无 stdin 管道（TTY）：argv 没给 prompt 也只能返回空（调用方据空报错）。
+        if (input.isTTY) {
+            resolveOnce('');
+            return;
+        }
+        let buf = '';
+        let legacy = false;
+        input.setEncoding('utf8');
+        input.on('data', (chunk) => {
+            buf += chunk;
+            if (legacy)
+                return; // legacy：整段累积到 EOF
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                if (!line.trim())
+                    continue;
+                let msg = null;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    msg = null;
+                }
+                if (!promptResolved) {
+                    if (msg && msg.type === 'prompt' && typeof msg.text === 'string') {
+                        resolveOnce(msg.text);
+                    }
+                    else {
+                        // 首行不是 prompt 控制消息 → legacy：把它放回去，整段当裸 prompt 读到 EOF
+                        legacy = true;
+                        buf = buf.length ? `${line}\n${buf}` : line;
+                        return;
+                    }
+                }
+                else if (msg && msg.type === 'ask_answer' && typeof msg.requestId === 'string') {
+                    opts.onAskAnswer(msg.requestId, Array.isArray(msg.answers) ? msg.answers : []);
+                }
+            }
+        });
+        input.on('end', () => {
+            // legacy 一次性：EOF 时整段 stdin = 裸 prompt
+            if (!promptResolved)
+                resolveOnce(buf.trim());
+        });
+    });
+}
 export async function runStreamJsonMode(provider, args, initialHistory, options) {
     process.stdout.on('error', (err) => {
         if (err.code === 'EPIPE')
@@ -45,6 +123,16 @@ export async function runStreamJsonMode(provider, args, initialHistory, options)
         if (finalized)
             return;
         finalized = true;
+        // 释放 stdin：attachStdinChannel 的 'data' 监听会让进程在本轮结束后**仍存活**
+        // （等下一行输入）→ broker 永远收不到子进程 close、web 端 conn.running 卡死。
+        // turn 已结束（无挂起提问），unref 让 stdout 排空后进程自然退出；中途挂起期间
+        // 不会走到这里，故等答案时进程仍被 stdin 监听保活。
+        try {
+            process.stdin.unref();
+        }
+        catch {
+            /* 某些 stdin 类型无 unref，忽略 */
+        }
         await saveContext(history);
     };
     // --- 压缩动作（/compact）：不需要 prompt ---
@@ -64,20 +152,33 @@ export async function runStreamJsonMode(provider, args, initialHistory, options)
         return;
     }
     // --- 普通一轮 ---
+    // 「问答 over wire」入站半边：pendingAsks 持本轮未决提问（requestId → resolver）。
+    const pendingAsks = new Map();
+    const rejectAllAsks = (reason) => {
+        for (const p of pendingAsks.values())
+            p.reject(new Error(reason));
+        pendingAsks.clear();
+    };
+    // 注册 askBridge handler：工具调 requestUserChoice → emit `ask` 到 stdout、挂起等 stdin 回灌的 ask_answer。
+    // 同一时刻可有多个未决问题（按 requestId 区分），但工具 isConcurrencySafe:false → 实际串行。
+    setAskHandler((questions) => new Promise((resolve, reject) => {
+        const requestId = crypto.randomUUID();
+        pendingAsks.set(requestId, { resolve, reject });
+        emitLine({ type: 'ask', requestId, questions });
+    }));
     const promptArgs = extractPromptArgs(args);
-    let prompt;
-    if (promptArgs.length > 0) {
-        prompt = promptArgs.join(' ');
-    }
-    else if (!process.stdin.isTTY) {
-        prompt = await readFromStdin();
-    }
-    else {
-        emitLine({ type: 'error', error: '未提供 prompt', code: 'llm_error' });
-        process.exit(1);
-    }
+    const prompt = await attachStdinChannel({
+        argvPrompt: promptArgs.length > 0 ? promptArgs.join(' ') : undefined,
+        onAskAnswer: (requestId, answers) => {
+            const p = pendingAsks.get(requestId);
+            if (p) {
+                pendingAsks.delete(requestId);
+                p.resolve(answers);
+            }
+        },
+    });
     if (!prompt.trim()) {
-        emitLine({ type: 'error', error: 'prompt 为空', code: 'llm_error' });
+        emitLine({ type: 'error', error: '未提供 prompt（argv / stdin 都为空）', code: 'llm_error' });
         process.exit(1);
     }
     // 记录最近目录（侧栏用）；title 优先用历史里第一条用户消息（稳定），否则用当前 prompt
@@ -89,6 +190,7 @@ export async function runStreamJsonMode(provider, args, initialHistory, options)
             process.exit(130);
         interrupted = true;
         abortController.abort();
+        rejectAllAsks('已中断'); // 挂起的提问立即落败，工具回 ok:false → loop 收口 interrupted
         emitLine({ type: 'interrupted' });
         void finalize().finally(() => process.exit(130));
     });

package/src/prompts/system.js

@@ -84,6 +84,9 @@ ${toolList}
   仅在 WebFetch 明确无法满足（如需要 JS 渲染后的内容、点击按钮、填表单、截图）时再尝试。
   如果 WebBrowser 报"无法启动浏览器/缺少依赖"，不要重试，改回 WebFetch 或告知用户安装依赖。
 - 一次回答里可以并行调用多个只读工具（Read/Glob/Grep/WebSearch/WebFetch），写工具（Edit/Write/Bash）请逐个执行。
+- 需要**用户拍板**时用 AskUserQuestion 提结构化选择题（最多 4 题、每题 2-4 选项；第一个选项放你的推荐并在 label 末尾标「(推荐)」）：
+  ① 需求/方案有取舍、没有绝对对错（多个合理方案各有利弊）→ 让用户选；② 关键信息缺失或模糊、继续做风险大 → 让用户补充。
+  能自己从代码/上下文/常识判断出答案的别问（免打断）；界面会自动附「其他(自由输入)」逃生项，无需你手动加。
 
 # 技能系统（积极使用）
 ${skillHint}
@@ -126,7 +129,7 @@ ${skillHint}
 
 # 行为约束
 - 没有用户许可不要执行破坏性操作（rm -rf / git reset --hard / git push --force 等）。
-- 如果用户的请求不清晰，先用一句话澄清再动手。
+- 如果用户的请求不清晰、或有多个合理方向需要取舍：优先用 AskUserQuestion 让用户拍板（带推荐项），而不是替他猜着干；只缺一点小信息时一句话澄清即可。
 - 任务完成后用一两句话总结改了什么，不要长篇大论。
 
 # 修改 vs 讨论（动手边界，重要）
@@ -168,7 +171,8 @@ export async function buildFullSystemPrompt(cwd, tools) {
             '- 以下内容来源于项目根目录的 `minimal-agent.md` 文件，具有时效性，可能已过时。',
             '- 它是参考线索，不是绝对真理。当它与实际代码或文件内容冲突时，以代码为准。',
             '- 涉及代码和项目文件的任何操作前，必须先用 Read / Grep 工具确认当前代码的实际状态，再基于最新信息做决策，不要仅凭此文档的描述操作。',
-            '- 如果你发现 `minimal-agent.md` 的描述与当前代码不一致，应主动用 Write 工具更新 `minimal-agent.md` 使其与代码保持同步。',
+            '- 同步规则：仅当你在**本轮任务中实际用 Write/Edit/MultiEdit 改动了代码或项目结构**、且这些改动使 `minimal-agent.md` 某处描述过时时，才在本轮结束的总结里用一句话**指出过时的具体位置**（哪一节 / 哪条），并询问用户是否要同步、或建议运行 `/init` 重建。',
+            '- 除非用户已明确授权，**不要擅自 Write 改写 `minimal-agent.md`**（它通常已纳入 git，盲目重写会污染 diff；任务进行中代码尚未定型，过早同步会把暂态写进文档、反而加重误导）。纯讨论 / 只读 / 搜索类的轮次不做任何同步动作。',
             '',
             projectInstructions,
         ].join('\n');

package/src/tools/ask/ask.js

@@ -0,0 +1,89 @@
+/**
+ * ============================================================
+ *  src/tools/ask/ask.ts —— AskUserQuestion 工具（向用户提结构化选择题）
+ * ------------------------------------------------------------
+ *  对齐上游 Claude Code 的 AskUserQuestion：让模型在「需要用户拍板」时停下来问，
+ *  而不是替用户瞎猜。它本身只是一个普通工具 —— call() 调 askBridge 的
+ *  requestUserChoice()，TUI 弹选择界面、用户选完把答案当 tool_result 喂回模型。
+ *  「等用户」= 这个工具返回得慢；非交互宿主（-p/gateway）自动选推荐项（见 askBridge）。
+ *
+ *  这一个工具同时让主循环 / workflow（tool: AskUserQuestion）/ agent: 节点
+ *  都获得「问用户」的能力 —— 动态工作流的交互底座。
+ * ============================================================
+ */
+import { z } from 'zod';
+import { requestUserChoice } from '../../askBridge.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+// ---------------- 1. Zod 输入 schema ----------------
+const optionSchema = z.object({
+    label: z
+        .string()
+        .min(1)
+        .describe('选项显示文本（简洁）；把推荐项放第一个，并在其 label 末尾标「(推荐)」'),
+    description: z
+        .string()
+        .optional()
+        .describe('该选项的说明 / 取舍，帮用户理解后果'),
+});
+const questionSchema = z.object({
+    question: z.string().min(1).describe('要问用户的完整问题'),
+    header: z
+        .string()
+        .min(1)
+        .describe('问题的短标签（≤12 字），如「交互底座」「鉴权方式」'),
+    multiSelect: z
+        .boolean()
+        .optional()
+        .describe('是否允许多选；默认 false（单选）'),
+    options: z
+        .array(optionSchema)
+        .min(2)
+        .describe('2-4 个互斥选项；第一个应为你的推荐项'),
+});
+const inputSchema = z.object({
+    questions: z
+        .array(questionSchema)
+        .min(1)
+        .describe('1-4 个问题（通常 1 个；确需一次问多件事时才多个）'),
+});
+// ---------------- 2. JSON Schema（由 Zod 自动派生） ----------------
+const parameters = toToolParameters(inputSchema);
+// ---------------- 3. Description（指导模型何时/如何用） ----------------
+const description = `向用户提出结构化的选择题（最多 4 题，每题 2-4 个选项），用于需要用户做决定的场合。
+使用时机：
+- 需求 / 方案有取舍、没有绝对对错（多个合理方案各有利弊）→ 让用户拍板；
+- 关键信息缺失或模糊、继续做风险大 → 让用户补充。
+不要用于：你自己能从代码 / 上下文 / 常识判断出答案的问题（那样只会打断用户）。
+约定：每题第一个选项放你的推荐，并在其 label 末尾标「(推荐)」。
+界面会自动附带「其他（自由输入）」逃生项，**无需**你手动加。
+返回值是用户的选择文本，据此继续。`;
+// ---------------- 4. call() ----------------
+async function call(input, signal) {
+    try {
+        const answers = await requestUserChoice(input.questions, signal);
+        const lines = ['用户已回答 AskUserQuestion：', ''];
+        answers.forEach((a, i) => {
+            lines.push(`Q${i + 1} [${a.header}] ${a.question}`);
+            lines.push(`A${i + 1}: ${a.selected.join('、') || '(未选)'}`);
+            lines.push('');
+        });
+        return { ok: true, content: lines.join('\n').trimEnd() };
+    }
+    catch (e) {
+        // 用户 ESC / Ctrl+C 取消提问 → 当普通工具失败喂回（主循环让模型换思路；
+        // workflow tool 步骤则按 onError 处理）。
+        return { ok: false, error: `提问被取消 / 中断：${e.message}` };
+    }
+}
+// ---------------- 5. 导出 ----------------
+export const askUserQuestionTool = {
+    name: 'AskUserQuestion',
+    description,
+    inputSchema,
+    parameters,
+    isReadOnly: true,
+    isConcurrencySafe: false,
+    maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+    call,
+};

package/src/tools/index.js

@@ -12,6 +12,7 @@
  *  这层是"防线"：模型给的参数永远不可信，必须 Zod 校验后才进 call()。
  * ============================================================
  */
+import { askUserQuestionTool } from './ask/ask.js';
 import { bashTool } from './bash/bash.js';
 import { editTool } from './edit/edit.js';
 import { multiEditTool } from './edit/multi-edit.js';
@@ -34,6 +35,7 @@ export const ALL_TOOLS = [
     webfetchTool,
     webbrowserTool,
     bashTool,
+    askUserQuestionTool,
 ];
 /** 按名字查表 */
 export function getToolByName(name) {
@@ -90,5 +92,5 @@ export async function executeTool(name, rawArguments, signal) {
     }
 }
 // 导出每个工具，方便测试单独 import
-export { readTool, editTool, writeTool, globTool, grepTool, webSearchTool, webfetchTool, webbrowserTool, bashTool };
+export { readTool, editTool, writeTool, globTool, grepTool, webSearchTool, webfetchTool, webbrowserTool, bashTool, askUserQuestionTool };
 export { multiEditTool } from './edit/multi-edit.js';

package/src/ui/App.js

@@ -14,6 +14,7 @@ import { listArchives, restoreArchive } from '../context/archive.js';
 import { saveContext } from '../context/persistContext.js';
 import { sessionFileFor } from '../context/sessionPath.js';
 import { listSessions } from '../context/sessionRegistry.js';
+import { AskQuestion } from './AskQuestion.js';
 import { InputBox } from './InputBox.js';
 import { LiveArea } from './LiveArea.js';
 import { MessageList } from './MessageList.js';
@@ -160,6 +161,18 @@ export function App({ provider, initialHistory }) {
             chat.ephemeralLine(`[tool result · #${hit.tool_call_id.slice(-8)} · 完整 ${hit.content.split('\n').length} 行]\n${hit.content}`);
             return;
         }
+        // /plan <目标> —— 便捷别名，等价 /workflow plan（跑 plan 工作流：
+        // 调研 → AskUserQuestion 选择 → 产出 ./PLAN.md）。改写后透传给 pluginRunner。
+        // 目标里的引号剥掉，避免破坏 workflow 参数 tokenizer（"..." 整体当一个位置参数）。
+        if (text.startsWith('/plan ') || text.trim() === '/plan') {
+            const goal = text.slice('/plan'.length).trim().replace(/"/g, '');
+            if (goal.length === 0) {
+                chat.ephemeralLine('[/plan] 用法：/plan <目标>（= /workflow plan：调研→提问选择→产出 ./PLAN.md）');
+                return;
+            }
+            void chat.submit(`/workflow plan "${goal}"`);
+            return;
+        }
         // 非命令 → 走正常 LLM 流程
         void chat.submit(text);
     }, 
@@ -177,5 +190,7 @@ export function App({ provider, initialHistory }) {
     // 它必须是兄弟节点中第一个，否则 above-sibling 会跟 Static commit 一起被重打
     // 到 stdout（实测看到 banner 反复打印 N 次）。
     const bannerText = `minimal-agent  · ${provider.name}/${provider.model} · /new 清空 · /compact 压缩 · /exit 退出 · Ctrl+C 中断`;
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(MessageList, { history: deferredHistory, compactGeneration: chat.compactGeneration, bannerText: bannerText, terminalRows: terminalRows }), _jsxs(Box, { flexDirection: "column", width: Math.max(1, terminalCols - 1), children: [_jsx(LiveArea, { progressStage: chat.progressStage, reasoningPreview: chat.reasoningPreview, streamingText: chat.streamingText, runningTools: chat.runningTools, pluginProgress: chat.pluginProgress, terminalCols: terminalCols, terminalRows: terminalRows }), chat.error && (_jsx(Box, { marginBottom: 1, children: _jsxs(Text, { color: "red", children: ["\u26A0 ", chat.error] }) })), chat.interrupted && (_jsx(Box, { marginBottom: 1, children: _jsx(Text, { color: "yellow", children: "\u26A1 \u64CD\u4F5C\u88AB\u7528\u6237\u4E2D\u65AD\uFF0C\u7B49\u5F85\u65B0\u7684\u4EFB\u52A1\u8F93\u5165..." }) })), _jsx(InputBox, { onSubmit: handleSubmit, disabled: chat.isLoading, onAbort: chat.abort, onClear: handleClear, onCompact: chat.compactNow }), _jsx(StatusLine, { provider: provider, history: chat.history, pluginProgress: chat.pluginProgress })] })] }));
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(MessageList, { history: deferredHistory, compactGeneration: chat.compactGeneration, bannerText: bannerText, terminalRows: terminalRows }), _jsxs(Box, { flexDirection: "column", width: Math.max(1, terminalCols - 1), children: [_jsx(LiveArea, { progressStage: chat.progressStage, reasoningPreview: chat.reasoningPreview, streamingText: chat.streamingText, runningTools: chat.runningTools, pluginProgress: chat.pluginProgress, terminalCols: terminalCols, terminalRows: terminalRows }), chat.error && (_jsx(Box, { marginBottom: 1, children: _jsxs(Text, { color: "red", children: ["\u26A0 ", chat.error] }) })), chat.interrupted && (_jsx(Box, { marginBottom: 1, children: _jsx(Text, { color: "yellow", children: "\u26A1 \u64CD\u4F5C\u88AB\u7528\u6237\u4E2D\u65AD\uFF0C\u7B49\u5F85\u65B0\u7684\u4EFB\u52A1\u8F93\u5165..." }) })), chat.pendingAsk ? (_jsx(AskQuestion, { questions: chat.pendingAsk, onAnswer: chat.answerAsk, onCancel: chat.abort })) : (
+                    /* handleSubmit 包装做 slash 命令拦截，非命令透传 chat.submit */
+                    _jsx(InputBox, { onSubmit: handleSubmit, disabled: chat.isLoading, onAbort: chat.abort, onClear: handleClear, onCompact: chat.compactNow })), _jsx(StatusLine, { provider: provider, history: chat.history, pluginProgress: chat.pluginProgress })] })] }));
 }

package/src/ui/AskQuestion.js

@@ -0,0 +1,177 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * ============================================================
+ *  src/ui/AskQuestion.tsx —— AskUserQuestion 工具的 TUI 问答界面
+ * ------------------------------------------------------------
+ *  这是 AskUserQuestion 工具向用户提问时弹出的选择题界面。由 askBridge 的
+ *  AskHandler（在 useChat mount 时通过 setAskHandler 注册）触发：handler 把
+ *  问题数组存进 pendingAsk state，App 看到 pendingAsk 存在便渲染本组件，
+ *  并让它**独占输入焦点**（屏蔽 InputBox），用户答完后 handler 的 Promise
+ *  以 AskAnswer[] resolve、继续工具回路；ESC/Ctrl+C 取消则 reject。
+ *
+ *  逐题进行：从第 0 题问到最后一题，每题答完推进，末题答完一次性回调 onAnswer。
+ *  每题选项列表末尾自动追加一个「✏️ 其他（自由输入）」伪选项，命中即切到文本
+ *  输入子模式，让用户填选项之外的答案（自由输入按单值处理，覆盖多选集合）。
+ *
+ *  Ink 用法与风格对齐 cli/configWizard.tsx：useInput 手写键位、↑↓ 取模移动
+ *  高亮、`> ` 前缀 + cyan 高亮、gray 操作提示、文本输入用累积 draft + backspace。
+ * ============================================================
+ */
+import { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+/** description 过长截断到此长度，防止 live 区被超长文本撑爆。 */
+const DESC_MAX = 80;
+function clampDesc(s) {
+    return s.length > DESC_MAX ? `${s.slice(0, DESC_MAX - 1)}…` : s;
+}
+export function AskQuestion({ questions, onAnswer, onCancel, }) {
+    // 当前进行到第几题
+    const [questionIndex, setQuestionIndex] = useState(0);
+    // 当前题高亮的选项下标（含末尾「其他」伪选项）
+    const [idx, setIdx] = useState(0);
+    // 多选时已选中的真实 option 下标集合
+    const [picked, setPicked] = useState(new Set());
+    // 已累积的答案
+    const [answers, setAnswers] = useState([]);
+    // 是否处于「其他（自由输入）」文本子模式
+    const [textMode, setTextMode] = useState(false);
+    // 文本子模式的累积草稿
+    const [draft, setDraft] = useState('');
+    const current = questions[questionIndex];
+    const multi = current?.multiSelect === true;
+    const options = current?.options ?? [];
+    // 末尾「其他」伪选项占据下标 options.length，故列表总长 = options.length + 1
+    const otherIndex = options.length;
+    const listLength = options.length + 1;
+    /** 切到下一题，重置所有逐题状态；若已是末题则一次性回调 onAnswer。 */
+    function advance(answer) {
+        const nextAnswers = [...answers, answer];
+        const nextQ = questionIndex + 1;
+        if (nextQ >= questions.length) {
+            onAnswer(nextAnswers);
+            return;
+        }
+        setAnswers(nextAnswers);
+        setQuestionIndex(nextQ);
+        setIdx(0);
+        setPicked(new Set());
+        setTextMode(false);
+        setDraft('');
+    }
+    useInput((input, key) => {
+        // 没有当前题（理论不会发生）→ 直接当作取消
+        if (!current) {
+            onCancel();
+            return;
+        }
+        // ---- 文本子模式：自由输入 ----
+        if (textMode) {
+            if (key.escape) {
+                // 退回选项列表（不取消整轮）
+                setTextMode(false);
+                setDraft('');
+                return;
+            }
+            if (key.return) {
+                const text = draft.trim();
+                if (text.length === 0)
+                    return;
+                // 自由输入按单值处理，覆盖多选集合
+                advance({
+                    header: current.header,
+                    question: current.question,
+                    selected: [text],
+                });
+                return;
+            }
+            if (key.backspace || key.delete) {
+                setDraft((s) => s.slice(0, -1));
+                return;
+            }
+            if (input && !key.meta && !key.ctrl) {
+                setDraft((s) => s + input);
+            }
+            return;
+        }
+        // ---- 选项列表模式 ----
+        if (key.escape || (key.ctrl && input === 'c')) {
+            onCancel();
+            return;
+        }
+        if (key.upArrow) {
+            setIdx((i) => (i - 1 + listLength) % listLength);
+            return;
+        }
+        if (key.downArrow) {
+            setIdx((i) => (i + 1) % listLength);
+            return;
+        }
+        // 高亮落在「其他」伪选项：Enter（单选/多选都）进入文本子模式
+        const onOther = idx === otherIndex;
+        if (multi) {
+            // 多选：空格 toggle；Enter 确认本题
+            if (input === ' ') {
+                if (onOther) {
+                    // 「其他」上按空格 → 进入自由输入
+                    setTextMode(true);
+                    setDraft('');
+                    return;
+                }
+                setPicked((prev) => {
+                    const next = new Set(prev);
+                    if (next.has(idx))
+                        next.delete(idx);
+                    else
+                        next.add(idx);
+                    return next;
+                });
+                return;
+            }
+            if (key.return) {
+                if (onOther) {
+                    setTextMode(true);
+                    setDraft('');
+                    return;
+                }
+                const selected = options
+                    .map((o, i) => (picked.has(i) ? o.label : null))
+                    .filter((l) => l !== null);
+                advance({
+                    header: current.header,
+                    question: current.question,
+                    selected,
+                });
+                return;
+            }
+            return;
+        }
+        // 单选：Enter 选中当前高亮项
+        if (key.return) {
+            if (onOther) {
+                setTextMode(true);
+                setDraft('');
+                return;
+            }
+            const opt = options[idx];
+            if (!opt)
+                return;
+            advance({
+                header: current.header,
+                question: current.question,
+                selected: [opt.label],
+            });
+        }
+    });
+    // 无题可问（空数组）→ 渲染占位（useInput 已处理取消，这里只防御渲染崩）
+    if (!current) {
+        return (_jsx(Box, { paddingX: 1, children: _jsx(Text, { color: "gray", children: "\uFF08\u65E0\u95EE\u9898\uFF09" }) }));
+    }
+    const progress = `提问 (${questionIndex + 1}/${questions.length}) · ${current.header}`;
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { color: "cyan", bold: true, children: progress }) }), _jsx(Box, { marginBottom: 1, children: _jsx(Text, { children: current.question }) }), textMode ? (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "gray", children: "\u270F\uFE0F \u81EA\u7531\u8F93\u5165\uFF1A" }), _jsx(Box, { marginTop: 1, borderStyle: "round", borderColor: "cyan", paddingX: 1, children: _jsx(Text, { children: draft || ' ' }) }), _jsx(Text, { color: "gray", children: "\u8F93\u5165\u540E Enter \u63D0\u4EA4 \u00B7 ESC \u8FD4\u56DE" })] })) : (_jsxs(Box, { flexDirection: "column", children: [options.map((opt, i) => {
+                        const active = i === idx;
+                        const box = multi ? (picked.has(i) ? '[x] ' : '[ ] ') : '';
+                        return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { color: active ? 'cyan' : undefined, children: [active ? '> ' : '  ', box, opt.label] }), opt.description ? (_jsxs(Text, { color: "gray", children: ['      ', clampDesc(opt.description)] })) : null] }, `${i}-${opt.label}`));
+                    }), _jsxs(Text, { color: idx === otherIndex ? 'cyan' : undefined, children: [idx === otherIndex ? '> ' : '  ', multi ? '    ' : '', "\u270F\uFE0F \u5176\u4ED6\uFF08\u81EA\u7531\u8F93\u5165\uFF09"] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: multi
+                                ? '↑↓ 移动 · 空格 多选 · Enter 确认本题 · ESC 取消'
+                                : '↑↓ 选择 · Enter 确认 · ESC 取消' }) })] }))] }));
+}

package/src/ui/hooks/useChat.js

@@ -23,6 +23,7 @@ import { getActiveSession, setActiveSession, } from '../../context/sessionRegist
 import { resolveSessionFile, sessionFileFor, } from '../../context/sessionPath.js';
 import { buildFullSystemPrompt } from '../../prompts/system.js';
 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';
 /**
@@ -123,6 +124,12 @@ export function useChat(args) {
     const [runningToolsMap, setRunningToolsMap] = useState(new Map());
     const runningTools = useMemo(() => Array.from(runningToolsMap.values()), [runningToolsMap]);
     const abortRef = useRef(null);
+    // ---- AskUserQuestion：执行中向用户提问 ----
+    // pendingAsk 非 null 时 App 渲染 <AskQuestion> 独占输入（不渲染 InputBox）。
+    // askResolverRef 持当前提问的 resolve/reject —— 用户答完 answerAsk 调 resolve，
+    // 让 askBridge.requestUserChoice 的 Promise 落定、工具 call() 返回、执行继续。
+    const [pendingAsk, setPendingAsk] = useState(null);
+    const askResolverRef = useRef(null);
     const streamingFlush = useThrottledFlush({
         delayMs: STREAM_FLUSH_MS,
         maxChars: STREAM_FLUSH_MAX_CHARS,
@@ -186,6 +193,38 @@ export function useChat(args) {
             abortRef.current?.abort();
         };
     }, []);
+    // mount 时把「弹选择界面」的处理器注册到 askBridge；unmount 注销。
+    // 工具 isConcurrencySafe:false + workflow 串行 → 同一时刻至多一个 pending，单槽即可。
+    // signal abort（用户 ESC / 中断）时 reject 并清掉 pending，让工具按「失败/取消」收尾。
+    useEffect(() => {
+        setAskHandler((questions, signal) => {
+            return new Promise((resolve, reject) => {
+                askResolverRef.current?.reject(new Error('被新的提问取代'));
+                askResolverRef.current = { resolve, reject };
+                setPendingAsk(questions);
+                const onAbort = () => {
+                    if (!askResolverRef.current)
+                        return;
+                    askResolverRef.current = null;
+                    setPendingAsk(null);
+                    reject(new Error('已被用户中断'));
+                };
+                if (signal?.aborted) {
+                    onAbort();
+                    return;
+                }
+                signal?.addEventListener('abort', onAbort, { once: true });
+            });
+        });
+        return () => setAskHandler(null);
+    }, []);
+    /** 用户答完当前提问：清 pending + resolve 工具侧 Promise，执行继续。 */
+    const answerAsk = useCallback((answers) => {
+        const r = askResolverRef.current;
+        askResolverRef.current = null;
+        setPendingAsk(null);
+        r?.resolve(answers);
+    }, []);
     // mount 时异步读 active session（默认 'default'，注册表里有就用注册值）。
     // 启动时初始 history 已经由 main.tsx/Root 走默认路径加载完了；
     // 如果注册表说 active 不是 default，理论上 main.tsx 应该按 active 加载——
@@ -470,6 +509,8 @@ export function useChat(args) {
         compactNow,
         switchSession,
         ephemeralLine,
+        pendingAsk,
+        answerAsk,
     };
 }
 export function handleEvent(ev, setters) {

package/workflows/plan.yaml

@@ -0,0 +1,90 @@
+# ============================================================
+#  workflows/plan.yaml —— 复刻 Claude Code「plan」流程的动态工作流
+# ------------------------------------------------------------
+#  旗舰演示 AskUserQuestion + 「受工作流指导的有界 TAOR」+ 人机交互：
+#    探索（agent 只读调研） → 澄清（直接用工具问用户，带推荐项）
+#      → 产出计划（agent 综合上下文落盘，遇取舍再回头问用户拍板） → 守门 assert。
+#
+#  与 adaptive-research 的区别：那条线演示「指导 + 随机应变」的旋钮，
+#  这条线把「交互（向用户提问）」也编进确定性骨架里 —— 既有 agent 节点的自主，
+#  又有 tool: AskUserQuestion 节点的「停下来问人」，二者共骑同一座 askBridge。
+#
+#  非交互宿主（-p / gateway / 子进程）下没有 UI handler，AskUserQuestion
+#  会自动选每题首项（约定=推荐项），整条流程照常跑完、绝不挂起。
+# ============================================================
+name: plan
+description: |
+  受工作流指导 + 可向用户提问 + 有界 TAOR 的动态计划流程。
+  - 先用有界子 agent 只读调研目标，梳理关键事实与未决点（不写盘、不副作用）；
+  - 再用 AskUserQuestion 直接问用户「计划要做到多详细」（带推荐项的单选）；
+  - 然后子 agent 综合调研与用户选择产出中文实现计划落到 ./PLAN.md，
+    遇到取舍 / 模糊点可再调 AskUserQuestion 让用户拍板；
+  - 最后 assert 守门，确认 PLAN.md 确实生成。
+  这是 minimal-agent 的旗舰演示：把「探索→澄清→（带推荐的）选择→产出计划」
+  编成确定性骨架，每个 agent 节点内是有界 TAOR，交互骑在 tool_call 回路上。
+version: "0.1"
+
+inputs:
+  - name: goal
+    type: string
+    required: true
+    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 末尾标「(推荐)」），非交互宿主会自动选它。
+  - id: clarify_depth
+    tool: AskUserQuestion
+    args:
+      questions:
+        - header: "计划深度"
+          question: "希望这份实现计划做到多详细？"
+          options:
+            - label: "详细分步 (推荐)"
+              description: "拆成可执行的有序步骤，每步说清动作、涉及文件与验收点"
+            - label: "快速概览"
+              description: "只给高层方向与关键决策，不展开到每一步"
+            - label: "带风险/回滚评估"
+              description: "在详细分步之外，额外标注每步风险与回滚方案"
+    capture:
+      content: depth_answer
+
+  # 3. 产出计划：agent 综合 findings + 用户选择落盘 ./PLAN.md，
+  #    遇取舍/模糊点可再调 AskUserQuestion 让用户拍板（带推荐项），写完用 Read 自检。
+  - id: draft_plan
+    agent: |
+      综合下面两份输入，为目标「${inputs.goal}」写一份中文实现计划，
+      用 Write 工具落到 ./PLAN.md（目录不存在就先创建）。
+
+      —— 调研结论（findings）——
+      ${findings}
+
+      —— 用户对计划深度的选择 ——
+      ${depth_answer}
+
+      要求：
+      - 计划详细程度遵循用户上面的选择；
+      - 若过程中遇到方案取舍或关键信息模糊、继续做风险大，调用 AskUserQuestion
+        让用户拍板（每题第一个选项放你的推荐并在 label 末尾标「(推荐)」），
+        据用户回答继续；
+      - 写完后用 Read 自检 ./PLAN.md 内容确实落好了再收尾。
+    allowed_tools: [Read, Grep, Glob, Write, AskUserQuestion]
+    capture:
+      content: plan_text
+
+  # 4. 守门：确认计划文件确实生成，否则给出中文排查提示
+  - id: verify
+    type: assert
+    condition: 'fileExists("./PLAN.md")'
+    onFail: "计划文件 ./PLAN.md 未生成，检查 draft_plan 步是否成功用 Write 落盘"