@armadra/agent 0.3.0 → 0.5.0

package/docs/providers.md

@@ -5,7 +5,7 @@
 ## 配置目录
 
 缺省 `~/.config/ama/`（Windows `%APPDATA%\ama\`；`AMA_CONFIG_DIR` 优先，其次 `XDG_CONFIG_HOME/ama`）。数据
-（会话、models.dev 缓存）在另一个目录：`~/.local/share/ama/`（`AMA_DATA_DIR` / `XDG_DATA_HOME`）。
+（会话、models.dev 刷新覆盖）在另一个目录：`~/.local/share/ama/`（`AMA_DATA_DIR` / `XDG_DATA_HOME`）。
 
 ```
 ~/.config/ama/                 0700
@@ -17,28 +17,28 @@
 └── skills/ prompts/           （按需）
 ~/.local/share/ama/
 ├── sessions/                  会话
-└── models-dev.json            models.dev 元数据缓存
+└── models-dev.json            models.dev 刷新覆盖（只有 ama models refresh 写）
 ```
 
 - `ama init`：建目录（0700）并补齐缺失的 `config.json` 与 `config.schema.json`，逐个打印「已创建」或
   「已存在，未改动」；已存在的 `config.json` 一律不覆盖（`--force` 也不），`config.schema.json` 不是用户文件，
   每次 `init` 都重写为当前版本；不创建空的 `auth.json`。
-- **首次运行自动初始化**：CLI 启动时若配置目录不存在，静默建目录并写最小 `config.json` 与 schema
-  （`AMA_NO_INIT=1` 关闭；SDK 与测试不触发）。
+- **首次运行自动初始化**：进入对话的命令（交互、`-p`、`--mode rpc`）与 `ama providers add` 启动时若配置目录不存在，
+  静默建目录并写最小 `config.json` 与 schema（`AMA_NO_INIT=1` 关闭；SDK 与测试不触发）。只读子命令（`config show` /
+  `path`、`doctor`、`models list`、`providers list`、`auth list`、`sessions` 等）不创建也不改写配置目录。
 - 最小 `config.json`：
 
   ```json
   {
     "$schema": "./config.schema.json",
     "version": 1,
-    "thinkingLevel": "medium",
-    "permission": { "mode": "default" },
-    "tools": { "preset": "default" },
     "providers": {}
   }
   ```
 
-  不写 `defaultModel`（零配置按「第一个有 key / 本地可达的供应商」挑选）。
+  不写任何缺省值（缺省值调整时老配置同样生效，`ama config show` 里来源也显示 default），也不写
+  `defaultModel`（见下文「缺省模型」）。`ama init` 结束时打印下一步（`ama auth set` / `ama providers add` /
+  `ama doctor`）。`config.schema.json` 里每个键都带说明与缺省值（运行时决定的键只写规则），编辑器悬停可见。
 
 - `ama config path`：打印配置目录、数据目录与各文件路径（标出是否存在）；`ama config edit`：用
   `$VISUAL` / `$EDITOR` 打开 `config.json`（不存在先 `init`），没有编辑器时打印路径。
@@ -75,26 +75,89 @@
 
 ## 内置供应商
 
-| id           | 协议                                            | baseUrl                                             | API Key 环境变量（顺序）                                     |
-| ------------ | ----------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------ |
-| `anthropic`  | anthropic-messages                              | `https://api.anthropic.com`                         | `ANTHROPIC_API_KEY`、`AMA_API_KEY_ANTHROPIC`                 |
-| `openai`     | openai-completions（推理模型 openai-responses） | `https://api.openai.com/v1`                         | `OPENAI_API_KEY`、`AMA_API_KEY_OPENAI`                       |
-| `google`     | google-generative-ai                            | `https://generativelanguage.googleapis.com/v1beta`  | `GEMINI_API_KEY`、`GOOGLE_API_KEY`、`AMA_API_KEY_GOOGLE`     |
-| `deepseek`   | openai-completions                              | `https://api.deepseek.com`                          | `DEEPSEEK_API_KEY`、`AMA_API_KEY_DEEPSEEK`                   |
-| `moonshot`   | openai-completions                              | `https://api.moonshot.cn/v1`                        | `MOONSHOT_API_KEY`、`KIMI_API_KEY`、`AMA_API_KEY_MOONSHOT`   |
-| `zhipu`      | openai-completions                              | `https://open.bigmodel.cn/api/paas/v4`              | `ZHIPU_API_KEY`、`ZAI_API_KEY`、`AMA_API_KEY_ZHIPU`          |
-| `dashscope`  | openai-completions                              | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `DASHSCOPE_API_KEY`、`QWEN_API_KEY`、`AMA_API_KEY_DASHSCOPE` |
-| `openrouter` | openai-completions                              | `https://openrouter.ai/api/v1`                      | `OPENROUTER_API_KEY`、`AMA_API_KEY_OPENROUTER`               |
-| `groq`       | openai-completions                              | `https://api.groq.com/openai/v1`                    | `GROQ_API_KEY`、`AMA_API_KEY_GROQ`                           |
-| `xai`        | openai-completions（目录模型 openai-responses） | `https://api.x.ai/v1`                               | `XAI_API_KEY`、`AMA_API_KEY_XAI`                             |
-| `mistral`    | openai-completions                              | `https://api.mistral.ai/v1`                         | `MISTRAL_API_KEY`、`AMA_API_KEY_MISTRAL`                     |
-| `ollama`     | openai-completions                              | `http://127.0.0.1:11434/v1`                         | 可无（`OLLAMA_API_KEY`）                                     |
-| `lmstudio`   | openai-completions                              | `http://127.0.0.1:1234/v1`                          | 可无                                                         |
+| id           | 渠道（**粗体**为缺省）                                                                | 缺省地址                                           | API Key 环境变量（顺序）                                      |
+| ------------ | ------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------- |
+| `anthropic`  | 单渠道 messages                                                                       | `https://api.anthropic.com`                        | `ANTHROPIC_API_KEY`、`AMA_API_KEY_ANTHROPIC`                  |
+| `openai`     | **responses**、chat                                                                   | `https://api.openai.com/v1`                        | `OPENAI_API_KEY`、`AMA_API_KEY_OPENAI`                        |
+| `google`     | 单渠道 gemini                                                                         | `https://generativelanguage.googleapis.com/v1beta` | `GEMINI_API_KEY`、`GOOGLE_API_KEY`、`AMA_API_KEY_GOOGLE`      |
+| `deepseek`   | **chat**、messages（`/anthropic`）                                                    | `https://api.deepseek.com`                         | `DEEPSEEK_API_KEY`、`AMA_API_KEY_DEEPSEEK`                    |
+| `moonshot`   | **chat**、messages、responses、chat-intl、messages-intl（`.ai`）                      | `https://api.moonshot.cn/v1`                       | `MOONSHOT_API_KEY`、`KIMI_API_KEY`、`AMA_API_KEY_MOONSHOT`    |
+| `zhipu`      | **chat**、messages（`/api/anthropic`）、chat-intl、messages-intl（`api.z.ai`）        | `https://open.bigmodel.cn/api/paas/v4`             | `ZHIPU_API_KEY`、`ZAI_API_KEY`、`AMA_API_KEY_ZHIPU`           |
+| `dashscope`  | **messages**（`/apps/anthropic`）、responses、chat、messages-intl、chat-intl          | `https://dashscope.aliyuncs.com/apps/anthropic`    | `DASHSCOPE_API_KEY`、`QWEN_API_KEY`、`AMA_API_KEY_DASHSCOPE`  |
+| `openrouter` | 单渠道 chat                                                                           | `https://openrouter.ai/api/v1`                     | `OPENROUTER_API_KEY`、`AMA_API_KEY_OPENROUTER`                |
+| `groq`       | 单渠道 chat                                                                           | `https://api.groq.com/openai/v1`                   | `GROQ_API_KEY`、`AMA_API_KEY_GROQ`                            |
+| `xai`        | **responses**、chat                                                                   | `https://api.x.ai/v1`                              | `XAI_API_KEY`、`AMA_API_KEY_XAI`                              |
+| `mistral`    | 单渠道 chat                                                                           | `https://api.mistral.ai/v1`                        | `MISTRAL_API_KEY`、`AMA_API_KEY_MISTRAL`                      |
+| `minimax`    | **messages**、responses（只 M3）、chat、messages-intl、chat-intl（`api.minimax.io`）  | `https://api.minimax.cn/anthropic`                 | `MINIMAX_API_KEY`、`AMA_API_KEY_MINIMAX`                      |
+| `stepfun`    | **messages**、chat、responses（只 step-5-preview）、messages-intl、chat-intl（`.ai`） | `https://api.stepfun.com`                          | `STEPFUN_API_KEY`、`STEP_API_KEY`、`AMA_API_KEY_STEPFUN`      |
+| `volcengine` | **responses**、chat                                                                   | `https://ark.cn-beijing.volces.com/api/v3`         | `ARK_API_KEY`、`VOLCENGINE_API_KEY`、`AMA_API_KEY_VOLCENGINE` |
+| `tencent`    | **messages**、chat（`/v1`）                                                           | `https://tokenhub.tencentmaas.com`                 | `TOKENHUB_API_KEY`、`HUNYUAN_API_KEY`、`AMA_API_KEY_TENCENT`  |
+| `ollama`     | 单渠道 chat                                                                           | `http://127.0.0.1:11434/v1`                        | 可无（`OLLAMA_API_KEY`）                                      |
+| `lmstudio`   | 单渠道 chat                                                                           | `http://127.0.0.1:1234/v1`                         | 可无                                                          |
 
 另有测试用供应商 `fake`（模型 `fake/echo`、`fake/reasoning`），见下文。
 
