minimal-agent 0.12.0 → 0.14.0

package/workflows/adaptive-research/workflow.mjs

@@ -0,0 +1,86 @@
+export const meta = {
+  apiVersion: 2,
+  description:
+    '受工作流指导的 TAOR：确定性骨架 + 两处随机应变。agent 自主调研写笔记，确定性步骤失败就地自愈，最后守门校验',
+  inputs: [
+    {
+      name: 'topic',
+      required: true,
+      greedy: true,
+      description: '调研主题（可直接一句话自然语言，不会被空格拆碎）',
+    },
+  ],
+  artifacts: [],
+}
+
+export default async function run(wf) {
+const { values: args } = wf.input
+const { sessionId: session, taskId: task } = wf.runtime
+const { agent } = wf.model
+const { call: tool } = wf.tools
+const { shell: sh } = wf.exec
+const { exists } = wf.fs
+const { verify } = wf.check
+const echo = wf.output.message
+const declareArtifact = wf.output.artifact
+const log = (message) => wf.output.progress({ phase: 'workflow', status: 'update', message: String(message) })
+
+// 自 adaptive-research.yaml 迁移。三处 DSL 机制在代码形态里的对应写法：
+//   done_when:        → 调用后自己 await exists() 判断，不满足就再喊一次
+//   onError: recover  → try/catch + 再调一次 agent()
+//   type: verify      → await verify()
+// 引擎因此不需要 done_when / onError / recover_hint / verify 这四个概念。
+
+const outDir = `out/adaptive-research/${session}/${task}`
+const notesPath = `${outDir}/notes.md`
+
+// ── 1. 开放式调研：把「怎么做」交给有界子 agent ──────────────────────
+const RESEARCH_PROMPT = `调研主题「${args.topic}」：用你手上的工具搜集 3-5 个关键要点，
+整理成简洁的中文 markdown，写到 ${notesPath}（目录不存在就先创建）。
+写完后用 Read 自检文件确实写好了再收尾。`
+
+let notes = await agent(RESEARCH_PROMPT, {
+  label: '自主调研写笔记',
+  allowedTools: ['Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob'],
+})
+
+// 「宣告要写却没写」是弱模型的典型烂尾（announce-not-do）。yaml 里这是引擎的
+// done_when + 自动 nudge；代码形态里就是一个 if —— 而且作者能看见它、能改它。
+for (let attempt = 1; attempt <= 2 && !(await exists(notesPath)); attempt++) {
+  log(`笔记还没落盘，第 ${attempt} 次提醒 agent 补上`)
+  notes = await agent(
+    `${notesPath} 还没有生成。请**现在就调用 Write 工具**把调研笔记写进去，不要只描述你打算做什么。`,
+    { label: `nudge-${attempt}`, allowedTools: ['Read', 'Write', 'Bash'] },
+  )
+}
+declareArtifact(notesPath)
+
+// ── 2. 确定性统计，失败就地自愈 ─────────────────────────────────────
+// 用 sh() 而不是 tool('Bash', …)：后者返回给模型看的展示文本
+// （`<stdout>…</stdout>\n\n[exit code: 0]`），想拿行数还得自己剥壳。
+let lineReport
+try {
+  const r = await sh(`wc -l ${notesPath}`)
+  if (r.exitCode !== 0) throw new Error(r.stderr || `exit ${r.exitCode}`)
+  lineReport = r.stdout.trim()
+} catch (e) {
+  // 原 yaml 的 onError:recover + recover_hint。代码形态下「救一把」就是再调一次
+  // agent 并把真实错误给它看 —— 比 DSL 声明更直白，也能看见救了什么。
+  log(`统计失败，起一个 agent 自愈：${e.message}`)
+  lineReport = await agent(
+    `执行 \`wc -l ${notesPath}\` 失败了：${e.message}\n` +
+      '请先用 Glob/Read 定位 notes.md 的真实位置，再统计它的行数，把结果说出来。',
+    { label: 'recover-count', allowedTools: ['Read', 'Glob', 'Bash'] },
+  )
+}
+
+// ── 3. 守门校验：agent 说做完了不算数 ───────────────────────────────
+const gate = await verify(`file_exists:${notesPath}`)
+if (!gate.passed) {
+  throw new Error(`调研笔记 ${notesPath} 未生成 —— 检查调研步骤。${gate.summary}`)
+}
+
+echo(`✅ 调研完成 → ${notesPath}`)
+echo(`   行数统计：${String(lineReport).trim().split('\n')[0]}`)
+return { notes: notesPath, lineReport, summary: notes }
+}

