minimal-agent 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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/loader.js

@@ -124,6 +124,24 @@ function validate(obj, file) {
         }
     }
 }
+// ADR-05: 控制流 type 集合——这些节点的"动作"由 type 自身定义，
+// 因此不能附带 tool/skill/llm 也不能配 output_schema / context_files / allowed_tools。
+const CONTROL_FLOW_TYPES = new Set([
+    'assert',
+    'branch',
+    'loop',
+    'pause',
+    'parallel',
+    'vote',
+]);
+const VALID_STEP_TYPES = new Set([
+    'assert',
+    'branch',
+    'loop',
+    'pause',
+    'parallel',
+    'vote',
+]);
 function validateSteps(steps, file, pathPrefix) {
     const seenIds = new Set();
     for (const [i, item] of steps.entries()) {
@@ -140,6 +158,10 @@ function validateSteps(steps, file, pathPrefix) {
             throw new WorkflowLoadError(`${p}.id "${s.id}" 在当前 steps 列表中重复`, file);
         }
         seenIds.add(s.id);
+        // type 枚举校验（提前于动作互斥，给更准确的错误信息）
+        if (s.type !== undefined && (typeof s.type !== 'string' || !VALID_STEP_TYPES.has(s.type))) {
+            throw new WorkflowLoadError(`${p}.type "${String(s.type)}" 非法；合法值: ${[...VALID_STEP_TYPES].join(' / ')}`, file);
+        }
         // 动作字段恰好一个
         const actionFields = ['tool', 'skill', 'llm', 'type'];
         const present = actionFields.filter((k) => s[k] !== undefined);
@@ -179,5 +201,92 @@ function validateSteps(steps, file, pathPrefix) {
             if (Array.isArray(s.else))
                 validateSteps(s.else, file, `${p}.else`);
         }
+        // ---------------- ADR-05 新增校验 ----------------
+        // parallel：必须有非空 fork[]，递归校验子步骤
+        if (s.type === 'parallel') {
+            if (!Array.isArray(s.fork) || s.fork.length === 0) {
+                throw new WorkflowLoadError(`${p} type=parallel 必须有 fork: [...]（至少 1 个子步骤）`, file);
+            }
+            validateSteps(s.fork, file, `${p}.fork`);
+        }
+        else if (s.fork !== undefined) {
+            throw new WorkflowLoadError(`${p}.fork 只能用在 type=parallel 节点上`, file);
+        }
+        // vote：voters_count (2~10) / rules / input 必填；threshold 可选但越界要拦
+        if (s.type === 'vote') {
+            const vc = s.voters_count;
+            const rules = s.rules;
+            const input = s.input;
+            const missing = typeof vc !== 'number' ||
+                !Number.isInteger(vc) ||
+                vc < 2 ||
+                vc > 10 ||
+                typeof rules !== 'string' ||
+                rules.length === 0 ||
+                typeof input !== 'string' ||
+                input.length === 0;
+            if (missing) {
+                throw new WorkflowLoadError(`${p} type=vote 要求 voters_count (2~10), rules, input 三个字段`, file);
+            }
+            if (s.threshold !== undefined) {
+                const t = s.threshold;
+                if (typeof t !== 'number' ||
+                    !Number.isInteger(t) ||
+                    t < 1 ||
+                    t > vc) {
+                    throw new WorkflowLoadError(`${p} threshold=${String(t)} 超出范围；必须是 1 <= threshold <= voters_count(${vc})`, file);
+                }
+            }
+        }
+        else {
+            // 非 vote 节点不应携带 vote-only 字段
+            for (const k of ['voters_count', 'rules', 'threshold']) {
+                if (s[k] !== undefined) {
+                    throw new WorkflowLoadError(`${p}.${k} 只能用在 type=vote 节点上`, file);
+                }
+            }
+        }
+        // output_schema：必须是 object；不能用在控制流节点上
+        if (s.output_schema !== undefined) {
+            if (typeof s.output_schema !== 'object' ||
+                s.output_schema === null ||
+                Array.isArray(s.output_schema)) {
+                throw new WorkflowLoadError(`${p}.output_schema 必须是对象`, file);
+            }
+            if (typeof s.type === 'string' && CONTROL_FLOW_TYPES.has(s.type)) {
+                throw new WorkflowLoadError(`${p}.output_schema 不能用在 type=${s.type} 控制流节点上`, file);
+            }
+        }
+        // context_files：[{ path, hint? }]；不能用在控制流节点上
+        if (s.context_files !== undefined) {
+            if (!Array.isArray(s.context_files)) {
+                throw new WorkflowLoadError(`${p}.context_files 必须是数组`, file);
+            }
+            for (const [j, cf] of s.context_files.entries()) {
+                if (!cf || typeof cf !== 'object' || Array.isArray(cf)) {
+                    throw new WorkflowLoadError(`${p}.context_files[${j}] 必须是 { path: string, hint?: string } 对象`, file);
+                }
+                const r = cf;
+                if (typeof r.path !== 'string' || r.path.length === 0) {
+                    throw new WorkflowLoadError(`${p}.context_files[${j}].path 必填（非空 string）`, file);
+                }
+                if (r.hint !== undefined && typeof r.hint !== 'string') {
+                    throw new WorkflowLoadError(`${p}.context_files[${j}].hint 必须是 string`, file);
+                }
+            }
+            if (typeof s.type === 'string' && CONTROL_FLOW_TYPES.has(s.type)) {
+                throw new WorkflowLoadError(`${p}.context_files 不能用在 type=${s.type} 控制流节点上`, file);
+            }
+        }
+        // allowed_tools：string[]；不能用在控制流节点上
+        if (s.allowed_tools !== undefined) {
+            if (!Array.isArray(s.allowed_tools) ||
+                !s.allowed_tools.every((x) => typeof x === 'string' && x.length > 0)) {
+                throw new WorkflowLoadError(`${p}.allowed_tools 必须是非空 string 数组`, file);
+            }
+            if (typeof s.type === 'string' && CONTROL_FLOW_TYPES.has(s.type)) {
+                throw new WorkflowLoadError(`${p}.allowed_tools 不能用在 type=${s.type} 控制流节点上`, file);
+            }
+        }
     }
 }

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