-协议列是供应商级缺省；目录条目可以用 `api` 覆盖（openai 的推理模型与 xai 的目录模型走
-`openai-responses`，非推理的 `gpt-4.1`、`gpt-4o*` 仍走 Completions）。
+**缺省协议**：Messages / Responses 优先、Chat 回落。能执行显式缓存的 Messages 端点（通义、MiniMax M2.x、腾讯）与
+官方推荐 Messages 的阶跃缺省 messages；OpenAI、xAI、火山方舟缺省 responses；DeepSeek、智谱、Kimi 只有隐式缓存，
+**缺省保持 chat，直到官方直连过了实测门**（见「渠道实测」）再改，切换只是 `builtin.ts` 里一行 `defaultChannel`。
+
+**内置渠道**（与用户的[渠道](#渠道channels一个供应商多种接口)同一机制）：
+
+- `provider/model@channel` 选渠道，例如 `deepseek/deepseek-v4-pro@messages`、`dashscope/qwen3.8-max@chat-intl`；
+  目录模型缺省挂全部渠道，目录可按模型限定（MiniMax M2.x、阶跃 step-3.x 没有 responses）。
+- 改缺省：`"providers": { "deepseek": { "defaultChannel": "messages" } }`；或只写协议
+  `"api": "anthropic-messages"`，选同协议的内置渠道。
+- 改某个渠道：`channels.<内置渠道名>` 只写要改的字段（`headers` / `compat` 合并一层，其余覆盖）；新名字的渠道追加
+  在后，目录模型同样可用。
+- **改了供应商级 `baseUrl`**（config、auth.json 或 `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL`）而没写自己的
+  `channels` 时，内置渠道作废，按「供应商级 `api` + 新 `baseUrl`」单渠道处理，与引入内置渠道之前一致：回落协议是
+  Chat（`api` 可改）；OpenAI / xAI / 火山方舟的**目录模型**在中转上仍走 Responses，目录外的 id（本地服务、中转
+  自有模型）走 Chat。落在任一内置渠道主机上（如国际站）不算中转。
+- 鉴权头按渠道：Anthropic 兼容端点缺省 `x-api-key`，Kimi、MiniMax、阶跃的 Messages 渠道按其文档用
+  `Authorization: Bearer`。
+
+### Coding Plan 类订阅端点
+
+火山方舟、阿里百炼、智谱、Kimi、MiniMax、阶跃等的 Coding Plan / Token Plan 额度只限编程工具使用，`ama -p` 与 RPC
+嵌入属于自动化调用，有被判违规的风险，因此**不做内置渠道**。确认条款允许后可自行加渠道（key 写在渠道上）：
+
+```json
+{
+  "providers": {
+    "volcengine": {
+      "channels": {
+        "coding": {
+          "api": "anthropic-messages",
+          "baseUrl": "https://ark.cn-beijing.volces.com/api/coding",
+          "apiKey": "$ARK_CODING_PLAN_KEY"
+        }
+      }
+    },
+    "zhipu": {
+      "channels": {
+        "coding": {
+          "api": "openai-completions",
+          "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
+          "apiKey": "$ZHIPU_CODING_PLAN_KEY"
+        }
+      }
+    },
+    "stepfun": {
+      "channels": {
+        "plan": {
+          "api": "anthropic-messages",
+          "baseUrl": "https://api.stepfun.com/step_plan",
+          "apiKey": "$STEP_PLAN_KEY",
+          "authHeader": "authorization-bearer"
+        }
+      }
+    }
+  }
+}
+```
+
+然后 `--model volcengine/<模型>@coding`（订阅端点的模型 id 以各家文档为准，目录外的 id 用 `models[]` 补上并写
+`"channels": ["coding"]`）。
 
 ## 模型引用
 
@@ -164,9 +227,10 @@ export PACKY_API_KEY=sk-...
   Messages 在 baseUrl 以 `/v1` 结尾时拼 `/messages`，否则 `/v1/messages`。
 - 不想手写 `models`：`ama models discover packy` 列出中转站的模型（`GET {baseUrl}/models`）；
   `--probe` 对每个模型依次试供应商协议、completions、responses、messages 的最小请求，记第一个成功
-  的（每模型最多 3 次，`--limit` 限制探测的模型数，缺省 30，执行前打印预估，401 / 403 / 429 即停）；
+  的（每模型最多 3 次，`--limit` 限制探测的模型数，缺省 30，执行前打印预估；模型之间并发，探测规则同下文
+  `providers add --probe`）；
   `--write` 把结果合并进用户级 `config.json`（已有同 id 不覆盖，只写 `id` 与和供应商不同的 `api`，
-  原文件备份为 `config.json.bak`）。上下文等元数据在运行时从 models.dev 缓存补（见下文「模型元数据」），
+  原文件备份为 `config.json.bak`）。上下文等元数据在运行时从 models.dev 快照补（见下文「模型元数据」），
   匹配不到的条目没有 `contextWindow`，自动压缩随之关闭，需要时手动补。
 
 ```sh
@@ -180,6 +244,19 @@ Claude Code 的通行约定），优先级低于 config 与 auth.json 的 `baseU
 `prompt_cache_key`）。`ama config show` 的「供应商」节与 `ama doctor` 标出 baseUrl 来自哪个变量；
 零配置挑的缺省模型来自官方目录，中转站未必有，用 `--model` 或 `defaultModel` 指定。
 
+### 缺省模型
+
+没有 `--model`、续会话的模型与 `defaultModel` 时，按供应商顺序（内置在前，config 里的自定义供应商在后）取第一个
+有 key（或本地服务可达）的供应商，再在它的模型里挑：
+
+- **内置供应商**：目录首条（目录按推荐顺序整理）；
+- **自定义供应商**（中转站，模型表是上游 `/models` 的顺序）：在 models.dev 有价格（输入价 > 0）、支持工具调用、
+  上下文 ≥ 64k 的模型里取**输入价最低**的；同价取上下文大的，再同取列表靠前的；一个都不满足才退回列表首条。
+
+`ama providers add` 在还没有 `defaultModel` 时按同一规则挑一个写进 `defaultModel`（探测过只在探测通过的模型里
+挑），摘要里写明选了谁、为什么；已有 `defaultModel` 不改。`ama config show` 与 `ama doctor` 的「模型」一行同样
+说明原因。没有任何可用模型时，启动提示列出 key 的环境变量名、`ama auth set` 与 `ama providers add`。
+
 ```sh
 OPENAI_BASE_URL=https://proxy.example/v1 OPENAI_API_KEY=$PACKY_API_KEY ama -p "hi" --model openai/qwen3.8-flash
 ```
@@ -221,7 +298,7 @@ Anthropic Messages（`/v1/messages`），且每个模型只在其中一部分接
 - **模型引用**：`provider/model` 走首选渠道；`provider/model@channel` 显式指定（`--model`、`defaultModel`、
   `/model`、SDK、RPC `set_model` 一致）。指定的渠道不在该模型的 `channels` 里 → 报错并列出可用的
   `provider/model@channel`。`@` 之后不是该供应商的渠道名时整串仍按模型 id 处理（兼容 id 里本来带 `@` 的模型）。
-- **向后兼容**：没有 `channels` 的供应商（含全部内置供应商）按单渠道处理——供应商级 `api` + `baseUrl`
+- **向后兼容**：没有 `channels` 的供应商（自定义供应商与单协议的内置供应商；多协议内置供应商的内置渠道见「内置供应商」）按单渠道处理——供应商级 `api` + `baseUrl`
   就是隐式的 `default` 渠道；模型级 `api` / `baseUrl` 仍然有效，覆盖在所选渠道之上（等价于一个匿名渠道）。
   已有配置不用改。写了 `channels` 时供应商级 `api` / `baseUrl` 不再单独成渠道。
 - **运行时**：选中的模型带上该渠道的协议、地址、key、headers 与 compat；会话记录（`model_change`）与
@@ -239,7 +316,8 @@ ama providers add packy --base-url https://www.packyapi.com/v1 --key-env PACKY_A
 ```
 ama providers add <id> --base-url <url> [--channel <name>=<api>@<baseUrl> …] [--api <api>|auto]
                        [--key-env <VAR>] [--probe] [--limit N] [--probe-models a,b,…]
-                       [--max-requests N] [--prefer chat,responses,messages] [--include-no-tools] [--yes]
+                       [--max-requests N] [--concurrency N] [--probe-timeout ms]
+                       [--prefer chat,responses,messages] [--include-no-tools] [--yes]
 ama providers list
 ama providers channels <id>
 ama providers remove <id>
@@ -258,10 +336,16 @@ ama providers refresh <id> [--probe …]
 - **`--probe`**：对选中的模型（`--probe-models` 列出的，缺省按 id 字母序不分大小写取前 `--limit` 个，缺省 30）
   逐个渠道发一次最小请求（有提示时只试提示里的渠道），**探测成功的渠道全部写进模型的 `channels`**，顺序按
   `--prefer`（缺省 chat、responses、messages）；全部失败的模型不写入；未探测的按提示写入并在表格里标「未探测」。
-  执行前打印请求数预估，超过 `--max-requests`（缺省 60）时截断模型数；401 / 403 / 429 立即停止。
+  执行前打印请求数与耗时预估，超过 `--max-requests`（缺省 60）时截断模型数。
+  - **判定**：HTTP 成功且流里出现第一个内容事件（文本 / 思考 / 工具调用）即判可用并立刻断开，不等推理模型
+    想完；只收到流开头、还没有内容时再等 1 s，期间没有报错也判可用（防止中转先回 200 再在流里报错被误判）。
+    HTTP 错误、流里的错误、超时（`--probe-timeout`，缺省 15000 ms）判不可用并记原因。
+  - **并发**：「模型 × 渠道」同时在途最多 `--concurrency` 个（1–16，缺省 6）；结果按模型、渠道顺序打印，
+    终端里单行刷新「探测 18/60」，最后打印总用时。
+  - **限流**：401 / 403 立即停止；429 时并发减半、2 s 后重试该请求一次，重试仍 429 则停止。
 - **渠道收敛**：写入前删掉没有任何模型挂载的候选渠道；`defaultChannel` 取剩下的第一个（按 `--prefer`）。
 - **写入**：用户级 `config.json` 的 `providers.<id>`（先备份为 `config.json.bak`）。模型条目只写 `id` 与
-  `channels`；上下文、输出、图像、推理、价格**不写进配置**，运行时从 models.dev 缓存补（见下节），所以
+  `channels`；上下文、输出、图像、推理、价格**不写进配置**，运行时从 models.dev 快照补（见下节），所以
   `refresh` 不会覆盖手改的字段，手写的值永远优先。models.dev 标明不支持工具调用的模型缺省不写入（Agent
   离不开工具调用），`--include-no-tools` 照写。对已存在的供应商再执行 `add`：只追加新渠道与新模型，已有
   渠道定义与模型条目一字不改。
@@ -270,8 +354,8 @@ ama providers refresh <id> [--probe …]
   中转实际价格可能不同）、匹配方式。
 - `list`：全部供应商（config.json 里的与有 key 的内置供应商）→ 渠道（协议、地址、key 来源：auth.json /
   `$VAR` / 字面量 / 无，从不显示 key）→ 模型数。`channels <id>`：每个渠道的协议、地址与挂载的模型数。
-  `remove`：删 `providers.<id>`（备份）与 auth.json 里该供应商的条目。`refresh`：重拉 `/models` 与
-  models.dev，只追加新模型（带 `--probe` 时同 add 的探测），已有条目不改；上游已下架的 id 只提示、不删。
+  `remove`：删 `providers.<id>`（备份）与 auth.json 里该供应商的条目。`refresh`：重拉 `/models`（models.dev
+  用本地快照），只追加新模型（带 `--probe` 时同 add 的探测），已有条目不改；上游已下架的 id 只提示、不删。
 
 实测（2026-10-02，一家同时提供三种接口的中转，22 个模型，共 29 次请求）：
 
@@ -287,43 +371,86 @@ ama providers refresh <id> [--probe …]
 
 ### 模型元数据：models.dev
 
-[models.dev](https://models.dev) 汇总了两百多家供应商的模型参数（`https://models.dev/api.json`，约 5 MB）。
-ama 用它给**没写元数据**的自定义模型补上下文、输出上限、输入模态、推理、价格与工具调用能力。
-
-- **何时联网**：只有 `ama providers add|refresh`、`ama models discover`、`ama models refresh-catalog`
-  会拉取；**启动不联网**，只读缓存。缓存在数据目录 `models-dev.json`（缺省 `~/.local/share/ama/`，只留用到的
-  字段，约 2.3 MB），记获取时间与 ETag，24 小时内不重拉（`refresh-catalog` 强制，带 `If-None-Match`）。离线或
-  失败时用旧缓存并 warning。`AMA_MODELS_DEV_URL` 换数据源（镜像或本地文件服务）。
-- **优先级**：用户配置（`models[]` / `modelOverrides[]` 里写了的字段）> 内置目录 > models.dev > 自定义缺省
-  （`maxTokens: 8192`、`input: ["text"]`、`reasoning: false`、不猜 `contextWindow`）。`ama models list` 与
-  `ama config show` 标出每个字段来自哪里（`config` / `目录` / `models.dev` / `缺省`）。
-- **字段映射**：`contextWindow = limit.context`；`maxTokens = min(limit.output, 65536, contextWindow)`——
+[models.dev](https://models.dev) 汇总了两百多家供应商的模型参数（`https://models.dev/api.json`，约 5 MB，MIT 许可，
+声明见仓库根的 `THIRD_PARTY_NOTICES.md`）。ama 把主流厂商的一份**裁剪快照随包携带**，用它给内置目录与自定义模型
+补上下文、输出上限、输入模态、推理、价格等数值事实。**启动与运行都不联网**。
+
+- **快照**：`src/ai/providers/models-dev/<provider>.json`，一家一份，收录清单在同目录 `_providers.json`（22 家：
+  anthropic、openai、google、xai、deepseek、moonshotai / moonshotai-cn、zhipuai / zai、alibaba / alibaba-cn、
+  minimax / minimax-cn、stepfun / stepfun-ai、volcengine、tencent-tokenhub、mistral、meta、xiaomi、groq，以及
+  openrouter 里原厂前缀白名单内的模型）。`scripts/update-models-dev.mjs`（零依赖）拉取、过滤（丢 `deprecated`、
+  输出不含文本、上下文为 0、`tool_call: false` 的条目）、裁剪字段（name、family、knowledge、release_date、
+  reasoning、modalities.input、limit.context / input / output、cost 含 `context_over_200k` 与按上下文的 `tiers`、
+  interleaved、beta 状态、canonical_model_id）并按键排序写出，再生成内联进 bundle 的 `models-dev-data.ts`；内容
+  不变时字节不变（`_meta.json` 的 `fetchedAt` 只随 sha256 变）。为控制体积（内联数据 ≤ 200 KB，测试守住）不收
+  `last_updated`、`reasoning_options`。
+- **每周刷新**：`.github/workflows/models-dev.yml` 每周一 03:17 UTC（与手动 `workflow_dispatch`）跑脚本，自动删掉
+  目录里与新快照相同的覆盖项，有改动才往固定分支 `chore/models-dev-refresh` 开 / 更新 PR（摘要列新增、删除、上下文 /
+  输出 / 价格变化；删除超过 30% 加 `needs-review`）。PR 用仓库 secret `MODELS_DEV_PR_TOKEN`（GitHub App token 或
+  fine-grained PAT，`contents` + `pull-requests` 写权限）创建以触发 CI；没有这个 secret 时 workflow 先自己跑
+  `pnpm run ci`，再用缺省 token 开 PR 并在描述里写明结果。合并由人做。
+- **`ama models refresh [--provider <id>[,<id>…]]`**：显式联网拉最新 `api.json`，按同一清单裁剪，写到数据目录
+  `models-dev.json`（缺省 `~/.local/share/ama/`），打印新增 / 上游删除 / 变价。之后的索引 = 内置快照 ⊕ 这份覆盖：
+  覆盖文件的 `fetchedAt` 晚于快照才叠加（升级 ama 带来更新的快照后旧覆盖自动失效），同一 `provider/model` 以覆盖
+  为准，上游删掉的条目沿用快照。`refresh-catalog` 是旧名。`AMA_MODELS_DEV_URL` 换刷新的数据源。旧版 ama 写的全量
+  缓存（version 1）不再读取。`ama providers add|refresh` 与 `ama models discover` 只用本地索引，不再拉 models.dev
+  （它们对 `/models` 的请求照旧）。
+- **内置目录（`catalog/*.json`）只写覆盖项**：文件级 `"modelsDev": "<快照供应商 id>"`（本地服务写 `false`）；条目
+  按 `<modelsDev>/<id>` 从快照继承 name、reasoning、contextWindow、maxTokens、input、cost、family、knowledge、
+  releaseDate、inputLimit、status，目录只写 ama 特有字段（`api`、`thinkingLevelMap`、`promptCache`、`compat`）与
+  有意不同于快照的值（如 openai 的 272k 窗口、deepseek 的价格）；`cost` 可只写要改的键。id 与快照不同时条目写
+  `"modelsDev": "provider/model"`，不继承写 `false`。快照里没有的模型（已 deprecated 等）写完整条目。
+  `catalog.test.ts` 把与快照取值相同的字段当冗余报错，`UPDATE_CATALOG=1 pnpm vitest run
+src/ai/providers/catalog.test.ts` 自动删除并重新生成 `catalog-data.ts`（之后跑 prettier）；确实要钉住与快照相同的
+  值时在条目上写 `"_reason": "…"`（注释，运行时忽略，该条目不做冗余检查）。目录继承的映射与自定义模型略有不同：
+  `maxTokens` 不封顶（取 `min(limit.output, contextWindow)`），缺的缓存价记 0。
+- **优先级**：用户配置（`models[]` / `modelOverrides[]` 里写了的字段）> 内置目录（快照 ⊕ 目录覆盖）> models.dev
+  索引 > 自定义缺省（`maxTokens: 8192`、`input: ["text"]`、`reasoning: false`、不猜 `contextWindow`）。
+  `ama models list` 与 `ama config show` 标出每个字段来自哪里（`config` / `目录` / `models.dev` / `缺省`；内置目录
+  从快照继承的字段标 `models.dev`）。
+- **字段映射**（自定义模型）：`contextWindow = limit.context`；`maxTokens = min(limit.output, 65536, contextWindow)`——
   `maxTokens` 每次请求都作为 `max_tokens` 发出，models.dev 给的是原厂上限（不少模型写的是与上下文相同的
   1M），中转换了上游后常拒收超大值，Anthropic 协议的思考预算也从它推导，64k 对编码 Agent 的单轮输出足够，
   需要更大时在配置里写；`input` 由 `modalities.input` 含不含 `image` 定为 `["text","image"]` 或 `["text"]`；
   `reasoning`；`cost` 取 `input` / `output` / `cache_read` / `cache_write`（$/M），缺缓存价时按输入价算
-  （不假设有折扣，保温的经济性判断因此偏保守）。
-- **匹配规则**（同一个 id 常在几十家转售商下重复出现，取值不一）：
+  （不假设有折扣，保温的经济性判断因此偏保守）；`cost.tiers` 取 models.dev 的按上下文档位，只有
+  `context_over_200k` 时折成 200k 一档；另补 `family`、`knowledge`、`releaseDate`、`inputLimit`（与上下文不同时）、
+  `status: "beta"`。
+- **匹配规则**（同一个 id 常在多家转售商下重复出现，取值不一）：
   1. 模型上写了 `"modelsDev": "provider/model"` → 直接用该条目（写 `false` 关闭补全）；
-  2. id 形如 `vendor/model` 且 models.dev 正好有这个 `provider/model` → 用它；
+  2. id 形如 `vendor/model` 且索引里正好有这个 `provider/model` → 用它；
   3. 按 id 不分大小写找全部同名条目；有 `canonical_model_id` 的，取指向与 id 同名的那个（否则取票数最多的），
      它若能在原厂供应商下找到 → 用原厂条目；
   4. 否则在（同一 canonical 的）条目里优先原厂供应商：anthropic、openai、google、deepseek、moonshotai(-cn)、
-     zhipuai、zai、alibaba(-cn)、xai、mistral、minimax(-cn)、llama（Meta）、cohere、xiaomi、stepfun 等
-     （models.dev 里没有 `qwen` / `meta` 这样的供应商 id，通义在 `alibaba`，Llama 在 `llama`）；
+     zhipuai、zai、alibaba(-cn)、xai、mistral、minimax(-cn)、meta、llama、cohere、xiaomi、stepfun(-ai)、volcengine、
+     tencent-tokenhub 等（models.dev 里没有 `qwen` 这样的供应商 id，通义在 `alibaba`）；
   5. 仍有多条 → 按 (上下文, 输出, 图像) 取多数，取值不一时记 warning；只有一条就用它；
   6. 同名找不到时依次试归一化后的 id：去 `vendor/` 前缀、去 `:free` 一类后缀、去 `-latest`、去日期后缀
      （`-0902`、`-20250514`、`-2025-05-14`）；
-  7. 都没有 → 「未匹配」，保持自定义缺省（不猜 `contextWindow`，自动压缩关闭）。
+  7. 都没有 → 「未匹配」，保持自定义缺省（不猜 `contextWindow`，自动压缩关闭）。快照只收主流厂商，转售商专有的
+     id 可能匹配不到，可在模型上写 `modelsDev` 指向收录的条目。
 
 ### 图像输入
 
 - 四条协议都把图片放进用户消息：Chat Completions `image_url`（data URL）、Responses `input_image`、
   Anthropic `image`（base64 source）、Gemini `inlineData`；工具结果里的图片同样映射。
 - 入口：`ama -p "描述这张图" --image a.png --image b.jpg`；交互界面与行式界面里写 `@图片路径`，或粘贴 /
-  拖入一个图片文件路径（整段输入里以 `.png` / `.jpg` / `.jpeg` / `.gif` / `.webp` 结尾且文件存在的词）。
-- 与 `read` 工具共用 MIME 检测（按文件头识别 PNG / JPEG / GIF / WebP，扩展名不符时以文件头为准）与大小上限
-  （单张 5 MB，取各家上限中最小的 Anthropic）。
+  拖入一个图片文件路径（整段输入里以 `.png` / `.jpg` / `.jpeg` / `.gif` / `.webp` 结尾且文件存在的词）；交互界面里
+  `Ctrl+V` 或 `/paste` 把剪贴板里的图片存成文件并在光标处插入 `@<路径>`（见下文「剪贴板图片」与 [tui.md](tui.md)「剪贴板图片」）。
+  `--image`、`@图片` 与粘贴的图片都按 `images.resize` 缩放。
+- 与 `read` 工具共用 MIME 检测（按文件头识别 PNG / JPEG / GIF / WebP，扩展名不符时以文件头为准）与大小上限。
+  上限按 **base64 后**计算（`ceil(字节/3)*4`），按当前模型的端点分档：官方 Anthropic（`api.anthropic.com`）
+  10 MB、官方 Gemini 与 OpenAI 20 MB，中转（内置供应商改了 baseUrl）与其它主机 5 MB；任一边超过 8000 px 拒绝。
+- 缩放（`images.resize`，缺省 `auto`）：超限时依次找 `sips`（macOS）、`magick` / `convert`（ImageMagick）缩到
+  上限以内再附上；找不到工具或 `off` 时按上面的规则拒绝并提示。零依赖，不内置图像解码。
+- 单次请求的图片总量预算按协议：`anthropic-messages` 32 MB，其它 20 MB（base64 后）。历史图片每轮重发，超预算时
+  从最旧的图开始换成占位文本 `[earlier image omitted to fit request size]`，一次降到预算的 60% 以下；超过当前端点
+  单图上限的旧图（换了模型 / 渠道之后）直接换成占位；单请求超过 20 张图且有长边 > 2000 px 的图时，继续从最旧的
+  降到 20 张以内。最新一条带图的消息不降。降级写成会话里的 `context_edit{reason:"image_budget"}`，之后前缀稳定，
+  缓存统计把这一次当重置点。
+- 剪贴板图片（交互界面 `Ctrl+V` / `/paste`）：`pasteClipboardImage` 依次调 `osascript` / `pngpaste`（macOS）、`wl-paste`（Wayland）/ `xclip`（X11）、
+  PowerShell `Get-Clipboard -Format Image`（Windows），写到 `<数据目录>/clipboard/<时间戳>.png`；
+  `ama sessions prune` 清理其中超过 7 天的文件。
 - 模型 `input` 不含 `image` 时直接拒绝并提示换模型（`-p` 退出 2，界面里给错误提示，不发请求）；`read`
   工具读图时只返回路径、尺寸与「当前模型不接受图片」。
 
@@ -352,6 +479,20 @@ ama 用它给**没写元数据**的自定义模型补上下文、输出上限、
 
 compat 只记录**已验证**的差异；新增条目请附文档链接或真实样本。
 
+## Anthropic Messages 的 compat
+
+按请求主机推断缺省（`src/ai/apis/anthropic-compat.ts`），`providers.<id>.compat`、渠道或模型级 `compat` 逐字段覆盖：
+
+| 开关                          | 作用                                                 | 缺省                                                                                                           |
+| ----------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `sendInterleavedThinkingBeta` | 预算型思考 + 工具时带 `interleaved-thinking` beta 头 | `api.anthropic.com` 开；DeepSeek、智谱、Kimi、通义、MiniMax、阶跃、腾讯、火山关；其它主机只对 `claude*` 模型开 |
+| `sendCacheControl`            | 打 `cache_control` 断点                              | 开；DeepSeek 关（文档写明忽略）                                                                                |
+| `adaptiveThinking`            | `{type:"adaptive"}` + `output_config.effort`         | 关；官方新模型在目录里逐条开                                                                                   |
+| `supportsCacheControlOnTools` | 最后一个工具定义上打断点                             | 开                                                                                                             |
+| `maxCacheBreakpoints`         | 断点个数上限                                         | 4                                                                                                              |
+
+OpenRouter 的 Messages 接口只在 `message_delta` 里给缓存 usage，解析本就按非空字段合并，不需要开关。
+
 ## Responses 与 Gemini 的 compat
 
 | 协议                   | 开关                            | 作用                                                                                                      | 缺省                                         |
@@ -394,15 +535,15 @@ Anthropic 的 `baseUrl` 以 `/v1` 结尾时请求 `{baseUrl}/messages`，不会
 
 ### 兼容开关（`providers.<id>.compat` 或模型级 `compat`）
 
-| 开关                              | 作用                                                    | 缺省                                      |
-| --------------------------------- | ------------------------------------------------------- | ----------------------------------------- |
-| `sendPromptCacheKey`              | 发 `prompt_cache_key`                                   | 请求主机是 `api.openai.com` 时开，其余关  |
-| `sendSessionAffinityHeaders`      | 发亲和头                                                | 关（含 OpenRouter，未实测）               |
-| `supportsLongCacheRetention`      | `long` 可用（Anthropic 1h、OpenAI 24h）；否则降为 short | `api.openai.com` / `api.anthropic.com` 开 |
-| `supportsExplicitPromptCacheMode` | Responses 的 `prompt_cache_options`（30m）              | 关                                        |
-| `cacheReporting`                  | `auto` / `silent` / `reported`：强制「是否报缓存」三态  | `auto`                                    |
+| 开关                              | 作用                                                    | 缺省                                                                            |
+| --------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `sendPromptCacheKey`              | 发 `prompt_cache_key`                                   | OpenAI、xAI、Mistral、Kimi（`.cn` / `.ai`）、腾讯 TokenHub 的官方主机开，其余关 |
+| `sendSessionAffinityHeaders`      | 发亲和头                                                | 关（含 OpenRouter，未实测）                                                     |
+| `supportsLongCacheRetention`      | `long` 可用（Anthropic 1h、OpenAI 24h）；否则降为 short | `api.openai.com` / `api.anthropic.com` / `tokenhub.tencentmaas.com` 开          |
+| `supportsExplicitPromptCacheMode` | Responses 的 `prompt_cache_options`（30m）              | 关                                                                              |
+| `cacheReporting`                  | `auto` / `silent` / `reported`：强制「是否报缓存」三态  | `auto`                                                                          |
 
-推断只看最终请求的主机名，不看 provider id：用 `OPENAI_BASE_URL` 或自定义 `baseUrl` 把 `openai` 指到中转时
+推断只看最终请求的主机名（`cache-params.ts` 的 `HOST_CACHE_CAPABILITIES`，只收官方文档写明支持的主机），不看 provider id：用 `OPENAI_BASE_URL` 或自定义 `baseUrl` 把 `openai` 指到中转时
 按中转处理。缺省只对官方端点开，是因为中转上实测「接受但未见收益」或「收下但不生效」（下表）。
 
 **400 自动剥离**：端点以 400 拒收并在错误体里点名 `prompt_cache_key` / `prompt_cache_retention` /
@@ -524,8 +665,66 @@ ama models cache-probe <provider/id> [--tokens 2048] [--gap-ms 3000] [--json] [-
 - `/v1` 去重与 `toolChoice: "none"` 经 ama 协议层实发验证：Messages 请求落在 `/v1/messages`，三种接口都接受
   `tool_choice: none` 且未产生工具调用。
 
+## 渠道实测
+
+`scripts/channel-probe.mjs`（先 `pnpm build:lib`）对 `provider/model@channel` 跑实测门，每个模型 ≤ 8 个请求：
+
+| 项                | 做法                                                           | 通过                                                                     |
+| ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| ① check           | 一次最小调用                                                   | 无错误且有文本                                                           |
+| ② 工具往返        | 一次并行 `read` 两个临时文件、回答口令                         | 有工具调用且回答含口令                                                   |
+| ③ thinking 两回合 | 接着同一对话、thinking=medium 再读一个文件（思考块随历史回放） | 第二次无错误；没有思考块或 Messages 上思考块无签名记 ⚠（签名回放未验证） |
+| ④ 缓存            | 约 3k token 的固定前缀相隔 `--gap-ms` 发两次                   | 第二次 cacheRead > 0                                                     |
+| tool_use.id       | ②③ 同一对话里的全部工具调用 id                                 | 互不相同                                                                 |
+
+四项全过且 id 不重复 = 过门；DeepSeek、智谱、Kimi 的官方 Messages 渠道过门后缺省改 messages。
+
+### 中转对比（2026-10-02，messages vs chat）
+
+同一测试中转（Chat / Messages 两种接口），`--gap-ms 8000`，84 次请求（含一轮调试），保守估价约 $0.11：
+
+| 模型@渠道                          | 协议 · 主机                           | ① check | ② 工具往返 | ③ thinking 两回合    | ④ 缓存（读 / 前缀） | id 唯一 | 请求 | 结论     |
+| ---------------------------------- | ------------------------------------- | ------- | ---------- | -------------------- | ------------------- | ------- | ---- | -------- |
+| `packy/kimi-k2.5@messages`         | anthropic-messages · www.packyapi.com | ✓       | ✓          | ⚠ 2/2 个思考块无签名 | ✓ 2734 / 2738       | ✓       | 7    | 未过     |
+| `packy/kimi-k2.5@chat`             | openai-completions · www.packyapi.com | ✓       | ✓          | ✓                    | ✓ 2688 / 2740       | ✓       | 7    | **过门** |
+| `packy/deepseek-v4-flash@messages` | anthropic-messages · www.packyapi.com | ✓       | ✓          | ⚠ 没有思考块         | ✓ 2048 / 2732       | ✓       | 7    | 未过     |
+| `packy/deepseek-v4-flash@chat`     | openai-completions · www.packyapi.com | ✓       | ✓          | ✓                    | ✓ 2048 / 2732       | ✓       | 7    | **过门** |
+| `packy/glm-5@messages`             | anthropic-messages · www.packyapi.com | ✓       | ✓          | ⚠ 2/2 个思考块无签名 | ✓ 2560 / 2733       | ✓       | 7    | 未过     |
+| `packy/glm-5@chat`                 | openai-completions · www.packyapi.com | ✓       | ✓          | ✓                    | ✓ 2560 / 2733       | ✓       | 7    | **过门** |
+| `packy/qwen3.8-flash@messages`     | anthropic-messages · www.packyapi.com | ✓       | ✓          | ⚠ 2/2 个思考块无签名 | ✓ 3053 / 3061       | ✓       | 7    | 未过     |
+| `packy/qwen3.8-flash@chat`         | openai-completions · www.packyapi.com | ✓       | ✓          | ✓                    | ✓ 2048 / 3063       | ✓       | 7    | **过门** |
+| `packy/MiniMax-M2.7@messages`      | anthropic-messages · www.packyapi.com | ✓       | ✓          | ⚠ 2/2 个思考块无签名 | ✓ 2638 / 2743       | ✓       | 7    | 未过     |
+| `packy/MiniMax-M2.7@chat`          | openai-completions · www.packyapi.com | ✓       | ✓          | ✓                    | ✓ 2638 / 2744       | ✓       | 7    | **过门** |
+
+- 五家在中转的两种接口上 ①②④ 全过，tool_use.id 在同一对话里都不重复（Kimi 的 id 形如 `functions.read:<n>`，
+  按对话递增；不同对话会从 0 重来，所以只能在同一对话里比较）。
+- Messages 接口上的思考块**都没有签名**（DeepSeek 没返回思考块）：中转把上游 Chat 转成 Messages 时不带签名，
+  ama 按规则降级为文本回放，往返照常成功，但签名回放没被验证——**中转结果不能替代官方直连的实测门**。
+- 缓存：通义在 Messages 上首个请求就写入 3053 token（执行 `cache_control`），第二次读满前缀；其余四家读命中照常、
+  `cache_creation_input_tokens` 为 0（端点自管的隐式缓存），与「缓存 · 中转实测」一致。
+
+### 官方直连（待用户用自己的 key 跑）
+
+每家 ≤ 8 个请求，Kimi 的缓存写入有延迟、用 `--gap-ms 8000`：
+
+```sh
+pnpm build:lib
+node scripts/channel-probe.mjs --model deepseek/deepseek-v4-pro@messages,deepseek/deepseek-v4-pro@chat --json /tmp/probe-deepseek.json
+node scripts/channel-probe.mjs --model zhipu/glm-5.3@messages,zhipu/glm-5.3@chat --json /tmp/probe-zhipu.json
+node scripts/channel-probe.mjs --model moonshot/kimi-k3@messages,moonshot/kimi-k3@chat --gap-ms 8000 --json /tmp/probe-kimi.json
+node scripts/channel-probe.mjs --model dashscope/qwen3.8-max@messages --json /tmp/probe-qwen.json
+node scripts/channel-probe.mjs --model minimax/MiniMax-M3@messages,minimax/MiniMax-M2.7@messages --json /tmp/probe-minimax.json
+node scripts/channel-probe.mjs --model stepfun/step-5-preview@messages --json /tmp/probe-stepfun.json
+node scripts/channel-probe.mjs --model tencent/hy3@messages --json /tmp/probe-tencent.json
+node scripts/channel-probe.mjs --model volcengine/doubao-seed-2-1-pro-260628@responses --json /tmp/probe-volcengine.json
+```
+
+key 用各家标准环境变量（上表）；没有 key 的那家记「没有 key」、不发请求。结果用 `--render` 重画后补进本节。
+
 ## 测试用 fake 供应商
 
-`--provider fake --model fake/echo`：回显最后一条用户消息。设 `AMA_FAKE_SCRIPT=<file.json>` 后
+`--model fake/echo`：回显最后一条用户消息。零配置的模型选择器、`ama doctor`、`ama models list`、
+`ama providers list`、`ama config show` 缺省不列 fake；`AMA_SHOW_FAKE=1` 或设了 `AMA_FAKE_SCRIPT` 时照列，
+显式 `--model fake/…` 任何时候都可用。设 `AMA_FAKE_SCRIPT=<file.json>` 后
 按脚本第 n 次调用产出文本、思考、工具调用、429、溢出、断流、延迟，脚本格式见
 `src/ai/fake/fake-script.ts`，示例在 `test/fixtures/scripts/`。