@raoxxxwq/pi-codebuddy-sdk

Pi 扩展：把 CodeBuddy 注册为 Pi 的模型提供商。你继续使用 Pi 的 TUI、工具、技能和扩展；CodeBuddy 通过 codebuddy CLI 在本地跑推理。除了选个模型，你在 Pi 里的使用方式完全不变。

• 仓库：https://github.com/MuJianxuan/pi-codebuddy-sdk
• 作者：raoxxxwq

它能做什么

• 在 Pi 中暴露 CodeBuddy 模型（/model 里以 codebuddy/... 出现）
• 把 Pi 的工具桥接给 SDK（工具仍由 Pi 执行；CodeBuddy 只负责规划和调用）
• 在主 Provider Path 上强制每轮只发起一个桥接工具调用以保证稳定
• 转发 Pi 生效中的 system prompt 和技能，让模型"像 Pi 一样行动"而非独立运行的 CodeBuddy Code；Pi 的 -nc / --no-context-files 退出选项被尊重
• 支持会话恢复（resume）、压缩（compaction）、流式输出、thinking 级别和图片
• 会话重建/恢复时对历史图片工具结果做文本化表示；当前轮次的用户图片保留其带类型的 base64/mime 数据
• 随时间学习任务实际服务的上下文窗口，并把 Pi 注册的模型元信息保守地对齐到观测到的真实值
• 可选的 AskCodebuddy 工具，把聚焦子任务委派给另一次 CodeBuddy 调用

安装

pi install npm:@raoxxxwq/pi-codebuddy-sdk

如果 Pi 已在运行，请重启。

要求

• codebuddy 在 PATH 上 —— 扩展会拉起和你独立使用时同一个 CLI。若 which codebuddy 失败，要么把它加入 PATH，要么在 codebuddy-sdk.json 里设置 pathToCodebuddyCode（见配置）。
• CodeBuddy 鉴权已可用 —— 只要 codebuddy 在你的终端能用，本扩展无需额外设置。

快速开始（已经在用 CodeBuddy）

不需要 codebuddy-sdk.json，也不需插件专属环境变量。

1. pi install npm:@raoxxxwq/pi-codebuddy-sdk
2. 重启 pi
3. /model → 选 codebuddy/...

可选：在 ~/.pi/agent/settings.json 里设置 defaultProvider / defaultModel，省去每次 /model。

启动后第一次查询可能要等几秒，因为模型要从 SDK 发现。

鉴权

扩展不存储凭据。CodeBuddy CLI 从你的机器读取。使用以下任一：

1. CLI 登录（推荐）

codebuddy login

在浏览器完成登录。凭据留在你机器上；Pi 自动复用。

2. API Key

export CODEBUDDY_API_KEY="your-api-key"

从你的 CodeBuddy 账户获取 key。不要提交它，也不要存进仓库文件。

3. 腾讯 iOA（内网）

export CODEBUDDY_INTERNET_ENVIRONMENT=ioa
codebuddy login

当 CodeBuddy 必须跑在 iOA 网络时使用。若你的环境还要求，附上 CODEBUDDY_API_KEY。

使用

pi
/model

挑任意以 codebuddy/ 开头的一项（例如 codebuddy/hy3）。

工具、技能、扩展、/compact 和 steer 的行为与其他 Pi 提供商一致。

AskCodebuddy

当 AskCodebuddy 工具启用（默认），任何提供商都能把聚焦子任务委派给一次独立的 CodeBuddy 调用。这就是 Delegation Path —— 与主 Provider Path 不同，CodeBuddy 在这里直接跑它自己的原生工具（而非 Pi 桥接的 MCP 工具）。

• "read" 模式（默认）：代码库相关问题 —— 审查、分析、解释。
• "full" 模式：允许写文件和执行 bash（无反馈地运行 —— 谨慎使用）。
• "none" 模式：仅通用知识（无文件访问）。

当当前活跃提供商已是 codebuddy/... 时，AskCodebuddy 会被自动屏蔽（防止循环委派）。

工作原理

两条路径

• Provider Path（主路径）：在 Pi 中选 codebuddy/... 模型后，CodeBuddy 作为 Pi 的 provider 直接驱动 Pi 工具。
• Delegation Path（委派路径）：Pi 中的其他 provider 调用 AskCodebuddy 工具，把聚焦任务委派给一次独立的 CodeBuddy 调用。

Pi 执行工具（Pi-Executed Tooling）

Provider Path 中，CodeBuddy 只计划和发起 tool call；实际的工具执行、权限边界、结果渲染和会话历史都由 Pi 负责。

严格 MCP 边界（Strict MCP Boundary）

Provider Path 默认只把 Pi Tool Bridge 提供的 MCP 工具暴露给 CodeBuddy，避免 CodeBuddy 加载外部 MCP 或原生工具后绕过 Pi 的权限、渲染与会话历史。严格 MCP 模式已默认启用，不再有可关闭的配置项。

会话同步（REUSE / REBUILD）

桥接层维护 Pi 与 CodeBuddy 会话之间的同步。当 Pi 历史与缓存会话一致时复用（REUSE，保持 prompt cache 热）；当历史出现分歧（如 /compact、会话树导航、fork、其他 provider 接过一轮）时整体重建（REBUILD）。

工具调用正确性保障（Tool Call Correctness）

针对 CodeBuddy 经 MCP 调用 Pi 工具时容易出现的选错工具、参数 schema 不符、并行批处理时参数被丢弃等问题，桥接层做了多层保障：

