minimal-agent 0.13.0 → 0.14.0

package/skills/workflow-creator/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: workflow-creator
+description: 创建、修改、审查 V2 动态工作流——放在 workflows 命名子目录中、由 /workflow 执行的受信任 ESM 代码编排模块。用户说「写一个工作流」「把这个流程做成工作流」「改一下某个工作流」时使用。它说明 WorkflowContext、可靠性守卫和端到端验收方式。
+---
+
+# workflow-creator —— 写出**能扛事**的动态工作流
+
+## 评价一条工作流的标准
+
+**功能、性能、鲁棒性** —— 具体说是四样：**控制力**（流程按你设计的走）、
+**越障能力**（某一步出意外能绕过去而不是整条崩）、**模板完成度**（该有的守卫都有）、
+**稳定性**（同样的输入跑十遍结果一致）。
+
+**行数不在其中。** 本项目的架构就是「轻引擎、重工作流」—— 不能让引擎膨胀，
+工作流该多写就多写。看到一条工作流比对应的 yaml 长，那通常是好事而不是坏事。
+
+举个真实的例子：`adaptive-research` 迁移后把 DSL 藏在 `done_when:` 两行声明里的守卫
+**摆到了明面上**，占了 20 行。那 20 行是这条工作流唯一不会烂尾的原因 ——
+删掉它跑起来一模一样，直到某天模型开始 announce-not-do。
+
+## 这个 skill 要防的那件事
+
+只看 API 参考的人会写出**没有任何守卫**的工作流，而且它**看起来更短更干净**。
+**能跑通 ≠ 写好了。** 下面的流程与规则就是把「好」变成可检查的。
+
+---
+
+## 一、先搞清楚要写的是什么
+
+动手前先答三个问题；答不上来就先问用户（**一次性合并问完**，别追问第二轮）：
+
+1. **成果和必需后置条件是什么？** 文件成果具体到路径与格式；非文件成果具体到 schema、协议令牌、
+   测试或目标应用状态。没有可观察判据的工作流没法验收，也就没法自动化。
+2. **哪些步骤是确定性的，哪些需要随机应变？** 这决定用原生函数、`wf.tools.call()` 还是 `wf.model.agent()`。
+3. **失败了怎么办？** 每个可能失败的地方，是「降级继续」「就地自愈」还是「诚实停止」？
+
+> 判断不了执行方式时，优先把纯计算留在 ESM/JS、确定性副作用交给 `wf.tools.call()`/
+> `wf.exec.file()`、开放判断交给 `wf.model.agent()`。失败语义必须由阶段契约决定：关键成果和验收证据失败要诚实停止；只有明确允许缺失的
+> 增强项才能降级继续。
+
+### 阶段契约不要只有 success / failed
+
+复杂成果通常由多个可独立使用的部分组成。阶段输出至少要区分：
+
+- **执行结局**：调用是否完成；
+- **内容完整性**：`complete | partial | unknown`；
+- **组件状态**：哪些部分已确认可用，哪些部分缺失；
+- **限制来源**：原始输入本身缺失、当前定位/处理失败，还是归属仍有歧义。
+
+父流程应继续使用已确认的组件，只对缺失组件降级或占位；不要因为一个可选或局部组件失败，
+把已经可靠完成的主体清空。反过来，文件落盘或子流程正常 `return` 只证明“执行完成”，
+不自动证明业务内容完整。结构化字段要进入 schema/result，不能只藏在人话 warning 里让下游再猜。
+
+---
+
+## 二、先查清楚你手上有什么（**动手前必做，不许跳过**）
+
+工作流最容易犯的错不是写错，而是**让 agent 从零重造一个已经存在的能力** ——
+自己写一段 PPT 生成逻辑，而项目里躺着一个沉淀了几十条踩坑经验的 `pptx` skill。
+
+**每次写工作流之前先跑这一条**：
+
+```bash
+node skills/workflow-creator/scripts/list-resources.mjs
+```
+
+它会现场列出这台机器上**当前**有什么：
+
+- **工具**（40+ 个）—— 用于 `wf.tools.call()` 与 `allowedTools`，按用途归好组
+- **Skills**（近 30 个）—— 用 `wf.model.skill(名字, 任务描述)` 调
+- **插件** —— 各自暴露的命令
+
+只想看一类就加 `--tools` / `--skills` / `--plugins`；要机器可读加 `--json`。
+
+> ⚠️ **为什么是脚本而不是这里写一张表**：写死的清单必然过时。工具会增删、
+> skills 是运行时扫目录的（用户还能在自己项目里放）、插件也可能装卸。
+> 一张落后的表会让你**用不上已有能力**，或者**写出不存在的工具名**（那会被
+> `allowedTools` 静默过滤，agent 少了能力还不明显报错）。
+> **清单靠现场查，判断靠下面这几条。**
+
+### 判断：这一步该用什么
+
+| 情况 | 用什么 |
+|---|---|
+| 现有 Skill 的能力、输入和产出契约与本阶段匹配 | 优先 `wf.model.skill()` 复用沉淀；不匹配时使用更小的 tool/agent 组合，不为迁就 Skill 扭曲流程 |
+| 没有现成 skill，任务开放 | `wf.model.agent()`，并在 prompt 里**点名让它先 Read 相关 SKILL.md** |
+| 完全确定性 | `wf.tools.call()` / `wf.exec.shell()` |
+| 已有普通动态工作流可完成一个阶段 | 在meta.dependencies声明名字，然后 `await wf.flow.child(name, inputs)`，从result读取结构化结果；不另起CLI进程 |
+| 要看图 | `wf.model.generate(prompt, { images: [...] })` —— 唯一通道 |
+| 产出不在文本里（截图等） | `wf.tools.callResult()` 而不是 `wf.tools.call()`，图在 `images` 字段 |
+| **要 JSON 回来** | `{ schema: {...} }` —— **别再手写 `parseJson` + nudge 循环**，引擎会校验 + 有界修复，返回的直接是对象 |
+| **同一件事做 N 遍** | `wf.flow.pipeline(items, { stages: [...] })` —— **不要**裸 `Promise.all(items.map(i => wf.model.agent(...)))`，那会让断点续跑静默失效 |
+| **这一步不需要前文** | 加 `{ isolated: true }` —— 逐项打分/格式转换/批量抽取都属此类，主线 history 不会变长 |
+| **这一步便宜/判断轻** | 可以 `{ model: '某个便宜模型 id' }`，但**随包分发的工作流别写死 id**（那是每台机器各自的配置） |
+| **给个目标，自己持续推进** | 先判断是否应由外层 Goal Runtime 管理；生命周期不写进 Runner。具体循环策略参考 `patterns.md` 第 19 节和 `workflows/goal/workflow.mjs`，按业务契约裁剪，不整段照抄 |
+
+例：`await wf.model.skill('pptx', '把 out/deck.json 转成 out/deck.pptx，要能被 PowerPoint 干净打开')`
+
+### 别忘了这三样能力
+
+`list-resources.mjs` 会列出全部，但下面三样最容易被忽略 —— 它们不像"工具"，
+更像"另一个世界的入口"：
+
+- **`ComputerUse`（桌面操控）** —— 能截屏、点击、按键、操控本机 GUI 应用。
+  应用的界面知识住在 `plugins/computer_use/app/<应用>.md`，**引擎会把说明书摘要
+  注入每一次观测**，所以工作流**不要**把界面知识抄进 prompt（抄了也打不过每次
+  新鲜送达的说明书，还只服务这一个工作流）。工作流只声明**目标和判据**。
+  调用时必须写 `{ uses: ['computer'] }`，否则宿主不转授权。
+  现成例子：`workflows/wechat-reading-shots/`。
+  ⚠️ 目前只吃 macOS。
+
+- **`WebBrowser`（真浏览器）** —— 需要登录、JS 渲染、要在页面里 `eval` 抽数据时用。
+  `{ uses: ['browser'] }`。⚠️ `eval` 还需要「设置 → 浏览器」开 Developer Mode。
+  现成例子：`workflows/illustrate/`。
+
+- **`Agent`（子任务分身）** —— 但在工作流里你基本用不到它：`wf.model.agent()` 本身就是
+  子任务。除非要在一个 agent 内部再并行分身。
+
+---
+
+## 三、目录形态：**一个工作流可以有很多文件**
+
+```
+workflows/<名字>/          ← 目录名**就是**工作流名，脚本里不写 name
+├── workflow.mjs           主入口（必需）
+├── scripts/*.mjs          原生 import 的纯函数，或独立进程辅助程序
+├── prompts/*.md           长 prompt 拆出来单独放（用 wf.fs.readText() 读取）
+├── assets/                模板、schema、示例数据
+└── README.md              意图 / 输入 / 产物 / 已知坑
+```
+
+**别把什么都塞进一个 `workflow.mjs`。** 复杂工作流该拆就拆，按架构需要来：
+
+- **确定性的纯数据处理**（解析、统计、坐标换算）→ 抽成 `scripts/*.mjs` 并原生相对
+  `import`。只有需要独立进程或第三方 CLI 时才用 `wf.exec.file()`。
+- **超过 30 行的 prompt** → 放 `prompts/xxx.md`，主脚本里用
+  用 `wf.runtime.workflowDir` 构造绝对路径，再交给 `wf.fs.readText()`。
+  （**不是** `wf.tools.call('Read')` —— 那个返回给模型看的格式。）
+  好处：改 prompt 不动代码，diff 干净。
+- **schema / 模板 / 固定清单** → 放 `assets/`，`wf.fs.readJson()` 读进来。
+
+主入口 `workflow.mjs` 应该读起来像**流程的目录**：一眼看清有几个阶段、每阶段干什么、
+守卫在哪。细节下沉到脚本和 prompt 文件里。
+
+需要用户文件、图片或目录时，把输入声明为 `type: 'resource'`，并按需设置
+`accepts`、`allowFile`、`allowDirectory`、`multiple`、`maxItems` 和
+`attachmentFallback: true`。这样 CLI/TUI 的路径与 Desktop 本轮拖入的附件会走同一条绑定链；
+工作流从 `wf.input.values.<name>` 取得路径，从 `wf.input.resources.<name>` 取得资源清单。
+如果工作流始终需要目录，即使用户只拖入一个文件，也要声明 `materialize: 'directory'`。
+不要从 transient context 或消息文本中猜附件路径。显式 `--input name=路径` 始终优先；多附件会自动物化为稳定目录。
+
+用 `node skills/workflow-creator/scripts/scaffold.mjs <名字>` 生成起步目录。
+
+**辅助脚本一律写 `.mjs`，不要 `.ts`**：它们是被 `node` spawn 的，而 npm 安装形态和绿色版
+U 盘上的 Node 版本不可控，`.ts` 需要 type-stripping 支持。同理**不要用 Python** ——
+宿主必然有 JS 运行时，Python 环境不一定有（这个项目为此踩过坑）。
+
+---
+
+## 四、脚本骨架
+
+开头必须是带 `apiVersion: 2` 的**纯字面量** `meta`，默认导出 `run(wf)`；禁止顶层
+启动业务，所有运行状态都放进 `run()`：
+
+```javascript
+export const meta = {
+  apiVersion: 2,
+  description: '一句话说清这个工作流做什么',   // 必填
+  inputs: [{ name: 'topic', required: true, greedy: true }],
+  artifacts: [],
+}
+
+export default async function run(wf) {
+  const { topic } = wf.input.values
+  const { sessionId, taskId } = wf.runtime
+  const OUT = `out/<名字>/${sessionId}/${taskId}/report.md`
+
+  await wf.model.agent(`……`, { label: '起草', allowedTools: ['Read', 'Write'] })
+
+  if (!(await wf.fs.exists(OUT))) throw new Error(`${OUT} 没产出`)
+  wf.output.artifact(OUT)
+
+  wf.output.message(`✅ 完成 → ${OUT}`)
+  return { path: OUT }
+}
+```
+
+**控制流用 JS 原生的**：`if` / `for` / `while` / `break` / `continue` / `try`，
+带标签的 `break outer` / `continue outer` 可跨嵌套循环跳。
+引擎**不提供**这些的替代品，因为不需要。
+
+**唯一的例外是扇出**：用 `wf.flow.pipeline()`，不要裸 `Promise.all` 并发记账调用。
+原因见下面第五节和 `references/api.md` —— 一句话是账本按车道定位，裸 `Promise.all`
+会让所有调用挤在同一条车道上并发记账，断点续跑静默失效。
+
+完整能力清单见 `references/api.md`，结构模式见 `references/patterns.md`。
+
+---
+
+## 五、脊梁规则：必需后置条件必须可观察
+
+> **每个阶段的必需后置条件都必须有独立于 Agent 自述的可观察证据，并定义有界恢复。**
+
+证据可以是文件存在与内容检查、结构化 schema、精确协议令牌、测试结果或目标应用实际打开结果。
+恢复可以是 nudge、换工具、换来源、重做当前阶段或诚实停止；不是每个 `wf.model.agent()` 都必须写文件或 nudge。
+纯分析、分类、候选探索等阶段只需验证其下游真正依赖的输出契约。
+
+验收范围要与成果组件对齐：局部增强失败只影响该组件，不能否定已独立核实的主体；真正缺少
+必需输入时则要明确标成 `source_limited` 一类的业务状态，不能靠降低阈值冒充通过。
+每次重试还必须改变至少一项：输入、定位框、工具、模型提示中的具体错误证据或执行策略。
+原始输入没有所需信息时立即停止该组件的重试；把同一输入和笼统的“再试一次”重复发送，
+既不能补回不存在的信息，也会把模型延迟放大成工作流卡顿。
+
+理由：弱模型的典型烂尾是 **announce-not-do** —— 输出「接下来我将创建该文件」然后就
+`end_turn` 了，文本读起来像做完了。实测遇到过：`ralph-loop` 第一次跑，agent 输出
+`<promise>DONE</promise>` 而文件根本不存在；加上验收门再跑才真做出来。
+
+当“文件必须落盘”确实是阶段后置条件时，标准写法是：
+
+```javascript
+let out = await wf.model.agent(PROMPT, { label: '写报告', allowedTools: ['Read', 'Write'] })
+
+for (let i = 1; i <= 2 && !(await wf.fs.exists(OUT)); i++) {
+  wf.output.progress(`${OUT} 还没落盘，第 ${i} 次提醒`)
+  out = await wf.model.agent(
+    `${OUT} 还没有生成。请**现在就调用 Write 工具**写进去，不要只描述你打算做什么。`,
+    { label: `nudge-${i}`, allowedTools: ['Read', 'Write'] },
+  )
+}
+if (!(await wf.fs.exists(OUT))) throw new Error(`${OUT} 始终未生成`)
+```
+
+引擎侧还有一道**廉价兜底**：`wf.model.agent()` 产出了文本却一次工具都没调时，会往
+`progress.md` 记一条 `⚠ #N agent 零工具调用` 并发 warning。
+**跑完之后在 progress.md 里搜「零工具调用」** —— 搜得到就说明那一步的 prompt 在邀请模型叙述而不是动手。
+
+---
+
+## 六、必踩的坑
+
+0. **扇出用 `wf.flow.pipeline()`，不要裸 `Promise.all(wf.model.agent(...))`**。
+   账本按「**车道内序号** + 内容指纹」定位断点，而裸 `Promise.all` 让所有调用挤在同一条
+   车道上并发记账 —— 序号取决于谁先返回，也就是取决于 LLM 延迟。**断点续跑随之静默失效**。
+   扇出**超过并发上限 8** 时必然发生，而 N ≤ 8 的验证恒绿、根本看不出来。
+   `pipeline` 给每一项一条确定的车道，扇出与 resume 因此可以兼得。
+   → 看到引擎发「断点续跑随之失效」这条 warning，就是在提示你改用 `pipeline`。
+
+1. **`wf.tools.call('Bash', …)` 返回的是给模型看的展示文本**
+   （`<stdout>\n83 x.md\n</stdout>\n\n[exit code: 0]`），`split('\n')[0]` 拿到的是字面量 `<stdout>`。
+   → 跑命令一律用 **`wf.exec.shell()`**，它返回 `{ stdout, stderr, exitCode }`。
+
+2. **产物路径要带 `${session}/${task}` 命名空间**。不带的话，同一会话换个目标重跑会撞上
+   同一个路径（引擎会先把旧的归档进 `.trash/` 兜底，但那是安全网不是设计）。
+
+3. **循环体里的逐迭代产物必须 `wf.output.artifact()`**。`meta.artifacts` 是静态字面量，
+   写不出 `out/${session}/page-${i}.png`。不登记 = 静默漏档：completed 少报、清理漏掉。
+
+4. **禁 `Date.now()` / `Math.random()` / 无参 `new Date()`**。断点续跑靠「调用序号 + 内容指纹」
+   重放，任何不确定性都会让指纹必然失配，等于 resume 直接失效。启动前静态扫描会拒绝并指出行号。
+   需要变化就让 `args` 或循环下标参与。
+
+5. **`meta` 必须是纯字面量、不许有 `name`**。它在执行前被静态求值，此时没有任何运行时值可用；
+   工作流名恒等于目录名（两处声明必然漂移）。
+
+6. **读数据文件一律用 `wf.fs.readText()` / `wf.fs.readJson()`，绝不要用 `wf.tools.call('Read', …)`**。
+
+   `Read` 工具的输出是**给模型看**的，带两样对程序化读取有害的东西：
+   每行的 `<行号><TAB>` 前缀，以及**重复读同一文件时开头插的一句**
+   「⚠️ 重复读取空转：该区间未变化…」。
+
+   第二条尤其阴险 —— 它**只在第二次出现**，于是同一段代码时对时错。
+   真实事故：research 阶段2 的 agent 写完 `branches.json` 后自己 Read 校验了一遍，
+   脚本随后 `wf.fs.readJson()` 就成了「第二次」→ 解析失败 → 静默返回 `null` →
+   下游报「JSON 格式错误或数组为空」，而那个文件手工 `cat` 完全合法。
+   排查花了两轮才找到，因为**第一次跑通过、第二次才炸**。
+
+   `readText`/`readJson` 直接读文件，不经过那条通道。同理 `wf.exec.shell()` 之于 `wf.tools.call('Bash')`。
+
+7. **看图只能走 `images` 通道**：`wf.model.generate(prompt, { images: [{ source: path, detail: 'high' }] })`。
+   内核的 tool 结果是纯字符串，把图片路径写进 prompt 文本模型是看不见的。
+
+8. **`WebBrowser` 的 `eval` 结果要 `parseJson` 两层**。抽取器里 `JSON.stringify(...)`
+   返回字符串，agent-browser 显示结果时又 JSON 编码一次 —— 收到的是「带外层引号的
+   双编码串」。少套一层会**静默**拿到字符串而不是数组，后续 `.length` 变成字符数。
+
+9. **工具返回的图片在 `wf.tools.callResult()` 的 `images` 里，`wf.tools.call()` 拿不到**。
+   ComputerUse 的 `observe`、任何看图类工具都一样。用 `wf.tools.call()` 的话那些截图
+   **被静默丢弃**，后面要看图的步骤没图可用、还不报错。
+   （legacy 引擎为这件事专门修过一次，新引擎一开始又漏了同一处。）
+
+10. **协议令牌要精确取值，不要在自由文本里找关键词**。
+    `includes('ok')` 会把「ok 的路子都走不通」判成成功；
+    `includes('12')` 会把 `PAGE=112 113` 判成到了第 12 页。
+    一律 `text.match(/OPEN=([a-z]+)/)?.[1] === 'ok'` 这样精确取。
+
+---
+
+## 七、写完必做的三件事
+
+```bash
+# 0. 查清楚手上有什么（写之前就该跑过一次；改工具名之后再跑一次）
+node skills/workflow-creator/scripts/list-resources.mjs --tools
+
+# 1. 静态校验（语法、禁用构造、meta 形状、脊梁规则）
+node skills/workflow-creator/scripts/validate.mjs workflows/<名字>/workflow.mjs
+
+#    校验器会真实 import ESM（不执行 run），同时核实相对模块和运行时包解析。
+
+# 2. 真跑一遍。先用最小输入，别一上来就跑真实大任务
+bun run src/main.tsx -p "/workflow <名字> 一个最小的测试输入"
+
+# 3. 看中间产物 —— 这一步最容易被跳过，但问题几乎都藏在这里
+cat .minimal-agent-workflow/<名字>/*/*/progress.md    # 每步的开始/完成/失败
+cat .minimal-agent-workflow/<名字>/*/*/journal.jsonl  # 每次调用的真实返回值
+```
+
+**看 `progress.md` 时重点找三样**：`✗`（失败）、`零工具调用`（announce-not-do）、
+以及「某一步的结果预览是空的」（模型没产出）。同时核对实际模型调用数、每次恢复是否改变了
+输入，以及 `partial/unknown` 项有没有被最终汇总；不要用“生成了文件”代替内容完整性结论。
+
+**跑不了端到端怎么办**（依赖 macOS-only 的 ComputerUse、需要授权的浏览器、
+收费 API…）：给工作流写**单元测试** —— 构造 `wf` stub，直接调用真实默认导出，
+只验证控制流。见 `references/patterns.md` §16，以及现成的例子
+`plugins/workflow-runner/test/wechatReadingShots.test.ts`（15 条断言，全程不碰桌面）。
+
+宿主要拿结构化结局就加 `--output-format json`：`ok` / `stop_reason` / `num_turns` / `result`。
+用户可见结论必须显式调用 `wf.output.message()`；模型内部文本不应自动冒充最终交付。
+
+---
+
+## 八、改一个已有工作流
+
+改脚本内容会让 `scriptHash` 变化，引擎据此**作废旧断点**并明示「脚本内容已改变，全新开始」——
+这是有意的：上次那份结论是另一份脚本产出的。所以改完直接重跑同一目标即可，不用手工清状态。
+
+真要清干净：删掉 `.minimal-agent-workflow/<名字>/` 即可（`.trash/` 里是旧产物的回收站，
+删它才会真正丢东西）。
+
+---
+
+## 九、把 yaml 工作流迁成代码形态
+
+见 `references/migration.md` —— 里面是 13 种 StepKind 到 JS 原生写法的逐条对照，
+以及「迁完怎么算合格」的四条判据（控制力 / 越障能力 / 模板完成度 / 稳定性）。

