# @buyong/pi-claude-bridge 中文文档 规范地址：https://npmcn.com/package/%40buyong/pi-claude-bridge/ 版本：0\.14\.3 npm 元数据更新时间：2026-11-06T20:00:50.144Z 中文译文更新时间：2026-11-09T19:01:24.796Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40buyong/pi-claude-bridge 原文对照：https://npmcn.com/package/%40buyong/pi-claude-bridge/?lang=original 项目主页：https://github.com/buYoung/pi-packages/tree/main/apps/pi-claude-bridge#readme 源码仓库：https://github.com/buYoung/pi-packages ## 关键信息（来自 npm 元数据） - 包体积（解压后）：385 kB，54 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：\>=22\.19\.0 - 运行依赖：4 个 - peer 依赖：@earendil-works/pi-ai \*，@earendil-works/pi-coding-agent \* - 首次发布：2026-09-25T12:55:46.900Z - 最新版本发布：2026-11-06T20:00:49.728Z - 近 30 天下载量：1833（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：14（近 12 个月 14 个） ## 中文简介 Pi扩展使用克洛德代码(通过Agent SDK)作为模型提供者. ## 安装 ```sh npm install @buyong/pi-claude-bridge ``` 也可以使用：`pnpm add @buyong/pi-claude-bridge`、`yarn add @buyong/pi-claude-bridge`、`bun add @buyong/pi-claude-bridge` ## README # 皮-克-克-桥 **联合国** | [한국어](https://npmcn.com/package/%40buyong/pi-claude-bridge/README.ko.md) [![npm version](https://img.shields.io/npm/v/@buyong/pi-claude-bridge)](https://www.npmjs.com/package/@buyong/pi-claude-bridge) 只有提供商的 Pi 扩展,通过 Claude Code 运行 Claude 模型 [SDK探员](https://github.com/anthropics/claude-agent-sdk-typescript)。工具调用通过 Pi 自己的工具运行;扩展时没有登记自己的工具或命令. `@buyong/pi-claude-bridge` 保留在 [pi- packages 单发](https://github.com/buYoung/pi-packages/tree/main/apps/pi-claude-bridge); npm 安装命令和软件包名称不变. 它来自 [埃利德金森/皮-克劳德-桥](https://github.com/elidickinson/pi-claude-bridge),它最初基于 [幽灵sdk-pi](https://github.com/prateekmedia/claude-agent-sdk-pi) 由普尔提克·苏纳尔所著. 报告这种分发方式的问题 [皮包问题](https://github.com/buYoung/pi-packages/issues)。 。 。 . **计费:** 请求目前与你的Claude订户配额相同 人类 [宣布后撤回](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) 改变在SDK探员身上 建造的工具,就像这个一样,是怎样收费的. [![](https://raw.githubusercontent.com/buYoung/pi-packages/main/apps/pi-claude-bridge/assets/claude-bridge1.png)](https://github.com/buYoung/pi-packages/blob/main/apps/pi-claude-bridge/assets/claude-bridge1.png)  [![](https://raw.githubusercontent.com/buYoung/pi-packages/main/apps/pi-claude-bridge/assets/claude-bridge2.png)](https://github.com/buYoung/pi-packages/blob/main/apps/pi-claude-bridge/assets/claude-bridge2.png) ## 安装 需要Pi 1.0.0或更新和节点 22.19.0或更新. 包装和型号检查最后用Pi 1.4.0确认,更早用Pi 1.2.0和1.3.0. ``` pi install npm:@buyong/pi-claude-bridge ``` ### 第一次使用前 - 使用 Claude 订阅账户签入 Claude 代码, 例如运行 `claude` 一次并完成登录。 大桥没有自己的资质:请求通过克洛德·克洛德(Claude Code)的登录到Anthropic,并按你的订阅配额计算. - 代理SDK作为依赖性安装了特定平台克洛德代码二进制. 如果无法运行于您的系统, 请设定 `provider.pathToClaudeCodeExecutable` (见 [配置](https://npmcn.com/package/%40buyong/pi-claude-bridge/#readme-configuration)) (中文(简体) ). - 不导出 `ANTHROPIC_BASE_URL`, (中文(简体) ), `ANTHROPIC_API_KEY`,或 `ANTHROPIC_AUTH_TOKEN` 用于 Pi 进程;它们重定向 Claude 代码(见 [已知问题](https://npmcn.com/package/%40buyong/pi-claude-bridge/#readme-known-issues)) (中文(简体) ). ### 第一项请求 1. 开始 `pi`运行 `/model`,并选择 `claude-bridge` 例如,模型 `claude-bridge/claude-haiku-4-5`。 。 。 . 2. 发送简短的提示, 如 `Reply with OK only.` 克洛德的回信证实克洛德代码登录和桥梁工作. 请求与克劳德的订阅配额不符. 若无 `claude-bridge` 模型出现或请求失败, 请检查 Claude 代码登录和上面的环境变量, 然后查看 [调试](https://npmcn.com/package/%40buyong/pi-claude-bridge/#readme-debugging)。 。 。 . ### 更新并删除 | 任务 | 命令 | 在你运行之前 | | --- | --- | --- | | 最新版更新 | `pi update npm:@buyong/pi-claude-bridge` | 即使印出准确的版本, 针头也保持不变 `Updated`。项目安装仅以保存的信任决定更新,或 `-a`。 。 。 . | | 键或修改精确的版本 | `pi install npm:@buyong/pi-claude-bridge@` | 替换 `` 带有已出版的版本. | | 只为当前工程安装 | `pi install -l npm:@buyong/pi-claude-bridge` | 在一个信任的项目内运行 . | | 删除 | `pi remove npm:@buyong/pi-claude-bridge` | 添加 `-l` 删除工程安装. | ### 文件桥写 - `claude-bridge.json` 在 Pi 代理目录中`PI_CODING_AGENT_DIR`默认值 `~/.pi/agent`)保持您的配置。 桥上加顶级键 `startupNoticeShown`在显示首发通知后 `detectedPlan`在从Claude代码登录读取你的计划后 即使项目文件存在,它也会将它们写入这个全局文件. - Claude 代码会话文件 `~/.claude/projects/` (或 `$CLAUDE_CONFIG_DIR/projects/`保持对话 克劳德代码的恢复。 桥在重建对话时会重写,并去掉自己的临时会话,但不会清理更早的会话. - `claude-bridge-cc-session` 条目在 Pi 会话中将一个 Pi 分支链接到它的 Claude 代码会话。 它们被排除在模式背景之外. - 调试日志和每克的 Claude 代码 CLI 日志只有在 `CLAUDE_BRIDGE_DEBUG=1` 已经设定。 桥上写着诊断垃圾堆 `claude-bridge-diag.log` 当它击中出乎意料的提供者状态或即时抓取失败时,即使调试关闭. 见 [调试](https://npmcn.com/package/%40buyong/pi-claude-bridge/#readme-debugging) 用于路径和人工清理. ## 选择和使用一个模型 使用 `/model` 以选择 Pi-ai 目录中的任何 Claude 模型, 例如 `claude-bridge/claude-fable-5-1`, (中文(简体) ), `claude-bridge/claude-opus-5`,或 `claude-bridge/claude-haiku-4-5`。 。 。 . Pi的工具被连接到克洛德代码,你和往常一样在Pi中使用. 大桥保存着 `bash` 参数不添加默认超时;执行时间限制属于Pi的工具. 技能和所选工具指导被传送到克洛德代码的系统即时,而被发送的指向中转到达克洛德的下一个工具边界. **思考选项 :** 与思考(选择水平与 `/thinking`,或用 Shift+Tab 进行循环,桥面要求适应性思维,从4.6 代起为 Claude 模型进行汇总显示。 Claude 4.5模型保留了Claude Code的默认处理和努力绘图. 对于其目录条目不允许关闭思维的模型(如Sonnet 5.5),该桥从未发出一个禁用思维的请求. Haiku 5.5被注册为一个不能关闭思维的模型: Pi 1. 4.0的目录允许关闭,但克洛德代码反正会一直思考. **系统快速更新 :** 每个新查询或复会都收到当前项目背景、技能和从Pi获取的指示(提供者使用) `snapshot: false`) (中文(简体) ). 已经运行的查询的 MCP 工具不更新 . 模型列表出自于pi-ai的Anthropic目录. 当Pi -ai添加了一个新的克洛德模型,它出现在 `/model` 更新 Pi 后, Pi 提供 pi- ai; 不需要桥更新 。 日期快照ID( 例如) `claude-opus-4-5-20251101`未显示. **1M 语境 :** 有线5/5.1, Opus 5.5/5/4.8/4.7, Sonnet 5.5/5, Haiku 5.5 得到1M上下文. Opus 4.6只获得1M在马克斯计划中或附加用法,而Sonnet 4.6只获得附加用法. 该桥检测出克洛德代码在第一个请求上登录的马克斯计划. 设定 `provider.plan` 或者说 `provider.longContextExtraUsage` 说明 [配置](https://npmcn.com/package/%40buyong/pi-claude-bridge/#readme-configuration) 当检测无法决定时, 或者您想要覆盖它. ### 压缩和分支摘要 Pi,或您安装的简易扩展名,开始收缩和分支摘要. 当a `claude-bridge` 模型进行总结,桥只服务于模型请求;它不接收摘要,也不在失败时取消摘要. Pi 发送自己的摘要请求,如压缩和分支摘要,并带有 `cacheRetention: "none"`在请求的 Pi 会话工作目录中,只有带有该标记的请求以单独的 Claude 代码程序运行,其结果包括符号用法 Claude 代码报告. 已经取消的请求不启动进程,运行期间的取消会作为取消而不是错误返回. 当一个摘要改变历史时,桥会像对其他历史变化一样重建克洛德法典会话. ## 配置 配置居住于 `~/.pi/agent/claude-bridge.json` (全球)或项目中的 Pi 配置目录,通常 `.pi/claude-bridge.json` (项目;全球合并). 每个文件必须包含一个JSON对象. 无效的 JSON 或非对象根(`null`,一个数组,或者一个原始的)被忽略而不屏蔽提供者。 在这种情况下,桥不会覆盖文件来记录启动通知或被检测到的计划;固定文件以再次启用这些更新. ```json { "provider": { "plan": "max", "longContextExtraUsage": false, "pathToClaudeCodeExecutable": "/home/you/.nix-profile/bin/claude" } } ``` `provider`数字 : - `plan`数字 : `"pro"` 或者说 `"max"`。 。 。 . `"max"` 启用带有1M上下文的 Opus 4.6。 当未设定时, 桥会从 Claude 代码登录中读取第一次请求时的计划( 没有额外的模型请求), 应用到当前会话, 并将其记录为 `detectedPlan` 以后的会议。 最大和企业地图到 `"max"` 提名 `"pro"`。团队计划不能分开,所以团队 Premium 用户设置 `"max"` 在这里。 在发现计划前, `"pro"` 适用。 这里设定的值总是胜利的. - `longContextExtraUsage`: 设置为 `true` 以启用1M文本模型,即使它们通过额外使用来花费你计划的资金。 它使Sonnet 4.6与每个计划1M,Opus 4.6与1M与Pro. Opus 4.7 或 4.8 不需要这个. - `forceTwoHundredK`: 将模型ID数组接入200K上下文, 不包含 `claude-bridge/` 前缀或前缀 `[1m]` 后缀( 例如 `["claude-opus-4-6"]`; 默认:无. 当Pi -ai在1M宣布一个型号时使用它, 但克劳德代码不会服务 1M 在你的计划中. - `autoMemoryEnabled`: 启用 Claude 代码的自动记忆系统( 默认) `false`) (中文(简体) ). - `pathToClaudeCodeExecutable`: 路径 `claude` 二进制. 当系统不能运行与 SDK 捆绑的 musl 或 glibc 二进制时使用它 。 比方说,尼克斯把它设定为 `"/home/you/.nix-profile/bin/claude"`。 。 。 . **扩展提供者和 `models.json`数字 :** 皮丝 `modelOverrides` 内 `~/.pi/agent/models.json` 不适用于扩展注册供应商,如Claude-bridge。 将模型钉入200K, 使用 `provider.forceTwoHundredK`· ; `contextWindow` 和其他模型字段没有配置覆盖. ### Claude 代码设置和环境 这些行为是固定的;没有配置密钥改变它们. - **MCP 服务器 :** 该桥总是会从用户,项目,或插件设置或claude.ai上屏蔽克洛德代码自行装入MCP服务器. Pi的工具和Pi MCP的工具通过桥继续可用 `custom-tools` 服务器. - **结果大小 :** 每个工具上 `custom-tools` 服务器声明 `anthropic/maxResultSizeChars: 52224`: Pi的工具输出限制(50KB,51200字节)加上线皮在切出输出时会增加空间. Claude Code给Claude送了这么大的结果 它将更大的结果保存到会话下的文件并显示克洛德的2KB预览. - **工具 `_meta`数字 :** 一个Pi MCP工具也带有 `_meta` 其服务器已声明,未作更改。 如果服务器声明 `anthropic/maxResultSizeChars`,其值取代52,224. `pi/maxOutputBytes` 编辑 `maxOutputBytes` 联 合 国 `mcp.json` 只限制Pi传递的东西,不要改变 `anthropic/maxResultSizeChars`。桥读这个 `_meta` 从 `meta` 内 `pi.getAllTools()` 和从扩展的答案 `tool-meta` 请求 `pi.events`,例如 `@buyong/pi-mcp-adapter`Pi 版本中 `pi.getAllTools()` 没有 `meta`,例如1.4.0,需要这样的扩展. - **权限 :** 提供商运行 Claude Code in `dontAsk` 权限模式和预先批准仅是桥的MCP服务器. 该桥不要求完全允许绕行或添加 `IS_SANDBOX` 值为绕行需要。 工具呼叫和 `@file` 在 macOS 上检查了工作目录外的扩展;没有测试在容器中以 uid 0 运行. - **环境:** 桥将家长克洛德代码的会话标记从儿童环境去除,并使用SDK入站. 阻碍非必要交通的变量只为克洛德密码的孩子设定,所以皮的 `bash` 工具和其他扩展保存其环境。 认证和服务器连接变量通过不变,这就是为什么输出的Anthropic变量覆盖了孩子(见 [已知问题](https://npmcn.com/package/%40buyong/pi-claude-bridge/#readme-known-issues)) (中文(简体) ). - **Claude 代码设置 :** 汇总查询与提供者查询一样,读取 Claude Code 默认设置源,所以 `env` 并配置一个 `apiKeyHelper` 来自您的 Claude 代码用户设置。 Claude Code的指令文件被排除在外;Claude接收上下文Pi发送取而代之. - **计划通知:** 只有当 `provider.plan` claude 代码登录不会显示您的计划( 例如, Team), 桥在 TUI 中显示下一条桥请求的通知 。 记录 `startupNoticeShown` 别再重复了. ## 与其他扩展的兼容性 ### 哪条注射路线到达克洛德码 桥将 Pi 的结构化部件( 项目上下文文件、 技能、 自定义提示、 附加指令、 自定义提示部分) `systemPromptOptions.sections`,以及明确的即时和工具指导),同时省略了 Pi 生成的带文: | 路线 | 到达克洛德码 | | --- | --- | | `before_agent_start` - > (中文) `message` | 是, 作为用户转弯时的文字提示 | | `context` 编辑最后一个用户消息 | 是, 作为文字提示文本 | | `--append-system-prompt` | 是的,和Pi的附加说明 | | `context_with_system` 编辑系统消息 | 是,当它包裹了 Pi 的提示; 当它取代 Pi 的提示时, 转弯失败 | | `before_agent_start` - > (中文) `systemPromptOptions.sections` | 是的,一个 `` 每个区块 | | `systemPromptOptions.promptGuidelines` | 是,作为补充说明 | | 工具 `promptSnippet` 财务报告和审定财务报表 `promptGuidelines` | 是, 用于正在运行的选定工具 | | `before_agent_start` - > (中文) `systemPrompt` | 不,丢掉 | 工具指导遵循了 Pi 的宣布工具选择, 而不是工具注册的地方: SDK `customTools`,扩展工具,以及所选择的内置工具都可以提供明确的指令. 桥上复制了指南,删除了重复的规则,并应用了以下描述的检查: [系统快速拒绝](https://npmcn.com/package/%40buyong/pi-claude-bridge/#readme-system-prompt-rejections)。这不能允许实时 MCP 工具刷新;下一次提供者查询启动时,即时应用更改. 注意两个陷阱。 第一,回来 `systemPrompt` 从 `before_agent_start` 使 Pi 替换整个系统的快取, 它丢弃任何 `context_with_system` 在同一行中编辑;其中只有一个到达请求. 第二,系统即时编辑 _包装_ 皮的及时。 如果一个扩展来取代了Pi的快取,则桥没有匹配,因此它拒绝转弯,而不是在没有您上下文文件,技能和自定义指令的情况下发送克洛德代码请求. 错误指定了已知最接近的提示及其偏差位置 . 要添加指令, 请使用 `message`, (中文(简体) ), `context`,或系统消息编辑,保持了Pi的快感. ### 为 Claude 代码所写的钩子 提供方和查询摘要 `disableAllHooks: true`,关闭用户、项目和插件 Claude 代码钩和 `statusLine` 命令。 没有桥架能让他们恢复 Pi 扩展事件处理不变 . 这面旗帜并不绕过克洛德密码的管理政策:在SDK的政策下,由管理员执行的钩子仍然可以运行. 克洛德码所建的地物与钩子是分开的. ### 系统快速拒绝 其他扩展可以更改系统即时. 如果文本中,大桥会转发到克洛德代码 仍然包含打开 Pi 的内置系统提示, 或者两个文件路径, Anthropic 寻找(`docs/custom-provider.md` 财务报告和审定财务报表 `docs/packages.md` 由于Anthropic可能把这些请求记为Extra Usage。 重试前先修整源扩展; 与 `CLAUDE_BRIDGE_DEBUG=1`,桥会写到桥日志上 当这种情况发生. ### 使用有 @gotgenes/pi-subagents 的圆形桥 添加以下内容到 `~/.pi/agent/subagents.json`数字 : ```json {"promptInheritance": {"claude-bridge": "portable"}} ``` ### 从另一个扩展创建桥梁 一个扩展可以创建自己的桥实例并注册它而不是默认导出. 使用 `getChildEnv` 以给出该实例的 Claude 代码进程变量 Pi 其它部分不能看到, 例如登录符号 : ```ts import { createClaudeBridgeExtension } from "@buyong/pi-claude-bridge/src/index.ts"; export default createClaudeBridgeExtension({ getChildEnv: ({ purpose }) => ({ CLAUDE_CODE_OAUTH_TOKEN: token }), }); ``` - 桥叫 `getChildEnv` 就在克劳德代码程序开始之前. `purpose` 实值 `"provider"` 关于示范请求和 `"summary"` 供摘要使用. - 返回的变量仅适用于这一过程,并覆盖桥架所设置的变量。 桥不将其写入Pi的环境,设置,日志,或错误消息. - 若为 `getChildEnv` 除了简单的字符串对象外, 丢出或返回其它任何对象, 请求失败而不启动 Claude Code 。 错误消息不包括值 . - 每个 Pi 进程装入一个桥实例 。 如果 Pi 也加载已安装的软件包, 注册实例首先服务请求 . ## 调试 设定 `CLAUDE_BRIDGE_DEBUG=1` 启用调试输出 : - **桥梁日志** 时间 `claude-bridge.log` 在 Pi 代理目录中`PI_CODING_AGENT_DIR`默认值 `~/.pi/agent`: 提供者呼叫,会话同步决定,工具结果,和克洛德代码stderr. 更改位置为 `CLAUDE_BRIDGE_DEBUG_PATH`。 。 。 . - **Per-query Claude 代码 CLI 日志** 时间 `cc-cli-logs/--.log` 桥头日志旁边:子进程自身的调试流,标记所在 `provider` 或者说 `compact-summary`显示 Claude 代码对会话加载、 API 请求和工具调用的看法. `CLAUDE_BRIDGE_DEBUG_PATH` 也将此目录移动到迁移的桥日志旁边 . - **诊断垃圾场** 时间 `claude-bridge-diag.log` 在 Pi 代理目录中: 出乎意料的提供者状态和快速抓取失败. 这些可以写 即使调试关闭,和 `CLAUDE_BRIDGE_DEBUG_PATH` 不移动它们. 诊断性写作是最佳的:一个失败的写作被忽略,而不是在TUI上打断提供者或打印. 工具结果调试预览只在启用调试时才会生成 . 当您报告会话重现失败时( 例如“ 找不到对话 ” ), 请附加 `syncResult:` 从桥头日志和匹配中的行 `cc-cli-logs/` 用于失败查询的文件。 共享前审查日志;它们可以包含提示和工具输出. ### 手动清理日志 日志从未自动旋转或删除 。 停止使用 Pi 和 Claude 代码的过程,保存所需的任何诊断,然后只删除日志文件. 在相同的外壳中运行示例 `HOME` 和路径覆盖为 Pi; 它扩展 `~` 财务报告和审定财务报表 `~/...` 内 `PI_CODING_AGENT_DIR` 和Pi一样: ```bash agent_dir="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}" case "$agent_dir" in '~') agent_dir="$HOME" ;; '~/'*) agent_dir="$HOME/${agent_dir#\~/}" ;; esac bridge_log="${CLAUDE_BRIDGE_DEBUG_PATH:-$agent_dir/claude-bridge.log}" cli_log_dir="$(dirname "$bridge_log")/cc-cli-logs" rm -f -- "$bridge_log" "$agent_dir/claude-bridge-diag.log" if [ -d "$cli_log_dir" ]; then find "$cli_log_dir" -maxdepth 1 -type f -name '*.log' -delete fi ``` 不删除 `~/.claude/projects/` (或 `$CLAUDE_CONFIG_DIR/projects/`)或该类 `tool-results/` 作为日志清理的一部分的目录:当桥重建对话时,早期会话仍然可以提供数据. ## 已知问题 **快速缓存在重建后并不总是完全被再利用.** 该桥保存了上下文附件,工具结果的确切形式和关键顺序,并保存了图像和大结果文件来避免重拾一切;如果Pi编辑了工具结果,则被编辑的内容会取胜. 即便如此,用克洛德代码2.1.303和海库5.5, 一个普通的恢复,没有重建 重写环境 `system` 消息,克劳德代码在会话的第二个请求上附加了第一个请求(约350个令牌)之后,而不是从缓存读取. 之后的每一个转弯 都会重写出一条小线索 `system` 大约25个纪念品 在进程重启后,或在只存在于皮中的对话后重建,成本相同;桥所增加的任何额外损失都没有被测量. Claude Code决定这些消息的去向和如何被缓存,因此桥无法去掉它们,匹配它们的内容形状(块数组或字符串)不会改变这一点. 收缩,树通航等真实历史变化,以及缓存过期,也防止了再利用的完全. **重启不会像现在这样恢复先前的克洛德代码会话 .** 该桥记录a `claude-bridge-cc-session` 链接条目,不包括在模式上下文中,关于当前 Pi 分支。 重开时,它只将早期的克洛德代码会话读作源材料并创建了新的克洛德代码会话UUID. 没有链接条目,文件,或者写手柄,它只从Pi历史中重建. 先前的会话和结果文件不会自动清理 . **文件 Claude 代码编辑不通过重建传输 .** 编辑本身作为工具调用和结果在历史中幸存;丢失的是后编辑文件快照. `@file` 扩展 _为:_ 载. **导出 Anthropic 环境变量超过 Claude 代码子( 第 107 期) .** 导出 `ANTHROPIC_BASE_URL`, (中文(简体) ), `ANTHROPIC_API_KEY`,或 `ANTHROPIC_AUTH_TOKEN` 将克洛德代码重定向到那个网关,每个转弯都会因认证错误而失败. 为 Pi 进程取消它们 . ## 发展和发行 本节供在联合国秘书处工作的撰稿人使用 `pi-packages` 仓库. ### 测试 开发需要节点22.19或后期和pnpm 10. 从 `pi-packages` 仓库根 : ```bash pnpm install --frozen-lockfile pnpm --filter @buyong/pi-claude-bridge typecheck pnpm --filter @buyong/pi-claude-bridge test:unit pnpm --filter @buyong/pi-claude-bridge verify --all --report /tmp/cc-bridge-offline.json pnpm --dir apps/pi-claude-bridge pack ``` 当没有类型错误或单位测试失败时,每个检查出口都使用代码0. `pack` 写入 npm `.tgz` 到应用程序目录并替换 `catalog:` 以真实版本为参考。 Pi 开发依赖来自工作空间目录, 而类型检查保留已有 `tsc` 财务报告和审定财务报表 `tsconfig.json`。 。 。 . 校验 CLI 仅是寄存器,不是 npm 包的一部分. 默认它不叫模特儿 将现场检查标记为 `skipped`· ; `verify --list` 列出支票。 现场检查需要Claude代码订阅登录并使用配额. ```bash pnpm --filter @buyong/pi-claude-bridge verify live-smoke --live --report /tmp/cc-bridge-live.json ``` 缓存测量是可选的,不是其中的一部分 `verify --all` 或者说 `test`;只在需要的时候运行. 一跑约73个海口5.5请求. 由于此处所描述的重新启动缺口 [已知问题](https://npmcn.com/package/%40buyong/pi-claude-bridge/#readme-known-issues), (中文(简体) ), `06-rebuild-cache` 报告 `fail` 和命令出口为 1. ```bash pnpm --filter @buyong/pi-claude-bridge verify --cache --live --report /tmp/cc-bridge-cache.json pnpm --filter @buyong/pi-claude-bridge test:cache ``` 现场检查只使用Haiku 5.5. 若为 `ANTHROPIC_API_KEY`, (中文(简体) ), `ANTHROPIC_AUTH_TOKEN`,或任何 `CLAUDE_CODE_USE_*` 变量被设定,在任何请求之前,它们以退出代码2停止。 一旦成功,他们以0退出,报告记录了版本,源散列,检查结果,以及请求数. 他们清理临时工作目录和克洛德代码会话,记录散列而不是请求文本. `pnpm --filter @buyong/pi-claude-bridge test` 也运行名为真API的集成测试. 设定 `CLAUDE_BRIDGE_TESTING_ALT_MODEL`,替代提供者需要检查,在应用程序中 `.env.test`。 。 。 . 真正的融合试验 `pi` 和 Claude 代码子进程并需要写入访问 `~/.claude`;一个挡住它的沙盒 `--resume` 失败 `No conversation found with session ID`。 。 。 . ### 单独检查本地装入 随着Node.js和Pi的安装和依赖性安装,从寄存器根运行. 单独的设置目录保留了现有的 npm 安装不同时加载. ```bash node --version pi --version package_dir="$PWD/apps/pi-claude-bridge" check_dir="$(mktemp -d)" mkdir -p "$check_dir/agent" "$check_dir/work" cd "$check_dir/work" PI_CODING_AGENT_DIR="$check_dir/agent" PI_OFFLINE=1 \ pi --no-skills --no-prompt-templates --no-themes --no-context-files -e "$package_dir" ``` 确认 Pi 启动时没有扩展加载出错 `/model` 列表 `claude-bridge/*` 模特们 成功加载无法证明克劳德认证或工作请求 。 在此环境中调用一个模型需要单独的认证,并且可以使用配额. ### 检查软件包内容 安装依赖后, 从寄存器根运行 . `tools/package-check/` 是 pi-package-creator 包检查器的复制件,不是 npm 包的一部分。 检查器实际上加载了扩展代码,所以它随您的用户权限运行. 这不叫模特儿. ```bash package_dir="$PWD/apps/pi-claude-bridge" reports="$(mktemp -d)" node "$package_dir/tools/package-check/validate-package.mjs" "$package_dir" \ --expect "$package_dir/tests/fixtures/package-inventory.json" --runtime \ --report "$reports/package-check.json" ``` 密码为 0 的路过运行退出, 报告显示 `status: "pass"`:一个扩展,零工具,命令,和旗帜,没有加载诊断. `skipped` 页:1 `semantic import and bundle inspection` 表示检查器不静态分析导入; 这不是失败 。 默认情况下,检查器使用安装在工作空间中的 Pi. 为检查全球安装的 Pi, 添加 `--pi-root "$(npm root -g)/@earendil-works/pi-coding-agent"`。 。 。 . 从只安装生产依赖的取出副本中再次检查释放归档 . `npm install` 联系 npm 注册。 在同一外壳中继续重用上述变量. ```bash artifact_dir="$(mktemp -d)" pnpm --dir "$package_dir" pack --pack-destination "$artifact_dir" mkdir -p "$artifact_dir/runtime" printf '{"private":true}\n' > "$artifact_dir/runtime/package.json" npm install --prefix "$artifact_dir/runtime" --omit=dev --ignore-scripts --legacy-peer-deps \ --no-audit --no-fund "$artifact_dir"/*.tgz node "$package_dir/tools/package-check/validate-package.mjs" \ "$artifact_dir/runtime/node_modules/@buyong/pi-claude-bridge" \ --expect "$package_dir/tests/fixtures/package-inventory.json" --runtime \ --pi-root "$package_dir/node_modules/@earendil-works/pi-coding-agent" \ --report "$reports/package-artifact.json" ``` 预期成果匹配源码检查 。 此检查确认只包含生产依赖的扩展负载; 它不检查 Claude 认证或真实请求 . ### 发布和上游更新 释放 `main` 跟踪 `origin/main`,带有干净的跟踪文件和Git索引。 更改日志条目进入 `UNRELEASED` 节 `CHANGELOG.md` (英文)和 `CHANGELOG.ko.md` (韩语);释放期间, `claude -p` 起草任何缺失条目,并在确认后记录。 从寄存器根运行以下并选择 `@buyong/pi-claude-bridge`数字 : ```bash pnpm release ``` 在更改日志草稿和版本选择后,您确认承诺,标记,并逐一推. 要先检查准备状态而不更改文件, 请运行 `pnpm release:dry-run --app pi-claude-bridge --version `。如果拒绝或取消,则剩下的步骤停止,本地更改已保留。 推力只发出 `main` 选择 `pi-claude-bridge-v` 标签。 共享 `.github/workflows/pi-packages.yml` at source root 从标记中选择桥,验证它,用 OIDC 发布到npm,并创建 GitHub 发布. 稳定版本使用 `latest` 标签; 预释使用其标识符或 `next`。 。 。 . Npm 信任的发布器必须链接到 GitHub 用户 `buYoung`,仓库 `pi-packages`,和工作流程文件名 `pi-packages.yml`中输入文件名. 没有配置上游远程或自动同步 。 必要时,用手拉动更改 [上游更新指南](https://github.com/buYoung/pi-packages/blob/main/apps/pi-claude-bridge/docs/upstream.md)。 。 。 . ## 许可证 [麻省理工学院](https://npmcn.com/package/%40buyong/pi-claude-bridge/LICENSE)许可通知保留了原作者Eli Dickinson的版权. ## 常见问题 ### @buyong/pi-claude-bridge 是什么？ Pi扩展使用克洛德代码\(通过Agent SDK\)作为模型提供者\. ### 如何安装 @buyong/pi-claude-bridge？ 在项目目录运行 npm install @buyong/pi-claude-bridge，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@earendil-works/pi-ai（\*）、@earendil-works/pi-coding-agent（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @buyong/pi-claude-bridge 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/buyong\_\_pi-claude-bridge 是否存在。 ### @buyong/pi-claude-bridge 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @buyong/pi-claude-bridge 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @buyong/pi-claude-bridge 可以商用吗？ @buyong/pi-claude-bridge 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @buyong/pi-claude-bridge 的下载量有多少？ 根据 npm 官方下载统计，@buyong/pi-claude-bridge 在 2026/10/09 – 2026/11/07 这 30 天内被下载 1,833 次，日均约 61 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @buyong/pi-claude-bridge 还在维护吗？ 最新版本 0\.14\.3 发布于 2026/11/07（3 天前）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/09/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。