@@ -0,0 +1,155 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/src/miniReAct.ts —— 简化版 ReAct 子循环
+ * ------------------------------------------------------------
+ *  ADR-05 阶段 4：当 llm step 声明 context_files 时，execLlmStep 会调本子循环
+ *  代替单轮 chat()。本循环只做最纯净的 ReAct：调 LLM → 执行 tool_call → 喂回
+ *  → 再调 → 直到模型不再调工具或达到 maxTurns。
+ *
+ *  为什么不复用 src/loop.ts::runQuery？
+ *    - runQuery 依赖太重：history 持久化、自动压缩、反应式压缩自救、
+ *      microCompact、reasoning 累积、sessionState 注入、SIGINT 标记消息等
+ *    - workflow 子步骤是"短小内嵌"，不需要这些工程化保障
+ *    - 独立实现可以精准控制：只用白名单工具、强 schema、重复调用 halt
+ *
+ *  关键决策：
+ *    1. **每轮都传 responseFormat**（如果有 output_schema）。OpenAI 兼容
+ *       provider 对 tool_calls + json_schema 混用通常允许：tool_calls 走 function
+ *       协议，最终 assistant 的 text 是 JSON。这样比"双轮探测"简单可靠。
+ *    2. **重复工具调用检测**：同 name 同 args 出现 3 次直接 halt，避免模型卡死。
+ *    3. **executeTool 自带 Zod 校验和错误包装**，本循环只需透传 tool_call_id 配对。
+ *    4. **maxTurns 默认 10**（vs runQuery 的 50），workflow 子步骤天生该收敛快。
+ * ============================================================
+ */
+import { chat, executeTool, } from '../../../src/plugin-sdk.js';
+/**
+ * 执行一次 ReAct 子循环。返回最终 StepResult（与 execLlmStep 老路径形状一致）。
+ *
+ * 抛错场景：
+ *   - 用户中断（signal.aborted）
+ *   - 重复工具调用 >= 3 次
+ *   - 用尽 maxTurns 仍未收敛
+ *   - output_schema 解析失败 / 非对象
+ */
+export async function runMiniReAct(args) {
+    const { messages, tools, output_schema, provider, signal } = args;
+    const maxTurns = args.maxTurns ?? 10;
+    // 工作消息列表：拷贝一份，避免污染调用方
+    const conv = [...messages];
+    let finalText = '';
+    /** 上一轮是否仍有 tool_calls（用于检测 "用尽轮数还在调工具" 这一退出态） */
+    let lastTurnHadToolCalls = false;
+    /** 重复工具调用计数：key = `${name}:${arguments}` */
+    const toolCallSignature = new Map();
+    const responseFormat = output_schema
+        ? {
+            type: 'json_schema',
+            json_schema: {
+                name: 'minireact_output',
+                schema: output_schema,
+                strict: true,
+            },
+        }
+        : undefined;
+    for (let turn = 0; turn < maxTurns; turn++) {
+        if (signal?.aborted)
+            throw new Error('用户中断');
+        // ---- 1. 调 LLM 并累积流式响应 ----
+        let textAccum = '';
+        const toolCallsAccum = [];
+        for await (const ev of chat({
+            provider,
+            messages: conv,
+            tools,
+            responseFormat,
+            signal,
+        })) {
+            if (ev.type === 'text_delta') {
+                textAccum += ev.delta;
+            }
+            else if (ev.type === 'tool_call_delta') {
+                mergeToolCallDelta(toolCallsAccum, ev);
+            }
+            else if (ev.type === 'done' && ev.stopReason === 'aborted') {
+                throw new Error('用户中断');
+            }
+            // reasoning_delta / 其它事件忽略
+        }
+        // ---- 2. 把 assistant 消息推入 conv ----
+        conv.push({
+            role: 'assistant',
+            content: textAccum.length > 0 ? textAccum : null,
+            ...(toolCallsAccum.length > 0 ? { tool_calls: toolCallsAccum } : {}),
+        });
+        // ---- 3. 无 tool_calls → 结束循环 ----
+        if (toolCallsAccum.length === 0) {
+            finalText = textAccum.trim();
+            lastTurnHadToolCalls = false;
+            break;
+        }
+        lastTurnHadToolCalls = true;
+        // ---- 4. 执行所有 tool_calls，结果回填为 tool 消息 ----
+        for (const tc of toolCallsAccum) {
+            // 重复检测
+            const sig = `${tc.function.name}:${tc.function.arguments}`;
+            const count = (toolCallSignature.get(sig) ?? 0) + 1;
+            toolCallSignature.set(sig, count);
+            if (count >= 3) {
+                throw new Error(`miniReAct: 检测到重复工具调用（${tc.function.name} 同参数已 ${count} 次），可能陷入循环，halt。`);
+            }
+            if (signal?.aborted)
+                throw new Error('用户中断');
+            const result = await executeTool(tc.function.name, tc.function.arguments, signal);
+            conv.push({
+                role: 'tool',
+                tool_call_id: tc.id,
+                content: result.ok ? result.content : `工具错误: ${result.error}`,
+            });
+        }
+        // 继续下一轮
+    }
+    // 用尽 maxTurns 且最后一轮仍有 tool_calls
+    if (lastTurnHadToolCalls) {
+        throw new Error(`miniReAct: 用尽 ${maxTurns} 轮未得到最终回答（仍在调工具）`);
+    }
+    // ---- 5. 输出处理 ----
+    if (output_schema) {
+        let parsed;
+        try {
+            parsed = JSON.parse(finalText);
+        }
+        catch (e) {
+            throw new Error(`miniReAct: output_schema 要求 JSON 但解析失败: ${e.message}\n收到: ${finalText.slice(0, 200)}`);
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error(`miniReAct: output_schema 要求对象，得到 ${Array.isArray(parsed) ? 'array' : typeof parsed}`);
+        }
+        return {
+            raw: parsed,
+            preview: `[json+tools] ${finalText.slice(0, 180)}${finalText.length > 180 ? '...' : ''}`,
+        };
+    }
+    return {
+        raw: { text: finalText, result: finalText },
+        preview: finalText.length > 200 ? `${finalText.slice(0, 200)}...` : finalText,
+    };
+}
+// ---------------- 辅助 ----------------
+/** 把一条 tool_call_delta 合并到累积数组上（与 src/loop.ts mergeToolCallDelta 同语义） */
+function mergeToolCallDelta(acc, ev) {
+    let slot = acc[ev.index];
+    if (!slot) {
+        slot = {
+            id: '',
+            type: 'function',
+            function: { name: '', arguments: '' },
+        };
+        acc[ev.index] = slot;
+    }
+    if (ev.id)
+        slot.id = ev.id;
+    if (ev.name)
+        slot.function.name += ev.name;
+    if (ev.argumentsDelta)
+        slot.function.arguments += ev.argumentsDelta;
+}

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

