ck-pi-zen-session 0.1.6 → 0.1.8

package/README.md

@@ -25,7 +25,8 @@ OpenCode Zen 免费模型同步、请求头伪装与 Session 会话自动维护
   - 若请求已有工具，严格按照官方客户端规约（`localeCompare`）按函数名升序重排；
   - 自动对齐流式用量元数据 `stream_options: { include_usage: true }`。
 - 🌐 **独立供应商隔离与零干扰保障 (`isZenModelTarget`)**：严格将生命周期守卫、请求头与请求体拦截限制在 `opencode-zen-free` 命名空间内，对 `relayhub`、`deepseek`、`anthropic`、`openai`、`onerouter`、`apmix` 等其他任何模型及 Claude Code（`pi-cc-extensions`）插件 100% 保持完全静默放行，零副作用、零冲突。
-- 🧠 **精准上下文与思维链适配**：严格对齐免费模型的 `contextWindow`、`maxTokens` 与 `thinkingLevelMap`（涵盖小米 MiMo、英伟达 Nemotron、Meta Muse Spark、Ling、Jev 等）。
+- 🧠 **高精智能模型能力与参数解析引擎 (v0.1.7)**：无论输入新 Key 还是 OpenCode Zen 官方端点动态上线任何新免费/零额度模型，自动深度识别其上下文窗口（Context Window，如 1M, 256K, 200K, 128K）、最大输出（Max Tokens，如 128K, 64K, 32K, 16K）、推理思考能力与思考等级映射（thinkingLevelMap，涵盖 6 档深度推理 [minimal..xhigh]、3 档标准推理 [low, high, max] 或快反模式）以及视觉多模态支持，并在 `/zen <key>` 和 `/zen list` 中呈现精美结构化卡片。
+- 🛡️ **OpenAI 标准思考档位全链路映射与双重防线 (v0.1.8)**：彻底修复 OpenCode Zen 上游端点不支持 `max` / `xhigh` 思考档位导致抛出 `[400] Invalid request parameters` 的致命问题。全面将思考档位映射对齐 OpenAI 标准 `reasoning_effort`（`low` / `medium` / `high`），并在 `before_provider_request` 请求体守卫中设立兜底防线，自动将非标准或溢出档位降级规约为合法参数，确保小米 MiMo、英伟达 Nemotron、Meta Muse Spark 等全系模型在任意 Pi 默认思考模式下 100% 稳定响应。
 - 🔌 **全自动多端持久化同步**：自动双写 Pi 本地配置（`~/.pi/agent/models.json` 和 `~/.pi/agent/auth.json`），若检测到 CC-Switch 亦无缝同步其 SQLite 数据库。
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ck-pi-zen-session",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "OpenCode Zen session auto-refresh and free-tier model catalog synchronization for the Pi coding agent.",
   "keywords": [
     "pi-package",

package/src/index.ts

@@ -10,7 +10,21 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+export {
+	formatModelCard,
+	formatThinkingSummary,
+	formatTokens,
+	inferModelCapabilities,
+	KNOWN_ZEN_FREE_MODELS,
+	OPENCODE_OFFICIAL_TOOLS,
+	ZEN_BASE_URL,
+	ZEN_PROVIDER_ID,
+	ZEN_USER_AGENT,
+} from "./models-registry.js";
 import {
+	formatModelCard,
+	formatThinkingSummary,
+	formatTokens,
 	KNOWN_ZEN_FREE_MODELS,
 	OPENCODE_OFFICIAL_TOOLS,
 	ZEN_BASE_URL,
@@ -68,8 +82,18 @@ export function registerZenProviderToPi(
 	}
 }
 
-export function isZenModelTarget(model?: { provider?: string; id?: string }): boolean {
-	if (!model) return false;
+export function isZenModelTarget(model?: { provider?: string; id?: string }, payloadModel?: string): boolean {
+	if (!model) {
+		if (payloadModel) {
+			const lower = payloadModel.toLowerCase();
+			return (
+				lower.endsWith("-free") ||
+				lower === "big-pickle" ||
+				lower.includes("zen")
+			);
+		}
+		return false;
+	}
 	// 严格隔离：仅处理 opencode-zen-free 或明确属于 opencode 官方的免费模型
 	// 绝不干涉 relayhub、deepseek、anthropic、openai 等其他任何供应商或 CC 插件
 	if (model.provider === ZEN_PROVIDER_ID) return true;
@@ -83,11 +107,20 @@ export function isZenModelTarget(model?: { provider?: string; id?: string }): bo
 }
 
 export default function piZenSession(pi: ExtensionAPI): void {
-	// 1. 若本地已配置 Key，启动时即刻注册独立供应商 opencode-zen-free
-	// 独立命名空间，彻底避开并兼容用户自带的官方登录 opencode / opencode-zen 套餐
 	const existingKey = getStoredZenApiKey();
 	if (existingKey) {
-		registerZenProviderToPi(pi, existingKey);
+		const storedSession = getStoredZenSessionId();
+		const storedModels = getStoredZenModels();
+		registerZenProviderToPi(pi, existingKey, storedSession || generateZenSessionId(), storedModels);
+
+		// 若已有 Key 但还没有持久化模型列表，后台静默自动探测一次
+		if (!storedModels || storedModels.length === 0) {
+			syncZenConfiguration()
+				.then((res) => {
+					registerZenProviderToPi(pi, res.apiKey, res.sessionId, res.resolvedModels);
+				})
+				.catch(() => {});
+		}
 	}
 
 	// 2. 核心请求头拦截钩子：在每一次请求发往 Provider 前注入完整官方客户端对齐请求头
@@ -107,6 +140,7 @@ export default function piZenSession(pi: ExtensionAPI): void {
 			}
 
 			// 注入全部官方客户端 7 维对齐请求头
+			delete event.headers["user-agent"];
 			event.headers["User-Agent"] = ZEN_USER_AGENT;
 			event.headers["x-opencode-client"] = "cli";
 			event.headers["x-opencode-session"] = currentSession;
@@ -119,8 +153,9 @@ export default function piZenSession(pi: ExtensionAPI): void {
 
 	// 3. 核心请求体守卫钩子：深度对齐 OpenCode 官方请求体结构与工具集
 	pi.on("before_provider_request", (event, ctx) => {
-		if (isZenModelTarget(ctx.model) && event.payload && typeof event.payload === "object") {
-			const payload = event.payload as Record<string, unknown>;
+		const payload = event.payload as Record<string, unknown> | undefined;
+		const payloadModel = typeof payload?.model === "string" ? payload.model : undefined;
+		if (isZenModelTarget(ctx.model, payloadModel) && payload && typeof payload === "object") {
 			const tools = payload.tools;
 			let modified = false;
 			const transformed = { ...payload };
@@ -145,6 +180,22 @@ export default function piZenSession(pi: ExtensionAPI): void {
 				modified = true;
 			}
 
+			// C. 规范化 reasoning_effort：OpenCode Zen 上游端点仅支持 "low", "medium", "high"
+			// 若为 "max" 或 "xhigh"，降级映射为 "high"；若为 "minimal" 映射为 "low"，彻底根除 400 Invalid request parameters
+			if (typeof transformed.reasoning_effort === "string") {
+				const effort = transformed.reasoning_effort.toLowerCase();
+				if (effort === "max" || effort === "xhigh") {
+					transformed.reasoning_effort = "high";
+					modified = true;
+				} else if (effort === "minimal") {
+					transformed.reasoning_effort = "low";
+					modified = true;
+				} else if (!["low", "medium", "high"].includes(effort)) {
+					transformed.reasoning_effort = "high";
+					modified = true;
+				}
+			}
+
 			if (modified) {
 				return transformed;
 			}
@@ -219,16 +270,21 @@ export async function handleZenCommand(
 			? `${status.sessionAgeMinutes} 分钟`
 			: `${(status.sessionAgeMinutes / 60).toFixed(1)} 小时`;
 
+		const storedModels = getStoredZenModels();
+		const reasoningCount = storedModels.filter((m) => m.reasoning).length;
+		const visionCount = storedModels.filter((m) => m.input.includes("image")).length;
+
 		const msg = [
 			"✨ [OpenCode Zen 运行状态]",
 			`• API Key: ${status.maskedKey}`,
 			`• Session: ${status.sessionId || "未生成"} (${status.sessionExpired ? "已过期" : `有效，创建于 ${ageDesc}前`})`,
-			`• 模型库: 已激活 ${status.modelsCount} 个免费模型`,
+			`• 模型库: 已激活 ${storedModels.length} 款 0 额度模型 (${reasoningCount} 款支持思考推理，${visionCount} 款支持多模态)`,
+			`• 请求头保护: 7维官方客户端签名 + 30分钟降序时间戳自愈`,
 			"",
 			"常用指令：",
-			"  /zen <key>   - 更新 Key 并全量重新同步",
+			"  /zen <key>   - 更新 Key 并全自动识别免费模型/上下文/思考等级",
 			"  /zen refresh - 强制换新 Session ID",
-			"  /zen list    - 查看所有可用免费模型规格",
+			"  /zen list    - 查看所有可用免费模型详细规格卡片",
 		].join("\n");
 
 		notify(ctx, msg, "info");
@@ -237,17 +293,20 @@ export async function handleZenCommand(
 
 	// 2. 查看模型清单: /zen list 或 /zen models
 	if (command === "list" || command === "models") {
-		const status = getZenStatusInfo();
-		if (status.modelIds.length === 0) {
+		const storedModels = getStoredZenModels();
+		if (storedModels.length === 0) {
 			notify(ctx, "当前尚未同步任何模型，请先运行 /zen <key>。", "warning");
 			return;
 		}
 
+		const modelCards = storedModels.map((m, idx) => formatModelCard(m, idx + 1));
 		const listMsg = [
-			`✨ [OpenCode Zen 免费模型列表 (${status.modelIds.length} 个)]`,
-			...status.modelIds.map((id) => `  • ${id}`),
+			`✨ [OpenCode Zen 免费模型列表 (${storedModels.length} 款)]`,
+			"智能识别精确上下文上限（Context）、最大输出（Max Tokens）及推理思考等级（Thinking）：",
+			"",
+			...modelCards,
 			"",
-			"提示：这些模型已就绪，可在 Pi 中直接切换使用！",
+			"提示：这些模型已全量注册至 Pi，使用 /model 或快捷键随时切换！",
 		].join("\n");
 
 		notify(ctx, listMsg, "info");
@@ -262,10 +321,16 @@ export async function handleZenCommand(
 			if (pi) {
 				registerZenProviderToPi(pi, result.apiKey, result.sessionId, result.resolvedModels);
 			}
+			if ((ctx as { modelRegistry?: { refresh?: (arg: unknown) => Promise<unknown> } }).modelRegistry?.refresh) {
+				await (ctx as { modelRegistry: { refresh: (arg: unknown) => Promise<unknown> } }).modelRegistry
+					.refresh({ providers: [ZEN_PROVIDER_ID] })
+					.catch(() => {});
+			}
+			const reasoningCount = result.resolvedModels.filter((m) => m.reasoning).length;
 			const successMsg = [
 				"✓ OpenCode Zen Session 已成功刷新！",
 				`• 全新 Session: ${result.sessionId}`,
-				`• 免费模型: 已对齐 ${result.modelsCount} 款 0 额度消耗模型`,
+				`• 免费模型: 已对齐 ${result.modelsCount} 款 0 额度模型 (${reasoningCount} 款支持思考推理)`,
 				`• 请求头伪装: 7 维官方客户端签名已注入`,
 				`• 同步状态: models.json ✓ | CC-Switch ${result.ccSwitchUpdated ? "✓" : "-(未安装或无此条目)"}`,
 			].join("\n");
@@ -279,19 +344,31 @@ export async function handleZenCommand(
 	// 4. 输入了具体的 API Key: /zen oc_sk_... 或其它 key
 	if (rawArg.length > 0 && !["status", "refresh", "list", "models"].includes(command)) {
 		try {
-			notify(ctx, "正在验证 OpenCode Zen API Key 并探测免费与零额度模型...", "info");
+			notify(ctx, "正在验证 OpenCode Zen API Key 并智能探测免费模型上下文与思考等级...", "info");
 			const result = await syncZenConfiguration({ apiKey: rawArg, forceSession: true });
 			if (pi) {
 				registerZenProviderToPi(pi, result.apiKey, result.sessionId, result.resolvedModels);
 			}
+			if ((ctx as { modelRegistry?: { refresh?: (arg: unknown) => Promise<unknown> } }).modelRegistry?.refresh) {
+				await (ctx as { modelRegistry: { refresh: (arg: unknown) => Promise<unknown> } }).modelRegistry
+					.refresh({ providers: [ZEN_PROVIDER_ID] })
+					.catch(() => {});
+			}
+
+			const modelCards = result.resolvedModels.map((m, idx) => formatModelCard(m, idx + 1));
+			const reasoningCount = result.resolvedModels.filter((m) => m.reasoning).length;
+
 			const msg = [
-				"🎉 OpenCode Zen 配置成功！免费套餐与零额度模型已自动识别并全量对接：",
+				"🎉 OpenCode Zen 配置成功！免费套餐与零额度模型已全自动识别并对接：",
 				`• API Key: ${maskKey(result.apiKey)} (已验证并保存)`,
-				`• 会话 Session: ${result.sessionId} (官方降序时间戳逆向算法)`,
-				`• 自动对接免费模型 (${result.modelsCount} 款，全部标记 0 额度消耗)：`,
-				...result.models.map((id) => `  • ${id}`),
+				`• 会话 Session: ${result.sessionId} (官方降序时间戳逆向算法，30分钟自动轮换自愈)`,
+				`• 识别到 ${result.modelsCount} 款 0 额度免费模型 (${reasoningCount} 款支持深度推理/思考)：`,
+				"",
+				...modelCards,
+				"",
 				`• 同步路径: ${result.modelsPath}`,
 				result.ccSwitchUpdated ? "• CC-Switch: 本地数据库已同步更新" : "",
+				"提示：全部模型参数已热载入 Pi，输入 /model 或在模型选择器中可即刻选用！",
 			].filter(Boolean).join("\n");
 			notify(ctx, msg, "info");
 		} catch (error) {
@@ -310,17 +387,23 @@ export async function handleZenCommand(
 			if (pi) {
 				registerZenProviderToPi(pi, result.apiKey, result.sessionId, result.resolvedModels);
 			}
+			if ((ctx as { modelRegistry?: { refresh?: (arg: unknown) => Promise<unknown> } }).modelRegistry?.refresh) {
+				await (ctx as { modelRegistry: { refresh: (arg: unknown) => Promise<unknown> } }).modelRegistry
+					.refresh({ providers: [ZEN_PROVIDER_ID] })
+					.catch(() => {});
+			}
+			const reasoningCount = result.resolvedModels.filter((m) => m.reasoning).length;
 			const msg = [
 				"✨ [OpenCode Zen 已自动刷新并就绪]",
 				`• API Key: ${maskKey(result.apiKey)}`,
 				`• 全新 Session: ${result.sessionId} (有效且已持久化)`,
-				`• 自动对接免费模型: 已同步 ${result.modelsCount} 个 0 额度消耗模型`,
+				`• 自动对接免费模型: 已同步 ${result.modelsCount} 个 0 额度消耗模型 (${reasoningCount} 款支持思考推理)`,
 				`• 请求头保护: 30分钟自动轮换 + 7维官方签名 + 6大核心工具全注入`,
 				"",
 				"常用操作：",
-				"  /zen <key>   - 更换 API Key",
+				"  /zen <key>   - 更换 API Key (自动重识免费模型/上下文/思考等级)",
 				"  /zen status  - 详情状态",
-				"  /zen list    - 查看所有可用免费模型",
+				"  /zen list    - 查看所有可用免费模型详细规格",
 			].join("\n");
 			notify(ctx, msg, "info");
 		} catch (error) {

package/src/models-registry.ts

@@ -11,23 +11,33 @@ export const ZEN_PROVIDER_ID = "opencode-zen-free";
 export const ZEN_BASE_URL = "https://opencode.ai/zen/v1";
 export const ZEN_USER_AGENT = "opencode/1.18.32 ai-sdk/provider-utils/4.0.23 runtime/bun/1.3.14";
 
-const STANDARD_THINKING_LEVELS: Record<string, string | null> = {
+export const STANDARD_THINKING_LEVELS: Record<string, string | null> = {
+	minimal: "low",
 	low: "low",
+	medium: "medium",
+	high: "high",
+	xhigh: "high",
+	max: "high",
+	off: null,
+};
+
+export const MUSE_SPARK_THINKING_LEVELS: Record<string, string | null> = {
+	minimal: "low",
+	low: "low",
+	medium: "medium",
 	high: "high",
-	max: "max",
-	medium: null,
-	minimal: null,
+	xhigh: "high",
+	max: "high",
 	off: null,
-	xhigh: null,
 };
 
-const MUSE_SPARK_THINKING_LEVELS: Record<string, string | null> = {
-	minimal: "minimal",
+export const GRANULAR_THINKING_LEVELS: Record<string, string | null> = {
+	minimal: "low",
 	low: "low",
 	medium: "medium",
 	high: "high",
-	xhigh: "xhigh",
-	max: "xhigh",
+	xhigh: "high",
+	max: "high",
 	off: null,
 };
 
@@ -127,43 +137,306 @@ export const KNOWN_ZEN_FREE_MODELS: Record<string, ZenModelDefinition> = {
 };
 
 /**
- * 为未来可能新增的免费模型生成自适应默认配置
+ * 高精智能模型能力与参数解析引擎
+ * 当用户输入新 Key 或探测到未收录的免费/零额度模型时，全自动深度识别：
+ * 1. 上下文窗口限制 (Context Window)
+ * 2. 最大输出 Token 上限 (Max Tokens)
+ * 3. 思考推理能力与思考等级映射 (Reasoning & thinkingLevelMap)
+ * 4. 文本/视觉多模态输入支持 (Input Modalities)
+ * 5. 0 额度计费配置 (Zero-Cost Billing)
  */
-export function buildFallbackModelDefinition(modelId: string): ZenModelDefinition {
-	const isReasoning = !modelId.includes("chat") && !modelId.includes("turbo");
-	const friendlyName = modelId
+export function inferModelCapabilities(
+	modelId: string,
+	raw?: Record<string, unknown>,
+): ZenModelDefinition {
+	// 1. 若为已知免费模型，以此为高精基准
+	if (KNOWN_ZEN_FREE_MODELS[modelId]) {
+		const base: ZenModelDefinition = { ...KNOWN_ZEN_FREE_MODELS[modelId] };
+		// 若在线接口返回了显式上下文或最大输出覆盖，进行动态微调
+		if (typeof raw?.context_window === "number" && raw.context_window > 0) {
+			base.contextWindow = raw.context_window;
+		} else if (typeof raw?.context_length === "number" && raw.context_length > 0) {
+			base.contextWindow = raw.context_length;
+		}
+		if (typeof raw?.max_tokens === "number" && raw.max_tokens > 0) {
+			base.maxTokens = raw.max_tokens;
+		} else if (typeof raw?.max_output_tokens === "number" && raw.max_output_tokens > 0) {
+			base.maxTokens = raw.max_output_tokens;
+		}
+		return base;
+	}
+
+	const lower = modelId.toLowerCase();
+
+	// 2. 上下文窗口识别 (contextWindow)
+	let contextWindow = 200000;
+	if (typeof raw?.context_window === "number" && raw.context_window > 0) {
+		contextWindow = raw.context_window;
+	} else if (typeof raw?.context_length === "number" && raw.context_length > 0) {
+		contextWindow = raw.context_length;
+	} else if (typeof raw?.max_context_length === "number" && raw.max_context_length > 0) {
+		contextWindow = raw.max_context_length;
+	} else if (typeof (raw?.limit as { context?: number } | undefined)?.context === "number") {
+		contextWindow = (raw!.limit as { context: number }).context;
+	} else if (lower.includes("2m") || lower.includes("2000k")) {
+		contextWindow = 2097152;
+	} else if (
+		lower.includes("1m") ||
+		lower.includes("1000k") ||
+		lower.includes("1024k") ||
+		lower.includes("muse") ||
+		lower.includes("spark") ||
+		lower.includes("gemini") ||
+		lower.includes("deepseek") ||
+		(lower.includes("nemotron") && lower.includes("ultra")) ||
+		(lower.includes("kimi") && lower.includes("k3")) ||
+		lower.includes("minimax")
+	) {
+		contextWindow = lower.includes("muse") || lower.includes("gemini") ? 1048576 : 1000000;
+	} else if (lower.includes("512k")) {
+		contextWindow = 524288;
+	} else if (
+		lower.includes("256k") ||
+		(lower.includes("nemotron") && lower.includes("lightning")) ||
+		lower.includes("ling") ||
+		(lower.includes("kimi") && !lower.includes("k3"))
+	) {
+		contextWindow = 262144;
+	} else if (
+		lower.includes("128k") ||
+		lower.includes("qwen") ||
+		lower.includes("grok") ||
+		lower.includes("jev") ||
+		lower.includes("system-1")
+	) {
+		contextWindow = lower.includes("qwen") ? 131072 : 128000;
+	} else {
+		contextWindow = 200000;
+	}
+
+	// 3. 最大输出 Token 识别 (maxTokens)
+	let maxTokens = 32000;
+	if (typeof raw?.max_output_tokens === "number" && raw.max_output_tokens > 0) {
+		maxTokens = raw.max_output_tokens;
+	} else if (typeof raw?.max_tokens === "number" && raw.max_tokens > 0) {
+		maxTokens = raw.max_tokens;
+	} else if (typeof (raw?.limit as { output?: number } | undefined)?.output === "number") {
+		maxTokens = (raw!.limit as { output: number }).output;
+	} else if (lower.includes("nemotron") && lower.includes("lightning")) {
+		maxTokens = 262144;
+	} else if (lower.includes("muse") || lower.includes("spark")) {
+		maxTokens = 131072;
+	} else if (lower.includes("nemotron") && lower.includes("ultra")) {
+		maxTokens = 128000;
+	} else if (
+		lower.includes("gemini") ||
+		lower.includes("claude-3-7") ||
+		lower.includes("claude-sonnet") ||
+		lower.includes("claude-opus") ||
+		lower.includes("deepseek-v4")
+	) {
+		maxTokens = 65536;
+	} else if (
+		lower.includes("deepseek") ||
+		lower.includes("ling") ||
+		lower.includes("glm") ||
+		lower.includes("qwen") ||
+		lower.includes("grok") ||
+		lower.includes("minimax") ||
+		lower.includes("gpt-5") ||
+		lower.includes("o1") ||
+		lower.includes("o3")
+	) {
+		maxTokens = 32768;
+	} else if (lower.includes("jev") || lower.includes("system-1") || lower.includes("kimi-k2")) {
+		maxTokens = 16384;
+	} else {
+		maxTokens = 32000;
+	}
+
+	// 4. 是否支持推理思考 (reasoning)
+	let reasoning = true;
+	if (typeof raw?.reasoning === "boolean") {
+		reasoning = raw.reasoning;
+	} else if (typeof raw?.supports_thinking === "boolean") {
+		reasoning = raw.supports_thinking;
+	} else if (typeof raw?.thinking === "boolean") {
+		reasoning = raw.thinking;
+	} else if (
+		lower.includes("system-1") ||
+		lower.includes("reflex") ||
+		lower.includes("chat-only") ||
+		lower.includes("instruct-only") ||
+		lower.includes("base") ||
+		lower.includes("instant") ||
+		lower.includes("jev")
+	) {
+		reasoning = false;
+	}
+
+	// 5. 思考等级映射 (thinkingLevelMap)
+	let thinkingLevelMap: ZenModelDefinition["thinkingLevelMap"] = undefined;
+	if (reasoning) {
+		if (lower.includes("muse") || lower.includes("spark")) {
+			thinkingLevelMap = MUSE_SPARK_THINKING_LEVELS;
+		} else if (
+			lower.includes("gemini") ||
+			lower.includes("claude") ||
+			lower.includes("gpt-5") ||
+			lower.includes("o1") ||
+			lower.includes("o3") ||
+			lower.includes("o4")
+		) {
+			thinkingLevelMap = GRANULAR_THINKING_LEVELS;
+		} else {
+			thinkingLevelMap = STANDARD_THINKING_LEVELS;
+		}
+	}
+
+	// 6. 输入模态识别 (input)
+	let input: ("text" | "image")[] = ["text"];
+	if (Array.isArray(raw?.modalities) && raw.modalities.length > 0) {
+		input = raw.modalities.includes("image") || raw.modalities.includes("vision") ? ["text", "image"] : ["text"];
+	} else if (
+		lower.includes("vision") ||
+		lower.includes("vl") ||
+		lower.includes("multimodal") ||
+		lower.includes("image") ||
+		lower.includes("omni") ||
+		lower.includes("gemini") ||
+		lower.includes("claude") ||
+		lower.includes("mimo") ||
+		lower.includes("muse") ||
+		lower.includes("gpt-4o") ||
+		lower.includes("gpt-5")
+	) {
+		input = ["text", "image"];
+	}
+
+	let baseCleanName = modelId
 		.split(/[-_]/)
 		.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
 		.join(" ");
 
+	// 修正品牌专有大小写
+	baseCleanName = baseCleanName
+		.replace(/\bDeepseek\b/g, "DeepSeek")
+		.replace(/\bQwen\b/g, "Qwen")
+		.replace(/\bMinimax\b/g, "MiniMax")
+		.replace(/\bGpt\b/g, "GPT")
+		.replace(/\bGlm\b/g, "GLM")
+		.replace(/\bOpencode\b/g, "OpenCode");
+
+	let displayName = baseCleanName;
+	if (lower.includes("gemini") && !displayName.includes("Google")) {
+		displayName = `Google ${displayName}`;
+	} else if (lower.includes("claude") && !displayName.includes("Anthropic")) {
+		displayName = `Anthropic ${displayName}`;
+	} else if ((lower.includes("gpt") || lower.includes("o1") || lower.includes("o3")) && !displayName.includes("OpenAI")) {
+		displayName = `OpenAI ${displayName}`;
+	} else if (lower.includes("kimi") && !displayName.includes("Moonshot")) {
+		displayName = `Moonshot ${displayName}`;
+	} else if (lower.includes("grok") && !displayName.includes("xAI")) {
+		displayName = `xAI ${displayName}`;
+	} else if (lower.includes("nemotron") && !displayName.includes("NVIDIA")) {
+		displayName = `NVIDIA ${displayName}`;
+	} else if (lower.includes("mimo") && !displayName.includes("Xiaomi")) {
+		displayName = `Xiaomi ${displayName}`;
+	} else if (lower.includes("muse") && !displayName.includes("Meta")) {
+		displayName = `Meta ${displayName}`;
+	}
+
+	displayName = `${displayName} (OpenCode Zen)`;
+
 	return {
 		id: modelId,
-		name: `${friendlyName} (OpenCode Zen)`,
-		contextWindow: 200000,
-		maxTokens: 32000,
-		reasoning: isReasoning,
-		input: ["text", "image"],
-		thinkingLevelMap: isReasoning ? STANDARD_THINKING_LEVELS : undefined,
+		name: displayName,
+		contextWindow,
+		maxTokens,
+		reasoning,
+		input,
+		thinkingLevelMap,
 		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
 	};
 }
 
+/**
+ * 格式化 Token 数量为人类易读字符串 (如 1M, 256K, 200K)
+ */
+export function formatTokens(tokens: number): string {
+	if (tokens >= 1000000) {
+		const m = Math.round(tokens / 100000) / 10;
+		return `${m}M (${tokens.toLocaleString("en-US")} tokens)`;
+	}
+	if (tokens >= 1000) {
+		const k = Math.round(tokens / 1024);
+		return `${k}K (${tokens.toLocaleString("en-US")} tokens)`;
+	}
+	return `${tokens.toLocaleString("en-US")} tokens`;
+}
+
+/**
+ * 格式化模型思考等级与推理能力描述
+ */
+export function formatThinkingSummary(model: ZenModelDefinition): string {
+	if (!model.reasoning) {
+		return "不支持 (快反系统/无需思考)";
+	}
+	if (!model.thinkingLevelMap) {
+		return "支持思考 (默认档位)";
+	}
+	const activeLevels = Object.entries(model.thinkingLevelMap)
+		.filter(([_, v]) => v !== null && v !== undefined)
+		.map(([k]) => k);
+
+	if (activeLevels.length >= 6) {
+		return `6档深度思考 [${activeLevels.join(", ")}]`;
+	}
+	if (activeLevels.length > 0) {
+		return `${activeLevels.length}档思考 [${activeLevels.join(", ")}]`;
+	}
+	return "支持思考";
+}
+
+/**
+ * 格式化生成模型的结构化卡片展示信息
+ */
+export function formatModelCard(model: ZenModelDefinition, index?: number): string {
+	const prefix = typeof index === "number" ? `${index}. ` : "• ";
+	const ctxStr = formatTokens(model.contextWindow);
+	const outStr = formatTokens(model.maxTokens);
+	const thinkStr = formatThinkingSummary(model);
+	const inputStr = model.input.includes("image") ? "文本 + 视觉 (多模态)" : "纯文本";
+
+	return [
+		`${prefix}${model.name} (${model.id})`,
+		`   └─ 上下文: ${ctxStr} | 最大输出: ${outStr} | 思考等级: ${thinkStr} | 模态: ${inputStr} | 额度: 0免费`,
+	].join("\n");
+}
+
+/**
+ * 为未来可能新增的免费模型生成自适应默认配置（向后兼容）
+ */
+export function buildFallbackModelDefinition(modelId: string): ZenModelDefinition {
+	return inferModelCapabilities(modelId);
+}
+
 /**
  * 解析并生成完整的模型列表
  */
-export function resolveModelDefinitions(discoveredIds: string[]): ZenModelDefinition[] {
+export function resolveModelDefinitions(
+	discovered: Array<string | { id: string; [key: string]: unknown }>,
+): ZenModelDefinition[] {
 	const list: ZenModelDefinition[] = [];
 	const seen = new Set<string>();
 
-	for (const id of discoveredIds) {
-		if (seen.has(id)) continue;
+	for (const item of discovered) {
+		const id = typeof item === "string" ? item : item?.id;
+		if (!id || seen.has(id)) continue;
 		seen.add(id);
 
-		if (KNOWN_ZEN_FREE_MODELS[id]) {
-			list.push(KNOWN_ZEN_FREE_MODELS[id]);
-		} else {
-			list.push(buildFallbackModelDefinition(id));
-		}
+		const rawItem = typeof item === "object" ? item : undefined;
+		list.push(inferModelCapabilities(id, rawItem));
 	}
 
 	return list;

package/src/sync.ts

@@ -15,12 +15,16 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import {
+	formatModelCard,
+	formatThinkingSummary,
+	formatTokens,
 	KNOWN_ZEN_FREE_MODELS,
 	resolveModelDefinitions,
 	ZEN_BASE_URL,
 	ZEN_PROVIDER_ID,
 	ZEN_USER_AGENT,
 } from "./models-registry.js";
+export { formatModelCard, formatThinkingSummary, formatTokens };
 import {
 	DEFAULT_SESSION_MAX_AGE_MS,
 	extractZenSessionTimestamp,
@@ -44,9 +48,17 @@ export function defaultCcSwitchDbPath(): string {
 }
 
 /**
- * 校验 API Key 并拉取 OpenCode Zen 在线模型清单，自动识别所有免费与零额度模型
+ * 校验 API Key 并拉取 OpenCode Zen 在线模型清单，自动识别所有免费与零额度模型 ID
  */
 export async function fetchZenFreeModels(apiKey: string): Promise<string[]> {
+	const catalog = await fetchZenModelCatalog(apiKey);
+	return catalog.map((m) => m.id);
+}
+
+/**
+ * 校验 API Key 并拉取 OpenCode Zen 完整免费模型目录，深度解析上下文与思考等级
+ */
+export async function fetchZenModelCatalog(apiKey: string): Promise<ZenModelDefinition[]> {
 	const res = await fetch(`${ZEN_BASE_URL}/models`, {
 		method: "GET",
 		headers: {
@@ -62,23 +74,38 @@ export async function fetchZenFreeModels(apiKey: string): Promise<string[]> {
 
 	const data = (await res.json()) as { data?: Array<{ id: string; [key: string]: unknown }> };
 	if (!data || !Array.isArray(data.data)) {
-		return Object.keys(KNOWN_ZEN_FREE_MODELS);
+		return Object.values(KNOWN_ZEN_FREE_MODELS);
 	}
 
-	// 自动识别所有带 free / zero / pickle 标识的零额度消耗免费模型
-	const freeIds = data.data
-		.map((item) => String(item.id))
-		.filter((id) => {
-			const lower = id.toLowerCase();
-			return (
-				lower.includes("free") ||
-				lower.includes("pickle") ||
-				lower.includes("zero") ||
-				lower.endsWith("-free")
-			);
-		});
+	// 自动识别所有带 free / zero / pickle / trial / demo / community 标识或零额度的免费模型
+	const freeItems = data.data.filter((item) => {
+		const id = String(item.id || "");
+		const lower = id.toLowerCase();
+		const isFreeByKeyword =
+			lower.includes("free") ||
+			lower.includes("pickle") ||
+			lower.includes("zero") ||
+			lower.includes("trial") ||
+			lower.includes("demo") ||
+			lower.includes("community") ||
+			lower.endsWith("-free");
+
+		const isFreeByMetadata =
+			(item as { free?: boolean }).free === true ||
+			(item as { is_free?: boolean }).is_free === true ||
+			(item as { tier?: string }).tier === "free" ||
+			((item as { cost?: { input?: number; output?: number } }).cost &&
+				(item as { cost: { input: number; output: number } }).cost.input === 0 &&
+				(item as { cost: { input: number; output: number } }).cost.output === 0) ||
+			((item as { pricing?: { input?: number } }).pricing &&
+				(item as { pricing: { input: number } }).pricing.input === 0);
+
+		const isKnown = KNOWN_ZEN_FREE_MODELS[id] !== undefined;
+
+		return isFreeByKeyword || isFreeByMetadata || isKnown;
+	});
 
-	return freeIds.length > 0 ? freeIds : Object.keys(KNOWN_ZEN_FREE_MODELS);
+	return freeItems.length > 0 ? resolveModelDefinitions(freeItems) : Object.values(KNOWN_ZEN_FREE_MODELS);
 }
 
 /**
@@ -217,21 +244,31 @@ export async function syncZenConfiguration(options: ZenSyncOptions = {}): Promis
 		throw new Error("未检测到 OpenCode Zen API Key。请指定 Key，例如：/zen oc_sk_xxx");
 	}
 
-	// 1. 在线校验 API Key 并拉取最新免费模型
-	const fetcher = options.fetchModels ?? fetchZenFreeModels;
-	let freeModelIds: string[] = [];
-	try {
-		freeModelIds = await fetcher(resolvedApiKey);
-	} catch (error) {
-		// 若因网络波动失败但已有已知列表，允许回退
-		if (!options.apiKey || options.fetchModels) {
-			freeModelIds = Object.keys(KNOWN_ZEN_FREE_MODELS);
-		} else {
-			throw error;
+	// 1. 在线校验 API Key 并拉取最新免费模型及精确能力规格
+	let resolvedModels: ZenModelDefinition[] = [];
+	if (options.fetchModels) {
+		try {
+			const fetched = await options.fetchModels(resolvedApiKey);
+			resolvedModels = resolveModelDefinitions(fetched);
+		} catch (error) {
+			if (!options.apiKey) {
+				resolvedModels = Object.values(KNOWN_ZEN_FREE_MODELS);
+			} else {
+				throw error;
+			}
+		}
+	} else {
+		try {
+			resolvedModels = await fetchZenModelCatalog(resolvedApiKey);
+		} catch (error) {
+			if (!options.apiKey) {
+				resolvedModels = Object.values(KNOWN_ZEN_FREE_MODELS);
+			} else {
+				throw error;
+			}
 		}
 	}
-
-	const resolvedModels = resolveModelDefinitions(freeModelIds);
+	const freeModelIds = resolvedModels.map((m) => m.id);
 
 	// 2. 确定 Session ID：若显式强制更新或当前已过期，则生成全新合规 Session
 	const currentSession = getStoredZenSessionId(modelsPath);

package/src/types.ts

@@ -43,7 +43,7 @@ export interface ZenSyncOptions {
 	modelsPath?: string;
 	authPath?: string;
 	dbPath?: string;
-	fetchModels?: (apiKey: string) => Promise<string[]>;
+	fetchModels?: (apiKey: string) => Promise<Array<string | { id: string; [key: string]: unknown }>>;
 }
 
 export interface ZenSyncResult {