package/workflows/e2e-capabilities/workflow.mjs

@@ -0,0 +1,102 @@
+export const meta = {
+  apiVersion: 2,
+  description:
+    'E2E：一次跑通 schema / pipeline / isolated 三项新能力（model 需本机配置，故不在此断言）',
+  inputs: [
+    { name: 'topic', required: true, greedy: true },
+    { name: 'items', type: 'number', default: 10 },
+  ],
+  artifacts: [],
+}
+
+export default async function run(wf) {
+const { values: args } = wf.input
+const { generate: llm, agent } = wf.model
+const log = (message) => wf.output.progress({ phase: 'workflow', status: 'update', message: String(message) })
+const echo = wf.output.message
+
+// 这条工作流的存在意义是「引擎自己的问题」和「模型的问题」分开：
+// 它只用最简单的生成任务，跑不通就一定是引擎的锅。
+// ⚠️ items 默认 10 > 并发上限 8 —— 扇出规模必须超过闸门才测得到车道分配。
+
+const N = Number(args.items ?? 10)
+log(`扇出 ${N} 项`)
+
+const SCORE = {
+  type: 'object',
+  required: ['index', 'score', 'verdict'],
+  properties: {
+    index: { type: 'number' },
+    score: { type: 'number', minimum: 0, maximum: 10 },
+    verdict: { enum: ['keep', 'drop'] },
+  },
+}
+
+// pipeline：每项独立走两个阶段，阶段之间无屏障。
+// 每个 llm 都 isolated —— 逐项打分不需要看前文，产出也不该污染主线。
+const batch = await wf.flow.pipeline(Array.from({ length: N }, (_, i) => i), {
+  label: '结构化打分',
+  errorMode: 'collect',
+  stages: [
+  // 阶段 1：结构化打分（schema 保证拿到的是对象，不是要自己 parse 的字符串）
+  (_prev, item) =>
+    llm(
+      `给「${args.topic}」的第 ${item} 个方面打分。` +
+        `只输出 JSON：{"index":${item},"score":0到10的数字,"verdict":"keep"或"drop"}`,
+      { schema: SCORE, label: `打分 #${item}`, isolated: true },
+    ),
+
+  // 阶段 2：确定性归一（纯 JS，不烧 token）
+  (s, _item, i) => ({ ...s, rank: i }),
+]})
+
+const ok = batch.results.filter((entry) => entry.ok).map((entry) => entry.value)
+if (ok.length === 0) throw new Error('全部项都失败了 —— 引擎或 provider 有问题')
+
+// 验收：schema 真的生效了吗（拿到的必须是对象且字段齐全）
+for (const s of ok) {
+  if (typeof s !== 'object' || typeof s.score !== 'number') {
+    throw new Error(`schema 未生效：拿到 ${JSON.stringify(s)}`)
+  }
+  if (s.verdict !== 'keep' && s.verdict !== 'drop') {
+    throw new Error(`enum 校验未生效：verdict=${s.verdict}`)
+  }
+}
+
+const keep = ok.filter((s) => s.verdict === 'keep').length
+
+// ── 带工具的 agent + schema（与上面的 llm 零工具路径是**两条不同的路**）────
+// agent 的工具循环里**不能**开原生 response_format（它要求每条 assistant 消息
+// 都是 JSON，与 tool_calls 互斥），所以引擎走「带工具干完活，再零工具整形」。
+//
+// 这条单独验的理由：整形轮的 history 里带着 tool_calls / tool 消息，而个别
+// provider 会因此拒绝 response_format —— 单测用 stub 只能证明引擎的分派对，
+// 证明不了真实 provider 认这个组合。`plan` 阶段 6 的独立验收走的正是这条路径。
+const REPORT = {
+  type: 'object',
+  required: ['file_count', 'verdict'],
+  properties: {
+    file_count: { type: 'number', minimum: 0 },
+    verdict: { enum: ['ok', 'empty'] },
+  },
+}
+const report = await agent(
+  '用 Glob 查一下当前工作目录下有多少个 .md 文件（只数数量，不要读内容）。' +
+    '然后只输出 JSON：{"file_count":数字,"verdict":"ok"（有文件）或"empty"（没有）}',
+  { label: '带工具+schema', allowedTools: ['Glob'], maxTurns: 5, schema: REPORT },
+)
+if (typeof report !== 'object' || typeof report.file_count !== 'number') {
+  throw new Error(`带工具路径的 schema 未生效：拿到 ${JSON.stringify(report)}`)
+}
+if (report.verdict !== 'ok' && report.verdict !== 'empty') {
+  throw new Error(`带工具路径的 enum 未生效：verdict=${report.verdict}`)
+}
+
+echo(
+  `✅ 能力冒烟通过：${ok.length}/${N} 项打分成功（keep ${keep} / drop ${ok.length - keep}），` +
+    `schema 返回对象、pipeline 扇出、isolated 未污染主线；` +
+    `带工具的 agent+schema 也通（数到 ${report.file_count} 个 .md，verdict=${report.verdict}）`,
+)
+
+return { total: N, ok: ok.length, keep, toolSchema: report.verdict }
+}

