@wallbreakerno4/opencode-commandcode 0.1.0

package/dist/host/v1.js

@@ -0,0 +1,118 @@
+/**
+ * v1 宿主接线（#37；实测定案 #11，原型证据在弃用分支 prototype/v1-host-loading）。
+ *
+ * 用户 config 只写一行 `plugin: ["@wallbreakerno4/opencode-commandcode"]`，其余全部
+ * 自举（与 v2 glue #36 共用工厂与运行时，宿主形态互不干扰）：
+ *
+ * - **三合一入口**：`server(input, options)` 由 v1 加载器消费（default 带 id 时
+ *   server 必须在场，否则整模块跳过，#11 实测），返回 `{config, auth}` hooks。
+ *   v1.18.x 是双轨宿主——内嵌 v2 运行时也会以嵌入式 ctx 调 default.setup，但它
+ *   懒加载且晚于 v1 config hook（1.18.25 真宿主探针实测），管线模式由先到的 v1
+ *   config hook 协商为 v1，setup 的构造调用幂等落空。
+ * - **config hook**：注入 `provider.commandcode-go = {npm, name, env, models}`。
+ *   npm 指向本包安装 spec（推导方式见 selfNpmSpec——注入裸包名会装出第二个模块
+ *   实例）；宿主经 arborist 缓存命中后 import 同一模块实例（目录存在即缓存命中，
+ *   #11 实测），按「第一个 create* 导出」判得与 v2 共用的工厂。注入前先以用户
+ *   已写的 `options.modelsUrls` 做 v1 启动协商（拉取一次，15s 总预算，失败用快照，
+ *   此后无后台刷新——v1 无 reload 机制），模型清单 = 协商后的级联。
+ * - **非破坏合并**：用户已写键一律优先（npm/name/env 整键、options 整块、models
+ *   逐 id）——插件只补缺，绝不覆盖用户显式配置；`options` 全权归用户（modelsUrls
+ *   通道所在），插件不注入任何默认值。
+ * - **auth hook**：注册 `/connect` 登录项（label 固定「Command Code API Key」，
+ *   CONTEXT.md）；loader 仅在 auth.json 有该 provider 凭证记录时被宿主调用（无凭证
+ *   不触发，#11 实测），把凭证翻译成工厂 `apiKey`；优先级 auth > env 由宿主保证
+ *   （与 v2 credential > env 一致）。
+ * - **测试边界**（testing.md §4 定案）：hook 的宿主交互行为不入 bun test——mock
+ *   宿主 = 重写宿主，验证 = 真宿主 v1（latest 1.18.x）验证，全程 XDG 隔离；
+ *   hooks 静态形状与 selfNpmSpec 纯函数推导在 bun test 内（testing.md §1.4）。
+ *
+ * 零依赖纪律（入口既定）：不 import `@opencode-ai/plugin`，宿主对象以本模块的
+ * 最小结构类型承接——字段名按 v1.18.25 真宿主探针收窄到 glue 触达的域，宿主漂移
+ * 时真宿主验证即暴露，不为漂移预付兼容成本。
+ */
+import { ENTRY_URL } from "../index.js";
+import { toV1ModelMap } from "../models/mapping.js";
+import { PROVIDER_ID } from "../protocol/envelope.js";
+import { ensureV1ProviderRuntime } from "../provider/model.js";
+import { API_KEY_ENV_VAR, API_KEY_METHOD_LABEL, PROVIDER_DISPLAY_NAME } from "./constants.js";
+/**
+ * config hook 注入的 npm spec：从入口模块自身的加载路径推导（#37 真宿主验证定案）。
+ * v1 宿主对 plugin 列表的裸包名会归一化为 `<name>@latest` 再定 arborist 缓存目录，
+ * 而 provider 的 `npm` spec **原样**定目录——注入裸包名会装出第二个模块实例，
+ * 伪装状态与模型管线全部翻倍（违背「v1 无后台刷新」与伪装 per-key 状态的进程内
+ * 单例前提）。因此 spec 不能写死包名，按 v1 缓存目录布局
+ * `…/opencode/packages/<spec>/node_modules/…` 从实际加载路径提取：
+ * - 正常安装形态（plugin 裸包名 → @latest 归一化、版本钉死等）：提取出的 `<spec>`
+ *   使 provider 解析命中同一缓存目录（目录存在即缓存命中，#11 实测）——同一模块
+ *   实例。
+ * - 其余形态（本地 file:// 直载开发、缓存布局漂移）：回退入口自身 URL，免安装
+ *   直接 import（#11 实测 file:// 绝对路径形态可用；file: 相对路径残缺不可用，
+ *   不产出）。
+ * 推导在 server() 调用时进行（ENTRY_URL 此时必已初始化，规避环导 TDZ）。
+ */
+export function selfNpmSpec(entryUrl) {
+    const marker = "/opencode/packages/";
+    const start = entryUrl.indexOf(marker);
+    if (entryUrl.startsWith("file:") && start !== -1) {
+        const from = start + marker.length;
+        const end = entryUrl.indexOf("/node_modules/", from);
+        if (end !== -1)
+            return entryUrl.slice(from, end);
+    }
+    return entryUrl;
+}
+// ---------------------------------------------------------------------------
+// provider 块注入（非破坏合并）
+// ---------------------------------------------------------------------------
+/**
+ * 注入 provider 块：插件自举字段垫底、用户已写键一律优先。models 逐 id 合并——
+ * 用户手写的模型条目保留（覆盖同 id 的管线产物），其余由级联清单补齐。
+ */
+function mergeProviderBlock(npmSpec, existing, models) {
+    const merged = {
+        name: PROVIDER_DISPLAY_NAME,
+        npm: npmSpec,
+        env: [API_KEY_ENV_VAR],
+        ...existing,
+        models: { ...models, ...existing?.models },
+    };
+    return merged;
+}
+// ---------------------------------------------------------------------------
+// server()：v1 插件入口
+// ---------------------------------------------------------------------------
+/**
+ * v1 插件入口（default.server）：返回 config / auth hooks。纯函数——宿主可能在
+ * config 重载或 auth login 等场景重复调用，重放注入幂等（同级联 → 同块）。
+ */
+export async function serverV1(_input, _options) {
+    // 自举 npm spec 按实际加载路径推导（见 selfNpmSpec）；此时入口模块必已完成求值
+    const npmSpec = selfNpmSpec(ENTRY_URL);
+    return {
+        config: async (config) => {
+            const existing = config.provider?.[PROVIDER_ID];
+            // 用户 modelsUrls 通道（model-pipeline.md §1.3）：仅用户已写时读取，作为
+            // v1 启动拉取的 config 通道初值（config > env > 默认列表）
+            const userModelsUrls = existing?.options?.modelsUrls;
+            // v1 启动协商：15s 总预算拉取一次（跨渠道共享），失败用快照；若运行时已被
+            // 工厂先行 / 内嵌 v2 setup 先行构造，幂等守卫使本调用退化为读当前级联
+            const cascade = await ensureV1ProviderRuntime({ modelsUrls: userModelsUrls });
+            config.provider ??= {};
+            config.provider[PROVIDER_ID] = mergeProviderBlock(npmSpec, existing, toV1ModelMap(cascade.models));
+        },
+        auth: {
+            provider: PROVIDER_ID,
+            loader: async (auth) => {
+                // 宿主传懒加载函数或现值（#11 原型实测两种形态）；key 缺位 = 凭证记录损坏，
+                // 空 apiKey 按 auth > env 优先级压过 env，请求以 401 浮现——warn 指路重新登录
+                const resolved = (typeof auth === "function" ? await auth() : auth);
+                const key = resolved?.key;
+                if (!key) {
+                    console.warn("[commandcode-go] 凭证记录存在但 key 为空，请求将返回 401；请重新 /connect 登录");
+                }
+                return { apiKey: key ?? "" };
+            },
+            methods: [{ type: "api", label: API_KEY_METHOD_LABEL }],
+        },
+    };
+}

