ck-pi-zen-session 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+Copyright (c) 传康Kk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# ck-pi-zen-session
+
+OpenCode Zen 免费模型同步、请求头伪装与 Session 会话自动维护插件，专为 [Pi 编码智能体](https://github.com/earendil-works/pi) 打造。
+
+---
+
+## 🌟 核心特性
+
+- ⚡ **/zen 指令一键激活**：输入一次 API Key (`/zen oc_sk_...`)，全自动验证、探测 9 款可用免费模型并注入 Pi 与 CC-Switch。
+- 🔄 **官方算法深度逆向**：完整对齐 OpenCode 客户端 `Identifier.descending("ses")` 与 `Identifier.ascending("msg")` 算法，生成 30 位降序会话 ID 与升序请求 ID，支持毫秒级时间戳反解。
+- 🛡️ **全套官方级伪装请求头**：自动注入全部 6 个官方客户端对齐请求头：
+  - `User-Agent`: `opencode/1.18.32 ai-sdk/provider-utils/4.0.23 runtime/bun/1.3.14`
+  - `x-opencode-client`: `cli`
+  - `x-opencode-session`: `ses_<12位反转时间戳十六进制><14位Base62>`
+  - `x-session-affinity`: 与 session 严格同步
+  - `X-Session-Id`: 与 session 严格同步
+  - `x-opencode-request`: `msg_<12位升序时间戳十六进制><14位Base62>`（每次 HTTP 请求唯一）
+- ⏱️ **45 分钟无感前置平滑轮换**：官方后端限制免费会话时长约为 1 小时（超时直接 403 `FreeTierError`）。本插件在底层请求拦截器（`before_provider_headers`）和 Agent 循环守卫（`before_agent_start`）中设置 45 分钟主动换新阈值，确保永不触碰 1 小时硬限制。
+- 🧰 **Agent 工具链兼容性守卫**：OpenCode Zen 免费端点对工具集有硬性要求（无工具直接拒绝）。插件在 `before_provider_request` 钩子中实时监控请求体，若用户处于无工具或纯文本问答模式，自动补齐兼容性工具定义，彻底根除 403 拦截。
+- 🌐 **独立供应商隔离命名空间**：注册为独立供应商 `opencode-zen-free`，彻底避开并兼容用户自带的官方登录 `opencode` / `opencode-zen` 套餐，互不干扰、平稳共存。
+- 🧠 **精准上下文与思维链适配**：严格对齐 9 款免费模型的 `contextWindow`、`maxTokens` 与 `thinkingLevelMap`（涵盖小米 MiMo、英伟达 Nemotron、Meta Muse Spark、Ling、Jev 等）。
+- 🔌 **全自动多端持久化同步**：自动双写 Pi 本地配置（`~/.pi/agent/models.json` 和 `~/.pi/agent/auth.json`），若检测到 CC-Switch 亦无缝同步其 SQLite 数据库。
+
+---
+
+## 📦 安装方法
+
+### 方式 1：npm 安装（推荐）
+
+```bash
+pi install npm:ck-pi-zen-session
+```
+
+### 方式 2：GitHub 源码安装
+
+```bash
+pi install git:github.com/1837620622/ck-pi-extension
+```
+
+---
+
+## 🚀 指令用法
+
+在 Pi 交互界面中直接键入 `/zen`：
+
+| 指令 | 说明 |
+| --- | --- |
+| `/zen <oc_sk_xxx>` | 设置/更新 API Key，自动在线验证并全量同步模型与全套请求头 |
+| `/zen` | 智能检查当前会话状态；若会话临近过期自动换新；若未配置 Key 则弹出交互输入框 |
+| `/zen refresh` | 强制生成全新的合法降序 Session ID 并更新所有请求头与落盘配置 |
+| `/zen status` | 查看当前 API Key 掩码、活跃会话精确存活时间及模型就绪状态 |
+| `/zen list`（或 `/zen models`） | 查看当前已激活的所有免费模型列表 |
+
+---
+
+## 🤖 内置免费模型库参数
+
+插件自动同步官方 9 款免费模型并配置精准上限与思维链等级：
+
+| 模型 ID | 上下文窗口 | 最大输出 | 推理思考等级 (thinkingLevelMap) | 支持模态 |
+| --- | --- | --- | --- | --- |
+| `mimo-v2.5-free` | 200,000 | 32,000 | low / high / max | 文本、图像 |
+| `mimo-v2.6-flash-free` | 200,000 | 32,000 | low / high / max | 文本、图像 |
+| `nemotron-3.5-lightning-free` | 262,144 | 262,144 | low / high / max | 文本 |
+| `nemotron-3-ultra-free` | 1,000,000 (1M) | 128,000 | low / high / max | 文本 |
+| `ling-3.0-flash-fin-free` | 262,144 | 32,768 | low / high / max | 文本 |
+| `big-pickle` | 200,000 | 32,000 | low / high / max | 文本 |
+| `muse-spark-1.3-contributor-free` | 1,048,576 (1M) | 131,072 | minimal / low / medium / high / xhigh | 文本、图像 |
+| `muse-spark-1.2-contributor-free` | 1,048,576 (1M) | 131,072 | minimal / low / medium / high / xhigh | 文本、图像 |
+| `jev-1.13-free` | 128,000 | 16,384 | 基础模型（无 reasoning） | 文本 |
+
+> 若 OpenCode 后端未来发布新免费模型，插件将自动探测发现并使用安全的自适应参数接入。
+
+---
+
+## 🔬 官方算法逆向解析
+
+OpenCode Zen 客户端针对防刷和网关鉴权设计了基于时间戳编码的降序（descending）与升序（ascending）标识符体系：
+
+```typescript
+// 1. Session ID (前缀 ses_, 降序排列)
+export function generateZenSessionId(timestampMs = Date.now()): string {
+  const combined = BigInt(timestampMs) * 0x1000n + BigInt(sequenceCounter);
+  const inverted = ~combined; // 关键位反转：时间越新，字典序十六进制越小
+  let hex = "";
+  for (let i = 0; i < 6; i++) {
+    const byte = Number((inverted >> BigInt(40 - 8 * i)) & 0xffn);
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return `ses_${hex}${randomBase62(14)}`; // 30 字符
+}
+
+// 2. Request ID (前缀 msg_, 升序排列)
+export function generateZenRequestId(timestampMs = Date.now()): string {
+  const combined = BigInt(timestampMs) * 0x1000n + BigInt(sequenceCounter);
+  let hex = "";
+  for (let i = 0; i < 6; i++) {
+    const byte = Number((combined >> BigInt(40 - 8 * i)) & 0xffn);
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return `msg_${hex}${randomBase62(14)}`; // 30 字符
+}
+```
+
+---
+
+## 👨‍💻 作者与许可
+
+- 作者：传康Kk
+- 邮箱：`1837620622@qq.com`
+- 仓库：[https://github.com/1837620622/ck-pi-extension](https://github.com/1837620622/ck-pi-extension)
+- 协议：MIT License

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "ck-pi-zen-session",
+  "version": "0.1.0",
+  "description": "OpenCode Zen session auto-refresh and free-tier model catalog synchronization for the Pi coding agent.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "opencode",
+    "zen",
+    "session",
+    "free-tier"
+  ],
+  "license": "MIT",
+  "author": "传康Kk <1837620622@qq.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1837620622/ck-pi-extension.git",
+    "directory": "packages/pi-zen-session"
+  },
+  "homepage": "https://github.com/1837620622/ck-pi-extension#pi-zen-session",
+  "bugs": {
+    "url": "https://github.com/1837620622/ck-pi-extension/issues"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "!src/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.85.0"
+  },
+  "scripts": {
+    "test": "esbuild src/index.test.ts --bundle --packages=external --platform=node --format=esm --outfile=.test-dist/test.mjs --log-level=warning && node --test .test-dist/test.mjs"
+  }
+}