package/workflows/e2e-llm/workflow.mjs

@@ -0,0 +1,52 @@
+export const meta = {
+  apiVersion: 2,
+  description: 'E2E：走一次 llm() 与一次 agent()，验证 LLM 路径与目标锚注入',
+  inputs: [{ name: 'topic', required: true, greedy: true }],
+  artifacts: [],
+}
+
+export default async function run(wf) {
+const { values: args } = wf.input
+const { sessionId: session, taskId: task } = wf.runtime
+const { generate: llm, agent } = wf.model
+const { exists } = wf.fs
+const echo = wf.output.message
+const declareArtifact = wf.output.artifact
+const log = (message) => wf.output.progress({ phase: 'workflow', status: 'update', message: String(message) })
+
+// 与 e2e-smoke 互补：那条一次 LLM 都不调（隔离引擎问题），这条专测 LLM 通路。
+// 刻意做到最小 —— 只要能证明「调得通、拿得到文本、目标锚注入了」就够，不烧 token。
+
+log('测试 llm() 通路')
+
+// llm()：纯文本生成，不给任何工具。弱模型也能跑。
+const oneLiner = await llm(
+  `用一句不超过 20 个字的话概括「${args.topic}」。只输出那句话，不要任何解释。`,
+)
+
+if (!oneLiner || !oneLiner.trim()) {
+  throw new Error('llm() 返回空文本 —— LLM 通路有问题')
+}
+echo(`llm() 产出：${oneLiner.trim()}`)
+
+// agent()：可以用工具。这里只给它 Write，验证 allowedTools 收敛真的生效。
+const outDir = `out/e2e-llm/${session}/${task}`
+const outPath = `${outDir}/note.md`
+
+await agent(
+  `把这句话写进文件 ${outPath}：\n\n${oneLiner.trim()}\n\n写完即可，不要做别的。`,
+  { label: 'write-note', allowedTools: ['Write'], maxTurns: 6 },
+)
+declareArtifact(outPath)
+
+// 确定性验收：agent 说做完了不算数，得文件真在
+if (!(await exists(outPath))) {
+  throw new Error(
+    `agent 宣称写完了但 ${outPath} 不存在 —— 这正是 announce-not-do 烂尾，` +
+      '确定性验收就是为了抓它',
+  )
+}
+
+echo(`✅ LLM 通路通过 → ${outPath}`)
+return { note: outPath }
+}

