# https://github.com/openclaw/acpx 项目说明书

生成时间：2026-06-23 12:02:30 UTC

## 目录

- [acpx 概述与系统架构](#page-1)
- [内置代理注册表与自定义适配器](#page-2)
- [会话、队列与权限控制](#page-3)
- [Flow 流程运行时、Replay 工具与扩展点](#page-4)

<a id='page-1'></a>

## acpx 概述与系统架构

### 相关页面

相关主题：[内置代理注册表与自定义适配器](#page-2), [会话、队列与权限控制](#page-3), [Flow 流程运行时、Replay 工具与扩展点](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/openclaw/acpx/blob/main/README.md)
- [package.json](https://github.com/openclaw/acpx/blob/main/package.json)
- [agents/README.md](https://github.com/openclaw/acpx/blob/main/agents/README.md)
- [agents/Codex.md](https://github.com/openclaw/acpx/blob/main/agents/Codex.md)
- [agents/Trae.md](https://github.com/openclaw/acpx/blob/main/agents/Trae.md)
- [examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md)
- [conformance/README.md](https://github.com/openclaw/acpx/blob/main/conformance/README.md)
- [src/cli/config.ts](https://github.com/openclaw/acpx/blob/main/src/cli/config.ts)
</details>

# acpx 概述与系统架构

## 项目定位与核心价值

`acpx` 是一个面向 [Agent Client Protocol (ACP)](https://agentclientprotocol.com) 的**无头 CLI 客户端**，目标是为 AI 智能体与编排器提供一种结构化的命令行通信方式，避免对 PTY 终端输出进行抓取式解析 资料来源：[README.md:1-20]()。

其设计定位强调三点：

- **统一入口**：通过同一套 CLI 表面即可对接 Pi、OpenClaw ACP、Codex、Claude 及其他 ACP 兼容代理 资料来源：[README.md:25-30]()。
- **多轮会话**：会话在多次调用之间持久化，并按仓库目录进行作用域划分，支持命名会话实现同一仓库内的并行工作流 资料来源：[README.md:33-42]()。
- **面向代理-代理通信**：CLI 的输出格式（`text` / `json` / `quiet`）与 JSON 事件信封（`eventVersion` / `sessionId` / `requestId` / `seq` / `stream` / `type`）专为机器消费而设计 资料来源：[README.md:182-200]()。

当前版本为 `0.11.1`，发布于 `package.json` 中，并明确声明仍处于 alpha 阶段，CLI/运行时接口可能变更 资料来源：[package.json:3]()。

## 系统架构与组件划分

`acpx` 的整体架构以“CLI 前端 + 运行时后端 + ACP 适配器层”三层模型为核心。`package.json` 通过 `exports` 字段同时暴露三个可被外部嵌入的入口：`./`（CLI 二进制）、`./runtime` 与 `./flows` 资料来源：[package.json:33-45]()，这表明项目在单一包内同时承载 CLI 入口、运行时 API 与 Flow 编排能力。

CLI 层负责参数解析、全局开关（`--approve-all`、`--deny-all`、`--cwd`、`--timeout`、`--ttl`、`--format` 等）以及将解析后的策略下发到运行时 资料来源：[README.md:78-100]()。配置层在 `src/cli/config.ts` 中定义了全局配置路径 `~/.acpx/config.json` 与项目级配置 `.acpxrc.json` 的合并规则，并集中校验 `ttl`、`timeout`、`queueMaxDepth` 等数值字段 资料来源：[src/cli/config.ts:8-25]()。

运行时与协议层负责 ACP `initialize` / `session/*` 调用的发送、JSON 事件流编排以及与适配器进程的 stdin/stdout 通信。会话控制响应（`sessions new|ensure`、`status`）始终包含 `acpxRecordId` 与 `acpxSessionId`，仅当适配器暴露 provider-native ID 时才附带 `agentSessionId` 资料来源：[README.md:200-210]()。

```mermaid
flowchart LR
    User[用户 / 上游编排器] --> CLI[acpx CLI]
    CLI --> Cfg[配置层<br/>~/.acpx/config.json + .acpxrc.json]
    CLI --> Runtime[运行时 + ACP 客户端]
    Runtime --> Adapter[内置 / 自定义 ACP 适配器]
    Adapter --> Provider[底层编码代理<br/>Codex / Claude / Pi / Trae ...]
    Runtime --> Flows[acpx/flows 编排]
    Runtime --> State[(~/.acpx/<br/>会话与 Flow 运行状态)]
```

会话与 Flow 状态统一落盘到 `~/.acpx/`，包括 `~/.acpx/flows/runs/` 下的运行记录；Flow 状态可被 `examples/flows/` 中的回放查看器（React Flow + ACP 会话检视）读取 资料来源：[examples/flows/README.md:1-20]()。

## 内置适配器与扩展点

`acpx` 通过“内置适配器 + 名称回退到原始命令”的策略同时支持托管与自定义适配器。在 `agents/README.md` 中列出了十余个官方内置项，包括 `codex` → `npx -y @agentclientprotocol/codex-acp`、`claude` → `@agentclientprotocol/claude-agent-acp`、`copilot` → `copilot --acp --stdio`、`fast-agent` → `uvx fast-agent-mcp acp`、`cursor` → `cursor-agent acp`、`gemini` → `gemini --acp`、`kilocode` → `npx -y @kilocode/cli acp`、`kimi` → `kimi acp`、`mux` → `npx -y mux@^0.27.0 acp`、`opencode` → `npx -y opencode-ai acp` 以及 `trae` → `traecli acp serve` 资料来源：[agents/README.md:1-20]()。

适配器对运行时控制语义具有差异性。例如，Codex 通过广告的 session config option 应用模型，因此 `--model` 与 `set model` 都走 `session/set_config_option` 路径；推理强度则编码进诸如 `gpt-5.2[high]` 的广告模型 ID 中 资料来源：[agents/Codex.md:1-10]()。Trae 则是一个独立适配器（`trae`），其上游位于 https://docs.trae.cn/cli 资料来源：[agents/Trae.md:1-5]()。

对于未在白名单中的名称，`acpx` 会将其视为原始命令直接执行，并提供 `--agent` 作为显式逃生口 资料来源：[README.md:65-70]()。这意味着社区和供应商可以低成本接入新适配器；社区已有 #362 提案要求将 Antigravity CLI（`agy --acp stdio`）以与 `claude` / `codex` / `opencode` 相同的形式升级为一等公民内置适配器。

## 协议合规与安装运行

在协议层，`acpx` 维护了一份 ACP 覆盖路线图（`docs/2026-02-19-acp-coverage-roadmap.md`）并启动了 ACP 一致性套件草案，覆盖 `initialize`、`session/new`、`session/prompt`、`session/update`、`session/cancel` 与基线错误语义 资料来源：[conformance/README.md:1-25]()。当前 `acp-core-v1` 配置文件包含 20 个强制用例。

安装方面，项目推荐 `npm install -g acpx@latest` 或通过 `npx acpx@latest` 临时运行，两种方式都会将状态写入 `~/.acpx/` 资料来源：[README.md:30-50]()。运行时要求 Node.js `>=22.13.0`，并采用 ESM（`"type": "module"`）与 `pnpm@10.33.2` 作为包管理器 资料来源：[package.json:175-185]()。

## See Also

- 内置代理与适配器清单：[agents/README.md](https://github.com/openclaw/acpx/blob/main/agents/README.md)
- Flow 编排示例与回放查看器：[examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md)
- ACP 一致性测试草案：[conformance/README.md](https://github.com/openclaw/acpx/blob/main/conformance/README.md)
- 配置与全局开关定义：[src/cli/config.ts](https://github.com/openclaw/acpx/blob/main/src/cli/config.ts)

---

<a id='page-2'></a>

## 内置代理注册表与自定义适配器

### 相关页面

相关主题：[acpx 概述与系统架构](#page-1), [会话、队列与权限控制](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/openclaw/acpx/blob/main/README.md)
- [agents/README.md](https://github.com/openclaw/acpx/blob/main/agents/README.md)
- [agents/Codex.md](https://github.com/openclaw/acpx/blob/main/agents/Codex.md)
- [agents/Kimi.md](https://github.com/openclaw/acpx/blob/main/agents/Kimi.md)
- [agents/Trae.md](https://github.com/openclaw/acpx/blob/main/agents/Trae.md)
- [package.json](https://github.com/openclaw/acpx/blob/main/package.json)
- [src/cli/flags.ts](https://github.com/openclaw/acpx/blob/main/src/cli/flags.ts)
</details>

# 内置代理注册表与自定义适配器

## 概述

acpx 是 [Agent Client Protocol (ACP)](https://agentclientprotocol.com) 的无头 CLI 客户端，它通过统一的命令入口把多个 ACP 兼容的编程代理暴露给用户与编排器。**内置代理注册表**（built-in agent registry）的核心职责，是把命令行中的代理名（例如 `codex`、`claude`、`pi`）映射到具体的适配器实现（adapter），而适配器再规定如何通过 stdio 启动子进程、协商 ACP 会话，并把代理特有的会话控制（`set_mode`、模型选择、`set_config_option`）翻译为 ACP 调用。

`资料来源：[README.md:1-8]()` 入口把 Pi、OpenClaw ACP、Codex、Claude 等 ACP 兼容代理统一为同一套 CLI 表面。注册表既包含项目自带的一组内置代理，也允许用户在运行时通过 `--agent` 转义口和 `~/.acpx/config.json` 注入自定义适配器，从而把任何支持 ACP stdio 的 CLI 工具接入 acpx，而无需修改核心代码。

## 内置适配器清单

`agents/` 目录下的每个 Markdown 文件代表一个内置代理条目，约定统一字段：内置名（built-in name）、默认启动命令（default command）、上游仓库（upstream）以及适配器特有的注意事项。

| 内置名 | 默认命令 | 上游 |
| --- | --- | --- |
| `codex` | `npx -y @agentclientprotocol/codex-acp` | agentclientprotocol/codex-acp |
| `kimi` | `kimi acp` | MoonshotAI/kimi-cli |
| `trae` | `traecli acp serve` | docs.trae.cn/cli |
| `claude` | （通过 npm 分发） | claude.ai/code |
| `pi`、`openclaw` | 主程序直启 | openclaw/openclaw |
| `fast-agent` | `uvx fast-agent-mcp acp` | （v0.11.0 新增内置） |

`资料来源：[agents/Codex.md:1-3]()` `资料来源：[agents/Kimi.md:1-3]()` `资料来源：[agents/Trae.md:1-3]()` `资料来源：[README.md:62-74]()`

Codex 适配器在 `agents/Codex.md` 中进一步指出：当前 codex-acp 暴露的运行时控制包括 ACP 模式以及通过广告模型（advertised model）实现的会话配置；推理强度被编码在形如 `gpt-5.2[high]` 的模型 ID 中，并通过 `acpx --model <id>` 或 `acpx codex set model <id>` 透传给会话。`资料来源：[agents/Codex.md:1-5]()`

注册表持续由社区驱动扩展。Issue #362 提议新增 Antigravity（`agy`）适配器，希望以 `acpx antigravity ...` 的形态与 `acpx claude`、`acpx codex`、`acpx opencode` 对齐，从而让 OpenClaw 操作员以及任何 ACP-stdio 编排器都能把 Antigravity CLI 纳入 acpx 管理。`资料来源：[Issue #362](https://github.com/openclaw/acpx/issues/362)`

v0.11.0 发布说明中提到，团队将默认 Claude ACP 适配器升级到 `@agentclientprotocol/claude-agent-acp@^0.37.0`，并新增了 `fast-agent` 内置条目，运行命令为 `uvx fast-agent-mcp acp`，进一步扩充了内置注册表。`资料来源：[README.md:3-7]()`

## 解析与回退机制

当用户在命令行中传入一个未在注册表中声明的名字时，acpx 不会直接报错，而是把该名字当作原始可执行命令处理：

```bash
acpx my-agent 'review this patch'                      # 未知名字 -> 原始命令
acpx --agent './bin/dev-acp --profile ci' 'run checks' # --agent 转义口
```

`资料来源：[README.md:70-73]()`

这种"回退到原始命令"的设计让用户可以临时挂载一个未在注册表中声明的 ACP 客户端，而无需修改代码或重建二进制。`--agent` 显式接受任意可执行命令，是项目为自定义适配器预留的主要扩展点；它与内置条目共享同一套会话、权限和输出语义，因此不会因为走"非内置"通道而失去一致性。

## 自定义适配器与配置

acpx 通过全局 + 项目两级 JSON 配置文件管理适配器、权限策略和会话行为：

```bash
acpx config show                 # 展示合并后的解析结果
acpx config init                 # 在 ~/.acpx/config.json 生成模板
```

`资料来源：[README.md:34-38]()`

`package.json` 中声明的运行时依赖（`@agentclientprotocol/sdk`、`commander`、`zod`）表明，适配器描述是使用 Zod 模式校验的结构化对象，确保自定义条目与内置条目遵循同一形状，从而让注册表扩展可以在不破坏现有 CLI 契约的前提下加入新条目。`资料来源：[package.json:60-65]()`

CLI 全局标志（`--approve-all`、`--deny-all`、`--policy`、`--cwd`、`--timeout`、`--ttl`、`--format`、`--suppress-reads`）在 `src/cli/flags.ts` 中被解析为统一的 `RootFlags` 类型，并按调用顺序组合后透传给当前选中的适配器；这意味着无论内置还是自定义代理，权限、超时和输出格式的语义都保持一致。`资料来源：[src/cli/flags.ts:1-25]()`

## See Also

- 持久化会话与队列：见 `acpx codex sessions ...` 子命令（[README.md](https://github.com/openclaw/acpx/blob/main/README.md)）
- ACP 流程（Flow）工作流：见 [examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md)
- Issue #362：Antigravity（agy）适配器提案
- v0.11.0 发布说明：见项目 Releases 页
- 适配器模式与配置 schema 校验：[package.json](https://github.com/openclaw/acpx/blob/main/package.json)

---

<a id='page-3'></a>

## 会话、队列与权限控制

### 相关页面

相关主题：[acpx 概述与系统架构](#page-1), [内置代理注册表与自定义适配器](#page-2), [Flow 流程运行时、Replay 工具与扩展点](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/openclaw/acpx/blob/main/README.md)
- [package.json](https://github.com/openclaw/acpx/blob/main/package.json)
- [src/cli/flags.ts](https://github.com/openclaw/acpx/blob/main/src/cli/flags.ts)
- [src/cli/config.ts](https://github.com/openclaw/acpx/blob/main/src/cli/config.ts)
- [src/cli/output/output.ts](https://github.com/openclaw/acpx/blob/main/src/cli/output/output.ts)
- [agents/Codex.md](https://github.com/openclaw/acpx/blob/main/agents/Codex.md)
</details>

# 会话、队列与权限控制

`acpx` 是一个无头 CLI 客户端，作为 [Agent Client Protocol (ACP)](https://agentclientprotocol.com) 的客户端与多个 coding agent（Codex、Claude、Pi、OpenClaw ACP bridge 等）通过结构化协议通信。其核心交互模型围绕三类控制面：**会话（Session）**、**提示队列（Prompt Queue）** 与 **权限控制（Permission Control）**。它们决定了多轮对话如何在多次 `acpx` 调用之间持久化、提示如何在被占用时排队等待，以及 agent 在缺少交互式终端时如何处理工具调用授权。

## 会话管理

`acpx` 的会话是**按仓库（cwd）粒度命名**的持久化多轮上下文，存活在 `~/.acpx` 下的本地存储中。`README.md` 显式声明 `acpx` “是一份一次性的 PTY 客户端” 的反例，提供“跨调用存活的多轮会话”，并且“每个仓库作用域独立”。

常用子命令（`README.md` 顶部 Usage 区）：

```bash
acpx codex sessions new --name api              # 创建命名会话
acpx codex -s api 'implement token pagination'  # 在命名会话中提示
acpx codex sessions                              # 列出当前命令下的会话
acpx codex sessions list                         # 显式列表
acpx codex sessions show                         # 查看 cwd 会话元数据
acpx codex sessions history                      # 查看最近 turn 历史
acpx codex sessions ensure                       # 复用或创建 cwd 默认会话
acpx codex sessions close                        # 软关闭 cwd 默认会话
```

`src/cli/flags.ts` 中可以看到对应的 flag 形状：`SessionsNewFlags` 暴露 `name` 与 `resumeSession`，`SessionsHistoryFlags` 含 `limit`，`SessionsListFlags` 含 `cursor / filterCwd / local`，`SessionsExportFlags` 与 `SessionsImportFlags` 分别有 `output / sourceCwd` 与 `name / destinationCwd`，`SessionsPruneFlags` 暴露 `dryRun / before / olderThan / includeHistory`（`src/cli/flags.ts`）。这意味着会话不仅可创建、关闭，还可导出/导入以及按时间或大小裁剪。

会话使用**软关闭（soft-close）** 生命周期：关闭不删除磁盘上的历史，因此可以稍后被同名 `ensure` 重新拉起。`README.md` 的特性列表还提到“崩溃重连”：当 agent 子进程死亡时，会话会被自动检测并尝试 resume 或 reload。

## 提示队列与生命周期

由于会话是跨进程持有的，单个 `acpx` 调用只是把提示发到队列、等待 turn 完成、然后退出。`README.md` 明确支持：

- **提示排队**：当前一个 prompt 仍在运行时，再次提交会按顺序排队。
- **`--no-wait` 异步入队**：仅入队不等待，便于编排。
- **Cooperative `cancel` 命令**：通过队列 IPC 发送 ACP `session/cancel`，不拆除会话状态。
- **队列所有者 TTL（`--ttl`）**：队列主进程在最近一次提示后仍保留一段时间，便于快速追加。
- **优雅取消（`Ctrl+C`）**：先发 `session/cancel`，再退回强制 kill。
- **`--timeout`**：限制单次 turn 的总耗时。

```mermaid
flowchart LR
    A[acpx call] -->|enqueue| Q[Prompt Queue]
    Q -->|in flight| S[ACP Session / Agent]
    S -->|turn complete| R[Result + history]
    A -->|--no-wait| Q
    A -->|Ctrl+C or cancel| S
    S -->|ttl expires| Q
```

`src/cli/flags.ts` 的 `PromptFlags` 中 `wait` 与 `session` 共同控制等待与会话路由；`ExecFlags` 与 `SessionsNewFlags` 中的 `file` / `resumeSession` 则支持从文件/stdin 装载 prompt 以及从已存会话 ID 恢复（`src/cli/flags.ts`）。

## 权限控制

权限面解决的是“agent 想执行 shell/读文件/写文件时，CLI 该如何裁决”。`README.md` 列出 4 个直观的全局开关加一个 JSON 策略入口：

| Flag | 行为 |
| --- | --- |
| `--approve-all` | 自动批准所有工具调用 |
| `--approve-reads`（默认） | 放行只读类工具，其他需要确认 |
| `--deny-all` | 全部拒绝，仅回答“能做什么” |
| `--non-interactive-permissions fail` | 非 TTY 下若遇到需要裁决的请求直接失败 |
| `--policy '<json>'` | 内联 JSON 策略，例如 `{"escalate":["execute"],"defaultAction":"deny"}` |

```bash
acpx --approve-all codex 'apply the patch and run tests'
acpx --approve-reads codex 'inspect repo structure and suggest plan'
acpx --deny-all codex 'explain what you can do without tool access'
acpx --non-interactive-permissions fail codex 'fail instead of deny in non-TTY'
acpx --policy '{"escalate":["execute"],"defaultAction":"deny"}' --format json codex exec 'ask before shell'
```

权限裁决结果在 `src/cli/output/output.ts` 中以 `OutputFormat = "text" | "json" | "quiet"`（`src/cli/config.ts` 中的 `VALID_OUTPUT_FORMATS`）渲染；其 `summarizeToolContent` / `summarizeToolContentEntry` 决定读类工具的输出是否被抑制（`src/cli/output/output.ts`），这与 `--suppress-reads` 行为一致。`src/cli/config.ts` 中还定义了 `VALID_AUTH_POLICY = {"skip","fail"}`，用于非交互场景下未授权时的处理策略。

## 全局选项与配置

控制面相关的全局开关与配置文件：

- `acpx config init` 在 `~/.acpx/config.json` 写入模板；`acpx config show` 输出合并后的解析配置（`src/cli/config.ts` 中的 `defaultGlobalConfigPath`）。
- 项目级配置位于 `<cwd>/.acpxrc.json`（`src/cli/config.ts` 中的 `projectConfigPath`）。
- `parseTtlMs` / `parseTimeoutMs` / `parseQueueMaxDepth` 在 `src/cli/config.ts` 中把秒或正整数归一化为毫秒或队列上限；非法值会抛错并指出 `expected non-negative seconds` / `expected positive seconds`。
- `agents/Codex.md` 提示：模型选择既可经由 `acpx --model <id>` 全局传入，也可通过 `acpx codex set model <id>` 写入当前会话，对应 ACP `session/set_config_option`（`README.md` 顶部 session controls 一节）。

```bash
acpx --timeout 1800 flow run ./my-flow.ts
acpx --ttl 30 codex 'keep queue owner alive for quick follow-ups'
acpx --verbose codex 'debug why adapter startup is failing'
```

## 社区与版本注记

v0.11.0（`package.json` 当前为 `0.11.1`）在权限与会话侧也带来相关变化：将内置 Claude ACP 适配器范围升级到 `@agentclientprotocol/claude-agent-acp@^0.37.0`，并在运行时会话状态/事件中暴露成本、token 明细以及命令元数据（README 顶部 v0.11.0 说明）。同期新增的 `fast-agent` 内置适配器（`uvx fast-agent-mcp acp`）以及 #362 中请求的 Antigravity (`agy`) 适配器，都遵循相同的 `acpx <agent>` 形式，因此会话、队列与权限控制面可一致地作用于这些新 agent。

## See Also

- [README.md](https://github.com/openclaw/acpx/blob/main/README.md) — 命令示例与功能概览
- [agents/README.md](https://github.com/openclaw/acpx/blob/main/agents/README.md) — 内置 agent 适配器清单
- [src/cli/flags.ts](https://github.com/openclaw/acpx/blob/main/src/cli/flags.ts) — 所有会话/队列相关 flag 定义
- [src/cli/config.ts](https://github.com/openclaw/acpx/blob/main/src/cli/config.ts) — 全局/项目配置与解析规则
- [src/cli/output/output.ts](https://github.com/openclaw/acpx/blob/main/src/cli/output/output.ts) — 权限裁决与工具输出的渲染管线
- [examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md) — Flow 运行时如何在多次 prompt 上复用上述控制面

---

<a id='page-4'></a>

## Flow 流程运行时、Replay 工具与扩展点

### 相关页面

相关主题：[acpx 概述与系统架构](#page-1), [会话、队列与权限控制](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [examples/flows/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/README.md)
- [README.md](https://github.com/openclaw/acpx/blob/main/README.md)
- [examples/flows/pr-triage/README.md](https://github.com/openclaw/acpx/blob/main/examples/flows/pr-triage/README.md)
- [package.json](https://github.com/openclaw/acpx/blob/main/package.json)
- [src/cli/flags.ts](https://github.com/openclaw/acpx/blob/main/src/cli/flags.ts)
- [agents/Codex.md](https://github.com/openclaw/acpx/blob/main/agents/Codex.md)
</details>

# Flow 流程运行时、Replay 工具与扩展点

## 概览与定位

`acpx` 的 Flow 运行时为多步骤 ACP 工作流提供 TypeScript 风格的声明式编排能力。开发者通过 `acpx flow run <file>` 命令将一个 TypeScript 流程模块载入 `acpx/flows` 运行时执行，并把运行产物持久化到 `~/.acpx/flows/runs/` 目录中。资料来源：[README.md:1-50]()

Flow 适用于单次 prompt 无法覆盖、需要组合多个 ACP 节点、原生命令与外部判定的场景。它的核心价值在于：

- 把"模型推理类"工作保留在 ACP 节点中；
- 把"确定性机械类"工作下沉到 `action` 节点；
- 把"路由/整形"放在 `compute` 节点中；
- 用 `decision` 与 `decisionEdge` 在不引入新节点类型的前提下表达约束性分支；
- 用 `checkpoint` 把外部事件（人工审批、外部信号）接入流程。资料来源：[README.md:50-100]()

## 核心节点类型与运行时语义

`acpx/flows` 运行时通过 `defineFlow(...)` 暴露一组语义清晰的节点类型，开发者从 `acpx/flows` 公共 API 引入即可使用：

| 节点类型 | 作用 | 典型用法 |
|----------|------|----------|
| `acp` | 在 ACP 会话内执行一轮或多轮 prompt | 让模型在受控 cwd 中推理并调用工具 |
| `action` | 运行时直接托管的确定性动作 | 跑 shell、准备 workspace、调用 GitHub |
| `compute` | 纯本地路由/数据整形 | 计算下一步走向、规整模型输出 |
| `decision` / `decisionEdge` | 受约束的 ACP 分支判断 | 在有限选项中选择路线 |
| `checkpoint` | 暂停流程等待外部事件 | 等人工审批或外部 webhook |

资料来源：[README.md:60-90]()

`examples/flows` 目录下的示例几乎覆盖了上述全部节点语义：

- `echo.flow.ts`：单个 ACP 节点直接返回 JSON。
- `branch.flow.ts`：使用 `decision()` 与 `decisionEdge()` 进行受限选择分类，再分支到 `continue` 或 `checkpoint`。
- `shell.flow.ts`：单个运行时托管的 shell 动作，返回结构化 JSON。
- `workdir.flow.ts`：原生工作区准备 + 隔离 cwd 中的 ACP 节点。
- `two-turn.flow.ts`：同会话多轮 ACP 流程，跨多步检视工作区、调用工具并精炼回答。
- `pr-triage/pr-triage.flow.ts`：端到端 PR triage 工作流示例，配有 `pr-triage/README.md` 写明规范。
- `replay-viewer/`：浏览器端 React Flow 可视化工具，用于回放已保存的运行 bundle。资料来源：[examples/flows/README.md:1-20]()

`pr-triage` 示例还展示了一个重要的运行时约定：流程应在整个判断通道内共享一个持久的 `main` ACP 会话；如果实时 ACP 连接中断，运行时需要尝试重连并恢复同一底层 agent 会话；如果恢复失败，必须显式失败，而不是悄悄开启新会话伪装上下文。资料来源：[examples/flows/pr-triage/README.md:10-25]()

```mermaid
flowchart LR
    A[flow run &lt;file&gt;] --> B[acpx/flows 加载 defineFlow]
    B --> C{节点类型}
    C -->|acp| D[ACP 会话路由]
    C -->|action| E[运行时托管动作]
    C -->|compute| F[本地路由/整形]
    C -->|decision| G[受限选择]
    C -->|checkpoint| H[暂停等待外部]
    D --> I[写入 ~/.acpx/flows/runs/]
    E --> I
    F --> I
    G --> I
    H --> I
    I --> J[replay-viewer 回放]
```

## Replay 工具与运行产物

Flow 运行产物（run bundle）默认落盘到 `~/.acpx/flows/runs/`，包含完整的状态机轨迹、ACP 会话元数据、节点输出等内容，方便事后回放与审计。资料来源：[README.md:55-75]()

`examples/flows/replay-viewer` 提供了一个浏览器端可视化工具，使用 React Flow 渲染已保存的运行 bundle：

- 支持"最近运行"选择器；
- 支持 ACP 会话检查（session inspection）；
- 配套有独立规范文件 `docs/2026-03-27-flow-replay-viewer.md`。在仓库根目录执行 `pnpm viewer` 即可启动。资料来源：[examples/flows/README.md:5-15]()

CLI 入口由 `acpx flow run` 承担，可接受的运行参数包括 `--input-file <path>`、`--input-json '<json>'`、`--timeout <sec>`、权限策略标志（如 `--approve-all`）以及输出格式（`text` / `json` / `json-strict` / `quiet`）。这些 CLI flag 的类型定义集中声明在 `src/cli/flags.ts` 中，例如 `format`、`timeout`、`ttl`、`approve-all` 等全局开关也复用于 flow 子命令。资料来源：[src/cli/flags.ts:1-60]()

举例：

```bash
# 直接以 JSON 输入运行示例
acpx flow run examples/flows/branch.flow.ts \
  --input-json '{"task":"FIX: add a regression test for the reconnect bug"}'

# 端到端 PR triage（必须显式授予 --approve-all）
acpx --approve-all flow run examples/flows/pr-triage/pr-triage.flow.ts \
  --input-json '{"repo":"openclaw/acpx","prNumber":150}'
```

资料来源：[examples/flows/README.md:25-40]()

## 扩展点与最佳实践

Flow 体系是 acpx 中最显式的扩展面，开发者可以从以下几个层次接入：

1. **节点作者扩展**：通过 `acpx/flows` 公共 API 编写自定义节点逻辑。`package.json` 的 `exports` 字段已经将 `acpx/flows` 作为稳定公共面发布（`./flows` 指向 `dist/flows.js`），外部包可以直接 `import { defineFlow } from "acpx/flows"`。资料来源：[package.json:40-60]()
2. **Agent 适配器扩展**：Flow 中的 `acp` 节点可以路由到任意 ACP 兼容 agent，包括内置的 `codex`、`claude` 等。Codex 适配器当前支持 `set model` 与 advertised model id（如 `gpt-5.2[high]`），在 Flow 中可以通过 `session/set_config_option` 进行控制。资料来源：[agents/Codex.md:1-10]()
3. **工作区隔离扩展**：`acp` 节点可以指定一个显式的 per-step `cwd`，让流程把 agent 工作圈定在可丢弃的 worktree 中，从而实现"flow workspace isolation"。资料来源：[README.md:30-50]()
4. **Replay 工具扩展**：由于运行 bundle 是结构化 JSON，社区可以构建自定义可视化或审计工具，无需修改 acpx 核心。

最佳实践：

- 把"需要模型判断"的部分放进 `acp` + `decision`，把"执行命令/GitHub 调用"放进 `action`；
- 长时间运行的判断节点使用 `checkpoint` 而不是阻塞等待；
- 涉及真实副作用（评论/合并 PR）的流程必须显式声明 `--approve-all`，例如 `pr-triage` 示例就在 README 中明确指出。资料来源：[examples/flows/README.md:45-55]()

## 失败模式与注意事项

- `pr-triage` 示例对真实 GitHub PR 具有副作用（评论、关闭），运行前需要明确仓库与 PR 号。资料来源：[examples/flows/README.md:50-55]()
- Flow 示例本身不构成 `acpx` 核心产品行为，其作用是演示公共作者面。资料来源：[examples/flows/README.md:55-60]()
- 当 ACP 连接中断时，运行时应尝试重连并恢复同一会话；若恢复失败必须显式失败，避免上下文丢失。资料来源：[examples/flows/pr-triage/README.md:15-25]()

## See Also

- 项目主索引：[README.md](README.md)
- Flow 示例目录：[examples/flows/README.md](examples/flows/README.md)
- PR Triage 规范：[examples/flows/pr-triage/README.md](examples/flows/pr-triage/README.md)
- Codex 适配器说明：[agents/Codex.md](agents/Codex.md)
- CLI flag 类型定义：[src/cli/flags.ts](src/cli/flags.ts)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：openclaw/acpx

摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Persisted token usage is always empty — breakdown rides on the prompt response (result.usage), not usage_update._meta.u…。

## 1. 安全/权限坑 · 来源证据：Persisted token usage is always empty — breakdown rides on the prompt response (result.usage), not usage_update._meta.u…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Persisted token usage is always empty — breakdown rides on the prompt response (result.usage), not usage_update._meta.usage
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/openclaw/acpx/issues/406 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://www.npmjs.com/package/acpx | host_targets=openclaw, claude

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://www.npmjs.com/package/acpx | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://www.npmjs.com/package/acpx | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://www.npmjs.com/package/acpx | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://www.npmjs.com/package/acpx | no_demo; severity=medium

## 7. 安全/权限坑 · 来源证据：Cursor ACP rejects shared/global --model values in ACPX while other providers accept them

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Cursor ACP rejects shared/global --model values in ACPX while other providers accept them
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/openclaw/acpx/issues/385 | 来源类型 github_issue 暴露的待验证使用条件。

## 8. 安全/权限坑 · 来源证据：Session-scoped MCP servers without writing to <cwd>/.acpxrc.json (CLI flag / config-path override)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Session-scoped MCP servers without writing to <cwd>/.acpxrc.json (CLI flag / config-path override)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/openclaw/acpx/issues/387 | 来源类型 github_issue 暴露的待验证使用条件。

## 9. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://www.npmjs.com/package/acpx | issue_or_pr_quality=unknown

## 10. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://www.npmjs.com/package/acpx | release_recency=unknown

<!-- canonical_name: openclaw/acpx; human_manual_source: deepwiki_human_wiki -->