# @geohar/pi-acp 中文文档

规范地址：https://npmcn.com/package/%40geohar/pi-acp/

版本：0\.4\.0
npm 元数据更新时间：2026-11-04T20:24:33.635Z
中文译文更新时间：2026-11-16T04:26:17.143Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40geohar/pi-acp
原文对照：https://npmcn.com/package/%40geohar/pi-acp/?lang=original
项目主页：https://github.com/georgeharker/pi-acp#readme
源码仓库：https://github.com/georgeharker/pi-acp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：477 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-08-23T01:24:40.767Z
- 最新版本发布：2026-11-04T20:24:33.259Z
- 近 30 天下载量：10538（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

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

## 安装

```sh
npm install @geohar/pi-acp
```

也可以使用：`pnpm add @geohar/pi-acp`、`yarn add @geohar/pi-acp`、`bun add @geohar/pi-acp`

## README

# 皮亚克

非加太集团[代理客户协议](https://agentclientprotocol.com/overview/introduction)适配器 [`pi`](https://github.com/earendil-works/pi) 编码代理(fka 低劣编码代理).

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

## 状态

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

等待一些小的突破变化.

## 与上游的差异

这是叉子 [`svkozak/pi-acp`](https://github.com/svkozak/pi-acp),作为 npm 发布 **`@geohar/pi-acp`** (上游无范围) `pi-acp`) (中文(简体) ).

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

在上游

-   **作为非加太任务的子代理人** - 一个捆绑的pi扩展桥 [亲水师](https://github.com/tintinweb/pi-subagents) 进入非加太集团 `plan` 频道,所以 每个副代理都作为任务出现。 见 [作为任务的子代理](https://npmcn.com/package/%40geohar/pi-acp/#readme-subagents-as-tasks)。 。 。 .
-   **MCP 自动配置** - 非加太国家 `mcpServers` 被翻译为生成 `<cwd>/.pi/mcp.json` 页:1 [pi- mcp- 适应器](https://github.com/nicobailon/pi-mcp-adapter) 装入。 见 [MCP 服务器](https://npmcn.com/package/%40geohar/pi-acp/#readme-mcp-servers)。 。 。 .
-   **多根工作空间** ——新增工作空间根基 `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 覆盖(参见 [环境变量](https://npmcn.com/package/%40geohar/pi-acp/#readme-environment-variables)) (中文(简体) ).

## 特征

-   作为非加太集团的流程助理产出 `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`](https://zed.dev/releases/preview/0.225.0)。会话加载/历史图到 pi 的会话文件。 可在 `pi` 在非加太客户端.

## 先决条件

确保 Pi 已安装

```bash
npm install -g @earendil-works/pi-coding-agent
```

-   节点.js 22+
-   `pi` v0.80.4+ 安装并可用于您的 `PATH` (适配器运行 `pi` 可执行文件)
-   配置 `pi` 用于您的模型提供者/ API 密钥

## 安装

### 将 pi-app 添加到您的 ACP 客户端,例如 . [齐德](https://zed.dev/docs/agents/external-agents/)

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

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

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

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

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

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

#### 全局安装

```bash
npm install -g @geohar/pi-acp
```

```json
  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "pi-acp",
      "args": [],
      "env": {}
    }
  }
```

#### 从源

```bash
npm install
npm run build
```

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

```json
  "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`) (中文(简体) ).

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

```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` (任务列表)频道未使用. 当你使用 [亲水师](https://github.com/tintinweb/pi-subagents) 扩展名, 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` 在转弯时向前移动 活动(水手在内部转弯),所以计划更新在提示时跟踪舰队.

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

```bash
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** 联 合 国 [非加太国家登记处](https://agentclientprotocol.com/get-started/registry)。 。 。 . 在泽德,这将显示 **认证** 在终端中发射 pi 的横幅 . 在终端中启动 pi 用于交互式登录/ 设置 :

```bash
pi-acp --terminal-login
```

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

## 发展

```bash
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- 适应器](https://github.com/nicobailon/pi-mcp-adapter) 通过 `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`:

```json
{
  "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` 可能会是 `/resume`d 直接单位:皮伊~

## 许可证

麻省理工学院(见 [自由主义](https://npmcn.com/package/%40geohar/pi-acp/LICENSE)) (中文(简体) ).

## 常见问题

### @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 和提交记录判断。