@@ -26,6 +26,7 @@ import { execLlmStep } from './stepExecutors/llm.js';
 import { execSkillStep } from './stepExecutors/skill.js';
 import { execToolStep } from './stepExecutors/tool.js';
 import { VarStack } from './types.js';
+import { runVoter } from './voteHelpers.js';
 import { WorkflowState } from './workflowState.js';
 function stepKind(step) {
     if (step.type)
@@ -220,6 +221,135 @@ async function* runSteps(steps, vars, ctx, state) {
             };
             continue;
         }
+        // ---------- 控制流：parallel ----------
+        //
+        // 每个 fork 独立 VarStack 副本 + 独立事件缓冲；Promise.all 并发执行。
+        // 子 fork 的事件先收进 buffer，再按 fork 顺序一次性 yield，保 UI
+        // 时间轴可读（并发 yield 会导致 UI 拿到乱序事件）。
+        // 任一 fork halt → 整个 parallel halt。
+        if (step.type === 'parallel') {
+            const forks = step.fork ?? [];
+            const results = await Promise.all(forks.map(async (forkStep) => {
+                const forkVars = vars.fork();
+                const events = [];
+                let halted = false;
+                try {
+                    halted = await collectStepsToBuffer([forkStep], forkVars, ctx, state, events);
+                }
+                catch (e) {
+                    halted = true;
+                    events.push({
+                        type: 'error',
+                        error: `fork ${forkStep.id} 抛异常: ${e.message}`,
+                    });
+                }
+                return {
+                    id: forkStep.id,
+                    events,
+                    vars: forkVars.snapshot(),
+                    halted,
+                };
+            }));
+            // 顺序 yield 所有 fork 事件
+            for (const r of results) {
+                for (const ev of r.events)
+                    yield ev;
+            }
+            if (results.some((r) => r.halted)) {
+                await state.appendProgress(`✗ ${step.id}: parallel: 至少一个 fork 失败`);
+                yield {
+                    type: 'workflow_step_end',
+                    id: step.id,
+                    ok: false,
+                    error: 'parallel: 至少一个 fork 失败',
+                };
+                yield {
+                    type: 'error',
+                    error: `Workflow halted at step "${step.id}": parallel: 至少一个 fork 失败`,
+                };
+                return true;
+            }
+            // 聚合：raw.fork 是 [{ id, vars }, ...]，capture 可走 fork.0.vars.xxx 这种点路径
+            const aggResult = {
+                raw: { fork: results.map((r) => ({ id: r.id, vars: r.vars })) },
+                preview: `parallel: ${results.length} forks done`,
+            };
+            if (step.capture)
+                bindCapture(step.capture, aggResult, vars);
+            await state.appendProgress(`✓ ${step.id} (parallel ×${results.length})`);
+            await state.writeVars(vars.snapshot());
+            yield {
+                type: 'workflow_step_end',
+                id: step.id,
+                ok: true,
+                output: aggResult.preview,
+            };
+            continue;
+        }
+        // ---------- 控制流：vote ----------
+        //
+        // 对每个 input 数组项跑 N 个 voter（同 prompt + refuted: boolean），
+        // refuted 票数 >= threshold 则视为驳回（item 不进 survived）。
+        // 心理学定位：voter 倾向于 refuted=true（找漏洞），所以阈值算"驳回票数"。
+        if (step.type === 'vote') {
+            const voters_count = step.voters_count ?? 3;
+            const threshold = step.threshold ?? Math.ceil(voters_count / 2);
+            let inputArr;
+            try {
+                inputArr = evalExpr(interpolate(step.input ?? '[]', vars), vars);
+            }
+            catch (e) {
+                const errMsg = `vote.input 求值失败: ${e.message}`;
+                await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
+                yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
+                yield {
+                    type: 'error',
+                    error: `Workflow halted at step "${step.id}": ${errMsg}`,
+                };
+                return true;
+            }
+            if (!Array.isArray(inputArr)) {
+                const errMsg = `vote.input 必须求值为数组，得到 ${typeof inputArr}`;
+                await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
+                yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
+                yield {
+                    type: 'error',
+                    error: `Workflow halted at step "${step.id}": ${errMsg}`,
+                };
+                return true;
+            }
+            const survived = [];
+            for (const item of inputArr) {
+                if (ctx.signal?.aborted) {
+                    yield { type: 'interrupted' };
+                    return true;
+                }
+                const verdicts = await Promise.all(Array.from({ length: voters_count }, () => runVoter(step.rules ?? '', item, vars, ctx)));
+                const refutedCount = verdicts.filter((v) => v.refuted === true).length;
+                if (refutedCount < threshold) {
+                    survived.push(item);
+                }
+            }
+            const voteResult = {
+                raw: {
+                    survived,
+                    total: inputArr.length,
+                    kept: survived.length,
+                },
+                preview: `vote: ${survived.length}/${inputArr.length} survived (threshold=${threshold}/${voters_count})`,
+            };
+            if (step.capture)
+                bindCapture(step.capture, voteResult, vars);
+            await state.appendProgress(`✓ ${step.id} (vote ${survived.length}/${inputArr.length})`);
+            await state.writeVars(vars.snapshot());
+            yield {
+                type: 'workflow_step_end',
+                id: step.id,
+                ok: true,
+                output: voteResult.preview,
+            };
+            continue;
+        }
         // ---------- 普通动作 step：tool / llm / skill / assert ----------
         try {
             const result = yield* dispatchActionStep(step, vars, ctx);
@@ -288,3 +418,17 @@ export async function* runWorkflow(def, inputs, ctx) {
         await state.cleanup();
     }
 }
