@geohar/pi-acp

中文文档
0.4.0发布于 2026/11/05MITES Module构建来源已验证近 30 天下载 1.1万

用于 pi 编码剂(fork)的 ACP 适配器,用于 ssub agent plan 的捆绑 pi 扩展

中文使用文档
文档目录15 节
  1. 状态
  2. 与上游的差异
  3. 特征
  4. 先决条件
  5. 安装
  6. 将 pi-app 添加到您的 ACP 客户端,例如 . 齐德
  7. 设置( E) pi-acp.json (中文(简体) )
  8. 斜线命令
  9. 作为任务的子代理
  10. 认证(非专利登记支助)
  11. 发展
  12. 限制
  13. MCP 服务器
  14. MCP 生成政策
  15. 许可证

皮亚克

非加太集团代理客户协议适配器 pi 编码代理(fka 低劣编码代理).

pi-acp 通讯 ACP JSON-RPC 2.0 优于标准 给非加太客户端(如Zed编辑)和产卵 pi --mode rpc连接请求/活动.

状态

这是一个MVP风格的适配器,意在今天有用并易于被移动. 一些非加太国家特征可能没有得到实施或支持(见: 限制) (中文(简体) ). 以发展为中心 齐德 编辑器支持,其他客户端可能具有不同程度的相容性.

等待一些小的突破变化.

与上游的差异

这是叉子 svkozak/pi-acp,作为 npm 发布 @geohar/pi-acp (上游无范围) pi-acp) (中文(简体) ).

何以为叉. 它的存在是为了在上游携带能力 并不具备,主要是表面 亲水师 编队作为非加太任务,自动配置 MCP 对pi,多根的工作空间, 和向ACP v2 前进—— 并独立地执行它们。 这是 独立分叉在 @geohar 范围以便安装并依赖 直接追踪到上游 没有承诺提供这些 向后变化(它们可能晚于上游)。 如果你想要原件,请使用 svkozak/pi-acp。 。 。 .

在上游

  • 作为非加太任务的子代理人 - 一个捆绑的pi扩展桥 亲水师 进入非加太集团 plan 频道,所以 每个副代理都作为任务出现。 见 作为任务的子代理。 。 。 .
  • MCP 自动配置 - 非加太国家 mcpServers 被翻译为生成 <cwd>/.pi/mcp.json 页:1 pi- mcp- 适应器 装入。 见 MCP 服务器。 。 。 .
  • 多根工作空间 ——新增工作空间根基 session/new 编号 : session/load (单位:千美元)sessionCapabilities.additionalDirectories,通过 --append-system-prompt。 。 。 .
  • v2 面向会话的能力 - 广告 session/resume, (中文(简体) ), session/close,以及 mcpCapabilities.http (实现非加太 v2 均等的步骤;见 docs/v2-parity-and-mcp-plan.md) (中文(简体) ).
  • PI_ACP_DATA_DIR ——适配器自身数据目录的env 覆盖(参见 环境变量) (中文(简体) ).

