agenttaskflow 0.0.1 → 0.4.2

package/docs/workflow-authoring.md

@@ -0,0 +1,80 @@
+# 编写 AgentTaskFlow 工作流
+
+## 使用正常 TypeScript
+
+直接写 `.ts`，用 tsx 或自己的 TypeScript 工具链执行。没有流程语法、解析器或 next/goto 调度器。默认 API 是同步的，不需要 async/await。
+
+```ts
+import { flow } from 'agenttaskflow';
+import { REVIEW, repair } from './common.js';
+
+flow('cxh', step => {
+  // 先产生待审查的方案。
+  step('给出方案');
+
+  // 每轮按真实结果决定是否继续，不让模型操纵整个流程。
+  for (let round = 0; round < 3; round++) {
+    if (step.check(REVIEW)) break;
+    if (round === 2) throw new Error('审查仍未通过');
+    repair(step);
+  }
+});
+```
+
+默认使用 `flow(command, step => { ... })`。`step(prompt)` 返回文本；`step.check(prompt)` 返回布尔值；`step.choose(prompt, ['pass', 'revise'])` 返回所选字符串。常见流程不需要类型声明或 schema。步骤名自动取提示词第一行，因此第一行应简短说明任务。
+
+共享模块接收现有 step，不要每步创建 flow。这样上下文和进程都连续。主流程每一阶段前必须有一句有意义的注释。需要自定义步骤名或 checkpoint 时使用完整的 Agent/withAgent API。
+
+## 提示词放在代码中
+
+**所有提示词直接写在流程 `.ts` 或共享 `.ts` 模块的字符串变量/函数中。不要把各种文字拆成很多小文本文件，不要让 agent 每一步去读提示词文件。**
+
+共享模块例子：
+
+```ts
+import type { Step } from 'agenttaskflow';
+
+export const REVIEW = `检查上一轮成果是否满足最初的全部要求。`;
+export const REPAIR = `根据上一轮意见修订，并报告真实修改。`;
+export function repair(step: Step) {
+  return step(REPAIR);
+}
+```
+
+只把完全相同的通用内容抽到 shared/common 模块，流程特有的提示词留在该流程文件。复用用普通 import，不设计额外 include 指令。
+
+## 结果和业务条件
+
+简单判断用 `step.check` 或 `step.choose`，库自动定义和校验结果格式。复杂结果才使用 `step.data(prompt, schema)`，用 Zod 的 `z.strictObject`、明确字段和枚举定义结构；也可以用完整 API 的 `agent.run(prompt, { schema })`。返回值已经解析，不需要手动 JSON.parse。模型输出不合法时库会在同一会话补答，默认最多两次。进程故障和权限拒绝不会当作格式错误重试。
+
+类型正确不代表业务合格。例如至少 15 个独立实验，应在 TypeScript 中维护 Map，以实验 ID 去重，验证证据再计数。循环要设定上限，耗尽后明确报错。不要只接受模型一句“已完成 15 个”。
+
+复杂条件使用 if/else、switch 或函数，不能用模型返回 next 字符串来决定任意跳转。模型可以返回业务事实或判定（pass/revise），真正的分支由代码决定。
+
+## 同步与异步
+
+默认使用 flow，step 同步返回，自动关闭进程。完整 API 的 Agent/withAgent、run 和 close 也同步。库内部的工作线程负责异步通信，实时输出不会停止。不需要额外写 main async 函数或 asyncio.run。
+
+若业务本身需要并行 agent 或嵌入服务器，可显式使用 AsyncAgent/withAsyncAgent。不要把 async 回调传给同步 flow/withAgent。普通 fetch 等 API 的异步语义保持原状。
+
+同步事件回调保持简短，不要重新调用当前 agent，不要依赖主线程 setTimeout 在 run 等待中触发任务控制。需要应用级 AbortSignal 时使用 AsyncAgent。
+
+## 中断和恢复
+
+flow 和 withAgent 保证正常结束或异常时 close。需要 checkpoint 时使用 withAgent；显式 runId 和 workflowVersion 用于下次创建 Agent 恢复逻辑会话；loadCheckpoint/saveCheckpoint 记录业务阶段。checkpoint 输入应包含主题、提示词版本和关键参数。
+
+恢复会话不恢复 JavaScript 调用栈，也不自动跳过 run。重复调用就是重复发任务。先核实已有产物，避免中断时已产生的操作被重做。只有业务验证通过后才保存 checkpoint。
+
+## 长文档迁移
+
+如果要求“不遗漏、原文原样”，不要概括或删减指导文档。将完整内容放进 TS 多行字符串，按阶段引用，并建立原文到提示词和代码检查的对照。模板字符串里的反引号、反斜杠和 `${...}` 必须正确处理，确保运行时字符串与原文一致。
+
+每个分支、重试上限、合格条件和归档要求都要落实到普通 TypeScript 结构。不要把几千行全部一次发出去后宣称已经实现精确控制。
+
+## 测试
+
+先用假 CLI 检查分支、补答、超时、相同 PID 和上下文，再运行小型真实 smoke。不要直接用昂贵实验验证调度。所有流程输入输出默认可见，补答也会显示输入和次数。
+
+```bash
+npm run smoke -- --provider codex --command cxh --rounds 5
+```