package/skills/workflow-creator/assets/template/workflow.mjs

@@ -0,0 +1,48 @@
+export const meta = {
+  // 一句话说清这个工作流做什么。会显示在 /workflows 列表里，必填。
+  description: 'TODO：一句话说清做什么',
+
+  // 输入声明。位置参数按这里的**数组顺序**映射；首个可标 greedy 吸收整句自然语言。
+  inputs: [{ name: 'topic', required: true, greedy: true }],
+
+  // 静态产物种子。带 ${} 的路径写不了（meta 是执行前静态求值的纯字面量），
+  // 那些用运行时的 declareArtifact() 登记。
+  artifacts: [],
+}
+
+// ⚠️ 目录名就是工作流名，这里不写 name。
+// ⚠️ 不能 import；不能用 Date.now() / Math.random() / 无参 new Date()。
+// 完整能力见 skills/workflow-creator/references/api.md
+
+// 产物路径带 ${session}/${task} 两级命名空间：session 隔离并行会话，
+// task 隔离「同一会话里换了个目标」。
+const OUT = `out/TODO-名字/${session}/${task}/report.md`
+
+log('开始')
+
+// ── 步骤 1：确定性的活用 tool() / sh() ──────────────────────────────
+// const r = await sh('node scripts/prepare.mjs')
+// if (r.exitCode !== 0) throw new Error(r.stderr)
+
+// ── 步骤 2：开放式的活用 agent() ────────────────────────────────────
+let out = await agent(
+  `TODO：把任务描述清楚。要产出文件时，明确写出路径 ${OUT}。`,
+  { label: 'TODO 这一步在干嘛', allowedTools: ['Read', 'Write', 'Grep', 'Glob'] },
+)
+
+// ── 脊梁规则：产出物必核实 + 有界 nudge ─────────────────────────────
+// agent 可能「宣告要做却没动手」（announce-not-do），文本读起来像做完了。
+// 删掉这段，这条工作流就失去了对该失效模式的全部防护。
+for (let i = 1; i <= 2 && !(await exists(OUT)); i++) {
+  log(`${OUT} 还没落盘，第 ${i} 次提醒`)
+  out = await agent(
+    `${OUT} 还没有生成。请**现在就调用 Write 工具**写进去，不要只描述你打算做什么。`,
+    { label: `nudge-${i}`, allowedTools: ['Read', 'Write'] },
+  )
+}
+if (!(await exists(OUT))) throw new Error(`${OUT} 始终未生成`)
+declareArtifact(OUT)
+
+// ── 收尾：echo 是 -p 模式 result 字段的唯一来源 ──────────────────────
+echo(`✅ 完成 → ${OUT}`)
+return { path: OUT }