特征

  • 作为非加太集团的流程助理产出 agent_message_chunk
  • 将 pi 工具执行映射到 ACP tool_call 编号 : tool_call_update
    • 当支持打开引用文件/内容的非加太客户可用时,工具呼叫位置会浮出水面
    • Pi 的相对文件路径在作为 ACP 工具位置发布前会话 cwd 被解决, 这样可以让 Zed 这样的客户端具有后续功能
    • 对于 edit, (中文(简体) ), pi-acp 试图从一个独特的 oldText 匹配编辑前文件快照,并在可能时将其包含在已发布工具位置
    • 对于 edit, (中文(简体) ), pi-acp 在工具运行前快照文件并发布 ACP 结构化 diff (单位:千美元)oldText编号 :newText尽可能完成时
  • 持续会期
    • pi 将自己的会话存储在 ~/.pi/agent/sessions/...
    • pi-acp 存储一个小映射文件 ~/.pi/pi-acp/session-map.json 这样 session/load 能够重接到上一个 pi 会话文件
  • 多工作空间支持sessionCapabilities.additionalDirectories(中文(简体) )
    • 非加太公司客户可以通过额外的工作空间根基 session/new 编号 : session/load (如Zed多根工作空间)
    • cwd 保留主工作目录; 额外的根通过 --append-system-prompt由于pi没有本土的多根工作空间概念
  • 斜线命令
    • 装入与 pi 常规兼容的基于文件的斜线命令
    • 为无头/ 编辑用户添加一小组内置命令
    • 支持技能命令( 如果在 pi 设置中启用, 它们显示为 /skill:skill-name (非加太客户端)
  • 技能由 pi 直接加载,并在非加太课程中提供
  • (泽德) pi-acp 向会话中发送“启动信息”块(pi 版本、上下文、技能、提示、扩展-类似于 pi 在终点站。 您可以通过设置来禁用 quietStartup: true 在 pi 设置中 (~/.pi/agent/settings.json 或者说 <project>/.pi/settings.json) (中文(简体) ). 何时 quietStartup 已启用, pi-acp 如果安装的 pi 版本已经过时, 仍然会发出“ 新版本可用 ” 消息 .
  • (Zed)会话历史在Zed中支持,从 v0.225.0。会话加载/历史图到 pi 的会话文件。 可在 pi 在非加太客户端.

先决条件

确保 Pi 已安装

npm install -g @earendil-works/pi-coding-agent
  • 节点.js 22+
  • pi v0.80.4+ 安装并可用于您的 PATH (适配器运行 pi 可执行文件)
  • 配置 pi 用于您的模型提供者/ API 密钥

安装

将 pi-app 添加到您的 ACP 客户端,例如 . 齐德

在Zed使用非加太公司登记处或支持它的其他客户

在Zed公司发射登记册 zed: acp registry 命令和选择 pi ACP 列表中的适配器 。 这将自动将代理服务器配置添加到您的 settings.json 并不断更新:

  "agent_servers": {
    "pi-acp": {
      "type": "registry",
    },
  }

使用方式 npx (不需要全局安装, 总是装入最新版本)

在您的 Zed 中添加以下内容 settings.json数字 :

  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "npx",
      "args": ["-y", "@geohar/pi-acp"],
      "env": {}
    }
  }

全局安装

npm install -g @geohar/pi-acp
  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "pi-acp",
      "args": [],
      "env": {}
    }
  }

从源

npm install
npm run build

将您的 ACP 客户端指向已建 dist/index.js数字 :

  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "node",
      "args": ["/path/to/pi-acp/dist/index.js"],
      "env": {}
    }
  }

设置( E)pi-acp.json(中文(简体) )

pi-app 读取自己的设置 pi-acp.json 在pi经纪人那里 extensions/ 目录——即:. <PI_CODING_AGENT_DIR>/extensions/pi-acp.json (默认) ~/.pi/agent/extensions/pi-acp.json),与其他扩展设置相通。 这是一个专用 pi- app 文件; 它是 没有 合并为pi自己的 settings.json。如果一个默认文件不存在,则在第一个运行中写入一个默认文件,而一个已有文件则永远不会被覆盖。 对于后向相容性,前为0.2.2位- <PI_CODING_AGENT_DIR>/pi-acp.json (agent root) — 当文件不存在时, 仍然读作倒置 extensions/。 。 。 .

选项 :

  • embeddedContext (布尔,默认) true()——广告非加太公司 promptCapabilities.embeddedContext 给客户的 何时 false,符合要求的非加太客户应避免发送嵌入式 resource 块; 如果他们还是发送它们, pi-acp 仍然通过将它们转换成纯文本的即时上下文而优雅地降解.
  • rpcTimeoutMs (数字,默认) 120000)——按要求暂停Pi RPC通话. 如此优雅的慢指令( 如收缩) 完成 .
  • debug (布尔,默认) false)——放出适配器调试日志到stderr.
  • piCommand (字符串,可选) – 覆盖 pi 可执行名称/路径. 缺席 = 平台默认(pi,或 pi.cmd )),在视窗上.
  • dataDir (字符串,可选) – 覆盖 pi-app 自己的数据目录. 缺席= ~/.pi/pi-acp。此控件可以控制会话图文件和未来任何适配器拥有的数据的存储位置;它与 PI_CODING_AGENT_DIR,它重现了pi自己的代理目录(因此 extensions/pi-acp.json) (中文(简体) ).

第一次运行时写入的默认文件包含:

{
  "embeddedContext": true,
  "rpcTimeoutMs": 120000,
  "debug": false
}

斜线命令

pi-acp 支持斜线命令 :

1) 基于文件的命令( aka 提示)

装入自 :

  • 用户命令 : ~/.pi/agent/prompts/**/*.md
  • 项目命令 : <cwd>/.pi/prompts/**/*.md