package/examples/common.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+
+// 提示词直接写在 TypeScript 模块中，复用使用普通 import。
+export const REMEMBER = (token: string) => `记住标记 ${token}，后续步骤会让你回忆。
+不要读写文件，不要调用工具。现在只回答“已记住”。`;
+export const RECALL = (round: number) => `这是第 ${round} 轮测试。
+从当前对话回忆最开始给你的标记。不要读写文件，不要调用工具。
+返回 token 和 round 两个字段，round 必须是 ${round}；不记得就返回 UNKNOWN，不要猜测。`;
+export const Recall = z.strictObject({ token: z.string(), round: z.number().int() });

package/examples/multi-fields.ts

@@ -0,0 +1,45 @@
+import { flow } from 'agenttaskflow';
+import { z } from 'zod';
+
+// 一次回答包含四个字段，库负责解析 JSON 和校验类型。
+const Review = z.strictObject({
+  passed: z.boolean().describe('方案是否满足全部要求'),
+  score: z.number().int().min(0).max(100).describe('完整性评分，0 到 100'),
+  problems: z.array(z.string()).describe('未满足的要求；没有问题时返回空数组'),
+  suggestion: z.string().describe('具体修改建议；通过时说明无需修改'),
+});
+
+const REVIEW = `审查当前待办工具方案
+要求：支持添加任务、完成任务、列出任务、本地持久化，以及文件损坏时的错误处理。
+逐项核对当前方案，返回是否通过、评分、问题列表和修改建议。
+只有全部要求都满足时 passed 才能为 true。只审查方案，不读写文件，不执行实现。`;
+
+flow('cxh', step => {
+  // 故意提供不完整的初稿，展示多个返回字段如何影响后续流程。
+  step(`记住待办工具初稿
+支持添加任务和列出任务，数据暂时保存在内存中。
+这只是初稿，请先原样复述，不要补全，不读写文件。`);
+
+  // 最多审查三轮；直接读取对象字段，不需要 JSON.parse。
+  for (let round = 1; round <= 3; round++) {
+    const { passed, score, problems, suggestion } = step.data(REVIEW, Review);
+
+    console.log(`\n第 ${round} 轮：通过=${passed}，评分=${score}/100`);
+    console.log('问题列表：', problems);
+    console.log('修改建议：', suggestion);
+
+    // 同时检查通过标记和问题列表，避免带着未解决的问题继续。
+    if (passed && problems.length === 0) break;
+    if (round === 3) throw new Error('三轮审查后仍未通过，请检查上面的结果');
+
+    // 将本轮返回的多个字段用于下一步提示词，仍在同一会话中。
+    step(`修订待办工具方案
+本轮评分：${score}/100。
+问题列表：${JSON.stringify(problems)}。
+修改建议：${suggestion}
+请补全所有要求，并输出完整的新方案。只在对话里输出，不读写文件。`);
+  }
+
+  // 审查通过后汇总方案，避免把设计完成误报为代码实现完成。
+  step('总结最终通过审查的方案，并明确这只是设计方案，尚未实现代码。');
+});

