pi-kimi-webbridge-bootstrap

English

面向 Pi 的轻量级 Kimi WebBridge 安装与更新代理。负责把官方 daemon 和 Pi skill 装好、对齐，不依赖 Kimi Code。

它本身不做浏览器操控。真正的控制能力在官方 WebBridge skill 里；本包装的是安装、校验、更新和发现。

不内置 Moonshot AI 的专有 skill 或运行时，元数据、二进制和 skill 都从官方 CDN 拉取：https://cdn.kimi.com/webbridge。

能做什么

• 缺 CLI 时，按平台装到 ~/.kimi-webbridge/bin/
• 新二进制对照官方 latest/version.json 做 SHA-256 校验
• CLI 挂了会尝试修复；激活失败则回滚到旧版本
• daemon 没起来就帮你拉起
• Pi 启动 / reload / 新会话时，大约每 6 小时检查一次更新
• 已有运行时走官方 CLI 的 upgrade，沿用它的版本匹配、回滚和重启逻辑
• 按当前 daemon 版本下载对应 skill，放进 Pi 缓存，经 resources_discover 暴露
• 新 skill 过完路径、条目类型、解压大小、frontmatter/版本校验后，再原子切换指针；失败时旧 skill 继续可用
• 首次引导若检测不到浏览器扩展连接，会提示安装扩展

定时检查是会话触发的，不会装 cron 或 launch agent。已有缓存 skill 时，检查在后台跑，CDN 慢或挂了不会拖住 Pi 的资源发现。skill 变了会在更新完成后让 Pi 重新加载资源。

环境要求

• 支持 package 和 resources_discover 的 Pi（测过 0.84.1）
• Node.js 20+
• macOS 或 Linux，arm64 / x64
  Windows 元数据能识别，但 skill 解压依赖兼容的 tar，本项目未完整验证
• 真正控浏览器需要 Kimi WebBridge 浏览器扩展

安装

从 npm：

pi install npm:@specode/pi-kimi-webbridge-bootstrap

从 git：

pi install git:github.com/specode/pi-kimi-webbridge-bootstrap

本地目录：

pi install /absolute/path/to/pi-kimi-webbridge-bootstrap

装完后执行 /reload。首次会话可能稍慢，因为要下载 CLI 和 skill。

如果希望 pi update --extensions 也能更新本 bootstrap 包本身，不要把 git 源钉死在某个 tag 或 commit 上。

浏览器扩展

CLI 和 skill 可以自动装；Chrome / Edge 的扩展需要你自己点确认。

1. 安装 Chrome 网上应用店里的 Kimi WebBridge
2. 确认扩展已启用
3. 在 Pi 里跑 /webbridge-status，看 Browser extension 是否为 connected

首次引导检测不到扩展时会自动给出链接。随时可用 /webbridge-setup 再看一遍说明。

命令

/webbridge-status   # daemon、扩展、skill 缓存、上次更新错误
/webbridge-setup    # 扩展安装引导，或确认已连接
/webbridge-update   # 强制检查发布并刷新 Pi skill，然后 reload 资源

配置

• PI_WEBBRIDGE_AUTO_UPDATE=0：关掉自动安装和定时检查；手动命令仍可用
• PI_WEBBRIDGE_UPDATE_INTERVAL_HOURS=<数字>：改默认 6 小时间隔

检查失败后，大约 15 分钟才会在后续会话事件里再次尝试。跨进程锁在 ~/.kimi-webbridge/pi-bootstrap-update.lock，避免不同 agent 目录的 Pi 会话同时改共享运行时；只有持有锁的进程已经不在了，才会回收陈旧锁。

更新边界

WebBridge daemon 是用户级全局的。官方 kimi-webbridge upgrade 可能顺带刷新其他 agent 运行时里已装的 WebBridge skill，并会短暂重启 daemon。自动检查发生在会话开始、浏览器任务之前，但别的程序如果也在用这个 daemon，仍可能观察到这次重启。

Pi 侧 active skill 靠原子缓存指针切换：

~/.pi/agent/cache/pi-kimi-webbridge-bootstrap/skills/active.json
~/.pi/agent/cache/pi-kimi-webbridge-bootstrap/skills/current -> releases/<version>-<archive-sha256>/
~/.pi/agent/cache/pi-kimi-webbridge-bootstrap/skills/releases/<version>-<archive-sha256>/

macOS / Linux 上 Pi 发现的是稳定路径 skills/current，校验通过后原子替换链接目标。Windows 上目录 junction 不能原子替换，所以用 active.json 原子选出不可变 release，更新后 Pi 再加载该路径。旧的已校验 release 会留着，方便回滚。迁移期间，遗留的 skills/kimi-webbridge/ 目录仍可作为回退。

若配置了 PI_CODING_AGENT_DIR，会用 Pi 解析后的 agent 目录。

开发检查

npm test
npm run check

许可证

MIT