# IMPLEMENT — extensions/pi 薄插件实现步骤

> 依据：`docs/REQ.md`（实现要求）+ `docs/FEATURES.md`（功能说明）
> 目标：把旧仓库 `pi-ocgo` 的厚插件改造为 ocgo-gateway 的 Pi 端薄壳插件。
>
> 现状：`extensions/pi/` 只有 docs 两个文件，无源码。网关（同仓库 master）已就绪：/api 别名、gateway-key 认证、bind 缺省 active、免 body.agent 均已实现并部署验证。

## 阶段 0：搭骨架

- [ ] `extensions/pi-ocgw/package.json`（name 已定 `pi-ocgw`）
- [ ] `extensions/pi/tsconfig.json` — 继承根 tsconfig
- [ ] `extensions/pi/pi/index.ts` — 入口，空壳先跑通
- [ ] `extensions/pi/src/core/` — 从旧仓库拷入需要的模块

## 阶段 1：拷入纯业务核心（src/core/）

从 `/Users/robin/myProject/pi-ocgo/src/core/` 拷入并改造：

| 文件 | 处理 | 说明 |
|------|------|------|
| `config.ts` | **改写为极简** | 只留 `{gatewayBase, gatewayKey}` + 读写/权限 600；删 key 池/冷却/封禁/粘合/缓存白名单配置 |
| `developerCompat.ts` | **完整保留** | developer→system 纯函数，零依赖（能力 4） |
| `cacheOptimizer.ts` | **完整保留** | 删 reasoning / 删时间戳 / 排序 tools + 默认白名单（能力 5） |
| `handoff.ts` | **完整保留** | 交接文档模板/计划/落盘/恢复（能力 7） |
| `sessionWorkspace.ts` | **保留** | 交接依赖的工作区/会话解析 |
| `usageStore.ts` | **删** | 用量归网关 `/admin/stats`（格式化函数可抽到 gatewayClient 复用） |
| `pricing.ts` | **删** | 计价归网关（如需展示费用从网关 stats 拿） |
| `keyRouter.ts` | **删** | 选路/轮换/冷却归网关 `decideKey` |
| `usage.ts` | **删** | 直打上游 usage 归网关 `/admin/quota`；格式化函数（keyWindowBars/footerSummary/formatUsageWindow）迁移到 gatewayClient 或保留独立展示模块 |
| `webui.ts` + `portfile.ts` + `assets/panel.html` | **删** | 面板归网关 `/admin` |
| `index.ts` | 重写导出 | 只导出 mini 需要的模块 |

新增：
- `gatewayClient.ts` — 网关 HTTP 控制面客户端（读 config → fetch /api/* → 解析 JSON）

## 阶段 2：重写 pi/index.ts（薄壳）

原 1415 行厚壳 → 精简薄壳，挂接这些钩子/命令：

| 钩子/命令 | 能力 | 实现要点 |
|-----------|------|---------|
| `registerProvider("pi-ocgw")` | 指向网关 | baseUrl=config.gatewayBase，models 硬编码同款 |
| `before_provider_headers` | 身份+对话标识 | Authorization=Bearer gatewayKey + x-ocgo-conversation=sessionId |
| `before_provider_request` | developer 兼容 | 保留（能力 4） |
| `context` / `before_agent_start` | 缓存前缀稳定 | 保留（能力 5） |
| `message_end` | 统计/推送/交接检查 | 读 usage → 走网关 /api/quota+/api/stats；触发交接提醒（能力 6/7） |
| `/ocgw` 命令组 | 薄命令 | setup/url/key/whoami/status/keys/quota/cost/bind/unbind/default/handoff/resume（§1.2 命令表） |

删除：429 轮换、session 粘合、web 面板、cache 命令、cooldown/watchdog（归网关或砍）、本地 usageStore 落盘。

## 阶段 3：测试 + 联调

- [ ] 重写 `test/*.test.ts`：gatewayClient（mock fetch）、config 读写、developerCompat、cacheOptimizer、handoff 决策
- [ ] 本地起网关（`npm run start`）→ 本地起 pi 装插件 → `/ocgw setup` → `/model pi-ocgw/*` → 发请求验证 header 注入
- [ ] 远端联调：`/ocgw bind` 绑对话 → 请求走对应上游 key → 面板/ stats 看到记录

## 阶段 4：文档收尾

- [ ] README / README-zh：改写为「极简网关配合版」安装/使用
- [ ] DEVELOPMENT / ARCHITECTURE：按新结构更新
- [ ] 部署文档 DEPLOY 已就绪（含 Caddy 方案 B + gateway-keys 同步）

## 验收标准（来自 REQ）

- [ ] 插件本地 config 只有 gatewayBase + gatewayKey
- [ ] 请求自动带 gateway-key + x-ocgo-conversation（可抓包验证）
- [ ] /ocgw 全部命令可用（走 /api/*，仅 gateway-key 认证，不需 Caddy 密码）
- [ ] 统计输出（TUI 进度条/footer/定时推送/命令输出）呈现不变，数据走网关
- [ ] developer 兼容（400 修复）与缓存前缀优化（命中率）行为与旧插件一致
- [ ] handoff 完整流程可用：双水位提醒 → /ocgw handoff → 新会话注入继任