@dsh-plus/llm-pi 0.1.13 → 0.1.14

package/lib/index.js

@@ -5,12 +5,13 @@ import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
 import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
 import { request } from "node:http";
 import { request as request$1 } from "node:https";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import HttpsProxyAgentModule from "https-proxy-agent";
-import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import { credentialKeyId, credentialKeyScope, credentialRef, isCredentialKeySegment, isCredentialRefName } from "@deepseek-ai/dsh-credentials";
 import { pathToFileURL } from "node:url";
 import * as vendoredAnonId from "@deepseek-ai/dsh-anonymous-user-id";
 import * as vendoredLlm from "@deepseek-ai/dsh-llm";
+import { LlmError } from "@deepseek-ai/dsh-llm";
 import * as vendoredDeepseek from "@deepseek-ai/dsh-llm-deepseek";
 import * as vendoredPiAiAdapter from "@deepseek-ai/dsh-llm-pi-ai";
 import * as vendoredPiAi from "@earendil-works/pi-ai";
@@ -18,6 +19,8 @@ import { anthropicMessagesApi } from "@earendil-works/pi-ai/api/anthropic-messag
 import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
 import { openAIResponsesApi } from "@earendil-works/pi-ai/api/openai-responses.lazy";
 import * as vendoredCatalog from "@earendil-works/pi-ai/providers/all";
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
 //#endregion
 //#region src/config.ts
 /**
@@ -59,6 +62,7 @@ const DEEPSEEK_REASONING_EFFORTS = [
 	"high",
 	"max"
 ];
+/** 旧版 imageDetail 枚举（0.1.2-alpha.1 已移除该字段；仅用于 schema 透传陷阱的取值集）。 */
 const DEEPSEEK_IMAGE_DETAILS = ["auto", "low"];
 /** dsh-timeout 的定时器上限（与官方 MAX_TIMER_DELAY_MS 对齐）。 */
 const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
