# channels 插件与参考插件的三线对齐表

参考仓：`Ebony-Vinyl/dsh-our-free-model`（本地克隆
`/tmp/pi-github-repos/Ebony-Vinyl/dsh-our-free-model`），关键实现位于
`vendor/channel-pack/src/`（144 个 TS 文件）。

命名规律（照它逐厂商对齐的三条线）：

| 后缀 | 职责 | 我们要对齐的东西 |
|---|---|---|
| `X-auth.ts` / `X-oauth.ts` / `login.ts` | **登录** | 登录流程、端点、参数、凭据形状 |
| `X-product.ts` / `models.ts` | **模型获取** | 远端端点、解析路径、兜底表 |
| `X-adapter.ts` / `llm-adapter.ts` | **接入模型服务** | chat 端点、载荷转换、鉴权头 |

## 一、登录（line ①）

| 平台 | 参考流程 | 我们的 flow | 状态 |
|---|---|---|---|
| trae | OAuth 17 参数 + 设备身份派生 | callback | ✅ 逐字节对齐（含 login_trace_id / machine_id / x_device_*） |
| minimax | device-poll | device-poll | ✅ |
| cline | device-poll | device-poll | ✅ |
| buddy | state-poll（**无回调**） | state-poll | ✅ |
| gemini | OAuth + client_secret | callback | ✅（含 client_secret、localhost 主机、6 scope） |
| lobsterai | 本地回调 + authCode 换 token | callback | ✅（含动态版本号、3 步活动领取） |
| opencode | paste | paste | ✅（参考本身即粘贴凭据） |
| **codearts** | **PKCE + DPoP ES256 + STS 换 AK/SK** | **callback** | ✅ **本轮修复**（此前误标 paste） |
| qoder | device-poll + 设备身份 | device-poll | ✅（含 Cosy-MachineToken/Type 成对） |
| zcode | init-poll | init-poll | ✅ |
| loomy | 微信扫码 poll | wechat-poll | ✅ |
| raccoon | 二维码 poll | qr-poll | ✅ |

### codearts 登录（本轮修复的重点）

此前标成 `flow="paste"`（手填凭据）是**错的**。参考 `login.ts` / `oauth.ts`
默认走**新式 IAM OAuth**：

1. 起本地回调服务器，端口须 **≥10000**（`MIN_CALLBACK_PORT`，低于此 portal 拒绝），
   路径 `/oauth/callback`
2. 打开 `https://codearts.huaweicloud.com/portal/authorize`，参数逐项：
   `theme=2`、`locale=zh-cn`、`uri_scheme=codearts-agent`、`client_id=codearts-agent`、
   `code_challenge_method=**SHA-256**`（不是 RFC 的 S256 —— 错值会让 portal
   **回退旧 ticket 流程**，看起来"也能用"但不是 OAuth）、`ticket_id`、
   `plugin-name=snap_AIIDE`、`plugin-version=5.2.0`；
   **不得**含 `auth_callback_url`（会被判异常并回退）
3. 回调收到 `code` 后，带 **DPoP 证明**向
   `https://sts.cn-north-4.myhuaweicloud.com/v1/oauth2/tokens` 换
   `credentials{access_key_id, secret_access_key, security_token, expiration}`
   + `refresh_token`
4. 凭据持久化须含续期材料：`refresh_token` / `code_verifier` / `dpop_private_key_jwk`

DPoP 细节：ES256 JWS，`header={alg,typ:dpop+jwt,jwk}`、
`payload={htm,htu,iat,jti}`；**签名是 raw r||s 64 字节**，而 openssl 输出 DER
——必须转换格式，否则服务端验签失败而字符串看起来完全正常。

终态判定只认 `invalid_grant` / `ErrorCode 含 ExpiredRefreshToken`；
**不认** `InvalidDPoPHeader`（那是一次请求层面的拒绝：时钟偏差、proof 重放、
网关抖动都会触发，当终态会把完好账号一步标死）。

旧 ticket 流程（`CODEARTS_LOGIN_BASE` + `/snap-manager/v1/login/ticket` 轮询）
保留作回退。

## 二、模型获取（line ②）

远端优先、兜底补位的机制已具备（`models_remote` + `effectiveModels`）。
本轮把**兜底表**逐平台补成参考全量：

| 平台 | 参考来源 | 兜底数 | 状态 |
|---|---|---|---|
| trae | `TRAE_FALLBACK_MODELS` | 28 可见 + 4 hidden | ✅（hidden 单列 `models_hidden`） |
| minimax | `GET /mavis/api/v1/models?region=cn&buildEnv=prod` | 4 | ✅ |
| cline | `GET /api/v1/models` + `recommended-models` | 3 | ✅ |
| buddy | （无独立表） | 7 | ✅ |
| gemini | — | 2 | ✅ |
| lobsterai | `GET /api/models/available`（**须带 model_flag**） | 19 | ✅ |
| opencode | `GET /v1/models` | 14 | ✅（含 `models_free`） |
| codearts | opengw `gateway/config` + `/v1/model/builtin` | 3 | ⚠️ 见下 |
| qoder | `/api/v2/model/list`（需 WASM 签名） | 19 | ✅（含 CN 独有 q37fmodel/gm51model） |
| zcode | `GET /api/v1/client/configs` | 2 | ✅ |
| loomy | `GET /api/v1/models`（取 `type==='chat'`） | 8 | ✅ |
| raccoon | 远端 + 兜底 | 6 | ✅ |

