kelvinschen/acpus

acpus

English  ·  官网  ·  迁移指南

让你的 Agent 以 Dynamic Workflow 编排 ACP Agent

[!TIP] 使用 DeepSeek Harness？ 安装 @acpus/dsh 后，可以在 DSH 中选择 Acpus 模式。 查看插件的安装和使用说明 →

Acpus 可以调用任何已配置且支持 ACP 协议的 Agent, 包括但不限于: Claude Code、Codex、OpenCode、Pi、Kimi、Trae。

使用 Acpus 时，你的 Agent 根据目标动态地生成的 TypeScript Workflow: 通过 step.agent 来程序化地调用其他 ACP Agent，通过组织 串行、并发、条件分支、循环 等控制结构来实现一个复杂的长程任务。

Acpus 运行时负责调度并持久化每个运行的节点的状态、Artifact 和结果。 一个节点失败后，可以只重试该部分，不必重跑整个任务，已有的运行结果不会丢失。

什么时候用 Acpus

一个 Agent 能稳定完成的小任务，直接交给一个 Agent 更省事。Acpus 更适合工作量大、容易漏项，或需要独立复核的任务：

• 大型迁移和重构。 在多个模块中修改同一类代码，逐项运行测试并审查结果，避免漏掉调用点。
• 调查疑难问题。 为偶发故障、线上事故或数据异常提出几种可能原因，再用日志、代码和数据逐一验证。
• 深入研究和事实核查。 从网页、协作记录或代码库收集材料，核对关键结论，并整理成带来源的报告。
• 批量处理待办。 对大量工单、简历、候选方案或历史记录做分类、去重、排序，并复核最重要的结果。
• 从多个角度评审。 从用户、投资人、竞争对手、安全或实现风险等角度检查同一个方案，再汇总成一份结论。
• 把反复纠正变成规则。 从历史会话和代码审查意见中找出重复问题，整理成规则，再验证这些规则能否防止真实错误。

这些任务通常会持续很多轮，容易漏项或偏离目标，也需要独立复核。Acpus 保存运行状态，方便中途检查，并在失败后继续。

工作方式

你描述目标
  → Orchestrator Agent 生成 TypeScript Workflow
  → Acpus 检查 Workflow，并按依赖和控制流运行节点
  → Worker Agent 或 Task 执行节点
  → Acpus 保存状态、Artifact 和结果
  → Orchestrator Agent 检查运行状态，并处理需要判断的情况
  → Orchestrator Agent 返回结果

Orchestrator Agent 负责拆分任务、定义节点和依赖、启动 Run，并查看运行状态。 需要人工判断时，它可以暂停 Run、重试节点、创建新 Run 或请求输入。

快速开始

支持全局配置一次的 MCP 接入，无需安装 Skill，调用时选择项目。

CLI 和 MCP 默认共享 ~/.acpus。设置 ACPUS_HOME=/绝对路径 可隔离 ACPUS 的全局配置、运行状态和全局 Workflow 库；该路径直接作为数据根目录，不再追加 .acpus。

1. 安装 CLI 和 Skill

[!TIP] 安装的是稳定路由 Skill；它会让 Agent 通过当前版本 CLI 动态读取完整指南和 authoring context。比如你可以和 Agent 说： “使用 acpus cli 工具来启动一个 workflow，判断这个 release 是否可以发布”

npm install -g acpus
npx skills add kelvinschen/acpus

2. 描述目标

[!TIP]

/acpus 启动一个 Workflow，判断这个 release 是否可以发布

Orchestrator Agent 会选择 Workflow 结构和 Worker Agent。 你也可以指定角色，例如让 Claude 审查，让 Codex 汇总结果。

为什么使用 TypeScript Workflow

• 可以审查。 Workflow 是真实的 TypeScript 模块，可以直接查看和修改。
• 可以混用 Agent。 同一 Workflow 可以为不同角色配置不同的 ACP-compatible Agent，你可以让 Claude Code 来写代码，让 Codex 来 review。
• 运行前会检查。 Acpus 会先检查类型和 Workflow 结构，再创建 Run。
• 源码位置灵活。 一次性 Workflow 可以从 stdin 传入；需要修改或复用时，可以保存为文件。

一个完整示例

下面的 Workflow 并行运行两次审查，再由第三个 Agent 汇总结果。

acpus workflow run --input '{"topic":"release readiness"}' - <<'WORKFLOW'
import { defineWorkflow, z } from "acpus/core";
import { md } from "acpus/expression";

const Review = z.object({
  summary: z.string(),
  ready: z.boolean(),
});

export default defineWorkflow({
  name: "quick-review",
  inputSchema: z.object({ topic: z.string() }),
  agents: {
    implementation: { use: "codex" },
    risk: { use: "claude" },
    synthesizer: { use: "codex" },
  },
}).build(({ input, agents, meta, step }) => {
  const reviews = step("reviews").parallel({
    branches: {
      implementation() {
        const review = step("implementation_review").agent({
          agent: agents.implementation,
          cwd: meta.workspaceDir,
          outputSchema: Review,
          prompt: md`Review implementation readiness for: ${input.topic}`,
        });
        return review.output;
      },
      risk() {
        const review = step("risk_review").agent({
          agent: agents.risk,
          cwd: meta.workspaceDir,
          outputSchema: Review,
          prompt: md`Challenge hidden risks for: ${input.topic}`,
        });
        return review.output;
      },
    },
  });

  const decision = step("synthesize").agent({
    agent: agents.synthesizer,
    cwd: meta.workspaceDir,
    outputSchema: Review,
    prompt: md`Synthesize these independent reviews: ${reviews.output}`,
  });

  return {
    reviews: reviews.output,
    decision: decision.output,
  };
});
WORKFLOW

