**[English](README.md)** | **中文**

---

# pi-opencodego

为 [pi](https://github.com/earendil-works/pi-coding-agent) 写的轻量扩展，专为 **OpenCode Go / Zen** 官方 API 通道提供三项增强：① 请求兼容过滤（解决 `developer` 角色 400）；② 多 key 轮询 + 配额感知 + 会话粘合；③ 用量 / token / 缓存 / 费用跟踪与可视化。

设计原则：**有则改之、无则不动**。

## 安装

需已装 [pi](https://github.com/earendil-works/pi-coding-agent)，二选一：

```bash
pi install npm:pi-opencodego        # 方式一：npm（推荐）
pi install git:github.com/february2015/pi-opencodego   # 方式二：GitHub
```

> ⚠️ pi 扩展会以完整系统权限运行，安装第三方扩展前建议先浏览 [源码](https://github.com/february2015/pi-opencodego)。

## 配置 key

```bash
/ocgo add main sk-你的key      # 添加 key（可加多个）
/ocgo use 1                    # 指定活跃 key（按序号）
/model opencode-go/deepseek-v4-flash   # 切到 OpenCode Go 模型
```

之后正常对话即可——插件自动注入 key、跟踪用量，限流/配额耗尽时自动轮换（同一会话始终粘合同一 key，避免前缀缓存失效）。

## 常用命令

| 命令 | 作用 |
|------|------|
| `/ocgo status` | 列出所有 key 及状态 |
| `/ocgo usage` | 查看三档限额 percent + 重置时间 |
| `/ocgo cost` | 今日 token、估算金额、缓存命中率 |
| `/ocgo add <name> <key>` | 添加 key |
| `/ocgo rm <n>` | 删除 key |
| `/ocgo use <n>` | 切到指定 key |
| `/ocgo next` | 切到下一个 key |
| `/ocgo reset` | 清除所有冷却/封禁 |
| `/ocgo cooldown <min>` | 设置冷却分钟 |
| `/ocgo watchdog [on\|off\|ms]` | watchdog 设置 |
| `/ocgo web` | 查看 Web 面板状态 |
| `/ocgo web start` | 启动 Web 面板（默认已自起） |
| `/ocgo web stop` | 停止 Web 面板 |
| `/ocgo web restart` | 重启 Web 面板 |
| `/ocgo help` | 全部命令 |

## Web 配额面板

扩展**默认自带**浏览器配额面板（默认端口 **8123**），pi 启动后自动后台拉起，无需手动命令。浏览器打开 `http://127.0.0.1:8123` 即可。

用内部指令控制：`/ocgo web status|start|stop|restart`。不想自起可设 `OCGO_NO_WEB=1`。

面板顶栏两个独立下拉：**页面刷新**（默认 5s）与 **OpenCode 查询**（默认 30s）。pi TUI 底栏也会渲染配额进度条 + footer 摘要（仅 TUI）。

## 功能特性

- **能力 A（修 400）**：`before_provider_request` 扫描 `role:"developer"`，上游不支持则改写为 `system`（或合并），幂等，默认开启仅对 `developer` 生效。
- **能力 B（多 key）**：key 池管理 + 配额/冷却/封禁状态 + 失败自动轮换 + **Session 粘合**（同会话同 key，避免换 key 丢前缀缓存）；只换 `Authorization` 头，透传 body。
- **能力 C（用量/费用）**：`message_end` 读标准 `usage` 自动记录；Go 为包月制，金额按内置价格表（含峰谷）估算；`/ocgo cost` 汇总 token、估算金额、缓存命中率。

> 官方 API 实测结论见 [docs/OPENCODE-API.md](docs/OPENCODE-API.md)。

## 目录结构

```
src/core/                    # 零 pi 依赖的纯业务（可被 dsh 复用）
├─ config.ts / keyRouter.ts / usage.ts / pricing.ts
├─ usageStore.ts / developerCompat.ts / webui.ts / portfile.ts / index.ts
pi/index.ts                  # pi 薄封装：事件挂接 + /ocgo 命令 + Web 面板自起
test/*.test.ts               # 单元测试
```

## 文档

| 文档 | 内容 |
|------|------|
| [docs/OPENCODE-API.md](docs/OPENCODE-API.md) | 官方 API 实测结论 |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 分层设计、pi 钩子、兼容性 |
| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | 开发运行、测试、验收、Roadmap |

## 协议

MIT