package/workflows/e2e-smoke/workflow.mjs

@@ -0,0 +1,59 @@
+export const meta = {
+  apiVersion: 2,
+  description: 'E2E 冒烟：只走确定性路径（tool/verify/exists/echo），零 LLM 零网络',
+  inputs: [
+    { name: 'name', required: true, greedy: true },
+    { name: 'times', type: 'number', default: 3 },
+  ],
+  // 静态声明只能写死路径；带 ${session}/${task} 的实际产物在下面用
+  // declareArtifact() 运行时登记 —— meta 是执行前静态求值的纯字面量，写不出插值。
+  artifacts: [],
+}
+
+export default async function run(wf) {
+const { values: args } = wf.input
+const { sessionId: session, taskId: task } = wf.runtime
+const { call: tool } = wf.tools
+const { exists } = wf.fs
+const { verify } = wf.check
+const echo = wf.output.message
+const declareArtifact = wf.output.artifact
+const log = (message) => wf.output.progress({ phase: 'workflow', status: 'update', message: String(message) })
+
+// 这条工作流一次 LLM 都不调：把「引擎自己的问题」和「模型的问题」分开。
+// 跑不通就一定是引擎的锅。
+
+log('开始冒烟')
+
+const times = Number(args.times ?? 3)
+const lines = []
+for (let i = 1; i <= times; i++) {
+  // 原生 for 循环 —— 代码编排取代 DSL 的地方，引擎不需要 loop 这个概念
+  lines.push(`${i}. 你好，${args.name}！`)
+}
+
+// 推荐写法：产物路径带 ${session}/${task} 两级命名空间。
+//   session 隔离并行会话，task 隔离「同一会话里换了个目标」。
+// 不带命名空间也能跑（引擎会在换任务时先把旧产物归档进 .trash/ 再清理），
+// 但那是安全网不是设计 —— 能命名空间就命名空间。
+const outDir = `out/e2e-smoke/${session}/${task}`
+const outPath = `${outDir}/greeting.md`
+
+await tool('Write', {
+  file_path: outPath,
+  content: `# 冒烟测试\n\nsession=${session}\ntask=${task}\n\n${lines.join('\n')}\n`,
+})
+declareArtifact(outPath)
+
+// 验收必须和写入锚在同一个 cwd（引擎红线）—— 这里顺带把它测到
+if (!(await exists(outPath))) {
+  throw new Error(`写完了却查不到 ${outPath} —— 说明写入与验收的 cwd 不一致`)
+}
+
+const v = await verify(`file_contains:${outPath}:你好`)
+if (!v.passed) throw new Error(`内容校验失败：${v.summary}`)
+
+echo(`✅ 冒烟通过：${times} 行 → ${outPath}`)
+
+return { lines: times, path: outPath }
+}

package/workflows/e2e-vision-schema/README.md

