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
+9
View File
@@ -0,0 +1,9 @@
node_modules/
package-lock.json
# 运行时缓存与凭据:由 pi / 扩展在 ~/.pi/agent 下生成,绝不入库
*.log
.env
.env.*
auth.json
commandcode-go-catalog.json
+9
View File
@@ -0,0 +1,9 @@
# Changelog
## [0.1.0] - 2026-11-16
首个版本,从 `~/.pi/agent/extensions/` 的本地实验文件收编为独立项目。
- `extensions/commandcode-go.ts`:`commandcode-go` provider,只走 CLI 内部端点 `POST /alpha/generate`;启动拉 `/provider/v1/models?view=client` 并过滤出 Go 套餐可用的 DeepSeek 模型;凭据按 env → `~/.commandcode/auth.json` → `~/.pi/agent/auth.json` 顺序验活;`/commandcode-go-status` 查看状态。
- `extensions/commandcode-transient-retry.ts`:把 Command Code 网关签名明确的偶发 400 改写成可重试,复用 pi 内置退避重试。
- 文档:`README.md`(安装/凭据/模型/风险/排查)、`docs/protocol.md`(线协议要点)、`LICENSE`(MIT + 上游署名)。
+42
View File
@@ -0,0 +1,42 @@
MIT License
Copyright (c) 2026 cat-shark
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
---
## Third-party attribution
The `/alpha/generate` transport in `extensions/commandcode-go.ts` is a port of
earlier MIT-licensed work. The original copyright notices belong to their
respective authors:
- `patlux/pi-commandcode-provider` (MIT) — `src/core.ts`, `src/converters.ts`
were the base for the request serializer, event-stream decoder, reasoning
replay, tool-call pairing and tool-call id shortening logic. The last version
of that project to still ship the `/alpha/generate` client was 0.7.12.
- `Mars-Sea/dsh-commandcode-provider` (MIT) — `docs/agent-reference/adapter-protocol.md`
and the `buildCliBody()` / `handleCliEvent()` implementations documented the
wire protocol as observed in `command-code@1.88.5`.
`extensions/commandcode-transient-retry.ts` is original to this project.
Command Code and DeepSeek are trademarks of their respective owners. This
project is not affiliated with or endorsed by Command Code.
+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)。
+80
View File
@@ -0,0 +1,80 @@
# `/alpha/generate` 线协议要点
Command Code 官方 CLI 自己走的内网端点。它**不是** OpenAI / Anthropic 兼容协议,`models.json` 无法表达,只能用 provider 扩展实现。以下事实来自逆向复验(`command-code@1.88.5`)与 MIT 许可的上游实现。
## 请求
```
POST https://api.commandcode.ai/alpha/generate
```
请求头:
| 头 | 值 |
|---|---|
| `Authorization` | `Bearer user_...` |
| `Content-Type` | `application/json` |
| `x-command-code-version` | `1.88.5`(伪装官方 CLI 版本) |
| `x-cli-environment` | `production` |
| `x-project-slug` | 项目名 |
| `x-taste-learning` | `false` |
| `x-co-flag` | `false` |
| `User-Agent` | `cli` |
| `x-session-id` | 会话 id |
| `x-cmd-zdr` | `1`(可选,零数据留存) |
请求体:
```jsonc
{
"config": { "workingDir": "...", "date": "...", "environment": {...}, "structure": "...", "isGitRepo": true },
"memory": "", "taste": "", "skills": [],
"permissionMode": "standard",
"params": {
"model": "deepseek/deepseek-v4.1-flash",
"messages": [...], // system 可用数组形式并带 cache_control
"tools": [...],
"system": [...],
"max_tokens": 131072,
"temperature": 0.2, // 可选
"stream": true,
"reasoning_effort": "high" // 可选,取值随模型目录的 reasoningEfforts
},
"threadId": "..."
}
```
约束:
- 工具参数 schema 必须是**对象根**(`type: "object"`)。
- `max_tokens` 服务端上限约 200K(实测 200 704 起 400),官方 CLI 取 131 072。
- `tool-call id` 上限 64 字符;超长需确定性缩短,且调用与结果共用同一映射。
- 历史 assistant 的 `thinking` 必须回放为 `{ "type": "reasoning", "text": ... }`,否则 DeepSeek 思考模式的工具循环会被拒。
## 响应事件流
| 事件 | 含义 |
|---|---|
| `reasoning-start` / `reasoning-delta` / `reasoning-end` | 思考块 |
| `text-start` / `text-delta` / `text-end` | 正文 |
| `tool-input-start` / `tool-input-delta` | 工具参数增量 |
| `tool-call` | 完整工具调用 |
| `cache-write-tokens` | 缓存写入计数 |
| `finish` | 结束,带 `totalUsage` |
| `error` | 错误,带 `code`(`MODEL_NOT_IN_PLAN` / `UNAUTHORIZED` / `upgrade_required` 等) |
| `abort` | 中断 |
## 相关端点
| 端点 | 鉴权 | 用途 |
|---|---|---|
| `GET /alpha/whoami` | 需要 | 验活 key(启动时逐把探测,5s 超时) |
| `GET /provider/v1/models?view=client` | 不需要 | 能力元数据:`minimumPlan`、`pricing`、`reasoningEfforts`、`context_length`、`inputModalities` |
| `POST /provider/v1/*` | 需要(且套餐要含 API 权限) | Go 套餐一律 `403 upgrade_required` |
## 上游来源
- `Mars-Sea/dsh-commandcode-provider`(MIT):`docs/agent-reference/adapter-protocol.md`、`buildCliBody()` / `handleCliEvent()`。
- `patlux/pi-commandcode-provider`(MIT):0.7.12 的 `src/core.ts` / `src/converters.ts`(序列化器、事件解码、reasoning 回放、tool-call 配对与 id 缩短)。
本项目是在这两份实现基础上裁剪出「只服务 Go 套餐」的单链路版本。
File diff suppressed because it is too large Load Diff
+56
View File
@@ -0,0 +1,56 @@
/**
* Auto-retry Command Code's transient HTTP 400s.
*
* Command Code's gateway occasionally rejects an otherwise valid request with
* a generic, server-side 400 — on the native Provider API
* (`/provider/v1/responses`) and on the `/alpha/generate` fallback alike:
*
* commandcode API error (400): {"message":"{\"type\":\"invalid_request_error\",
* \"code\":\"\",\"message\":\"invalid request error trace_id: <hex>\"}\n",
* "type":"invalid_request_error"}
*
* The request is well formed and the identical payload succeeds on replay, so
* this is a transient upstream failure, not a client error. Pi only retries
* assistant errors whose message matches its transient-error classifier
* (`isRetryableAssistantError`), and a bare 400 does not match. Rewriting the
* finalized message to carry the classifier's "server error" marker lets Pi's
* built-in auto-retry (settings.retry: 3 attempts with backoff) handle it
* transparently.
*
* Scope is deliberately narrow — provider `commandcode` + HTTP 400 + the
* gateway's `invalid_request_error` signature — so genuine client-side 400s
* are not blanket-retried.
*/
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
const COMMAND_CODE_ERROR = /\bcommand[ -]?code API error\b/i
const COMMAND_CODE_PROVIDERS = new Set(["commandcode", "command-code", "commandcode-go"])
const HTTP_400 = /\b400\b/
const TRANSIENT_SIGNATURE = /invalid request error trace_id|"type"\s*:\s*"invalid_request_error"/i
// Already matches one of Pi's retryable patterns: leave the message untouched.
const ALREADY_RETRYABLE =
/server.?error|internal.?error|overloaded|rate.?limit|too many requests|\b(?:408|409|429|5\d\d)\b/i
const RETRY_MARKER =
" [transient Command Code gateway error; treated as server error, auto-retrying]"
export default function (pi: ExtensionAPI) {
pi.on("message_end", async (event, ctx) => {
const message = event.message
if (!message || message.role !== "assistant") return
if (message.stopReason !== "error") return
if (
!COMMAND_CODE_PROVIDERS.has(message.provider ?? "") &&
!COMMAND_CODE_PROVIDERS.has(ctx.model?.provider ?? "")
)
return
const errorMessage = message.errorMessage
if (typeof errorMessage !== "string" || errorMessage.length === 0) return
if (!COMMAND_CODE_ERROR.test(errorMessage) || !HTTP_400.test(errorMessage)) return
if (!TRANSIENT_SIGNATURE.test(errorMessage)) return
if (ALREADY_RETRYABLE.test(errorMessage) || errorMessage.includes(RETRY_MARKER)) return
return { message: { ...message, errorMessage: errorMessage + RETRY_MARKER } }
})
}
+32
View File
@@ -0,0 +1,32 @@
{
"name": "commandcode-pi",
"version": "0.1.0",
"description": "pi provider for the Command Code Go plan: registers DeepSeek models and streams over the CLI /alpha/generate transport",
"type": "module",
"keywords": [
"pi-package",
"pi-extension",
"commandcode",
"provider",
"deepseek"
],
"license": "MIT",
"repository": {
"type": "git",
"url": "git+ssh://git@git.cat-shark.xyz:2222/cat-shark/commandcode-pi.git"
},
"pi": {
"extensions": [
"./extensions/commandcode-go.ts",
"./extensions/commandcode-transient-retry.ts"
],
"changelogPath": "./CHANGELOG.md"
},
"peerDependencies": {
"@earendil-works/pi-ai": "*",
"@earendil-works/pi-coding-agent": "*"
},
"engines": {
"node": ">=20"
}
}