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,9 @@
|
||||
node_modules/
|
||||
package-lock.json
|
||||
|
||||
# 运行时缓存与凭据:由 pi / 扩展在 ~/.pi/agent 下生成,绝不入库
|
||||
*.log
|
||||
.env
|
||||
.env.*
|
||||
auth.json
|
||||
commandcode-go-catalog.json
|
||||
@@ -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 + 上游署名)。
|
||||
@@ -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.
|
||||
@@ -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)。
|
||||
@@ -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
@@ -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 } }
|
||||
})
|
||||
}
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user