+/**
+ * parallel fork 用：把 runSteps 的 yield 流收集到 buffer 数组，
+ * 让外层 Promise.all 拿到完整事件后再顺序 yield。
+ *
+ * 注：for-await 无法读取 generator 的 return value（JS 限制），
+ * 所以"是否 halted"靠"buffer 里有 error event"近似判断 —— 这符合
+ * runSteps 的语义（halt 一定会 yield error / interrupted）。
+ */
+async function collectStepsToBuffer(steps, vars, ctx, state, buffer) {
+    for await (const ev of runSteps(steps, vars, ctx, state)) {
+        buffer.push(ev);
+    }
+    return buffer.some((ev) => ev.type === 'error' || ev.type === 'interrupted');
+}

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

@@ -8,26 +8,84 @@
  *    - 流式累积文本（reasoning 字段在这里忽略；只关心最终文本）
  *
  *  capture：
- *    - `{ text: var_name }` 绑生成文本
+ *    - `{ text: var_name }` 绑生成文本（无 output_schema 时）
  *    - `{ result: var_name }` 同义
+ *    - `{ <field>: var_name }` 当 output_schema 命中时按 raw 上的字段名取
+ *
+ *  ADR-05: 当 step.output_schema 存在 → 走 provider-native structured output：
+ *    - 通过 chat() 的 responseFormat 参数下发 JSON Schema
+ *    - 收到的文本必须解析为 JSON 对象，整对象作为 raw 暴露给 capture
+ *    - system prompt 切换为严格 JSON 模式，禁止 markdown 代码块包裹
  * ============================================================
  */
-import { chat } from '../../../../src/plugin-sdk.js';
+import { ALL_TOOLS, chat } from '../../../../src/plugin-sdk.js';
 import { interpolate } from '../expressions.js';
