@sema-agent/client-core 0.77.1 → 0.77.2

package/dist/model/catalog.d.ts

@@ -1,135 +1,36 @@
-/**
- * catalog.ts — **模型 provider 目录的三层源解析**(design/160 需求②,2026-07-31)。
- *
- * ## 它解决什么
- *
- * `providerPresets.json` 是**编译进包的静态表**:加一家 provider、改一个 model 的 cap,都得发一次
- * client-core。而三端(CLI / web / 桌面)要的是同一份目录、可在线更新、离线仍能用。本模块把
- * 设计档 §需求② 的三层源做成一个**纯解析器**:
- *
- * ```
- *   ① 线上目录(URL 由调用方传入 —— 本文件零默认地址,见下「为什么不写死 URL」)
- *        ↓ 拉取失败 / 离线 / 校验不过(整份弃用)
- *   ② 包内兜底 = PROVIDER_PRESETS(零改动即兜底)
- *        ↓
- *   ③ 用户本地覆盖(自定义 provider,合并语义:同 id 用户 > 线上 > 包内)
- * ```
- *
- * ## 四条设计纪律(每条都在 pure 门 MC 段有断言)
- *
- * 1. **零 Node、零自发网络**:本文件不 import 任何 `node:*`,也**不碰全局 `fetch`** ——
- *    网络能力由调用方注入 `fetchJson` 端口。宿主没给 ⇒ 线上腿整条不启用(`reason: 'no-fetch-port'`),
- *    而不是「偷偷换个方式做」(与 host.ts 的缺席语义同一条纪律)。
- *    ⇒ 桌面渲染进程 / 浏览器 / TUI 用同一份代码,各自注入自己的传输。
- * 2. **绝不半解析**(设计档明写):`schemaVersion` 超出支持区间、`providers` 不是数组、
- *    **任何一行**形状不合格 ⇒ **整份**线上目录弃用走兜底。半解析 = 用户拿到一张自己也说不清
- *    是哪一版的表。
- * 3. **来源标注是产品位不是调试位**:返回值恒带 `source` 与 `online.{ok,reason}`。端据此渲
- *    「目录为内置版本(离线)」——「静默用兜底」在本层必须是**可观测**的,否则用户会以为看到的
- *    是最新表([honest-absence-not-fabricated-zero])。
- * 4. **诚实缺席**:`staleness` 只在真吃到线上目录时在场;`ageMs` 只在调用方给了 `nowMs`
- *    且 `generatedAt` 可解析时在场。不知道就是键缺席,绝不 `?? 0`,也绝不偷读时钟
- *    (时钟是宿主资产,与 `AdapterContext.now` 同一条口径)。
- *
- * ## 为什么不写死线上 URL
- *
- * 目录仓位(设计档待裁点 3:`sema-agent/model-catalog` 公开仓 or release asset)**候 clay 裁**。
- * 机制先行、地址后填:URL 由调用方从配置/settings 传入。本文件里出现任何默认地址,都会让
- * 「还没定的仓位」提前变成事实契约。https-only 是硬校验(目录是会被下载并影响**出站地址**的
- * 数据,明文信道下可被改写成钓鱼网关)。
- *
- * ## 本批不做(留口注释,别当遗漏)
- *
- * · **缓存与 ETag**:`~/.sema/cache/model-catalog.json` + ETag/304 + 新鲜窗 + `localGeneratedAt`
- *   防降级(设计档 pi 调研节)。落盘是宿主能力(fs 在 host.ts 的 `FsPort`),所以缓存层应当是
- *   **本模块之上**的一层:调用方拿 `resolveModelCatalog` 的结果自行落盘,并把上次的 `generatedAt`
- *   与新拉到的比较后决定是否替换。⇒ 加缓存时**不需要**改本文件的形状,只需在 `fetchJson` 注入
- *   处做 ETag,并在外层加一个「旧远端压不过新包」的比较。
- * · **签名 / sha256**:同上,属传输层与目录产出方的约定(设计档待裁点 3)。
- * · **`oauth` / `subscribe` 字段**:设计档待裁点 3b。本批只加纯链接位 `consoleUrl`/`signupUrl`
- *   (见 providerPresets.ts),授权码流/设备码流一律不进。
- *
- * ## probe 复用面评估(设计档 §需求②-C「复用面」;只评估不搬,搬迁下一批做)
- *
- * 桌面端 onboard 要「选 provider → 填 key → 探活」,探活那一步现在只在壳树。按
- * [multiclient-migration-batch-discipline](模块级状态与读写口同包)逐个评估,结论如下 ——
- * 这是下一批的搬迁清单,坐标为壳树 `src/sema/onboard/`:
- *
- * | 文件 | 结论 | 依据 |
- * |---|---|---|
- * | `probePlan.ts`(139 行) | ✅ **整搬,零改造** | 零 import、零模块级状态、纯函数四件(`buildVerdictRequest` / `extractApiError` / `looksLikeModelError` / `judgeMessagesProbe`)。判决表本身就是「三端必须一致」的那部分。 |
- * | `probeProvider.ts`(223 行) | ⚠️ **拆搬**:判定+请求编排进包、传输与 TLS 留端 | ①裸 `fetch`/`AbortController`/`setTimeout` ⇒ 改注入 `fetchImpl`(本包既有姿势:`limitsWire`/`detachWire`/`liveInitToolFace` 的 `opts.fetchImpl`);②`ensureProxyBootstrap()` 动态 import 壳的 `utils/proxy.js`(`configureGlobalAgents`)= **Node undici 专属**,浏览器无此概念 ⇒ 留端,做成可选的「拨号前置钩子」端口;③`isCertError`/`applySystemTlsTrust`(壳 `tlsTrust.ts`,读系统钥匙串 + 设 `NODE_EXTRA_CA_CERTS`)= 纯 Node ⇒ 留端,做成可选的「一次性重试钩子」;④`nearestListed()` 与 `unwrapFetchError()` 是纯函数 ⇒ 直接进包。搬后包内出口 ≈ `probeProvider({ baseUrl, api, apiKey, modelId }, { fetchImpl, beforeDial?, retryOnCertError? })`。 |
- * | `detectSources.ts`(524 行) | ❌ **本批不搬** | 它整个是**宿主文件系统扫描器**:`node:fs`(existsSync/readdirSync/readFileSync/statSync)+ `node:os` homedir + `node:path` + `process.env` + 两个外部解析器(`jsonc-parser`/`yaml`)+ 壳内 `ccConfigFallback`。可搬的只有「读到的配置 → `ImportableProvider` 的分类/归一逻辑」那一小半,而它与扫描代码是逐行交织的。⇒ 要搬得先在壳里把「扫描(IO)」与「分类(纯)」拆开,是独立一批的量。**桌面端不阻塞**:桌面 onboard 的导入源探测本就该是主进程的活(与 CLI 同为 Node 侧),复用价值远低于 probe 两件。 |
- * | `onboardZeroModel.ts`(2.8K) | 🔶 **顺路可搬** | 已有独立单测(`onboardZeroModel.test.ts`),看形状是纯判定;搬前需确认零壳态依赖。 |
- * | `applyOnboard.ts` / `OnboardWizard.tsx` / `BigStepTitle.tsx` / `ccSwitchReader.ts` | ❌ 属端 | 落盘编排 / Ink 渲染 / 读 cc-switch sqlite —— 宿主辖区,桌面端各写各的渲染器(设计档 §C 与 pi 的 `AuthInteraction` seam 同一心智)。 |
- *
- * 搬迁批建议顺序:`probePlan`(零风险打头,先让包里有判决表)→ `probeProvider` 拆搬(带
- * fetchImpl 注入 + 两个可选钩子端口)→ `onboardZeroModel` → detectSources 拆分单列一批。
- */
 import { type ProviderPreset } from './providerPresets.js';