package/src/index.ts

@@ -0,0 +1,358 @@
+/**
+ * OpenCode Zen 插件主入口 (ck-pi-zen-session)
+ *
+ * 功能特色：
+ * 1. 提供 /zen 命令：支持输入 Key 即刻激活、刷新 Session、查看状态与模型清单；
+ * 2. 逆向对齐官方 Identifier.descending("ses") 算法，保真生成 30 位降序会话 ID；
+ * 3. 自动注入伪装请求头 (User-Agent, x-opencode-session)；
+ * 4. 自动双写 ~/.pi/agent/models.json 与 CC-Switch 本地数据库；
+ * 5. 常驻 before_agent_start 钩子：每当 Session 临近过期（>12h），后台无感自动刷新。
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import {
+	KNOWN_ZEN_FREE_MODELS,
+	ZEN_BASE_URL,
+	ZEN_PROVIDER_ID,
+	ZEN_USER_AGENT,
+} from "./models-registry.js";
+import {
+	getStoredZenApiKey,
+	getStoredZenSessionId,
+	getZenStatusInfo,
+	syncZenConfiguration,
+} from "./sync.js";
+import {
+	DEFAULT_SESSION_MAX_AGE_MS,
+	generateZenRequestId,
+	generateZenSessionId,
+	isZenSessionExpired,
+	isValidZenSessionId,
+} from "./session.js";
+
+export function registerZenProviderToPi(
+	pi: ExtensionAPI,
+	apiKey: string,
+	sessionId: string = getStoredZenSessionId() || generateZenSessionId(),
+): void {
+	try {
+		pi.registerProvider(ZEN_PROVIDER_ID, {
+			name: "OpenCode Zen (Free)",
+			baseUrl: ZEN_BASE_URL,
+			apiKey: apiKey,
+			api: "openai-completions",
+			headers: {
+				"User-Agent": ZEN_USER_AGENT,
+				"x-opencode-client": "cli",
+				"x-opencode-session": sessionId,
+				"x-session-affinity": sessionId,
+				"X-Session-Id": sessionId,
+			},
+			compat: {
+				maxTokensField: "max_tokens",
+				requiresReasoningContentOnAssistantMessages: true,
+				supportsDeveloperRole: false,
+				supportsStore: false,
+			},
+			models: Object.values(KNOWN_ZEN_FREE_MODELS),
+		});
+	} catch {
+		// 忽略重复注册
+	}
+}
+
+export default function piZenSession(pi: ExtensionAPI): void {
+	// 1. 若本地已配置 Key，启动时即刻注册独立供应商 opencode-zen-free
+	// 独立命名空间，彻底避开并兼容用户自带的官方登录 opencode / opencode-zen 套餐
+	const existingKey = getStoredZenApiKey();
+	if (existingKey) {
+		registerZenProviderToPi(pi, existingKey);
+	}
+
+	// 2. 核心请求头拦截钩子：在每一次请求发往 Provider 前注入完整伪装请求头
+	pi.on("before_provider_headers", (event, ctx) => {
+		const model = ctx.model;
+		const isZenModel =
+			model?.provider === ZEN_PROVIDER_ID ||
+			model?.id?.includes("-free") ||
+			model?.id === "big-pickle";
+
+		if (isZenModel) {
+			// 检查 x-opencode-session 是否过期 (>45分钟) 或缺失
+			let currentSession = event.headers["x-opencode-session"];
+			if (
+				typeof currentSession !== "string" ||
+				!isValidZenSessionId(currentSession) ||
+				isZenSessionExpired(currentSession, DEFAULT_SESSION_MAX_AGE_MS)
+			) {
+				currentSession = generateZenSessionId();
+				event.headers["x-opencode-session"] = currentSession;
+				// 异步落盘，保持配置同步
+				syncZenConfiguration({ forceSession: true }).catch(() => {});
+			}
+
+			// 注入全部官方客户端对齐请求头
+			event.headers["User-Agent"] = ZEN_USER_AGENT;
+			event.headers["x-opencode-client"] = "cli";
+			event.headers["x-opencode-session"] = currentSession;
+			event.headers["x-session-affinity"] = currentSession;
+			event.headers["X-Session-Id"] = currentSession;
+			event.headers["x-opencode-request"] = generateZenRequestId();
+		}
+	});
+
+	// 3. 核心请求体守卫钩子：OpenCode Zen 免费端点对工具集有硬性要求，若缺失工具会报 403 FreeTierError
+	pi.on("before_provider_request", (event, ctx) => {
+		const model = ctx.model;
+		const isZenModel =
+			model?.provider === ZEN_PROVIDER_ID ||
+			model?.id?.includes("-free") ||
+			model?.id === "big-pickle";
+
+		if (isZenModel && event.payload && typeof event.payload === "object") {
+			const payload = event.payload as Record<string, unknown>;
+			const tools = payload.tools;
+			// 若当前请求没有附带任何工具定义（如纯文本问答模式），自动补齐兼容性工具定义以规避 403 拦截
+			if (!Array.isArray(tools) || tools.length === 0) {
+				return {
+					...payload,
+					tools: [
+						{
+							type: "function",
+							function: {
+								name: "bash",
+								description: "Execute bash command in the terminal",
+								parameters: {
+									type: "object",
+									properties: {
+										command: { type: "string", description: "Command to execute" },
+									},
+									required: ["command"],
+								},
+							},
+						},
+						{
+							type: "function",
+							function: {
+								name: "read",
+								description: "Read contents of a file",
+								parameters: {
+									type: "object",
+									properties: {
+										path: { type: "string", description: "Path to file" },
+									},
+									required: ["path"],
+								},
+							},
+						},
+					],
+				};
+			}
+		}
+	});
+
+	// 4. 常驻生命周期守卫：在每次 Agent 循环执行前，自动检测 Session 有效性并无感续期
+	pi.on("before_agent_start", async () => {
+		try {
+			const currentSession = getStoredZenSessionId();
+			// 若当前会话不存在或已使用超过 45 分钟，后台自动续期
+			if (!currentSession || isZenSessionExpired(currentSession, DEFAULT_SESSION_MAX_AGE_MS)) {
+				const apiKey = getStoredZenApiKey();
+				if (apiKey) {
+					await syncZenConfiguration({ forceSession: true });
+				}
+			}
+		} catch {
+			// 后台静默处理，绝不中断用户的编码交互流程
+		}
+	});
+
+	// 4. 注册 /zen 指令
+	pi.registerCommand("zen", {
+		description: "OpenCode Zen 免费模型与 Session 会话自动维护 (/zen [key|refresh|status|list])",
+		getArgumentCompletions: (prefix: string) => {
+			const candidates = ["refresh", "status", "list", "models"]
+				.filter((cmd) => cmd.startsWith(prefix.toLowerCase()))
+				.map((cmd) => ({ value: cmd, label: cmd }));
+			return candidates.length > 0 ? candidates : null;
+		},
+		handler: async (args, ctx) => {
+			await handleZenCommand(args, ctx, pi);
+		},
+	});
+}
+
+export async function handleZenCommand(
+	args: string,
+	ctx: ExtensionCommandContext,
+	pi?: ExtensionAPI,
+): Promise<void> {
+	const rawArg = args.trim();
+	const command = rawArg.toLowerCase();
+
+	// 1. 查看状态: /zen status
+	if (command === "status") {
+		const status = getZenStatusInfo();
+		if (!status.hasKey) {
+			notify(ctx, "OpenCode Zen 尚未配置 API Key。请使用 /zen <oc_sk_xxx> 进行配置。", "warning");
+			return;
+		}
+
+		const ageDesc = status.sessionAgeMinutes < 60
+			? `${status.sessionAgeMinutes} 分钟`
+			: `${(status.sessionAgeMinutes / 60).toFixed(1)} 小时`;
+
+		const msg = [
+			"✨ [OpenCode Zen 运行状态]",
+			`• API Key: ${status.maskedKey}`,
+			`• Session: ${status.sessionId || "未生成"} (${status.sessionExpired ? "已过期" : `有效，创建于 ${ageDesc}前`})`,
+			`• 模型库: 已激活 ${status.modelsCount} 个免费模型`,
+			"",
+			"常用指令：",
+			"  /zen <key>   - 更新 Key 并全量重新同步",
+			"  /zen refresh - 强制换新 Session ID",
+			"  /zen list    - 查看所有可用免费模型规格",
+		].join("\n");
+
+		notify(ctx, msg, "info");
+		return;
+	}
+
+	// 2. 查看模型清单: /zen list 或 /zen models
+	if (command === "list" || command === "models") {
+		const status = getZenStatusInfo();
+		if (status.modelIds.length === 0) {
+			notify(ctx, "当前尚未同步任何模型，请先运行 /zen <key>。", "warning");
+			return;
+		}
+
+		const listMsg = [
+			`✨ [OpenCode Zen 免费模型列表 (${status.modelIds.length} 个)]`,
+			...status.modelIds.map((id) => `  • ${id}`),
+			"",
+			"提示：这些模型已就绪，可在 Pi 中直接切换使用！",
+		].join("\n");
+
+		notify(ctx, listMsg, "info");
+		return;
+	}
+
+	// 3. 强制换新 Session: /zen refresh
+	if (command === "refresh") {
+		try {
+			notify(ctx, "正在生成全新 OpenCode Zen 会话 ID 并同步...", "info");
+			const result = await syncZenConfiguration({ forceSession: true });
+			if (pi) {
+				registerZenProviderToPi(pi, result.apiKey, result.sessionId);
+			}
+			const successMsg = [
+				"✓ OpenCode Zen Session 已成功刷新！",
+				`• 全新 Session: ${result.sessionId}`,
+				`• 请求头伪装: User-Agent, x-opencode-session 已注入`,
+				`• 同步状态: models.json ✓ | CC-Switch ${result.ccSwitchUpdated ? "✓" : "-(未安装或无此条目)"}`,
+			].join("\n");
+			notify(ctx, successMsg, "info");
+		} catch (error) {
+			notify(ctx, `刷新失败: ${formatError(error)}`, "error");
+		}
+		return;
+	}
+
+	// 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");
+			const result = await syncZenConfiguration({ apiKey: rawArg, forceSession: true });
+			if (pi) {
+				registerZenProviderToPi(pi, result.apiKey, result.sessionId);
+			}
+			const msg = [
+				"🎉 OpenCode Zen 配置成功！免费套餐与请求头已全部就绪：",
+				`• API Key: ${maskKey(result.apiKey)} (已验证并保存)`,
+				`• 会话 Session: ${result.sessionId} (官方降序时间戳逆向算法)`,
+				`• 发现免费模型: ${result.modelsCount} 个已自动配置 (含思维链 thinkingLevelMap 适配)`,
+				`• 同步路径: ${result.modelsPath}`,
+				result.ccSwitchUpdated ? "• CC-Switch: 本地数据库已同步更新" : "",
+			].filter(Boolean).join("\n");
+			notify(ctx, msg, "info");
+		} catch (error) {
+			notify(ctx, `配置失败: ${formatError(error)}`, "error");
+		}
+		return;
+	}
+
+	// 5. 无参调用: /zen
+	const status = getZenStatusInfo();
+	if (status.hasKey) {
+		// 已有 Key 时，自动检测并刷新 Session
+		try {
+			notify(ctx, "正在检测并刷新 OpenCode Zen 会话...", "info");
+			const result = await syncZenConfiguration({ forceSession: status.sessionExpired });
+			if (pi) {
+				registerZenProviderToPi(pi, result.apiKey, result.sessionId);
+			}
+			const msg = [
+				"✨ [OpenCode Zen 已连接就绪]",
+				`• API Key: ${maskKey(result.apiKey)}`,
+				`• 活跃 Session: ${result.sessionId} (${result.isNewSession ? "已换新" : "仍有效"})`,
+				`• 免费模型: ${result.modelsCount} 个可用`,
+				"",
+				"常用操作：",
+				"  /zen <key>   - 更换 API Key",
+				"  /zen refresh - 换新会话 ID",
+				"  /zen status  - 详情状态",
+			].join("\n");
+			notify(ctx, msg, "info");
+		} catch (error) {
+			notify(ctx, `同步状态失败: ${formatError(error)}`, "error");
+		}
+		return;
+	}
+
+	// 没有 Key，如果在支持交互的 UI 环境下，弹出输入框
+	if (ctx.hasUI && typeof ctx.ui.input === "function") {
+		try {
+			const enteredKey = await ctx.ui.input(
+				"请输入 OpenCode Zen API Key (形如 oc_sk_...):",
+				"oc_sk_",
+			);
+			if (enteredKey && enteredKey.trim()) {
+				await handleZenCommand(enteredKey.trim(), ctx);
+				return;
+			}
+			notify(ctx, "已取消输入。如需配置请使用 /zen <oc_sk_xxx>", "info");
+			return;
+		} catch {
+			// fallthrough to text usage
+		}
+	}
+
+	notify(ctx, "请提供 OpenCode Zen API Key。用法：/zen <oc_sk_xxx>", "warning");
+}
+
+function maskKey(key: string): string {
+	if (!key) return "未配置";
+	if (key.length <= 12) return "******";
+	return `${key.slice(0, 8)}...${key.slice(-4)}`;
+}
+
+function notify(
+	ctx: ExtensionCommandContext,
+	message: string,
+	level: "info" | "warning" | "error" = "info",
+): void {
+	try {
+		if (ctx.hasUI) {
+			ctx.ui.notify(message, level);
+		} else {
+			// 终端或非交互环境日志输出
+			console.log(`[${level.toUpperCase()}] ${message}`);
+		}
+	} catch {
+		// 容错
+	}
+}
+
+function formatError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/models-registry.ts

@@ -0,0 +1,170 @@
+/**
+ * OpenCode Zen 免费模型参数与配置注册表
+ *
+ * 严格基于 OpenCode 官方客户端内置参数与在线端点响应对齐：
+ * 包含精确上下文上限（Context Window）、最大输出（Max Tokens）、推理思考等级映射（thinkingLevelMap）与输入模态。
+ */
+
+import type { ZenModelDefinition } from "./types.js";
+
+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> = {
+	low: "low",
+	high: "high",
+	max: "max",
+	medium: null,
+	minimal: null,
+	off: null,
+	xhigh: null,
+};
+
+const MUSE_SPARK_THINKING_LEVELS: Record<string, string | null> = {
+	minimal: "minimal",
+	low: "low",
+	medium: "medium",
+	high: "high",
+	xhigh: "xhigh",
+	max: "xhigh",
+	off: null,
+};
+
+/**
+ * 官方已知免费模型精确规格字典
+ */
+export const KNOWN_ZEN_FREE_MODELS: Record<string, ZenModelDefinition> = {
+	"mimo-v2.5-free": {
+		id: "mimo-v2.5-free",
+		name: "Xiaomi Mimo v2.5 Free (OpenCode Zen)",
+		contextWindow: 200000,
+		maxTokens: 32000,
+		reasoning: true,
+		input: ["text", "image"],
+		thinkingLevelMap: STANDARD_THINKING_LEVELS,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	},
+	"mimo-v2.6-flash-free": {
+		id: "mimo-v2.6-flash-free",
+		name: "Xiaomi Mimo v2.6 Flash Free (OpenCode Zen)",
+		contextWindow: 200000,
+		maxTokens: 32000,
+		reasoning: true,
+		input: ["text", "image"],
+		thinkingLevelMap: STANDARD_THINKING_LEVELS,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	},
+	"nemotron-3.5-lightning-free": {
+		id: "nemotron-3.5-lightning-free",
+		name: "Nemotron 3.5 Lightning Free (OpenCode Zen)",
+		contextWindow: 262144,
+		maxTokens: 262144,
+		reasoning: true,
+		input: ["text"],
+		thinkingLevelMap: STANDARD_THINKING_LEVELS,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	},
+	"nemotron-3-ultra-free": {
+		id: "nemotron-3-ultra-free",
+		name: "Nemotron 3 Ultra Free (OpenCode Zen)",
+		contextWindow: 1000000,
+		maxTokens: 128000,
+		reasoning: true,
+		input: ["text"],
+		thinkingLevelMap: STANDARD_THINKING_LEVELS,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	},
+	"ling-3.0-flash-fin-free": {
+		id: "ling-3.0-flash-fin-free",
+		name: "Ling 3.0 Flash Fin Free (OpenCode Zen)",
+		contextWindow: 262144,
+		maxTokens: 32768,
+		reasoning: true,
+		input: ["text"],
+		thinkingLevelMap: STANDARD_THINKING_LEVELS,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	},
+	"big-pickle": {
+		id: "big-pickle",
+		name: "Big Pickle Free (OpenCode Zen)",
+		contextWindow: 200000,
+		maxTokens: 32000,
+		reasoning: true,
+		input: ["text"],
+		thinkingLevelMap: STANDARD_THINKING_LEVELS,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	},
+	"muse-spark-1.3-contributor-free": {
+		id: "muse-spark-1.3-contributor-free",
+		name: "Meta Muse Spark 1.3 Free (OpenCode Zen)",
+		contextWindow: 1048576,
+		maxTokens: 131072,
+		reasoning: true,
+		input: ["text", "image"],
+		thinkingLevelMap: MUSE_SPARK_THINKING_LEVELS,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	},
+	"muse-spark-1.2-contributor-free": {
+		id: "muse-spark-1.2-contributor-free",
+		name: "Meta Muse Spark 1.2 Free (OpenCode Zen)",
+		contextWindow: 1048576,
+		maxTokens: 131072,
+		reasoning: true,
+		input: ["text", "image"],
+		thinkingLevelMap: MUSE_SPARK_THINKING_LEVELS,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	},
+	"jev-1.13-free": {
+		id: "jev-1.13-free",
+		name: "TypeSafe Jev 1.13 System-1 Free (OpenCode Zen)",
+		contextWindow: 128000,
+		maxTokens: 16384,
+		reasoning: false,
+		input: ["text"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	},
+};
+
+/**
+ * 为未来可能新增的免费模型生成自适应默认配置
+ */
+export function buildFallbackModelDefinition(modelId: string): ZenModelDefinition {
+	const isReasoning = !modelId.includes("chat") && !modelId.includes("turbo");
+	const friendlyName = modelId
+		.split(/[-_]/)
+		.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+		.join(" ");
+
+	return {
+		id: modelId,
+		name: `${friendlyName} (OpenCode Zen)`,
+		contextWindow: 200000,
+		maxTokens: 32000,
+		reasoning: isReasoning,
+		input: ["text", "image"],
+		thinkingLevelMap: isReasoning ? STANDARD_THINKING_LEVELS : undefined,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	};
+}
+
+/**
+ * 解析并生成完整的模型列表
+ */
+export function resolveModelDefinitions(discoveredIds: string[]): ZenModelDefinition[] {
+	const list: ZenModelDefinition[] = [];
+	const seen = new Set<string>();
+
+	for (const id of discoveredIds) {
+		if (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));
+		}
+	}
+
+	return list;
+}