package/examples/review.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { withAgent } from 'agenttaskflow';
+
+const DESIGN = `设计一个本地待办事项命令行工具。
+要求支持添加、完成、列表、持久化、错误处理和自动化测试。只给方案，不修改文件。`;
+const REVIEW = `检查当前方案是否满足最初所有要求。返回 verdict=pass 或 revise，以及 reason。`;
+const REVISE = `根据上一轮审查意见补全方案。只在对话中返回完整修订方案。`;
+const Review = z.strictObject({ verdict: z.enum(['pass', 'revise']), reason: z.string() });
+
+withAgent({ command: 'cxh' }, agent => {
+  // 建立方案。
+  agent.run(DESIGN, { name: '生成方案' });
+
+  // 审查通过后退出循环，否则修订，最多三轮。
+  for (let round = 1; round <= 3; round++) {
+    const review = agent.run(REVIEW, { name: `审查 ${round}`, schema: Review });
+    if (review.verdict === 'pass') break;
+    if (round === 3) throw new Error('三轮审查仍未通过');
+    agent.run(REVISE, { name: `修订 ${round}` });
+  }
+
+  // 前置检查通过后再输出汇总。
+  agent.run('总结最终方案和已修复的问题，不要声称已实现代码。', { name: '最终汇总' });
+});

package/examples/simple.ts

@@ -0,0 +1,16 @@
+import { flow } from 'agenttaskflow';
+
+flow('cxh', step => {
+  // 先生成方案，只在对话里工作，不修改文件。
+  step('设计一个本地待办工具，只给方案。要求支持添加、完成、列表、本地保存和错误处理。');
+
+  // 不合格就修订，最多检查三轮。
+  for (let i = 0; i < 3; i++) {
+    if (step.check('当前方案是否满足最初的全部要求？')) break;
+    if (i === 2) throw new Error('三轮后仍未通过');
+    step('根据刚才的检查补全方案。只在对话里输出，不修改文件。');
+  }
+
+  // 前置检查通过后汇总。
+  step('总结最终方案，不要声称已经实现代码。');
+});

package/examples/smoke.ts

@@ -0,0 +1,41 @@
+import { parseArgs } from 'node:util';
+import { randomUUID } from 'node:crypto';
+import { withAgent, type Provider } from 'agenttaskflow';
+import { REMEMBER, RECALL, Recall } from './common.js';
+
+const { values } = parseArgs({ options: {
+  provider: { type: 'string', default: 'codex' }, command: { type: 'string' },
+  'command-arg': { type: 'string', multiple: true },
+  cwd: { type: 'string', default: process.cwd() }, rounds: { type: 'string', default: '5' },
+  timeout: { type: 'string', default: '600' },
+} });
+const rounds = Number(values.rounds);
+if (!Number.isInteger(rounds) || rounds < 1) throw new Error('--rounds 必须是正整数');
+const token = `ATF-${randomUUID().replaceAll('-', '').slice(0, 12)}`;
+
+try {
+  withAgent({
+    provider: values.provider as Provider,
+    command: [values.command ?? values.provider!, ...(values['command-arg'] ?? [])],
+    cwd: values.cwd, timeoutMs: Number(values.timeout) * 1000,
+  }, agent => {
+    // 先记住随机标记；后续输入不再包含标记，检查上下文是否连续。
+    agent.run(REMEMBER(token), { name: '记住标记' });
+    const pid = agent.pid;
+
+    // 使用普通 for/if 控制流程，每一轮都复用同一进程。
+    for (let round = 1; round <= rounds; round++) {
+      const result = agent.run(RECALL(round), { name: `回忆第 ${round} 轮`, schema: Recall });
+      if (result.token !== token || result.round !== round) throw new Error(`第 ${round} 轮上下文验证失败`);
+      if (!pid || agent.pid !== pid) throw new Error('常驻进程 PID 发生变化');
+      console.log(`PASS ${round}/${rounds} · PID=${pid}`);
+    }
+
+    // 业务自行保存检查点；不自动重放流程。
+    agent.saveCheckpoint('smoke', { rounds }, { token });
+    console.log(`完成 · runId=${agent.runId} · sessionId=${agent.sessionId}`);
+  });
+} catch (error) {
+  console.error(String(error));
+  process.exitCode = 1;
+}