2) 内建命令

  • /compact [instructions...] - 运行 pi 压缩(可选择使用自定义指令)
  • /autocompact on|off|toggle - 切换自动收缩
  • /export - 在会话中导出当前会话到 HTML cwd
  • /session - 显示会话统计数据(电话/留言/费用/会话文件)
  • /name <name> - 设置会话显示名称
  • /queue all|one-at-a-time - 设置 pi 队列模式( 不稳定特性)
  • /changelog - 打印已安装的 pi 更改日志( 最佳)
  • /steering - 地图到 pi 引导模式、 获取/ 设定
  • /follow-up - 拍下来 pi 后续模式、获取/设定

其他内置命令 :

  • /model - 未执行(在Zed中使用模型选择器 UI)
  • /thinking - Zed中“模式”选择器的地图
  • /clear - 未执行(使用 ACP 客户端“ 新” 命令)

3) 技能命令

  • Skill 命令可以在 pi 设置中启用,并将以 ACP 客户端的 slash 命令列表中显示为 /skill:skill-name。 。 。 .

说明: pi扩展提供的斜线命令目前不支持.

作为任务的子代理

非加太计划,所以非加太计划 plan (任务列表)频道未使用. 当你使用 亲水师 扩展名, pi- app 可以显示运行 副代理机队作为一个非加太计划——每个副代理机队成为一项任务 pending 编号 : in_progress 编号 : completed 状态.

因为 pi 的 RPC 模式不会转发 pi 的 进程内事件总线( )subagents:*,桥是 由 Pi 扩展完成 。 这个 pi-acp 软件包与扩展名相乘(src/pi-extension.ts, (中文(简体) ), 已公布 pi.extensions:装入pi内部,它订阅巴士,每换一换, 持续a CustomEntry 通过 pi.appendEntry("acp:subagents", <record>)。附带 entry_appended 事件, pi 在 RPC 上前进( 不同于总线本身); 适配器解码它 改为 a plan 更新. CustomEntry (无) CustomMessageEntry)是故意使用的,所以舰队 状态被记录而不输入模型的上下文. entry_appended 在转弯时向前移动 活动(水手在内部转弯),所以计划更新在提示时跟踪舰队.

没有配置——两套装入后才有效:

pi install npm:@tintinweb/pi-subagents
pi install npm:@geohar/pi-acp   # loads the pi.extensions entry (the bridge)

适配器标出Pi的过程 PI_ACP=1,激活捆绑的扩展名 那里; 扩展在普通终端中保持惰性 pi 会话( 无标记), 因此没有效果 在适配器外面.

非加太集团 PlanEntryStatus 没有 failed 值,所以失败的子剂显示为 completed 带有 (failed) 注释.

认证(非专利登记支助)

此代理支持 终端 Auth 联 合 国 非加太国家登记处。 。 。 . 在泽德,这将显示 认证 在终端中发射 pi 的横幅 . 在终端中启动 pi 用于交互式登录/ 设置 :

pi-acp --terminal-login

你的ACP客户也可以根据代理广告自动引用 authMethods。 。 。 .

发展

npm install
npm run dev        # run from src via tsx
npm run build
npm run lint
npm run test

