Agent skill

acpx

Headless ACP CLI for agent-to-agent communication. Use when running coding agents (pi/qwen/codex/claude/gemini) headlessly, managing persistent sessions, queueing prompts, or consuming structured agent output from scripts. 触发词：acpx, ACP, agent communication, headless agent, session management, agent orchestration, 代理通信, 无头代理

View SKILL.md on GitHub Repository
Stars 3
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/Dwsy/agent/tree/main/skills/acpx

SKILL.md

acpx - Headless ACP CLI

ACP (Agent Client Protocol) 的无头 CLI 客户端，专为 agent-to-agent 通信设计，避免 PTY 抓取问题。

安装

bash
npm i -g acpx

核心能力

能力 说明
持久会话 多轮对话，按 repo/cwd 自动恢复
一次性执行 exec 模式，单次执行不保存状态
并行会话 -s/--session 命名会话，同仓库多对话
队列管理 多个 prompt 自动排队，--no-wait 异步提交
权限控制 --approve-all/--approve-reads/--deny-all
结构化输出 text/json/quiet 三种格式
优雅取消 cancel 命令或 Ctrl+C 发送 ACP session/cancel

内置 Agent 注册表

名称 命令
pi npx pi-acp
qwen qwen --acp
codex npx @zed-industries/codex-acp
claude npx -y @zed-industries/claude-agent-acp
gemini gemini --acp
cursor cursor-agent acp
copilot copilot --acp --stdio
openclaw openclaw acp
droid droid exec --output-format acp
kimi kimi acp
opencode npx -y opencode-ai acp
kiro kiro-cli acp
kilocode npx -y @kilocode/cli acp

默认 agent 是 codex。

命令模型

bash
# 基本用法
acpx <agent> '<prompt>'              # 持久会话模式
acpx <agent> exec '<prompt>'         # 一次性执行
acpx <agent> -s <name> '<prompt>'    # 命名会话

# 会话管理
acpx <agent> sessions                # 列出会话
acpx <agent> sessions new            # 新建会话
acpx <agent> sessions show [name]    # 显示会话详情
acpx <agent> sessions history [name] # 查看历史
acpx <agent> sessions close [name]   # 关闭会话

# 控制
acpx <agent> cancel                  # 取消当前任务
acpx <agent> set-mode <mode>         # 设置模式
acpx <agent> set <key> <value>       # 设置选项
acpx <agent> status                  # 查看状态

全局选项

选项 说明
--agent <cmd> 原始 ACP agent 命令（逃逸口）
--cwd <dir> 工作目录（影响会话作用域）
--approve-all 自动批准所有权限请求
--approve-reads 批准读取，写入需确认（默认）
--deny-all 拒绝所有权限请求
--format <fmt> 输出格式：text/json/quiet
--timeout <s> 最大等待时间
--ttl <s> 队列所有者空闲 TTL（默认 300s）
--verbose 详细日志

输出格式

text（默认）

人类可读的流式输出，带更新和工具状态。

json

NDJSON 事件流，适合自动化：

bash
acpx --format json qwen 'review code' | jq -r 'select(.type=="tool_call") | [.status, .title] | @tsv'

quiet

仅输出最终结果，适合脚本：

bash
result=$(acpx --format quiet qwen exec 'summarize repo')

实用工作流

持久仓库助手

bash
# 第一次：分析问题
acpx qwen 'inspect failing tests and propose a fix plan'

# 后续：继续同一会话
acpx qwen 'apply the smallest safe fix and run tests'

并行命名流

bash
acpx qwen -s backend 'fix API pagination bug'
acpx qwen -s docs 'draft changelog entry for release'

队列异步提交

bash
# 启动任务
acpx qwen 'run full test suite and investigate failures'

# 不等待，排队执行
acpx qwen --no-wait 'after tests, summarize root causes'

一次性脚本步骤

bash
summary=$(acpx --format quiet exec 'summarize repo purpose in 3 lines')
echo "Summary: $summary"

机器可读输出用于编排

bash
acpx --format json qwen 'review current branch changes' > events.ndjson

使用自定义 adapter

bash
acpx --agent './bin/custom-acp-server --profile ci' 'run validation checks'

指定工作目录

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

会话行为

会话作用域由以下决定：

  • agentCommand（agent 命令）
  • 绝对 cwd（工作目录）
  • 可选的 session name

持久化：

  • 会话记录存储在 ~/.acpx/sessions/*.json
  • -s/--session 在同一仓库创建并行命名对话
  • 关闭的会话保留 closed: true 和 closedAt 时间戳
  • 自动恢复跳过已关闭的会话

队列机制

每个持久会话有独立队列：

  • 当前运行的 acpx 进程成为队列所有者
  • 其他调用通过本地 IPC 提交 prompt
  • Unix 使用 ~/.acpx/queues/<hash>.sock
  • Windows 使用命名管道
  • 所有者空闲 TTL 后自动关闭（默认 300s）

配置文件

配置合并顺序（后优先）：

  1. 全局：~/.acpx/config.json
  2. 项目：<cwd>/.acpxrc.json

支持配置：

  • defaultAgent：默认 agent
  • defaultPermissions：权限模式
  • ttl：空闲 TTL
  • timeout：超时
  • format：输出格式
  • agents：agent 名称映射
  • auth：认证凭据
bash
acpx config show   # 查看配置
acpx config init   # 初始化全局配置模板

错误处理

  • NO_SESSION：无持久会话，需先 sessions new
  • 权限被拒绝：所有权限请求被拒绝时退出
  • 超时：超过 --timeout 时退出
  • Ctrl+C：发送 ACP session/cancel，等待后强制终止

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

Dwsy/agent

undo-redo

Use the undo_redo tool to rewind or reapply buffered file changes or inspect diffs without UI navigation. Use when you need to adjust or verify changes in the current session history.

3 0
Explore
Dwsy/agent

exa

使用 Exa.ai API 进行高质量的互联网搜索。需要 EXA_API_KEY 环境变量。

3 0
Explore
Dwsy/agent

backend-unit-test

后端单元测试技能。触发场景： - 用户要求运行/创建单元测试 - 用户要求验证数据 - 用户要求用 Maven 运行测试 - 关键词：test, maven test, junit, springboot test, 单元测试, 测试验证 核心：不改 pom，用 reactor 模式运行。

3 0
Explore
Dwsy/agent

mermaid-flow-image

将流程需求整理为可渲染的 Mermaid（简化版/详细版），并通过 Kroki 生成可发送的高分辨率 PNG 图片。适用于“把架构流程画出来并直接发图”的场景。

3 0
Explore
Dwsy/agent

web-browser

Allows to interact with web pages by performing actions such as clicking buttons, filling out forms, and navigating links. It works by remote controlling Google Chrome or Chromium browsers using the Chrome DevTools Protocol (CDP). When Claude needs to browse the web, it can use this skill to do so.

3 0
Explore
Dwsy/agent

ralph-loop-gen

任务管理系统模板生成器 - 根据用户输入或JSON配置生成完整的任务管理结构（模板生成器，非直接执行器）

3 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results