# @gugu-acp/pi-acp 中文文档

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

版本：1\.1\.0
npm 元数据更新时间：2026-11-01T03:49:50.478Z
中文译文更新时间：2026-11-01T07:28:45.411Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：349 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：3 个
- 首次发布：2026-09-25T04:02:49.941Z
- 最新版本发布：2026-11-01T03:49:50.160Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

Gugu build的pi-acp 0.0.34：上游源代码加上补丁 [https://github.com/GUYI-AI/gugu-acp/tree/main/bridges/pi-acp](https://github.com/GUYI-AI/gugu-acp/tree/main/bridges/pi-acp)

## 安装

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

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

## README

> **Gugu构建。** `@gugu-acp/pi-acp@1.1.0` ＝ [pi-acp](https://github.com/svkozak/pi-acp) V0.0.34 + 4补丁（es）保留 [gugu-acp](https://github.com/GUYI-AI/gugu-acp/tree/main/bridges/pi-acp/patches);每个补丁都说明了为什么需要它，它对应于哪个上游PR，以及何时可以删除它。类似于apache 2.0的上游。

# pi-acp

运河管理局([代理客户端协议](https://agentclientprotocol.com/overview/introduction))适配器 [`pi`](https://github.com/earendil-works/pi) 编码剂（该死的编码剂）。

`pi-acp` 沟通 **ACP JSON-RPC 2.0在工作室** 到ACP客户端（如Zed编辑器）和刷出 `pi --mode rpc`，在两者之间桥接请求/事件。

## 状态

这是一个mvp风格的适配器，旨在在今天很有用，并且易于迭代。某些ACP特性可能未实现或不受支持(参见 [限制](https://npmcn.com/package/%40gugu-acp/pi-acp/#readme-limitations)）. 以发展为中心 [Zed](https://zed.dev/) 编辑器支持，其他客户端可能具有不同级别的兼容性。

预计会有一些小的突破性变化。

## 功能

-   将辅助输出作为ACP进行流处理 `agent_message_chunk`
-   将pi工具执行映射到ACP `tool_call` / `tool_call_update`
    -   当ACP客户端支持打开所引用的文件/上下文时，工具调用位置会显示出来
    -   在作为ACP工具位置发出之前，pi的相对文件路径会根据会话cd进行解析，这使得像Zed这样的客户端可以使用后续功能
    -   为 `edit`， `pi-acp` 尝试从唯一字符中推断基于1的行号 `oldText` 匹配预编辑文件快照，并在可能的情况下将其包含在发出的工具位置中
    -   为 `edit`， `pi-acp` 在工具运行之前对文件进行快照并发出ACP **结构的差异** （`oldText`/`newText`)
-   会话持久性
    -   PI将自己的会话存储在 `~/.pi/agent/sessions/...`
    -   `pi-acp` 将小映射文件存储在 `~/.pi/pi-acp/session-map.json` 所以 `session/load` 可以重新连接到以前的PI会话文件吗
-   削减命令
    -   加载与pi约定兼容的基于文件的斜杠命令
    -   为无头/编辑器的使用添加一组内置命令
    -   支持技能命令(如果在pi设置中启用，它们显示为 `/skill:skill-name` 在ACP客户端)
-   上下文窗口使用情况
    -   报告pi的实际上下文占用(`get_session_stats` → `contextUsage`)作为ACP发送给客户端 `usage_update` 每次转弯后，打开 `session/new` 和 `session/load`，然后进行型号切换
    -   需要pi版本，其 `get_session_stats` 反应包括 `contextUsage`;否则不会报告使用情况
    -   在压缩之后，pi可能还没有一个值得信赖的令牌计数，因此客户机将保留之前的值，直到下一次模型响应
-   技能由pi直接加载，并在ACP会话中可用
-   (Zed) `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` 在ACP客户端。

## 先决条件

确保安装了pi

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

-   node . js 22 +
-   `pi` V0.81.0 +已安装并可在您的 `PATH` (适配器运行 `pi` 可执行的)
-   配置 `pi` 分别为您的模型提供程序/API密钥

## 安装

### 将pi-acp添加到ACP客户端，例如： [Zed](https://zed.dev/docs/agents/external-agents/)

#### 使用ACP注册表在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", "pi-acp"],
      "env": {}
    }
  }
```

#### 全球安装

```bash
npm install -g 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": {}
    }
  }
```

### 环境变量

-   `PI_ACP_ENABLE_EMBEDDED_CONTEXT=true` 广告机场核心计划 `promptCapabilities.embeddedContext` 对客户端的支持。
-   默认值：unset/其他值表示 `false`.
-   当禁用时，兼容的ACP客户端应该避免发送嵌入式 `resource` 块。如果他们还是送了他们， `pi-acp` 通过将它们转换为纯文本提示上下文，仍然可以优雅地降级。

你可以在Zed设置中添加环境变量：

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

### 削减命令

`pi-acp` 支持斜杠命令：

#### 1)基于文件的命令（又名提示）

加载:

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

#### 2)内置命令

-   `/compact [instructions...]` -运行PI压缩（可选的自定义指令）
-   `/autocompact on|off|toggle` -切换自动压实开关
-   `/export` -将当前会话导出为会话中的HTML格式 `cwd`
-   `/session` -显示会话统计（令牌/消息/成本/会话文件）
-   `/name <name>` - set会话显示名称
-   `/queue all|one-at-a-time` -设置PI队列模式（不稳定特性）
-   `/changelog` 打印已安装的PI变更日志（尽最大努力）
-   `/steering` -映射到 `pi` 转向模式，获取/设置
-   `/follow-up` -向 `pi` 后续模式，get/set

其他内置命令：

-   `/model` -没有实现（使用Zed中的模型选择器UI）
-   `/thinking` -映射到Zed中的‘mode’选择器
-   `/clear` -未实现（使用ACP客户端‘new’命令）

#### 3)技能命令

-   技能命令可以在pi设置中启用，并将在ACP客户端的斜杠命令列表中显示为 `/skill:skill-name`.

**注意**：目前不支持pi扩展提供的斜杠命令。

## 身份验证（ACP注册表支持）

这个代理支持 **终端身份验证** 为 [运河管理局注册](https://agentclientprotocol.com/get-started/registry). 在Zed中，这将显示an **进行身份验证** 在终端中启动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协议）

## 限制

-   没有ACP文件系统委托(`fs/*`)，没有ACP终端授权(`terminal/*`）. PI在本地读/写和执行。
-   MCP服务器在ACP参数中被接受，并存储在会话状态中，但不通过该适配器连接到pi。如果你使用 [pi MCP适配器](https://github.com/nicobailon/pi-mcp-adapter) 它将在ACP客户端中可用。
-   助理流当前发送为 `agent_message_chunk` （没有单独的思想流）。
-   队列是在客户端实现的，应该像pi一样工作 `one-at-a-time`
-   ~ACP客户端还不支持会话历史记录，但ACP会话来自 `pi-acp` 可以 `/resume`直接用PI表示D~

## 许可证

麻省理工学院(见 [许可证](https://npmcn.com/package/%40gugu-acp/pi-acp/LICENSE)）。

## 常见问题

### @gugu-acp/pi-acp 是什么？

Gugu build的pi-acp 0\.0\.34：上游源代码加上补丁 https://github\.com/GUYI-AI/gugu-acp/tree/main/bridges/pi-acp

### 如何安装 @gugu-acp/pi-acp？

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

### @gugu-acp/pi-acp 支持 TypeScript 吗？

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

### @gugu-acp/pi-acp 支持 ESM 还是 CommonJS？

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

### @gugu-acp/pi-acp 需要什么版本的 Node\.js？

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

### @gugu-acp/pi-acp 可以商用吗？

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

### @gugu-acp/pi-acp 还在维护吗？

最新版本 1\.1\.0 发布于 2026/11/01（2 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/09/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。