项目布局 :

  • src/acp/* - ACP服务器+翻译层
  • src/pi-rpc/* — pi 子进程包装器( RPC 协议)

限制

  • 没有非加太文件系统授权(fs/*并且没有非加太集团最终代表团(ACP)terminal/*) pi 读取/写出并本地执行.
  • 没有非加太国家允许的地标(session/request_permission: pi在本地执行工具,不会在RPC上表面执行前工具意图,因此适配器尚不能打开.

MCP 服务器

MCP服务器由非加太客户端通过(session/new, (中文(简体) ), session/load, (中文(简体) ), session/resume) 翻译 改为 a 会话范围临时文件 并交给 pi- mcp- 适应器 通过 pi --mode rpc --mcp-config <tempfile>. stdio 和 http 服务器得到支持; sse/ app 服务器 无法用通知表达和跳过。 临时文件在会话结束时被删除 . 安装 pi-mcp-adapter 在你身边 packages 用于服务器实际加载——适配器发出 a 丢失时启动通知 .

临时文件可能包含客户端按字面意思发送的秘密(a) Authorization 页眉值, 或 stdio env 值),所以只用所有者写(0700临时目录 0600 权限。 保持一个 全部从磁盘上显示为无记名符号 $env:VAR (通过保单) auth.bearerTokenEnv,或一个 $env:-从客户端得到的值头) - pi-mcp-adapter 解析 $env: 在连接,所以只有 占位符被写入.

{\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}有意识的说 没有 写入 <cwd>/.pi/mcp.json这条路是Pi自己最高的 工程配置命名空间( 设置、 提示、 信任、 mcp ): 将用户的全局写入其中 MCP配置,持续过会,并泄露为无关(甚至非ACP) pi会 从同一个目录. --mcp-config 仅覆盖 pi- mcp- 适应器 pi-global 源头,从来不是pi的 配置 dir, 所以所有 pi 自己的 MCP 配置( 全球和项目) 仍然流出 。 烂透了 <cwd>/.pi/mcp.json 由更古老的 pi- acp 版本所留下( 标记) _generatedBy: pi-acp)被清理干净 自动.

MCP 生成政策

默认 pi- app 生成每个 ACP 提供的服务器进入临时覆盖( 添加- 它永远不会) 覆盖您的配置 。 要控制它生成的哪些服务器——同样的语义pi用于 子代理工具/扩展继承-创建 ~/.pi/pi-acp/mcp-policy.json (单位:千美元) PI_ACP_DATA_DIR:

{
  "generate": "*",
  "exclude": ["mcp-combiner"],
  "auth": {
    "some-http-server": { "bearerTokenEnv": "MY_TOKEN", "headers": { "X-Extra": "v" } }
  }
}
  • generate ——哪些服务器 pi-app 可写: true编号 :"*"= 全部(默认) = ["a","b"] =: 只有这些.. false = 无。 未生成的服务器留给您自己( 低优先级) 配置 .
  • exclude - 拒绝名单(胜出) generate:永远不要生成这些. 用于您的服务器 在全球用它自己的亲和器(例如无记名自动联合器)配置,所以pi-app不会覆盖它.
  • auth 用于服务器 pi-app 已经 生成、 写入 Authorization: Bearer $env:<VAR> (+ 额外) (原始内容存档于2018-10-21). headers. pi- mcp- 适应器插值 $env: 在连接时, 符号不会写入磁盘 .

名字对案件不敏感。 注意 ACP MCP 形状没有专用的认证字段,所以无记名认证可以 仅作为 HTTP 页眉进行旅行—— 由服务器中的客户端提供 headers,或通过 这个政策 auth。 。 。 .

  • 附加的工作空间根不是硬文件系统边界:pi可以在外操作. 它们被传达给模型(工作空间意识),而不是作为沙盒执行.
  • 助理串流目前作为 agent_message_chunk (无分别想流.
  • 队列已执行客户端,应该像 Pi 一样工作 one-at-a-time
  • 非加太公司客户尚未掌握会议的历史,但非加太公司的会议来自 pi-acp 可能会是 /resumed 直接单位:皮伊

许可证

麻省理工学院(见 自由主义) (中文(简体) ).

版本与发布记录

@geohar/pi-acp 共发布 9 个版本,首次发布于 2026/08/23;过去 12 个月发布了 9 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.4.0latest2026/11/0511 天前
0.3.22026/09/211 个月前
0.3.12026/09/012 个月前
0.3.02026/08/252 个月前
0.2.02026/08/242 个月前
0.1.52026/08/232 个月前

关于 @geohar/pi-acp 的常见问题

@geohar/pi-acp 是什么?

用于 pi 编码剂(fork)的 ACP 适配器,用于 ssub agent plan 的捆绑 pi 扩展

如何安装 @geohar/pi-acp?

在项目目录运行 npm install @geohar/pi-acp,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 pi-acp,可以用 npx pi-acp 直接运行。

@geohar/pi-acp 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/geohar__pi-acp 是否存在。

@geohar/pi-acp 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@geohar/pi-acp 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@geohar/pi-acp 可以商用吗?

@geohar/pi-acp 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@geohar/pi-acp 的下载量有多少?

根据 npm 官方下载统计,@geohar/pi-acp 在 2026/10/16 – 2026/11/14 这 30 天内被下载 10,538 次,日均约 351 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geohar/pi-acp 还在维护吗?

最新版本 0.4.0 发布于 2026/11/05(11 天前);至今共发布 9 个版本,其中过去 12 个月发布了 9 个;首次发布于 2026/08/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。