# pi-kimi-webbridge-bootstrap

[English](./README.md) | [简体中文](./README.zh-CN.md)

一个 [Pi](https://github.com/earendil-works/pi-mono) 扩展：自动安装和更新官方 [Kimi WebBridge](https://www.kimi.com/) CLI、本地守护进程与 Pi 技能，让 Pi 直接操作已登录的浏览器标签页。

`/webbridge-status` 输出示例：

```text
WebBridge daemon: running (v0.1.3)
Browser extension: connected
Pi skill: v0.1.3
CLI: ~/.kimi-webbridge/bin/kimi-webbridge
Skill: ~/.pi/agent/cache/pi-kimi-webbridge-bootstrap/skills/current/kimi-webbridge
```

## 环境要求

- 支持 `resources_discover` 的 Pi（已用 Pi 1.0.2 及以上版本测试）
- Node.js >= 20
- macOS 或 Linux（`arm64` 或 `x64`）
- 已在 Chrome 或 Edge 中安装并启用 [Kimi WebBridge 浏览器扩展](https://chromewebstore.google.com/detail/kimi-webbridge/fldmhceldgbpfpkbgopacenieobmligc)

## 安装

从 npm 安装：

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

从 GitHub 安装：

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

从本地目录安装（开发调试）：

```bash
pi install /path/to/pi-kimi-webbridge-bootstrap
```

安装后执行 `/reload` 或重启 Pi 生效。

## 使用说明

1. 首次启动会话（或执行 `/reload`）时，扩展会将官方 CLI 下载到 `~/.kimi-webbridge/bin/`，启动本地守护进程，并将版本匹配的技能缓存到 `~/.pi/agent/cache/pi-kimi-webbridge-bootstrap/skills/`。
2. 在 Chrome 或 Edge 中安装并启用 [Kimi WebBridge 浏览器扩展](https://chromewebstore.google.com/detail/kimi-webbridge/fldmhceldgbpfpkbgopacenieobmligc)。如果首次运行时未检测到浏览器连接，Pi 会自动提示该安装链接。
3. 执行 `/webbridge-status`，确认 `Browser extension` 显示为 `connected`。
4. 本地已有可用技能缓存后，扩展默认每 6 小时在会话启动时于后台异步检查更新，不会阻塞 Pi 启动。后台更新切换到新版本技能后，会提示你执行 `/reload`。

### 命令

| 命令 | 说明 |
| --- | --- |
| `/webbridge-status` | 查看本地守护进程状态、浏览器扩展连接、缓存技能版本及最近一次更新错误 |
| `/webbridge-setup` | 显示浏览器扩展安装说明，或确认浏览器扩展已连接 |
| `/webbridge-update` | 立即检查上游新版本并更新本地 CLI 与技能缓存 |

## 配置

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `PI_WEBBRIDGE_AUTO_UPDATE` | `1` | 设为 `0` 可关闭自动安装与定时更新检查（手动命令仍可用） |
| `PI_WEBBRIDGE_UPDATE_INTERVAL_HOURS` | `6` | 会话触发后台更新检查的间隔小时数（失败后冷却 15 分钟再试） |
| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | 自定义 Pi Agent 目录（技能缓存目录自动跟随） |

## 隐私与安全

- 仅从 Moonshot AI 官方 CDN（`https://cdn.kimi.com/webbridge`）下载二进制与技能包，本扩展包内不打包任何专有二进制或技能源码。
- 新下载的 CLI 会对照 `latest/version.json` 校验 SHA-256，若新版本无法启动或状态异常则自动回滚到上一版二进制。
- 技能压缩包会先在独立目录中完成 tar 头校验、条目类型检查、路径穿越检查、解压体积限制和 `SKILL.md` frontmatter 校验，通过后才原子切换 `skills/current`。
- 通过 `~/.kimi-webbridge/pi-bootstrap-update.lock` 进程锁协调多个并发的 Pi 会话，仅在持锁进程已退出时回收陈旧锁。
- 不注册系统级 cron 或 launchd 定时任务，仅在 Pi 会话事件中触发检查。注意 `~/.kimi-webbridge` 及其守护进程为当前系统用户共享，执行 `kimi-webbridge upgrade` 时会短暂重启该守护进程。

## 本地开发

```bash
# 运行测试
npm test

# 语法检查并运行测试
npm run check

# 检查打包文件列表
npm run pack:check
```

## 许可证

[MIT](./LICENSE)。