acpx

acpx

何时使用此技能

当你需要通过 acpx 运行编码 Agent、管理持久化 ACP 会话、将提示词加入队列，或从脚本中读取结构化输出时，请使用此技能。

尤其适用于 wave-planner-acpx 获批后的 Wave-Driven Development 执行。

acpx 是什么

acpx 是一个用于 ACP（Agent Client Protocol）的无头、可编写脚本的 CLI 客户端，旨在实现 Agent 到 Agent 的自动化，无需抓取 PTY 内容。

核心功能：

• 按仓库或 cwd 管理持久化的多轮会话
• 单次执行模式（exec）
• 命名并行会话（-s/--session）
• 支持队列的提示词提交，可选择即发即忘（--no-wait）
• 协作式取消（cancel）正在执行的轮次
• 会话控制（set-mode、set <key> <value>）
• 检查会话元数据和历史记录（sessions show、sessions history）
• 检查本地 Agent 进程（status）
• 结构化输出格式（text、json、quiet）
• 使用 --suppress-reads 获得更简洁的编排输出
• 使用 --prompt-retries 重试临时提示词错误
• 通过 ACP session/set_model 通用地选择模型
• 支持 Codex 会话的 --model
• v0.4.0 中的实验性流程运行时和回放相关工具

安装

npm i -g acpx

为稳定复用会话，建议使用全局安装，而不是 npx。

命令模型

默认命令是 prompt。

acpx [global_options] [prompt_text...]
acpx [global_options] prompt [prompt_options] [prompt_text...]
acpx [global_options] exec [prompt_options] [prompt_text...]
acpx [global_options] cancel [-s <name>]
acpx [global_options] set-mode <mode> [-s <name>]
acpx [global_options] set <key> <value> [-s <name>]
acpx [global_options] status [-s <name>]
acpx [global_options] sessions [list | new [--name <name>] | close [name] | show [name] | history [name] [--limit <count>]]
acpx [global_options] config [show | init]

acpx [global_options] <agent> [prompt_options] [prompt_text...]
acpx [global_options] <agent> exec [prompt_options] [prompt_text...]

内置 Agent 注册表

友好名称：

• codex -> npx @zed-industries/codex-acp
• claude -> npx @zed-industries/claude-agent-acp
• gemini -> gemini
• opencode -> npx opencode-ai
• pi -> npx pi-acp
• qoder -> qodercli --acp
• trae -> traecli acp serve

规则：

• 默认 Agent 是 codex。
• 未知的位置 Agent 标记会被视为原始命令。
• --agent <command> 是显式的原始命令模式。
• 不要同时使用位置 Agent 标记和 --agent。

核心工作流

持久化提示词会话

acpx codex 'inspect failing tests and propose fix plan'
acpx codex 'apply minimal fix and run tests'

单次执行

acpx exec 'summarize this repo'
acpx codex exec 'review changed files'

会话

acpx sessions new --name backend
acpx codex -s backend 'fix API pagination bug'
acpx codex sessions history backend --limit 20
acpx codex sessions close backend

排队和即发即忘

acpx codex 'run full test suite and investigate failures'
acpx codex --no-wait 'after tests, summarize root causes and next steps'

用于编排的结构化输出

acpx --format json codex exec 'review changed files' > events.ndjson

重试和更简洁的日志

acpx codex --prompt-retries 2 'run targeted tests and summarize failures'
acpx --format json --suppress-reads codex exec 'review changed files'

Wave-Driven 编排指南

按波次运行工作 Agent 时：

1. 为每个工作 Agent 创建一个命名会话（-s <agent-name>）。
2. 向工作 Agent 发送带有严格所有权边界的提示词。
3. 要求每个响应都包含明确的完成标记。
4. 等待收到标记后再合并。
5. 按波次顺序合并。
6. 在开始下一波之前运行集成检查。

建议的完成标记： WAVE {WAVE_ID} / {AGENT_NAME} DONE

建议的工作 Agent 交接格式：

1. 摘要
2. 更改的文件
3. 补丁/差异
4. 测试方法（命令和预期结果）
5. 风险/TODO/依赖项说明

全局选项

• --agent <command> 原始 ACP 适配器命令
• --cwd <dir> 会话作用域目录
• --approve-all 自动批准所有请求
• --approve-reads 批准读取/搜索操作，写入操作则提示确认
• --deny-all 拒绝所有请求
• --model <id> 在目标 Agent/会话支持时请求指定模型
• --format <fmt> 输出格式：text、json、quiet
• --suppress-reads 在需要更简洁日志时隐藏原始读取/搜索输出
• --prompt-retries <count> 自动重试临时提示词错误
• --timeout <seconds> 最大等待时间
• --ttl <seconds> 队列所有者的空闲 TTL
• --verbose 调试日志

权限标志不能同时使用。

会话行为

持久化提示词会话的作用域由以下项确定：

• agentCommand
• 绝对路径 cwd
• 可选的 session 名称

提示：

• 在同一仓库中并行处理时使用命名会话。
• 谨慎使用 --cwd；更改 cwd 会改变会话作用域。
• 使用 status 和 sessions show/history 调试状态。

实用示例

并行命名工作流：

acpx codex -s backend 'implement contract types for Wave 0'
acpx claude -s docs 'draft migration notes for Wave 0'

在宽松模式下进行仓库范围的审查：

acpx --cwd ~/repos/shop --approve-all codex -s pr-842 \
  'review PR #842 for regressions and propose minimal patch'