-/** 支持的目录 schemaVersion 区间(闭区间)。产目录那一方按这个区间发版。 */
 export declare const CATALOG_SCHEMA_VERSION_MIN = 1;
 export declare const CATALOG_SCHEMA_VERSION_MAX = 1;
-/** 线上目录文档的信封形。`providers` 与包内表**同形**(ProviderPreset),所以两层可直接按 id 合并。 */
 export interface OnlineCatalogDoc {
     schemaVersion: number;
-    /** 目录生成时刻(ISO8601)。用于端渲新鲜度;不可解析也不弃用整份(它不是契约位)。 */
     generatedAt: string;
     providers: ProviderPreset[];
 }
-/**
- * 结果的来源标注 = **最高优先级的在场层**:
- * · `merged` —— 用户覆盖层真的贡献了行(不管线上腿成没成);
- * · `online` —— 线上目录被接受且无用户覆盖;
- * · `bundled` —— 只有包内表(离线 / 线上被拒 / 没配 URL)。
- */
 export type CatalogSource = 'online' | 'bundled' | 'merged';
-/** 线上腿被拒的**具体**理由(端可据此分诊:是没配、是离线、还是目录本身坏了)。 */
 export type CatalogRejectReason = 'no-online-url' | 'no-fetch-port' | 'insecure-url' | 'fetch-failed' | 'payload-not-object' | 'schema-version-missing' | 'schema-version-unsupported' | 'generated-at-missing' | 'providers-not-array' | 'provider-row-invalid';