package/src/session.ts

@@ -0,0 +1,163 @@
+/**
+ * OpenCode Zen 客户端会话 ID 逆向生成器与时间戳解析器
+ *
+ * 逆向自 OpenCode 官方二进制客户端 Identifier.descending("ses") 算法：
+ * 1. 结构：ses_<12位反转时间戳十六进制><14位Base62随机安全字符>，总长 30 字符。
+ * 2. 时间戳编码：
+ *    combined = BigInt(Date.now()) * 4096n + BigInt(counter)
+ *    inverted = ~combined
+ *    取低 48 位按大端序编码为 12 位十六进制。
+ * 3. 降序特性（descending）：时间越晚，按字典序排序越靠前。
+ */
+
+import { webcrypto } from "node:crypto";
+
+const B62_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+
+let lastTimestamp = 0;
+let sequenceCounter = 0;
+
+/**
+ * 生成符合 OpenCode 官方规约的 Session ID (前缀 ses_)
+ * @param timestampMs 毫秒时间戳，默认为 Date.now()
+ */
+export function generateZenSessionId(timestampMs: number = Date.now()): string {
+	if (timestampMs !== lastTimestamp) {
+		lastTimestamp = timestampMs;
+		sequenceCounter = 0;
+	}
+	sequenceCounter++;
+
+	// 0x1000n = 4096n
+	const combined = BigInt(timestampMs) * 0x1000n + BigInt(sequenceCounter);
+	const inverted = ~combined;
+
+	// 6 字节（48 位）大端序十六进制
+	let hex = "";
+	for (let i = 0; i < 6; i++) {
+		const byte = Number((inverted >> BigInt(40 - 8 * i)) & 0xffn);
+		hex += byte.toString(16).padStart(2, "0");
+	}
+
+	// 14 字符 Base62 密码学安全随机串
+	const randBytes = new Uint8Array(14);
+	if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+		crypto.getRandomValues(randBytes);
+	} else if (webcrypto && webcrypto.getRandomValues) {
+		webcrypto.getRandomValues(randBytes);
+	} else {
+		for (let i = 0; i < 14; i++) {
+			randBytes[i] = Math.floor(Math.random() * 256);
+		}
+	}
+
+	let randStr = "";
+	for (let i = 0; i < 14; i++) {
+		randStr += B62_CHARS[randBytes[i] % 62];
+	}
+
+	return `ses_${hex}${randStr}`;
+}
+
+/**
+ * 生成符合 OpenCode 官方规约的 Request 请求唯一标识符 (前缀 msg_, 升序 ascending)
+ * @param timestampMs 毫秒时间戳，默认为 Date.now()
+ */
+export function generateZenRequestId(timestampMs: number = Date.now()): string {
+	if (timestampMs !== lastTimestamp) {
+		lastTimestamp = timestampMs;
+		sequenceCounter = 0;
+	}
+	sequenceCounter++;
+
+	const combined = BigInt(timestampMs) * 0x1000n + BigInt(sequenceCounter);
+	// 升序直接编码，不取反
+	let hex = "";
+	for (let i = 0; i < 6; i++) {
+		const byte = Number((combined >> BigInt(40 - 8 * i)) & 0xffn);
+		hex += byte.toString(16).padStart(2, "0");
+	}
+
+	const randBytes = new Uint8Array(14);
+	if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+		crypto.getRandomValues(randBytes);
+	} else if (webcrypto && webcrypto.getRandomValues) {
+		webcrypto.getRandomValues(randBytes);
+	} else {
+		for (let i = 0; i < 14; i++) {
+			randBytes[i] = Math.floor(Math.random() * 256);
+		}
+	}
+
+	let randStr = "";
+	for (let i = 0; i < 14; i++) {
+		randStr += B62_CHARS[randBytes[i] % 62];
+	}
+
+	return `msg_${hex}${randStr}`;
+}
+
+/**
+ * 校验字符串是否为标准 OpenCode Zen Session ID
+ */
+export function isValidZenSessionId(id: string | null | undefined): boolean {
+	if (!id || typeof id !== "string") return false;
+	return /^ses_[0-9a-f]{12}[0-9A-Za-z]{14}$/.test(id);
+}
+
+/**
+ * 从降序 Session ID 中提取精确创建毫秒时间戳
+ * @param sessionId ses_ 开头的 30 位 ID
+ * @param referenceTimeMs 参考基准时间（默认当前时间），用于消解 36 位周期（约 2.18 年）
+ */
+export function extractZenSessionTimestamp(
+	sessionId: string,
+	referenceTimeMs: number = Date.now(),
+): number | null {
+	if (!isValidZenSessionId(sessionId)) return null;
+
+	const hex = sessionId.slice(4, 16);
+	const inverted48 = BigInt(`0x${hex}`);
+	// inverted48 = 0xffffffffffffn - (combined & 0xffffffffffffn)
+	const combined48 = 0xffffffffffffn - inverted48;
+	const ts48 = combined48 / 0x1000n; // 36 位时间戳部分
+
+	const MOD_36 = 1n << 36n;
+	const refBig = BigInt(referenceTimeMs);
+	const refBase = refBig - (refBig % MOD_36);
+	let candidate = refBase + ts48;
+
+	// 若相差超过半个周期，微调回正确的时间跨度
+	if (candidate > refBig + (MOD_36 / 2n)) {
+		candidate -= MOD_36;
+	} else if (candidate < refBig - (MOD_36 / 2n)) {
+		candidate += MOD_36;
+	}
+
+	return Number(candidate);
+}
+
+/**
+ * 官方 OpenCode Zen 后端对会话生命周期严格限制（超 1 小时即报 403 FreeTierError）
+ * 默认设定为 45 分钟，确保在达到 1 小时硬限制前无感平滑轮换
+ */
+export const DEFAULT_SESSION_MAX_AGE_MS = 45 * 60 * 1000;
+
+/**
+ * 判断指定 Session ID 是否已过期
+ * @param sessionId 会话 ID
+ * @param maxAgeMs 最大允许有效时长（默认 45 分钟）
+ * @param nowMs 当前时间戳
+ */
+export function isZenSessionExpired(
+	sessionId: string | null | undefined,
+	maxAgeMs: number = DEFAULT_SESSION_MAX_AGE_MS,
+	nowMs: number = Date.now(),
+): boolean {
+	if (!sessionId) return true;
+	const ts = extractZenSessionTimestamp(sessionId, nowMs);
+	if (ts === null) return true;
+	const age = nowMs - ts;
+	// 超过最大年限或超出未来 5 分钟（时钟漂移异常）均视为过期
+	return age > maxAgeMs || age < -(5 * 60 * 1000);
+}

