# @automatalabs/pi-acp 中文文档

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

版本：0\.9\.4
npm 元数据更新时间：2026-09-24T17:17:06.589Z
中文译文更新时间：2026-11-07T06:48:49.029Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：287 kB，72 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：5 个
- 首次发布：2026-07-16T16:42:10.758Z
- 最新版本发布：2026-09-24T17:17:06.197Z
- 近 30 天下载量：8705（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

正在处理的代理客户端协议服务器 [pi 编码代理](https://github.com/earendil-works/pi)它通过它出版的SDK嵌入了pi,并且将ACP协议版本1比作stdio. 标准产出专供非加太国家自然资源研究所使用.

## 安装

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

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

## README

# `@automatalabs/pi-acp`

正在处理的代理客户端协议服务器 [pi 编码代理](https://github.com/earendil-works/pi)它通过它出版的SDK嵌入了pi,并且将ACP协议版本1比作stdio. 标准产出专供非加太国家自然资源研究所使用.

## 命令行

运行服务器 `npx @automatalabs/pi-acp` 或已安装 `pi-acp` 二进制. `pi-acp --version` 在不启动服务器的情况下打印软件包版本.

## 无副作用库 API

软件包条目导出值 API `runAcp(options?)`, (中文(简体) ), `PiAcpAgent`,以及 `resolveDeps`,加上只使用类型脚本 `PiAcpDeps` 类型。 导入它不会启动服务器, 打开 stdio 连接, 也不会变异 `console` 或无常. 呼唤并等待 `runAcp()` 指定连接; 通过部分 `PiAcpDeps` 和/或用于嵌入和测试的ACP流.

### Pi 配置和拆卸

会话加载操作员真实的 pi 配置——设置,扩展和 pi 自己的 MCP 服务器——来自 `PiAcpDeps.agentDir`,默认为 pi 的 `getAgentDir()` (单位:千美元)`$PI_CODING_AGENT_DIR`,则 `~/.pi/agent`) (中文(简体) ). 覆盖到一个孤立的目录上指向 pi; 嵌入器和测试器 `createAgentSession` 应当,因为资源加载器读取此路径并启动它找到的扩展 _在此之前_ 会话工厂叫.

会话闭幕 发送 pi 的 `session_shutdown` 在处理会话之前, 匹配 `AgentSessionRuntime.dispose()`这个事件是Pi唯一一份延期清理合同 所以通过扩展程序释放出来 这比程序外的非CAP后端更重要: pi 运行 **正在处理**,所以它留下的任何东西都是在主机事件回路上的活柄,而不是OS用一个子进程树收获的东西.

## AgentPrism 内置后端

`@automatalabs/acp-agents` 飞船作为内置 `pi` 后端 。 用后端的 ID 来给一个呼叫进行路由,以保持 Pi 配置的默认模式, 或者包含 pi 的精确度 `provider/model-id` 路由前缀后 :

```ts
await runner.run("Review this change", { model: "pi" });
await runner.run("Review this change", { model: "pi/openrouter/vendor/model-id" });
```

跑步者是第一个 `pi/` 区域并发送剩余 `provider/model-id` 通过非加太集团保留的逐字记录 `model` 配置频道. Pi- acp 广告配置 `model` 从已完成的证书和提供者-过滤-意识的 Pi 目录中选择被覆盖; 设置请求刷新并需要加入该目录。 用 JSON- RPC 的未知模型拒绝 `-32602` 财务报告和审定财务报表 `data.errorKind = "invalid_model"`。 。 。 .

### 思考层面

Pi -app's (英语) `thinkingLevel` 选择是模型意识。 它的明显选择是皮的 `getSupportedThinkingLevels()` 选定模型的结果, 按 Pi 顺序: 封顶的模型 `high` 不做广告 `xhigh` 或者说 `max`,一个非理性模式只广告 `off`之前 选择一个模型,选项使用 Pi 的完整识别域作为未知模型 最好的退缩。 这个域名曾经来源于皮的帮助者 合成模型 支持每个关卡; pi-app 不维持并行的硬编码词汇.

该选项带有添加剂的非加太元数据 `_meta["@automatalabs/agentprism"].recognizedValues`。可见的选择仍然是得到支持的选择 子集,虽然此元数据包含 Pi 完整的命令域,所以客户端可以区分一个 不支持从垃圾中识别值 。 支持的一组请求保持不变。 A 类 已确认但未支持的请求被 Pi 夹住 `clampThinkingLevel()` 和对策 呼应有效水平。 在 JSON- RPC 中, 一个未识别值会大声失败 `-32602` 财务报告和审定财务报表 `data.errorKind = "invalid_config_value"`;它从未被交给皮的最低级后退.

## MCP和结构化产出

Pi-acp服务于stdio,Streamable HTTP,以及遗留的SSE MCP服务器并消耗了稳定的工具,资源,提示,完成,日志,页码,进度,以及动态工具注册. 它还提供MCP客户端采样,工作空间根和形式/URL诱导. 客户端托管 `acp` 运输仍然为跑道所有。 对于 `agent({ schema })`,Pi接收跑者客户端托管的 HTTP `StructuredOutput` 工具通过此标准 MCP 路径,并保留常用的即时嵌入式计划外加已验证的上个文本倒置.

## 认证

证书是环境的。 服务器无条件发布一种方法:

| 编号 | 名称 | 来源 |
| --- | --- | --- |
| `pi-stored-credentials` | pi 存储的证书 | 毕 `~/.pi/agent/auth.json`,或服务器环境中的提供者 API 密钥(`ANTHROPIC_API_KEY`, (中文(简体) ), `OPENAI_API_KEY`, (中文(简体) ), `GEMINI_API_KEY`, (中文(简体) ), `XAI_API_KEY`, (中文(简体) ), `OPENROUTER_API_KEY`(中文(简体) ) |

提供商API-键 方法曾经坐在一起 `env_var`\- 型;非加太化学品方案1.21.0(`@agentclientprotocol/sdk` 1.4.0)从协议中删除了该变体,因此它们不再被公示——环境变量本身仍然受到尊重. 认证请求是不可承认的,因为环境或Pi的认证商店提供这个秘密. 缺少证书的选定或可解决模式 `-32000` 因此客户端可以暂停认证. 完全没有模式是不同的: `-32602` 编号 : `invalid_model`。 。 。 .

## 保留的工具命名空间

pi -app拥有 `mcp__` 用于注入的 MCP 工具的前缀。 Pi 扩展不能在此命名空间注册名称 .

## 第1版限制

负载回放是活性线性分支,不包括分支地貌和收缩摘要. `additionalDirectories` 被接受但被忽略了,因为 pi 不是root- confined。 ACP即时音频被贬为文本注释. 终端登录认证未曝光 .

### 土著会议指导

Pi广告 `_session/steering` 在顶级初始化元数据为 `_meta: { steering: { supported: true } }`,带有严格的活性转动只用语义. 当Pi迅速转弯时 live,服务器将提供的 ACP 内容转换为文本/图像转换为 `session/prompt` 呼唤本地人 `AgentSession.steer(text, images)`返回时 `{ outcome: "injected" }`; 原件 `session/prompt` 仍然拥有所有输出、使用和 和解。 当会场闲置时——或者方向盘到达时,恰好转弯了,比派早到 消耗它 —— 服务器删除任何未保存的本地队列条目并返回 `{ outcome: "promptRequired", reason: "noRunningTurn" }`它从不打电话 `prompt()`, (中文(简体) ), `followUp()`,或 向导的另一个回合启动帮助器,所以向导无法创建隐藏的工作或预置输入到一个 后即发. 取消比赛使用相同的 `promptRequired/noRunningTurn` 无活动时的响应 转身接受指示。 无法预料的内部失败通过 常规结构错误路径.

### 装入的会话转会状态( T)`_session/loaded_turn`(中文(简体) )

Pi也广告 `_session/loaded_turn` 在顶级初始化元数据为 `_meta: { loadedTurn: { supported: true } }` 重接臂的自动完成 重新打开的会话证据 `session/load` (一个重新启动的主机恢复路径). `_session/loaded_turn/query { sessionId }` 回答装入的会话的创建回合是否 仍在运行中 : `running` 在此过程中转弯执行( 然后客户端等待) 联 合 国 `_session/loaded_turn/ended` 推——以转弯的停止理由发送,或其错误,何时 转弯结束,武装和清除一发手表, `completed` 当会话日记时 最后一个信件条目是助理信件( pi standing 每一个完整的 LLM 信件, at `message_end`因此,完成的转弯总是留下一个助手的叶子 和回放的后缀 助理信息是转动的终极信息——权威的,绝不是静悄悄的猜测),并 `interrupted` 否则(日记显示一个被中断/被放弃的转弯——没有运行,所以) 重新发行是安全的)。 未知会话的查询是标准 `unknown_session` 错误.

### 会话系统提示( E)`_meta.systemPrompt`(中文(简体) )

Pi 在顶级初始化元数据时广告一个会话系统即时通道 `_meta: { systemPrompt: { replace: true, append: true } }`。客户端设置 `_meta.systemPrompt` 打开 `session/new`, (中文(简体) ), `session/resume`, (中文(简体) ), `session/load`,或 `session/fork` - 相同的空钥匙 `claude-agent-acp` 读取,这样客户端就可以在两台服务器之间保持一丝形状——要么是一个 字符串或对象 :

-   (单位:千美元) **字符串**,或 `{ replace }`,替换 pi 的内置系统提示: 它需要 pi 的自定义即时 时间档( `SYSTEM.md` 编号 : `--system-prompt` 通过资源加载器 `systemPromptOverride`,与操作员配置的快取一样。 用自定义的快递 `buildSystemPrompt` **放弃默认指令文本** ——"活用工具"列表及其"活用工具" 片段、其指南和pi docs/示例路径- 仍按此顺序附加 附加系统即时条目,项目上下文文件(`AGENTS.md` 和里面的朋友们 `<project_context>`),技能障碍(当 `read` 或者说 `bash` 工具可用) `Current working directory` 线条;
-   `{ append }` 作为另一个附加系统即时条目添加 **之后** 操作员自己的 配置条目( e)`appendSystemPromptOverride`故它绝不能使他们流离失所;
-   `{ replace, append }` 两者兼有.

指令是每个会话的:它们只塑造请求打开的会话并被读取 每次重修时 都会重修旧好 `session/resume` 没有键运行在 Pi 自己的配置。 A 类 错误的值——非字符串/非对象、空白字符串、非字符串字段或任何其他字段 比起来 `replace` 编号 : `append` 被JSON-RPC拒绝 `-32602` 财务报告和审定财务报表 `data.errorKind = "invalid_system_prompt"` (单位:千美元)`data.field` 罪犯姓名) **在此之前** 任何日记 或会话状态; 无法使用的指示从不运行在默认的提示下。 这个 `@automatalabs/acp-agents` `pi` 后端从后端中性驱动此信道 `systemPrompt: { replace?, append? }` 选项.

## 发展

这个 `pnpm test` 故意运行脚本 `tsc -p tsconfig.type-tests.json` 在运行时间测试套房之前。 这是与被冻结规格中的测试标本例子的微小偏差,确保了T2b公共类型合同检查在当地和CI测试运行中执行.

运行 `node scripts/smoke-pi-package.mjs` 在更改 Pi 依赖性后从寄存器根。 它将这个适配器装入其中,并检查其在新npm和pnpm装置中的公共SDK进口. Pi 0.87.0 保持其实验性遥控带出已公布的本地SDK,因此这个适配器不再需要提供 `@earendil-works/pi-server`。 。 。 .

## 建于皮-第三派通知

此软件包取决于和嵌入 `@earendil-works/pi-coding-agent`, (中文(简体) ), `@earendil-works/pi-agent-core`,以及 `@earendil-works/pi-ai` 版本为0.87.1. pi为版权Earendil Inc.,Mario Zechner,和Armin Ronacher,根据MIT许可证发行. 依赖软件包保留了MIT的完整版权和许可证文本. pi-app本身为Apache-2.0.

## 模型发现偏好

非加太模式目录继续揭露每个经认证的现有模式。 本地合并的 Pi `enabledModels` 设置将演示文稿元数据添加到模型配置选项 `_meta["@automatalabs/agentprism.modelDiscovery"]`数字 : `{ source:"enabledModels", preferred:string[], unmatched:string[] }`原生图案顺序和 匹配的语义被保留,然后首选项会交叉认证的目录。 无比 模式仍然可见。 首选项不限制执行; 没有配置首选项 列表中,MCP摘要显示可用的提供者组。 目前模式不同于首选模式 模型,以及 `thinkingLevel` 选项必须找到精确的选定模型.

## 常见问题

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

正在处理的代理客户端协议服务器 pi 编码代理它通过它出版的SDK嵌入了pi,并且将ACP协议版本1比作stdio\. 标准产出专供非加太国家自然资源研究所使用\.

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

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

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

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

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

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

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

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

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

@automatalabs/pi-acp 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @automatalabs/pi-acp 的下载量有多少？

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

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

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