agentprism-workflows

<p align="center"> <img src="docs/assets/banner.png" alt="AgentPrism — 一键运行多个智能代理脚本" /> </p> # AgentPrism 工作流 运行 **动态、多智能代理工作流脚本** — `agent()`、`parallel()`、`pipeline()` — 通过真正的编程智能代理（Claude Code、OpenAI Codex 和 OpenCode），具有确定性日志记录、恢复、token 预算和 git 工作树隔离。 您编写一个小的 JavaScript **脚本**（`export const meta`，然后调用 `agent()` / `parallel()` / `pipeline()`）；引擎在沙盒领域运行它，将每个 `agent()` 调用扩展到 [Agent Client Protocol](https://agentclientprotocol.com) （ACP）后端。它有两种可用方式： - **作为 TypeScript SDK** — `@automatalabs/workflows` — 在您自己的程序中嵌入运行器。 - **作为 stdio MCP 服务器** — `@automatalabs/mcp-server`，基于 SDK 构建 — 向任何 MCP 主机（Claude Code、Zed 等）公开一个 `workflow` 工具。 > `@automatalabs/*` 包 **发布在 npm 上** — 请参阅 [安装](#安装)。有两个用户界面：`@automatalabs/workflows` SDK 和 `@automatalabs/mcp-server` stdio 服务器。 --- ## 为什么选择 AgentPrism ### 真实的智能代理驱动程序，通过开放协议驱动 每个 `agent()` 调用都在一个 **已配置的编程智能代理** 上运行 — Claude Code、Codex 或 OpenCode — 通过 [ACP](https://agentclientprotocol.com) 驱动，而不是在原始模型 API 周围重新实现智能代理循环。您获得每个后端的工具循环、权限和上下文管理，以及您已经在机器上拥有的身份验证（`~/.claude/.credentials.json`、`~/.codex/auth.json` 或 `opencode auth login`）。当驱动程序改进时，您的流程在无需更改代码的情况下得到改进。 ### 多个智能代理，一个工作流 后端由每个 `agent()` 调用 **选择**：一个 `opus` 审查步骤，一个 `gpt-5.5-codex` 实现步骤，一个 `opencode/zai/glm-5.2` 规划步骤和一个自定义 `browser` QA 智能代理可以共享一个脚本，相互传递结构化结果，并独立交换。任何 ACP 服务器都注册为一个命名后端 — 内置的是默认值，而不是边界。 ### 可恢复的运行 — 无需重新花费 token 脚本在确定性领域运行，每个 `agent()` 调用都在身份哈希下记录。如果在运行过程中终止进程 — 崩溃、部署、Ctrl-C — `resume()` 从日志中重放已完成的 前缀作为缓存命中（**零 token**），然后仅执行从未运行的步骤。提供商配额墙也不会导致运行失败：它 **暂停** 并在预算补充后恢复。 ### 结构化输出作为验证对象 `agent({ schema })` 返回一个模式验证对象，而不是要解析的文本。Claude 和 Codex 原生约束生成；OpenCode 和合格的自定义 ACP 智能代理在广告 HTTP MCP 支持时自动获得一个客户端托管的 `StructuredOutput` MCP 工具。运行器仍然验证并在不匹配时重新提示，因此同一个 API 适用于原生、工具捕获和最终文本 JSON 回退路径。 ### 完整的 ACP 规范，由构建强制执行 每个客户端 ACP 方法都被提供（`fs/*`、`terminal/*`、权限请求、诱导、MCP-over-ACP），并且智能代理端的表面 — 会话模式、会话生命周期、身份验证/提供商 — 被驱动，而不是存根。一个覆盖率清单按照 SDK 的方法常量进行键控，如果协议漂移，则会破坏构建，并且针对真实的 Claude、Codex 和 OpenCode 后端的实时端到端套件会阻塞每次推送。 ### 无人工干预运行的控制 硬 token 预算（运行级别上限，脚本中的 `budget.remaining()`）、每个调用的 git **工作树隔离**、每个调用的超时和重试，以及 `checkpoint()` — 一个记录的人工审批门，暂停运行，直到决策到达并重放。 --- ## 工作原理 一个进程同时扮演 **两个协议角色**：它是一个 **MCP 服务器** （或库），接受工作流脚本，以及一个 **ACP 客户端**，驱动一个或多个智能代理子进程来执行每个 `agent()` 调用。 ``` 您的程序 ──或── MCP 主机（Claude Code / Zed / …） │ runDynamicWorkflow(脚本) 调用工具 "workflow" ▼ ┌──────────────────────────────────────────────┐ │ AgentPrism 调度器 │ │ • 确定性引擎运行脚本 │ │ • ACP 客户端 → 驱动智能代理服务器 │ └──────────────────────────────────────────────┘ │ 会话/新建，会话/提示 … （ACP，JSON-RPC 超过 stdio） ▼ claude-agent-acp / codex-acp / opencode acp （长期运行，池化子进程） │ → 真实的 Claude / Codex / OpenCode 智能代理，每个 agent() 调用一个会话 ``` 确定性引擎（沙盒 `vm` 领域、`parallel`/`pipeline`、日志/恢复、token 预算、工作树隔离）独立于 *如何* 运行单个智能代理和 *如何* 暴露工具。请参阅 [`docs/design-notes.md`](docs/design-notes.md) 以获取完整的协议级设计。 --- ## 需求 - **Node.js ≥ 22** 和 **pnpm ≥ 10** （请参阅 `.nvmrc` / `packageManager`）。 - 一个已配置的后端智能代理 CLI： - **Claude** — 通过捆绑的 `@agentclientprotocol/claude-agent-acp`；来自 `~/.claude/.credentials.json` 或 `ANTHROPIC_API_KEY` 的身份验证（调度器继承您的环境）。 - **Codex** — 通过 `@automatalabs/codex-acp` （+ `@openai/codex` 二进制，作为依赖项安装）；来自 `~/.codex/auth.json` 的身份验证。 - **OpenCode** — 支持但 **未捆绑**。在 PATH 上安装 `opencode` CLI 或将 `opencode-ai` 添加到您自己的项目（其平台二进制文件很大），然后使用 `opencode auth login` 进行身份验证。 您只需要您实际调用的后端（s）的身份验证。 --- ## 安装 ### 从 npm ```bash pnpm add @automatalabs/workflows # SDK # 或，要运行 MCP 服务器： pnpm add @automatalabs/mcp-server ``` ### 从源代码（用于开发） ```bash git clone <此仓库> agentprism-workflows cd agentprism-workflows pnpm install # 安装依赖 + 获取后端二进制文件 pnpm build # 跨所有包的 tsc -b ``` --- ## 快速入门 — SDK 运行一个工作流脚本。默认后端是 ACP 运行器（`createAcpRunner()`），因此这驱动真正的智能代理并需要后端身份验证。 ```ts import { runDynamicWorkflow } from "@automatalabs/workflows"; const script = ` export const meta = { name: "repo-scan", description: "描述一个仓库为 JSON，三种方式并行", phases: [{ title: "Fan" }], }; const SCHEMA = { type: "object", additionalProperties: false, required: ["repo", "fileCount"], properties: { repo: { type: "string" }, fileCount: { type: "number" } }, }; phase("Fan"); const results = await parallel([ () => agent("以 JSON 格式报告此仓库 {repo, fileCount}。", { label: "a1", schema: SCHEMA }), () => agent("以 JSON 格式报告此仓库 {repo, fileCount}。", { label: "a2", schema: SCHEMA }), ]); return results; `; const run = await runDynamicWorkflow(script, { args: {} }); console.log(run.status); // "completed" | "paused" | "failed" | "aborted" console.log(run.result); // [{ repo: "...", fileCount: 123 }, …] — 模式验证对象 console.log(run.tokenUsage, run.runId); ``` `runDynamicWorkflow` 解析为一个 **终端** `WorkflowRunResult`，即使在暂停/失败/中止时 — 读取 `run.status` 而不是捕获。要交换后端（或在测试中存根），请传递您自己的运行器：`runDynamicWorkflow(script, { runner })`。对于更低级别的控制，请使用 `WorkflowManager` / `runWorkflow` （也从 SDK 重新导出）。 ### 直接运行单个智能代理 ```ts import { createAcpRunner } from "@automatalabs/workflows"; const runner = createAcpRunner(); const data = await runner.run("以 JSON 格式总结此仓库 {summary}。", { schema: { type: "object", additionalProperties: false, required: ["summary"], properties: { summary: { type: "string" } }, }, model: "opus", // 路由到 Claude；例如 "gpt-5-codex" 路由到 Codex cwd: process.cwd(), }); // data 类型化并根据模式验证（普通对象，不是文本） await runner.dispose(); // 关闭池化的后端进程 ``` --- ## 快速入门 — MCP 服务器 `workflow` 工具同步运行脚本到完成，流式传输 `notifications/progress`，并返回结构化结果。 在 MCP 主机的配置文件中注册 stdio 服务器： ```json { "mcpServers": { "agentprism-workflow": { "command": "agentprism-workflow", "env": { "AGENTPRISM_DEFAULT_BACKEND": "claude" } } } } ``` 从源代码 checkout 中，指向已构建的入口： ```json { "mcpServers": { "agentprism-workflow": { "command": "node", "args": ["/abs/path/to/agentprism-workflows/packages/mcp-server/dist/index.js"] } } } ``` **工具：`workflow`** — 输入参数： | 参数 | 类型 | 备注 | |---|---|---| | `script` | 字符串（**必填**） | 原始 JS；第一个语句必须是 `export const meta = { name, description, phases? }`；必须至少调用一次 `agent()`。 | | `args` | 任意 | 作为全局 `args` 暴露给脚本。 | | `maxAgents` | 数字 | 默认 1000。 | | `concurrency` | 数字 | **限制为 16** （不被拒绝）。 | | `agentRetries` | 数字 | **限制为 3**。 | | `agentTimeoutMs` | 数字 \| 空 | 每个智能代理的超时；省略为无。 | | `tokenBudget` | 数字 \| 空 | 运行的硬总 token 限制；省略为无。 | | `resumeFromRunId` | 字符串 | 从其持久化日志中恢复先前的运行（恢复是 **显式** 的）。 | 运行在同步（一个 `tools/call` = 一个完整的运行）。通过使用 `resumeFromRunId` 再次调用 `workflow` 以在暂停/崩溃后恢复。 --- ## 编写工作流脚本 脚本是一个普通的 JavaScript，其 **第一个语句** 是 `meta` 字面量。在其中，可以使用以下全局变量（注入到运行的领域 — 它们不是可导入的函数；`@automatalabs/workflows` 提供了环境 `.d.ts`，以便您的编辑器了解它们）： - `agent(prompt, opts?)` — 运行一个子智能代理。带有 `opts.schema` （一个 JSON 模式），您会得到一个验证的对象作为返回值；没有它，助手会得到文本。其他选项：`label`、`phase`、`model`/`tier`、`mode`、`agentType`、`isolation`、`cwd`、`timeoutMs`、`retries`、`mcpServers`、`images`、`meta`、`promptMeta`。（`meta`/`promptMeta` 是泛型 ACP `_meta`，传递到 `session/new` / `session/prompt` — 协议的扩展曲面用于自定义智能代理属性。工具策略和指令来自 `agentType` 定义；`toolNames`/`instructions` 仍然是较低级别的 `createAcpRunner().run()` API 选项。） - `parallel([fn, …])` — 并发运行 thunk；**屏障** （等待所有）。 - `pipeline(items, stage1, stage2, …)` — 独立地将每个项目流式传输通过阶段（阶段间无屏障）。 - `phase(title)`、`log(msg)` — 进度分组 + 叙述。 - `budget` — 运行的 token 预算（`budget.total`、`budget.remaining()`、`budget.spent()`）。 - `checkpoint()`、`gate()`、`verify()`、`judgePanel()`、`loopUntilDry()`、`completenessCheck()`、`retry()`、`workflow()`、`args`。 确定性被强制执行（`Date.now`/`Math.random`/`new Date()` 在领域中被中和），因此被终止的运行 **从其日志中恢复**，在未更改的前缀上进行缓存命中。 --- ## 结构化输出 传递一个 JSON 模式作为 `agent({ schema })`，返回值是一个 **验证的对象**，而不是文本。Claude 和 Codex 原生约束生成；OpenCode 在广告 HTTP MCP 支持时使用注入的客户端托管的 `StructuredOutput` MCP 工具。通用 ACP 智能代理在选择加入时获得相同的工具。运行器验证并在不匹配时重新提示；公共 `agent({ schema })` API 不变。请参阅 [`docs/design-notes.md` §6](docs/design-notes.md) 以获取每个后端的机制。 --- ## 后端和选择 后端由每个 `agent()` 调用根据传递的 `model`/`tier` 选择，按提供者前缀： - **已注册的自定义后端名称** （精确，或 `name/<inner-model>`）→ 该后端 — 首先匹配，请参见下文。 - `opencode`、`opencode/<provider/model>` → **OpenCode** (`opencode acp`)。内部模型是 OpenCode 目录 ID，例如 `zai/glm-5.2`；括号修饰符例如 `opencode/zai/glm-5.2[high]` 驱动 OpenCode 的努力选项。 - `opus`、`sonnet`、`haiku`、`claude…`、`anthropic/…` → **Claude** (`claude-agent-acp`)。 - `gpt…`、`codex…`、`o3`/`o4`、`openai/…` → **Codex** (`codex-acp`)。 - 否则默认后端（`AGENTPRISM_DEFAULT_BACKEND`，默认为 `claude` — 也可命名为已注册的自定义后端）。 一个长期运行的 ACP 进程，每个后端 **池化** 并在 `agent()` 调用之间重用（一个生成 + 一个 `initialize`），每个调用都有一个新鲜的会话 — 因此工作树隔离通过每个会话的 `cwd` 保存。 ### 自定义后端 — 运行 *任意* ACP 智能代理 内置功能不是限制：注册 **任意 ACP 智能代理** （您自己的图像生成包装器，浏览器 QA 智能代理...）作为命名后端，并通过名称路由到它。 ```ts import { createAcpRunner, runDynamicWorkflow } from "@automatalabs/workflows"; const runner = createAcpRunner({ backends: { browser: { command: "node", args: ["/abs/path/to/browser-acp.js"], env: { HEADLESS: "1" }, // 合并到 process.env sessionMeta: { allowedDomains: ["example.com"] }, // 静态 session/new _meta 默认值 }, }, }); await runDynamicWorkflow(script, { runner }); ``` 在脚本内部：`agent("验证 checkout 流程…", { model: "browser", schema: VERDICT, meta: { credsRef: "vault://qa" } })`。`model: "browser/vision-large"` 还会通过智能代理的配置选项目录选择 `vision-large`。相同的注册可以通过 `AGENTPRISM_BACKENDS` 环境变量（相同形状的 JSON）声明 — 这是 MCP 服务器获取它的方式。名称不区分大小写；`claude`、`codex` 和 `opencode` 是保留的。 自定义后端使用通用方言：模式作为 turn 级 `_meta.outputSchema` 转发（普通 JSON 模式），当初始化的智能代理广告 HTTP MCP 支持时，运行器注入一个本地主机 `StructuredOutput` MCP 工具，其输入模式为相同模式。没有 HTTP MCP 时，或在后端配置上设置 `structuredOutput:false` 时，模式在提示中声明，结果通过 JSON 解析最终助手消息读取。每个调用的 `meta` 合并到注册表的 `sessionMeta` 默认值；协议关键键（模式通道，`runId`）始终获胜。 #### 脚本声明后端（`meta.backends`） 工作流脚本也可以声明它需要的后端，因此工作流是一个自包含的工件（并且 *作者编写的工作流* 可以带上它们自己的 ACP 服务器）： ```js export const meta = { name: "visual-qa", description: "验证预览部署", backends: { browser: { command: "browser-acp", args: ["--headless"], sessionMeta: { mode: "verify" } }, }, }; const verdict = await agent("验证 checkout 流程…", { model: "browser", schema: VERDICT }); ``` 脚本声明的后端在主机上生成命令，因此它们 **在批准之前是惰性的** — 引擎解析它们但从不执行： - **SDK**：在 `runDynamicWorkflow` 中传递 `allowScriptBackends: true` （或每个后端的批准回调）；未批准的声明会抛出指导信息而不是静默路由。 - **MCP 服务器**：不支持诱导的客户端会询问每个唯一生成的配置（会话粘性）；其他客户端会收到一个信息性工具错误，名称中包含 `AGENTPRISM_ALLOW_SCRIPT_BACKENDS=1` 环境选项。 --- ## 配置 | 环境变量 | 默认值 | 含义 | |---|---|---| | `AGENTPRISM_DEFAULT_BACKEND` | `claude` | 当模型/层级没有暗示一个时使用的后端（`claude` \| `codex` \| `opencode` \| 已注册的自定义名称）。 | | `AGENTPRISM_BACKENDS` | （无） | 自定义 ACP 后端作为 JSON：`{"<name>": {"command": "…", "args": […], "env": {…}, "sessionMeta": {…}}}`。按名称计算 `createAcpRunner({ backends })` 优先。 | | `AGENTPRISM_ALLOW_SCRIPT_BACKENDS` | （未设置） | MCP 服务器仅：`1`/`true` 批准 **脚本声明的** `meta.backends` 无头（适用于不支持诱导的客户端）。 | | `AGENTPRISM_ACP_POOL_SIZE` | `1` | 每个后端保留的长期运行进程。 | | `AGENTPRISM_ACP_INIT_TIMEOUT_MS` | `60000` | 后端的单次 ACP `initialize` 握手超时（否则快速失败非 ACP 命令）。 | | `AGENTPRISM_CLAUDE_ACP_CMD` / `…_ARGS` | （捆绑） | 重写 Claude ACP 服务器命令/参数。 | | `AGENTPRISM_CODEX_ACP_CMD` / `…_ARGS` / `…_BIN` | （捆绑） | 重写 Codex ACP 服务器命令/参数/二进制文件。 | | `AGENTPRISM_OPENCODE_ACP_CMD` / `…_ARGS` | `opencode acp` | 重写 OpenCode ACP 服务器命令/参数。带有 `…_CMD`，参数仅来自 `…_ARGS`。 | | `AGENTPRISM_OPENCODE_E2E_MODEL` | `opencode/zai/glm-5.2` | 实时端到端 OpenCode 模型规范。 | --- ## 文档 - [`docs/api.md`](docs/api.md) — **API 参考**：`WorkflowManager` 选项/生命周期/事件（包括 `agentEvent` token 级流），`ExecOptions`（包括每个运行的 `cwd` 用于工作树每运行主机），运行器曲面（`run()`，模型路由，事件总线，交互式会话，功能），后端解析 + 每个环境变量，和完整的 `WorkflowError` 代码表。 - [`docs/design-notes.md`](docs/design-notes.md) — 深入的协议级设计：ACP 生命周期，结构化输出关键点，模型/权限/用法/取消机制，和引擎血统。 - [`CONTRIBUTING.md`](CONTRIBUTING.md) — 本地开发，测试（包括有门控的实时后端端到端），和发布。 - [Agent Client Protocol](https://agentclientprotocol.com) · [Model Context Protocol](https://modelcontextprotocol.io) ## 许可证 Apache-2.0 — 请参阅 [`LICENSE`](LICENSE)。