@@ -0,0 +1,48 @@
+# e2e-vision-schema —— 识图 + 结构化输出的组合探针
+
+## 跑之前必须满足（否则不是引擎的问题）
+
+1. **基座模型支持视觉**。`ConfigService.provider()` 解析出的模型 `supportsVision`
+   必须为 true，否则图片送不进去，会在「不同的图给出了完全相同的描述」那条断言上失败。
+2. **有一个装着图片的目录**（png/jpg/jpeg，递归深度 ≤ 4）。**素材要自备** ——
+   这条工作流不附带图片，`dir` 是必填参数。
+3. **POSIX shell 可用**（Git Bash / mac / Linux）。脚本用 `find … | sort | head`
+   列素材。⚠️ win32 上 Bash 工具找不到 Git Bash 时会**回落 cmd**，而 cmd 的 `find`
+   是搜文本的完全不同的命令 —— 那种机器上这条探针跑不了（绿色版 U 盘场景要留意）。
+
+## 跑法
+
+```bash
+minimal-agent -p "/workflow e2e-vision-schema <图片目录> --input limit=10"
+```
+
+`dir` 是贪婪首参，所以 `limit` **必须**走 `--input limit=N`，不能当位置参数给。
+
+⚠️ **`limit` 默认 10 是刻意的：它必须 > 并发上限 8。** 扇出规模不超过闸门时，
+所有项同时起跑、完成顺序恰好稳定，车道分配根本没被考验到 —— 用例恒绿等于没测。
+
+## 它锁的是什么
+
+`illustrate` 阶段 5（逐图识图打分）依赖 `images` + `schema` + `isolated` + `pipeline`
+四者叠加。但 `illustrate` 的阶段 1-3 靠 WebBrowser 的 eval 抓图，**需要「设置 → 浏览器」
+里开启 Developer Mode 并把搜索站点加白名单** —— 没有那个授权就到不了阶段 5。
+
+于是「引擎的问题」和「授权/网络的问题」会纠缠在一起：抓不到图时你没法判断
+images+schema 到底通没通。这条探针把素材换成本地文件，**跑不通就一定是引擎或
+provider 的锅**。改引擎的结构化输出 / 车道 / 隔离逻辑之后，直接跑它。
+
+## 验收判据（为什么不只看「跑完没报错」）
+
+- `schema` 生效：逐条断言字段类型、`minimum/maximum`、`enum`。
+- **模型真看见了图**：`schema` 只能保证「形状对」—— 一个完全没收到图片的模型照样
+  能吐出合法 JSON。所以额外断言「N 张不同的图必须给出 > 1 种 subject」。
+- `pipeline` 车道：扇出 > 并发上限，账本里每项应是独立车道 `main/p1i<下标>`。
+
+## 实测记录
+
+- 2026-08-19，豆包 `doubao-seed-2-1-turbo-260628`（OpenAI 格式），10 张 UI 截图：
+  10/10 成功、10 种不同描述、schema 与 enum 全部生效。
+- 同日 resume 验证：把账本截断到 6 条（保留的是 i2/i3/i5/i6/i7 五条**不连续**车道）
+  后重跑 —— 引擎报「重放 6 次 / 上次账本 6 条」，且输出自证：那 5 项描述**逐字不变**，
+  被截断的 5 项描述全变（其中一项 `kind` 从 `screenshot` 变成 `diagram`）。
+

package/workflows/e2e-vision-schema/workflow.mjs

