@armadra/agent 0.4.0 → 0.5.1

package/dist/ai/apis/anthropic-request.d.ts

@@ -1,22 +1,24 @@
 /**
  * anthropic-messages 请求体（设计 §3.1、§3.3、§3.6）：消息转换、三断点缓存、thinking、工具。
  *
- * 缓存断点（cacheRetention 缺省 short，未指定时读 `AMA_CACHE_RETENTION`；none 不打；long 加
+ * compat 按主机推断见 anthropic-compat.ts（[W5-M2]）。
+ *
+ * 缓存断点（`sendCacheControl` 关时不打；cacheRetention 缺省 short，未指定时读 `AMA_CACHE_RETENTION`；none 不打；long 加
  * `ttl: "1h"`，仅 `supportsLongCacheRetention`——官方端点缺省开，中转缺省关、降为 short；最后做 TTL
  * 顺序校验，5m 之后出现 1h 则全部降为 5m）按优先级取前
  * `maxCacheBreakpoints` 个：① 最后一条 user 消息（含工具结果）的最后一个块 ② system 末块
  * ③ 最后一个工具定义（`supportsCacheControlOnTools`）。
  *
  * thinking：`adaptiveThinking` 模型发 `{type:"adaptive"}` + `output_config.effort`；
- * 其余推理模型按预算发 `{type:"enabled", budget_tokens}`，预算计入 max_tokens；off 发
+ * 其余推理模型按预算发 `{type:"enabled", budget_tokens}`，预算计入 max_tokens（有工具时带交错思考 beta 头，
+ * `sendInterleavedThinkingBeta` 关时不带）；off 发
  * `{type:"disabled"}`（映射表 off 为 null 的模型不发）。思考开启时不发 temperature，
  * 除非 `supportsTemperatureWithThinking`。`toolChoice: "none"`（有工具时）→ `tool_choice:{type:"none"}`。
  */
-import type { AnthropicMessagesCompat, AssistantMessage, Model, ModelThinkingLevel, ProviderData, StreamOptions, ToolResultMessage, TranscriptContext, UserMessage } from "../types.js";
+import type { AssistantMessage, Model, ModelThinkingLevel, StreamOptions, ToolResultMessage, TranscriptContext, UserMessage } from "../types.js";
 export declare const ANTHROPIC_VERSION = "2023-06-01";
 export declare const INTERLEAVED_THINKING_BETA = "interleaved-thinking-2025-05-14";
