feat: commandcode-pi 0.1.0 — Command Code Go provider over /alpha/generate

从 ~/.pi/agent/extensions/ 的本地实验文件收编为独立 pi 包:

- extensions/commandcode-go.ts:provider commandcode-go,只走 CLI 内部端点
  POST /alpha/generate;启动拉 /provider/v1/models 并过滤出 Go 套餐可用的
  DeepSeek 模型;凭据按 env → ~/.commandcode/auth.json → pi auth.json 顺序验活
- extensions/commandcode-transient-retry.ts:把网关签名明确的偶发 400 改写为
  可重试,复用 pi 内置退避重试
- 文档:README(安装/凭据/模型/风险/排查)、docs/protocol.md(线协议)、
  LICENSE(MIT + 上游署名)
This commit is contained in:
2026-11-16 18:17:49 +08:00
commit 657fe90fd3
8 changed files with 1377 additions and 0 deletions
+149
View File
@@ -0,0 +1,149 @@
# commandcode-pi
让 **Command Code「Go」套餐**能在 [pi](https://pi.dev) 里当 API 用:注册 DeepSeek 模型,并用官方 CLI 的内部端点 `POST /alpha/generate` 流式对话。
> 非官方实现。它模拟官方 CLI 的请求头与线协议,属于对厂商内部接口的逆向复用,见 [风险与合规](#风险与合规)。
## 为什么需要它
Command Code 把「订阅套餐」和「Provider API」拆成了两种权限:
| 通道 | 端点 | Go 套餐可用 |
|---|---|---|
| Provider API(OpenAI 兼容) | `/provider/v1/responses`、`/provider/v1/chat/completions` | ❌ 一律 `403 upgrade_required` |
| 官方 CLI 内部端点 | `/alpha/generate` | ✅ 唯一可用通道 |
现成的两个 pi 插件都用不了:`@commandcode/pi-commandcode-provider`(官方)只走 Provider API;`pi-commandcode-provider`(社区)自 0.8.0 起主动删掉了 `/alpha/generate` 兜底(最后带兜底的是 0.7.12)。因此这里自建一个只走该端点的最小 provider。
## 安装
```bash
# 从本仓库安装(跟踪 main,改完 push 后 pi update --extensions 生效)
pi install ssh://git@git.cat-shark.xyz:2222/cat-shark/commandcode-pi.git
# 需要锁版本时
pi install ssh://git@git.cat-shark.xyz:2222/cat-shark/commandcode-pi.git@v0.1.0
```
安装后由 pi 管理到 `~/.pi/agent/git/git.cat-shark.xyz/cat-shark/commandcode-pi`。
不想用包管理时,也可以直接把两个文件拷进全局扩展目录(pi 启动即自动发现):
```bash
cp extensions/*.ts ~/.pi/agent/extensions/
```
> 两种方式**只选一种**。同时存在会造成 provider id `commandcode-go` 被注册两次。
本包 `package.json` 的 `pi.extensions` 同时声明了两个文件:
| 文件 | 作用 | 可否省略 |
|---|---|---|
| `extensions/commandcode-go.ts` | provider 本体 | 必需 |
| `extensions/commandcode-transient-retry.ts` | 把 Command Code 网关偶发 400 改写成可重试,复用 pi 内置退避重试 | 可选,省略后偶发 400 需手工重发 |
## 凭据
按可信度顺序自动挑选,启动时逐个 `GET /alpha/whoami` 验活,过期的自动跳过:
1. 环境变量:`COMMAND_CODE_GO_API_KEY` → `COMMAND_CODE_API_KEY` → `COMMANDCODE_API_KEY`
2. `~/.commandcode/auth.json`(`cmd login` 写入的官方 CLI 凭据)
3. `~/.pi/agent/auth.json`(pi 的 `/login` 写入的凭据,条目 id 依次尝试 `commandcode-go`、`commandcode`、`command-code`)
全部失效时留占位符,`/login` 选 `commandcode-go` 粘贴新 key 即可写入 `auth.json`。
```bash
# 换 key 后确认拿到了哪一把(只显示前 8 位)
/commandcode-go-status
```
## 用法
启动时拉取 `GET /provider/v1/models?view=client` 生成模型列表,缓存到 `~/.pi/agent/commandcode-go-catalog.json`(命中缓存不刷新,要最新目录就删掉该文件)。
过滤规则(在 `toModelConfig()` 里):
- 只保留 `id` 以 `deepseek/` 开头的模型
- 只保留 `minimumPlan` 为空或 `individual-go` 的模型(其它档位选到就是 `MODEL_NOT_IN_PLAN`)
典型注册结果(全部 Go 套餐可用):
| 模型 | 上下文 | 图片 | 思考档位 |
|---|---|---|---|
| `deepseek/deepseek-v4-pro` | 1M | ✗ | off/high/max |
| `deepseek/deepseek-v4-flash` | 1M | ✗ | off/high/max |
| `deepseek/deepseek-v4-flash-fast` | 1M | ✗ | low/high/max |
| `deepseek/deepseek-v4-flash-vision-exp` | 1M | ✓ | off/high/max |
| `deepseek/deepseek-v4.1-flash` | 1M | ✓ | off/low/high/max |
| `deepseek/deepseek-v4.1-flash-fast` | 1M | ✓ | off/low/high/max |
设为默认(`enabledModels` 首项会抢占 `defaultProvider`,两处都要对齐):
```json
"defaultProvider": "commandcode-go",
"defaultModel": "deepseek/deepseek-v4.1-flash",
"enabledModels": ["commandcode-go/deepseek/deepseek-v4.1-flash", "..."]
```
## 配置
| 环境变量 | 默认 | 说明 |
|---|---|---|
| `COMMAND_CODE_GO_API_KEY` / `COMMAND_CODE_API_KEY` / `COMMANDCODE_API_KEY` | — | 最高优先级凭据来源 |
| `COMMANDCODE_API_BASE` | `https://api.commandcode.ai` | 换网关/镜像时用 |
代码内常量:`CLI_VERSION = "1.88.5"`(请求头伪装的官方 CLI 版本)、`MAX_OUTPUT_TOKENS = 131072`(服务端实际上限约 200K,按官方 CLI 取值压低)、`TOOL_CALL_ID_LIMIT = 64`(网关拒绝更长的 tool-call id)。
## 验证
```bash
# 1. 模型注册(应为 6 个,且无 provider warning)
pi --list-models | grep -c commandcode-go
# 2. 纯文本
pi -p "用三个词回答:你好" --model commandcode-go/deepseek/deepseek-v4.1-flash
# 3. 工具循环(验证工具调用、结果回传、历史回放)
pi -p "用 bash 工具执行 uname -a,然后只回答内核版本"
# 4. 失败分类:选一个 Go 套餐没有的模型,应报 403 MODEL_NOT_IN_PLAN 并带中文提示
```
## 错误码
| 网关返回 | 扩展给的提示 |
|---|---|
| `MODEL_NOT_IN_PLAN` | 该模型不在 Go 套餐内,换一个模型 |
| `UNAUTHORIZED` | key 无效/过期,走 `/login` 或换 env |
| `upgrade_required` | Go 套餐没有 Provider API 权限,本扩展只走 `/alpha/generate` |
## 风险与合规
1. **非官方通道**:`/alpha/generate` 是官方 CLI 的内部端点,未公开承诺稳定;上游改协议或封禁即失效,且需要同步升级 `CLI_VERSION`。
2. **服务条款冲突风险**:伪装 `User-Agent`、`x-command-code-version` 模拟官方客户端,与 Command Code 服务条款存在冲突,账号自负风险。
3. **无自动重试**(provider 本体):依赖 pi 内置重试;`commandcode-transient-retry.ts` 只覆盖网关签名特征明确的 400。
4. **成本为估算**:价格取自上游目录,`maxTokens` 统一按 131 072 注册(目录未给 `maxOutputTokens`),不影响计费但会高估可用输出上限。
5. **缓存陈旧**:`~/.pi/agent/commandcode-go-catalog.json` 命中即不刷新。
## 故障排查
| 现象 | 排查 |
|---|---|
| `/model` 里没有 `commandcode-go` | `pi list` 看包是否装了;`pi --list-models` 是否有 warning;两个来源是否重复加载 |
| 一直 401 | key 过期:`/commandcode-go-status` 看凭据前缀,`curl -H "Authorization: Bearer $KEY" https://api.commandcode.ai/alpha/whoami` |
| 403 `MODEL_NOT_IN_PLAN` | 选了 Go 套餐不含的模型,见上方模型表 |
| 偶发 `invalid request error trace_id` 400 | 网关瞬态故障;确认 `commandcode-transient-retry.ts` 已加载,然后重发 |
| 模型列表少了新模型 | 删掉 `~/.pi/agent/commandcode-go-catalog.json` 后重启 |
## 开发
```bash
git clone ssh://git@git.cat-shark.xyz:2222/cat-shark/commandcode-pi.git
cd commandcode-pi
# 本包无 runtime 依赖,扩展直接由 pi 加载(pi 提供 @earendil-works/* 模块映射)
# 改完提交并推送,让 pi 管理的副本跟上
git push && pi update --extensions
```
版本号写在 `package.json`,变更写 `CHANGELOG.md`(pi 会按版本号在下次启动的 "Extension Updates" 里展示)。线协议细节见 [`docs/protocol.md`](docs/protocol.md)。