package/skills/workflow-creator/references/api.md

@@ -0,0 +1,216 @@
+# WorkflowContext V2 API
+
+动态工作流是受信任的本地 ESM 模块，不是安全沙箱。入口固定为：
+
+```js
+export const meta = {
+  apiVersion: 2,
+  description: '一句话说明用途',
+  inputs: [],
+  dependencies: [],
+}
+
+export default async function run(wf) {
+  return { ok: true }
+}
+```
+
+允许原生相对 `import`、`node:` 内置模块和已声明的运行时包。模块顶层只能放纯常量、
+函数与类，不得保存每次运行会改变的状态；运行状态必须在 `run(wf)` 内。
+
+本表与
+`plugins/workflow-runner/src/workflowContextCapabilities.json` 自动对账；能力注册表、运行时
+形状、类型与本参考共享这一份真值。
+
+## 能力表
+
+| 路径 | 说明 |
+|---|---|
+| `wf.input.values` | 经过 `meta.inputs` 强制类型后的输入 |
+| `wf.input.resources` | 资源输入对应的 `InvocationResource[]` |
+| `wf.runtime.workflowName` | 目录名，也是工作流唯一名称 |
+| `wf.runtime.workflowDir` | 工作流包绝对目录 |
+| `wf.runtime.cwd` | 本次有效工作目录 |
+| `wf.runtime.sessionId` | 会话身份 |
+| `wf.runtime.taskId` | 任务实例身份 |
+| `wf.runtime.runId` | 当前运行身份 |
+| `wf.runtime.rootRunId` | 整棵父子执行树身份 |
+| `wf.runtime.goal` | 只读目标锚 |
+| `wf.model.generate` | 零工具模型生成；支持 schema、images 等选项 |
+| `wf.model.agent` | 有界 TAOR 子任务 |
+| `wf.model.skill` | 调用一个 Skill agent |
+| `wf.model.require` | 在昂贵步骤前核实模型角色能力 |
+| `wf.tools.call` | 调用工具，返回文本 |
+| `wf.tools.callResult` | 调用工具，返回 content/images/metadata |
+| `wf.exec.shell` | 执行 shell 字符串，返回 stdout/stderr/exitCode |
+| `wf.exec.file` | 用参数数组执行脚本或程序，避免 shell quoting |
+| `wf.fs.exists` | 每次读取真实磁盘状态 |
+| `wf.fs.readText` | 读取纯文本，失败返回 null |
+| `wf.fs.readJson` | 读取 JSON，失败返回 null |
+| `wf.fs.writeText` | 原子、幂等写文本 |
+| `wf.fs.writeJson` | 原子、幂等写 JSON |
+| `wf.fs.mkdir` | 递归建目录 |
+| `wf.flow.pipeline` | 有界、稳定 lane 的结构化流水线 |
+| `wf.flow.child` | 调用 `meta.dependencies` 声明的子工作流 |
+| `wf.flow.ask` | 人在回路闸门 |
+| `wf.check.verify` | 确定性检查 |
+| `wf.state.budget` | 当前执行树 token 账本快照 |
+| `wf.state.resetModelContext` | 长循环回到入口上下文 |
+| `wf.state.addGoalSupplement` | 追加贯穿后续调用的目标补充 |
+| `wf.state.syncManagedContract` | managedRuntime 将契约交回外层控制器 |
+| `wf.output.message` | 用户可见且进入历史的最终输出 |
+| `wf.output.progress` | 结构化进度事件 |
+| `wf.output.artifact` | 动态登记产物 |
+
+`wf.fs` 不进 journal；模型、工具、进程、询问和子工作流进入 journal。工作流返回值必须
+可 JSON 序列化。Runner 只解释完成、失败与中断，不解释 `partial`、`suspected` 等业务字段。
+
+## 模型选项
+
+`wf.model.generate(prompt, options)`、`agent`、`skill` 支持：
+
+```js
+{
+  label: '识图',
+  allowedTools: ['Read', 'Write'],
+  maxTurns: 20,
+  uses: ['browser'],
+  images: [{ source: imagePath, detail: 'high' }],
+  contextFiles: [{ path: 'PLAN.md', hint: '验收标准' }],
+  timeoutMs: 900_000,
+  maxTokens: 8192,
+  model: 'vision',
+  isolated: true,
+  nativeSchema: false,
+  schema: {
+    type: 'object',
+    required: ['items'],
+    properties: { items: { type: 'array', items: { type: 'string' } } },
+  },
+}
+```
+
+- 图片只能通过 `images` 通道送入模型，路径写进 prompt 不等于传图。
+- `schema` 会执行 JSON 提取、校验和有界格式修复；不要另写无差别重问循环。
+- `isolated` 适合逐项识别、分类、格式转换，避免扇出污染主历史。
+- 随包工作流使用语义角色，不写死某台机器的模型 ID。
+- 超时包含排队、工具轮和 schema 修复；等待调度不会占模型槽。
+
+## pipeline
+
+```js
+const batch = await wf.flow.pipeline(items, {
+  label: '逐项识别',
+  concurrency: 6,
+  errorMode: 'collect', // collect | fail-fast
+  stages: [
+    async (_previous, item, index) =>
+      wf.model.generate(`识别第${index}项：${item}`, { isolated: true }),
+    async (text, item, index) => ({ item, index, text }),
+  ],
+})
+
+const values = batch.results
+  .filter((entry) => entry.ok)
+  .map((entry) => entry.value)
+const failures = batch.results.filter((entry) => !entry.ok)
+```
+
+- 返回顺序永远与输入一致；失败包含 `name/message/code`，不再用 `null` 丢原因。
+- `collect` 继续其它项；`fail-fast` 停止尚未开始的项，等待已开始项退出后抛错。
+- 取消始终抛 `AbortError`，不能变成普通项目失败。
+- 并发缺省由 `MINIMAL_AGENT_WORKFLOW_PIPELINE_CONCURRENCY` 控制，不得超过
+  `MINIMAL_AGENT_WORKFLOW_PIPELINE_MAX_CONCURRENCY`。
+- 扇出模型/工具/进程调用必须用 pipeline，不要裸 `Promise.all` 破坏 journal lane。
+
+## 子工作流
+
+```js
+export const meta = {
+  apiVersion: 2,
+  description: '父工作流',
+  dependencies: ['question-crops'],
+}
+
+export default async function run(wf) {
+  const child = await wf.flow.child(
+    'question-crops',
+    { source: wf.input.values.source },
+    { label: '分题' },
+  )
+  return { inventory: await wf.fs.readJson(child.result.manifest) }
+}
+```
+
+子输入显式传递，不重新吸收父附件。父子共享取消、调用总量、用量账本与全局调度上限，
+但 history、目标、journal、状态和产物所有权隔离。循环依赖、超过八层、未声明依赖及
+managedRuntime 子调用都会拒绝。子工作流完成不会产生顶层终态。
+
+## 文件、进程和原生 import
+
+纯计算优先原生 import：
+
+```js
+import { normalize } from './scripts/normalize.mjs'
+```
+
+需要独立进程或第三方 CLI 才用：
+
+```js
+const result = await wf.exec.file('./scripts/render.mjs', ['build', jobPath], {
+  timeoutMs: 120_000,
+})
+if (result.exitCode !== 0) throw new Error(result.stderr)
+```
+
+`wf.exec.file()` 对 `.mjs`/`.js` 脚本使用宿主 Node 运行；其它路径按可执行文件处理。
+不要为普通数组排序、坐标转换、字符串拼装等纯函数反复启动 Node。
+
+## 输出和进度
+
+```js
+wf.output.progress({
+  phase: 'extract',
+  status: 'update',
+  current: 3,
+  total: 10,
+  message: '正在处理第3项',
+})
+wf.output.artifact(path)
+wf.output.message(`完成：${path}`)
+```
+
+结构化事件自动补充 workflow/run/rootRunId，并写入 `events.jsonl`。`progress.md` 继续保存
+人类可读记录。根工作流只产生一个终态。
+
+## 环境限额
+
+| 环境变量 | 默认值 |
+|---|---:|
+| `MINIMAL_AGENT_WORKFLOW_MAX_ACTIVE_RUNS` | 4 |
+| `MINIMAL_AGENT_WORKFLOW_MODEL_CONCURRENCY` | 8 |
+| `MINIMAL_AGENT_WORKFLOW_TOOL_CONCURRENCY` | 16 |
+| `MINIMAL_AGENT_WORKFLOW_PROCESS_CONCURRENCY` | 8 |
+| `MINIMAL_AGENT_WORKFLOW_PIPELINE_CONCURRENCY` | 4 |
+| `MINIMAL_AGENT_WORKFLOW_PIPELINE_MAX_CONCURRENCY` | 32 |
+| `MINIMAL_AGENT_WORKFLOW_MAX_CALLS` | 1000 |
+
+非法数值会响亮报错，不静默回退默认值。限制只协调当前 minimal-agent 进程。
+
+## verify 与 ask
+
+```js
+await wf.check.verify([
+  'file_exists:out/a.md',
+  'file_contains:out/a.md:标题',
+  'shell:bun test',
+])
+
+const answer = await wf.flow.ask('是否继续？', [
+  { label: '继续（推荐）', description: '进入下一阶段' },
+  { label: '停止', description: '保留现场' },
+])
+```
+
+`ask` 的推荐项必须放第一位；非交互宿主按首项兜底。`budget()` 只在新一轮开始前读取，
+不在一轮中途打断正在产生的成果。