• 工具名映射：mcp__custom_tools__read ↔ read 双向翻译。
• 参数重命名：file_path → path、old_string → oldText、new_string → newText 等。
• 并行 arg-dropping 防护：检测被丢弃的空参数并延迟补齐，防止用空参数执行工具导致校验失败。
• Provider Tool Guidance：注入工具使用顺序约定（先 read 理解，再 edit 定点修改，write 只用于新建/全量替换，bash 仅在文件工具不足或用户要求命令时使用），并强制每轮至多一个工具调用。单工具调用现已强制，不再有 serialToolCalls 配置项。
• 串行协调：运行时通过串行槽与 canUseTool 预校验，拦截并行调用与空必填参数。

运行时校准（Runtime Calibration）

扩展会学习每个模型运行时实际服务的上下文窗口（Served Context Window），并以保守注册策略消除"窗口漂移"（Window Drift）：绝不宣传比运行时已证明能服务的更大窗口。校准记录按环境信号键控，存于用户级缓存，跨 Pi 会话复用。

项目信任系统

全局配置在扩展启动时加载。项目配置只在 session_start 时你选择 Allow and remember 后才会读取；该决策按规范化的项目路径记录于 ~/.pi/agent/codebuddy-sdk-project-trust.json。在无对话框 UI 的模式下，未获批准的项目配置会被忽略并告警。

配置

可选。 默认值对多数用户已够用。

全局文件：~/.pi/agent/codebuddy-sdk.json

项目文件：.pi/codebuddy-sdk.json

全局配置在扩展启动时加载。项目配置只在 session_start 选择 Allow and remember 后读取；决策存于 ~/.pi/agent/codebuddy-sdk-project-trust.json。无对话框 UI 的模式下，未批准的项目配置会被忽略并告警。

项目 askCodebuddy 与 provider 段按 key 覆盖全局值；数组替换全局数组而非拼接。provider.pathToCodebuddyCode 仅全局有效：即便对已批准的项目，项目值也会被忽略并告警。改完项目配置后运行 /reload。

{
  "askCodebuddy": {
    "enabled": true,
    "allowFullMode": true,
    "defaultMode": "read"
  },
  "provider": {
    "appendSystemPrompt": true,
    "pathToCodebuddyCode": "/path/to/codebuddy"
  }
}

AskCodebuddy 选项

| 选项 | 默认 | 含义 | |--------|---------|---------| | askCodebuddy.enabled | true | 注册 AskCodebuddy 委派工具 | | askCodebuddy.allowFullMode | true | 允许写能力的（"full"）委派模式 | | askCodebuddy.defaultMode | "read" | 默认委派模式："read"（文件访问）、"full"（写 + bash）或 "none"（仅通用知识） | | askCodebuddy.defaultIsolated | false | 委派是否运行在干净会话（无对话历史）中 | | askCodebuddy.appendSkills | true | 在委派 system prompt 中包含 Pi 技能块 | | askCodebuddy.name | "AskCodebuddy" | 工具名 | | askCodebuddy.label | "Ask CodeBuddy" | Pi TUI 中显示的工具标签 | | askCodebuddy.description | 自动 | 在 Pi 中显示的工具描述 |

Provider 选项

这些控制主 Provider Path（在 /model 中选 codebuddy/... 时）。标注 escape hatch 的不是日常调优项 —— 仅用于调试或兼容性时关闭。

| 选项 | 默认 | 含义 | |--------|---------|---------| | provider.appendSystemPrompt | true | 使用 Pi 的 system prompt 和 Pi Tool Bridge 指导，而非 CodeBuddy 默认身份（escape hatch —— 关闭会重新启用 CodeBuddy 文件系统设置） | | provider.settingSources | ["user","project"] | 要加载的 CodeBuddy 文件系统设置；仅当 appendSystemPrompt=false 时使用（escape hatch） | | provider.pathToCodebuddyCode | 自动 | 全局专用；当 codebuddy 不在 PATH 时指定其路径；项目值被忽略 |

主 Provider Path 始终以严格 MCP 模式运行，因此在 provider 模式下 CodeBuddy 只可见 Pi 桥接的 MCP server。

provider 以保守校准 floor 注册每个模型。缓存同时记录 latest 和 max 观测值用于诊断，但后续更大的观测值永远不会抬高先前已证明的 floor。

隐私

• 扩展不向本仓库或任何第三方遥测端点发送对话数据。
• 凭据完全由你机器上的 CodeBuddy CLI 处理。
• AskCodebuddy 动作摘要只存固定执行动词（如 Bash）；原始 Bash/PowerShell/Terminal 命令不持久化进 Pi 工具结果。
• 可选调试模式（CODEBUDDY_SDK_DEBUG=1）在 ~/.pi/agent/ 下写本地日志；路径已脱敏，prompt 和工具载荷不会被记录。用完请删除日志。

排错

export CODEBUDDY_SDK_DEBUG=1

默认日志：~/.pi/agent/codebuddy-sdk.log。维护者细节见 CONTRIBUTING.md。

运行时校准缓存：~/.pi/agent/codebuddy-sdk-model-calibration.json 按运行时环境存储观测到的模型能力 floor。

项目配置信任存储：~/.pi/agent/codebuddy-sdk-project-trust.json 按规范化项目路径记录允许/拒绝决策。删除相关条目可重新请求确认。

开发

维护者：见 CONTRIBUTING.md。

License

MIT

灵感来源

早期的 MCP 桥接模式受 pi-claude-bridge 启发。本包是基于 @tencent-ai/agent-sdk 的独立代码库。