-/** 线上腿的结局。`ok: true` 时不带 `reason`(枚举互斥)。 */
 export interface CatalogOnlineOutcome {
     ok: boolean;
     reason?: CatalogRejectReason;
-    /**
-     * 拒绝细节(人话,给分诊用)。🔴 只放判决相关的短语与被截断的错误 message,
-     * **绝不回显载荷本身**([credential-error-path-leak]:错误路径是凭证外泄的经典入口;
-     * 目录 URL 本身是公开物,但宿主注入的 fetchJson 可能带鉴权头,所以异常只取 message 前段)。
-     */
     detail?: string;
 }
-/** 线上目录的新鲜度。只在真吃到线上目录时在场。 */
 export interface CatalogStaleness {
-    /** 目录自述的生成时刻,原样透传(烂串也原样给端,由端决定怎么说)。 */
     generatedAt: string;
-    /** 距今毫秒。只在调用方给了 `nowMs` 且 `generatedAt` 可解析时在场 —— 不知道就键缺席。 */
     ageMs?: number;
 }
 export interface ModelCatalogResult {
-    /** 合并后的 provider 表(新数组;包内表绝不被就地改写)。 */
     providers: ProviderPreset[];
     source: CatalogSource;
     staleness?: CatalogStaleness;
     online: CatalogOnlineOutcome;
-    /** 用户覆盖层真正贡献的 provider id(替换的 + 新增的)。无覆盖 ⇒ 空数组。 */
     overrideIds: string[];
 }
-/**
- * 注入式取 JSON 端口 —— **本包唯一的线上目录取数口**。
- * 约定:2xx ⇒ resolve 已解析的 JSON;其它一切(网络错 / 非 2xx / 解析失败)⇒ reject。
- * ETag/304、超时、代理、鉴权头全归宿主(它们各端形态不同,见文件头「本批不做」)。
- */
 export type CatalogFetchJson = (url: string) => Promise<unknown>;
 export interface ResolveModelCatalogOptions {
-    /** 线上目录 URL。缺席 ⇒ 线上腿不启用(本包零默认地址)。必须是 https。 */
     onlineUrl?: string;
-    /** 取数口。缺席 ⇒ 线上腿不启用(本包绝不自己碰 fetch)。 */
     fetchJson?: CatalogFetchJson;
-    /** 用户本地覆盖(自定义 provider)。同 id 恒赢线上与包内。 */
     overrides?: readonly ProviderPreset[];
-    /** 当前时刻(宿主时钟)。缺席 ⇒ 不算 ageMs(而不是自己读 Date.now)。 */
     nowMs?: number;
 }