@@ -0,0 +1,149 @@
+export const meta = {
+  apiVersion: 2,
+  description:
+    'E2E：识图（images 通道）+ 结构化输出（schema）+ 上下文隔离（isolated）+ 并发扇出（pipeline）四者叠加是否真的能通 —— illustrate 阶段 5 依赖的正是这条组合路径',
+  inputs: [
+    {
+      name: 'dir',
+      type: 'resource',
+      required: true,
+      greedy: true,
+      allowDirectory: true,
+      allowFile: false,
+      multiple: true,
+      materialize: 'directory',
+      accepts: ['image/*'],
+      attachmentFallback: true,
+      description: '图片素材目录（递归找 png/jpg）',
+    },
+    { name: 'limit', type: 'number', default: 10, description: '最多取几张' },
+  ],
+  artifacts: [],
+}
+
+export default async function run(wf) {
+const { values: args } = wf.input
+const { generate: llm } = wf.model
+const { shell: sh } = wf.exec
+const echo = wf.output.message
+const log = (message) => wf.output.progress({ phase: 'workflow', status: 'update', message: String(message) })
+
+// ============================================================
+//  为什么单独有这条探针，而不是直接跑 illustrate：
+//
+//  illustrate 的阶段 1-3 靠 WebBrowser 的 eval 从搜索结果页抽图 URL，
+//  **需要「设置 → 浏览器」里开启 Developer Mode 并把站点加白名单**。
+//  没有那个授权就到不了阶段 5 —— 而阶段 5 才是新能力所在。
+//
+//  于是「引擎的问题」和「授权/网络的问题」会纠缠在一起：抓不到图时你
+//  没法判断 images+schema 到底通没通。这条探针把素材换成本地文件，
+//  跑不通就一定是引擎或 provider 的锅。
+//
+//  ⚠️ limit 默认 10 > 并发上限 8 —— 扇出规模必须超过闸门，否则所有项
+//     同时起跑、顺序恰好稳定，车道分配根本没被考验到。
+// ============================================================
+
+const dir = String(args.dir)
+const limit = Number(args.limit ?? 10)
+
+// sort 是为**指纹稳定**：find 的输出顺序不保证，顺序一变图片路径就换车道，
+// 断点续跑会整片失配。确定性纪律不只管 Date.now()。
+const found = await sh(
+  `find "${dir}" -maxdepth 4 \\( -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' \\) | sort | head -${limit}`,
+)
+const files = found.stdout
+  .split('\n')
+  .map((s) => s.trim())
+  .filter(Boolean)
+
+if (files.length === 0) {
+  throw new Error(`${dir} 下没找到任何 png/jpg/jpeg（find 退出码 ${found.exitCode}）`)
+}
+log(`素材 ${files.length} 张（并发上限 8，扇出 ${files.length} 项）`)
+
+const VERDICT = {
+  type: 'object',
+  required: ['subject', 'has_text', 'quality', 'kind'],
+  properties: {
+    subject: { type: 'string' },
+    has_text: { type: 'boolean' },
+    quality: { type: 'number', minimum: 0, maximum: 10 },
+    kind: { enum: ['screenshot', 'photo', 'diagram', 'other'] },
+  },
+}
+
+const batch = await wf.flow.pipeline(files, {
+    label: '视觉结构化识别',
+    errorMode: 'collect',
+    stages: [
+
+    // 阶段 1：识图 + 结构化。四项能力在这一个调用里全用上了。
+    (path, _item, i) =>
+      llm(
+        `下方附上一张图片。请**只看这张图**客观描述：
+- subject：一句话说明画的是什么（中文）
+- has_text：图里有没有可读的文字
+- quality：0-10 的观感质量
+- kind：screenshot / photo / diagram / other 四选一
+
+只输出 JSON 对象本身，不要 markdown 代码块、不要解释。`,
+        {
+          label: `识图 #${i}`,
+          images: [{ source: path, detail: 'high' }],
+          schema: VERDICT,
+          isolated: true,
+        },
+      ),
+
+    // 阶段 2：确定性归一（纯 JS，不烧 token）
+    (v, path, i) => ({ ...v, path, index: i }),
+  ]})
+const results = batch.results.filter((entry) => entry.ok).map((entry) => entry.value)
+
+if (results.length === 0) {
+  throw new Error('全部识图都失败了 —— images 通道或 schema 路径有问题')
+}
+
+// ── 逐条验收：schema 到底生效了没 ────────────────────────────────────
+// 这几条断言是这条探针的全部意义。拿到字符串、拿到缺字段的对象、拿到
+// enum 之外的值 —— 任何一样都说明 schema 没起作用，而**不是**模型答得不好。
+for (const r of results) {
+  if (typeof r !== 'object') {
+    throw new Error(`schema 未生效：拿到的不是对象 —— ${JSON.stringify(r)}`)
+  }
+  if (typeof r.subject !== 'string' || r.subject.length === 0) {
+    throw new Error(`schema 未生效：subject 不是非空字符串 —— ${JSON.stringify(r)}`)
+  }
+  if (typeof r.has_text !== 'boolean') {
+    throw new Error(`schema 未生效：has_text 不是布尔 —— ${JSON.stringify(r)}`)
+  }
+  if (typeof r.quality !== 'number' || r.quality < 0 || r.quality > 10) {
+    throw new Error(`schema 的 minimum/maximum 未生效：quality=${r.quality}`)
+  }
+  if (!['screenshot', 'photo', 'diagram', 'other'].includes(r.kind)) {
+    throw new Error(`enum 未生效：kind=${r.kind}`)
+  }
+}
+
+// ── 识图真的看见图了吗 ───────────────────────────────────────────────
+// schema 能保证「形状对」，保证不了「模型真看见了图」—— 一个瞎猜的模型
+// 也能吐出合法 JSON。判据：不同图片必须给出不同的 subject。全都一样
+// 说明图片压根没送到（或送的是同一张）。
+const subjects = new Set(results.map((r) => r.subject))
+if (results.length > 1 && subjects.size === 1) {
+  throw new Error(
+    `${results.length} 张不同的图给出了完全相同的 subject「${results[0].subject}」—— ` +
+      'images 通道很可能没真的把图送到模型。',
+  )
+}
+
+echo(
+  `✅ 视觉 + 结构化组合通过：${results.length}/${files.length} 张识图成功，` +
+    `${subjects.size} 种不同描述（schema 校验全过、enum 生效、isolated 未污染主线）`,
+)
+for (const r of results) {
+  echo(`   · #${r.index} [${r.kind}] ${r.has_text ? '有字' : '无字'} 质量${r.quality} — ${r.subject}`)
+}
+
+return { total: files.length, ok: results.length, distinct: subjects.size }
+}

