acpx：让编码代理在无终端环境下协作的 ACP 命令行客户端
用于有状态代理客户端协议 (ACP) 会话的无头 CLI 客户端。
秒懂
- 它是什么？
- acpx 是一个面向 Agent Client Protocol 的无头 CLI，为编码代理提供持久会话和结构化输出。它适合自动化编排，但 pre-1.0 状态和依赖上游代理认证是采用前需要确认的关键点。
- 适合谁用？
- 适合需要将编码代理集成到自动化流水线的开发者或编排系统，尤其是希望避免终端转义序列、改用结构化事件输出的场景。不适合依赖图形界面或需要稳定 API 的生产环境，因为 acpx 明确标注为 pre-1.0，CLI 和运行时接口仍在变动。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库在最近一天内有新的提交。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
代理之间对话，而不是人与终端对话
acpx 解决的是一个具体问题：当编码代理（如 Codex、Claude Code）需要被另一个程序调用时，通常只能通过交互式终端，输出混杂着 ANSI 转义序列，会话状态也难以保存。acpx 作为 Agent Client Protocol 的无头客户端，把代理封装成一条命令行接口，让编排系统可以用结构化方式发起会话、发送提示词、读取事件。它的目标用户不是终端里的开发者，而是需要调度多个代理的 orchestrator，或者想在 CI 中运行代码审查的工程师。README 中的示例 `acpx codex "summarize this repository"` 展示的是一次典型调用，输出是 `[tool]` 和 `[done]` 标记的结构化事件，而不是终端画面。
ACP 协议：状态如何跨越多次调用保留
acpx 的核心机制是 Agent Client Protocol，它定义了客户端与编码代理之间的通信方法。会话状态保存在 `~/.acpx/` 目录下，这意味着每次调用 `acpx codex -s backend "trace the checkout timeout"` 时，代理能读取之前的上下文。会话支持并行命名工作流，当一轮对话还在运行时，后续提示词会进入队列。这种设计避免了自动化脚本意外启动新对话，因为显式创建会话（`acpx codex sessions new`）是开始对话的前提。相比之下，`exec` 子命令提供无状态运行，适合一次性任务。数据流是：CLI 解析参数，通过 ACP 与代理进程通信，将事件以 NDJSON 格式输出，或者以纯文本形式打印最终结果。
安装与启动：一条 npm 命令，但前置条件不少
安装很简单：`npm install -g acpx@latest`，要求 Node.js 22.13 或更高。不想全局安装时，可以用 `npx acpx@latest` 前缀。但真正运行前，你必须先安装并认证对应的上游代理，比如 Codex 或 Claude Code，除非该适配器自己处理认证。创建一个会话并发送提示词的命令是 `acpx codex sessions new` 和 `acpx codex "find the slowest test and explain why"`。会话默认绑定到当前仓库，这为多项目隔离提供了便利。自定义 ACP 服务器通过 `acpx --agent '<command>'` 启动，配置文件可以设置全局或项目级别的默认值，命令行参数优先。
输出格式：从终端噪音到机器可读事件
文本输出是默认选项，但自动化场景更关心 `--format json`，它输出 NDJSON 格式的 ACP 事件，保留结构化思考、工具调用、diff 和完成状态。`--format quiet` 只打印最终助手文本，适合日志精简。相比之下，直接调用代理的终端输出包含转义序列，解析困难。acpx 把事件流暴露出来，让下游程序可以精确知道代理做了什么，而不是猜测。但要注意，JSON 输出的结构取决于 ACP 协议的实现程度，README 提到了一个 ACP 覆盖路线图（docs/2026-02-19-acp-coverage-roadmap.md），说明并非所有协议方法都已实现，实际字段可能随版本变化。
权限模式：控制代理能碰什么
acpx 的权限模式从读取审批到显式拒绝或批准所有策略，覆盖了不同风险等级。`--cwd` 参数设置会话范围和文件系统边界，这比单纯依赖代理自身的沙箱更直接。但文档没有详细说明每种模式的具体行为，比如审批是交互式还是通过回调处理。对于无人值守的自动化，`deny` 或 `approve-all` 可能更合适，但这也意味着要么限制代理能力，要么完全信任它。这是一个明显的权衡：权限控制越细，自动化程度越低；越宽松，风险越高。采用前需要阅读 permissions 文档，确认模式与你的工作流匹配。
流程编排：超越单轮对话的 TypeScript 工作流
`acpx flow run` 是比简单会话更高级的功能，它执行 TypeScript 编写的工作流，将 ACP 对话与确定性动作、决策、计算和检查点组合在一起。这意味着你可以编写一个流程，先让代理分析代码，然后根据结果执行特定命令，再继续下一轮对话。包还导出 `acpx/runtime` 和 `acpx/flows`，供应用程序直接使用这些原语，而不必通过命令行。这适合复杂任务，比如多步骤重构。但文档指出这是较新的功能，架构说明文档（docs/2026-03-25-acpx-flows-architecture.md）单独存在，暗示它可能不如核心会话功能成熟。对于简单用例，直接用 `exec` 可能更省事。
维护成本与许可：MIT 下的 pre-1.0 现实
acpx 采用 MIT 许可，这意味着你可以自由使用和修改，但项目明确标注 pre-1.0，CLI 和运行时接口被描述为“evolving”。最近发布频率不低（v0.13.0 到 v0.13.2 间隔约一个月），这既是活跃的信号，也意味着升级可能引入破坏性变更。会话数据存储在 `~/.acpx/`，升级时需要注意格式兼容性，文档提到导出/导入功能，但未说明具体版本迁移策略。对于长期运行的系统，锁定版本并定期测试升级是必要的，但 README 没有给出迁移指南。另一个成本是上游代理的维护：acpx 只是客户端，Codex 或 Claude Code 的认证和版本更新仍需你自行管理。
替代方案：直接调用代理 API 与终端自动化
一个现实的替代方案是直接使用各代理的官方 API 或 SDK，例如 Codex 的 API，但这需要为每个代理编写不同的集成代码，且通常不提供统一的会话抽象。另一个方案是使用 expect 脚本或类似工具驱动现有 CLI，但这种方式脆弱，容易因终端输出变化而失效。acpx 的差异在于它建立在 ACP 标准之上，提供一致的接口，并输出结构化事件，这比解析 ANSI 转义序列可靠得多。然而，ACP 本身是相对较新的协议，其覆盖范围有限，如果某个代理不支持所需的协议方法，acpx 可能无法提供帮助。对于只需要单一代理的场景，直接使用代理自带 CLI 可能更简单，acpx 的价值体现在多代理或自动化编排时。
编辑结论
适合需要将编码代理集成到自动化流水线的开发者或编排系统，尤其是希望避免终端转义序列、改用结构化事件输出的场景。不适合依赖图形界面或需要稳定 API 的生产环境，因为 acpx 明确标注为 pre-1.0，CLI 和运行时接口仍在变动。采用前应验证：上游代理（如 Codex、Claude Code）是否已安装并完成认证，Node.js 版本是否不低于 22.13，以及权限模式（如 deny、approve-all）是否符合你的安全策略。建议从 `acpx codex exec` 开始做无状态测试，再逐步启用持久会话。
社区笔记