package/package.json

@@ -1,9 +1,22 @@
 {
   "name": "agenttaskflow",
-  "version": "0.0.1",
-  "description": "Persistent task workflows inside your existing Claude Code or Codex session (placeholder, coming soon)",
-  "keywords": ["agent", "workflow", "claude-code", "codex", "llm"],
-  "license": "MIT",
-  "author": "maplewizard",
-  "main": "index.js"
+  "version": "0.4.2",
+  "description": "TypeScript workflows with persistent Codex and Claude Code sessions",
+  "type": "module",
+  "engines": { "node": ">=22.15.0" },
+  "bin": { "atf": "dist/cli.js" },
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "examples", "test", "docs", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.check.json",
+    "test": "npm run build && node --import tsx --test --test-concurrency=1 tests/*.test.ts",
+    "smoke": "tsx examples/smoke.ts",
+    "simple": "tsx examples/simple.ts",
+    "multi-fields": "tsx examples/multi-fields.ts",
+    "flows": "tsx test/run.ts",
+    "prepack": "npm run build"
+  },
+  "dependencies": { "esbuild": "~0.28.0", "proper-lockfile": "^4.1.2", "zod": "^4.0.0" },
+  "devDependencies": { "@types/node": "^22.0.0", "@types/proper-lockfile": "^4.1.4", "tsx": "^4.20.0", "typescript": "^5.9.0" }
 }

package/test/README.md

@@ -0,0 +1,37 @@
+# 真实 agent 流程测试
+
+最近一次真实 cxh 测试：六项全部通过，详细耗时和会话信息见 [RESULTS.md](./RESULTS.md)。
+
+在项目根目录运行，默认使用 cxh。每个测试是普通 TS 函数，提示词直接放在 TS 中，公共逻辑放在 shared.ts。统一入口负责参数、会话和测试汇总。
+
+```bash
+npm run flows -- --list
+npm run flows -- multi-fields
+npm run flows -- branches loop
+npm run flows -- all
+```
+
+| 流程 | 检查内容 | 正常步骤数（不含补答） |
+| --- | --- | --- |
+| multi-fields | 五个字段，含数组和嵌套对象，校验订单计算 | 1 |
+| branches | if/else 两个分支、choose 和 switch | 6 |
+| loop | while 循环，按返回的缺失项逐项修订 | 7 |
+| modules | import 公共函数，同一会话中更新购物清单 | 4 |
+| context | 随机标记跨五轮回忆，核对轮数 | 6 |
+| correction | 本地校验故意拒绝首次结果，验证补答 prompt | 1 + 至少一次补答 |
+
+指定其他命令或 provider：
+
+```bash
+npm run flows -- all --command cx
+npm run flows -- multi-fields --provider claude --command claude
+npx tsx test/run.ts context --command cxh --timeout 600
+```
+
+`--command` 是可执行文件，不是 shell 字符串。固定参数使用重复的 `--command-arg`。`--timeout` 是每个步骤的总超时秒数，默认 600。
+
+每个测试启动独立 agent 会话，测试内多步共用进程和上下文。因此 all 会依次启动六个会话，cxh 的启动/预热也会执行六次。测试调用真实模型，会消耗额度；只要求对话计算和设计，不要求读写业务文件。运行日志仍保存在项目的 .agenttaskflow/。
+
+通过与否由 TS 断言决定，不靠模型自己声称成功。某个测试失败后继续执行其余测试，最后以非零退出码表示存在失败。correction 专门使用故障注入验证补答，其他测试仍可能因模型返回不正确而失败。
+
+这里的 test/ 用于人工运行真实 agent 流程；tests/ 是已有的自动回归测试（npm test），使用假 CLI 验证协议、超时和清理等行为。

package/test/RESULTS.md