package/workflows/e2e-write-greet/workflow.mjs

@@ -0,0 +1,37 @@
+export const meta = {
+  apiVersion: 2,
+  description: 'E2E 极简工作流，证明 /workflow CLI 端到端通（无 LLM 无网络）',
+  inputs: [{ name: 'topic', required: true, greedy: true }],
+  artifacts: [],
+}
+
+export default async function run(wf) {
+const { values: args } = wf.input
+const { sessionId: session, taskId: task } = wf.runtime
+const { call: tool } = wf.tools
+const { verify } = wf.check
+const echo = wf.output.message
+const declareArtifact = wf.output.artifact
+
+// 自 e2e-write-greet.yaml 迁移。原来 3 个 step（tool → verify → assert）在代码形态里
+// 就是三行：写、查、断言。yaml 里的 capture 机制不再需要 —— tool() 直接返回值。
+
+const outPath = `out/e2e-write-greet/${session}/${task}/note.txt`
+
+const writeResult = await tool('Write', {
+  file_path: outPath,
+  content: `topic=${args.topic} ok`,
+})
+declareArtifact(outPath)
+
+const v = await verify(`file_exists:${outPath}`)
+if (!v.passed) throw new Error(`note.txt 未落盘：${v.summary}`)
+
+// 原 yaml 的 assert `length(note_body) > 0` —— capture 绑的是 tool 的回执文本
+if (!writeResult || writeResult.length === 0) {
+  throw new Error('tool(Write) 没有返回回执文本')
+}
+
+echo(`✅ ${outPath}`)
+return { path: outPath }
+}

package/workflows/file-census/README.md

@@ -0,0 +1,14 @@
+# file-census
+
+## 意图
+TODO：这个工作流解决什么问题，为什么值得单独存在。
+
+## 输入
+TODO：每个 input 的含义与示例。
+
+## 产物
+TODO：产出什么文件、在哪。
+
+## 已知坑
+TODO：跑的过程中踩到的、下次要注意的。写在这里比写在脑子里管用。
+

package/workflows/file-census/scripts/.gitkeep

@@ -0,0 +1,2 @@
+# 确定性辅助脚本放这里，用 sh(`node scripts/x.mjs`) 调。一律写 .mjs，不要 .ts / .py。
+

package/workflows/file-census/workflow.mjs