package/dist/host/v2.d.ts

@@ -0,0 +1,33 @@
+/**
+ * v2 宿主接线（#36；实测定案 #12/#5）。
+ *
+ * 用户 config 只写空壳 `{providers: {"commandcode-go": {}}}`，其余全部自举：
+ *
+ * - **catalog.transform 自指注册**（#12 S1 定案）：provider.update 设
+ *   `package = "aisdk:" + <入口模块 URL>`——宿主剥掉 `aisdk:` 前缀后原生 import
+ *   该文件，命中同一模块实例（instance seq 全程 = 1，伪装模块进程内状态安全
+ *   的前提）；锚点取入口模块的 `import.meta.url`（ENTRY_URL）而非 glue 子模块的
+ *   ——工厂判据「第一个 create* 导出」作用在入口模块上。`aisdk:<registry 包名>`
+ *   链路在 beta-18684 已死（UnsupportedPackageError），不用。模型按级联清单
+ *   update-or-create 注册：首播 = 包内快照（启动零阻塞），后台拉取签名变化触发
+ *   `catalog.reload()` 重放本 transform，届时 latestCascade 已是管线实时级联。
+ * - **integration.transform 认证**（#12 S2 定案）：为全新 provider upsert
+ *   integration（update 是 upsert，无需预存），注册 key 方法（/connect 粘贴）与
+ *   env 方法；凭证由宿主解析后经工厂 `apiKey` 注入，优先级 credential > env。
+ * - **modelsUrls v2 settings 通道**：用户写的 `settings.modelsUrls` 由宿主合并进
+ *   工厂 options 顶层（beta-18684 实测：transform 草稿不带 config settings，插件
+ *   侧构造时不可见），首次工厂调用经管线 rebindModelsUrls 接入（config > env >
+ *   默认列表，原值不变零开销跳过）；settings 壳其余字段原样保留不 clobber。
+ * - **测试边界**（testing.md §4 定案）：glue 是全项目唯一无自动化测试的模块——
+ *   mock 宿主 = 重写宿主；验证 = 真宿主（锁定 v2 beta 快照）验证 + #21 人工验收。
+ *
+ * 零依赖纪律（入口既定）：不 import `@opencode-ai/plugin`，宿主 ctx 以本模块的
+ * 最小结构类型承接——字段名按 node_modules 实测的 beta d.ts 收窄到 glue 触达的
+ * 域，宿主漂移时真宿主验证即暴露，不为漂移预付兼容成本。
+ */
+/**
+ * v2 插件入口（default.setup）：自举 provider、模型与认证方法，并把共享运行时
+ * 接上宿主目录。幂等——插件热重载重跑 setup 时 transform 重放为 upsert、运行时
+ * 幂等构造、reload 回调重设到活 ctx。
+ */
+export declare function setupV2(context: unknown): Promise<void>;