-export declare const DEFAULT_ANTHROPIC_COMPAT: Readonly<AnthropicMessagesCompat>;
-export declare function detectAnthropicCompat(model: Model, provider?: ProviderData): AnthropicMessagesCompat;
+export { DEFAULT_ANTHROPIC_COMPAT, detectAnthropicCompat } from "./anthropic-compat.js";
 type Json = Record<string, unknown>;
 export interface AnthropicRequest {
     body: Json;
@@ -39,4 +41,3 @@ export declare function anthropicMessagesUrl(baseUrl: string): string;
 export declare function normalizeToolId(id: string): string;
 export declare function convertMessages(messages: readonly (UserMessage | AssistantMessage | ToolResultMessage)[]): Json[];
 export declare function buildAnthropicRequest(model: Model, context: TranscriptContext, options: StreamOptions): AnthropicRequest;
-export {};

package/dist/ai/apis/anthropic-request.js

@@ -1,46 +1,27 @@
 /**
  * anthropic-messages 请求体（设计 §3.1、§3.3、§3.6）：消息转换、三断点缓存、thinking、工具。
  *
- * 缓存断点（cacheRetention 缺省 short，未指定时读 `AMA_CACHE_RETENTION`；none 不打；long 加
+ * compat 按主机推断见 anthropic-compat.ts（[W5-M2]）。
+ *
+ * 缓存断点（`sendCacheControl` 关时不打；cacheRetention 缺省 short，未指定时读 `AMA_CACHE_RETENTION`；none 不打；long 加
  * `ttl: "1h"`，仅 `supportsLongCacheRetention`——官方端点缺省开，中转缺省关、降为 short；最后做 TTL
  * 顺序校验，5m 之后出现 1h 则全部降为 5m）按优先级取前
  * `maxCacheBreakpoints` 个：① 最后一条 user 消息（含工具结果）的最后一个块 ② system 末块
  * ③ 最后一个工具定义（`supportsCacheControlOnTools`）。
  *
  * thinking：`adaptiveThinking` 模型发 `{type:"adaptive"}` + `output_config.effort`；
- * 其余推理模型按预算发 `{type:"enabled", budget_tokens}`，预算计入 max_tokens；off 发
+ * 其余推理模型按预算发 `{type:"enabled", budget_tokens}`，预算计入 max_tokens（有工具时带交错思考 beta 头，
+ * `sendInterleavedThinkingBeta` 关时不带）；off 发
  * `{type:"disabled"}`（映射表 off 为 null 的模型不发）。思考开启时不发 temperature，
  * 除非 `supportsTemperatureWithThinking`。`toolChoice: "none"`（有工具时）→ `tool_choice:{type:"none"}`。
  */
 import { contentText, normalizeContext, sanitizeText } from "../context.js";
 import { budgetedMaxTokens, clampThinkingLevel, mappedThinkingValue, thinkingBudget, } from "../thinking.js";
+import { detectAnthropicCompat } from "./anthropic-compat.js";
 import { effectiveRetention, resolveCacheRetention, resolvePromptCacheCompat, } from "./cache-params.js";
 export const ANTHROPIC_VERSION = "2023-06-01";
 export const INTERLEAVED_THINKING_BETA = "interleaved-thinking-2025-05-14";
-const ANTHROPIC_COMPAT_KEYS = [
-    "supportsCacheControlOnTools",
-    "supportsTemperatureWithThinking",
-    "adaptiveThinking",
-    "maxCacheBreakpoints",
-];
-export const DEFAULT_ANTHROPIC_COMPAT = {
-    supportsCacheControlOnTools: true,
-    supportsTemperatureWithThinking: false,
-    adaptiveThinking: false,
-    maxCacheBreakpoints: 4,
-};
-function pick(compat) {
-    const out = {};
-    for (const key of ANTHROPIC_COMPAT_KEYS) {
-        const value = compat?.[key];
-        if (value !== undefined)
-            out[key] = value;
-    }
-    return out;
-}
-export function detectAnthropicCompat(model, provider) {
-    return { ...DEFAULT_ANTHROPIC_COMPAT, ...pick(provider?.compat), ...pick(model.compat) };
-}
+export { DEFAULT_ANTHROPIC_COMPAT, detectAnthropicCompat } from "./anthropic-compat.js";
 export function cacheControlFor(retention) {
     if (retention === "none")
         return undefined;
@@ -227,7 +208,7 @@ function applyThinking(body, model, compat, level, requestedMax, hasTools, betas
     if (plan.budget < 1024)
         return undefined; // 回答上限太小，放弃思考
     body["thinking"] = { type: "enabled", budget_tokens: plan.budget, display: "summarized" };
-    if (hasTools)
+    if (hasTools && compat.sendInterleavedThinkingBeta !== false)
         betas.push(INTERLEAVED_THINKING_BETA);
     return String(plan.budget);
 }
@@ -236,7 +217,8 @@ export function buildAnthropicRequest(model, context, options) {
     const normalized = normalizeContext(context, { model });
     const cacheCompat = resolvePromptCacheCompat(model, "anthropic-messages");
     const retention = effectiveRetention(resolveCacheRetention(options.cacheRetention), cacheCompat);
-    const cacheControl = cacheControlFor(retention);
+    // sendCacheControl:false（端点忽略 cache_control，如 DeepSeek）：不打断点
+    const cacheControl = compat.sendCacheControl === false ? undefined : cacheControlFor(retention);
     const messages = convertMessages(normalized.messages);
     const level = clampThinkingLevel(model, options.thinkingLevel ?? "off");
     const betas = [];

package/dist/ai/apis/cache-params.d.ts

@@ -2,8 +2,8 @@
  * 协议层缓存参数（第三波 §1.3）：缓存兼容开关的端点推断、保留层级解析、亲和头。
  *
  * 推断只看最终请求的主机名（不看 provider id：`OPENAI_BASE_URL` 把 openai 指到中转时按中转处理）：
- * - `sendPromptCacheKey`、`supportsLongCacheRetention`：只有官方端点（api.openai.com /
- *   api.anthropic.com）缺省开；
+ * - `sendPromptCacheKey`、`supportsLongCacheRetention`：按 `HOST_CACHE_CAPABILITIES`（[W5-M2]，官方
+ *   文档写明支持的主机才开；其余主机——含全部中转——缺省关）。`sendPromptCacheKey` 只对 OpenAI 两条线有意义；
  * - `sendSessionAffinityHeaders`、`supportsExplicitPromptCacheMode`：缺省一律关（实测中转都接受
  *   但未见命中提升，OpenRouter 未实测，见 docs/providers.md「缓存」）；
  * - `cacheReporting`：`auto`。
@@ -15,6 +15,15 @@
  */
 import { type PostOptions } from "../http.js";
 import type { Api, CacheRetention, Model, PromptCacheCompat } from "../types.js";
+/**
+ * 按主机的缓存能力（精确主机名；docs/research/R1-models-protocols.md §2.1 的官方文档为据）：
+ * - OpenAI：`prompt_cache_key` 路由 + `prompt_cache_retention: "24h"`；
+ * - Anthropic：`ttl: "1h"`；
+ * - xAI、Mistral、Kimi：官方推荐 `prompt_cache_key`（Kimi 的 `prompt_cache_options.ttl` 形状不同，不开）；
+ * - 腾讯 TokenHub：Anthropic 线 `cache_control` 支持 `ttl: "1h"`，OpenAI 线自动缓存 + `prompt_cache_key`。
+ * 通义 Messages 只有 5m（不开长保留）；Groq 的 Responses 不认 `prompt_cache_key`（不开）。
+ */
+export declare const HOST_CACHE_CAPABILITIES: Readonly<Record<string, Partial<Pick<PromptCacheCompat, "sendPromptCacheKey" | "supportsLongCacheRetention">>>>;
 /** 请求实际发往的主机名（小写）；baseUrl 不可解析时返回空串。 */
 export declare function endpointHost(model: Pick<Model, "baseUrl">, api: Api): string;
 /** 解析后的缓存兼容开关：端点推断 ← `model.compat`。 */

package/dist/ai/apis/cache-params.js

@@ -2,8 +2,8 @@
  * 协议层缓存参数（第三波 §1.3）：缓存兼容开关的端点推断、保留层级解析、亲和头。
  *
  * 推断只看最终请求的主机名（不看 provider id：`OPENAI_BASE_URL` 把 openai 指到中转时按中转处理）：
- * - `sendPromptCacheKey`、`supportsLongCacheRetention`：只有官方端点（api.openai.com /
- *   api.anthropic.com）缺省开；
+ * - `sendPromptCacheKey`、`supportsLongCacheRetention`：按 `HOST_CACHE_CAPABILITIES`（[W5-M2]，官方
+ *   文档写明支持的主机才开；其余主机——含全部中转——缺省关）。`sendPromptCacheKey` 只对 OpenAI 两条线有意义；
  * - `sendSessionAffinityHeaders`、`supportsExplicitPromptCacheMode`：缺省一律关（实测中转都接受
  *   但未见命中提升，OpenRouter 未实测，见 docs/providers.md「缓存」）；
  * - `cacheReporting`：`auto`。
@@ -19,7 +19,23 @@ const DEFAULT_BASE_URLS = {
     "openai-completions": "https://api.openai.com/v1",
     "openai-responses": "https://api.openai.com/v1",
 };
-const OFFICIAL_HOSTS = new Set(["api.openai.com", "api.anthropic.com"]);
+/**
+ * 按主机的缓存能力（精确主机名；docs/research/R1-models-protocols.md §2.1 的官方文档为据）：
+ * - OpenAI：`prompt_cache_key` 路由 + `prompt_cache_retention: "24h"`；
+ * - Anthropic：`ttl: "1h"`；
+ * - xAI、Mistral、Kimi：官方推荐 `prompt_cache_key`（Kimi 的 `prompt_cache_options.ttl` 形状不同，不开）；
+ * - 腾讯 TokenHub：Anthropic 线 `cache_control` 支持 `ttl: "1h"`，OpenAI 线自动缓存 + `prompt_cache_key`。
+ * 通义 Messages 只有 5m（不开长保留）；Groq 的 Responses 不认 `prompt_cache_key`（不开）。
+ */
+export const HOST_CACHE_CAPABILITIES = {
+    "api.openai.com": { sendPromptCacheKey: true, supportsLongCacheRetention: true },
+    "api.anthropic.com": { supportsLongCacheRetention: true },
+    "api.x.ai": { sendPromptCacheKey: true },
+    "api.mistral.ai": { sendPromptCacheKey: true },
+    "api.moonshot.cn": { sendPromptCacheKey: true },
+    "api.moonshot.ai": { sendPromptCacheKey: true },
+    "tokenhub.tencentmaas.com": { sendPromptCacheKey: true, supportsLongCacheRetention: true },
+};
 const PROMPT_CACHE_KEYS = [
     "sendPromptCacheKey",
     "sendSessionAffinityHeaders",
@@ -39,11 +55,14 @@ export function endpointHost(model, api) {
 }
 /** 解析后的缓存兼容开关：端点推断 ← `model.compat`。 */
 export function resolvePromptCacheCompat(model, api) {
-    const official = OFFICIAL_HOSTS.has(endpointHost(model, api));
+    const name = endpointHost(model, api);
+    const host = Object.hasOwn(HOST_CACHE_CAPABILITIES, name)
+        ? HOST_CACHE_CAPABILITIES[name]
+        : undefined;
     const out = {
-        sendPromptCacheKey: official && api !== "anthropic-messages",
+        sendPromptCacheKey: host?.sendPromptCacheKey === true && api !== "anthropic-messages",
         sendSessionAffinityHeaders: false,
-        supportsLongCacheRetention: official,
+        supportsLongCacheRetention: host?.supportsLongCacheRetention === true,
         supportsExplicitPromptCacheMode: false,
         cacheReporting: "auto",
     };

package/dist/ai/apis/openai-compat.d.ts

@@ -19,7 +19,10 @@ interface InferenceRule {
     baseUrl: string;
     patch: (modelId: string) => Patch;
 }
-/** 推断表：13 家内置里走 OpenAI 兼容线的 11 家（anthropic / google 不走本协议）。 */
+/**
+ * 推断表：内置里有 OpenAI 兼容线（Chat 渠道或单渠道回落）的各家（anthropic / google 不走本协议）。
+ * [W5-M2] 新增四家暂无已验证的差异，按保守缺省（空补丁）登记。
+ */
 export declare const INFERENCE_RULES: readonly InferenceRule[];
 /** 命中的推断规则（先 provider id，后 baseUrl 子串）。 */
 export declare function findInferenceRule(providerId: string, baseUrl: string): InferenceRule | undefined;

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

@@ -39,7 +39,10 @@ export const CONSERVATIVE_COMPAT = {
     supportsStrictTools: false,
     supportsStore: false,
 };
-/** 推断表：13 家内置里走 OpenAI 兼容线的 11 家（anthropic / google 不走本协议）。 */
+/**
+ * 推断表：内置里有 OpenAI 兼容线（Chat 渠道或单渠道回落）的各家（anthropic / google 不走本协议）。
+ * [W5-M2] 新增四家暂无已验证的差异，按保守缺省（空补丁）登记。
+ */
 export const INFERENCE_RULES = [
     {
         provider: "openai",
@@ -102,6 +105,10 @@ export const INFERENCE_RULES = [
         baseUrl: "mistral.ai",
         patch: () => ({ thinkingFormat: "none", requiresToolResultName: true }),
     },
+    { provider: "minimax", baseUrl: "minimax", patch: () => ({}) },
+    { provider: "stepfun", baseUrl: "stepfun", patch: () => ({}) },
+    { provider: "volcengine", baseUrl: "volces.com", patch: () => ({}) },
+    { provider: "tencent", baseUrl: "tencentmaas.com", patch: () => ({}) },
     { provider: "ollama", baseUrl: ":11434", patch: () => ({}) },
     { provider: "lmstudio", baseUrl: ":1234", patch: () => ({}) },
 ];

package/dist/ai/image-limits.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 图片大小上限（docs/wave5-plan.md §4、D11；R1 §3.2）。[W5-I]
+ *
+ * 各家的上限都按 **base64 后**的字节数计算：`base64Bytes = ceil(bytes / 3) * 4`。
+ *
+ * | 端点                                   | 单图     | 单请求总量（按协议）            |
+ * | -------------------------------------- | -------- | ------------------------------- |
+ * | 官方 Anthropic（api.anthropic.com）    | 10 MB    | anthropic-messages 32 MB        |
+ * | 官方 Gemini（generativelanguage…）     | 20 MB    | google-generative-ai 20 MB      |
+ * | 官方 OpenAI（api.openai.com）          | 20 MB    | 其它协议 20 MB                  |
+ * | 中转（内置供应商改了 baseUrl）/ 未知   | 5 MB     | 同上，按协议                    |
+ *
+ * 中转背后常是 Bedrock / Vertex（单图 5 MB），所以只认官方主机，其余一律按 5 MB。
+ * 尺寸：任一边 > 8000 px 拒绝；单请求超过 20 张图时每边 ≤ 2000 px（Anthropic）。
+ */
+import type { Api } from "./types.js";
+export declare const MB: number;
+/** 单图任一边上限（像素）。 */
+export declare const MAX_IMAGE_EDGE = 8000;
+/** 单请求图片数超过这个数时，每张图的边长上限收紧为 `MANY_IMAGES_EDGE`。 */
+export declare const MANY_IMAGES_COUNT = 20;
+export declare const MANY_IMAGES_EDGE = 2000;
+/** 未知端点 / 中转的单图上限（base64 后）。 */
+export declare const DEFAULT_IMAGE_BASE64_LIMIT: number;
+export interface ImageLimits {
+    /** 单张图片 base64 后的上限（字节）。 */
+    perImageBase64: number;
+    /** 单次请求全部图片 base64 后的总量预算（字节）。 */
+    perRequestBase64: number;
+}
+export type ImageEndpoint = "anthropic" | "gemini" | "openai" | "other";
+/** 判断端点只需要地址与协议。 */
+export interface ImageModelInfo {
+    baseUrl?: string | undefined;
+    api: Api;
+}
+/** 原始字节数 → base64 后的字节数。 */
+export declare function base64Size(bytes: number): number;
+/** 按 baseUrl 的主机判断是不是官方端点；中转与未知主机都是 `other`。 */
+export declare function imageEndpoint(model: Pick<ImageModelInfo, "baseUrl">): ImageEndpoint;
+/** 单请求图片总量预算按协议：Anthropic 32 MB，其余（含 Gemini）20 MB。 */
+export declare function requestImageBudget(api: Api): number;
+export declare function imageLimits(model: ImageModelInfo, api?: Api): ImageLimits;
+/** 文案用：`10 MB`、`3.8 MB`。 */
+export declare function formatMb(bytes: number): string;

package/dist/ai/image-limits.js

@@ -0,0 +1,68 @@
+/**
+ * 图片大小上限（docs/wave5-plan.md §4、D11；R1 §3.2）。[W5-I]
+ *
+ * 各家的上限都按 **base64 后**的字节数计算：`base64Bytes = ceil(bytes / 3) * 4`。
+ *
+ * | 端点                                   | 单图     | 单请求总量（按协议）            |
+ * | -------------------------------------- | -------- | ------------------------------- |
+ * | 官方 Anthropic（api.anthropic.com）    | 10 MB    | anthropic-messages 32 MB        |
+ * | 官方 Gemini（generativelanguage…）     | 20 MB    | google-generative-ai 20 MB      |
+ * | 官方 OpenAI（api.openai.com）          | 20 MB    | 其它协议 20 MB                  |
+ * | 中转（内置供应商改了 baseUrl）/ 未知   | 5 MB     | 同上，按协议                    |
+ *
+ * 中转背后常是 Bedrock / Vertex（单图 5 MB），所以只认官方主机，其余一律按 5 MB。
+ * 尺寸：任一边 > 8000 px 拒绝；单请求超过 20 张图时每边 ≤ 2000 px（Anthropic）。
+ */
+export const MB = 1024 * 1024;
+/** 单图任一边上限（像素）。 */
+export const MAX_IMAGE_EDGE = 8000;
+/** 单请求图片数超过这个数时，每张图的边长上限收紧为 `MANY_IMAGES_EDGE`。 */
+export const MANY_IMAGES_COUNT = 20;
+export const MANY_IMAGES_EDGE = 2000;
+/** 未知端点 / 中转的单图上限（base64 后）。 */
+export const DEFAULT_IMAGE_BASE64_LIMIT = 5 * MB;
+/** 原始字节数 → base64 后的字节数。 */
+export function base64Size(bytes) {
+    return Math.ceil(bytes / 3) * 4;
+}
+const OFFICIAL_HOSTS = {
+    "api.anthropic.com": "anthropic",
+    "generativelanguage.googleapis.com": "gemini",
+    "api.openai.com": "openai",
+};
+const PER_IMAGE = {
+    anthropic: 10 * MB,
+    gemini: 20 * MB,
+    openai: 20 * MB,
+    other: DEFAULT_IMAGE_BASE64_LIMIT,
+};
+function hostOf(url) {
+    if (url === undefined)
+        return undefined;
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 按 baseUrl 的主机判断是不是官方端点；中转与未知主机都是 `other`。 */
+export function imageEndpoint(model) {
+    const host = hostOf(model.baseUrl);
+    return (host !== undefined ? OFFICIAL_HOSTS[host] : undefined) ?? "other";
+}
+/** 单请求图片总量预算按协议：Anthropic 32 MB，其余（含 Gemini）20 MB。 */
+export function requestImageBudget(api) {
+    return api === "anthropic-messages" ? 32 * MB : 20 * MB;
+}
+export function imageLimits(model, api = model.api) {
+    return {
+        perImageBase64: PER_IMAGE[imageEndpoint(model)],
+        perRequestBase64: requestImageBudget(api),
+    };
+}
+/** 文案用：`10 MB`、`3.8 MB`。 */
+export function formatMb(bytes) {
+    const mb = bytes / MB;
+    return `${Number.isInteger(mb) ? mb : mb.toFixed(1)} MB`;
+}

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

@@ -1,22 +1,34 @@
 /**
- * 13 家内置供应商（设计 §3.3）。这里只放供应商级数据；模型来自 catalog/*.json，compat 由
- * 各协议的 detectCompat 推断（openai-compat.ts 的推断表），这里只写推断不出来的东西。
+ * 内置供应商（设计 §3.3、docs/wave5-plan.md §3.2）。这里只放供应商级数据；模型来自 catalog/*.json，
+ * compat 由各协议的 detectCompat 推断（openai-compat.ts、anthropic-compat.ts 的主机表），这里只写推断
+ * 不出来的东西。
  *
- * 这里的 `api` 是供应商级缺省；目录条目可用 `api` 覆盖（openai 推理模型与 xai 目录模型走
- * openai-responses，见 catalog/*.json）。
+ * 内置渠道（[W5-M2]）：一家同时开放多种协议时写 `channels`（首个不一定是缺省，看 `defaultChannel`）。
+ * registry 物化时与用户 config 的 `channels` 合并（同名字段级覆盖、新名追加），用户的 `defaultChannel`
+ * 优先。供应商级 `api` + `baseUrl` 是**单渠道回落**：用户（config / auth.json / `*_BASE_URL`）把
+ * baseUrl 改到别处时内置渠道整体作废，按这一对单渠道处理（与引入内置渠道之前的行为一致）。
+ * 只做按量计费端点；Coding Plan 类订阅端点不做内置渠道（D9），见 docs/providers.md。
  *
  * `baseUrlEnv`（第三波 §2.3）：通行约定的 baseUrl 环境变量（OpenAI SDK 的 `OPENAI_BASE_URL`、
  * Claude Code 的 `ANTHROPIC_BASE_URL`），设了就把内置供应商指向中转站，零配置可用；优先级低于
  * config.json 与 auth.json 的 baseUrl。
  */
-import type { ProviderData } from "../types.js";
+import type { Api, ProviderData } from "../types.js";
 export type BuiltinProvider = Omit<ProviderData, "models" | "builtin"> & {
     baseUrlEnv?: string;
+    /**
+     * 单渠道回落时目录模型的协议（缺省同 `api`）：OpenAI / xAI 的目录模型在中转上仍走 Responses，
+     * 目录外的 id（本地服务、中转自有模型）走 `api`（Chat）。
+     */
+    catalogApi?: Api;
 };
 export declare const BUILTIN_PROVIDERS: readonly BuiltinProvider[];
+/** 内置供应商的官方主机（单渠道回落 + 全部内置渠道）。 */
+export declare function builtinHosts(providerId: string): Set<string>;
 /**
  * 内置供应商的 baseUrl 是否被改到了非官方主机（中转站）：此时目录外的 model id 也接受，
- * compat 走保守缺省。非内置供应商返回 false。
+ * compat 走保守缺省。按渠道比较主机：落在任一内置渠道的主机上（如国际站）不算中转。
+ * 非内置供应商与本地服务返回 false。
  */
 export declare function isRelayedBaseUrl(providerId: string, baseUrl: string): boolean;
 /** 自定义供应商的兜底环境变量名：`AMA_API_KEY_<ID>`（非字母数字转下划线、大写）。 */

package/dist/ai/providers/builtin.js

@@ -1,14 +1,26 @@
 /**
- * 13 家内置供应商（设计 §3.3）。这里只放供应商级数据；模型来自 catalog/*.json，compat 由
- * 各协议的 detectCompat 推断（openai-compat.ts 的推断表），这里只写推断不出来的东西。
+ * 内置供应商（设计 §3.3、docs/wave5-plan.md §3.2）。这里只放供应商级数据；模型来自 catalog/*.json，
+ * compat 由各协议的 detectCompat 推断（openai-compat.ts、anthropic-compat.ts 的主机表），这里只写推断
+ * 不出来的东西。
  *
- * 这里的 `api` 是供应商级缺省；目录条目可用 `api` 覆盖（openai 推理模型与 xai 目录模型走
- * openai-responses，见 catalog/*.json）。
+ * 内置渠道（[W5-M2]）：一家同时开放多种协议时写 `channels`（首个不一定是缺省，看 `defaultChannel`）。
+ * registry 物化时与用户 config 的 `channels` 合并（同名字段级覆盖、新名追加），用户的 `defaultChannel`
+ * 优先。供应商级 `api` + `baseUrl` 是**单渠道回落**：用户（config / auth.json / `*_BASE_URL`）把
+ * baseUrl 改到别处时内置渠道整体作废，按这一对单渠道处理（与引入内置渠道之前的行为一致）。
+ * 只做按量计费端点；Coding Plan 类订阅端点不做内置渠道（D9），见 docs/providers.md。
  *
  * `baseUrlEnv`（第三波 §2.3）：通行约定的 baseUrl 环境变量（OpenAI SDK 的 `OPENAI_BASE_URL`、
  * Claude Code 的 `ANTHROPIC_BASE_URL`），设了就把内置供应商指向中转站，零配置可用；优先级低于
  * config.json 与 auth.json 的 baseUrl。
  */
+function ch(name, api, baseUrl, extra = {}) {
+    return { name, api, baseUrl, ...extra };
+}
+const CHAT = "openai-completions";
+const MESSAGES = "anthropic-messages";
+const RESPONSES = "openai-responses";
+/** 文档写 `Authorization: Bearer` 的 Anthropic 兼容端点（Kimi、MiniMax、阶跃）。 */
+const BEARER = { authHeader: "authorization-bearer" };
 export const BUILTIN_PROVIDERS = [
     {
         id: "anthropic",
@@ -24,7 +36,14 @@ export const BUILTIN_PROVIDERS = [
         id: "openai",
         name: "OpenAI",
         api: "openai-completions",
+        catalogApi: RESPONSES,
         baseUrl: "https://api.openai.com/v1",
+        // 全部模型缺省 Responses（R1 §2.3）；Chat 作渠道
+        channels: [
+            ch("responses", RESPONSES, "https://api.openai.com/v1"),
+            ch("chat", CHAT, "https://api.openai.com/v1"),
+        ],
+        defaultChannel: "responses",
         baseUrlEnv: "OPENAI_BASE_URL",
         envKeys: ["OPENAI_API_KEY", "AMA_API_KEY_OPENAI"],
         requiresApiKey: true,
@@ -43,6 +62,12 @@ export const BUILTIN_PROVIDERS = [
         name: "DeepSeek",
         api: "openai-completions",
         baseUrl: "https://api.deepseek.com",
+        // 实测门（wave5-plan §3.2）未过前缺省 chat；messages 上 cache_control 被忽略
+        channels: [
+            ch("chat", CHAT, "https://api.deepseek.com"),
+            ch("messages", MESSAGES, "https://api.deepseek.com/anthropic"),
+        ],
+        defaultChannel: "chat",
         envKeys: ["DEEPSEEK_API_KEY", "AMA_API_KEY_DEEPSEEK"],
         requiresApiKey: true,
     },
@@ -51,6 +76,15 @@ export const BUILTIN_PROVIDERS = [
         name: "Moonshot (Kimi)",
         api: "openai-completions",
         baseUrl: "https://api.moonshot.cn/v1",
+        // 实测门未过前缺省 chat（K3 在 Messages 端点有 tool_use.id 复用的第三方报告）
+        channels: [
+            ch("chat", CHAT, "https://api.moonshot.cn/v1"),
+            ch("messages", MESSAGES, "https://api.moonshot.cn/anthropic", BEARER),
+            ch("responses", RESPONSES, "https://api.moonshot.cn/v1"),
+            ch("chat-intl", CHAT, "https://api.moonshot.ai/v1"),
+            ch("messages-intl", MESSAGES, "https://api.moonshot.ai/anthropic", BEARER),
+        ],
+        defaultChannel: "chat",
         envKeys: ["MOONSHOT_API_KEY", "KIMI_API_KEY", "AMA_API_KEY_MOONSHOT"],
         requiresApiKey: true,
     },
@@ -59,6 +93,14 @@ export const BUILTIN_PROVIDERS = [
         name: "Zhipu GLM",
         api: "openai-completions",
         baseUrl: "https://open.bigmodel.cn/api/paas/v4",
+        // 实测门未过前缺省 chat；只有隐式缓存
+        channels: [
+            ch("chat", CHAT, "https://open.bigmodel.cn/api/paas/v4"),
+            ch("messages", MESSAGES, "https://open.bigmodel.cn/api/anthropic"),
+            ch("chat-intl", CHAT, "https://api.z.ai/api/paas/v4"),
+            ch("messages-intl", MESSAGES, "https://api.z.ai/api/anthropic"),
+        ],
+        defaultChannel: "chat",
         envKeys: ["ZHIPU_API_KEY", "ZAI_API_KEY", "AMA_API_KEY_ZHIPU"],
         requiresApiKey: true,
     },
@@ -67,6 +109,15 @@ export const BUILTIN_PROVIDERS = [
         name: "Alibaba DashScope (Qwen)",
         api: "openai-completions",
         baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        // Messages 端点执行 cache_control（5m），直接切
+        channels: [
+            ch("messages", MESSAGES, "https://dashscope.aliyuncs.com/apps/anthropic"),
+            ch("responses", RESPONSES, "https://dashscope.aliyuncs.com/compatible-mode/v1"),
+            ch("chat", CHAT, "https://dashscope.aliyuncs.com/compatible-mode/v1"),
+            ch("messages-intl", MESSAGES, "https://dashscope-intl.aliyuncs.com/apps/anthropic"),
+            ch("chat-intl", CHAT, "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"),
+        ],
+        defaultChannel: "messages",
         envKeys: ["DASHSCOPE_API_KEY", "QWEN_API_KEY", "AMA_API_KEY_DASHSCOPE"],
         requiresApiKey: true,
     },
@@ -94,7 +145,14 @@ export const BUILTIN_PROVIDERS = [
         id: "xai",
         name: "xAI",
         api: "openai-completions",
+        catalogApi: RESPONSES,
         baseUrl: "https://api.x.ai/v1",
+        // 官方已把 Anthropic 兼容标为 deprecated，不做 messages 渠道
+        channels: [
+            ch("responses", RESPONSES, "https://api.x.ai/v1"),
+            ch("chat", CHAT, "https://api.x.ai/v1"),
+        ],
+        defaultChannel: "responses",
         envKeys: ["XAI_API_KEY", "AMA_API_KEY_XAI"],
         requiresApiKey: true,
     },
@@ -106,6 +164,69 @@ export const BUILTIN_PROVIDERS = [
         envKeys: ["MISTRAL_API_KEY", "AMA_API_KEY_MISTRAL"],
         requiresApiKey: true,
     },
+    {
+        id: "minimax",
+        name: "MiniMax",
+        api: "openai-completions",
+        baseUrl: "https://api.minimax.cn/v1",
+        // 官方推荐 Anthropic 兼容端点；M2.x 执行 cache_control（5m），M3 的缓存行为列入实测；Responses 只有 M3
+        channels: [
+            ch("messages", MESSAGES, "https://api.minimax.cn/anthropic", BEARER),
+            ch("responses", RESPONSES, "https://api.minimax.cn/v1"),
+            ch("chat", CHAT, "https://api.minimax.cn/v1"),
+            ch("messages-intl", MESSAGES, "https://api.minimax.io/anthropic", BEARER),
+            ch("chat-intl", CHAT, "https://api.minimax.io/v1"),
+        ],
+        defaultChannel: "messages",
+        envKeys: ["MINIMAX_API_KEY", "AMA_API_KEY_MINIMAX"],
+        requiresApiKey: true,
+    },
+    {
+        id: "stepfun",
+        name: "StepFun",
+        api: "openai-completions",
+        baseUrl: "https://api.stepfun.com/v1",
+        // 自动前缀缓存；Responses 按模型开放（目录标注）
+        channels: [
+            ch("messages", MESSAGES, "https://api.stepfun.com", BEARER),
+            ch("chat", CHAT, "https://api.stepfun.com/v1"),
+            ch("responses", RESPONSES, "https://api.stepfun.com/v1"),
+            ch("messages-intl", MESSAGES, "https://api.stepfun.ai", BEARER),
+            ch("chat-intl", CHAT, "https://api.stepfun.ai/v1"),
+        ],
+        defaultChannel: "messages",
+        envKeys: ["STEPFUN_API_KEY", "STEP_API_KEY", "AMA_API_KEY_STEPFUN"],
+        requiresApiKey: true,
+    },
+    {
+        id: "volcengine",
+        name: "Volcengine Ark (Doubao)",
+        api: "openai-completions",
+        catalogApi: RESPONSES,
+        baseUrl: "https://ark.cn-beijing.volces.com/api/v3",
+        // 官方推荐 Responses（显式缓存只在 Responses 上）；Anthropic 兼容只在 Coding Plan，不做渠道（D9）
+        channels: [
+            ch("responses", RESPONSES, "https://ark.cn-beijing.volces.com/api/v3"),
+            ch("chat", CHAT, "https://ark.cn-beijing.volces.com/api/v3"),
+        ],
+        defaultChannel: "responses",
+        envKeys: ["ARK_API_KEY", "VOLCENGINE_API_KEY", "AMA_API_KEY_VOLCENGINE"],
+        requiresApiKey: true,
+    },
+    {
+        id: "tencent",
+        name: "Tencent TokenHub (Hunyuan)",
+        api: "openai-completions",
+        baseUrl: "https://tokenhub.tencentmaas.com/v1",
+        // Anthropic 线执行 cache_control（含 1h），直接切
+        channels: [
+            ch("messages", MESSAGES, "https://tokenhub.tencentmaas.com"),
+            ch("chat", CHAT, "https://tokenhub.tencentmaas.com/v1"),
+        ],
+        defaultChannel: "messages",
+        envKeys: ["TOKENHUB_API_KEY", "HUNYUAN_API_KEY", "AMA_API_KEY_TENCENT"],
+        requiresApiKey: true,
+    },
     {
         id: "ollama",
         name: "Ollama (local)",
@@ -132,15 +253,23 @@ function hostOf(url) {
         return undefined;
     }
 }
+/** 内置供应商的官方主机（单渠道回落 + 全部内置渠道）。 */
+export function builtinHosts(providerId) {
+    const builtin = BUILTIN_PROVIDERS.find((p) => p.id === providerId);
+    const urls = [builtin?.baseUrl, ...(builtin?.channels ?? []).map((c) => c.baseUrl)];
+    return new Set(urls.map((url) => (url ? hostOf(url) : undefined)).filter((h) => h !== undefined));
+}
 /**
  * 内置供应商的 baseUrl 是否被改到了非官方主机（中转站）：此时目录外的 model id 也接受，
- * compat 走保守缺省。非内置供应商返回 false。
+ * compat 走保守缺省。按渠道比较主机：落在任一内置渠道的主机上（如国际站）不算中转。
+ * 非内置供应商与本地服务返回 false。
  */
 export function isRelayedBaseUrl(providerId, baseUrl) {
     const builtin = BUILTIN_PROVIDERS.find((p) => p.id === providerId);
     if (builtin === undefined || builtin.requiresApiKey === false)
         return false;
-    return hostOf(baseUrl) !== hostOf(builtin.baseUrl);
+    const host = hostOf(baseUrl);
+    return host === undefined || !builtinHosts(providerId).has(host);
 }
 /** 自定义供应商的兜底环境变量名：`AMA_API_KEY_<ID>`（非字母数字转下划线、大写）。 */
 export function fallbackEnvKey(providerId) {