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

6.9 KiB
Raw Blame History

commandcode-pi

让 Command Code「Go」套餐能在 pi 里当 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。

安装

# 从本仓库安装(跟踪 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 启动即自动发现):

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。

# 换 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,两处都要对齐):

"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)。

验证

# 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 后重启

开发

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。