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:
@@ -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)。
|
||||
Reference in New Issue
Block a user