minimal-agent 0.12.0 → 0.14.0

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

@@ -0,0 +1,103 @@
+# 把 yaml 工作流迁成代码形态
+
+## 先说清楚这份文档现在是干什么用的
+
+**仓库里已经没有 yaml 工作流了** —— DSL 引擎（`plugins/workflow-runner-legacy/`）与
+`workflows/*.yaml` 已整体删除。所以这份对照表不再是「迁移剩下的」，而是
+**「从 git 历史里把下线的能力捞回来」**用的。
+
+下线的 5 条：`ppt` / `webppt` / `word` / `youtube-shorts` / `book-review-short`。
+它们的**脚本与 skill 都还在**（`skills/ui-design/`、`skills/pptx/`、`skills/ai-image/` 等），
+消失的只是 yaml 编排那一层。捞法：
+
+```bash
+git show ffbb313:workflows/ppt.yaml > /tmp/ppt.yaml     # ffbb313 = 删除前的 HEAD
+git show ffbb313 --stat -- workflows/                    # 看还有哪些
+```
+
+然后照下面的对照表重写成 `workflows/ppt/workflow.mjs`。
+
+> ⚠️ `ppt.yaml`（1670 行）里嵌着 40+ 条专项事故教训（对比度、scrim 极性、图生图信任分层、
+> 配额耗尽……），迁移时**必须逐条搬运**。只搬流程骨架会把那些教训全部丢掉，而它们每一条
+> 都是真实事故换来的。
+
+## 逐条对照
+
+| yaml DSL | 代码形态 | 备注 |
+|---|---|---|
+| `type: set` | `const x = …` / `let x = …` | 变量就是变量 |
+| `type: branch` + `condition` | `if` / `else if` | |
+| `type: loop` `over:` `as:` | `for (const x of list)` | |
+| `type: loop` `max_iterations:` | `for (let i = 1; i <= N; i++)` | |
+| `fresh_context: true` | `wf.state.resetModelContext()`（放循环体第一行） | |
+| `type: break` | `break` | |
+| `type: break` `target: outer` | `break outerLabel` | JS 带标签的 break，跨词法嵌套循环 |
+| `type: continue` `target: outer` | `continue outerLabel` | 同上 |
+| `type: assert` `condition:` | `if (!cond) throw new Error(onFail)` | |
+| `type: verify` `checks:` | `await wf.check.verify([...])` | |
+| `type: echo` | `wf.output.message(...)` | |
+| `type: pause` | `await wf.flow.ask(...)` | |
+| `tool:` + `args:` | `await wf.tools.call(name, input)` | 跑 shell 用 `wf.exec.shell()` |
+| `llm:` | `await wf.model.generate(prompt)` | |
+| `agent:` | `await wf.model.agent(prompt, opts)` | |
+| `skill:` | `await wf.model.skill(name, input)` | |
+| `capture:` | 直接用返回值 | 不需要这个概念 |
+| `when:` | `if` 包起来 | |
+| `onError: continue` | `try { … } catch { 占位值 }` | |
+| `onError: recover` | `catch` 里再调一次 `wf.model.agent()`，把真实错误给它 | |
+| `onError: halt` | 什么都不写（默认就是抛） | |
+| `max_retries:` | `for (let i = 0; i < N; i++) { try { …; break } catch {} }` | |
+| `done_when:` | 显式验证必需后置条件；失败时按阶段契约有界恢复或停止 | 证据不只限于文件，见 patterns.md 脊梁规则 |
+| `goal_supplement: true` | `await wf.state.addGoalSupplement(text)` | |
+| `output_schema:` | 给 `agent/llm` 传 `schema:`，直接接收校验过的对象；按原失败语义决定 catch 后降级或停止 | 引擎提供校验与有界修复，不要求 provider 原生支持 |
+| `context_files:` | `{ contextFiles: [{path, hint}] }` | |
+| `images:` | `{ images: [...] }` | |
+| `uses: [browser]` | `{ uses: ['browser'] }` | |
+| `${var}` 插值 | 模板串 `` `${var}` `` | |
+| `extract(x, '正则')` | `x.matchAll(/正则/g)` | |
+| `join(list, sep)` | `list.join(sep)` | |
+| `${a ? b : c}` | 模板串里的三元 | |
+| `${session}` | `${wf.runtime.sessionId}` | V2 不注入全局变量 |
+| `self_heal.*` | `for` + `try`（作者自己写） | 引擎不再管 |
+| `artifacts:` (step 级) | `wf.output.artifact(path)` | meta.artifacts 只做静态种子 |
+
+## 迁完怎么算合格
+
+**不看行数。** 本项目是「轻引擎、重工作流」，工作流长一点是正常的，甚至常常是好事 ——
+把引擎藏起来的东西摆到明面上，本来就要占篇幅。
+
+合格的判据是四样：
+
+| 判据 | 怎么检查 |
+|---|---|
+| **控制力** | 原 yaml 的每个阶段、每个分支、每次跳转，代码里都找得到对应物 |
+| **越障能力** | 原 yaml 每个 `onError` / `done_when` / `max_retries`，代码里都有对应的 try/catch 或核实循环 |
+| **模板完成度** | `validate.mjs` 无 warning；产物有 `wf.output.artifact` + 确定性核实 |
+| **稳定性** | 同一输入连跑两次结果一致；第二次应命中 completed 或按 journal 重放 |
+
+一个真实的例子说明「长」为什么常常是对的：`adaptive-research` 迁移后，DSL 里
+`done_when` + 引擎自动恢复那两行声明，展开成了 20 行显式的核实与有界恢复循环。
+收益是**那 20 行你能看见、能改、能针对具体工作流选择 nudge、换工具、重做或停止**——
+DSL 版本里的恢复策略是引擎写死的，工作流作者改不了。
+
+> **迁移时别为了短而砍守卫。** 短的那一版跑起来一模一样，直到某天模型开始 announce-not-do。
+
+## 迁移流程
+
+1. **通读 yaml，把它的控制图画出来**（哪些是循环、哪些是分支、跳转到哪）。
+   跨层跳转（`break/continue target:`）要特别标出来，它们决定标签放哪。
+2. **先搭骨架**：把控制流用 JS 写出来，每一步先放 `wf.output.progress('TODO: …')` 占位，跑一遍看流程对不对。
+3. **逐步填实**，每填一步跑一次。
+4. **守卫单独过一遍**：yaml 里每个 `done_when` / `onError` / `assert` / `verify` 都要在
+   代码里找到对应物。漏掉的地方就是将来会烂尾的地方。
+5. **完成针对性验证并记录迁移证据。** 当前运行时已不加载 YAML；历史 YAML 只作为迁移输入读取，
+   不要复制回 `workflows/`、不要宣称它会被代码形态遮蔽。需要留档时放在版本历史或明确的非运行文档位置。
+
+## 迁移时特别容易漏的
+
+- **`capture` 的绑定字段**：yaml 里 `capture: {text: x}` 和 `capture: {content: x}` 取的是
+  不同字段（agent 步只有 `text`/`result`，tool 步才有 `content`）。代码形态直接用返回值，
+  但要注意 `wf.tools.call()` 返回的是**工具的展示文本**，跑 shell 请用 `wf.exec.shell()` 拿结构化结果。
+- **产物路径**：yaml 里常写 `out/<name>/${session}/…`，代码形态建议加一层 `${task}`。
+- **`_iter` / `_exec_round` 这类隐式变量**：代码形态就是你自己的循环变量，注意 0-based / 1-based
+  的差异（yaml 里 `${_iter}` 从 0 开始，人话文案里常要 `+1`）。