企业官网建设流程全解析

什么是acpx？一文看懂统一操控20+ AI编码代理的无头ACP客户端全景图

【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpx

acpx是一个无头（Headless）ACP 命令行客户端，让你用一条统一的命令操控 20+ 款 AI 编码代理（Codex、Claude Code、Gemini、Cursor 等）。它把"有状态的 ACP 会话、一次性任务、权限审批、机器可读输出"收敛成同一套接口，是自动化流水线里连接 AI 编码代理的终极瑞士军刀 🧰。

一、acpx 是什么？

先讲人话：acpx 就是一个"AI 编码代理的统一遥控器"。

过去你每接一个 AI 编码工具（Codex、Claude Code、Kiro……）就要学一套交互方式；想做自动化时，很多人只能靠"抓取终端输出"这种脆弱手段。acpx 基于 Agent Client Protocol (ACP) 这个开放协议，直接以结构化 JSON-RPC 与代理对话：

核心代码入口在 src/cli.ts 与 src/cli-core.ts，内置代理注册表位于 src/agent-registry.ts。

二、为什么需要无头 ACP 客户端？

• 🤖代理之间要对话：acpx 的主用户其实是"另一个 AI 或编排器"，人类可以直接驱动，但它是为自动化而生的（见 VISION.md）。
• 🔁上下文不丢失：持久会话让多轮对话跨越进程存活，追问时自动恢复上下文。
• 📦可嵌入：npm 包导出acpx/runtime与acpx/flows，应用不必重复造轮子，直接复用会话存储、队列与生命周期管理。
• 🧾机器可读：--format json每行一条 ACP JSON-RPC 消息，管道接jq就能做流水线。

三、如何一键安装 acpx？（最快 30 秒上手）

1️⃣ 要求Node.js 22.13+，然后全局安装：

npm install -g acpx@latest

2️⃣ 不想全局安装？每条命令前加npx acpx@latest即可。

3️⃣ 想从源码构建？克隆仓库后执行pnpm install与pnpm run build：

git clone https://gitcode.com/gh_mirrors/ac/acpx

完整安装细节见 docs/install.md。

四、acpx 三步速通教程：建会话、发提示、看结果

以 Codex 为例（其他代理命令形状完全一致）：

acpx codex sessions new # 第1步：创建会话 acpx codex "找到最慢的测试并解释原因" # 第2步：发送提示 acpx codex "再给出一个一行修复方案" # 第3步：上下文自动延续

你会看到结构化的事件流：助手文本、[tool]工具调用块、计划更新，以及最终的[done] end_turn。

两个高频技巧：

• 一次性任务：acpx codex exec "用5句话总结这个仓库"—— 不读不写任何保存的会话，脚本友好。
• 排队不阻塞：上一轮还在跑时，acpx codex --no-wait "…"会把新提示排队到运行中的会话上，fire-and-forget。

更完整的入门路径参考 docs/quickstart.md。

五、如何统一操控 20+ AI 编码代理？

acpx 内置了一份友好的代理注册表：25 个预置名字，每个都解析为对应的 ACP 适配器命令，全部支持同一套命令面（prompt/exec/cancel/sessions/status）：

完整清单见 docs/agents.md，每个代理的适配说明放在 agents/ 目录（如 agents/Claude.md、agents/Codex.md）。

隐藏福利——横向对比命令：同一个提示词丢给多个代理，输出并排摘要：

acpx compare codex claude gemini "总结这次改动"

详见 docs/compare.md。自定义代理则用acpx --agent '<command>' …，配置指南在 docs/custom-agents.md。

六、持久会话：上下文跨进程存活，还能并行开多路

会话按(代理命令, 绝对目录, 可选名称)作为作用域键持久化在~/.acpx/下：

• 目录内自动恢复：在src/子目录发提示，会自动恢复仓库根目录创建的会话，体验上就像"我一直在这个仓库里和 codex 聊天"。
• 命名会话并行：-s backend修 API、-s docs写发布说明，两条工作流互不干扰。
• 完整生命周期：sessions子命令支持 list / new / show / history / export / import / prune 等，详见 docs/sessions.md 与 docs/session-control.md。

七、权限管控与机器可读输出：自动化的安全阀

ACP 代理在执行写文件、跑命令前会请求权限，acpx 用清晰的模式替你裁决：

进阶玩法是用--permission-policy做按工具细分的策略（autoApprove / autoDeny / escalate），规则细节见 docs/permissions.md。

输出格式三选一：文本（默认）、quiet（只要最终答案）、json（NDJSON 全量 ACP 事件），格式说明在 docs/output-formats.md，退出码语义见 docs/exit-codes.md。

八、Flows：把多步 AI 工作流写成 TypeScript 模块

当"一个提示词不够用"时，acpx 的 Flows（实验性功能）登场：用 TypeScript 定义工作流，混合ACP 对话节点 / shell 动作 / 计算 / 决策 / 检查点，运行状态持久化在~/.acpx/flows/runs/，每一步可检查、可重放。

acpx flow run ./my-flow.ts --input-file ./input.json

官方示例包括 PR 分诊流水线，可参考 examples/flows/ 与 examples/flows/README.md，架构设计文档在 docs/2026-03-25-acpx-flows-architecture.md。若你的应用需要与 CLI 共享同一个本地会话属主，可用createSharedAcpRuntime()，见 docs/shared-sessions.md。

九、项目结构导览：核心模块在哪里

文档体系以 docs/ 为主：CLI 参考、提示词指南、配置说明。

十、总结：一张图记住 acpx

• 一个协议：ACP，摆脱终端抓取和适配胶水代码；
• 一个接口：20+ AI 编码代理共享同一命令面，随时切换、随时对比；
• 两种形态：既是人类可操作的 CLI，也是可嵌入（acpx/runtime）的会话后端；
• 三大场景：多轮持久会话、无状态一次性exec、多步 Flows 工作流。

acpx 目前处于 1.0 之前，接口仍在演进（MIT 协议，见 LICENSE）。如果你想让 CI、编排器或另一个 AI 稳定地"指挥"一堆编码代理，它就是那个完整、简单又免费的统一入口 —— 现在就试试你的第一条acpx命令吧 🚀

【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpx