@armadra/agent 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 更新记录
 
+## 0.3.0（2026-10-02）
+
+自定义供应商与多渠道、models.dev 模型元数据、图像输入、默认配置目录。
+
+- **一键接入**：`ama providers add <id> --base-url <url>` 只要 baseUrl 与 key——列出中转的模型、按提示或 `--probe` 逐渠道
+  探测、写进配置；`list` / `channels` / `remove` / `refresh`。
+- **渠道**：一个供应商可挂多个渠道（协议 + 地址 + 可选 key / headers / compat），模型声明 `channels`，
+  `provider/model@channel` 指定渠道；旧配置按隐式 `default` 渠道处理，不用改。
+- **models.dev 元数据**：上下文、输出上限、图像输入、推理、价格缺省从 models.dev 补（数据目录缓存，启动不联网），
+  `ama models refresh-catalog` 刷新；`models list` / `config show` 标出每个字段的来源。
+- **图像输入**：`-p --image`、界面里 `@图片路径`；与 read 工具共用 MIME 检测与 5 MB 上限；模型不收图片时拒绝。
+- **配置目录**：首次运行自动建 `~/.config/ama/` 与最小 `config.json`、`config.schema.json`；`ama init`、
+  `ama config path`、`ama config edit`。
+- **修复**：Responses 的 `incomplete_details.reason: "length"` 按输出截断处理（中转转发 DeepSeek 时出现）。
+
 ## 0.2.1（2026-10-02）
 
 npm 首发：`npm i -g @armadra/agent`。功能与 0.2.0 相同。

package/README.md

@@ -41,7 +41,9 @@ ama
 | 方面           | 内容                                                                                                                                                                  |
 | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 多协议与供应商 | 4 条协议线、13 家内置供应商（Anthropic、OpenAI、Google、DeepSeek、Moonshot、智谱、通义、OpenRouter、Groq、xAI、Mistral、Ollama、LM Studio）、自定义供应商、模型级协议 |
-| 零配置与中转站 | 有 key 就选第一个可用的供应商；识别 `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL`；`ama models discover` 从中转站探测协议并写回配置                                        |
+| 零配置与中转站 | 有 key 就选第一个可用的供应商；识别 `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL`；`ama providers add` 只给 baseUrl 与 key 一键接入：列模型、探测渠道、写回配置            |
+| 模型元数据     | 上下文、输出上限、图像输入、推理、价格缺省从 models.dev 补（本地缓存，启动不联网）；一个供应商可挂多个渠道（Chat / Responses / Messages），`provider/model@渠道`      |
+| 图像输入       | `-p --image`、界面里 `@图片路径`；四条协议都映射；模型不收图片时直接拒绝并提示换模型                                                                                  |
 | 工具与预设     | read / edit / write / bash / grep / glob，另有 ls、todo、task（子 Agent）、codemode；四个预设 `default` / `minimal` / `codemode` / `coordinator`                      |
 | codemode       | 模型写一段 JS，在受 Node 权限模型约束的子进程里编排多次工具调用，只有输出回到模型                                                                                     |
 | Skill          | `SKILL.md` 目录，模型按索引自行读取，用户用 `/skill:<名字>` 调用；另有提示模板                                                                                        |
@@ -133,10 +135,13 @@ ama -p "列出 TODO" --model deepseek/deepseek-v4-pro --output-format json
 
 ## 配置
 
-一个文件 `~/.config/ama/config.json`。常用的只有五个键：
+一个文件 `~/.config/ama/config.json`。第一次运行 ama 时自动建好目录（0700）、最小的 `config.json` 与给编辑器用的
+`config.schema.json`；也可以 `ama init` 手动建（已有文件不覆盖）。`ama config path` 打印各文件位置，`ama config edit`
+用 `$VISUAL` / `$EDITOR` 打开。常用的只有五个键：
 
 ```json
 {
+  "$schema": "./config.schema.json",
   "version": 1,
   "defaultModel": "anthropic/<model-id>",
   "thinkingLevel": "medium",
@@ -150,13 +155,13 @@ ama -p "列出 TODO" --model deepseek/deepseek-v4-pro --output-format json
 
 ### 文件位置与层级
 
-| 位置                  | 内容                                                                                                       |
-| --------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `~/.config/ama/`      | 用户级：`config.json`、`auth.json`、`hooks.json`、`keybindings.json`、`trust.json`、`AGENTS.md`、`skills/` |
-| `~/.local/share/ama/` | 数据：`sessions/`（会话 JSONL）、输入历史                                                                  |
-| `<项目>/.ama/`        | 项目级：`config.json`（只能收紧）、`hooks.json` / `skills/` / `prompts/`（需信任）                         |
-| `<项目>/AGENTS.md`    | 项目约定，从 cwd 向上查找，自动进系统提示                                                                  |
-| `--profile <文件>`    | 宿主 profile（嵌入方用，见「嵌入 Armadra」）                                                               |
+| 位置                  | 内容                                                                                                                                                 |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `~/.config/ama/`      | 用户级：`config.json`、`config.schema.json`（ama 生成）、`auth.json`（0600）、`hooks.json`、`keybindings.json`、`trust.json`、`AGENTS.md`、`skills/` |
+| `~/.local/share/ama/` | 数据：`sessions/`（会话 JSONL）、`models-dev.json`（模型元数据缓存）、输入历史                                                                       |
+| `<项目>/.ama/`        | 项目级：`config.json`（只能收紧）、`hooks.json` / `skills/` / `prompts/`（需信任）                                                                   |
+| `<项目>/AGENTS.md`    | 项目约定，从 cwd 向上查找，自动进系统提示                                                                                                            |
+| `--profile <文件>`    | 宿主 profile（嵌入方用，见「嵌入 Armadra」）                                                                                                         |
 
 `AMA_CONFIG_DIR` / `AMA_DATA_DIR` 可改两个目录；也遵循 `XDG_CONFIG_HOME` / `XDG_DATA_HOME`，Windows 下是 `%APPDATA%\ama` 与 `%LOCALAPPDATA%\ama`。
 
@@ -172,6 +177,41 @@ ama doctor               # 配置层级、项目信任、key 来源、Hook、终
 
 ## 接入中转站
 
+**一键接入**：只给 baseUrl 与 key。
+
+```sh
+export PACKY_API_KEY=sk-...
+ama providers add packy --base-url https://proxy.example/v1 --key-env PACKY_API_KEY --probe --limit 8 --yes
+ama -p "hi" --model packy/kimi-k2.5               # 首选渠道
+ama -p "hi" --model packy/kimi-k2.5@messages      # 指定渠道（Anthropic Messages）
+ama -p "图里有什么颜色" --image shot.png --model packy/kimi-k2.5
+ama providers list                                 # 供应商 → 渠道 → 模型数、key 来源
+```
+
+`add` 列出 `GET {baseUrl}/models` 的模型，从 baseUrl 推出 chat / responses / messages 三个候选渠道，`--probe` 逐渠道发最小
+请求，把能用的渠道写进每个模型的 `channels`；上下文、输出上限、图像、推理与价格不写进配置，运行时从 models.dev 缓存补
+（`ama models list` 标出每个字段的来源）。不给 `--key-env` 时 key 从 stdin 读（不回显）存进 `auth.json`。写入后的配置：
+
+```json
+{
+  "providers": {
+    "packy": {
+      "apiKey": "$PACKY_API_KEY",
+      "channels": {
+        "chat": { "api": "openai-completions", "baseUrl": "https://proxy.example/v1" },
+        "responses": { "api": "openai-responses", "baseUrl": "https://proxy.example/v1" },
+        "messages": { "api": "anthropic-messages", "baseUrl": "https://proxy.example" }
+      },
+      "defaultChannel": "chat",
+      "models": [
+        { "id": "kimi-k2.5", "channels": ["chat", "messages"] },
+        { "id": "grok-4.7", "channels": ["responses"] }
+      ]
+    }
+  }
+}
+```
+
 **零配置**：内置的 `openai` / `anthropic` 识别 `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL`。baseUrl 不在官方主机时接受目录外的 model id，缓存相关字段按保守缺省。
 
 ```sh
@@ -200,7 +240,8 @@ OPENAI_BASE_URL=https://proxy.example/v1 OPENAI_API_KEY=$PACKY_API_KEY \
 
 - `api` 缺省 `openai-completions`；可选 `openai-responses`、`anthropic-messages`、`google-generative-ai`。
 - `apiKey` 支持 `$ENV` / `${ENV}`（读环境变量）与 `!command`（执行命令取值），不要把 key 明文写进配置。
-- 自定义模型不猜 `contextWindow`，没写时自动压缩关闭；需要时在模型条目里补上。
+- 自定义模型的元数据缺省从 models.dev 补（`ama models refresh-catalog` 刷新缓存）；匹配不到时不猜 `contextWindow`，自动
+  压缩关闭，需要时在模型条目里补上或写 `"modelsDev": "provider/model"` 指定条目。
 
 **不想手写模型表**：让 ama 去问中转站。
 
@@ -310,7 +351,7 @@ anthropic/<model-id> · think:medium · ↑412k ↓8.1k · cache 83% ♨ · $0.8
 | Ctrl+C               | 清空输入；输入为空时 1.5 秒内再按一次退出  |
 | Tab                  | 补全：`/` 命令、模板与 Skill，`@` 文件路径 |
 
-常用命令：`/model`、`/thinking`、`/permission`、`/tools`、`/compact`、`/tree`（回到某条消息之前重新分支）、`/fork`、`/resume`、`/new`、`/session`、`/cache`、`/hooks`、`/skill:<名字>`、`/help`。按键可在 `~/.config/ama/keybindings.json` 覆盖。见 [docs/tui.md](docs/tui.md)。
+常用命令：`/model`、`/thinking`、`/permission`、`/tools`、`/compact`、`/tree`（回到某条消息之前重新分支）、`/fork`、`/resume`、`/new`、`/session`、`/cache`、`/hooks`、`/skill:<名字>`、`/help`。输入里的 `@图片路径`（或粘贴 / 拖入的图片路径）作为图片附件发给模型；`/model` 按「供应商 · 渠道」分组，标出上下文与 `img`。按键可在 `~/.config/ama/keybindings.json` 覆盖。见 [docs/tui.md](docs/tui.md)。
 
 `--no-tui`（或 stdin / stdout 不是 TTY、`TERM=dumb`）进入行式界面：readline + 括号粘贴，命令相同。
 
@@ -322,6 +363,9 @@ anthropic/<model-id> · think:medium · ↑412k ↓8.1k · cache 83% ♨ · $0.8
 | `json`            | 一个 `result` 对象：会话 id、模型、`stopReason`、`text`、用量、费用、缓存统计 |
 | `stream-json`     | 每行一个事件，与 RPC 事件同形状                                               |
 
+`--image <文件>` 可重复，随提示发送图片（PNG / JPEG / GIF / WebP，单张 ≤ 5 MB）；提示里的 `@图片路径` 同样作为附件。当前
+模型不收图片时直接退出 2，不发请求。
+
 退出码：0 正常 · 1 运行期错误 · 2 用法错误 · 3 配置错误 · 4 无可用模型或 key · 5 会话错误 · 6 宿主 / Hook 启动失败 · 78 宿主 API 版本不匹配 · 130 / 143 信号。
 
 ### RPC

package/dist/agent/session-cache.js

@@ -7,6 +7,7 @@
  * 之后的首个请求是重置点。子会话（depth > 0）有自己的控制器，`warmSubagents` 为 false 时不保温。
  * fork 出的会话沿用根会话 id 作 `prompt_cache_key`（只是路由提示）；task 子会话不沿用。
  */
+import { modelRefOf } from "../ai/providers/channels.js";
 import { readFileSync } from "node:fs";
 import { evaluateWarm } from "../ai/cache/economics.js";
 import { fingerprintContext } from "../ai/cache/fingerprint.js";
@@ -183,7 +184,7 @@ export class SessionCacheController {
                 const record = {
                     at,
                     purpose,
-                    model: { provider: model.provider, id: model.id },
+                    model: modelRefOf(model),
                     api: model.api,
                     baseUrl: model.baseUrl ?? "",
                     fingerprint: fingerprintContext(context, model),
@@ -305,7 +306,9 @@ export class SessionCacheController {
         const model = this.core.model();
         if (record === undefined || this.disposed)
             return undefined;
-        if (model.provider !== record.model.provider || model.id !== record.model.id)
+        if (model.provider !== record.model.provider ||
+            model.id !== record.model.id ||
+            model.channel !== record.model.channel)
             return undefined;
         const messages = convertToLlm(this.core.agent.messages, {
             provider: model.provider,

package/dist/agent/session-state.js

@@ -5,13 +5,14 @@
  * 压缩与分支摘要请求的 usage 也计入；`usage` 条目（缓存保温等不进上下文的请求，第三波 §1.7）
  * 计入 token 与费用但不算消息。上下文 % 用投影感知估算（§9）。
  */
+import { modelRefOf } from "../ai/providers/channels.js";
 export function buildSessionState(input) {
     const { agent, manager, model } = input;
     return {
         isStreaming: agent.isRunning,
         isCompacting: input.isCompacting,
         isRetrying: input.isRetrying,
-        model: { provider: model.provider, id: model.id },
+        model: modelRefOf(model),
         thinkingLevel: input.thinkingLevel,
         permissionMode: input.permissionMode,
         sessionId: manager.id,

package/dist/agent/session-sync.js

@@ -28,17 +28,24 @@ export function persistMessage(core, message) {
 export function recordModelState(core, model, thinkingLevel) {
     let provider;
     let modelId;
+    let channel;
     let thinking;
     for (const entry of core.manager.branch()) {
         if (entry.type === "model_change") {
             provider = entry.provider;
             modelId = entry.modelId;
+            channel = entry.channel;
         }
         else if (entry.type === "thinking_level_change")
             thinking = entry.thinkingLevel;
     }
-    if (provider !== model.provider || modelId !== model.id) {
-        core.appendEntry({ type: "model_change", provider: model.provider, modelId: model.id });
+    if (provider !== model.provider || modelId !== model.id || channel !== model.channel) {
+        core.appendEntry({
+            type: "model_change",
+            provider: model.provider,
+            modelId: model.id,
+            ...(model.channel !== undefined ? { channel: model.channel } : {}),
+        });
     }
     if (thinking !== thinkingLevel) {
         core.appendEntry({ type: "thinking_level_change", thinkingLevel });

package/dist/agent/session.js

@@ -10,6 +10,7 @@
  * - `steer()` / `followUp()`：运行中入队（返回 "queued"）；空闲时直接以该消息开始一个周期（"handled"）。
  * - `abort()`：中断供应商流、工具、重试等待与压缩；回到 idle 后 resolve；不清队列。
  */
+import { modelRefOf } from "../ai/providers/channels.js";
 import { join } from "node:path";
 import { AmaError } from "../errors.js";
 import { buildProjection } from "../session/projection.js";
@@ -141,7 +142,8 @@ export class AgentSessionImpl {
     }
     async resolveApiKey() {
         try {
-            return (await this.options.providers.resolveApiKey(this.currentModel.provider)).apiKey;
+            const { provider, channel } = this.currentModel;
+            return (await this.options.providers.resolveApiKey(provider, channel)).apiKey;
         }
         catch {
             return undefined;
@@ -358,15 +360,14 @@ export class AgentSessionImpl {
         }
         this.currentModel = lookup.model;
         this.compaction.refresh();
+        const next = modelRefOf(lookup.model);
         this.appendEntry({
             type: "model_change",
-            provider: lookup.model.provider,
-            modelId: lookup.model.id,
-        });
-        this.emit({
-            type: "model_changed",
-            model: { provider: lookup.model.provider, id: lookup.model.id },
+            provider: next.provider,
+            modelId: next.id,
+            ...(next.channel !== undefined ? { channel: next.channel } : {}),
         });
+        this.emit({ type: "model_changed", model: next });
     }
     setThinkingLevel(level) {
         this.currentThinking = level;

package/dist/ai/apis/openai-responses.js

@@ -50,7 +50,8 @@ export function parseResponsesUsage(raw) {
 }
 export function mapResponsesStatus(status, incomplete) {
     if (status === "incomplete") {
-        if (incomplete === "max_output_tokens")
+        // 中转转发的 DeepSeek 等上游写 `length`（实测 2026-10-02），与 `max_output_tokens` 同义。
+        if (incomplete === "max_output_tokens" || incomplete === "length")
             return { reason: "length" };
         return {
             reason: "error",

package/dist/ai/cache/fingerprint.d.ts

@@ -11,7 +11,7 @@ import type { Model, ModelRef, TranscriptContext } from "../types.js";
 import type { PrefixFingerprint } from "./types.js";
 /** sha256 的前 16 位 hex（64 bit）。 */
 export declare function hash16(text: string): string;
-export declare function modelKey(model: Pick<Model, "provider" | "id"> | ModelRef): string;
+export declare function modelKey(model: Pick<Model, "provider" | "id" | "channel"> | ModelRef): string;
 export declare function fingerprintContext(context: TranscriptContext, model: Pick<Model, "provider" | "id">): PrefixFingerprint;
 /** 两个指纹的差异（按归因顺序：system → tools → model）；相同返回 undefined。 */
 export declare function fingerprintChange(prev: PrefixFingerprint, cur: PrefixFingerprint): "system" | "tools" | "model" | undefined;

package/dist/ai/cache/fingerprint.js

@@ -14,7 +14,7 @@ export function hash16(text) {
     return createHash("sha256").update(text).digest("hex").slice(0, 16);
 }
 export function modelKey(model) {
-    return `${model.provider}/${model.id}`;
+    return `${model.provider}/${model.id}${model.channel !== undefined ? `@${model.channel}` : ""}`;
 }
 function sortedTools(tools) {
     return [...tools].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));

package/dist/ai/cache/reporting.js

@@ -41,7 +41,8 @@ function hostOf(baseUrl) {
     }
 }
 export function endpointKey(record) {
-    return `${record.model.provider}|${hostOf(record.baseUrl)}|${record.model.id}`;
+    const channel = record.model.channel !== undefined ? `@${record.model.channel}` : "";
+    return `${record.model.provider}|${hostOf(record.baseUrl)}|${record.model.id}${channel}`;
 }
 function sameFingerprint(a, b) {
     return a.system === b.system && a.tools === b.tools && a.model === b.model;

package/dist/ai/providers/channels.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 渠道（docs/providers.md「渠道」）：一个供应商下的多种接口（协议 + 地址 + 可选 key / headers / compat）。
+ *
+ * - 没有 `channels` 的供应商按单渠道处理：供应商级 `api` + `baseUrl` 就是隐式的 `default` 渠道，
+ *   模型上不出现 `channel` / `channels` 字段，行为与引入渠道之前完全相同。
+ * - 有 `channels` 时：模型 `channels[0]` 是首选，缺省 `defaultChannel`；模型级 `api` / `baseUrl`
+ *   覆盖在所选渠道之上（等价于匿名渠道）。
+ * - 模型引用 `provider/model@channel`：`@` 之后是该供应商的渠道名才当渠道，否则整串仍是 model id。
+ * - 渠道自己的 key 以 `<provider>@<channel>` 为键进 key 解析（config 的 `channels.<c>.apiKey` 或
+ *   auth.json 的同名条目），没有时用供应商的 key。
+ */
+import type { ProviderConfig } from "../../config/types.js";
+import type { Api, ProviderChannel } from "../types.js";
+/** 隐式渠道名（单渠道供应商）。 */
+export declare const DEFAULT_CHANNEL = "default";
+/** 渠道 key 在 key 解析里的键。 */
+export declare function channelKeyId(providerId: string, channel: string): string;
+/** config 的 `channels` → 物化渠道表（跳过名字非法或缺 api / baseUrl 的，返回警告）。 */
+export declare function parseChannels(providerId: string, config: ProviderConfig): {
+    channels: ProviderChannel[];
+    defaultChannel: string | undefined;
+    warnings: string[];
+};
+/** 模型的渠道表：去掉不存在的；空 → [defaultChannel]。 */
+export declare function modelChannels(wanted: readonly string[] | undefined, known: readonly ProviderChannel[], defaultChannel: string, onUnknown: (name: string) => void): string[];
+/**
+ * 拆 `provider/model@channel` 末尾的渠道：只看最后一个 `/` 之后的部分；渠道名不合法时返回 undefined。
+ * 是否真的是渠道由调用方结合供应商的渠道表判断。
+ */
+export declare function splitChannelRef(ref: string): {
+    base: string;
+    channel: string;
+} | undefined;
+/** `provider/model` 或 `provider/model@channel`（channel 为空时不带后缀）。 */
+export declare function formatModelRef(ref: {
+    provider: string;
+    id: string;
+    channel?: string;
+}): string;
+/** Model / ModelRef → ModelRef（带上渠道，没有渠道时不出现该键）。 */
+export declare function modelRefOf(model: {
+    provider: string;
+    id: string;
+    channel?: string | undefined;
+}): {
+    provider: string;
+    id: string;
+    channel?: string;
+};
+/** 协议的短名（表格用）。 */
+export declare function apiShortName(api: Api): string;

package/dist/ai/providers/channels.js

@@ -0,0 +1,96 @@
+/**
+ * 渠道（docs/providers.md「渠道」）：一个供应商下的多种接口（协议 + 地址 + 可选 key / headers / compat）。
+ *
+ * - 没有 `channels` 的供应商按单渠道处理：供应商级 `api` + `baseUrl` 就是隐式的 `default` 渠道，
+ *   模型上不出现 `channel` / `channels` 字段，行为与引入渠道之前完全相同。
+ * - 有 `channels` 时：模型 `channels[0]` 是首选，缺省 `defaultChannel`；模型级 `api` / `baseUrl`
+ *   覆盖在所选渠道之上（等价于匿名渠道）。
+ * - 模型引用 `provider/model@channel`：`@` 之后是该供应商的渠道名才当渠道，否则整串仍是 model id。
+ * - 渠道自己的 key 以 `<provider>@<channel>` 为键进 key 解析（config 的 `channels.<c>.apiKey` 或
+ *   auth.json 的同名条目），没有时用供应商的 key。
+ */
+import { CHANNEL_NAME_PATTERN } from "../../config/types.js";
+/** 隐式渠道名（单渠道供应商）。 */
+export const DEFAULT_CHANNEL = "default";
+/** 渠道 key 在 key 解析里的键。 */
+export function channelKeyId(providerId, channel) {
+    return `${providerId}@${channel}`;
+}
+/** config 的 `channels` → 物化渠道表（跳过名字非法或缺 api / baseUrl 的，返回警告）。 */
+export function parseChannels(providerId, config) {
+    const warnings = [];
+    const channels = [];
+    for (const [name, raw] of Object.entries(config.channels ?? {})) {
+        const c = raw;
+        if (!CHANNEL_NAME_PATTERN.test(name) || !c || !c.api || !c.baseUrl) {
+            warnings.push(`provider "${providerId}" channel "${name}" is invalid; ignored`);
+            continue;
+        }
+        const channel = { name, api: c.api, baseUrl: c.baseUrl };
+        if (c.authHeader !== undefined)
+            channel.authHeader = c.authHeader;
+        if (c.headers !== undefined)
+            channel.headers = { ...c.headers };
+        if (c.compat !== undefined)
+            channel.compat = { ...c.compat };
+        channels.push(channel);
+    }
+    let defaultChannel = config.defaultChannel;
+    if (defaultChannel !== undefined && !channels.some((c) => c.name === defaultChannel)) {
+        warnings.push(`provider "${providerId}" defaultChannel "${defaultChannel}" not found`);
+        defaultChannel = undefined;
+    }
+    return { channels, defaultChannel: defaultChannel ?? channels[0]?.name, warnings };
+}
+/** 模型的渠道表：去掉不存在的；空 → [defaultChannel]。 */
+export function modelChannels(wanted, known, defaultChannel, onUnknown) {
+    const names = new Set(known.map((c) => c.name));
+    const out = [];
+    for (const name of wanted ?? []) {
+        if (!names.has(name))
+            onUnknown(name);
+        else if (!out.includes(name))
+            out.push(name);
+    }
+    return out.length > 0 ? out : [defaultChannel];
+}
+/**
+ * 拆 `provider/model@channel` 末尾的渠道：只看最后一个 `/` 之后的部分；渠道名不合法时返回 undefined。
+ * 是否真的是渠道由调用方结合供应商的渠道表判断。
+ */
+export function splitChannelRef(ref) {
+    const at = ref.lastIndexOf("@");
+    if (at <= 0 || at < ref.lastIndexOf("/"))
+        return undefined;
+    const channel = ref.slice(at + 1);
+    if (!CHANNEL_NAME_PATTERN.test(channel))
+        return undefined;
+    return { base: ref.slice(0, at), channel };
+}
+/** `provider/model` 或 `provider/model@channel`（channel 为空时不带后缀）。 */
+export function formatModelRef(ref) {
+    return `${ref.provider}/${ref.id}${ref.channel !== undefined ? `@${ref.channel}` : ""}`;
+}
+/** Model / ModelRef → ModelRef（带上渠道，没有渠道时不出现该键）。 */
+export function modelRefOf(model) {
+    return {
+        provider: model.provider,
+        id: model.id,
+        ...(model.channel !== undefined ? { channel: model.channel } : {}),
+    };
+}
+/** 协议的短名（表格用）。 */
+export function apiShortName(api) {
+    switch (api) {
+        case "openai-completions":
+            return "chat";
+        case "openai-responses":
+            return "responses";
+        case "anthropic-messages":
+            return "messages";
+        case "google-generative-ai":
+            return "gemini";
+        default:
+            return api;
+    }
+}

package/dist/ai/providers/enrich.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 用 models.dev 缓存给自定义模型补元数据（docs/providers.md「模型元数据：models.dev」）。
+ *
+ * 优先级：用户配置写了的字段 > models.dev > 自定义缺省（maxTokens 8192、input ["text"]、
+ * reasoning false、不猜 contextWindow）。内置目录的模型不经过这里（目录本身就是人工校对的值）。
+ * 只读传入的索引，不联网。
+ */
+import type { ModelConfig } from "../../config/types.js";
+import type { Model } from "../types.js";
+import { type EnrichableField, type ModelsDevIndex, type ModelsDevMatch } from "./models-dev.js";
+export type FieldSource = "config" | "catalog" | "models.dev" | "default";
+export interface ModelMetadata {
+    sources: Record<EnrichableField, FieldSource>;
+    /** models.dev 匹配结果；未查（没有缓存或 `modelsDev: false`）为 undefined。 */
+    match?: ModelsDevMatch | undefined;
+    /** 是否查过 models.dev（有缓存且没关闭）。 */
+    looked: boolean;
+    /** models.dev 的 tool_call。 */
+    toolCall?: boolean;
+}
+export type ModelsDevSource = ModelsDevIndex | (() => ModelsDevIndex | undefined) | undefined;
+/** 惰性取索引：只有真的要补字段时才读缓存（启动时没有自定义模型就不读约 2 MB 的缓存）。 */
+export declare function lazyIndex(source: ModelsDevSource): () => ModelsDevIndex | undefined;
+/**
+ * 补全一个自定义模型条目（config 的 `models[]` 或合成的模型）。返回补过字段的条目（不含
+ * `modelsDev` / `channels` 这些配置专用键）与每个字段的来源。
+ */
+export declare function enrichEntry(entry: ModelConfig, index: () => ModelsDevIndex | undefined): {
+    entry: Omit<ModelConfig, "modelsDev" | "channels">;
+    metadata: ModelMetadata;
+};
+/** 内置目录模型的来源（全部 catalog；目录没写 contextWindow / cost 的为缺省）。 */
+export declare function catalogMetadata(model: Model): ModelMetadata;
+export declare function sourceText(source: FieldSource): string;

package/dist/ai/providers/enrich.js

@@ -0,0 +1,86 @@
+/**
+ * 用 models.dev 缓存给自定义模型补元数据（docs/providers.md「模型元数据：models.dev」）。
+ *
+ * 优先级：用户配置写了的字段 > models.dev > 自定义缺省（maxTokens 8192、input ["text"]、
+ * reasoning false、不猜 contextWindow）。内置目录的模型不经过这里（目录本身就是人工校对的值）。
+ * 只读传入的索引，不联网。
+ */
+import { ENRICHABLE_FIELDS, modelsDevFields, } from "./models-dev.js";
+/** 惰性取索引：只有真的要补字段时才读缓存（启动时没有自定义模型就不读约 2 MB 的缓存）。 */
+export function lazyIndex(source) {
+    if (typeof source !== "function")
+        return () => source;
+    let loaded = false;
+    let index;
+    return () => {
+        if (!loaded) {
+            loaded = true;
+            try {
+                index = source();
+            }
+            catch {
+                index = undefined;
+            }
+        }
+        return index;
+    };
+}
+function needsLookup(entry) {
+    return ENRICHABLE_FIELDS.some((field) => entry[field] === undefined);
+}
+/**
+ * 补全一个自定义模型条目（config 的 `models[]` 或合成的模型）。返回补过字段的条目（不含
+ * `modelsDev` / `channels` 这些配置专用键）与每个字段的来源。
+ */
+export function enrichEntry(entry, index) {
+    const { modelsDev, channels: _channels, ...rest } = entry;
+    const sources = {};
+    for (const field of ENRICHABLE_FIELDS) {
+        sources[field] = rest[field] !== undefined ? "config" : "default";
+    }
+    const metadata = { sources, looked: false };
+    if (modelsDev === false || (!needsLookup(rest) && modelsDev === undefined)) {
+        return { entry: rest, metadata };
+    }
+    const idx = index();
+    if (idx === undefined)
+        return { entry: rest, metadata };
+    metadata.looked = true;
+    const match = idx.match(entry.id, typeof modelsDev === "string" ? modelsDev : undefined);
+    metadata.match = match;
+    if (match === undefined)
+        return { entry: rest, metadata };
+    const fields = modelsDevFields(match.model);
+    if (fields.toolCall !== undefined)
+        metadata.toolCall = fields.toolCall;
+    const out = { ...rest };
+    for (const field of ENRICHABLE_FIELDS) {
+        if (out[field] !== undefined)
+            continue;
+        const value = fields[field];
+        if (value === undefined)
+            continue;
+        out[field] = structuredClone(value);
+        sources[field] = "models.dev";
+    }
+    if (out.name === undefined && fields.name !== undefined)
+        out.name = fields.name;
+    return { entry: out, metadata };
+}
+/** 内置目录模型的来源（全部 catalog；目录没写 contextWindow / cost 的为缺省）。 */
+export function catalogMetadata(model) {
+    const sources = {};
+    for (const field of ENRICHABLE_FIELDS) {
+        sources[field] = model[field] !== undefined ? "catalog" : "default";
+    }
+    return { sources, looked: false };
+}
+const SOURCE_TEXT = {
+    config: "config",
+    catalog: "目录",
+    "models.dev": "models.dev",
+    default: "缺省",
+};
+export function sourceText(source) {
+    return SOURCE_TEXT[source];
+}

package/dist/ai/providers/models-dev-cache.d.ts

@@ -0,0 +1,53 @@
+/**
+ * models.dev 缓存（docs/providers.md「模型元数据：models.dev」）。
+ *
+ * - 缓存文件 `<dataDir>/models-dev.json`：`{ version, url, fetchedAt, etag?, providers }`，providers 是
+ *   `trimModelsDev()` 裁剪后的数据（约 2.3 MB，原始约 5 MB）。写入走同目录临时文件 + rename。
+ * - **启动不联网**：`loadModelsDevIndex()` 只读缓存（按路径 + mtime 记忆，同一进程只解析一次）。
+ * - 联网只在 `ama providers add|refresh`、`ama models discover`、`ama models refresh-catalog` 调
+ *   `refreshModelsDev()` 时发生：缓存 24 小时内不重拉（`force` 例外），带 `If-None-Match`；304 只刷新时间；
+ *   失败时返回旧缓存与 warning。`AMA_MODELS_DEV_URL` 换数据源。
+ */
+import { ModelsDevIndex, type ModelsDevData } from "./models-dev.js";
+export declare const MODELS_DEV_URL = "https://models.dev/api.json";
+export declare const MODELS_DEV_URL_ENV = "AMA_MODELS_DEV_URL";
+export declare const MODELS_DEV_FILE = "models-dev.json";
+export declare const MODELS_DEV_TTL_MS: number;
+export declare const MODELS_DEV_TIMEOUT_MS = 30000;
+export interface ModelsDevCacheFile {
+    version: 1;
+    url: string;
+    /** ISO 8601。 */
+    fetchedAt: string;
+    etag?: string;
+    providers: ModelsDevData;
+}
+export declare function modelsDevCachePath(dataDir: string): string;
+export declare function modelsDevUrl(env?: Readonly<Record<string, string | undefined>>): string;
+/** 读缓存；不存在或损坏返回 undefined（损坏不报错：下次拉取会覆盖）。 */
+export declare function readModelsDevCache(dataDir: string): ModelsDevCacheFile | undefined;
+export declare function writeModelsDevCache(dataDir: string, file: ModelsDevCacheFile): void;
+/** 只读缓存构造索引（不联网）；没有缓存返回 undefined。 */
+export declare function loadModelsDevIndex(dataDir: string): ModelsDevIndex | undefined;
+export type RefreshStatus = "fresh" | "updated" | "not-modified" | "stale" | "unavailable";
+export interface RefreshResult {
+    status: RefreshStatus;
+    index?: ModelsDevIndex;
+    fetchedAt?: string;
+    url: string;
+    warning?: string;
+}
+export interface RefreshOptions {
+    dataDir: string;
+    env?: Readonly<Record<string, string | undefined>>;
+    /** 忽略 TTL（`ama models refresh-catalog`）。 */
+    force?: boolean;
+    ttlMs?: number;
+    timeoutMs?: number;
+    now?: () => number;
+    fetch?: typeof fetch;
+}
+/** 按需拉取 models.dev 并更新缓存；失败时回落旧缓存（status `stale`）或无数据（`unavailable`）。 */
+export declare function refreshModelsDev(options: RefreshOptions): Promise<RefreshResult>;
+/** 一行状态说明（命令输出用）。 */
+export declare function describeRefresh(result: RefreshResult): string;