@@ -87,7 +91,7 @@ const modelEntry = z.object({
 	compat: compatDict.description("模型级 compat（字段级合并，压过 route 级与继承值）"),
 	imagePixelBudget: z.number().step(1).min(1).description("（仅 adapter: deepseek）单张请求图片的总像素预算；缺省继承官方目录"),
 	imageMaxBytes: z.number().step(1).min(1).description("（仅 adapter: deepseek）单张请求图片的编码字节上限；缺省继承官方目录"),
-	imageDetail: z.union(DEEPSEEK_IMAGE_DETAILS).description("（仅 adapter: deepseek）图片细节档位；low 使用 512x512 像素预算")
+	imageDetail: z.union(DEEPSEEK_IMAGE_DETAILS).description("（已移除）图片细节档位；0.1.2-alpha.1 起请改用 imagePixelBudget/imageMaxBytes")
 });
 const providerProfile = z.object({
 	adapter: z.union(ADAPTER_KINDS).description("路由适配器：pi=PiAiAdapter（默认，三协议）；deepseek=官方 DeepSeekAdapter（图片走 Files API 文件通道，失败自动降级 base64）").default("pi"),
@@ -117,7 +121,9 @@ const providerProfile = z.object({
 	timeoutMs: z.natural().description("HTTP/provider 超时毫秒"),
 	websocketConnectTimeoutMs: z.natural().description("WebSocket 连接超时毫秒"),
 	streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).description("单支流式读取的最大空闲间隔毫秒"),
-	maxRequestImageBytes: z.natural().description("单请求 base64 图片载荷上限字节；缺省 20MiB（rc8 起生效，旧配置免改）"),
+	maxRequestImageBytes: z.natural().description("单请求 base64 图片载荷上限字节；缺省 20MiB（0.1.2-alpha.1 起官方必需字段，旧配置免改）"),
+	requestImagePixelBudget: z.number().step(1).min(1).description("单请求每个确定性内联图片版本的像素总预算；缺省 2048x2048（官方同值）"),
+	requestImageMaxBytes: z.number().step(1).min(1).description("内联图片版本编码字节目标；缺省 1MiB（官方同值）"),
 	retryPolicy: z.any().description("provider 重试策略（dsh-llm RetryPolicy 形状，构建期校验）"),
 	thinking: z.union(DEEPSEEK_THINKING).description("（仅 adapter: deepseek）思考模式开关；缺省用提供商默认"),
 	reasoningEffort: z.union(DEEPSEEK_REASONING_EFFORTS).description("（仅 adapter: deepseek）推理档位；缺省为 high"),
@@ -494,7 +500,14 @@ var DeepseekRouteRegistrar = class {
 			},
 			resolveApiKey: this.resolveApiKey,
 			resolveUserId: () => this.resolveUserId(),
-			resolveAttachments: () => ctx.get("attachments")
+			resolveAttachments: () => ctx.get("attachments"),
+			resolveImageAccess: (attachments, ref) => kit.resolveImageAttachmentAccess(attachments, (hostPath) => ctx.get("fs")?.processPathFromHostPath(hostPath), ref),
+			prepareExtensions: (request) => {
+				return ctx.get("deepseekLlmApiExtensions")?.prepare(request) ?? Promise.resolve({
+					fields: {},
+					accept: () => Promise.resolve()
+				});
+			}
 		});
 		adapter.providerInfo = (provider) => ({
 			id: provider,
@@ -586,8 +599,7 @@ function catalogOf(kit) {
 		...model.maxTokens === void 0 ? {} : { maxTokens: model.maxTokens },
 		...model.inputModalities === void 0 ? {} : { input: [...model.inputModalities] },
 		...model.imagePixelBudget === void 0 ? {} : { imagePixelBudget: model.imagePixelBudget },
-		...model.imageMaxBytes === void 0 ? {} : { imageMaxBytes: model.imageMaxBytes },
-		...model.imageDetail === void 0 ? {} : { imageDetail: model.imageDetail }
+		...model.imageMaxBytes === void 0 ? {} : { imageMaxBytes: model.imageMaxBytes }
 	});
 	const catalog = {
 		baseUrl: resolved.baseURL,
@@ -749,71 +761,106 @@ async function discoverModels(request, deps) {
 }
 //#endregion
 //#region src/compat.ts
-const FIELDS_BY_PROTOCOL = {
+const GATES_BY_PROTOCOL = {
 	"openai-completions": {
-		supportsStore: "boolean",
-		supportsDeveloperRole: "boolean",
-		supportsReasoningEffort: "boolean",
-		supportsUsageInStreaming: "boolean",
-		maxTokensField: ["max_completion_tokens", "max_tokens"],
-		requiresToolResultName: "boolean",
-		requiresAssistantAfterToolResult: "boolean",
-		requiresThinkingAsText: "boolean",
-		requiresReasoningContentOnAssistantMessages: "boolean",
-		thinkingFormat: [
-			"openai",
-			"openrouter",
-			"deepseek",
-			"together",
-			"zai",
-			"qwen",
-			"chat-template",
-			"qwen-chat-template",
-			"string-thinking",
-			"ant-ling"
-		],
-		chatTemplateKwargs: "object",
-		openRouterRouting: "object",
-		vercelGatewayRouting: "object",
-		zaiToolStream: "boolean",
-		supportsOpenAIGrammarTools: "boolean",
-		supportsStrictMode: "boolean",
-		cacheControlFormat: ["anthropic"],
-		sendSessionAffinityHeaders: "boolean",
-		deferredToolsMode: ["kimi"],
-		sessionAffinityFormat: [
-			"openai",
-			"openai-nosession",
-			"openrouter"
-		],
-		supportsLongCacheRetention: "boolean"
+		supportsStore: "offer",
+		supportsDeveloperRole: "offer",
+		supportsReasoningEffort: "offer",
+		supportsUsageInStreaming: "offer",
+		supportsFinishReason: "offer",
+		maxTokensField: "offer",
+		requiresToolResultName: "offer",
+		requiresAssistantAfterToolResult: "offer",
+		requiresThinkingAsText: "offer",
+		requiresReasoningContentOnAssistantMessages: "offer",
+		thinkingFormat: "offer",
+		chatTemplateKwargs: "offer",
+		chatTemplateArgs: "offer",
+		supportsThinkingTokenBudget: "offer",
+		supportsStrictMode: "offer",
+		cacheControlFormat: "offer",
+		supportsLongCacheRetention: "offer",
+		openRouterRouting: "withhold",
+		vercelGatewayRouting: "withhold",
+		zaiToolStream: "withhold",
+		supportsOpenAIGrammarTools: "withhold",
+		sendSessionAffinityHeaders: "withhold",
+		deferredToolsMode: "withhold",
+		sessionAffinityFormat: "withhold"
 	},
 	"openai-responses": {
-		supportsDeveloperRole: "boolean",
-		sessionAffinityFormat: [
-			"openai",
-			"openai-nosession",
-			"openrouter"
-		],
-		supportsLongCacheRetention: "boolean",
-		supportsStrictMode: "boolean",
-		supportsOpenAIGrammarTools: "boolean",
-		supportsToolSearch: "boolean",
-		supportsExplicitPromptCacheMode: "boolean"
+		supportsDeveloperRole: "offer",
+		supportsStrictMode: "offer",
+		supportsLongCacheRetention: "offer",
+		sessionAffinityFormat: "withhold",
+		supportsOpenAIGrammarTools: "withhold",
+		supportsAdditionalTools: "withhold",
+		supportsToolSearch: "withhold",
+		supportsExplicitPromptCacheMode: "withhold"
 	},
 	"anthropic-messages": {
-		supportsEagerToolInputStreaming: "boolean",
-		supportsLongCacheRetention: "boolean",
-		sendSessionAffinityHeaders: "boolean",
-		supportsCacheControlOnTools: "boolean",
-		supportsTemperature: "boolean",
-		forceAdaptiveThinking: "boolean",
-		allowEmptySignature: "boolean",
-		supportsStrictTools: "boolean",
-		supportsToolReferences: "boolean"
+		supportsEagerToolInputStreaming: "offer",
+		supportsLongCacheRetention: "offer",
+		supportsCacheControlOnTools: "offer",
+		supportsTemperature: "offer",
+		forceAdaptiveThinking: "offer",
+		allowEmptySignature: "offer",
+		supportsStrictTools: "offer",
+		sendSessionAffinityHeaders: "withhold",
+		supportsToolReferences: "withhold"
 	}
 };
-function checkValue(_api, field, spec, value, where) {
+/** 某协议某字段的可配性（'offer'/'withhold'；未列出 = 无此字段）。 */
+function compatDispositionOf(api, field) {
+	return GATES_BY_PROTOCOL[api][field];
+}
+/**
+* 字段取值约束（对齐官方 config.ts compatProfile schema）：
+* boolean 字段 → 'boolean'；maxTokensField/thinkingFormat/cacheControlFormat
+* → 枚举；chatTemplateKwargs/chatTemplateArgs → 对象。
+*/
+const VALUE_SPECS = {
+	supportsStore: "boolean",
+	supportsDeveloperRole: "boolean",
+	supportsReasoningEffort: "boolean",
+	supportsUsageInStreaming: "boolean",
+	supportsFinishReason: "boolean",
+	maxTokensField: ["max_completion_tokens", "max_tokens"],
+	requiresToolResultName: "boolean",
+	requiresAssistantAfterToolResult: "boolean",
+	requiresThinkingAsText: "boolean",
+	requiresReasoningContentOnAssistantMessages: "boolean",
+	thinkingFormat: [
+		"openai",
+		"deepseek",
+		"openrouter",
+		"together",
+		"baseten",
+		"zai",
+		"qwen",
+		"chat-template",
+		"qwen-chat-template",
+		"string-thinking",
+		"ant-ling"
+	],
+	chatTemplateKwargs: "object",
+	chatTemplateArgs: "object",
+	supportsThinkingTokenBudget: "boolean",
+	supportsStrictMode: "boolean",
+	cacheControlFormat: ["anthropic"],
+	supportsLongCacheRetention: "boolean",
+	supportsEagerToolInputStreaming: "boolean",
+	supportsCacheControlOnTools: "boolean",
+	supportsTemperature: "boolean",
+	forceAdaptiveThinking: "boolean",
+	allowEmptySignature: "boolean",
+	supportsStrictTools: "boolean"
+};
+/** 某协议全部可配置（offer）的 compat 键（UI 渲染字段组与校验共用）。 */
+function compatFieldsOf(api) {
+	return Object.entries(GATES_BY_PROTOCOL[api]).flatMap(([field, disposition]) => disposition === "offer" ? [field] : []);
+}
+function checkValue(field, spec, value, where) {
 	if (spec === "boolean") {
 		if (typeof value !== "boolean") throw new Error(`${where}: compat.${field} 必须是布尔值`);
 		return;
@@ -825,29 +872,36 @@ function checkValue(_api, field, spec, value, where) {
 	if (typeof value !== "string" || !spec.includes(value)) throw new Error(`${where}: compat.${field} 必须是 ${spec.map((v) => JSON.stringify(v)).join(" | ")} 之一`);
 }
 /**
-* 校验一份 compat 字典对指定协议合法：未知协议/未知键拒绝（对比官方的静默丢弃），
-* 已知键校验值类型/枚举。undefined 值视为未设置，跳过（语义同 pi-ai 的 ??）。
+* 校验一份 compat 字典对指定协议合法（对齐官方门控语义 + schema 值约束）：
+* - 未知键/withhold 字段拒绝（官方 0.1.2-alpha.1 写时拒绝，替代旧版静默丢弃）；
+* - 值类型/枚举按官方 schema 校验；
+* - 无值键（null/undefined）拒绝（官方 assertOfferedCompatFields 同款：
+*   "写了但没生效" 的表面状态不允许）。
 */
 function validateCompat(api, compat, where) {
 	if (compat === void 0) return;
-	const fields = FIELDS_BY_PROTOCOL[api];
-	if (fields === void 0) throw new Error(`${where}: 协议 ${JSON.stringify(api)} 无 compat 字段表（支持：${Object.keys(FIELDS_BY_PROTOCOL).join(", ")}）`);
+	const gate = GATES_BY_PROTOCOL[api];
+	if (gate === void 0) throw new Error(`${where}: 协议 ${JSON.stringify(api)} 无 compat 字段表（支持：${Object.keys(GATES_BY_PROTOCOL).join(", ")}）`);
+	const offered = compatFieldsOf(api);
 	for (const [key, value] of Object.entries(compat)) {
-		const spec = fields[key];
-		if (spec === void 0) throw new Error(`${where}: compat.${key} 不是 ${api} 协议的合法字段（合法字段：${Object.keys(fields).join(", ")}）`);
-		if (value === void 0) continue;
-		checkValue(api, key, spec, value, where);
+		const disposition = gate[key];
+		if (disposition !== "offer") {
+			if (disposition === "withhold") throw new Error(`${where}: compat.${key} 官方按协议 withhold（内置目录已为对应厂商设置该开关）；请以目录 provider 名作为 route 名（继承目录值），或移除该字段`);
+			throw new Error(`${where}: compat.${key} 不是 ${api} 协议的合法字段（可配置字段：${offered.join(", ")}）`);
+		}
+		if (value === void 0 || value === null) throw new Error(`${where}: compat.${key} 未设置值；给出值或移除该键（留空不会生效）`);
+		checkValue(key, VALUE_SPECS[key], value, where);
 	}
 }
 /**
-* 逐字段合并 compat 层（后者覆盖前者），丢弃 undefined 值。
+* 逐字段合并 compat 层（后者覆盖前者），丢弃 undefined/null 值。
 * 层序：继承源（仅同协议）→ route 级 → 模型级。
 */
 function mergeCompat(...layers) {
 	const merged = {};
 	for (const layer of layers) {
 		if (layer === void 0) continue;
-		for (const [key, value] of Object.entries(layer)) if (value !== void 0) merged[key] = value;
+		for (const [key, value] of Object.entries(layer)) if (value !== void 0 && value !== null) merged[key] = value;
 	}
 	return Object.keys(merged).length > 0 ? merged : void 0;
 }
@@ -968,14 +1022,14 @@ function declaredModalities(configured) {
 /** 物化单个模型目录条目：官方 base 在下，条目显式字段逐字段覆盖。 */
 function materializeModel$1(route, entry, deps) {
 	if (entry.reasoningEfforts !== void 0 || nonEmptyDict(entry.compat)) invalid$1(route, `model "${entry.id}" 的 reasoningEfforts/compat 仅 adapter: pi 可用`);
+	if (entry.imageDetail !== void 0) invalid$1(route, `model "${entry.id}" 的 imageDetail 已随 0.1.2-alpha.1 移除；请改用 imagePixelBudget/imageMaxBytes（低细节可配更小的 imagePixelBudget）并删除 imageDetail`);
 	const base = resolveOfficialBase(route, entry, deps);
 	const input = declaredModalities(entry.input) ?? base.input;
 	const imageFields = {
 		imagePixelBudget: entry.imagePixelBudget ?? base.imagePixelBudget,
-		imageMaxBytes: entry.imageMaxBytes ?? base.imageMaxBytes,
-		imageDetail: entry.imageDetail ?? base.imageDetail
+		imageMaxBytes: entry.imageMaxBytes ?? base.imageMaxBytes
 	};
-	if (!(input?.includes("image") ?? false) && Object.values(imageFields).some((value) => value !== void 0)) invalid$1(route, `model "${entry.id}" 未声明 image 模态，不可配置 imagePixelBudget/imageMaxBytes/imageDetail`);
+	if (!(input?.includes("image") ?? false) && Object.values(imageFields).some((value) => value !== void 0)) invalid$1(route, `model "${entry.id}" 未声明 image 模态，不可配置 imagePixelBudget/imageMaxBytes`);
 	return {
 		id: entry.id,
 		...(entry.name ?? base.name) === void 0 ? {} : { name: entry.name ?? base.name },
@@ -1029,7 +1083,7 @@ function rawAdapterConfig(profile, baseURL, models) {
 /** 物化单个 deepseek route；lenient 下失败告警并返回 null（调用方跳过注册）。 */
 function buildRoute(route, profile, deps) {
 	try {
-		if (deps.kit.deepseek === void 0) invalid$1(route, "使用 adapter: deepseek，但当前运行时套件不含 dsh-llm-deepseek（需 dsh ≥ 0.1.1-rc.2）");
+		if (deps.kit.deepseek === void 0) invalid$1(route, "使用 adapter: deepseek，但当前运行时套件不含 dsh-llm-deepseek（0.1.2-alpha.1 基线）");
 		rejectPiOnlyFields(route, profile);
 		if (profile.extends !== void 0 && profile.extends !== "deepseek") invalid$1(route, `的 extends ${JSON.stringify(profile.extends)} 非法：adapter: deepseek 仅支持 "deepseek"（官方目录）`);
 		if (profile.apiKeyEnv === void 0 || profile.apiKeyEnv.length === 0) invalid$1(route, "需要 apiKeyEnv：DeepSeekAdapter 无环境自发现，凭据引用必须显式配置");
@@ -1066,16 +1120,31 @@ function buildDeepseekRoutes(providers, deps) {
 //#endregion
 //#region src/profiles.ts
 /**
-* profile 构建器：插件 Config → ResolvedPiAiProviderProfile 映射。
+* profile 构建器（0.1.2-alpha.1 适配版）：插件 Config → 官方 schema 形状的
+* 「前置数据源归一化」→ 官方 resolveProfiles（或插件等价兜底）→
+* ResolvedPiAiProviderProfile。
 *
-* 语义与官方 dsh-llm-pi-ai 的 resolveProfiles 链逐点对齐（index.js:1068-1471），
-* 差异仅在两点扩展：
-* - base 来源从"route 同名内置目录"换为 extends 三级数据源（inherit.ts）；
-* - compat 从 2 字段枚举扩展为逐协议全量字段（compat.ts），写入即校验。
+* 适配决策（resolveProfiles 复用评估，2026-08）：
+* - 官方 resolveProfiles 仅在 @deepseek-ai/dsh-llm-pi-ai 的 src/config.ts 子路径
+*   导出，npm 发布形态不携带 src/（lib/index.js 单 bundle），包根也不导出该
+*   符号——真实部署（npm 布局 dsh 树）与 vendored 兜底都无法引用官方解析链；
+* - 因此：dsh 树 dev 布局（src 存在）时经 src 子路径复用官方 resolveProfiles
+*   （resolve-dsh.ts 探测），其余形态走本文件的 resolveProfilesFallback——
+*   语义逐行对齐官方 config.ts:resolveProfiles + catalog.ts:resolveRouteModels
+*   （协议限定本插件三协议），compat 门控以官方 catalog.ts COMPAT_GATES 为
+*   唯一事实源（见 compat.ts）；
+* - 两条路径的输入相同：插件独占的 extends/models.dev/草稿路由等语义在此
+*   「前置归一化」为全显式官方 schema 形状（模型条目字段全部落定），官方链
+*   不再需要目录查找；normalizeRoute 的产物经 kit.resolveProfiles 进入
+*   官方 adapter 消息链路。
 *
-* 产物经 `new PiAiAdapter({ profiles })` 进入官方消息链路；
-* 任何不可服务的配置在此处抛错（命名 route/model），配合 settings 写入校验，
-* 非法配置在写入时被拒绝、运行期保留上一份好配置。
+* 与官方链的既有缝隙（记录在案）：
+* - 模型级 maxTokens 在官方 schema 中兼作「能力值」与「显式配置的请求默认
+*   cap」；归一化把继承值物化进条目后官方链会全部计入 configuredMaxTokens，
+*   此处按插件原语义回填为「仅用户显式配置」——请求默认 cap 行为不变；
+* - 官方 schema 无模型级 baseUrl/headers/cost：端点收敛为 route 级单一值
+*   （模型间端点不一致写时拒绝），headers/cost 不继承（0.84.2 目录无模型级
+*   headers；harness 不消费 cost 元数据，与官方 NO_COST 同口径）。
 * @module llm-pi/profiles
 */
 /** 内置目录未描述时的零价目（harness 不消费 cost 元数据，同官方 NO_COST）。 */
@@ -1093,53 +1162,60 @@ function invalid(provider, detail) {
 function declaredInput(configured) {
 	return configured === void 0 || configured.length === 0 ? void 0 : [...configured];
 }
-/**
-* 单个模型的 reasoning 物化（逐行对齐官方 resolveModelReasoning）：
-* 显式 dict → 全档位确定的 thinkingLevelMap（未声明档位置 null）；
-* false → 非推理模型；缺省 → 保留继承源的 reasoning 能力。
-*/
-function resolveModelReasoning(provider, entry, base) {
-	const efforts = entry.reasoningEfforts;
-	if (efforts === void 0) {
-		if (base.reasoning === void 0) return { reasoning: false };
-		return {
-			reasoning: base.reasoning,
-			...base.thinkingLevelMap === void 0 ? {} : { thinkingLevelMap: base.thinkingLevelMap }
-		};
-	}
-	if (efforts === false) return { reasoning: false };
-	if (Object.keys(efforts).length === 0) invalid(provider, `model "${entry.id}" 的 reasoningEfforts 为空：声明档位、置 false 或缺省继承`);
+/** 显式 reasoningEfforts 字典的合法性校验（官方 resolveModelReasoning 同款规则）。 */
+function validateReasoningEfforts(provider, entryId, efforts) {
+	if (Object.keys(efforts).length === 0) invalid(provider, `model "${entryId}" 的 reasoningEfforts 为空：声明档位、置 false 或缺省继承`);
 	for (const level of THINKING_LEVELS) {
 		const wire = efforts[level];
 		if (wire === void 0) continue;
 		if (wire === null) {
-			if (level !== "off") invalid(provider, `model "${entry.id}" reasoningEfforts.${level} 需要线值；仅 off 可留空`);
-		} else if (wire.length === 0) invalid(provider, `model "${entry.id}" reasoningEfforts.${level} 不能为空字符串`);
+			if (level !== "off") invalid(provider, `model "${entryId}" reasoningEfforts.${level} 需要线值；仅 off 可留空`);
+		} else if (wire.length === 0) invalid(provider, `model "${entryId}" reasoningEfforts.${level} 不能为空字符串`);
 	}
-	if (!THINKING_LEVELS.filter((level) => efforts[level] !== void 0).some((level) => level !== "off")) invalid(provider, `model "${entry.id}" reasoningEfforts 只有 off；声明思考档位或置 false`);
-	const map = {};
-	for (const level of THINKING_LEVELS) {
-		const wire = efforts[level];
-		if (wire === void 0) map[level] = null;
-		else if (wire !== null) map[level] = wire;
-	}
-	return {
-		reasoning: true,
-		thinkingLevelMap: map
-	};
+	if (!THINKING_LEVELS.filter((level) => efforts[level] !== void 0).some((level) => level !== "off")) invalid(provider, `model "${entryId}" reasoningEfforts 只有 off；声明思考档位或置 false`);
 }
-/** Harness 自管凭据的 api-key auth（对齐官方 harnessApiKeyAuth，index.js:1215）。 */
-function harnessApiKeyAuth(name) {
-	return {
-		name,
-		resolve: ({ credential }) => Promise.resolve({
-			auth: credential?.key === void 0 ? {} : { apiKey: credential.key },
-			source: name
-		})
+/**
+* 继承源的 reasoning 能力 → 官方 reasoningEfforts 字典（全显式归一化的一环）。
+* - base 无推理能力 → false（与官方"手写模型缺省不推理"同语义）；
+* - base 带 thinkingLevelMap → 逐档位翻译：线值照抄；null（不支持）不声明
+*   （dict 未声明档位置 null = 不支持，语义一致）；缺省档位（off/minimal/
+*   low/medium/high）线值 = 档位名（pi-ai dispatch 的 `map?.[level] ?? level`），
+*   xhigh/max 缺省 = 不支持（pi-ai 对两档的缺省语义）——翻译后支持档位集合
+*   与线值与内置目录逐档位一致；
+* - base 只有 reasoning:true 无表（models.dev 保守源）→ 声明基档位为默认
+*   线值、xhigh/max 不支持——与 pi-ai 无表默认语义一致。
+*/
+function reasoningEffortsFromBase(provider, entry, base) {
+	if (entry.reasoningEfforts !== void 0) {
+		if (entry.reasoningEfforts === false) return false;
+		validateReasoningEfforts(provider, entry.id, entry.reasoningEfforts);
+		return entry.reasoningEfforts;
+	}
+	if (base.reasoning !== true) return false;
+	const map = base.thinkingLevelMap;
+	if (map === void 0) return {
+		off: null,
+		minimal: "minimal",
+		low: "low",
+		medium: "medium",
+		high: "high"
 	};
+	const dict = {};
+	for (const level of THINKING_LEVELS) {
+		const wire = map[level];
+		if (wire === void 0) {
+			if (level === "xhigh" || level === "max") continue;
+			dict[level] = level;
+		} else if (wire !== null) dict[level] = wire;
+	}
+	return dict;
 }
-/** 物化单个模型：继承 base 在下，条目显式字段逐字段覆盖。lenient 下缺 api/baseURL 时跳过（返回 null）。 */
-function materializeModel(route, profile, entry, base, routeApi, providerBaseUrl, defaultInput, deps, configuredMaxTokens) {
+/**
+* 物化单个模型为官方 schema 条目（全显式）。lenient 下缺 api/baseURL 时
+* 返回 null（调用方跳过该模型）。
+*/
+function materializeModel(route, profile, entry, base, routeApi, defaultInput, deps) {
+	if (entry.imageDetail !== void 0) invalid(route, `model "${entry.id}" 的 imageDetail 已随 0.1.2-alpha.1 移除；请改用 imagePixelBudget/imageMaxBytes（仅 adapter: deepseek）并删除 imageDetail`);
 	const api = profile.api ?? base.api ?? routeApi;
 	if (api === void 0) {
 		if (deps.lenient) {
@@ -1148,7 +1224,7 @@ function materializeModel(route, profile, entry, base, routeApi, providerBaseUrl
 		}
 		invalid(route, `model "${entry.id}" 需要 api：继承源未提供，请在 route 上设置 api`);
 	}
-	const baseUrl = profile.baseURL ?? base.baseUrl ?? providerBaseUrl;
+	const baseUrl = profile.baseURL ?? base.baseUrl ?? builtinProviderBaseUrl(deps.kit, profile.extends ?? "");
 	if (baseUrl === void 0) {
 		if (deps.lenient) {
 			deps.warn?.(`llm-pi: provider "${route}" model "${entry.id}" 无法获得 baseURL（继承源缺失），已跳过该模型`);
@@ -1156,32 +1232,34 @@ function materializeModel(route, profile, entry, base, routeApi, providerBaseUrl
 		}
 		invalid(route, `model "${entry.id}" 需要 baseURL：继承源未提供，请在 route 上设置 baseURL`);
 	}
+	const name = entry.name ?? base.name ?? entry.id;
 	const contextWindow = entry.contextWindow ?? base.contextWindow ?? profile.defaultContextWindow ?? 262144;
 	const maxTokens = entry.maxTokens ?? base.maxTokens ?? profile.defaultMaxTokens ?? 32768;
-	if (entry.maxTokens !== void 0) configuredMaxTokens.set(entry.id, entry.maxTokens);
+	const input = declaredInput(entry.input) ?? base.input ?? [...defaultInput];
 	validateCompat(api, profile.compat, `provider "${route}"`);
 	validateCompat(api, entry.compat, `provider "${route}" model "${entry.id}"`);
 	const compat = mergeCompat(base.api === api ? base.compat : void 0, profile.compat, entry.compat);
+	if (compat !== void 0) validateCompat(api, compat, `provider "${route}" model "${entry.id}"`);
 	return {
-		id: entry.id,
-		name: entry.name ?? base.name ?? entry.id,
+		entry: {
+			id: entry.id,
+			...name === entry.id ? {} : { name },
+			...contextWindow === 262144 ? {} : { contextWindow },
+			...maxTokens === 32768 ? {} : { maxTokens },
+			...input.length === 1 && input[0] === "text" ? {} : { input },
+			reasoningEfforts: reasoningEffortsFromBase(route, entry, base),
+			...compat === void 0 ? {} : { compat }
+		},
 		api,
-		provider: route,
-		baseUrl,
-		...resolveModelReasoning(route, entry, base),
-		input: declaredInput(entry.input) ?? base.input ?? [...defaultInput],
-		cost: base.cost ?? NO_COST,
-		contextWindow,
-		maxTokens,
-		...base.headers === void 0 ? {} : { headers: { ...base.headers } },
-		...compat === void 0 ? {} : { compat }
+		baseUrl
 	};
 }
-/** 物化一个 route 的全部模型；返回模型列表与显式配置的请求 cap 表。
-*  lenient 下 route 无任何可服务模型时返回 null（调用方跳过该 route）。 */
+/**
+* 物化一个 route 的全部模型为官方条目；返回 route 级唯一 api/baseURL 与
+* 用户显式配置的请求 cap 表。lenient 下 route 无任何可服务模型时返回 null。
+*/
 function materializeRouteModels(route, profile, deps, defaultInput) {
 	const configuredMaxTokens = /* @__PURE__ */ new Map();
-	const providerBaseUrl = profile.extends === void 0 ? void 0 : builtinProviderBaseUrl(deps.kit, profile.extends);
 	const entries = [];
 	if (profile.models !== void 0 && profile.models.length > 0) {
 		const seen = /* @__PURE__ */ new Set();
@@ -1197,6 +1275,7 @@ function materializeRouteModels(route, profile, deps, defaultInput) {
 				deps.warn?.(`llm-pi: provider "${route}" model "${entry.id}" 的 extends 引用当前不可解析（${error.message}）；已降级为手写条目`);
 				base = {};
 			}
+			if (entry.maxTokens !== void 0) configuredMaxTokens.set(entry.id, entry.maxTokens);
 			entries.push({
 				id: entry.id,
 				entry,
@@ -1212,18 +1291,22 @@ function materializeRouteModels(route, profile, deps, defaultInput) {
 	} else invalid(route, "未配置 models 且未配置 provider 级 extends；本 route 无模型可服务");
 	const apis = new Set(entries.map(({ base }) => profile.api ?? base.api).filter((api) => api !== void 0));
 	const routeApi = apis.size === 1 ? [...apis][0] : void 0;
-	const models = entries.map(({ id, entry, base }) => materializeModel(route, profile, entry ?? { id }, base, routeApi, providerBaseUrl, defaultInput, deps, configuredMaxTokens)).filter((model) => model !== null);
-	if (models.length === 0) {
+	const materialized = entries.map(({ id, entry, base }) => materializeModel(route, profile, entry ?? { id }, base, routeApi, defaultInput, deps)).filter((model) => model !== null);
+	if (materialized.length === 0) {
 		if (deps.lenient) {
 			deps.warn?.(`llm-pi: provider "${route}" 当前没有可服务的模型（继承源漂移），已跳过该 route 的注册`);
 			return null;
 		}
 		invalid(route, "route 内没有可服务的模型");
 	}
-	const finalApis = new Set(models.map((m) => m.api));
-	if (finalApis.size > 1) invalid(route, `route 内模型协议不一致（${[...finalApis].join(", ")}）；一个 route 只能服务一种协议`);
+	const apisFinal = new Set(materialized.map((m) => m.api));
+	if (apisFinal.size > 1) invalid(route, `route 内模型协议不一致（${[...apisFinal].join(", ")}）；一个 route 只能服务一种协议`);
+	const baseUrls = new Set(materialized.map((m) => m.baseUrl));
+	if (baseUrls.size > 1) invalid(route, `route 内模型端点不一致（${[...baseUrls].join(", ")}）；官方 schema 无模型级端点，请以 route 级 baseURL 统一`);
 	return {
-		models,
+		models: materialized.map((m) => m.entry),
+		api: materialized[0]?.api,
+		baseUrl: materialized[0]?.baseUrl,
 		configuredMaxTokens
 	};
 }
@@ -1236,63 +1319,309 @@ function isDraftRoute(profile) {
 	return (profile.adapter ?? "pi") === "pi" && (profile.models === void 0 || profile.models.length === 0) && profile.extends === void 0;
 }
 /**
-* 校验并物化全部 route。任一 route 不可服务即整体抛错——
-* settings 写入校验与运行期 profiles 回调共用本函数，
-* 保证"写入时被拒"与"运行期不可能拿到坏配置"互为表里。
-* 草稿路由（isDraftRoute）跳过物化，不参与 adapter 注册。
+* 前置数据源归一化：一个 route → 官方 schema 形状的全显式 profile。
+* 不可服务的 route（deepseek 路由 / 草稿 / lenient 下无模型）返回 undefined。
+* 校验规则对齐官方 resolveProfiles（baseURL/displayName 非空、idle 超时边界、
+* 图片限额正整数、defaultInput 非空）。
 */
-function buildProfiles(providers, deps) {
-	const resolved = /* @__PURE__ */ new Map();
-	for (const [route, profile] of Object.entries(providers ?? {})) {
-		if ((profile.adapter ?? "pi") === "deepseek") continue;
-		if (isDraftRoute(profile)) continue;
-		if (route.length === 0) throw new Error("llm-pi: provider 名不能为空");
-		if (profile.baseURL !== void 0 && profile.baseURL.length === 0) invalid(route, "baseURL 为空");
-		if (profile.displayName !== void 0 && profile.displayName.length === 0) invalid(route, "displayName 为空");
-		const streamIdleTimeoutMs = profile.streamIdleTimeoutMs ?? 3e5;
-		if (!Number.isFinite(streamIdleTimeoutMs) || streamIdleTimeoutMs <= 0 || streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) invalid(route, `streamIdleTimeoutMs 必须是 (0, ${MAX_TIMER_DELAY_MS}] 内的有限数`);
-		const defaultInput = [...profile.defaultInput ?? ["text"]];
-		if (defaultInput.length === 0) invalid(route, "defaultInput 至少要声明一种模态");
-		const displayName = profile.displayName ?? route;
-		const catalog = materializeRouteModels(route, profile, deps, defaultInput);
-		if (catalog === null) continue;
-		const api = catalog.models[0]?.api;
-		const factory = api === void 0 ? void 0 : deps.kit.protocolFactories[api];
-		if (factory === void 0) invalid(route, `api ${JSON.stringify(api)} 本插件无法服务（支持：openai-completions/openai-responses/anthropic-messages）`);
-		const piProvider = deps.kit.createProvider({
-			id: route,
-			name: displayName,
-			...profile.baseURL === void 0 ? profile.extends === void 0 ? {} : { baseUrl: builtinProviderBaseUrl(deps.kit, profile.extends) } : { baseUrl: profile.baseURL },
-			...profile.headers === void 0 ? {} : { headers: { ...profile.headers } },
-			auth: { apiKey: harnessApiKeyAuth(displayName) },
-			models: catalog.models,
-			api: factory()
-		});
-		resolved.set(route, {
-			provider: route,
+function normalizeRoute(route, profile, deps) {
+	if ((profile.adapter ?? "pi") === "deepseek") return void 0;
+	if (isDraftRoute(profile)) return void 0;
+	if (route.length === 0) throw new Error("llm-pi: provider 名不能为空");
+	if (profile.baseURL !== void 0 && profile.baseURL.length === 0) invalid(route, "baseURL 为空");
+	if (profile.displayName !== void 0 && profile.displayName.length === 0) invalid(route, "displayName 为空");
+	const streamIdleTimeoutMs = profile.streamIdleTimeoutMs ?? 3e5;
+	if (!Number.isFinite(streamIdleTimeoutMs) || streamIdleTimeoutMs <= 0 || streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) invalid(route, `streamIdleTimeoutMs 必须是 (0, ${MAX_TIMER_DELAY_MS}] 内的有限数`);
+	const maxRequestImageBytes = profile.maxRequestImageBytes ?? 20971520;
+	if (!Number.isInteger(maxRequestImageBytes) || maxRequestImageBytes <= 0) invalid(route, "maxRequestImageBytes 必须是正整数");
+	const requestImagePixelBudget = profile.requestImagePixelBudget ?? 4194304;
+	if (!Number.isSafeInteger(requestImagePixelBudget) || requestImagePixelBudget <= 0) invalid(route, "requestImagePixelBudget 必须是正整数");
+	const requestImageMaxBytes = profile.requestImageMaxBytes ?? 1048576;
+	if (!Number.isSafeInteger(requestImageMaxBytes) || requestImageMaxBytes <= 0) invalid(route, "requestImageMaxBytes 必须是正整数");
+	const defaultInput = [...profile.defaultInput ?? ["text"]];
+	if (defaultInput.length === 0) invalid(route, "defaultInput 至少要声明一种模态");
+	const materialized = materializeRouteModels(route, profile, deps, defaultInput);
+	if (materialized === null) return void 0;
+	const { api, baseUrl, models, configuredMaxTokens } = materialized;
+	if (deps.kit.protocolFactories[api] === void 0) invalid(route, `api ${JSON.stringify(api)} 本插件无法服务（支持：openai-completions/openai-responses/anthropic-messages）`);
+	const displayName = profile.displayName ?? route;
+	return {
+		profile: {
+			...profile.apiKeyEnv === void 0 ? {} : { apiKeyEnv: profile.apiKeyEnv },
 			displayName,
-			...profile.apiKeyEnv === void 0 ? {} : { apiKeyEnv: credentialRef(profile.apiKeyEnv) },
-			streamIdleTimeoutMs,
-			maxRequestImageBytes: profile.maxRequestImageBytes ?? 20971520,
-			retryPolicy: deps.kit.resolveRetryPolicy(profile.retryPolicy, `llm-pi: provider "${route}" retryPolicy`),
-			...profile.headers === void 0 ? {} : { headers: { ...profile.headers } },
+			api,
+			...baseUrl === void 0 ? {} : { baseURL: baseUrl },
+			models,
+			...profile.defaultContextWindow === void 0 ? {} : { defaultContextWindow: profile.defaultContextWindow },
+			...profile.defaultMaxTokens === void 0 ? {} : { defaultMaxTokens: profile.defaultMaxTokens },
+			defaultInput,
+			...profile.headers === void 0 ? {} : { headers: profile.headers },
 			...profile.reasoning === void 0 ? {} : { reasoning: profile.reasoning },
-			...profile.thinkingBudgets === void 0 ? {} : { thinkingBudgets: { ...profile.thinkingBudgets } },
+			...profile.thinkingBudgets === void 0 ? {} : { thinkingBudgets: profile.thinkingBudgets },
 			...profile.cacheRetention === void 0 ? {} : { cacheRetention: profile.cacheRetention },
 			...profile.transport === void 0 ? {} : { transport: profile.transport },
 			...profile.timeoutMs === void 0 ? {} : { timeoutMs: profile.timeoutMs },
 			...profile.websocketConnectTimeoutMs === void 0 ? {} : { websocketConnectTimeoutMs: profile.websocketConnectTimeoutMs },
-			configuredMaxTokens: catalog.configuredMaxTokens,
-			piProvider
+			...profile.streamIdleTimeoutMs === void 0 ? {} : { streamIdleTimeoutMs: profile.streamIdleTimeoutMs },
+			...profile.maxRequestImageBytes === void 0 ? {} : { maxRequestImageBytes: profile.maxRequestImageBytes },
+			...profile.requestImagePixelBudget === void 0 ? {} : { requestImagePixelBudget: profile.requestImagePixelBudget },
+			...profile.requestImageMaxBytes === void 0 ? {} : { requestImageMaxBytes: profile.requestImageMaxBytes },
+			...profile.retryPolicy === void 0 ? {} : { retryPolicy: profile.retryPolicy }
+		},
+		configuredMaxTokens
+	};
+}
+/** Harness 自管凭据的 api-key auth（对齐官方 harnessApiKeyAuth）。 */
+function harnessApiKeyAuth(name) {
+	return {
+		name,
+		resolve: ({ credential }) => Promise.resolve({
+			auth: credential?.key === void 0 ? {} : { apiKey: credential.key },
+			source: name
+		})
+	};
+}
+/** 官方 resolveModelReasoning 的插件侧镜像：dict → {reasoning, thinkingLevelMap}。 */
+function resolveModelReasoning(entry) {
+	const efforts = entry.reasoningEfforts;
+	if (efforts === void 0 || efforts === false) return { reasoning: false };
+	const map = {};
+	for (const level of THINKING_LEVELS) {
+		const wire = efforts[level];
+		if (wire === void 0) map[level] = null;
+		else if (wire !== null) map[level] = wire;
+	}
+	return {
+		reasoning: true,
+		thinkingLevelMap: map
+	};
+}
+/** 官方 resolveModelCompat 的插件侧镜像：门控表过滤 + 模型级拒绝不适配字段。 */
+function resolveModelCompat(provider, entry, api) {
+	const configured = {};
+	for (const [field, value] of Object.entries(entry.compat ?? {})) {
+		if (compatDispositionOf(api, field) !== "offer") {
+			const offered = compatFieldsOf(api);
+			invalid(provider, `model "${entry.id}" 的 compat.${field} 不适用于协议 ${api}；该协议可配置字段：${offered.length === 0 ? "无" : offered.join(", ")}`);
+		}
+		if (value === void 0 || value === null) invalid(provider, `model "${entry.id}" 的 compat.${field} 未设置值；给出值或移除该键`);
+		configured[field] = value;
+	}
+	if (Object.keys(configured).length === 0) return {};
+	return { compat: configured };
+}
+/**
+* 官方 resolveProfiles 的插件等价实现（npm 形态无 src/config.ts 可导入时兜底）。
+* 输入为 normalizeRoute 的全显式产物（api/baseURL/条目字段全部落定），语义与
+* 官方 config.ts:resolveProfiles + catalog.ts:resolveRouteModels 逐行对齐：
+* 默认值（streamIdleTimeoutMs/图片限额/容量兜底）、retryPolicy 解析、
+* configuredMaxTokens（此处按全显式条目计入，buildProfiles 再回填为用户显式
+* 集）、createProvider 构建 piProvider（harness api-key auth）。
+*/
+function resolveProfilesFallback(providers, deps) {
+	const resolved = /* @__PURE__ */ new Map();
+	for (const [provider, source] of Object.entries(providers ?? {})) {
+		if (source.baseURL !== void 0 && source.baseURL.length === 0) invalid(provider, "baseURL 为空");
+		if (source.displayName !== void 0 && source.displayName.length === 0) invalid(provider, "displayName 为空");
+		const streamIdleTimeoutMs = source.streamIdleTimeoutMs ?? 3e5;
+		if (!Number.isFinite(streamIdleTimeoutMs) || streamIdleTimeoutMs <= 0 || streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) invalid(provider, `streamIdleTimeoutMs 必须是 (0, ${MAX_TIMER_DELAY_MS}] 内的有限数`);
+		const maxRequestImageBytes = source.maxRequestImageBytes ?? 20971520;
+		if (!Number.isInteger(maxRequestImageBytes) || maxRequestImageBytes <= 0) invalid(provider, "maxRequestImageBytes 必须是正整数");
+		const requestImagePixelBudget = source.requestImagePixelBudget ?? 4194304;
+		if (!Number.isSafeInteger(requestImagePixelBudget) || requestImagePixelBudget <= 0) invalid(provider, "requestImagePixelBudget 必须是正整数");
+		const requestImageMaxBytes = source.requestImageMaxBytes ?? 1048576;
+		if (!Number.isSafeInteger(requestImageMaxBytes) || requestImageMaxBytes <= 0) invalid(provider, "requestImageMaxBytes 必须是正整数");
+		const defaultInput = [...source.defaultInput ?? ["text"]];
+		if (defaultInput.length === 0) invalid(provider, "defaultInput 至少要声明一种模态");
+		const displayName = source.displayName ?? provider;
+		const api = source.api;
+		if (api === void 0) invalid(provider, "需要 api：本插件仅支持 openai-completions/openai-responses/anthropic-messages");
+		const factory = deps.protocolFactories[api];
+		if (factory === void 0) invalid(provider, `api ${JSON.stringify(api)} 本插件无法服务（支持：openai-completions/openai-responses/anthropic-messages）`);
+		if (source.baseURL === void 0) invalid(provider, "需要 baseURL：官方 schema 无模型级端点，端点只能 route 级表达");
+		const configuredMaxTokens = /* @__PURE__ */ new Map();
+		const seen = /* @__PURE__ */ new Set();
+		const models = (source.models ?? []).map((entry) => {
+			if (entry.id.length === 0) invalid(provider, "存在空 id 的模型条目");
+			if (seen.has(entry.id)) invalid(provider, `模型 "${entry.id}" 重复列出`);
+			seen.add(entry.id);
+			const contextWindow = entry.contextWindow ?? source.defaultContextWindow ?? 262144;
+			if (!Number.isInteger(contextWindow) || contextWindow <= 0) invalid(provider, `model "${entry.id}" contextWindow 必须是正整数`);
+			const maxTokens = entry.maxTokens ?? source.defaultMaxTokens ?? 32768;
+			if (!Number.isInteger(maxTokens) || maxTokens <= 0) invalid(provider, `model "${entry.id}" maxTokens 必须是正整数`);
+			if (entry.maxTokens !== void 0) configuredMaxTokens.set(entry.id, entry.maxTokens);
+			return {
+				id: entry.id,
+				name: entry.name ?? entry.id,
+				api,
+				provider,
+				baseUrl: source.baseURL,
+				input: [...entry.input ?? defaultInput],
+				cost: NO_COST,
+				contextWindow,
+				maxTokens,
+				...resolveModelReasoning(entry),
+				...resolveModelCompat(provider, entry, api)
+			};
+		});
+		if (models.length === 0) invalid(provider, "route 内没有可服务的模型");
+		const { apiKeyEnv, retryPolicy, models: _models, displayName: _displayName, ...rest } = source;
+		resolved.set(provider, {
+			...rest,
+			provider,
+			displayName,
+			...apiKeyEnv === void 0 ? {} : { apiKeyEnv: credentialRef(apiKeyEnv) },
+			streamIdleTimeoutMs,
+			maxRequestImageBytes,
+			requestImagePixelBudget,
+			requestImageMaxBytes,
+			retryPolicy: deps.resolveRetryPolicy(retryPolicy, `llm-pi: provider "${provider}" retryPolicy`),
+			...rest.headers === void 0 ? {} : { headers: { ...rest.headers } },
+			...rest.thinkingBudgets === void 0 ? {} : { thinkingBudgets: { ...rest.thinkingBudgets } },
+			configuredMaxTokens,
+			piProvider: deps.createProvider({
+				id: provider,
+				name: displayName,
+				...source.baseURL === void 0 ? {} : { baseUrl: source.baseURL },
+				auth: { apiKey: harnessApiKeyAuth(displayName) },
+				models,
+				api: factory()
+			})
 		});
 	}
 	return resolved;
 }
+/**
+* 校验并物化全部 pi route。任一 route 不可服务即整体抛错——
+* settings 写入校验与运行期 profiles 回调共用本函数，
+* 保证"写入时被拒"与"运行期不可能拿到坏配置"互为表里。
+* 草稿路由（isDraftRoute）跳过物化，不参与 adapter 注册。
+*/
+function buildProfiles(providers, deps) {
+	const resolved = /* @__PURE__ */ new Map();
+	for (const [route, profile] of Object.entries(providers ?? {})) {
+		let normalized;
+		try {
+			normalized = normalizeRoute(route, profile, deps);
+			if (normalized === void 0) continue;
+			const single = deps.kit.resolveProfiles({ [route]: normalized.profile });
+			for (const [name, built] of single) resolved.set(name, {
+				...built,
+				configuredMaxTokens: normalized.configuredMaxTokens
+			});
+		} catch (error) {
+			if (!deps.lenient) throw error;
+			deps.warn?.(`llm-pi: provider "${route}" 不可服务（${error instanceof Error ? error.message : String(error)}），已跳过注册`);
+		}
+	}
+	return resolved;
+}
 /** settings 写入校验钩子：完整试跑解析，非法配置在写入处拒绝。 */
 function assertServiceable(config, deps) {
 	buildProfiles(config.providers, deps);
 	buildDeepseekRoutes(config.providers, deps);
 }
+/** 官方 jsonImage：pi-ai 凭据里显式 undefined 成员 JSON 序列化为缺省/数组 null。 */
+function jsonImage(value) {
+	if (Array.isArray(value)) return value.map((entry) => entry === void 0 ? null : jsonImage(entry));
+	if (typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype) {
+		const image = {};
+		for (const [key, member] of Object.entries(value)) if (member !== void 0) image[key] = jsonImage(member);
+		return image;
+	}
+	return value;
+}
+/** 官方 toPiCredential：api-key 记录按字段重建；grant 载荷原样透传。 */
+function toPiCredential(record) {
+	if (record === void 0) return void 0;
+	if (record.kind === "api-key") return {
+		type: "api_key",
+		...record.key === void 0 ? {} : { key: record.key },
+		...record.env === void 0 ? {} : { env: { ...record.env } }
+	};
+	return record.payload;
+}
+/** 官方 toRecord：pi-ai 凭据 → 可存储的记录联合。 */
+function toRecord(credential) {
+	if (credential.type === "api_key") return {
+		kind: "api-key",
+		...credential.key === void 0 ? {} : { key: credential.key },
+		...credential.env === void 0 ? {} : { env: { ...credential.env } }
+	};
+	return {
+		kind: "grant",
+		payload: jsonImage(credential)
+	};
+}
+/** 官方 writableStore：写路径需要凭据服务，缺失时抛 NO_CREDENTIAL_STORE。 */
+function writableStore(ctx) {
+	const credentials = ctx.get("credentials");
+	if (credentials === void 0) throw new LlmError("llm-pi: 当前组合未挂载凭据服务（dsh-credentials-local），登录产生的凭据无处存储", "NO_CREDENTIAL_STORE");
+	return credentials;
+}
+/**
+* pi-ai `CredentialStore`（官方 credentialStoreFrom 等价实现）。
+* 路由键任意而记录 id 受语法约束：语法外的 id 读答"未存储"、删除无事可做、
+* modify 拒绝（写不落地不能报成功）。
+*/
+function credentialStoreFrom(ctx, recordKeyFor) {
+	return {
+		async read(providerId) {
+			const credentials = ctx.get("credentials");
+			if (credentials === void 0) return void 0;
+			if (!isCredentialKeySegment(providerId)) return void 0;
+			return toPiCredential(await credentials.readRecord(recordKeyFor(providerId)));
+		},
+		async list() {
+			const stored = await ctx.get("credentials")?.listRecords() ?? [];
+			const mine = [];
+			for (const entry of stored) {
+				if (credentialKeyScope(entry.key) !== "llm-pi-ai") continue;
+				mine.push({
+					providerId: credentialKeyId(entry.key),
+					type: entry.kind === "api-key" ? "api_key" : "oauth"
+				});
+			}
+			return mine;
+		},
+		async modify(providerId, mutate) {
+			if (!isCredentialKeySegment(providerId)) throw new LlmError(`llm-pi: provider id "${providerId}" 无法寻址存储的凭据记录（记录 id 是小写连字符标识）；该 route 请改用 apiKeyEnv 认证`, "UNSTORABLE_PROVIDER_ID");
+			return toPiCredential(await writableStore(ctx).modifyRecord(recordKeyFor(providerId), async (current) => {
+				const next = await mutate(toPiCredential(current));
+				return next === void 0 ? void 0 : toRecord(next);
+			}));
+		},
+		async delete(providerId) {
+			if (!isCredentialKeySegment(providerId)) return;
+			await writableStore(ctx).deleteRecord(recordKeyFor(providerId));
+		}
+	};
+}
+/**
+* pi-ai `AuthContext`（官方 authContextFrom 等价实现）：
+* env() 先查凭据服务（存储的环境值对 provider 自发现可见），再回退启动环境；
+* fileExists() 问宿主进程文件系统（~/.aws/credentials 等是本进程所在机器的事实）。
+*/
+function authContextFrom(ctx) {
+	return {
+		async env(name) {
+			if (isCredentialRefName(name)) {
+				const hit = await ctx.get("credentials")?.resolve(credentialRef(name));
+				if (hit !== void 0) return hit.value;
+			}
+			return launchEnvironmentOf(ctx).get(name)?.value;
+		},
+		async fileExists(path) {
+			const expanded = path.startsWith("~/") || path === "~" ? resolve(homedir(), path.slice(1).replace(/^\//, "")) : path;
+			try {
+				await access(expanded);
+				return true;
+			} catch {
+				return false;
+			}
+		}
+	};
+}
 //#endregion
 //#region src/resolve-dsh.ts
 /**
@@ -1306,8 +1635,16 @@ function assertServiceable(config, deps) {
 *    的目录，按文件路径动态 import——与 dsh 官方插件共享同一模块实例；
 * 2. vendored：回退到本插件 dependencies 里的固定版本副本（裸 import）。
 *
-* 两条路径产物都过形状自检（assertKitShape）：上游 rc 重构导致形状漂移时
+* 两条路径产物都过形状自检（assertKitShape）：上游重构导致形状漂移时
 * 抛错，由调用方决定回退或放弃注册——绝不让坏套件进入消息链路。
+*
+* 0.1.2-alpha.1 起的新面（包根未导出、仅 src 子路径有）：
+* - resolveProfiles（config.ts）：官方解析链，dev 布局树可经 src 子路径复用；
+* - credentialStoreFrom/authContextFrom（auth.ts）：PiAiAdapter 必需 auth 注入。
+* npm 发布形态（lib/index.js 单 bundle + 无 src/）两者都拿不到：dsh 树优先
+* 探测 src/*（含 lib/* 候选），未命中时 resolveProfiles 走插件等价实现
+* （profiles.ts，门控表对齐官方 catalog.ts）、auth 走内联等价实现
+* （auth-inline.ts，recordKeyFor 自包根导出同源注入）——形状自检兜底。
 * @module llm-pi/resolve-dsh
 */
 /** kit 必备形状清单：缺失即视为上游不兼容。 */
@@ -1319,7 +1656,9 @@ function assertKitShape(kit, origin) {
 		"stream",
 		"listModels",
 		"resolveModel",
-		"providerInfo"
+		"providerInfo",
+		"prepareCall",
+		"providerRetryPolicy"
 	]) if (typeof kit.PiAiAdapter.prototype[method] !== "function") problems.push(`PiAiAdapter.prototype.${method} 缺失`);
 	if (typeof kit.createProvider !== "function") problems.push("pi-ai createProvider 缺失");
 	if (typeof kit.getBuiltinModels !== "function") problems.push("pi-ai getBuiltinModels 缺失");
@@ -1327,6 +1666,9 @@ function assertKitShape(kit, origin) {
 	for (const [api, factory] of Object.entries(kit.protocolFactories)) if (typeof factory !== "function") problems.push(`协议工厂 ${api} 缺失`);
 	if (typeof kit.LlmError !== "function") problems.push("dsh-llm LlmError 缺失");
 	if (typeof kit.resolveRetryPolicy !== "function") problems.push("dsh-llm resolveRetryPolicy 缺失");
+	if (typeof kit.resolveProfiles !== "function") problems.push("resolveProfiles 缺失");
+	if (typeof kit.resolveImageAttachmentAccess !== "function") problems.push("resolveImageAttachmentAccess 缺失");
+	if (typeof kit.auth?.credentialStoreFrom !== "function" || typeof kit.auth?.authContextFrom !== "function") problems.push("auth 助手（credentialStoreFrom/authContextFrom）缺失");
 	if (problems.length > 0) throw new Error(`llm-pi: ${origin} 来源的运行时套件形状不兼容：${problems.join("；")}`);
 }
 /** deepseek 模块形状自检；返回问题清单（空 = 可用），由调用方决定降级。 */
@@ -1372,6 +1714,24 @@ async function importTreeModules(root) {
 		anthropic
 	};
 }
+/**
+* 探测包目录下的子路径模块：src/<name>.ts（dsh 树 dev 布局 / 源码仓库）→
+* src/<name>.js → lib/<name>.js（未来构建形态）。加载失败（依赖缺失等）
+* 视为该候选不可用，继续下一候选；全部未命中返回 undefined（调用方兜底）。
+*/
+async function probeSubmodule(pkgDir, name) {
+	for (const candidate of [
+		`src/${name}.ts`,
+		`src/${name}.js`,
+		`lib/${name}.js`
+	]) {
+		const absPath = join(pkgDir, candidate);
+		if (!existsSync(absPath)) continue;
+		try {
+			return await import(pathToFileURL(absPath).href);
+		} catch {}
+	}
+}
 /** 从同一 dsh 安装树加载 deepseek 适配器模块（失败返回 undefined，不拖垮核心套件）。 */
 async function importTreeDeepseek(root) {
 	const nm = join(root, "node_modules");
@@ -1390,7 +1750,28 @@ async function importTreeDeepseek(root) {
 		return { problem: error instanceof Error ? error.message : String(error) };
 	}
 }
-function kitFromTree(mods) {
+function protocolFactoriesOf(mods) {
+	return {
+		"openai-completions": mods.completions["openAICompletionsApi"],
+		"openai-responses": mods.responses["openAIResponsesApi"],
+		"anthropic-messages": mods.anthropic["anthropicMessagesApi"]
+	};
+}
+/** 插件等价解析链的套件依赖（与 PiAiAdapter 同源，杜绝跨源混用）。 */
+function treeResolverDeps(mods, protocolFactories) {
+	return {
+		createProvider: mods.piAi["createProvider"],
+		protocolFactories,
+		resolveRetryPolicy: mods.llm["resolveRetryPolicy"]
+	};
+}
+function kitFromTree(mods, auth, config) {
+	const protocolFactories = protocolFactoriesOf(mods);
+	const resolverDeps = treeResolverDeps(mods, protocolFactories);
+	const officialResolveProfiles = config?.["resolveProfiles"];
+	const officialCredentialStoreFrom = auth?.["credentialStoreFrom"];
+	const officialAuthContextFrom = auth?.["authContextFrom"];
+	const recordKeyFor = mods.piAiAdapter["recordKeyFor"];
 	return {
 		source: "dsh-tree",
 		PiAiAdapter: mods.piAiAdapter["PiAiAdapter"],
@@ -1404,11 +1785,13 @@ function kitFromTree(mods) {
 		builtinProviders: mods.catalog["builtinProviders"],
 		getBuiltinProviders: mods.catalog["getBuiltinProviders"],
 		getBuiltinModels: mods.catalog["getBuiltinModels"],
-		protocolFactories: {
-			"openai-completions": mods.completions["openAICompletionsApi"],
-			"openai-responses": mods.responses["openAIResponsesApi"],
-			"anthropic-messages": mods.anthropic["anthropicMessagesApi"]
-		}
+		protocolFactories,
+		resolveProfiles: officialResolveProfiles !== void 0 ? officialResolveProfiles : (providers) => resolveProfilesFallback(providers, resolverDeps),
+		auth: {
+			credentialStoreFrom: officialCredentialStoreFrom !== void 0 ? officialCredentialStoreFrom : (ctx) => credentialStoreFrom(ctx, recordKeyFor),
+			authContextFrom: officialAuthContextFrom !== void 0 ? officialAuthContextFrom : authContextFrom
+		},
+		resolveImageAttachmentAccess: mods.llm["resolveImageAttachmentAccess"]
 	};
 }
 /** vendored 兜底副本的 deepseek 模块（形状自检不过时返回 undefined）。 */
@@ -1420,9 +1803,18 @@ function loadVendoredDeepseek() {
 	};
 	return checkDeepseekShape(kit).length === 0 ? kit : void 0;
 }
-/** vendored 兜底副本套件（导出供单测直接使用，免走 dsh 树解析）。 */
+/**
+* vendored 兜底副本套件（导出供单测直接使用，免走 dsh 树解析）。
+* npm 发布形态不携带 src/、lib 仅 index.js/invariant.js——resolveProfiles 与
+* auth 助手在此无条件走插件等价实现（内联/门控表对齐，见文件头说明）。
+*/
 function loadVendoredKit() {
 	const deepseek = loadVendoredDeepseek();
+	const protocolFactories = {
+		"openai-completions": openAICompletionsApi,
+		"openai-responses": openAIResponsesApi,
+		"anthropic-messages": anthropicMessagesApi
+	};
 	const kit = {
 		source: "vendored",
 		PiAiAdapter: vendoredPiAiAdapter.PiAiAdapter,
@@ -1436,11 +1828,17 @@ function loadVendoredKit() {
 		builtinProviders: vendoredCatalog.builtinProviders,
 		getBuiltinProviders: vendoredCatalog.getBuiltinProviders,
 		getBuiltinModels: vendoredCatalog.getBuiltinModels,
-		protocolFactories: {
-			"openai-completions": openAICompletionsApi,
-			"openai-responses": openAIResponsesApi,
-			"anthropic-messages": anthropicMessagesApi
+		protocolFactories,
+		resolveProfiles: (providers) => resolveProfilesFallback(providers, {
+			createProvider: vendoredPiAi.createProvider,
+			protocolFactories,
+			resolveRetryPolicy: vendoredLlm.resolveRetryPolicy
+		}),
+		auth: {
+			credentialStoreFrom: (ctx) => credentialStoreFrom(ctx, vendoredPiAiAdapter.recordKeyFor),
+			authContextFrom
 		},
+		resolveImageAttachmentAccess: vendoredLlm.resolveImageAttachmentAccess,
 		...deepseek === void 0 ? {} : { deepseek }
 	};
 	assertKitShape(kit, "vendored");
@@ -1464,26 +1862,32 @@ function dshTreeAnchor() {
 async function resolveDshKit() {
 	const diagnostics = [];
 	const anchor = dshTreeAnchor();
-	if (anchor !== void 0) try {
-		const kit = kitFromTree(await importTreeModules(anchor));
-		assertKitShape(kit, "dsh-tree");
-		const tree = await importTreeDeepseek(anchor);
-		if (tree.kit !== void 0) return {
-			kit: {
-				...kit,
-				deepseek: tree.kit
-			},
-			diagnostics
-		};
-		diagnostics.push(`dsh 安装树的 dsh-llm-deepseek 不可用（${tree.problem ?? "未知原因"}）；adapter: deepseek 的 route 不可用，pi 路由不受影响`);
-		return {
-			kit,
-			diagnostics
-		};
-	} catch (error) {
-		diagnostics.push(`dsh 安装树套件不可用（${anchor}）：${error instanceof Error ? error.message : String(error)}；回退 vendored 副本`);
-	}
-	else diagnostics.push("未能从 process.argv[1] 定位 dsh 安装树；回退 vendored 副本");
+	if (anchor !== void 0) {
+		const treePkgDir = join(anchor, "node_modules", "@deepseek-ai", "dsh-llm-pi-ai");
+		try {
+			const mods = await importTreeModules(anchor);
+			const [auth, config] = await Promise.all([probeSubmodule(treePkgDir, "auth"), probeSubmodule(treePkgDir, "config")]);
+			const kit = kitFromTree(mods, auth, config);
+			assertKitShape(kit, "dsh-tree");
+			if (auth === void 0) diagnostics.push("dsh 树不含 dsh-llm-pi-ai/src（npm 发布形态）；认证助手使用插件内联等价实现");
+			if (config === void 0) diagnostics.push("dsh 树不含 dsh-llm-pi-ai/src（npm 发布形态）；profile 解析使用插件等价实现（compat 门控对齐官方 catalog.ts）");
+			const tree = await importTreeDeepseek(anchor);
+			if (tree.kit !== void 0) return {
+				kit: {
+					...kit,
+					deepseek: tree.kit
+				},
+				diagnostics
+			};
+			diagnostics.push(`dsh 安装树的 dsh-llm-deepseek 不可用（${tree.problem ?? "未知原因"}）；adapter: deepseek 的 route 不可用，pi 路由不受影响`);
+			return {
+				kit,
+				diagnostics
+			};
+		} catch (error) {
+			diagnostics.push(`dsh 安装树套件不可用（${anchor}）：${error instanceof Error ? error.message : String(error)}；回退 vendored 副本`);
+		}
+	} else diagnostics.push("未能从 process.argv[1] 定位 dsh 安装树；回退 vendored 副本");
 	const kit = loadVendoredKit();
 	if (kit.deepseek === void 0) diagnostics.push("vendored 副本的 dsh-llm-deepseek 形状不兼容；adapter: deepseek 的 route 不可用");
 	return {
@@ -1557,7 +1961,15 @@ async function startRuntime(ctx, rawConfig) {
 	const adapter = new kit.PiAiAdapter({
 		profiles,
 		resolveApiKey: makeResolveApiKey(ctx, kit),
-		resolveAttachments: () => ctx.get("attachments")
+		resolveAttachments: () => ctx.get("attachments"),
+		auth: {
+			credentials: kit.auth.credentialStoreFrom(ctx),
+			authContext: kit.auth.authContextFrom(ctx)
+		},
+		resolveImageAccess: (attachments, ref) => kit.resolveImageAttachmentAccess(attachments, (hostPath) => ctx.get("fs")?.processPathFromHostPath(hostPath), ref),
+		onReplayDegrade: ({ provider, model, reason }) => {
+			logger.warn(`llm-pi: 助手历史中 "${provider}/${model}" 的回放状态不可用，该消息按 provider 中立内容发送（${reason}）`);
+		}
 	});
 	const storedApiKey = async (provider) => {
 		if (provider === void 0) return void 0;