@@ -0,0 +1,27 @@
+# 真实流程测试结果
+
+日期：2026-09-26。环境：macOS、Node.js 22.19.0，provider 为 codex，命令为 cxh，包装脚本报告模型 deepseek-v4-flash。
+
+执行：`node --import tsx test/run.ts all --command cxh`（使用 Node.js 22.19.0 的绝对路径）。
+
+结果：**6 通过，0 失败，退出码 0**。累计约 195 秒，包含各测试启动及预热。
+
+| 流程 | 耗时 | PID | 补答 | 核对结果 |
+| --- | --- | --- | --- | --- |
+| multi-fields | 13.1s | 17324 | 0 | 五个字段及嵌套对象匹配，订单总价 11，余额 1 |
+| branches | 40.3s | 22748 | 0 | 库存 0 判 false、库存 3 判 true，枚举选择 pickup |
+| loop | 53.4s | 38505 | 0 | 四轮审查，缺失项依次为 3、2、1、0，三次补充 |
+| modules | 28.2s | 59310 | 0 | 共享模块首次返回 3 件/11 元，更新后返回 4 件/16 元 |
+| context | 38.4s | 69992 | 0 | 五轮回忆均返回正确随机标记与轮数 |
+| correction | 21.4s | 85239 | 1 | 首次本地校验故意拒绝，补答后返回 42 件，验证调用两次 |
+
+每个流程只有一个 process_started 事件，后续步骤及补答没有重新启动进程。会话 ID：
+
+- multi-fields：01a0de5f-a328-7171-981b-861590b0117f
+- branches：01a0de5f-d47a-7d51-9517-4b545678cc3e
+- loop：01a0de60-7007-70a0-a072-1cdcfea7eda9
+- modules：01a0de61-4020-7241-92d3-59f37d1dd194
+- context：01a0de61-afaa-72b1-8716-401923e60d4d
+- correction：01a0de62-475e-76b3-88e0-a337ecb42e1c
+
+测试核对的是结构化结果和流程走向，不评估所有自由文本的事实准确性。例如 branches 中的通知是模型生成的示例文案，不代表实际发生发货。correction 使用故障注入验证补答链路，本次没有自然出现 JSON 格式错误。本次六个流程只运行了 cxh，未运行 Claude Code。

package/test/branches.ts

@@ -0,0 +1,23 @@
+import assert from 'node:assert/strict';
+import type { Step } from 'agenttaskflow';
+import { CHAT_ONLY } from './shared.js';
+
+export default function branches(step: Step) {
+  // 强制覆盖 if 和 else 两条路径，条件有可核实的标准答案。
+  for (const stock of [0, 3]) {
+    const available = step.check(`检查库存\n当前库存 ${stock} 件，是否能立即交付 2 件？${CHAT_ONLY}`);
+    assert.equal(available, stock >= 2);
+    if (available) step(`库存充足\n请给出一条发货通知。${CHAT_ONLY}`);
+    else step(`库存不足\n请给出一条缺货通知，不要声称已经发货。${CHAT_ONLY}`);
+    console.log(`PASS 分支：${available ? '发货' : '缺货'}`);
+  }
+
+  // 三选一返回枚举，由普通 switch 决定走向。
+  const choice = step.choose(`选择运输方式\n当天送达选 express，普通配送选 standard，自取选 pickup。
+客户要求自取，应选择哪个？${CHAT_ONLY}`, ['express', 'standard', 'pickup']);
+  assert.equal(choice, 'pickup');
+  switch (choice) {
+    case 'pickup': step(`自取分支\n请写一条到店取货提醒。${CHAT_ONLY}`); break;
+    default: throw new Error(`走错分支：${choice}`);
+  }
+}

package/test/context.ts

@@ -0,0 +1,18 @@
+import assert from 'node:assert/strict';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import type { Step } from 'agenttaskflow';
+import { CHAT_ONLY } from './shared.js';
+
+export default function context(step: Step) {
+  // 后续提示词不再包含随机标记，实际检查上下文是否保留。
+  const token = randomUUID();
+  step(`记住随机标记\n标记为 ${token}。之后的回答必须原样回忆它。${CHAT_ONLY}`);
+  for (let round = 1; round <= 5; round++) {
+    const result = step.data(`回忆第 ${round} 轮\n返回最初的标记 token，以及当前轮数 round。`,
+      z.strictObject({ token: z.string(), round: z.number().int() }));
+    assert.equal(result.token, token);
+    assert.equal(result.round, round);
+    console.log(`PASS 回忆 ${round}/5`);
+  }
+}

package/test/correction.ts