运行与控制

[!TIP] 通常不需要你来执行这些命令。你的 Agent 会帮你检查和运行 Workflow，并查看和控制 Run。

检查和运行 Workflow

一次性 Workflow 适合使用带引号的 heredoc。 如果源码包含本地 Task/helper 模块，或需要继续修改和复用，请保存为 workflow.ts。 临时源码也可以放在项目目录之外。

# 检查 Workflow，但不创建 Run
acpus workflow check workflow.ts --input '{"topic":"release readiness"}'

# 在终端查看静态工作流树
acpus workflow viz workflow.ts

# 生成自包含的 HTML 工作流图
acpus workflow viz workflow.ts --out workflow.html

# 创建 Run
acpus workflow run workflow.ts --input '{"topic":"release readiness"}'

# 查看 Run
acpus runs inspect 

workflow check 会执行类型检查、编译和验证，但不会创建 Run。 workflow viz 默认在终端显示工作流树；--out 会生成 HTML 文件。 workflow run 创建 Run，并输出简短的 inspect/follow 提示。 runs inspect 显示 Run 的持久化状态。

查看和控制 Run

查看状态

acpus runs inspect 
acpus runs inspect  --forensics
acpus runs inspect  --target  --forensics
acpus runs inspect  --await-decision
acpus runs inspect  --follow

--forensics 显示冻结的定义、实际调用值和调度器接受的结果。 省略 --target 时，它默认检查 root。

--await-decision 会等待下一处需要判断的输入、暂停或终态。 --follow 只等待 Run 进入终态。

运行控制

acpus runs pause 
acpus runs resume 
acpus runs retry  --target 
acpus runs steer  --target  --instruction ''
acpus runs signal  --target  --payload '{"approved":true}'
acpus runs fork  --workflow workflow.ts

retry 可以重试失败或超时的 Task、Agent 和 frame。local Agent Retry 会先清理并放弃受影响 的 Session generation，再以 authored prompt 创建下一代；若范围碰到显式共享 Session， Runtime 会拒绝并给出对应的 fork --target 命令。steer 采用 Interrupt & Continue：先 fence 并 drain 当前 Turn，再在同一 Session 的 replacement Turn 中使用新指令。 fork 创建新 Run。 新 Run 只会复用与新 Workflow 兼容、且依赖未变化的已完成工作。

Hook

通过 Hook 在 Workflow 执行的特定生命周期执行本地命令，例如:

• 运行启动时和完成后，执行特定的环境准备和清理工作
• 运行等待 Signal 输入时，发送通知给你
• 执行到特定类型节点前，记录执行信息到特定日志文件

Hook 命令失败或超时不会改变 Workflow 的状态和输出。

Acpus 通过统一配置管理 Hook。文件位置、完整结构、事件、筛选、验证命令、输入格式和加载时机见 Acpus 配置。

你也可以让你的 Agent 来配置 Hook。

配置 Agent

Acpus 通过 @acpus/acp 使用稳定的 ACP v1 会话接口。具名 Agent、Preset、项目/全局作用域、解析优先级和加载时机统一见 Acpus 配置。显式 { command: "..." } 会绕过具名解析。

Workflow Agent profile 还可声明 model 和字符串到字符串的 config 选项，例如 { use: "my-agent", model: "model-id", config: { reasoning_effort: "high" } }。 Acpus 将它们作为 ACP 会话的期望 model 和 options 应用，并在恢复会话时重放。

Skill 安装的补充说明

标准 Skills 工具负责安装、更新和移除 Acpus 路由 Skill：

npx skills add kelvinschen/acpus

这个无版本路由只要求 Agent 每个任务运行一次 acpus skill read。该命令从当前 CLI 版本读取完整 Skill，并注入当前 workspace 的 Preset 和 authoring scale context。因此升级 CLI 后，完整指南会自动更新，无需重新安装路由 Skill。

不安装路由 Skill 也可以直接运行 acpus skill read 获取相同的完整指南。

核心概念

执行单元

持久化对象

Acpus 将 Run 状态保存在当前 Workspace。

从旧版本迁移

Acpus 0.5 使用 YAML Workflow Spec，并采用不同的节点模型和 CLI。 当前版本使用 TypeScript 模块、Expr 值流、Agent、Task、Signal、新的控制面和新的持久化 Runtime。 当前版本不提供兼容层（compatibility shim）。

迁移指南 说明概念对应关系和重写步骤。 旧版文档见 Acpus 0.5.2 中文 README。

文档

• 内置 Acpus Skill
• 迁移指南
• 发布指南
• Specs 索引
• Core Spec
• Expression Spec
• Workflow Compiler Spec
• Runtime Spec
• CLI Spec
• WebUI Spec

当前实现机制以代码、导出类型和可执行帮助为准；跨实现保持的稳定产品合同见 specs/。 未来工作放在 docs/roadmap/。 旧版本保留在 Git Tag 历史中。

开发

pnpm install
pnpm build
pnpm typecheck
pnpm test

许可证

MIT