@dsh-plus/llm-pi 0.1.25 → 0.1.27

package/lib/client.js

@@ -168,7 +168,10 @@ window.__ModuleLoader__.load({
 			confirm: "Confirm",
 			cancel: "Cancel"
 		};
-		/** own 覆盖同键合并（返回新对象，入参不可变）。 */
+		/**
+		* own 覆盖同键合并（返回新对象，入参不可变）。
+		* 返回类型保留两侧键集合，调用方据此派生 DictKey。
+		*/
 		function mergeDict(base, own) {
 			return {
 				...base,
@@ -516,7 +519,7 @@ ${extra}
 			"retryPolicy",
 			"models"
 		]);
-		/** 摘出 wire 对象里卡片未认识的字段（undefined 值不保留）。 */
+		/** 摘出 wire 对象里卡片未认识的字段（undefined 值不保留；入参只要求是普通对象）。 */
 		function extraOf(wire, known) {
 			const out = {};
 			for (const [key, value] of Object.entries(wire)) if (!known.has(key) && value !== void 0) out[key] = value;
@@ -666,10 +669,11 @@ ${extra}
 		}
 		/** 提交补丁：完整配置对象，providers 全量替换；空值一律剔除。 */
 		function toPatch(draft) {
+			const refreshHours = toNum(draft.catalogRefreshHours);
 			return {
 				enabled: draft.enabled,
 				catalogUrl: draft.catalogUrl.trim(),
-				catalogRefreshHours: toNum(draft.catalogRefreshHours),
+				catalogRefreshHours: refreshHours,
 				catalogProxy: draft.catalogProxy.trim(),
 				providers: Object.fromEntries(Object.entries(draft.providers).map(([route, provider]) => [route, providerToWire(provider)]))
 			};
@@ -1029,6 +1033,7 @@ ${extra}
 						className: "lpc-grid",
 						children: fields.map((field) => {
 							const spec = compatFieldSpec(effective, field);
+							if (spec === void 0) return null;
 							if (spec === "boolean") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SelectField, {
 								id: `${props.idPrefix}-${field}`,
 								label: field,

package/lib/index.d.ts

@@ -4,13 +4,13 @@ import { Context } from "@deepseek-ai/cordis";
 /** settings 命名空间（字面量即合法命名空间，0.1.2-alpha.2 起编译期校验；webui 配置卡片与插件运行期读取同一份）。 */
 declare const SETTINGS_NS = "dsh-plus-llm-pi";
 /** 本插件可为手写 route 提供的协议实现（与官方 PROTOCOLS 表一致）。 */
-declare const PROTOCOL_IDS: readonly ["openai-completions", "openai-responses", "anthropic-messages"];
+declare const PROTOCOL_IDS: readonly ['openai-completions', 'openai-responses', 'anthropic-messages'];
 type ProtocolId = (typeof PROTOCOL_IDS)[number];
 /** pi-ai 思考档位，升级序。 */
-declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
-declare const MODALITIES: readonly ["text", "image"];
+declare const THINKING_LEVELS: readonly ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+declare const MODALITIES: readonly ['text', 'image'];
 /** 路由适配器种类：pi = PiAiAdapter（默认）；deepseek = 官方 DeepSeekAdapter（文件通道）。 */
-declare const ADAPTER_KINDS: readonly ["pi", "deepseek"];
+declare const ADAPTER_KINDS: readonly ['pi', 'deepseek'];
 type AdapterKind = (typeof ADAPTER_KINDS)[number];
 type ThinkingLevel = (typeof THINKING_LEVELS)[number];
 type Modality = (typeof MODALITIES)[number];
@@ -35,6 +35,13 @@ interface ProviderProfileConfig {
   extends?: string;
   displayName?: string;
   api?: ProtocolId;
+  /**
+   * 端点；缺省继承 extends 源 provider 的端点。
+   *
+   * 不并 `| undefined`：schemastery 的输入契约用 null 表示「显式置空」，省略即未设置；
+   * 消费方按 `baseURL ?? 默认值` 处理。并上 undefined 会与 ObjectS 的 `string | null`
+   * 冲突（exactOptionalPropertyTypes 下二者不可互赋）。
+   */
   baseURL?: string;
   apiKeyEnv?: string;
   headers?: Record<string, string>;
@@ -80,11 +87,16 @@ interface LlmPiConfig {
   catalogProxy: string;
   providers: Record<string, ProviderProfileConfig>;
 }
-declare const Config: z<LlmPiConfig>;
+/**
+ * schema 的宽松输入面：cordis 行级 config 与 settings 用户层都可能只给部分键
+ * （5 个根字段均有 schema 默认值），解析输出仍是完整的 {@link LlmPiConfig}。
+ */
+type LlmPiConfigInput = Partial<LlmPiConfig>;
+declare const Config: z<LlmPiConfigInput, LlmPiConfig>;
 //#endregion
 //#region src/index.d.ts
 declare const name = "dsh-plus-llm-pi";
-declare const inject: readonly ["credentials", "llm"];
+declare const inject: readonly ['credentials', 'llm'];
 declare function apply(ctx: Context, config: LlmPiConfig): Promise<void>;
 //#endregion
 export { Config, type LlmPiConfig, type ModelEntryConfig, type ProviderProfileConfig, SETTINGS_NS, apply, inject, name };

package/lib/index.js

@@ -66,7 +66,14 @@ const DEEPSEEK_REASONING_EFFORTS = [
 const DEEPSEEK_IMAGE_DETAILS = ["auto", "low"];
 /** dsh-timeout 的定时器上限（与官方 MAX_TIMER_DELAY_MS 对齐）。 */
 const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
-/** 键为可选档位，值为线协议拼写；仅 off 可留空（支持但不发送参数）。 */
+/**
+* 键为可选档位，值为线协议拼写；仅 off 可留空（支持但不发送参数）。
+*
+* 类型收窄说明：schemastery 的 z.dict 把输出推断为"全部键必填"（cosmokit 的
+* Dict 是不带可选修饰的映射类型），而运行期语义是"键可选"——profiles.ts 的
+* validateReasoningEfforts 按缺键 = 未声明处理，schema 也只校验给出的键。
+* 故此处只把该节点的类型标注回真实契约，schema 校验行为不变。
+*/
 const reasoningEfforts = z.dict(z.union([z.string(), z.const(null)]), z.union(THINKING_LEVELS));
 const thinkingBudgets = z.object({
 	minimal: z.number(),
@@ -151,7 +158,10 @@ const Config = z.object({
 function builtinProviderBaseUrl(kit, provider) {
 	return kit.builtinProviders().find((p) => p.id === provider)?.baseUrl;
 }
-/** 内置目录是否存在该 provider。 */
+/**
+* 内置目录是否存在该 provider；同时把运行期配置里的 provider 字符串
+* 收窄为目录键字面量（调用方随后可直调 getBuiltinModels）。
+*/
 function hasBuiltinProvider(kit, provider) {
 	return kit.getBuiltinProviders().includes(provider);
 }
@@ -699,7 +709,7 @@ function deepseekCatalogAnswer(kit, route) {
 	if (models.length === 0) throw new kit.LlmError("该 route 未配置 models 且未 extends deepseek；请手工录入模型", "DISCOVERY_FAILED");
 	return models;
 }
-/** 内置目录直答（route 配了 provider 级 extends 时）。 */
+/** 内置目录直答（route 配了 provider 级 extends 时；入参已由 hasBuiltinProvider 收窄）。 */
 function catalogAnswer(kit, source) {
 	return builtinModelIds(kit, source).map((id) => {
 		const model = kit.getBuiltinModels(source).find((m) => m.id === id);
@@ -719,7 +729,7 @@ function catalogAnswer(kit, source) {
 async function discoverModels(request, deps) {
 	const { kit } = deps;
 	const route = request.provider === void 0 ? void 0 : deps.configProviders()[request.provider];
-	if ((route?.adapter ?? "pi") === "deepseek") return deepseekCatalogAnswer(kit, route);
+	if (route !== void 0 && (route.adapter ?? "pi") === "deepseek") return deepseekCatalogAnswer(kit, route);
 	if (route?.extends !== void 0 && hasBuiltinProvider(kit, route.extends)) return catalogAnswer(kit, route.extends);
 	const baseURL = request.baseURL ?? route?.baseURL;
 	if (baseURL === void 0 || baseURL.length === 0) throw new kit.LlmError(`route ${JSON.stringify(request.provider ?? "")} 未配 baseURL 且 extends 源无内置目录；无法探测模型清单`, "DISCOVERY_FAILED");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/llm-pi",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "dsh-plus service+ui plugin: 基于 PiAiAdapter 的自定义 LLM 路由（全量 compat、模型继承、models.dev 目录兜底）",
   "type": "module",
   "main": "lib/index.js",
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "https-proxy-agent": "^9.1.0",
-    "@dsh-plus/shared": "0.1.14"
+    "@dsh-plus/shared": "0.1.16"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",

package/src/catalog/builtin.ts

@@ -28,14 +28,21 @@ export interface ModelBase {
   headers?: Record<string, string>
 }
 
+/** 内置目录的 provider id 字面量联合（pi-ai 生成目录的键集）。 */
+export type BuiltinProviderId = ReturnType<DshKit['getBuiltinProviders']>[number]
+
 /** 内置 provider 的端点（provider 级 extends 的 baseURL 缺省值）。 */
 export function builtinProviderBaseUrl(kit: DshKit, provider: string): string | undefined {
   return kit.builtinProviders().find((p) => p.id === provider)?.baseUrl
 }
 
-/** 内置目录是否存在该 provider。 */
-export function hasBuiltinProvider(kit: DshKit, provider: string): boolean {
-  return kit.getBuiltinProviders().includes(provider)
+/**
+ * 内置目录是否存在该 provider；同时把运行期配置里的 provider 字符串
+ * 收窄为目录键字面量（调用方随后可直调 getBuiltinModels）。
+ */
+export function hasBuiltinProvider(kit: DshKit, provider: string): provider is BuiltinProviderId {
+  const ids: readonly string[] = kit.getBuiltinProviders()
+  return ids.includes(provider)
 }
 
 /** 内置 provider 的全部模型 id（UI extends 选择器用）。 */

package/src/catalog/official.ts

@@ -15,7 +15,8 @@ export interface OfficialModelBase {
   contextWindow?: number
   maxTokens?: number
   input?: ('text' | 'image')[]
-  imagePixelBudget?: number
+  /** 官方目录取值为像素数或 'low' 预设（DeepSeekCatalogModel 同域；透传给官方 schema 校验）。 */
+  imagePixelBudget?: number | 'low'
   imageMaxBytes?: number
 }
 

package/src/client/card.tsx

@@ -26,15 +26,16 @@ import {
   type ProviderDraft,
   toPatch,
 } from './draft.ts'
+import type { Translate } from './i18n.ts'
 import { ProvidersSection } from './views/providers.tsx'
 
 export interface CardProps {
-  t(key: string): string
+  t: Translate
   scope: Scope
   api: NamespaceSettingsApi
 }
 
-function modelsDevText(status: WireModelsDevStatus | null, t: (key: string) => string): string {
+function modelsDevText(status: WireModelsDevStatus | null, t: Translate): string {
   if (status === null) return t('modelsDevEmpty')
   if (status.error !== null) return `${t('modelsDevError')}${status.error}`
   if (status.fetchedAt === null) return t('modelsDevEmpty')

package/src/client/client.ts

@@ -18,11 +18,11 @@ import type { Context } from '@deepseek-ai/cordis'
 import {
   createNamespaceApi,
   createSettingsScope,
-  type SettingsRemoteFace,
+  type PluginClientContext,
 } from '@dsh-plus/shared/client'
 import { SETTINGS_NS } from '../ns.ts'
 import { LlmPiCard } from './card.tsx'
-import { en, NS, zh } from './i18n.ts'
+import { type DictKey, en, NS, zh } from './i18n.ts'
 import { injectStyle } from './styles.ts'
 
 export const name = 'dsh-plus-llm-pi'
@@ -30,28 +30,8 @@ export const name = 'dsh-plus-llm-pi'
 /** 浏览器半需要的 cordis 服务 key（loader 据此注入；package.json 的 dsh.client.inject 管包加载顺序）。 */
 export const inject = ['slots', 'locale', 'remote', 'remote.settings'] as const
 
-interface SlotsLike {
-  inject(key: string, callback: () => unknown): unknown
-  register(options: Record<string, unknown>, component: unknown): () => void
-}
-
-interface LocaleLike {
-  register(ns: string, dict: { zh: Record<string, string>; en: Record<string, string> }): () => void
-  bind(ns: string): (key: string) => string
-}
-
-interface RemoteLike {
-  settings: SettingsRemoteFace
-  $on(event: string, listener: (payload?: unknown) => void): () => void
-}
-
-interface ClientContext {
-  slots: SlotsLike
-  locale: LocaleLike
-  get(key: 'remote'): RemoteLike
-  on(event: string, listener: () => void): () => void
-  effect(execute: () => () => void, label?: string): unknown
-}
+/** 宿主窄面收编在 @dsh-plus/shared/client；TKey 传入本包 DictKey 使键名受检。 */
+type ClientContext = PluginClientContext<DictKey>
 
 export function apply(ctx: Context): void {
   const c = ctx as unknown as ClientContext

package/src/client/draft.ts

@@ -206,8 +206,8 @@ const KNOWN_PROVIDER_KEYS = new Set([
   'models',
 ])
 
-/** 摘出 wire 对象里卡片未认识的字段（undefined 值不保留）。 */
-function extraOf(wire: Record<string, unknown>, known: Set<string>): Record<string, unknown> {
+/** 摘出 wire 对象里卡片未认识的字段（undefined 值不保留；入参只要求是普通对象）。 */
+function extraOf(wire: object, known: Set<string>): Record<string, unknown> {
   const out: Record<string, unknown> = {}
   for (const [key, value] of Object.entries(wire)) {
     if (!known.has(key) && value !== undefined) out[key] = value
@@ -225,7 +225,7 @@ function modelDraftFromWire(model: WireModel): ModelDraft {
     input: inputFromWire(model.input),
     reasoningEfforts: reasoningFromWire(model.reasoningEfforts),
     compat: { ...(model.compat ?? {}) },
-    extra: extraOf(model as Record<string, unknown>, KNOWN_MODEL_KEYS),
+    extra: extraOf(model, KNOWN_MODEL_KEYS),
   }
 }
 
@@ -268,7 +268,7 @@ function providerDraftFromWire(provider: WireProvider): ProviderDraft {
     maxRequestImageBytes: numToText(provider.maxRequestImageBytes),
     retryPolicy: provider.retryPolicy,
     models: (provider.models ?? []).map(modelDraftFromWire),
-    extra: extraOf(provider as Record<string, unknown>, KNOWN_PROVIDER_KEYS),
+    extra: extraOf(provider, KNOWN_PROVIDER_KEYS),
   }
 }
 
@@ -357,10 +357,14 @@ export function draftFromValue(value: ConfigValue): Draft {
 
 /** 提交补丁：完整配置对象，providers 全量替换；空值一律剔除。 */
 export function toPatch(draft: Draft): ConfigPatch {
+  const refreshHours = toNum(draft.catalogRefreshHours)
   return {
     enabled: draft.enabled,
     catalogUrl: draft.catalogUrl.trim(),
-    catalogRefreshHours: toNum(draft.catalogRefreshHours),
+    // 保存动作在文本非法时不可用（card.tsx 的 invalid 门控），故写入路径必为合法数字；
+    // dirty 比较路径可能拿到非法文本的 undefined（JSON.stringify 时同键被丢弃），
+    // 此处仅把"保存前已校验"的运行期事实带到类型层，取值不变。
+    catalogRefreshHours: refreshHours as unknown as number,
     catalogProxy: draft.catalogProxy.trim(),
     providers: Object.fromEntries(
       Object.entries(draft.providers).map(([route, provider]) => [route, providerToWire(provider)]),

package/src/client/fields.tsx

@@ -6,7 +6,7 @@
  */
 
 import { ChevronDownIcon } from '@dsh-plus/shared/client'
-import { type ReactElement, useEffect, useState } from 'react'
+import { type ReactElement, type ReactNode, useEffect, useState } from 'react'
 
 import type { HeaderPair } from './draft.ts'
 
@@ -20,7 +20,7 @@ export interface CollapseSectionProps {
   /** 默认展开态；复杂项传 false（默认折叠）。 */
   defaultOpen: boolean
   disabled?: boolean
-  children: ReactElement | ReactElement[] | null
+  children: ReactNode
 }
 
 export function CollapseSection(props: CollapseSectionProps): ReactElement {

package/src/client/i18n.ts

@@ -7,7 +7,7 @@ import { commonEn, commonZh, mergeDict } from '@dsh-plus/shared/client'
 
 export const NS = 'dsh-plus-llm-pi'
 
-const ownZh: Record<string, string> = {
+const ownZh = {
   title: 'LLM 路由（llm-pi）',
   description: '自定义 LLM 路由：协议、compat、模型目录与 models.dev 目录兜底。',
   enabled: '启用插件',
@@ -86,9 +86,9 @@ const ownZh: Record<string, string> = {
   catalogFailed: '目录加载失败。',
   saveOk: '已保存。',
   saveFailed: '保存失败：',
-}
+} as const
 
-const ownEn: Record<string, string> = {
+const ownEn = {
   title: 'LLM routes (llm-pi)',
   description: 'Custom LLM routes: protocol, compat, model catalog and models.dev fallback.',
   enabled: 'Enable plugin',
@@ -169,7 +169,13 @@ const ownEn: Record<string, string> = {
   catalogFailed: 'Failed to load catalog.',
   saveOk: 'Saved.',
   saveFailed: 'Save failed: ',
-}
+} as const
 
-export const zh: Record<string, string> = mergeDict(commonZh, ownZh)
-export const en: Record<string, string> = mergeDict(commonEn, ownEn)
+export type DictKey = keyof typeof commonZh | keyof typeof ownZh
+
+/** 卡片/面板共用的翻译函数类型（slot 注入的 bind 结果按此消费）。 */
+export type Translate = (key: DictKey) => string
+
+// 标注为 Record<DictKey, string>：en 缺任一键即编译期报错（中英强制对齐）。
+export const zh: Record<DictKey, string> = mergeDict(commonZh, ownZh)
+export const en: Record<DictKey, string> = mergeDict(commonEn, ownEn)

package/src/client/views/compat.tsx

@@ -9,6 +9,7 @@ import type { ReactElement } from 'react'
 
 import { COMPAT_FALLBACK_API, compatFieldSpec, compatFieldsOf } from '../constants.ts'
 import { CollapseSection, JsonField, SelectField } from '../fields.tsx'
+import type { Translate } from '../i18n.ts'
 
 /** api 变更后裁剪 compat：只保留新渲染组的字段，避免保存时被后端拒绝。 */
 export function pruneCompatForApi(
@@ -31,7 +32,7 @@ export interface CompatEditorProps {
   epoch: number
   disabled?: boolean
   wide?: boolean
-  t(key: string): string
+  t: Translate
   onEdit(next: Record<string, unknown>): void
 }
 
@@ -56,6 +57,8 @@ export function CompatEditor(props: CompatEditorProps): ReactElement {
         <div className="lpc-grid">
           {fields.map((field) => {
             const spec = compatFieldSpec(effective, field)
+            // 键取自同一张表（compatFieldsOf），spec 不可能为 undefined；此处仅收窄类型
+            if (spec === undefined) return null
             if (spec === 'boolean') {
               return (
                 <SelectField

package/src/client/views/models.tsx

@@ -11,11 +11,12 @@ import { fetchCatalog, type WireModelsDevStatus } from '../api.ts'
 import { MODALITIES, THINKING_LEVELS } from '../constants.ts'
 import { emptyModelDraft, type ModelDraft, type ReasoningDraft } from '../draft.ts'
 import { TextField } from '../fields.tsx'
+import type { Translate } from '../i18n.ts'
 import { CompatEditor } from './compat.tsx'
 
 type CatalogSource = 'builtin' | 'models-dev'
 
-function catalogNote(status: WireModelsDevStatus | undefined, t: (key: string) => string): string {
+function catalogNote(status: WireModelsDevStatus | undefined, t: Translate): string {
   if (status === undefined) return ''
   if (status.error !== null) return `${t('modelsDevError')}${status.error}`
   return `${t('modelsDevStatusLine')}：${status.providers} 个 provider，快照 ${status.fetchedAt ?? '-'}`
@@ -29,7 +30,7 @@ export interface ModelsTableProps {
   models: ModelDraft[]
   epoch: number
   disabled?: boolean
-  t(key: string): string
+  t: Translate
   onModels(next: ModelDraft[]): void
 }
 
@@ -158,7 +159,7 @@ export interface ModelRowProps {
   listId: string
   epoch: number
   disabled?: boolean
-  t(key: string): string
+  t: Translate
   onPatch(patch: Partial<ModelDraft>): void
   onRemove(): void
 }
@@ -268,7 +269,7 @@ export interface ReasoningEditorProps {
   idPrefix: string
   value: ReasoningDraft
   disabled?: boolean
-  t(key: string): string
+  t: Translate
   onEdit(next: ReasoningDraft): void
 }
 

package/src/client/views/provider-fields.tsx

@@ -17,13 +17,14 @@ import {
 } from '../constants.ts'
 import type { ProviderDraft } from '../draft.ts'
 import { SelectField, TextField } from '../fields.tsx'
+import type { Translate } from '../i18n.ts'
 import { pruneCompatForApi } from './compat.tsx'
 
 export interface ProviderScalarFieldsProps {
   id: string
   draft: ProviderDraft
   disabled?: boolean
-  t(key: string): string
+  t: Translate
   onPatch(patch: Partial<ProviderDraft>): void
 }
 

package/src/client/views/providers.tsx

@@ -10,6 +10,7 @@ import { type ReactElement, useState } from 'react'
 
 import type { ProviderDraft } from '../draft.ts'
 import { CollapseSection, JsonField, KeyValueEditor } from '../fields.tsx'
+import type { Translate } from '../i18n.ts'
 import { CompatEditor } from './compat.tsx'
 import { ModelsTable } from './models.tsx'
 import { ProviderScalarFields, ProviderSelectFields } from './provider-fields.tsx'
@@ -18,7 +19,7 @@ export interface ProvidersSectionProps {
   providers: Record<string, ProviderDraft>
   epoch: number
   disabled?: boolean
-  t(key: string): string
+  t: Translate
   onAddRoute(key: string): void
   onRemoveRoute(route: string): void
   onPatchProvider(route: string, patch: Partial<ProviderDraft>): void
@@ -86,7 +87,7 @@ export interface ProviderSectionProps {
   draft: ProviderDraft
   epoch: number
   disabled?: boolean
-  t(key: string): string
+  t: Translate
   onRemove(): void
   onPatch(patch: Partial<ProviderDraft>): void
 }

package/src/config-api.ts

@@ -8,6 +8,7 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
 
 import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
 
 import { builtinModelIds } from './catalog/builtin.ts'
 import type { LlmPiRuntime } from './service.ts'

package/src/config.ts

@@ -52,8 +52,18 @@ export const DEFAULT_REQUEST_IMAGE_MAX_BYTES = 1024 * 1024
 /** dsh-timeout 的定时器上限（与官方 MAX_TIMER_DELAY_MS 对齐）。 */
 export const MAX_TIMER_DELAY_MS = 2 ** 31 - 1
 
-/** 键为可选档位，值为线协议拼写；仅 off 可留空（支持但不发送参数）。 */
-const reasoningEfforts = z.dict(z.union([z.string(), z.const(null)]), z.union(THINKING_LEVELS))
+/**
+ * 键为可选档位，值为线协议拼写；仅 off 可留空（支持但不发送参数）。
+ *
+ * 类型收窄说明：schemastery 的 z.dict 把输出推断为"全部键必填"（cosmokit 的
+ * Dict 是不带可选修饰的映射类型），而运行期语义是"键可选"——profiles.ts 的
+ * validateReasoningEfforts 按缺键 = 未声明处理，schema 也只校验给出的键。
+ * 故此处只把该节点的类型标注回真实契约，schema 校验行为不变。
+ */
+const reasoningEfforts = z.dict(
+  z.union([z.string(), z.const(null)]),
+  z.union(THINKING_LEVELS),
+) as unknown as z<ReasoningEfforts>
 
 export type ThinkingLevel = (typeof THINKING_LEVELS)[number]
 export type Modality = (typeof MODALITIES)[number]
@@ -80,6 +90,13 @@ export interface ProviderProfileConfig {
   extends?: string
   displayName?: string
   api?: ProtocolId
+  /**
+   * 端点；缺省继承 extends 源 provider 的端点。
+   *
+   * 不并 `| undefined`：schemastery 的输入契约用 null 表示「显式置空」，省略即未设置；
+   * 消费方按 `baseURL ?? 默认值` 处理。并上 undefined 会与 ObjectS 的 `string | null`
+   * 冲突（exactOptionalPropertyTypes 下二者不可互赋）。
+   */
   baseURL?: string
   apiKeyEnv?: string
   headers?: Record<string, string>
@@ -127,6 +144,12 @@ export interface LlmPiConfig {
   providers: Record<string, ProviderProfileConfig>
 }
 
+/**
+ * schema 的宽松输入面：cordis 行级 config 与 settings 用户层都可能只给部分键
+ * （5 个根字段均有 schema 默认值），解析输出仍是完整的 {@link LlmPiConfig}。
+ */
+export type LlmPiConfigInput = Partial<LlmPiConfig>
+
 const thinkingBudgets = z.object({
   minimal: z.number(),
   low: z.number(),
@@ -302,7 +325,7 @@ const providerProfile = z.object({
     .description('本 route 的模型目录；缺省且 provider 有 extends 时继承该源全部模型'),
 })
 
-export const Config: z<LlmPiConfig> = z.object({
+export const Config: z<LlmPiConfigInput, LlmPiConfig> = z.object({
   enabled: z.boolean().description('总开关（关闭则不注册任何 route）').default(true),
   catalogUrl: z
     .string()

package/src/discovery.ts

@@ -6,7 +6,7 @@
  * GET {baseURL}/models、4MB 上限、署名头）与官方一致。结果不落盘。
  * @module llm-pi/discovery
  */
-import { builtinModelIds, hasBuiltinProvider } from './catalog/builtin.ts'
+import { type BuiltinProviderId, builtinModelIds, hasBuiltinProvider } from './catalog/builtin.ts'
 import { officialModelIds } from './catalog/official.ts'
 import type { ProviderProfileConfig } from './config.ts'
 import type { DshKit } from './resolve-dsh.ts'
@@ -129,8 +129,8 @@ function deepseekCatalogAnswer(kit: DshKit, route: ProviderProfileConfig): Disco
   return models
 }
 
-/** 内置目录直答（route 配了 provider 级 extends 时）。 */
-function catalogAnswer(kit: DshKit, source: string): DiscoveryEntry[] {
+/** 内置目录直答（route 配了 provider 级 extends 时；入参已由 hasBuiltinProvider 收窄）。 */
+function catalogAnswer(kit: DshKit, source: BuiltinProviderId): DiscoveryEntry[] {
   return builtinModelIds(kit, source).map((id) => {
     const models = kit.getBuiltinModels(source)
     const model = models.find((m) => m.id === id)
@@ -155,7 +155,9 @@ export async function discoverModels(
   const { kit } = deps
   const route: ProviderProfileConfig | undefined =
     request.provider === undefined ? undefined : deps.configProviders()[request.provider]
-  if ((route?.adapter ?? 'pi') === 'deepseek') {
+  // route 为空时 (route?.adapter ?? 'pi') 恒为 'pi'，故显式判空不改变分支结果，
+  // 只用于把 route 收窄为已定义（供 deepseekCatalogAnswer 使用）。
+  if (route !== undefined && (route.adapter ?? 'pi') === 'deepseek') {
     return deepseekCatalogAnswer(kit, route)
   }
   if (route?.extends !== undefined && hasBuiltinProvider(kit, route.extends)) {

package/src/profiles.ts

@@ -628,7 +628,10 @@ export function resolveProfilesFallback(
         name: displayName,
         ...(source.baseURL === undefined ? {} : { baseUrl: source.baseURL }),
         auth: { apiKey: harnessApiKeyAuth(displayName) },
-        models,
+        // 物化条目的 compat 是开放字典（写时经 validateCompat 按 api 门控校验），
+        // 与 pi-ai Model 的逐协议 compat 类型不同构；运行期仅由 pi-ai 按字段读取，
+        // 形状与官方 resolveProfiles 产物一致，故此处按目标契约收窄。
+        models: models as unknown as Parameters<DshKit['createProvider']>[0]['models'],
         api: factory() as never,
       }),
     } as ResolvedPiAiProviderProfile)

package/src/resolve-dsh.ts

@@ -131,7 +131,12 @@ function assertKitShape(kit: DshKit, origin: string): void {
       'prepareCall',
       'providerRetryPolicy',
     ] as const) {
-      if (typeof (kit.PiAiAdapter.prototype as Record<string, unknown>)[method] !== 'function') {
+      // 原型方法存在性自检：类实例的原型在运行期是普通对象，按方法名索引读取安全
+      // （类类型本身无索引签名，故经 unknown 转字典视图；形状由本函数逐项断言）。
+      if (
+        typeof (kit.PiAiAdapter.prototype as unknown as Record<string, unknown>)[method] !==
+        'function'
+      ) {
         problems.push(`PiAiAdapter.prototype.${method} 缺失`)
       }
     }
@@ -164,7 +169,9 @@ function checkDeepseekShape(kit: DeepSeekKit): string[] {
   const problems: string[] = []
   if (typeof kit.DeepSeekAdapter !== 'function') problems.push('DeepSeekAdapter 不是类')
   else if (
-    typeof (kit.DeepSeekAdapter.prototype as Record<string, unknown>)['stream'] !== 'function'
+    // 同 assertKitShape：原型方法存在性自检，经 unknown 转字典视图读取。
+    typeof (kit.DeepSeekAdapter.prototype as unknown as Record<string, unknown>)['stream'] !==
+    'function'
   ) {
     problems.push('DeepSeekAdapter.prototype.stream 缺失')
   }

package/src/service.ts

@@ -12,6 +12,7 @@
 import type { Context } from '@deepseek-ai/cordis'
 import type { CredentialRef } from '@deepseek-ai/dsh-credentials'
 import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment'
+import type { DirectoryRegistrationHandle } from '@deepseek-ai/dsh-llm'
 import type { ResolvedPiAiProviderProfile } from '@deepseek-ai/dsh-llm-pi-ai'
 import type {} from '@deepseek-ai/dsh-settings'
 import { deepEqualJson } from '@deepseek-ai/dsh-util-values'
@@ -237,7 +238,7 @@ export async function startRuntime(ctx: Context, rawConfig: LlmPiConfig): Promis
     registeredFacts = facts
   }
 
-  let directory: { replace: (entries: unknown[]) => void } | undefined
+  let directory: DirectoryRegistrationHandle | undefined
   let directoryFacts: unknown
   /** 草稿路由（无模型占位）从原始配置直读——它们不进 adapter profiles。 */
   const draftRoutes = (): { route: string; displayName: string }[] => {
@@ -263,8 +264,7 @@ export async function startRuntime(ctx: Context, rawConfig: LlmPiConfig): Promis
     }
     commitDirectory(
       (batch: DirectoryEntry[]) => {
-        if (directory === undefined)
-          directory = ctx.llm.registerConfigurableProviders(batch as never)
+        if (directory === undefined) directory = ctx.llm.registerConfigurableProviders(batch)
         else directory.replace(batch)
       },
       entries,