package/src/sync.ts

@@ -0,0 +1,375 @@
+/**
+ * OpenCode Zen 模型发现、Session 维护与配置同步服务
+ *
+ * 负责：
+ * 1. 验证 OpenCode Zen API Key 并在线获取最新可用免费模型清单；
+ * 2. 依据官方 Identifier.descending 规约生成/刷新合规 Session ID；
+ * 3. 自动注入伪装请求头 (User-Agent 与 x-opencode-session)；
+ * 4. 同步更新 ~/.pi/agent/models.json 与 ~/.pi/agent/auth.json；
+ * 5. 若已安装 CC-Switch，自动无缝同步更新 ~/.cc-switch/cc-switch.db。
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import {
+	KNOWN_ZEN_FREE_MODELS,
+	resolveModelDefinitions,
+	ZEN_BASE_URL,
+	ZEN_PROVIDER_ID,
+	ZEN_USER_AGENT,
+} from "./models-registry.js";
+import {
+	DEFAULT_SESSION_MAX_AGE_MS,
+	extractZenSessionTimestamp,
+	generateZenSessionId,
+	isZenSessionExpired,
+	isValidZenSessionId,
+} from "./session.js";
+import type { ZenStatusInfo, ZenSyncOptions, ZenSyncResult } from "./types.js";
+
+export function defaultModelsPath(): string {
+	return join(homedir(), ".pi", "agent", "models.json");
+}
+
+export function defaultAuthPath(): string {
+	return join(homedir(), ".pi", "agent", "auth.json");
+}
+
+export function defaultCcSwitchDbPath(): string {
+	return join(homedir(), ".cc-switch", "cc-switch.db");
+}
+
+/**
+ * 校验 API Key 并拉取 OpenCode Zen 在线模型清单
+ */
+export async function fetchZenFreeModels(apiKey: string): Promise<string[]> {
+	const res = await fetch(`${ZEN_BASE_URL}/models`, {
+		method: "GET",
+		headers: {
+			Authorization: `Bearer ${apiKey.trim()}`,
+			"User-Agent": ZEN_USER_AGENT,
+		},
+	});
+
+	if (!res.ok) {
+		const text = await res.text().catch(() => "");
+		throw new Error(`OpenCode Zen API 验证失败 (HTTP ${res.status}): ${text || res.statusText}`);
+	}
+
+	const data = (await res.json()) as { data?: Array<{ id: string }> };
+	if (!data || !Array.isArray(data.data)) {
+		return Object.keys(KNOWN_ZEN_FREE_MODELS);
+	}
+
+	const freeIds = data.data
+		.map((item) => item.id)
+		.filter((id) => id.includes("free") || id === "big-pickle" || id.includes("pickle"));
+
+	return freeIds.length > 0 ? freeIds : Object.keys(KNOWN_ZEN_FREE_MODELS);
+}
+
+/**
+ * 读取当前系统中已配置的 OpenCode Zen API Key
+ */
+export function getStoredZenApiKey(authPath = defaultAuthPath(), modelsPath = defaultModelsPath()): string | null {
+	try {
+		if (existsSync(authPath)) {
+			const auth = JSON.parse(readFileSync(authPath, "utf8")) as Record<string, { key?: string }>;
+			if (auth[ZEN_PROVIDER_ID]?.key) {
+				return auth[ZEN_PROVIDER_ID].key;
+			}
+		}
+	} catch {
+		// 忽略读取错误
+	}
+
+	try {
+		if (existsSync(modelsPath)) {
+			const models = JSON.parse(readFileSync(modelsPath, "utf8")) as {
+				providers?: Record<string, { apiKey?: string }>;
+			};
+			if (models.providers?.[ZEN_PROVIDER_ID]?.apiKey) {
+				return models.providers[ZEN_PROVIDER_ID].apiKey;
+			}
+		}
+	} catch {
+		// 忽略读取错误
+	}
+
+	return null;
+}
+
+/**
+ * 读取当前已配置的 Session ID
+ */
+export function getStoredZenSessionId(modelsPath = defaultModelsPath()): string | null {
+	try {
+		if (existsSync(modelsPath)) {
+			const models = JSON.parse(readFileSync(modelsPath, "utf8")) as {
+				providers?: Record<string, { headers?: { "x-opencode-session"?: string } }>;
+			};
+			const ses = models.providers?.[ZEN_PROVIDER_ID]?.headers?.["x-opencode-session"];
+			if (isValidZenSessionId(ses)) return ses;
+		}
+	} catch {
+		// 忽略错误
+	}
+	return null;
+}
+
+/**
+ * 获取 OpenCode Zen 的运行状态摘要
+ */
+export function getZenStatusInfo(
+	modelsPath = defaultModelsPath(),
+	authPath = defaultAuthPath(),
+): ZenStatusInfo {
+	const key = getStoredZenApiKey(authPath, modelsPath);
+	const sessionId = getStoredZenSessionId(modelsPath) ?? "";
+	const ts = sessionId ? extractZenSessionTimestamp(sessionId) : null;
+	const now = Date.now();
+	const ageMinutes = ts ? Math.max(0, Math.round((now - ts) / 60000)) : 999999;
+	const expired = isZenSessionExpired(sessionId, DEFAULT_SESSION_MAX_AGE_MS, now);
+
+	let modelIds: string[] = [];
+	try {
+		if (existsSync(modelsPath)) {
+			const models = JSON.parse(readFileSync(modelsPath, "utf8")) as {
+				providers?: Record<string, { models?: Array<{ id: string }> }>;
+			};
+			const list = models.providers?.[ZEN_PROVIDER_ID]?.models;
+			if (Array.isArray(list)) {
+				modelIds = list.map((m) => m.id);
+			}
+		}
+	} catch {
+		// ignore
+	}
+
+	let maskedKey = "未配置";
+	if (key) {
+		maskedKey = key.length > 12 ? `${key.slice(0, 8)}...${key.slice(-4)}` : "******";
+	}
+
+	return {
+		hasKey: Boolean(key),
+		maskedKey,
+		sessionId,
+		sessionAgeMinutes: ageMinutes,
+		sessionExpired: expired,
+		modelsCount: modelIds.length,
+		modelIds,
+	};
+}
+
+/**
+ * 执行 OpenCode Zen 全量同步（Key 校验、模型拉取、Session 生成、文件落盘、CC-Switch 数据库同步）
+ */
+export async function syncZenConfiguration(options: ZenSyncOptions = {}): Promise<ZenSyncResult> {
+	const modelsPath = options.modelsPath ?? defaultModelsPath();
+	const authPath = options.authPath ?? defaultAuthPath();
+	const dbPath = options.dbPath ?? defaultCcSwitchDbPath();
+
+	const resolvedApiKey = options.apiKey?.trim() || getStoredZenApiKey(authPath, modelsPath);
+	if (!resolvedApiKey) {
+		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;
+		}
+	}
+
+	const resolvedModels = resolveModelDefinitions(freeModelIds);
+
+	// 2. 确定 Session ID：若显式强制更新或当前已过期，则生成全新合规 Session
+	const currentSession = getStoredZenSessionId(modelsPath);
+	let targetSession = currentSession;
+	let isNewSession = false;
+
+	if (options.forceSession || !currentSession || isZenSessionExpired(currentSession, DEFAULT_SESSION_MAX_AGE_MS)) {
+		targetSession = generateZenSessionId();
+		isNewSession = true;
+	}
+
+	// 3. 更新 ~/.pi/agent/models.json
+	let modelsDoc: { providers?: Record<string, unknown> } = {};
+	try {
+		if (existsSync(modelsPath)) {
+			modelsDoc = JSON.parse(readFileSync(modelsPath, "utf8")) as { providers?: Record<string, unknown> };
+		}
+	} catch {
+		modelsDoc = {};
+	}
+	if (!modelsDoc.providers || typeof modelsDoc.providers !== "object") {
+		modelsDoc.providers = {};
+	}
+
+	modelsDoc.providers[ZEN_PROVIDER_ID] = {
+		baseUrl: ZEN_BASE_URL,
+		api: "openai-completions",
+		apiKey: resolvedApiKey,
+		headers: {
+			"User-Agent": ZEN_USER_AGENT,
+			"x-opencode-client": "cli",
+			"x-opencode-session": targetSession,
+			"x-session-affinity": targetSession,
+			"X-Session-Id": targetSession,
+		},
+		compat: {
+			maxTokensField: "max_tokens",
+			requiresReasoningContentOnAssistantMessages: true,
+			supportsDeveloperRole: false,
+			supportsStore: false,
+		},
+		models: resolvedModels,
+	};
+
+	mkdirSync(dirname(modelsPath), { recursive: true });
+	writeFileSync(modelsPath, `${JSON.stringify(modelsDoc, null, 2)}\n`, "utf8");
+
+	// 4. 更新 ~/.pi/agent/auth.json
+	let authDoc: Record<string, unknown> = {};
+	try {
+		if (existsSync(authPath)) {
+			authDoc = JSON.parse(readFileSync(authPath, "utf8")) as Record<string, unknown>;
+		}
+	} catch {
+		authDoc = {};
+	}
+	authDoc[ZEN_PROVIDER_ID] = {
+		type: "api_key",
+		key: resolvedApiKey,
+	};
+	mkdirSync(dirname(authPath), { recursive: true });
+	writeFileSync(authPath, `${JSON.stringify(authDoc, null, 2)}\n`, "utf8");
+
+	// 5. 同步 CC-Switch 数据库
+	let ccSwitchUpdated = false;
+	try {
+		ccSwitchUpdated = updateCcSwitchDb(dbPath, resolvedApiKey, targetSession, resolvedModels);
+	} catch {
+		ccSwitchUpdated = false;
+	}
+
+	return {
+		apiKey: resolvedApiKey,
+		sessionId: targetSession,
+		isNewSession,
+		modelsCount: resolvedModels.length,
+		models: resolvedModels.map((m) => m.id),
+		modelsPath,
+		ccSwitchUpdated,
+	};
+}
+
+/**
+ * 同步 CC-Switch 数据库中的 opencode-zen-free 配置
+ */
+export function updateCcSwitchDb(
+	dbPath: string,
+	apiKey: string,
+	sessionId: string,
+	models: unknown[],
+): boolean {
+	if (!existsSync(dbPath)) return false;
+
+	// 优先使用 Node 22+ 内置的 node:sqlite
+	try {
+		const db = new DatabaseSync(dbPath);
+		const selectStmt = db.prepare("SELECT app_type, settings_config FROM providers WHERE id = ?");
+		const rows = selectStmt.all(ZEN_PROVIDER_ID) as Array<{ app_type: string; settings_config: string }>;
+
+		if (rows.length > 0) {
+			const updateStmt = db.prepare(
+				"UPDATE providers SET settings_config = ? WHERE id = ? AND app_type = ?",
+			);
+
+			for (const row of rows) {
+				try {
+					const cfg = JSON.parse(row.settings_config) as Record<string, unknown>;
+					if (row.app_type === "pi") {
+						cfg.apiKey = apiKey;
+						const headers = (cfg.headers ?? {}) as Record<string, string>;
+						headers["User-Agent"] = ZEN_USER_AGENT;
+						headers["x-opencode-client"] = "cli";
+						headers["x-opencode-session"] = sessionId;
+						headers["x-session-affinity"] = sessionId;
+						headers["X-Session-Id"] = sessionId;
+						cfg.headers = headers;
+						cfg.models = models;
+					} else if (row.app_type === "opencode") {
+						const opts = (cfg.options ?? {}) as Record<string, unknown>;
+						opts.apiKey = apiKey;
+						const headers = (opts.headers ?? {}) as Record<string, string>;
+						headers["User-Agent"] = ZEN_USER_AGENT;
+						headers["x-opencode-client"] = "cli";
+						headers["x-opencode-session"] = sessionId;
+						headers["x-session-affinity"] = sessionId;
+						headers["X-Session-Id"] = sessionId;
+						opts.headers = headers;
+						cfg.options = opts;
+					}
+					updateStmt.run(JSON.stringify(cfg), ZEN_PROVIDER_ID, row.app_type);
+				} catch {
+					// 忽略单行解析失败
+				}
+			}
+			db.close();
+			return true;
+		}
+		db.close();
+	} catch {
+		// 若 node:sqlite 不可用，尝试调用 Python3 脚本无痛回退
+		try {
+			const script = `
+import sqlite3, json, sys
+conn = sqlite3.connect('${dbPath}')
+c = conn.cursor()
+c.execute("SELECT app_type, settings_config FROM providers WHERE id = '${ZEN_PROVIDER_ID}'")
+rows = c.fetchall()
+if rows:
+    for app, cfg_str in rows:
+        try:
+            cfg = json.loads(cfg_str)
+            if app == 'pi':
+                cfg['apiKey'] = '${apiKey}'
+                headers = cfg.get('headers', {})
+                headers['User-Agent'] = '${ZEN_USER_AGENT}'
+                headers['x-opencode-session'] = '${sessionId}'
+                cfg['headers'] = headers
+            elif app == 'opencode':
+                opts = cfg.get('options', {})
+                opts['apiKey'] = '${apiKey}'
+                headers = opts.get('headers', {})
+                headers['User-Agent'] = '${ZEN_USER_AGENT}'
+                headers['x-opencode-session'] = '${sessionId}'
+                opts['headers'] = headers
+                cfg['options'] = opts
+            c.execute("UPDATE providers SET settings_config = ? WHERE id = ? AND app_type = ?", (json.dumps(cfg), '${ZEN_PROVIDER_ID}', app))
+        except Exception:
+            pass
+    conn.commit()
+conn.close()
+`;
+			execFileSync("python3", ["-c", script], { timeout: 3000 });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	return false;
+}

package/src/types.ts

@@ -0,0 +1,67 @@
+/**
+ * OpenCode Zen 类型定义
+ */
+
+export interface ZenModelDefinition {
+	id: string;
+	name: string;
+	contextWindow: number;
+	maxTokens: number;
+	reasoning: boolean;
+	input: ("text" | "image")[];
+	thinkingLevelMap?: Partial<Record<"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", string | null>>;
+	cost: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+	};
+}
+
+export interface ZenProviderConfig {
+	baseUrl: string;
+	api: string;
+	apiKey: string;
+	headers: {
+		"User-Agent": string;
+		"x-opencode-session": string;
+		[key: string]: string;
+	};
+	compat: {
+		maxTokensField: string;
+		requiresReasoningContentOnAssistantMessages: boolean;
+		supportsDeveloperRole: boolean;
+		supportsStore: boolean;
+		[key: string]: unknown;
+	};
+	models: ZenModelDefinition[];
+}
+
+export interface ZenSyncOptions {
+	apiKey?: string;
+	forceSession?: boolean;
+	modelsPath?: string;
+	authPath?: string;
+	dbPath?: string;
+	fetchModels?: (apiKey: string) => Promise<string[]>;
+}
+
+export interface ZenSyncResult {
+	apiKey: string;
+	sessionId: string;
+	isNewSession: boolean;
+	modelsCount: number;
+	models: string[];
+	modelsPath: string;
+	ccSwitchUpdated: boolean;
+}
+
+export interface ZenStatusInfo {
+	hasKey: boolean;
+	maskedKey: string;
+	sessionId: string;
+	sessionAgeMinutes: number;
+	sessionExpired: boolean;
+	modelsCount: number;
+	modelIds: string[];
+}