@@ -0,0 +1,20 @@
+import assert from 'node:assert/strict';
+import { z } from 'zod';
+import type { Step } from 'agenttaskflow';
+import { CHAT_ONLY } from './shared.js';
+
+export default function correction(step: Step) {
+  // 故障注入：故意拒绝首次结构正确的回答，确定性地验证补答链路。
+  // 这不是日常业务写法，也不代表模型首次输出一定有格式问题。
+  let validations = 0;
+  const Result = z.strictObject({ answer: z.number().int(), unit: z.string() })
+    .superRefine((_value, context) => {
+      if (++validations === 1) context.addIssue({ code: 'custom',
+        message: '测试注入：首次结果不予接受。请沿用已经算出的结果，仅重新提交完整 JSON，不重复任务。' });
+    });
+
+  const result = step.data(`计算总件数\n每箱 6 件，共 7 箱。返回 answer 和 unit，unit 必须为“件”。${CHAT_ONLY}`, Result);
+  assert.ok(validations >= 2, '应至少发生一次补答');
+  assert.deepEqual(result, { answer: 42, unit: '件' });
+  console.log(`PASS 补答校验，验证次数=${validations}`);
+}

package/test/loop.ts

@@ -0,0 +1,30 @@
+import assert from 'node:assert/strict';
+import { z } from 'zod';
+import type { Step } from 'agenttaskflow';
+import { CHAT_ONLY } from './shared.js';
+
+export default function loop(step: Step) {
+  // 故意从不完整方案开始，每轮只增加一项，保证循环多次执行。
+  const required = ['添加任务', '完成任务', '本地保存'];
+  const features: string[] = [];
+  let reviews = 0;
+  while (reviews < 4) {
+    const result = step.data(`审查第 ${reviews + 1} 轮\n要求：${JSON.stringify(required)}。
+当前方案仅包含：${JSON.stringify(features)}。不要自行补全。
+按要求的原始顺序，返回缺失项 missing，全部具备时 passed 为 true。${CHAT_ONLY}`,
+      z.strictObject({ passed: z.boolean(), missing: z.array(z.string()) }));
+    reviews++;
+    const expected = required.filter(feature => !features.includes(feature));
+    assert.deepEqual(result.missing, expected);
+    assert.equal(result.passed, expected.length === 0);
+    console.log(`第 ${reviews} 轮，缺失项：`, result.missing);
+    if (result.passed) break;
+
+    // 使用返回数组来决定本轮修订内容，流程状态由 TS 维护。
+    const addition = result.missing[0];
+    step(`补充一项设计\n请描述“${addition}”的设计，只补充这一项。${CHAT_ONLY}`);
+    features.push(addition);
+  }
+  assert.equal(reviews, 4);
+  assert.deepEqual(features, required);
+}

package/test/modules.ts

@@ -0,0 +1,12 @@
+import type { Step } from 'agenttaskflow';
+import { CHAT_ONLY, summarizeCart, assertTotals } from './shared.js';
+
+export default function modules(step: Step) {
+  // 主流程写入上下文，公共模块读取同一个会话里的清单。
+  step(`记住购物清单\n苹果单价 3 元，数量 2。梨单价 5 元，数量 1。${CHAT_ONLY}`);
+  assertTotals(summarizeCart(step), 3, 11);
+
+  // 修改上下文后再次调用同一个公共函数。
+  step(`更新购物清单\n再加 1 个梨，其他不变。${CHAT_ONLY}`);
+  assertTotals(summarizeCart(step), 4, 16);
+}

package/test/multi-fields.ts

@@ -0,0 +1,22 @@
+import assert from 'node:assert/strict';
+import { z } from 'zod';
+import type { Step } from 'agenttaskflow';
+import { CHAT_ONLY } from './shared.js';
+
+export default function multiFields(step: Step) {
+  // 一次返回字符串、数字、布尔值、数组和嵌套对象。
+  const result = step.data(`计算订单\n订单号 ORDER-42，苹果单价 3 元买 2 件，梨单价 5 元买 1 件。
+预算 12 元。按输入顺序返回商品名称，计算是否在预算内和剩余额度。${CHAT_ONLY}`,
+    z.strictObject({
+      orderId: z.string(),
+      total: z.number(),
+      withinBudget: z.boolean(),
+      items: z.array(z.string()),
+      budget: z.strictObject({ limit: z.number(), remaining: z.number() }),
+    }));
+  console.log('解析后的对象：', result);
+  assert.deepEqual(result, {
+    orderId: 'ORDER-42', total: 11, withinBudget: true,
+    items: ['苹果', '梨'], budget: { limit: 12, remaining: 1 },
+  });
+}

