acpx 项目说明书 - Doramagic.ai

Doramagic 项目包 · 项目说明书

acpx 项目

用于 Agent Client Protocol (ACP) 的无界面命令行客户端，可在命令行中与编码代理交互。

acpx 概述与系统架构

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

章节 相关页面

继续阅读本节完整说明和来源证据。

项目定位与核心价值

acpx 是一个面向 Agent Client Protocol (ACP) 的无头 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。

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"）与 [email protected] 作为包管理器资料来源：package.json:175-185。

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

acpx 是 Agent Client Protocol (ACP) 的无头 CLI 客户端，它通过统一的命令入口把多个 ACP 兼容的编程代理暴露给用户与编排器。内置代理注册表（built-in agent registry）的核心职责，是把命令行中的代理名（例如 codex、claude、pi）映射到具体的适配器实现（adapter），而适配器再规定如何通过 stdio...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述

acpx 是 Agent Client Protocol (ACP) 的无头 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

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

解析与回退机制

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

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

资料来源：README.md:70-73

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

自定义适配器与配置

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

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

会话、队列与权限控制

acpx 是一个无头 CLI 客户端，作为 Agent Client Protocol (ACP) 的客户端与多个 coding agent（Codex、Claude、Pi、OpenClaw ACP bridge 等）通过结构化协议通信。其核心交互模型围绕三类控制面：会话（Session）、提示队列（Prompt Queue）与权限控制（Permission Contr...

章节 相关页面

继续阅读本节完整说明和来源证据。

acpx 是一个无头 CLI 客户端，作为 Agent Client Protocol (ACP) 的客户端与多个 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 区）：

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 的总耗时。

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"}`

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 一节）。

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。

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

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

章节 相关页面

继续阅读本节完整说明和来源证据。

概览与定位

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

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

举例：

# 直接以 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 中最显式的扩展面，开发者可以从以下几个层次接入：

节点作者扩展：通过 acpx/flows 公共 API 编写自定义节点逻辑。package.json 的 exports 字段已经将 acpx/flows 作为稳定公共面发布（./flows 指向 dist/flows.js），外部包可以直接 import { defineFlow } from "acpx/flows"。资料来源：package.json:40-60
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
工作区隔离扩展：acp 节点可以指定一个显式的 per-step cwd，让流程把 agent 工作圈定在可丢弃的 worktree 中，从而实现"flow workspace isolation"。资料来源：README.md:30-50
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

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Persisted token usage is always empty — breakdown rides on the prompt response (result.usage), not usage_update._meta.u…

可能影响授权、密钥配置或安全边界。

medium 可能修改宿主 AI 配置

安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。

medium 能力判断依赖假设

假设不成立时，用户拿不到承诺的能力。

medium 维护活跃度未知

新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录

acpx 项目

acpx 概述与系统架构

项目定位与核心价值

系统架构与组件划分

内置适配器与扩展点

协议合规与安装运行

See Also

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

概述

内置适配器清单

解析与回退机制

自定义适配器与配置

See Also

会话、队列与权限控制

会话管理

提示队列与生命周期

权限控制

全局选项与配置

社区与版本注记

See Also

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

概览与定位

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

Replay 工具与运行产物

扩展点与最佳实践

失败模式与注意事项

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

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

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

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

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

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

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

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

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

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