@@ -0,0 +1,110 @@
+export const meta = {
+  apiVersion: 2,
+  description: '给定一个目录路径，统计各种文件扩展名的数量，产出一份 markdown 报告',
+
+  inputs: [
+    { name: 'dir', type: 'resource', required: true, greedy: true, allowFile: false, allowDirectory: true, multiple: true, materialize: 'directory', attachmentFallback: true, description: '要统计的目录路径或附件目录（相对工作目录）' },
+  ],
+
+  artifacts: [],
+}
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+export default async function run(wf) {
+const { values: args } = wf.input
+const { sessionId: session, taskId: task } = wf.runtime
+const { call: tool } = wf.tools
+const { exists } = wf.fs
+const { verify } = wf.check
+const echo = wf.output.message
+const declareArtifact = wf.output.artifact
+const log = (message) => wf.output.progress({ phase: 'workflow', status: 'update', message: String(message) })
+
+// ⚠️ 目录名就是工作流名，这里不写 name。
+// V2 是真实 ESM：确定性纯计算直接使用上面的 node:fs/node:path import。
+// 完整能力见 skills/workflow-creator/references/api.md
+
+const OUT = `out/file-census/${session}/${task}/report.md`
+
+log(`统计目录：${args.dir}`)
+
+// ── 步骤 1：确认目录存在 ─────────────────────────────────────────────
+const dirExists = await exists(args.dir)
+if (!dirExists) throw new Error(`目录不存在：${args.dir}`)
+
+// ── 步骤 2：同进程原生 ESM 统计扩展名（确定性，跨平台） ──────────────
+const root = String(args.dir);
+const counts = {};
+let totalFiles = 0;
+let totalDirs = 0;
+
+function walk(dir) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) { return; }
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) { totalDirs++; walk(full); }
+    else if (entry.isFile()) {
+      totalFiles++;
+      const ext = path.extname(entry.name).toLowerCase() || '(无扩展名)';
+      counts[ext] = (counts[ext] || 0) + 1;
+    }
+  }
+}
+
+walk(root);
+
+// 按数量降序
+const sorted = Object.entries(counts).sort((a, b) => b[1] - a[1]);
+const stats = { totalFiles, totalDirs, sorted };
+
+// ── 步骤 3：生成 markdown 报告 ────────────────────────────────────────
+const lines = []
+lines.push('# 文件扩展名统计报告')
+lines.push('')
+lines.push(`- **统计目录**：\`${args.dir}\``)
+lines.push(`- **文件总数**：${stats.totalFiles}`)
+lines.push(`- **目录总数**：${stats.totalDirs}`)
+lines.push(`- **扩展名种类**：${stats.sorted.length}`)
+lines.push('')
+lines.push('## 扩展名分布')
+lines.push('')
+lines.push('| 扩展名 | 文件数 | 占比 |')
+lines.push('|--------|--------|------|')
+
+for (const [ext, count] of stats.sorted) {
+  const pct = stats.totalFiles > 0 ? ((count / stats.totalFiles) * 100).toFixed(1) + '%' : '0%'
+  lines.push(`| \`${ext}\` | ${count} | ${pct} |`)
+}
+
+lines.push('')
+lines.push('> 已自动排除 `node_modules` 和 `.git` 目录。')
+lines.push('')
+
+const reportContent = lines.join('\n')
+
+await tool('Write', {
+  file_path: OUT,
+  content: reportContent,
+})
+
+declareArtifact(OUT)
+
+// ── 步骤 4：确定性验收（不用 agent，直接 verify） ─────────────────────
+const v = await verify([
+  `file_exists:${OUT}`,
+  `file_contains:${OUT}:文件扩展名统计报告`,
+  `file_contains:${OUT}:扩展名分布`,
+])
+if (!v.passed) throw new Error(`验收失败：${v.summary}`)
+
+// ── 收尾：echo 是 -p 模式 result 字段的唯一来源 ──────────────────────
+echo(`✅ 统计完成 → ${OUT}`)
+echo(`   文件总数：${stats.totalFiles}，扩展名种类：${stats.sorted.length}`)
+echo(`   最多的扩展名：${stats.sorted[0]?.[0] ?? '无'} (${stats.sorted[0]?.[1] ?? 0} 个)`)
+
+return { path: OUT, totalFiles: stats.totalFiles, extCount: stats.sorted.length }
+}