-/** schemaVersion 是否落在支持区间内(非整数一律否)。 */
 export declare function isSupportedCatalogSchemaVersion(v: unknown): boolean;
 export type ValidateCatalogResult = {
     ok: true;
@@ -139,20 +40,8 @@ export type ValidateCatalogResult = {
     reason: CatalogRejectReason;
     detail?: string;
 };
-/**
- * 校验线上载荷 —— **纯同步**,端可以单用(比如「刷新目录」按钮先本地校验再落盘)。
- * 🔴 全或无:任何一条不合格 ⇒ 整份拒,绝不半解析。
- */
 export declare function validateOnlineCatalog(payload: unknown): ValidateCatalogResult;
-/**
- * 按 id 分层合并:**后来的层赢**,行序 = 首见序(包内序稳定在前,新家按层依次追加)。
- * 纯函数,端可以单用(比如只合并「包内 + 用户覆盖」的离线路径)。
- */
 export declare function mergeProviderLayers<T extends {
     id: string;
 }>(...layers: readonly (readonly T[])[]): T[];
-/**
- * 解析出一份可用的 provider 目录 —— 三层源 + 来源标注。**永不 reject**:线上腿的任何失败都
- * 收敛成 `online.ok === false` 并回落包内表(离线可用是硬需求)。
- */
 export declare function resolveModelCatalog(opts?: ResolveModelCatalogOptions): Promise<ModelCatalogResult>;

package/dist/model/catalog.js

@@ -1,76 +1,6 @@
-/**
- * catalog.ts — **模型 provider 目录的三层源解析**(design/160 需求②,2026-07-31)。
- *
- * ## 它解决什么
- *
- * `providerPresets.json` 是**编译进包的静态表**:加一家 provider、改一个 model 的 cap,都得发一次
- * client-core。而三端(CLI / web / 桌面)要的是同一份目录、可在线更新、离线仍能用。本模块把
- * 设计档 §需求② 的三层源做成一个**纯解析器**:
- *
- * ```
- *   ① 线上目录(URL 由调用方传入 —— 本文件零默认地址,见下「为什么不写死 URL」)
- *        ↓ 拉取失败 / 离线 / 校验不过(整份弃用)
- *   ② 包内兜底 = PROVIDER_PRESETS(零改动即兜底)
- *        ↓
- *   ③ 用户本地覆盖(自定义 provider,合并语义:同 id 用户 > 线上 > 包内)
- * ```
- *
- * ## 四条设计纪律(每条都在 pure 门 MC 段有断言)
- *
- * 1. **零 Node、零自发网络**:本文件不 import 任何 `node:*`,也**不碰全局 `fetch`** ——
- *    网络能力由调用方注入 `fetchJson` 端口。宿主没给 ⇒ 线上腿整条不启用(`reason: 'no-fetch-port'`),
- *    而不是「偷偷换个方式做」(与 host.ts 的缺席语义同一条纪律)。
- *    ⇒ 桌面渲染进程 / 浏览器 / TUI 用同一份代码,各自注入自己的传输。
- * 2. **绝不半解析**(设计档明写):`schemaVersion` 超出支持区间、`providers` 不是数组、
- *    **任何一行**形状不合格 ⇒ **整份**线上目录弃用走兜底。半解析 = 用户拿到一张自己也说不清
- *    是哪一版的表。
- * 3. **来源标注是产品位不是调试位**:返回值恒带 `source` 与 `online.{ok,reason}`。端据此渲
- *    「目录为内置版本(离线)」——「静默用兜底」在本层必须是**可观测**的,否则用户会以为看到的
- *    是最新表([honest-absence-not-fabricated-zero])。
- * 4. **诚实缺席**:`staleness` 只在真吃到线上目录时在场;`ageMs` 只在调用方给了 `nowMs`
- *    且 `generatedAt` 可解析时在场。不知道就是键缺席,绝不 `?? 0`,也绝不偷读时钟
- *    (时钟是宿主资产,与 `AdapterContext.now` 同一条口径)。
- *
- * ## 为什么不写死线上 URL
- *
- * 目录仓位(设计档待裁点 3:`sema-agent/model-catalog` 公开仓 or release asset)**候 clay 裁**。
- * 机制先行、地址后填:URL 由调用方从配置/settings 传入。本文件里出现任何默认地址,都会让
- * 「还没定的仓位」提前变成事实契约。https-only 是硬校验(目录是会被下载并影响**出站地址**的
- * 数据,明文信道下可被改写成钓鱼网关)。
- *
- * ## 本批不做(留口注释,别当遗漏)
- *
- * · **缓存与 ETag**:`~/.sema/cache/model-catalog.json` + ETag/304 + 新鲜窗 + `localGeneratedAt`
- *   防降级(设计档 pi 调研节)。落盘是宿主能力(fs 在 host.ts 的 `FsPort`),所以缓存层应当是
- *   **本模块之上**的一层:调用方拿 `resolveModelCatalog` 的结果自行落盘,并把上次的 `generatedAt`
- *   与新拉到的比较后决定是否替换。⇒ 加缓存时**不需要**改本文件的形状,只需在 `fetchJson` 注入
- *   处做 ETag,并在外层加一个「旧远端压不过新包」的比较。
- * · **签名 / sha256**:同上,属传输层与目录产出方的约定(设计档待裁点 3)。
- * · **`oauth` / `subscribe` 字段**:设计档待裁点 3b。本批只加纯链接位 `consoleUrl`/`signupUrl`
- *   (见 providerPresets.ts),授权码流/设备码流一律不进。
- *
- * ## probe 复用面评估(设计档 §需求②-C「复用面」;只评估不搬,搬迁下一批做)
- *
- * 桌面端 onboard 要「选 provider → 填 key → 探活」,探活那一步现在只在壳树。按
- * [multiclient-migration-batch-discipline](模块级状态与读写口同包)逐个评估,结论如下 ——
- * 这是下一批的搬迁清单,坐标为壳树 `src/sema/onboard/`:
- *
- * | 文件 | 结论 | 依据 |
- * |---|---|---|
- * | `probePlan.ts`(139 行) | ✅ **整搬,零改造** | 零 import、零模块级状态、纯函数四件(`buildVerdictRequest` / `extractApiError` / `looksLikeModelError` / `judgeMessagesProbe`)。判决表本身就是「三端必须一致」的那部分。 |
- * | `probeProvider.ts`(223 行) | ⚠️ **拆搬**:判定+请求编排进包、传输与 TLS 留端 | ①裸 `fetch`/`AbortController`/`setTimeout` ⇒ 改注入 `fetchImpl`(本包既有姿势:`limitsWire`/`detachWire`/`liveInitToolFace` 的 `opts.fetchImpl`);②`ensureProxyBootstrap()` 动态 import 壳的 `utils/proxy.js`(`configureGlobalAgents`)= **Node undici 专属**,浏览器无此概念 ⇒ 留端,做成可选的「拨号前置钩子」端口;③`isCertError`/`applySystemTlsTrust`(壳 `tlsTrust.ts`,读系统钥匙串 + 设 `NODE_EXTRA_CA_CERTS`)= 纯 Node ⇒ 留端,做成可选的「一次性重试钩子」;④`nearestListed()` 与 `unwrapFetchError()` 是纯函数 ⇒ 直接进包。搬后包内出口 ≈ `probeProvider({ baseUrl, api, apiKey, modelId }, { fetchImpl, beforeDial?, retryOnCertError? })`。 |
- * | `detectSources.ts`(524 行) | ❌ **本批不搬** | 它整个是**宿主文件系统扫描器**:`node:fs`(existsSync/readdirSync/readFileSync/statSync)+ `node:os` homedir + `node:path` + `process.env` + 两个外部解析器(`jsonc-parser`/`yaml`)+ 壳内 `ccConfigFallback`。可搬的只有「读到的配置 → `ImportableProvider` 的分类/归一逻辑」那一小半,而它与扫描代码是逐行交织的。⇒ 要搬得先在壳里把「扫描(IO)」与「分类(纯)」拆开,是独立一批的量。**桌面端不阻塞**:桌面 onboard 的导入源探测本就该是主进程的活(与 CLI 同为 Node 侧),复用价值远低于 probe 两件。 |
- * | `onboardZeroModel.ts`(2.8K) | 🔶 **顺路可搬** | 已有独立单测(`onboardZeroModel.test.ts`),看形状是纯判定;搬前需确认零壳态依赖。 |
- * | `applyOnboard.ts` / `OnboardWizard.tsx` / `BigStepTitle.tsx` / `ccSwitchReader.ts` | ❌ 属端 | 落盘编排 / Ink 渲染 / 读 cc-switch sqlite —— 宿主辖区,桌面端各写各的渲染器(设计档 §C 与 pi 的 `AuthInteraction` seam 同一心智)。 |
- *
- * 搬迁批建议顺序:`probePlan`(零风险打头,先让包里有判决表)→ `probeProvider` 拆搬(带
- * fetchImpl 注入 + 两个可选钩子端口)→ `onboardZeroModel` → detectSources 拆分单列一批。
- */
 import { PROVIDER_PRESETS } from './providerPresets.js';
-/** 支持的目录 schemaVersion 区间(闭区间)。产目录那一方按这个区间发版。 */
 export const CATALOG_SCHEMA_VERSION_MIN = 1;
 export const CATALOG_SCHEMA_VERSION_MAX = 1;
-/** schemaVersion 是否落在支持区间内(非整数一律否)。 */
 export function isSupportedCatalogSchemaVersion(v) {
     return (typeof v === 'number' &&
         Number.isInteger(v) &&
@@ -89,10 +19,6 @@ function isProviderRow(v) {
         typeof r.authEnv === 'string' &&
         Array.isArray(r.models));
 }
-/**
- * 校验线上载荷 —— **纯同步**,端可以单用(比如「刷新目录」按钮先本地校验再落盘)。
- * 🔴 全或无:任何一条不合格 ⇒ 整份拒,绝不半解析。
- */
 export function validateOnlineCatalog(payload) {
     if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
         return { ok: false, reason: 'payload-not-object', detail: 'catalog payload is not a JSON object' };
@@ -119,7 +45,6 @@ export function validateOnlineCatalog(payload) {
         return {
             ok: false,
             reason: 'provider-row-invalid',
-            // 只报**位置**不报内容:载荷是外部数据,回显 = 把不可信内容带进日志面。
             detail: `provider row #${bad} failed the shape gate (whole document rejected — no partial parse)`,
         };
     }
@@ -132,10 +57,6 @@ export function validateOnlineCatalog(payload) {
         },
     };
 }
-/**
- * 按 id 分层合并:**后来的层赢**,行序 = 首见序(包内序稳定在前,新家按层依次追加)。
- * 纯函数,端可以单用(比如只合并「包内 + 用户覆盖」的离线路径)。
- */
 export function mergeProviderLayers(...layers) {
     const order = [];
     const byId = new Map();
@@ -156,19 +77,13 @@ export function mergeProviderLayers(...layers) {
     }
     return out;
 }
-/** https-only(目录会影响出站地址,明文信道可被改写成钓鱼网关)。 */
 function isHttpsUrl(u) {
     return /^https:\/\/\S+$/i.test(u.trim());
 }
-/** 异常 → 短 detail(只取 message 前段,绝不带栈、绝不带载荷)。 */
 function shortError(e) {
     const msg = e instanceof Error ? e.message : String(e);
     return msg.slice(0, 160);
 }
-/**
- * 解析出一份可用的 provider 目录 —— 三层源 + 来源标注。**永不 reject**:线上腿的任何失败都
- * 收敛成 `online.ok === false` 并回落包内表(离线可用是硬需求)。
- */
 export async function resolveModelCatalog(opts) {
     const overrides = opts?.overrides ?? [];
     let onlineDoc = null;
@@ -181,11 +96,9 @@ export async function resolveModelCatalog(opts) {
         online = { ok: false, reason: 'no-fetch-port', detail: 'host did not install a fetchJson port' };
     }
     else if (!isHttpsUrl(url)) {
-        // 🔴 校验在拨号**之前**:非 https 连请求都不发。
         online = { ok: false, reason: 'insecure-url', detail: 'online catalog URL must be https' };
     }
     else {
-        // 单发不重试:重试/超时预算属宿主传输层(注入的 fetchJson 自己带)。
         let payload;
         let dialFailure = null;
         try {

package/dist/model/catalogLoader.d.ts

@@ -1,164 +1,50 @@
-/**
- * catalogLoader.ts — **目录候选链的宿主 loader**(design/166 §1-§3,2026-08-04)。
- *
- * ## 它与 `catalog.ts` 的分工(🔴 委托,不平行重做)
- *
- * `catalog.ts` 已经是三层源解析器:`resolveModelCatalog`(线上→包内→用户覆盖三层合并)+
- * `validateOnlineCatalog`(schemaVersion 区间 / 逐行 `isProviderRow` / **绝不半解析** / 不回显载荷)
- * + `CatalogFetchJson` 注入端口 + `CatalogSource`·`CatalogRejectReason` 两张词表。
- * 本文件**只补 catalog.ts 声明不管的宿主面**,四件事:
- *
- *   ① **候选链遍历**(`DEFAULT_CATALOG_SOURCES` = raw.githubusercontent → jsDelivr,可配);
- *   ② **传输安全硬门**:https + 域白名单(拨号**之前**判,域外源连请求都不发)——
- *      而且**重定向目标过同一道门**(fetch 默认跟随重定向,不设门 = 白名单可被 302 绕过);
- *   ③ **`catalog.sha256` 旁签**(同源同路径,SHA-256 hex 比对);
- *   ④ **缓存**(`configHome/cache/model-catalog.json`)的信封与读回语义。
- *
- * 载荷面的判决(schemaVersion / 逐行形状 / 整份弃 / 不回显)**一行都不在这里重写** ——
- * 本文件拿到字节流之后做的唯一一件事是 `JSON.parse`,然后把结果交给 `resolveModelCatalog`,
- * 由它去 `validateOnlineCatalog`。UI 渲染也只认 `ModelCatalogResult.source` + `online.reason`
- * (+ 本文件加的 `cacheHit`),**不发明第二套 origin 词表**。
- *
- * ## 🔴 为什么缓存的**落盘动作**在宿主而不在这里(与设计档 §3 的偏差,记在这)
- *
- * 设计档 §3 写的是「loader 原子写(tmp+rename)」。但本包有一条机械门守着的硬法:
- * `src/**` 的 index 值级闭包**零 Node 内建**(`scripts/run-client-core-portability-test.mjs`
- * ①c 段),因为同一份代码要在浏览器/桌面渲染进程里跑。`node:fs` 一进来,那道门当场红。
- * ⇒ 落盘走**注入口** `CatalogCachePort`(与 `host.ts` 的 `FsPort`、`catalog.ts` 的
- * `CatalogFetchJson` 同一条纪律:能力由宿主注入,库不自己 `require('fs')`)。
- * **tmp+rename 的原子性是 `writeAtomic` 实现方的契约**,本文件在类型注释里把它写成要求;
- * Node 宿主的十行参考实现见 `CatalogCachePort.writeAtomic` 的注释。
- * 缺席该口 ⇒ 缓存腿整条不启用(`cacheHit` 键**缺席**,不是 `false` —— 「没查过」和「查过没用上」
- * 是两件事,[honest-absence-not-fabricated-zero])。
- *
- * ## 🔴 `forceRefresh` 为什么没有(与设计档 §1 签名的偏差)
- *
- * 本 loader **恒先走网络**,缓存只在候选链**全败**时顶上(设计档 §3 自己就是这么定的读时机)。
- * 也就是说没有任何一条「优先吃缓存」的路径可供 `forceRefresh` 去绕过 —— 收下这个参数只会
- * 得到一个恒为空操作的旋钮,而空操作的旋钮是**假 affordance**(调用方以为自己强制刷新了)。
- * 真要「手动刷新」,直接再调一次本函数就是最新语义。
- *
- * ## 时钟
- *
- * 与 `catalog.ts` 同一口径:**绝不偷读时钟**。`nowMs` 缺席 ⇒ 缓存信封不写 `fetchedAt`、
- * 陈旧判定不做(`cacheStale` 键缺席),而不是 `Date.now()` 兜底。
- */
 import { type EnvLike } from '../hostEnv.js';
 import { type ModelCatalogResult, type OnlineCatalogDoc } from './catalog.js';
 import type { ProviderPreset } from './providerPresets.js';
-/**
- * 默认候选链(design/166 §1;clay 裁「可配置,默认 github」)。
- * 第二跳 jsDelivr 对 gh 仓是被动 CDN、零接入成本 —— 这就是大陆可达性的零维护替身。
- * 🔴 顺序即优先级:逐源尝试,前一跳成了就不拨下一跳。
- */
 export declare const DEFAULT_CATALOG_SOURCES: readonly string[];
-/** 默认域白名单 = 默认链两跳的 host。用户显式配置的源 host 在运行期并入(用户自担)。 */
 export declare const CATALOG_DEFAULT_HOSTS: readonly string[];
-/** 候选链的 env 键(一键安装脚本改这里;settings.json `env` 块同名同义,见 design/166 §2)。 */
 export declare const CATALOG_SOURCES_ENV = "SEMA_CATALOG_SOURCES";
-/**
- * 单源的**传输层**结局。
- *
- * 🔴 它**不是**第二套 origin 词表:UI 渲染「目录从哪来」恒读 `ModelCatalogResult.source` +
- * `online.reason` + `cacheHit`。本词表只服务于 **doctor 的逐源分诊**(「两跳分别为什么没成」),
- * 那是 `catalog.ts` 的单 URL 视角在结构上说不出来的量 —— 它只有一个 `online` 结局位。
- */
 export type CatalogSourceOutcome = 'ok' | 'insecure-url' | 'host-not-allowed' | 'redirect-blocked' | 'redirect-opaque' | 'redirect-loop' | 'http-error' | 'network-error' | 'invalid-json' | 'sha-mismatch';
-/** 一次逐源尝试的留痕(doctor 用;🔴 绝不带载荷内容,只带判决与被截断的 message)。 */
 export interface CatalogSourceAttempt {
     url: string;
     outcome: CatalogSourceOutcome;
-    /** HTTP 状态码(只在真收到响应时在场)。 */
     status?: number;
-    /** 旁签是否**真的比对过**(只在 `outcome:'ok'` 时在场;false = sha 拿不到,已记 warn 放行)。 */
     shaChecked?: boolean;
-    /** 人话细节(判决相关短语 / 被截断的错误 message)。 */
     detail?: string;
 }
-/** 缓存文件的信封(design/166 §3)。`fetchedAt` 缺席 = 写入时宿主没给时钟。 */
 export interface CatalogCacheEnvelope {
     fetchedAt?: number;
     sourceUrl: string;
     catalog: OnlineCatalogDoc;
 }
-/**
- * 缓存口 —— 宿主注入(本包零 `node:fs`,理由见文件头)。
- *
- * `writeAtomic` 的契约是**原子替换**(临时文件 + rename),不是 `writeFile` 的别名:
- * 半截文件会让下一次冷启动读到一份坏缓存。Node 宿主的参考实现:
- * ```js
- * async writeAtomic(path, text) {
- *   await mkdir(dirname(path), { recursive: true })
- *   const tmp = `${path}.${process.pid}.tmp`
- *   await writeFile(tmp, text, 'utf8')
- *   await rename(tmp, path)     // 同目录 rename = 原子
- * }
- * ```
- * 两个动词都允许同步或异步实现;抛异常由 loader 收成 warning(缓存是纵深,不是主路径)。
- */
 export interface CatalogCachePort {
     read(path: string): string | null | Promise<string | null>;
     writeAtomic(path: string, text: string): void | Promise<void>;
 }
-/** `loadCatalogWithSources` 的入参。 */
 export interface LoadCatalogOptions {
-    /** 缓存落点的根(`configHome/cache/model-catalog.json`)。缺席 ⇒ 缓存腿不启用。 */
     configHome?: string;
-    /** 覆盖候选链(缺省 `DEFAULT_CATALOG_SOURCES`;env 恒赢本项,见 `resolveCatalogSources`)。 */
     sources?: readonly string[];
-    /** 宿主 env(缺省 `hostEnv()`)。 */
     env?: EnvLike;
-    /** 每源传输预算(缺省 `DEFAULT_CATALOG_TIMEOUT_MS`)。 */
     timeoutMs?: number;
-    /** 宿主时钟。缺席 ⇒ 不算 ageMs、不写 fetchedAt、不判 stale(绝不偷读时钟)。 */
     nowMs?: number;
-    /** 传输注入口(缺省全局 `fetch`;本包既有姿势 = limitsWire/detachWire 的 `fetchImpl`)。 */
     fetchImpl?: typeof fetch;
-    /** 缓存口。缺席 ⇒ 缓存腿整条不启用(`cacheHit` 键缺席)。 */
     cache?: CatalogCachePort;
-    /** 用户本地覆盖层,原样透传给 `resolveModelCatalog`。 */
     overrides?: readonly ProviderPreset[];
 }
-/**
- * 结果 = `ModelCatalogResult`(来源标注/新鲜度/合并表全归 catalog.ts)+ 宿主面四位。
- * 🔴 只**加**位不改位:端渲染仍读 `source` / `online.reason`。
- */
 export interface LoadedModelCatalog extends ModelCatalogResult {
-    /** 真正被吃下的那一跳(线上成功或缓存自述的来源);全败 ⇒ 缺席。 */
     sourceUrl?: string;
-    /** 这份线上载荷是不是从缓存顶上来的。**缓存口缺席 ⇒ 本键缺席**(没查过 ≠ 查过没用上)。 */
     cacheHit?: boolean;
-    /** 缓存是否已过 30 天(照用但如实标)。只在 `cacheHit:true` 且宿主给了时钟时在场。 */
     cacheStale?: boolean;
-    /** 逐源留痕(doctor 分诊用)。 */
     attempts: CatalogSourceAttempt[];
-    /** 非致命的诚实记账(sha 拿不到 / 缓存读写失败 / 缓存半截)。 */
     warnings: string[];
 }
-/** `SEMA_CATALOG_SOURCES` 的逗号列表解析(去空白、丢空项;缺席 ⇒ 空列表)。 */
 export declare function parseCatalogSources(raw: string | undefined | null): string[];
-/** `resolveCatalogSources` 的入参。 */
 export interface ResolveCatalogSourcesOptions {
     env?: EnvLike;
     sources?: readonly string[];
 }
-/**
- * 候选链优先级(design/166 §2,高→低):env `SEMA_CATALOG_SOURCES` > 调用方(settings)> 默认链。
- * 🔴 「配了但解析出空列表」按**没配**处理:空链会把目录腿整条静默关掉,而调用方以为自己配了。
- */
 export declare function resolveCatalogSources(opts?: ResolveCatalogSourcesOptions): string[];
-/**
- * 传输面硬门:**https + host 在白名单内**。拨号之前判 —— 不合格的地址连请求都不发。
- * 🔴 白名单是**域**的门、https 是**协议**的门,两道都要过:白名单里的 host 走 http 照样拒
- * (明文信道下目录可被改写成钓鱼网关,而目录决定的正是出站地址)。
- */
 export declare function isAllowedCatalogUrl(url: string, allowedHosts: ReadonlySet<string>): boolean;
-/** 旁签地址 = 同源同路径换后缀(design/165 §4:`dist/catalog.sha256`)。 */
 export declare function catalogShaUrlFor(catalogUrl: string): string;
-/** 缓存文件绝对路径(design/166 §3)。POSIX 分隔符 —— Node 侧 `path.join` 对它是幂等的。 */
 export declare function catalogCachePath(configHome: string): string;
-/**
- * 解析出一份可用的 provider 目录 —— **候选链 + 传输硬门 + 旁签 + 缓存**,载荷判决全委托
- * `resolveModelCatalog`。🔴 **永不 reject**:onboard 不能因为网络死。
- */
 export declare function loadCatalogWithSources(opts?: LoadCatalogOptions): Promise<LoadedModelCatalog>;