package/test/run.ts

@@ -0,0 +1,55 @@
+import { parseArgs } from 'node:util';
+import { flow, type Step } from 'agenttaskflow';
+import context from './context.js';
+import multiFields from './multi-fields.js';
+import branches from './branches.js';
+import loop from './loop.js';
+import modules from './modules.js';
+import correction from './correction.js';
+
+const cases: Record<string, (step: Step) => void> = {
+  'multi-fields': multiFields, branches, loop, modules, context, correction,
+};
+const { values, positionals } = parseArgs({ allowPositionals: true, options: {
+  provider: { type: 'string', default: 'codex' },
+  command: { type: 'string' },
+  'command-arg': { type: 'string', multiple: true },
+  timeout: { type: 'string', default: '600' },
+  list: { type: 'boolean', default: false },
+} });
+if (values.list) {
+  console.log('可用流程：\n' + Object.keys(cases).join('\n') + '\nall');
+} else {
+  if (!['codex', 'claude'].includes(values.provider!)) throw new Error('provider 必须是 codex 或 claude');
+  const timeout = Number(values.timeout);
+  if (!Number.isFinite(timeout) || timeout <= 0) throw new Error('timeout 必须是正数（秒）');
+  const selected = positionals.length ? positionals : ['multi-fields'];
+  const names = selected.includes('all') ? Object.keys(cases) : [...new Set(selected)];
+  for (const name of selected) if (name !== 'all' && !Object.hasOwn(cases, name)) throw new Error(`未知流程：${name}，使用 --list 查看`);
+  let failures = 0;
+  for (const name of names) {
+    console.log(`\n========== 测试：${name} ==========`);
+    const started = Date.now();
+    const pids = new Set<unknown>();
+    let corrections = 0;
+    try {
+      // 每个测试独立会话；一个测试内部的全部步骤复用同一进程。
+      flow({ provider: values.provider as 'codex' | 'claude',
+        command: [values.command ?? (values.provider === 'claude' ? 'claude' : 'cxh'), ...(values['command-arg'] ?? [])],
+        timeoutMs: timeout * 1000,
+        onEvent: event => {
+          if (event.kind === 'process_started') pids.add(event.text);
+          if (event.kind === 'correction') corrections++;
+        },
+      }, cases[name]);
+      if (pids.size !== 1) throw new Error(`预期只启动一个进程，实际 ${pids.size}`);
+      if (name === 'correction' && corrections < 1) throw new Error('没有收到补答事件');
+      console.log(`PASS ${name} · ${((Date.now() - started) / 1000).toFixed(1)}s · 补答 ${corrections} 次`);
+    } catch (error) {
+      failures++;
+      console.error(`FAIL ${name}:`, error);
+    }
+  }
+  console.log(`\n测试结束：${names.length - failures} 通过，${failures} 失败`);
+  if (failures) process.exitCode = 1;
+}

package/test/shared.ts

@@ -0,0 +1,15 @@
+import assert from 'node:assert/strict';
+import { z } from 'zod';
+import type { Step } from 'agenttaskflow';
+
+// 公共提示词直接放在 TS 中，多个流程复用同一个 step 和会话。
+export const CHAT_ONLY = '只在对话中完成任务，不读写文件，不调用外部工具。';
+export const Totals = z.strictObject({ count: z.number().int(), total: z.number() });
+
+export function summarizeCart(step: Step) {
+  return step.data(`汇总购物清单\n根据之前记住的清单，返回商品总件数 count 和总价 total。${CHAT_ONLY}`, Totals);
+}
+
+export function assertTotals(result: z.infer<typeof Totals>, count: number, total: number) {
+  assert.deepEqual(result, { count, total });
+}

package/index.js

@@ -1 +0,0 @@
-module.exports = {};