pi ACP 适配器
将 pi 编程代理接入 Zed 等 ACP 客户端。
按维度查看评分与理由
适配器采用 stdio JSON-RPC，公开说明会启动本地 pi 进程、读取或写入项目文件、执行命令，并披露会话映射的存储位置；测试也表明工具调用、文件位置和完成后的实际差异会展示给客户端。扩展的 select/confirm 请求具有一次性允许或拒绝流程，发布工作流的权限也较窄。扣分在于 pi 的本地文件和命令能力没有适配器级最小权限边界或普遍的逐次确认机制；敏感数据、日志、提示内容及模型提供商传输的处理政策不完整；依赖使用范围版本且推荐的 npx 模式总是获取最新版；没有文件修改或命令执行的自动回滚。作者、仓库、许可证和 npm provenance 配置提供了归属线索，但发布者身份仍未由指定企业注册表验证。
组件测试覆盖事件顺序、重试、取消、排队、无效命令、扩展 UI 降级以及基于实际文件内容生成差异，显示普通交互路径有明确处理。依赖项、pi 最低版本和 PATH 要求均有说明，失败或不支持状态通常会向用户显示。扣分在于文档存在可见不一致：README 要求 Node.js 22+，package.json 声明 >=20；README 限制部分称没有单独 thought stream，而测试期望 agent_thought_chunk。材料也没有展示进程启动、协议失配、提供商认证等更广泛故障的消息处理。
目标用户和主要场景明确，即通过 Zed 等 ACP 客户端使用 pi，并提供注册表、npx、全局安装及源码安装方式。功能边界尤其清楚，明确列出未委托的文件系统和终端、未接通的 MCP 参数、不支持的命令及客户端兼容性风险，因此 capability_boundaries 获得满分。命令语法、环境变量和无效模式处理有示例，但普通提示、权限触发条件及跨客户端行为没有完整定义；此外项目以 Zed 为中心，且 Node 版本要求互相矛盾，限制了环境适配得分。
README 结构清晰，涵盖状态、功能、前置条件、安装、配置、命令、认证、开发、项目布局和限制；安装示例覆盖多条路径，因此信息架构和安装说明充分。限制清单具体，MIT 文本、元数据和 LICENSE 一致，故这两项可获满分。扣分在于配置示例交替使用 pi 和 pi-acp 作为服务器键名，缺少 FAQ 或系统化故障排除；虽然有 0.0.33 版本、标签发布说明和自动发布流程，但没有随附的持续 changelog；作者、问题追踪和仓库路径可识别维护入口，却没有维护政策、支持承诺或团队责任说明。
证据显示输出对编辑器直接可用：支持流式消息、思考片段、工具状态、终端元数据、文件位置、行号、真实修改前后差异、会话恢复和取消。作为 pi 与 ACP 客户端之间的专用桥接层，它提供了明显的增量价值，且只有两个运行时 npm 依赖并支持免全局安装，因此输出可用性和边际价值充分。成本效益扣分是因为始终获取最新版的 npx 路径、外部 pi 安装、模型服务费用以及本地执行风险均未被量化或系统说明。
README 的多项具体能力可由 package 元数据、工作流和组件测试交叉印证，包括事件映射、差异、位置、权限请求、重试、排队和取消。项目也使用 MVP、best-effort、可能不兼容等限定语，通常能区分承诺与限制。扣分在于所给材料缺少核心 src 实现和锁文件，无法从实现层完整追踪声明；测试本身仅是静态文本，不能证明已运行；部分文档声明还与测试或 package.json 不一致，因此未达到彻底可核验或完全交叉一致。
- pi 在本地直接读取、写入并执行命令；README 明确说明没有 ACP 文件系统或终端委托边界，不应假定客户端会为每个外部效果请求确认。
- 使用 npx -y pi-acp 会始终加载最新版，而项目同时警告可能发生小型破坏性变更；需要稳定部署时应固定并审核版本。
- Node.js 要求在 README 的 22+ 与 package.json 的 >=20 之间不一致，应在部署前自行确认实际兼容版本。
- 敏感提示、API 密钥、日志和模型提供商数据流没有完整政策说明；应隔离凭据并审查 pi 及其提供商配置。
- 虽然会展示文件差异并支持取消，但没有自动回滚；取消也不能证明已经发生的文件修改或命令副作用会被撤销。
这个 Agent 能做什么，适合哪些场景？
pi-acp 是 pi 编程代理与 Agent Client Protocol（ACP）客户端之间的适配器，开发重点是 Zed 编辑器。它通过标准输入输出提供 ACP JSON-RPC 2.0 接口，同时启动 `pi --mode rpc`，在两套协议之间转发请求和事件。适配器可流式输出助手消息，将 pi 的工具执行映射为 ACP 工具调用，并在可能时附带文件位置、行号和结构化编辑差异。它还支持会话持久化、文件式与内置斜杠命令、pi 技能命令，以及 Zed 中的启动信息和会话历史。该项目仍属于 MVP，部分 ACP 功能尚未实现，其他 ACP 客户端的兼容程度也可能不同。
ACP 客户端通过 stdio 向 pi-acp 发送 JSON-RPC 2.0 请求；适配器启动 pi --mode rpc，并在客户端与 pi 子进程之间转换请求和事件。助手输出被发送为 ACP agent_message_chunk，pi 工具执行被转换为 tool_call 和 tool_call_update。它会把相对工具路径按会话 cwd 解析为文件位置；对于 edit，还会在执行前保存文件快照，尝试通过唯一的 oldText 匹配推断从 1 开始的行号，并在完成后发出包含 oldText 与 newText 的结构化差异。pi 的会话仍存放在 ~/.pi/agent/sessions/...，适配器在 ~/.pi/pi-acp/session-map.json 保存映射，以便 session/load 重新连接原会话。它也会读取 ~/.pi/agent/prompts//*.md 和 <cwd>/.pi/prompts//*.md，提供 /compact、/export、/session、/name、/steering 等命令，并公开已启用的 /skill:skill-name 命令。
- 使用 Zed 编写代码、希望在编辑器的外部代理界面中运行 pi 的开发者。
- 需要在 ACP 客户端中实时查看助手输出、工具执行状态和文件位置的开发者。
- 希望在 Zed 和终端版 pi 之间恢复同一批会话文件的用户。
- 依赖项目级或用户级 Markdown 提示命令，并希望从 ACP 客户端调用这些命令的团队。
- 需要让 ACP 客户端展示编辑前后结构化差异并尽可能定位修改行的代码审查场景。
这个 Agent 有哪些优点和局限？
- 直接桥接 ACP JSON-RPC 2.0 与
pi --mode rpc，可将 pi 接入支持 ACP 的编辑器客户端。 - 工具事件不仅包含状态，还可提供已解析的绝对文件位置；
edit在条件允许时附带行号和结构化差异。 - 会话映射允许 ACP 客户端重新连接 pi 自身的会话文件，并可在 pi 与客户端之间恢复会话。
- 同时支持用户级、项目级、内置和技能斜杠命令，适合已有 pi 提示与技能配置的用户。
- 提供 ACP Registry、npx、全局安装和源码构建四种部署路径。
- 项目明确定位为 MVP，可能出现小幅破坏性变更，部分 ACP 功能尚未实现。
- 核心运行依赖 Node.js 22+、
piv0.80.4+、本地pi可执行文件以及单独配置的模型提供商或 API 密钥。 - 没有 ACP
fs/*文件系统委派和terminal/*终端委派；pi 会直接在本地读写文件并执行命令。 - ACP 参数中的 MCP 服务器只会保存在会话状态中，不会由该适配器连接到 pi。
- 扩展提供的斜杠命令不受支持，
/model和/clear也未实现；非 Zed 客户端的兼容性可能不同。
如何安装或部署这个 Agent？
前置条件是 Node.js 22+，并确保 pi v0.80.4+ 已在 PATH 中：npm install -g @earendil-works/pi-coding-agent。模型提供商及其 API 密钥需要在 pi 中单独配置。使用 Zed ACP Registry 时，运行 zed: acp registry 并选择 pi ACP；配置会写入 agent_servers.pi-acp，类型为 registry。无需全局安装时，可在 Zed 的 agent_servers.pi 中设置 "type": "custom"、"command": "npx"、"args": ["-y", "pi-acp"]。也可运行 npm install -g pi-acp，然后把命令设为 pi-acp；从源码安装则执行 npm install 和 npm run build，再让客户端运行 node /path/to/pi-acp/dist/index.js。
如何使用这个 Agent？
先在 pi 中完成模型提供商和 API 密钥配置，再按照安装说明把 pi-acp 注册为 ACP 服务器；从 Zed 的外部代理界面启动该服务器即可建立首个会话。若使用 ACP Registry 认证，可在 Zed 的 Authenticate 横幅中打开终端，或手动运行 pi-acp --terminal-login 完成交互式登录或设置。会话中可以直接发送编程请求，也可运行 /compact [instructions...]、/autocompact on|off|toggle、/export、/session、/name <name>、/queue all|one-at-a-time、/changelog、/steering 和 /follow-up。若要声明嵌入式上下文能力，可在服务器环境中设置 PI_ACP_ENABLE_EMBEDDED_CONTEXT=true；未启用时，意外收到的 resource 块会被转换为纯文本提示上下文。
这个 Agent 与同类方案有什么区别？
与直接在终端中运行 pi 相比，pi-acp 增加了面向 Zed 等客户端的 ACP 协议层、工具事件映射和编辑器会话体验，但仍由本地 pi 进程执行实际工作。README 提到的 pi MCP adapter 是补充方案：pi-acp 本身不会把 ACP 参数中的 MCP 服务器接入 pi。
常见问题
它是否自带模型或模型账号？
它会在哪里执行文件和终端操作？
fs/* 或 terminal/* 委派，因此客户端无法通过这些 ACP 接口隔离或代办相关操作。