-const LLM_STEP_SYSTEM = '你正在被一个 workflow 调用。只输出本步骤要求的内容本身，不要寒暄、不要列要求复述、不要工具调用语法。';
+import { runMiniReAct } from '../miniReAct.js';
+const LLM_STEP_SYSTEM_PLAIN = '你正在被一个 workflow 调用。只输出本步骤要求的内容本身，不要寒暄、不要列要求复述、不要工具调用语法。';
+const LLM_STEP_SYSTEM_SCHEMA = `你正在被一个 workflow 调用。
+要求：
+1. 严格按指定 JSON Schema 输出有效 JSON，**不要 markdown 代码块包裹**（不要 \`\`\`json 也不要 \`\`\`）
+2. 不要寒暄、不要解释、不要额外字段
+3. 字段缺失或类型不符会导致 workflow 失败
+4. 字符串内特殊字符必须正确转义（双引号 \\", 反斜杠 \\\\, 换行 \\n）`;
+const LLM_STEP_SYSTEM_WITH_TOOLS = `你正在被一个 workflow 调用。你被授予了有限的工具（通常是 Read）以查询提供的上下文文件。
+
+工作流程：
+1. 先用 Read 工具读取你需要的文件（按需读取，**不要全部读完再思考**——大文件分段读、按 hint 选读）
+2. 基于读到的内容生成最终回答
+3. 不要寒暄、不要复述要求、不要解释你的推理过程
+4. 完成后**不要**再调用工具，直接输出最终回答
+
+如果 workflow 要求结构化输出，请在最终回答里严格遵循 JSON Schema（无 markdown 代码块包裹）。`;
 export async function execLlmStep(step, vars, ctx) {
     if (typeof step.llm !== 'string')
         throw new Error(`step ${step.id}: 缺少 llm 字段`);
     const prompt = interpolate(step.llm, vars);
+    // ===== ADR-05 阶段 4: context_files → miniReAct 子循环 =====
+    if (step.context_files && step.context_files.length > 0) {
+        const fileList = step.context_files
+            .map((f) => `- ${interpolate(f.path, vars)}${f.hint ? ` — ${f.hint}` : ''}`)
+            .join('\n');
+        const augmented = `${prompt}\n\n**以下文件可用，请用 Read 工具按需读取**：\n${fileList}`;
+        const allowedNames = step.allowed_tools ?? ['Read'];
+        const allowedTools = ALL_TOOLS.filter((t) => allowedNames.includes(t.name));
+        if (allowedTools.length === 0) {
+            throw new Error(`step ${step.id}: context_files 启用但 allowed_tools=${JSON.stringify(allowedNames)} 没有匹配的可用工具`);
+        }
+        return await runMiniReAct({
+            messages: [
+                { role: 'system', content: LLM_STEP_SYSTEM_WITH_TOOLS },
+                { role: 'user', content: augmented },
+            ],
+            tools: allowedTools,
+            output_schema: step.output_schema,
+            provider: ctx.provider,
+            signal: ctx.signal,
+            maxTurns: step.maxTurns ?? 10,
+        });
+    }
+    // ===== END NEW =====
+    const useSchema = step.output_schema !== undefined;
     const messages = [
-        { role: 'system', content: LLM_STEP_SYSTEM },
+        { role: 'system', content: useSchema ? LLM_STEP_SYSTEM_SCHEMA : LLM_STEP_SYSTEM_PLAIN },
         { role: 'user', content: prompt },
     ];
+    const responseFormat = useSchema
+        ? {
+            type: 'json_schema',
+            json_schema: {
+                name: `${step.id}_output`,
+                schema: step.output_schema,
+                strict: true,
+            },
+        }
+        : undefined;
     let text = '';
     for await (const ev of chat({
         provider: ctx.provider,
         messages,
         tools: [],
+        responseFormat,
         signal: ctx.signal,
     })) {
         if (ev.type === 'text_delta')
@@ -37,6 +95,24 @@ export async function execLlmStep(step, vars, ctx) {
         }
     }
     const trimmed = text.trim();
+    if (useSchema) {
+        // strict structured output：解析 JSON 后整个对象作为 raw
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (e) {
+            throw new Error(`step ${step.id}: output_schema 要求 JSON 输出但解析失败: ${e.message}\n收到: ${trimmed.slice(0, 200)}`);
+        }
+        if (parsed === null || typeof parsed !== 'object') {
+            throw new Error(`step ${step.id}: output_schema 要求对象输出，得到 ${typeof parsed}: ${trimmed.slice(0, 100)}`);
+        }
+        return {
+            raw: parsed,
+            preview: `[json] ${trimmed.slice(0, 180)}${trimmed.length > 180 ? '...' : ''}`,
+        };
+    }
+    // 老路径：裸文本
     return {
         raw: { text: trimmed, result: trimmed },
         preview: trimmed.length > 200 ? `${trimmed.slice(0, 200)}...` : trimmed,

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

@@ -1,3 +1,4 @@
+// TODO ADR-05: output_schema 暂未在 skill 节点生效，仅 llm 节点支持；workflow 用 vote 时通过 runVoter 直接调 execLlmStep
 /**
  * ============================================================
  *  plugins/workflow-runner/src/stepExecutors/skill.ts —— skill step 执行

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

@@ -52,6 +52,12 @@ export class VarStack {
         if (this.frames.length > 1)
             this.frames.pop();
     }
+    /** ADR-05: parallel 用——给子 fork 一份深拷贝栈；子 fork 的 set/push/pop 不污染父栈。 */
+    fork() {
+        const child = new VarStack();
+        child.frames = this.frames.map((f) => ({ ...f }));
+        return child;
+    }
     /** 合并所有帧为一个普通对象（外层覆盖内层），用于 vars 持久化与事件 */
     snapshot() {
         return Object.assign({}, ...this.frames);

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

@@ -0,0 +1,104 @@
+/**
+ * ============================================================
+ *  voteHelpers.ts —— vote 节点的 voter 调用辅助
+ * ------------------------------------------------------------
+ *  对抗式审查：N 个 voter 跑同一 prompt + refuted: boolean 反向投票。
+ *  策略上倾向 refuted=true（找漏洞），所以阈值算的是"驳回票数"。
+ *  详见 ADR-05。
+ * ============================================================
+ */
+import { execLlmStep } from './stepExecutors/llm.js';
+/** voter 输出 schema（内置，不接受用户自定义） */
+export const VERDICT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['refuted', 'reasoning'],
+    properties: {
+        refuted: { type: 'boolean', description: '是否驳回此 finding' },
+        reasoning: { type: 'string', description: '核心论证（≤200 字）' },
+    },
+};
+export function buildVoterPrompt(rules, item) {
+    const itemStr = typeof item === 'string' ? item : JSON.stringify(item, null, 2);
+    return `你是一个对抗式审查者，你的核心任务是积极找出下面这个 finding 的逻辑漏洞、证据不足、或论证它是伪命题。
+
+**被审查的 finding**：
+${itemStr}
+
+**审查规则**：
+${rules}
+
+**重要心理学定位**：你应当倾向于 refuted=true。只在你**找不到任何合理的反驳角度**且这个 finding 论证扎实时，才输出 refuted=false。"老好人式赞同"是错误的。
+
+输出 JSON，refuted=true 表示你成功找到反驳理由，false 表示你认为它确实成立。reasoning 字段写明你的核心论证（≤200 字）。`;
+}
+/** 单个 voter 调用。包装 execLlmStep，强制 VERDICT_SCHEMA + 对抗式 prompt。
+ *  解析失败时默认 refuted=false（保守保留 item，避免 LLM 失误导致正确 finding 被误删）。 */
+export async function runVoter(rules, item, vars, ctx) {
+    const virtualStep = {
+        id: 'vote_voter', // 仅 ID，不影响事件流
+        llm: buildVoterPrompt(rules, item),
+        output_schema: VERDICT_SCHEMA,
+    };
+    try {
+        const result = await execLlmStep(virtualStep, vars, ctx);
+        const verdict = extractVerdict(result.raw);
+        if (verdict)
+            return verdict;
+        return { refuted: false, reasoning: '(voter 输出格式异常，保守保留)' };
+    }
+    catch (e) {
+        return {
+            refuted: false,
+            reasoning: `(voter 调用失败: ${e.message}，保守保留)`,
+        };
+    }
+}
+/**
+ * 从 execLlmStep 的 raw 提取 { refuted, reasoning }：
+ *   1. raw 直接含字段（B 改完 llm.ts 串通 output_schema 后的形态）
+ *   2. raw.text / raw.result 是 JSON 字符串，parse 后含字段（B 未改完时的 fallback）
+ *   3. raw.text / raw.result 含 ```json fenced block，剥壳后含字段
+ *   4. 其余 → null
+ */
+function extractVerdict(raw) {
+    if (typeof raw.refuted === 'boolean' &&
+        typeof raw.reasoning === 'string') {
+        return { refuted: raw.refuted, reasoning: raw.reasoning };
+    }
+    for (const k of ['text', 'result']) {
+        const v = raw[k];
+        if (typeof v !== 'string' || v.length === 0)
+            continue;
+        const parsed = tryParseJsonLike(v);
+        if (parsed &&
+            typeof parsed === 'object' &&
+            typeof parsed.refuted === 'boolean' &&
+            typeof parsed.reasoning === 'string') {
+            return {
+                refuted: parsed.refuted,
+                reasoning: parsed.reasoning,
+            };
+        }
+    }
+    return null;
+}
+function tryParseJsonLike(s) {
+    // 1. 直接 JSON
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        // 2. 剥 ```json ... ``` 围栏
+        const fence = s.match(/```(?:json)?\s*([\s\S]*?)```/);
+        if (fence) {
+            try {
+                return JSON.parse(fence[1].trim());
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+}

package/src/llm/client.js

@@ -34,7 +34,7 @@
  * ```
  */
 export async function* chat(args) {
-    const { provider, messages, tools, signal } = args;
+    const { provider, messages, tools, signal, responseFormat } = args;
     // 1. 把 Tool 数组转成 OpenAI 协议的 tools 字段
     const openaiTools = tools.map((t) => ({
         type: 'function',
@@ -52,6 +52,8 @@ export async function* chat(args) {
         stream: 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`;

package/src/tools/edit/edit.js

@@ -19,7 +19,7 @@ import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
 import { resolveToolPath, findActualString, preserveQuoteStyle, detectLineEndingsForString, applyLineEnding, countOccurrences, splitReplaceAll, } from '../shared/fileUtils.js';
 import { filePathField } from '../shared/schemas.js';
-import { assertFresh, recordRead } from '../shared/fileState.js';
+import { assertFresh, recordRead, wasTruncated } from '../shared/fileState.js';
 /** 编辑文件大小上限：1GB。防止模型试图 Edit 超大文件撑爆内存。 */
 const MAX_EDIT_FILE_SIZE_BYTES = 1024 * 1024 * 1024;
 // ---------------- 1. Zod 输入 schema ----------------
@@ -122,19 +122,22 @@ async function call(input) {
     }
     // splitCount = 出现次数
     const occurrences = countOccurrences(original, searchTarget);
+    const truncHint = wasTruncated(filePath)
+        ? `\n\n⚠️ 上次 Read 该文件时被截断了（只看到部分内容）。当前 old_string 可能在截断范围外。请用更小的 limit + offset 精确读取目标行号附近后再 Edit。`
+        : '';
     if (occurrences === 0) {
         // 模糊匹配提示：找找有没有"接近"的内容
         const hint = findFuzzyMatchHint(original, searchTarget);
         const extraMsg = hint ? `\n\n💡 提示：${hint}` : '';
         return {
             ok: false,
-            error: `在 ${filePath} 中找不到 old_string。请先用 Read 工具核对内容（注意空格/缩进/换行）。${extraMsg}`,
+            error: `在 ${filePath} 中找不到 old_string。请先用 Read 工具核对内容（注意空格/缩进/换行）。${extraMsg}${truncHint}`,
         };
     }
     if (occurrences > 1 && !replaceAll) {
         return {
             ok: false,
-            error: `old_string 在文件中出现了 ${occurrences} 次，不唯一。\n请扩大 old_string 包含更多上下文，或显式传 replace_all=true。`,
+            error: `old_string 在文件中出现了 ${occurrences} 次，不唯一。\n请扩大 old_string 包含更多上下文，或显式传 replace_all=true。${truncHint}`,
         };
     }
     const replaced = replaceAll

package/src/tools/edit/multi-edit.js

@@ -20,7 +20,7 @@ import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
 import { resolveToolPath, detectFileLineEndings, applyLineEnding, findActualString, preserveQuoteStyle, countOccurrences, splitReplaceAll, } from '../shared/fileUtils.js';
 import { filePathField } from '../shared/schemas.js';
-import { assertFresh, recordRead } from '../shared/fileState.js';
+import { assertFresh, recordRead, wasTruncated } from '../shared/fileState.js';
 // ---------------- 1. Zod 输入 schema ----------------
 const editItemSchema = z.object({
     old_string: z.string().min(1).describe('要替换的原文本（不允许为空 —— 创建新文件请用 Edit 工具）'),
@@ -93,6 +93,9 @@ async function call(input) {
     }
     // 4f. 在内存中顺序应用所有 edit（任一失败立即返回，磁盘不动）
     let currentContent = originalContent;
+    const truncHint = wasTruncated(filePath)
+        ? `\n\n⚠️ 上次 Read 该文件时被截断了（只看到部分内容）。当前 old_string 可能在截断范围外。请用更小的 limit + offset 精确读取目标行号附近后再 MultiEdit。`
+        : '';
     for (let i = 0; i < edits.length; i++) {
         const edit = edits[i];
         const replaceAll = edit.replace_all ?? false;
@@ -103,7 +106,7 @@ async function call(input) {
         if (actualOld === null) {
             return {
                 ok: false,
-                error: `edits[${i}] 未匹配到 old_string（在已应用前序 ${i} 处修改后的内容中找不到）。请先用 Read 工具核对当前内容（注意空格/缩进/换行），并检查 edit 顺序。`,
+                error: `edits[${i}] 未匹配到 old_string（在已应用前序 ${i} 处修改后的内容中找不到）。请先用 Read 工具核对当前内容（注意空格/缩进/换行），并检查 edit 顺序。${truncHint}`,
             };
         }
         if (actualOld !== edit.old_string) {
@@ -114,13 +117,13 @@ async function call(input) {
         if (occurrences === 0) {
             return {
                 ok: false,
-                error: `edits[${i}] 未匹配到 old_string（已应用前序 ${i} 处修改后内容中出现 0 次）。`,
+                error: `edits[${i}] 未匹配到 old_string（已应用前序 ${i} 处修改后内容中出现 0 次）。${truncHint}`,
             };
         }
         if (occurrences > 1 && !replaceAll) {
             return {
                 ok: false,
-                error: `edits[${i}].old_string 在当前内容中出现 ${occurrences} 次，不唯一。请扩大 old_string 包含更多上下文，或显式传 replace_all=true。`,
+                error: `edits[${i}].old_string 在当前内容中出现 ${occurrences} 次，不唯一。请扩大 old_string 包含更多上下文，或显式传 replace_all=true。${truncHint}`,
             };
         }
         currentContent = replaceAll

package/src/tools/read/read.js

@@ -127,10 +127,13 @@ async function call(input) {
     }
     // 4f. 大小兜底 + 自动分段提示
     let content = numbered;
+    let truncated = false;
     if (content.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
         content =
             content.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) +
-                `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
+                `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)` +
+                `\n\n⚠️ **重要：本次返回的是截断内容**。直接基于这部分内容写 Edit/Write 会失败 —— old_string 可能在截断范围外，Write 会丢失截断范围外的内容。必须做以下之一：(1) 用更小的 limit + 精确的 offset 缩小读取范围；(2) 已知改动位置时直接 offset 到目标行号附近；(3) 整文件覆盖请用多次 Edit 而非 Write。`;
+        truncated = true;
     }
     const startIdx = Math.max(0, offset - 1);
     const endIdx = Math.min(totalLines, startIdx + limit);
@@ -142,7 +145,7 @@ async function call(input) {
     if (st.size > 100 * 1024 && offset === 1) {
         content += `\n\n⚠️ 注意：这是一个大文件（${(st.size / 1024).toFixed(1)} KB）。建议用 offset/limit 分段读取，例如先读关键部分（imports、exports、函数签名）。`;
     }
-    recordRead(filePath);
+    recordRead(filePath, { truncated });
     return { ok: true, content };
 }
 async function readSmallFile(filePath, offset, limit) {

package/src/tools/shared/fileState.js

@@ -16,15 +16,23 @@
  */
 import { existsSync, statSync } from 'node:fs';
 const fileState = new Map();
-export function recordRead(absPath) {
+export function recordRead(absPath, opts) {
     try {
         const st = statSync(absPath);
-        fileState.set(absPath, { timestamp: st.mtimeMs, size: st.size });
+        fileState.set(absPath, {
+            timestamp: st.mtimeMs,
+            size: st.size,
+            truncated: opts?.truncated ?? false,
+        });
     }
     catch {
         // 文件不存在或无权访问 —— 不记录，让 Read 自己处理错误
     }
 }
+/** 查询上次 Read 是否被截断。供 Edit/MultiEdit 给出更精准 error hint、Write 做 hard guard 用。 */
+export function wasTruncated(absPath) {
+    return fileState.get(absPath)?.truncated ?? false;
+}
 export function assertFresh(absPath) {
     const entry = fileState.get(absPath);
     if (!entry) {

package/src/tools/write/write.js

@@ -20,7 +20,7 @@ import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
 import { applyLineEnding, detectFileBomEncoding, detectFileLineEndings, resolveToolPath, } from '../shared/fileUtils.js';
 import { filePathField } from '../shared/schemas.js';
-import { assertFresh, recordRead } from '../shared/fileState.js';
+import { assertFresh, recordRead, wasTruncated } from '../shared/fileState.js';
 /** 写入内容上限：1GB。防止模型试图写入超大内容撑爆内存/磁盘。 */
 const MAX_WRITE_SIZE_BYTES = 1024 * 1024 * 1024;
 // ---------------- 1. Zod 输入 schema ----------------
@@ -50,6 +50,14 @@ async function call(input) {
     if (!freshness.ok) {
         return { ok: false, error: freshness.error };
     }
+    // Ranged-read hard guard：上次 Read 被截断时禁止 Write 覆盖。
+    // Write 无脑覆盖整文件，部分 Read 后 Write 会真的把截断范围外的内容全删掉。
+    if (existsSync(filePath) && wasTruncated(filePath)) {
+        return {
+            ok: false,
+            error: `${filePath} 上次 Read 时被截断了（看到的是部分内容）。Write 会用 content 覆盖整个文件 —— 直接 Write 会丢失截断范围之外的内容！必须先用更小的 limit + 多次 offset Read 到末尾确认看完整后再 Write，或改用 Edit 工具精确替换某段内容（Edit 不需要整文件视野）。`,
+        };
+    }
     const contentSize = Buffer.byteLength(input.content, 'utf8');
     if (contentSize > MAX_WRITE_SIZE_BYTES) {
         return {

package/workflows/schema.json

@@ -41,7 +41,10 @@
         "tool": { "type": "string" },
         "skill": { "type": "string" },
         "llm": { "type": "string" },
-        "type": { "enum": ["assert", "branch", "loop", "pause"] },
+        "type": {
+          "enum": ["assert", "branch", "loop", "pause", "parallel", "vote"],
+          "description": "控制流节点类型。⚠ ADR-05 新增 'parallel' 与 'vote'，详见 docs/05-advanced-workflow-integration.md。"
+        },
         "args": { "type": "object" },
         "input": { "type": "string" },
         "capture": {
@@ -67,7 +70,48 @@
           "type": "array",
           "items": { "$ref": "#/definitions/step" }
         },
-        "prompt": { "type": "string" }
+        "prompt": { "type": "string" },
+        "output_schema": {
+          "type": "object",
+          "description": "⚠ ADR-05 新增：LLM 输出 JSON Schema 强约束，走 provider-native structured output。仅 llm/skill 节点生效；详见 docs/05-advanced-workflow-integration.md。"
+        },
+        "fork": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/step" },
+          "description": "⚠ ADR-05 新增：type=parallel 时的 fork 子步骤数组，Promise.all 并发执行。详见 docs/05-advanced-workflow-integration.md。"
+        },
+        "voters_count": {
+          "type": "integer",
+          "minimum": 2,
+          "maximum": 10,
+          "description": "⚠ ADR-05 新增：type=vote 的 voter 数量（2~10）。详见 docs/05-advanced-workflow-integration.md。"
+        },
+        "rules": {
+          "type": "string",
+          "description": "⚠ ADR-05 新增：type=vote 给 voter 的审查指令。详见 docs/05-advanced-workflow-integration.md。"
+        },
+        "threshold": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "⚠ ADR-05 新增：type=vote 的多数门阈值，默认 ceil(voters_count/2)。详见 docs/05-advanced-workflow-integration.md。"
+        },
+        "context_files": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path"],
+            "properties": {
+              "path": { "type": "string", "minLength": 1 },
+              "hint": { "type": "string" }
+            }
+          },
+          "description": "⚠ ADR-05 新增：llm/skill 节点声明可用的上下文文件清单（path + hint），runner 拼进 prompt 并开放 Read 子循环，不 inline 内容。详见 docs/05-advanced-workflow-integration.md。"
+        },
+        "allowed_tools": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "⚠ ADR-05 新增：与 context_files 配对的 mini ReAct 工具白名单，缺省 ['Read']。详见 docs/05-advanced-workflow-integration.md。"
+        }
       }
     }
   }