Files
commandcode-pi/README.md
T
cat-shark 657fe90fd3 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 + 上游署名)
2026-11-16 18:17:49 +08:00

150 lines
6.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)。