package/dist/host/v2.js

@@ -0,0 +1,110 @@
+/**
+ * v2 宿主接线（#36；实测定案 #12/#5）。
+ *
+ * 用户 config 只写空壳 `{providers: {"commandcode-go": {}}}`，其余全部自举：
+ *
+ * - **catalog.transform 自指注册**（#12 S1 定案）：provider.update 设
+ *   `package = "aisdk:" + <入口模块 URL>`——宿主剥掉 `aisdk:` 前缀后原生 import
+ *   该文件，命中同一模块实例（instance seq 全程 = 1，伪装模块进程内状态安全
+ *   的前提）；锚点取入口模块的 `import.meta.url`（ENTRY_URL）而非 glue 子模块的
+ *   ——工厂判据「第一个 create* 导出」作用在入口模块上。`aisdk:<registry 包名>`
+ *   链路在 beta-18684 已死（UnsupportedPackageError），不用。模型按级联清单
+ *   update-or-create 注册：首播 = 包内快照（启动零阻塞），后台拉取签名变化触发
+ *   `catalog.reload()` 重放本 transform，届时 latestCascade 已是管线实时级联。
+ * - **integration.transform 认证**（#12 S2 定案）：为全新 provider upsert
+ *   integration（update 是 upsert，无需预存），注册 key 方法（/connect 粘贴）与
+ *   env 方法；凭证由宿主解析后经工厂 `apiKey` 注入，优先级 credential > env。
+ * - **modelsUrls v2 settings 通道**：用户写的 `settings.modelsUrls` 由宿主合并进
+ *   工厂 options 顶层（beta-18684 实测：transform 草稿不带 config settings，插件
+ *   侧构造时不可见），首次工厂调用经管线 rebindModelsUrls 接入（config > env >
+ *   默认列表，原值不变零开销跳过）；settings 壳其余字段原样保留不 clobber。
+ * - **测试边界**（testing.md §4 定案）：glue 是全项目唯一无自动化测试的模块——
+ *   mock 宿主 = 重写宿主；验证 = 真宿主（锁定 v2 beta 快照）验证 + #21 人工验收。
+ *
+ * 零依赖纪律（入口既定）：不 import `@opencode-ai/plugin`，宿主 ctx 以本模块的
+ * 最小结构类型承接——字段名按 node_modules 实测的 beta d.ts 收窄到 glue 触达的
+ * 域，宿主漂移时真宿主验证即暴露，不为漂移预付兼容成本。
+ */
+import { ENTRY_URL } from "../index.js";
+import { toV2ModelFields } from "../models/mapping.js";
+import { PROVIDER_ID } from "../protocol/envelope.js";
+import { ensureProviderRuntime, latestCascade } from "../provider/model.js";
+import { API_KEY_ENV_VAR, API_KEY_METHOD_LABEL, PROVIDER_DISPLAY_NAME } from "./constants.js";
+// ---------------------------------------------------------------------------
+// setup 接线
+// ---------------------------------------------------------------------------
+/**
+ * v2 插件入口（default.setup）：自举 provider、模型与认证方法，并把共享运行时
+ * 接上宿主目录。幂等——插件热重载重跑 setup 时 transform 重放为 upsert、运行时
+ * 幂等构造、reload 回调重设到活 ctx。
+ */
+export async function setupV2(context) {
+    const ctx = context;
+    await ctx.catalog.transform((draft) => {
+        draft.provider.update(PROVIDER_ID, (provider) => {
+            provider.name = PROVIDER_DISPLAY_NAME;
+            // 自指（#12 S1 定案）：aisdk: 前缀强制（漏写即 UnsupportedPackageError）；
+            // 锚点是入口模块 ENTRY_URL（create* 工厂判据所在），宿主再 import 同一路径
+            // 命中同一模块实例
+            provider.package = `aisdk:${ENTRY_URL}`;
+            provider.integrationID = PROVIDER_ID;
+            provider.activation = "auto";
+        });
+        // 模型注册（update-or-create）：目录键与上游 modelID 同为 wire id（可含 `/`）。
+        // 首播 = 包内快照（启动零阻塞）；后台拉取签名变化触发 catalog.reload() 重放本
+        // 回调，届时 latestCascade() 已是管线实时级联
+        for (const resolved of latestCascade().models.map(toV2ModelFields)) {
+            draft.model.update(PROVIDER_ID, resolved.id, (model) => {
+                model.id = resolved.id;
+                model.modelID = resolved.modelID;
+                model.name = resolved.name;
+                model.capabilities = {
+                    tools: true,
+                    input: [...resolved.capabilities.input],
+                    output: [...resolved.capabilities.output],
+                };
+                model.limit = { context: resolved.limit.context, output: resolved.limit.output };
+                // 严格透传（model-pipeline.md §3.1）：产物无档位即空数组，不造变体
+                model.variants = resolved.variants.map((variant) => ({
+                    id: variant.id,
+                    settings: { reasoningEffort: variant.settings.reasoningEffort },
+                }));
+                // 必填基线防御：字段归宿主 update-or-create 的 Model.Info 默认基线所有
+                // （cost 省略 = 不写价格，model-pipeline.md §3.2；基线缺位才补），已有值
+                // （含用户经 config 写入的 disabled）一律不覆盖
+                model.status ??= "active";
+                model.enabled ??= true;
+                model.time ??= { released: 0 };
+            });
+        }
+    });
+    // 认证方法（#12 S2 定案）：integration.update 为全新 provider upsert；key 方法
+    // 带 /connect 输入框 label，env 方法声明环境变量；integrationID 与 providerID
+    // 同名——凭证解析终点是工厂 options.apiKey，优先级 credential > env 由宿主保证
+    await ctx.integration.transform((draft) => {
+        draft.update(PROVIDER_ID, (integration) => {
+            integration.name = PROVIDER_DISPLAY_NAME;
+        });
+        draft.method.update({
+            integrationID: PROVIDER_ID,
+            method: { type: "key", label: API_KEY_METHOD_LABEL },
+        });
+        draft.method.update({
+            integrationID: PROVIDER_ID,
+            method: { type: "env", names: [API_KEY_ENV_VAR] },
+        });
+    });
+    // 共享运行时（模型管线 + 伪装状态单例）：注册全部完成后构造——变更回调只会晚于
+    // 此刻触发，reload 不会空放。构造时管线按 env/默认列表启动并后台首轮拉取（启动
+    // 零阻塞）；modelsUrls 的 config 通道（settings.modelsUrls）在 beta-18684 的
+    // transform 草稿上不可见（宿主在目录构建后才合并，实测探针 settings=null），它
+    // 由宿主合并进工厂 options、经首次工厂调用 rebindModelsUrls 接入管线
+    ensureProviderRuntime({
+        onModelDataChange: () => {
+            ctx.catalog.reload().catch((error) => {
+                // reload 失败目录停在上一份级联：打 warn 留痕，不打断后台刷新节奏
+                console.warn(`[commandcode-go] catalog.reload 失败（${String(error)}），目录沿用上一份级联`);
+            });
+        },
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @wallbreakerno4/opencode-commandcode 的入口骨架：单包三导出，v1/v2 双宿主共用。
+ *
+ * 形状即契约（防回归断言见 tests/package-shape.test.ts）：
+ * - default `{ id, setup, server }`——v2 宿主读 `id` + `setup`（接线实现在
+ *   src/host/v2.ts，#36）；v1 宿主加载器在 default 带 `id` 时要求 `server` 也在场，
+ *   缺 `server` 则整模块跳过并忽略全部命名导出（#11 真机实测），三键缺一不可。
+ *   v1 宿主是双轨形态：v1 加载器调 `server()`，内嵌 v2 运行时也调 `setup()`——
+ *   两条路共用同一模块实例与运行时单例，模式由先到者协商（接线实现 src/host/v1.ts，
+ *   #37）。
+ * - `createCommandCode` 工厂——v1/v2 共用的 provider 运行时入口，宿主按「模块
+ *   第一个 `create*` 前缀导出」判据发现它，不得引入排位更靠前的 `create*` 导出；
+ *   实现与其 options/provider 契约类型见 src/provider/model.ts（#35 工厂装配）。
+ *
+ * 入口保持零运行时依赖：不 import `@opencode-ai/plugin`（v2 的 define() 是恒等
+ * 函数），避免被宿主 beta API 漂移绑架。
+ */
+import { serverV1 } from "./host/v1.js";
+import { setupV2 } from "./host/v2.js";
+import type { V1Hooks } from "./host/v1.js";
+/**
+ * 入口模块自身的 file URL：v2 自指（#12 S1 定案）的锚点。宿主的 aisdk 工厂
+ * 判据（「模块第一个 create* 前缀导出」）作用在**本入口模块**上，glue 子模块的
+ * `import.meta.url` 指向 dist/host/v2.js，作 package 会半个月厂都找不到——必须
+ * 以本入口的 URL 为准，且宿主以此路径再 import 时命中同一模块实例（单实例，
+ * 伪装进程内状态安全的前提）。
+ */
+export declare const ENTRY_URL: string;
+/**
+ * 单包三导出的 default 形状。
+ * id 为字面量类型：该标识在 v2 插件 id、v1 config 注入键、integrationID、模型 id
+ * 前缀 `commandcode-go/<wire>` 四处同名，写错任何一处即编译失败。
+ */
+export interface CommandCodePlugin {
+    readonly id: "commandcode-go";
+    /** v2 插件入口：OpenCode 2 `setup(ctx)`（#36 宿主接线；v1 宿主的内嵌 v2 运行时同样调用） */
+    readonly setup: (context: unknown) => Promise<void> | void;
+    /** v1 插件入口：`server(input, options)` → hooks（options 为插件级配置，#37 宿主接线） */
+    readonly server: (input: unknown, options: unknown) => Promise<V1Hooks>;
+}
+export { createCommandCode, type CommandCodeFactoryOptions, type CommandCodeProvider } from "./provider/model.js";
+declare const _default: {
+    id: "commandcode-go";
+    setup: typeof setupV2;
+    server: typeof serverV1;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * @wallbreakerno4/opencode-commandcode 的入口骨架：单包三导出，v1/v2 双宿主共用。
+ *
+ * 形状即契约（防回归断言见 tests/package-shape.test.ts）：
+ * - default `{ id, setup, server }`——v2 宿主读 `id` + `setup`（接线实现在
+ *   src/host/v2.ts，#36）；v1 宿主加载器在 default 带 `id` 时要求 `server` 也在场，
+ *   缺 `server` 则整模块跳过并忽略全部命名导出（#11 真机实测），三键缺一不可。
+ *   v1 宿主是双轨形态：v1 加载器调 `server()`，内嵌 v2 运行时也调 `setup()`——
+ *   两条路共用同一模块实例与运行时单例，模式由先到者协商（接线实现 src/host/v1.ts，
+ *   #37）。
+ * - `createCommandCode` 工厂——v1/v2 共用的 provider 运行时入口，宿主按「模块
+ *   第一个 `create*` 前缀导出」判据发现它，不得引入排位更靠前的 `create*` 导出；
+ *   实现与其 options/provider 契约类型见 src/provider/model.ts（#35 工厂装配）。
+ *
+ * 入口保持零运行时依赖：不 import `@opencode-ai/plugin`（v2 的 define() 是恒等
+ * 函数），避免被宿主 beta API 漂移绑架。
+ */
+import { serverV1 } from "./host/v1.js";
+import { setupV2 } from "./host/v2.js";
+/**
+ * 入口模块自身的 file URL：v2 自指（#12 S1 定案）的锚点。宿主的 aisdk 工厂
+ * 判据（「模块第一个 create* 前缀导出」）作用在**本入口模块**上，glue 子模块的
+ * `import.meta.url` 指向 dist/host/v2.js，作 package 会半个月厂都找不到——必须
+ * 以本入口的 URL 为准，且宿主以此路径再 import 时命中同一模块实例（单实例，
+ * 伪装进程内状态安全的前提）。
+ */
+export const ENTRY_URL = import.meta.url;
+export { createCommandCode } from "./provider/model.js";
+export default {
+    id: "commandcode-go",
+    setup: setupV2,
+    server: serverV1,
+};

package/dist/models/api.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `/provider/v1/models` 响应的运行时解析（契约：docs/spec/model-pipeline.md §0/§3，
+ * 事实层：docs/research/model-metadata-sources.md §二实测形状）。
+ *
+ * 该端点是发现（id 清单）、`context_length` 与 `name` 的权威（§3 字段表），匿名
+ * 拉取即可。OpenAI 兼容样板字段 `object` / `owned_by` 与响应生成时刻的动态时间戳
+ * `created` 在此剥除——`created` 一旦流入下游，变更签名（模型管线 II）就必然每次
+ * 误判「列表变了」，所以在数据入口处结构性剔除，而不是靠下游记得跳过它。
+ */
+/** 单条发现：`name` / `contextLength` 现网 62/62 全有，类型上可选以容忍上游字段级缺失 */
+export interface ApiModelEntry {
+    readonly id: string;
+    readonly name?: string;
+    readonly contextLength?: number;
+}
+export type ModelsApiParseResult = {
+    readonly ok: true;
+    readonly models: readonly ApiModelEntry[];
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+export declare function parseModelsApi(input: unknown): ModelsApiParseResult;

package/dist/models/api.js

@@ -0,0 +1,44 @@
+/**
+ * `/provider/v1/models` 响应的运行时解析（契约：docs/spec/model-pipeline.md §0/§3，
+ * 事实层：docs/research/model-metadata-sources.md §二实测形状）。
+ *
+ * 该端点是发现（id 清单）、`context_length` 与 `name` 的权威（§3 字段表），匿名
+ * 拉取即可。OpenAI 兼容样板字段 `object` / `owned_by` 与响应生成时刻的动态时间戳
+ * `created` 在此剥除——`created` 一旦流入下游，变更签名（模型管线 II）就必然每次
+ * 误判「列表变了」，所以在数据入口处结构性剔除，而不是靠下游记得跳过它。
+ */
+import { asRecord } from "../protocol/json.js";
+export function parseModelsApi(input) {
+    const root = asRecord(input);
+    if (root === null)
+        return fail("顶层不是 JSON 对象");
+    const data = root["data"];
+    if (!Array.isArray(data))
+        return fail("data 必须是数组");
+    const models = [];
+    for (const [index, raw] of data.entries()) {
+        const entry = asRecord(raw);
+        if (entry === null)
+            return fail(`data[${index}] 不是对象`);
+        const id = entry["id"];
+        if (typeof id !== "string" || id.length === 0)
+            return fail(`data[${index}].id 必须是非空字符串`);
+        const name = entry["name"];
+        if (name !== undefined && typeof name !== "string")
+            return fail(`data[${index}]「${id}」.name 必须是字符串`);
+        const contextLength = entry["context_length"];
+        if (contextLength !== undefined &&
+            (typeof contextLength !== "number" || !Number.isFinite(contextLength) || contextLength <= 0)) {
+            return fail(`data[${index}]「${id}」.context_length 必须是正数`);
+        }
+        models.push({
+            id,
+            ...(name !== undefined ? { name } : {}),
+            ...(contextLength !== undefined ? { contextLength } : {}),
+        });
+    }
+    return { ok: true, models };
+}
+function fail(detail) {
+    return { ok: false, detail };
+}

package/dist/models/artifact.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 构建产物 schema v1 的运行时解析（契约：docs/spec/model-pipeline.md §1）。
+ *
+ * 产物经分发渠道以 JSON 到达运行时（拉取与缓存归模型管线 II，#34），本模块只负责
+ * 把未知形状的已解析 JSON 变成可信的 `Artifact`。三条硬规则：
+ * - 同版本内只允许新增可选字段：未知字段一律忽略、不搬运进解析结果（向前兼容）；
+ * - 遇到大于已知上限的 `schemaVersion`：整体弃用该产物（调用方降级到包内快照 +
+ *   告警），不做多版本兼容解析（§1.2）；
+ * - 必填字段缺失或类型不对：整个产物判 malformed 整体弃用，不做逐模型挑拣——
+ *   快照 = 最后已知良好产物，坏产物宁可整层让位（§5 的产物级降级粒度）。
+ *
+ * 产物形状的唯一出口在构建侧 `scripts/build-models/emit.ts`（其 `Artifact` 类型
+ * 为组装权威）；本文件为运行时侧独立定义——跨构建/运行时边界不共享编译单元，
+ * 两处字段须保持逐键兼容，改 schema 时两边同步。
+ */
+export interface ArtifactModel {
+    readonly id: string;
+    readonly name: string;
+    readonly reasoning: boolean;
+    readonly inputModalities: readonly string[];
+    readonly efforts?: readonly string[];
+    readonly context: number;
+    readonly maxOutput: number;
+}
+export interface Artifact {
+    readonly schemaVersion: 1;
+    readonly generatedAt: string;
+    readonly sourceCliVersion: string;
+    readonly models: readonly ArtifactModel[];
+}
+export type ArtifactParseResult = {
+    readonly ok: true;
+    readonly artifact: Artifact;
+} | {
+    readonly ok: false;
+    readonly error: ArtifactParseError;
+};
+export type ArtifactParseError = {
+    readonly reason: "future-version";
+    readonly schemaVersion: number;
+} | {
+    readonly reason: "malformed";
+    readonly detail: string;
+};
+export declare function parseArtifact(input: unknown): ArtifactParseResult;

package/dist/models/artifact.js

@@ -0,0 +1,108 @@
+/**
+ * 构建产物 schema v1 的运行时解析（契约：docs/spec/model-pipeline.md §1）。
+ *
+ * 产物经分发渠道以 JSON 到达运行时（拉取与缓存归模型管线 II，#34），本模块只负责
+ * 把未知形状的已解析 JSON 变成可信的 `Artifact`。三条硬规则：
+ * - 同版本内只允许新增可选字段：未知字段一律忽略、不搬运进解析结果（向前兼容）；
+ * - 遇到大于已知上限的 `schemaVersion`：整体弃用该产物（调用方降级到包内快照 +
+ *   告警），不做多版本兼容解析（§1.2）；
+ * - 必填字段缺失或类型不对：整个产物判 malformed 整体弃用，不做逐模型挑拣——
+ *   快照 = 最后已知良好产物，坏产物宁可整层让位（§5 的产物级降级粒度）。
+ *
+ * 产物形状的唯一出口在构建侧 `scripts/build-models/emit.ts`（其 `Artifact` 类型
+ * 为组装权威）；本文件为运行时侧独立定义——跨构建/运行时边界不共享编译单元，
+ * 两处字段须保持逐键兼容，改 schema 时两边同步。
+ */
+import { asRecord } from "../protocol/json.js";
+/** 运行时已知的产物 schema 上限；上游破坏性变更递增版本号后此处随之上调 */
+const KNOWN_ARTIFACT_SCHEMA_VERSION = 1;
+export function parseArtifact(input) {
+    const root = asRecord(input);
+    if (root === null)
+        return malformed("顶层不是 JSON 对象");
+    const version = root["schemaVersion"];
+    if (typeof version !== "number" || !Number.isInteger(version))
+        return malformed("schemaVersion 必须是整数");
+    if (version > KNOWN_ARTIFACT_SCHEMA_VERSION) {
+        return { ok: false, error: { reason: "future-version", schemaVersion: version } };
+    }
+    if (version !== KNOWN_ARTIFACT_SCHEMA_VERSION)
+        return malformed(`schemaVersion ${version} 低于已知下限`);
+    const generatedAt = root["generatedAt"];
+    if (typeof generatedAt !== "string" || generatedAt.length === 0)
+        return malformed("generatedAt 必须是非空字符串");
+    const sourceCliVersion = root["sourceCliVersion"];
+    if (typeof sourceCliVersion !== "string" || sourceCliVersion.length === 0) {
+        return malformed("sourceCliVersion 必须是非空字符串");
+    }
+    const rawModels = root["models"];
+    if (!Array.isArray(rawModels))
+        return malformed("models 必须是数组");
+    const models = [];
+    const seen = new Set();
+    for (const [index, raw] of rawModels.entries()) {
+        const entry = asRecord(raw);
+        if (entry === null)
+            return malformed(`models[${index}] 不是对象`);
+        const id = entry["id"];
+        if (typeof id !== "string" || id.length === 0)
+            return malformed(`models[${index}].id 必须是非空字符串`);
+        if (seen.has(id))
+            return malformed(`models[${index}].id「${id}」重复——id 是模型主键`);
+        seen.add(id);
+        const name = entry["name"];
+        if (typeof name !== "string" || name.length === 0)
+            return malformed(`models[${index}]「${id}」.name 必须是非空字符串`);
+        const reasoning = entry["reasoning"];
+        if (typeof reasoning !== "boolean")
+            return malformed(`models[${index}]「${id}」.reasoning 必须是布尔`);
+        const rawModalities = entry["inputModalities"];
+        const inputModalities = asStringArray(rawModalities);
+        if (inputModalities === null)
+            return malformed(`models[${index}]「${id}」.inputModalities 必须是字符串数组`);
+        const context = entry["context"];
+        if (typeof context !== "number" || !Number.isFinite(context) || context <= 0) {
+            return malformed(`models[${index}]「${id}」.context 必须是正数`);
+        }
+        const maxOutput = entry["maxOutput"];
+        if (typeof maxOutput !== "number" || !Number.isFinite(maxOutput) || maxOutput <= 0) {
+            return malformed(`models[${index}]「${id}」.maxOutput 必须是正数`);
+        }
+        const rawEfforts = entry["efforts"];
+        let efforts;
+        if (rawEfforts !== undefined) {
+            const parsed = asStringArray(rawEfforts);
+            if (parsed === null)
+                return malformed(`models[${index}]「${id}」.efforts 必须是字符串数组`);
+            efforts = parsed;
+        }
+        models.push({
+            id,
+            name,
+            reasoning,
+            inputModalities,
+            // efforts 无档位不写字段，与构建侧出口形状逐键一致
+            ...(efforts !== undefined ? { efforts } : {}),
+            context,
+            maxOutput,
+        });
+    }
+    return {
+        ok: true,
+        artifact: {
+            schemaVersion: 1,
+            generatedAt,
+            sourceCliVersion,
+            models,
+        },
+    };
+}
+function malformed(detail) {
+    return { ok: false, error: { reason: "malformed", detail } };
+}
+/** 字符串数组守卫：非数组或含非字符串项返回 null（空数组合法——语义由调用方定） */
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.every((item) => typeof item === "string") ? value : null;
+}

package/dist/models/cascade.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 运行时三层级联合并（契约：docs/spec/model-pipeline.md §3）。
+ *
+ * 原则：**每字段单一天窗**，权威 = 离网关事实最近的来源，包内快照永远最后（§3 字段表）：
+ * - 发现（暴露哪些 id）：API ∩ 产物层——产物拉取失败时快照顶替产物角色，交集规则
+ *   不变（「快照兜发现时同规则」）；API 整体失败时发现退化为产物层 id 清单。
+ * - `context` / `name`：API 权威（`context_length` 是网关实际执行值；name 同为
+ *   API 字段），字段级缺失时逐级回落产物 → 快照。
+ * - `efforts` / variants：产物层独供，无兜底链。
+ * - `reasoning` / `inputModalities` / `maxOutput`：产物层权威；「快照」兜底由产物
+ *   解析的整体弃用语义结构性保证——坏产物进不到本模块，只可能整层换成快照。
+ * - `tool_call`：常量 `true`，在宿主消费映射（mapping.ts）落键。
+ *
+ * 纯函数、无 I/O：拉取、TTL、变更签名与降级重试归模型管线 II（#34）；本模块只把
+ * 已解析的层合并成宿主消费映射的直接输入，并暴露产物层来源供降级日志注明退到了哪层。
+ */
+import type { ApiModelEntry } from "./api.js";
+import type { Artifact } from "./artifact.js";
+/**
+ * 级联解析后的单模型：字段取值已定天窗，是宿主消费映射（mapping.ts）的直接输入。
+ * 当前与 `ArtifactModel` 同构属有意为之——独立命名表达它是级联出口这个领域概念，
+ * 将来 API 独有字段落进运行时（如模型自报能力）后两边分化。
+ */
+export interface ResolvedModel {
+    readonly id: string;
+    readonly name: string;
+    readonly reasoning: boolean;
+    readonly inputModalities: readonly string[];
+    readonly efforts?: readonly string[];
+    readonly context: number;
+    readonly maxOutput: number;
+}
+export interface ModelLayers {
+    /** `/provider/v1/models` 解析结果；缺省 = API 失败，发现退化为产物层 id 清单 */
+    readonly api?: readonly ApiModelEntry[];
+    /** 构建产物；缺省 = 拉取/解析失败，快照顶替产物角色 */
+    readonly artifact?: Artifact;
+    /** 包内快照：与产物同 schema、随插件发版内置，永远可用 */
+    readonly snapshot: Artifact;
+}
+/** 产物角色由谁扮演——模型管线 II 的降级日志据此注明退到了哪层（§5） */
+export type ProductLayer = "artifact" | "snapshot";
+export interface CascadeResult {
+    readonly models: readonly ResolvedModel[];
+    readonly productLayer: ProductLayer;
+}
+export declare function mergeModelLayers(layers: ModelLayers): CascadeResult;