**trae 的 `isHidden` 语义**：`browser_use_subagent` / `explore_sub_agent_v13` /
`explore_sub_agent_v2` / `summary` 是内部子 agent，不进用户可选列表。
`model_list` 已按此过滤（`models_hidden`）。

**opencode 的 `isFree`**：参考明确标注 7 个模型匿名可用、其余需付费 key。
此前 `model_list` 把 `isFree` 硬编码为 false，等于把官方免费模型标成付费。

### codearts 模型获取（未闭环）

参考 `models.ts` 从两个端点拉：
- `OPENGW_GATEWAY_CONFIG_URL`（`opengw.developer.huaweicloud.com/api/v1/gateway/config`）
  → `result.models`，这是 **benefit（免费额度）模型**权威来源
- `SNAP_MODEL_BUILTIN_URL`（`/v1/model/builtin`）→ `builtinModels`，常规模型

两者都要 **AK/SK 的 SDK-HMAC-SHA256 签名**。另有 `normalizeModelId`
（去尾部 `-NNNN` 日期版本）与 `isCodeArtsBenefitModel`（决定 chat 是否带
`maas_type: benefit`，不带则 404 `model is not registered`）。
**这部分尚未实现**——我们的 codearts 目前只有 3 个硬编码模型名。

## 三、接入模型服务（line ③）

**本轮发现的最严重问题**：源注册时 `base_url + adapter.endpoint` 拼出的
chat URL **全部缺路径前缀**，11 个平台里 11 个都不对。已逐个修正：

| 平台 | 正确 chat 端点 | 修正前 |
|---|---|---|
| trae | `…/api/agent/v3/llm_utils_chat` | `…/chat/completions` |
| cline | `api.cline.bot/api/v1/chat/completions` | `api.cline.bot/chat/completions` |
| lobsterai | `…/api/proxy/v1/chat/completions` | `…/chat/completions` |
| qoder | `api2-v2.qoder.sh/model/v1/chat/completions` | `…/chat/completions` |
| buddy | `copilot.tencent.com/v2/chat/completions` | `…/chat/completions` |
| codearts | `…/api/v2/chat/completions` | `…/chat/completions` |
| opencode | `opencode.ai/zen/v1/chat/completions` | `opencode.ai/zen/chat/completions` |
| raccoon | `…/api/web/llm/v2/chat/completions` | `…/chat/completions` |
| loomy | `loomy.xunfei.cn/chat/completions` | `loomy.xunfei.cn` |
| zcode | `zcode.z.ai/api/v1/zcode-plan/anthropic/v1/messages` | `zcode.z.ai/v1/messages` |
| gemini | `/v1internal:generateContent`（私有动词） | `/v1beta/models/{model}:generateContent`（公开，凭据不匹配） |

### 未闭环：trae 的载荷转换

trae **不是 OpenAI 兼容**。参考 `trae.ts:30` 注释：
「载荷必须转换：OpenAI 的 `{model, messages, tools, tool_choice, stream}` 需要
映射为 SOLO 格式（`function`、`config_name` 等字段），不能透传」；
`model` 还要映射到 `config_name`（查远端模型列表）。

我们有一个 `internal/lua/adapters/trae.lua`，但它描述的是
`trae-local-api`（本地 OpenAI 兼容代理，`127.0.0.1:19900`），**不做** SOLO
转换（`grep config_name` = 0 命中），且平台声明用的是 `adapter = "openai"`。
所以 trae 的**端点现在对了，载荷仍然错**。这是一块独立性工作。

### 未闭环：gemini 的私有协议信封

端点是 `/v1internal:` 了，但参考 `gemini.ts` 还有三件必须保留的细节：
1. **身份五头逐字写死、不许随机**（且**不带** `x-goog-api-key` / `x-goog-api-client`）
2. **流式请求刻意不带 `Accept` 头**
3. **信封逐层字母序序列化**（Go 的 `encoding/json` 对 map 自动字母序，TS 的
   `JSON.stringify` 按插入序 —— 不排序字节就与上游不同）

## 四、明确不做的（附理由）

| 参考模块 | 行数 | 为什么不做 |
|---|---|---|
| `gemini-sigstore.ts` | 268 | 我们推理走无状态适配器，插件不参与推理 → 插件侧缓存会成为死代码 ⛔ |
| `qoder-wasm.ts` | 1442 | 需随插件分发 298KB wasm 二进制；B 类，待立项 |
| `zcode-captcha.ts` | 2212 | 阿里云滑块，需真实浏览器/验证码链路；B 类 |
| `captcha-*.ts` | 1223 | 同上 |

## 五、本机实测踩到的坑（都已修）

1. **`xxd` 不存在** —— `command -v xxd` 为空，用它取十六进制会**静默得到空串**。
   改用 `od -An -tx1`。
2. **`openssl ec -text` 会截断 32 字节 priv**（实测只给 30 字节）→ `d` 必须用
   `openssl asn1parse` 的 `[HEX DUMP]`；`tail -c 32` 拿到的是 SEC1 结构里
   **公钥的 y**，不是 `d`。
3. **Lua local 前向引用**：`local function` 只从定义处向后可见。`hexToBin` /
   `b64url` / `b64urlRaw` 被 CodeArts 的 PKCE/DPoP 调用，必须移到 CodeArts 块
   **之前**（本文件累计踩过 6 次）。
4. **`min_port` 参数读到 `argv[2]`** 与 `out_path` 冲突 —— 回调脚本的第 5 个
   参数才是 minPort。
5. **Lua 双引号串里的 `\1`** 是转义坑（`sed 's/…/…/\1/'` 会报
   invalid escape sequence）→ 改用 `awk -F': ' '{print $NF}'`。