ck-pi-zen-session 0.1.1 → 0.1.3

package/README.md

@@ -8,15 +8,21 @@ OpenCode Zen 免费模型同步、请求头伪装与 Session 会话自动维护
 
 - ⚡ **/zen 指令一键激活**：输入一次 API Key (`/zen oc_sk_...`)，全自动验证、探测 9 款可用免费模型并注入 Pi 与 CC-Switch。
 - 🔄 **官方算法深度逆向**：完整对齐 OpenCode 客户端 `Identifier.descending("ses")` 与 `Identifier.ascending("msg")` 算法，生成 30 位降序会话 ID 与升序请求 ID，支持毫秒级时间戳反解。
-- 🛡️ **全套官方级伪装请求头**：自动注入全部 6 个官方客户端对齐请求头：
+- 🛡️ **全套官方级伪装请求头**：自动注入全部 7 个官方客户端对齐请求头：
   - `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-opencode-request`: `msg_<12位升序时间戳十六进制><14位Base62>`（每次 HTTP 请求唯一）
+  - `x-opencode-project`: `prj_<16位工作区哈希>`（与官方项目哈希行为对齐）
   - `x-session-affinity`: 与 session 严格同步
   - `X-Session-Id`: 与 session 严格同步
-  - `x-opencode-request`: `msg_<12位升序时间戳十六进制><14位Base62>`（每次 HTTP 请求唯一）
 - ⏱️ **30 分钟无感前置平滑轮换**：官方后端限制免费会话时长约为 1 小时（超时直接 403 `FreeTierError`）。本插件在底层请求拦截器（`before_provider_headers`）和 Agent 循环守卫（`before_agent_start`）中设置 30 分钟主动换新阈值，兼顾会话上下文平滑与长期高频调用稳定性，确保永不触碰 1 小时硬限制。
-- 🧰 **Agent 工具链兼容性守卫**：OpenCode Zen 免费端点对工具集有硬性要求（无工具直接拒绝）。插件在 `before_provider_request` 钩子中实时监控请求体，若用户处于无工具或纯文本问答模式，自动补齐兼容性工具定义，彻底根除 403 拦截。
+- 🚑 **网关异常自愈守卫 (`after_provider_response`)**：新增底层响应拦截，一旦检测到远端网关返回 401 或 403 `FreeTierError`，立即当场触发 Session 换新与后台持久化，并提示用户，彻底终结会话失效死锁。
+- 🔑 **多源凭据自适应感知**：支持优先读取 `OPENCODE_API_KEY`、`OPENCODE_ZEN_API_KEY` 环境变量，亦可直接使用 `/zen <key>` 配置，无缝兼容各类容器与终端环境。
+- 🧰 **官方全套 6 大核心工具链守卫与字母序规约**：OpenCode Zen 免费端点对工具集有硬性要求（无工具直接拒绝）。插件在 `before_provider_request` 钩子中实时监控请求体：
+  - 若用户处于纯文本或无工具模式，自动补齐官方完整的 6 大核心工具（`bash`, `edit`, `glob`, `grep`, `read`, `write`）与 `tool_choice: "auto"`，彻底根除 403 拦截；
+  - 若请求已有工具，严格按照官方客户端规约（`localeCompare`）按函数名升序重排；
+  - 自动对齐流式用量元数据 `stream_options: { include_usage: true }`。
 - 🌐 **独立供应商隔离命名空间**：注册为独立供应商 `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 数据库。
@@ -46,7 +52,7 @@ pi install git:github.com/1837620622/ck-pi-extension
 | 指令 | 说明 |
 | --- | --- |
 | `/zen <oc_sk_xxx>` | 设置/更新 API Key，自动在线验证并全量同步模型与全套请求头 |
-| `/zen` | 智能检查当前会话状态；若会话临近过期自动换新；若未配置 Key 则弹出交互输入框 |
+| `/zen` | 立即一键强制换新 Session 并全面刷新所有请求头；若未配置 Key 则弹出交互输入框 |
 | `/zen refresh` | 强制生成全新的合法降序 Session ID 并更新所有请求头与落盘配置 |
 | `/zen status` | 查看当前 API Key 掩码、活跃会话精确存活时间及模型就绪状态 |
 | `/zen list`（或 `/zen models`） | 查看当前已激活的所有免费模型列表 |

package/package.json

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

package/src/index.ts

@@ -12,6 +12,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import {
 	KNOWN_ZEN_FREE_MODELS,
+	OPENCODE_OFFICIAL_TOOLS,
 	ZEN_BASE_URL,
 	ZEN_PROVIDER_ID,
 	ZEN_USER_AGENT,
@@ -24,6 +25,7 @@ import {
 } from "./sync.js";
 import {
 	DEFAULT_SESSION_MAX_AGE_MS,
+	generateZenProjectId,
 	generateZenRequestId,
 	generateZenSessionId,
 	isZenSessionExpired,
@@ -45,6 +47,7 @@ export function registerZenProviderToPi(
 				"User-Agent": ZEN_USER_AGENT,
 				"x-opencode-client": "cli",
 				"x-opencode-session": sessionId,
+				"x-opencode-project": generateZenProjectId(),
 				"x-session-affinity": sessionId,
 				"X-Session-Id": sessionId,
 			},
@@ -53,6 +56,7 @@ export function registerZenProviderToPi(
 				requiresReasoningContentOnAssistantMessages: true,
 				supportsDeveloperRole: false,
 				supportsStore: false,
+				supportsUsageInStreaming: true,
 			},
 			models: Object.values(KNOWN_ZEN_FREE_MODELS),
 		});
@@ -69,7 +73,7 @@ export default function piZenSession(pi: ExtensionAPI): void {
 		registerZenProviderToPi(pi, existingKey);
 	}
 
-	// 2. 核心请求头拦截钩子：在每一次请求发往 Provider 前注入完整伪装请求头
+	// 2. 核心请求头拦截钩子：在每一次请求发往 Provider 前注入完整官方客户端对齐请求头
 	pi.on("before_provider_headers", (event, ctx) => {
 		const model = ctx.model;
 		const isZenModel =
@@ -91,17 +95,18 @@ export default function piZenSession(pi: ExtensionAPI): void {
 				syncZenConfiguration({ forceSession: true }).catch(() => {});
 			}
 
-			// 注入全部官方客户端对齐请求头
+			// 注入全部官方客户端 7 维对齐请求头
 			event.headers["User-Agent"] = ZEN_USER_AGENT;
 			event.headers["x-opencode-client"] = "cli";
 			event.headers["x-opencode-session"] = currentSession;
+			event.headers["x-opencode-project"] = generateZenProjectId();
 			event.headers["x-session-affinity"] = currentSession;
 			event.headers["X-Session-Id"] = currentSession;
 			event.headers["x-opencode-request"] = generateZenRequestId();
 		}
 	});
 
-	// 3. 核心请求体守卫钩子：OpenCode Zen 免费端点对工具集有硬性要求，若缺失工具会报 403 FreeTierError
+	// 3. 核心请求体守卫钩子：深度对齐 OpenCode 官方请求体结构与工具集
 	pi.on("before_provider_request", (event, ctx) => {
 		const model = ctx.model;
 		const isZenModel =
@@ -112,46 +117,56 @@ export default function piZenSession(pi: ExtensionAPI): void {
 		if (isZenModel && event.payload && typeof event.payload === "object") {
 			const payload = event.payload as Record<string, unknown>;
 			const tools = payload.tools;
-			// 若当前请求没有附带任何工具定义（如纯文本问答模式），自动补齐兼容性工具定义以规避 403 拦截
+			let modified = false;
+			const transformed = { ...payload };
+
+			// A. 工具规范对齐：无工具时补齐官方 6 大核心工具；已有工具时按字母升序严格重排 (localeCompare)
 			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"],
-								},
-							},
-						},
-					],
-				};
+				transformed.tools = OPENCODE_OFFICIAL_TOOLS;
+				transformed.tool_choice = "auto";
+				modified = true;
+			} else {
+				transformed.tools = [...tools].sort((a: any, b: any) => {
+					const nameA = a.function?.name || a.name || "";
+					const nameB = b.function?.name || b.name || "";
+					return nameA.localeCompare(nameB);
+				});
+				modified = true;
+			}
+
+			// B. 流式元数据对齐：补充 stream_options: { include_usage: true }
+			if (transformed.stream === true && !transformed.stream_options) {
+				transformed.stream_options = { include_usage: true };
+				modified = true;
+			}
+
+			if (modified) {
+				return transformed;
+			}
+		}
+	});
+
+	// 4. 网关响应守卫：遇 401/403 会话受限或过期时，立即自愈换新 Session ID
+	pi.on("after_provider_response", (event, ctx) => {
+		const model = ctx.model;
+		const isZenModel =
+			model?.provider === ZEN_PROVIDER_ID ||
+			model?.id?.includes("-free") ||
+			model?.id === "big-pickle";
+
+		if (isZenModel && (event.status === 401 || event.status === 403)) {
+			// 自动异步刷新 Session
+			syncZenConfiguration({ forceSession: true }).catch(() => {});
+			if (ctx.hasUI) {
+				ctx.ui.notify(
+					`检测到 OpenCode Zen 会话受限 (HTTP ${event.status})，已自动轮换新 Session ID。`,
+					"warning",
+				);
 			}
 		}
 	});
 
-	// 4. 常驻生命周期守卫：在每次 Agent 循环执行前，自动检测 Session 有效性并无感续期
+	// 5. 常驻生命周期守卫：在每次 Agent 循环执行前，自动检测 Session 有效性并无感续期
 	pi.on("before_agent_start", async () => {
 		try {
 			const currentSession = getStoredZenSessionId();
@@ -167,7 +182,7 @@ export default function piZenSession(pi: ExtensionAPI): void {
 		}
 	});
 
-	// 4. 注册 /zen 指令
+	// 6. 注册 /zen 指令
 	pi.registerCommand("zen", {
 		description: "OpenCode Zen 免费模型与 Session 会话自动维护 (/zen [key|refresh|status|list])",
 		getArgumentCompletions: (prefix: string) => {
@@ -284,23 +299,24 @@ export async function handleZenCommand(
 	// 5. 无参调用: /zen
 	const status = getZenStatusInfo();
 	if (status.hasKey) {
-		// 已有 Key 时，自动检测并刷新 Session
+		// 已有 Key 时，自动强制刷新 Session 并重新注册热载
 		try {
-			notify(ctx, "正在检测并刷新 OpenCode Zen 会话...", "info");
-			const result = await syncZenConfiguration({ forceSession: status.sessionExpired });
+			notify(ctx, "正在刷新 OpenCode Zen 会话与请求头...", "info");
+			const result = await syncZenConfiguration({ forceSession: true });
 			if (pi) {
 				registerZenProviderToPi(pi, result.apiKey, result.sessionId);
 			}
 			const msg = [
-				"✨ [OpenCode Zen 已连接就绪]",
+				"✨ [OpenCode Zen 已自动刷新并就绪]",
 				`• API Key: ${maskKey(result.apiKey)}`,
-				`• 活跃 Session: ${result.sessionId} (${result.isNewSession ? "已换新" : "仍有效"})`,
-				`• 免费模型: ${result.modelsCount} 个可用`,
+				`• 全新 Session: ${result.sessionId} (有效且已持久化)`,
+				`• 免费模型: 已同步 ${result.modelsCount} 个可用免费模型`,
+				`• 请求头保护: 30分钟自动轮换 + 7维官方签名 + 6大核心工具全注入`,
 				"",
 				"常用操作：",
 				"  /zen <key>   - 更换 API Key",
-				"  /zen refresh - 换新会话 ID",
 				"  /zen status  - 详情状态",
+				"  /zen list    - 查看所有可用免费模型",
 			].join("\n");
 			notify(ctx, msg, "info");
 		} catch (error) {
@@ -317,7 +333,7 @@ export async function handleZenCommand(
 				"oc_sk_",
 			);
 			if (enteredKey && enteredKey.trim()) {
-				await handleZenCommand(enteredKey.trim(), ctx);
+				await handleZenCommand(enteredKey.trim(), ctx, pi);
 				return;
 			}
 			notify(ctx, "已取消输入。如需配置请使用 /zen <oc_sk_xxx>", "info");

package/src/models-registry.ts

@@ -168,3 +168,143 @@ export function resolveModelDefinitions(discoveredIds: string[]): ZenModelDefini
 
 	return list;
 }
+
+/**
+ * OpenCode 官方 6 大核心内置工具规范与 Schema 定义
+ * 严格对齐 OpenCode 客户端源码（按字母顺序排序：bash, edit, glob, grep, read, write）
+ */
+export const OPENCODE_OFFICIAL_TOOLS = [
+	{
+		type: "function",
+		function: {
+			name: "bash",
+			description: "Execute bash commands in the workspace environment",
+			parameters: {
+				type: "object",
+				properties: {
+					command: { type: "string", description: "Shell command string to execute" },
+					workdir: {
+						type: "string",
+						description:
+							"Working directory. Defaults to the active Location; relative paths resolve within it.",
+					},
+				},
+				required: ["command"],
+			},
+		},
+	},
+	{
+		type: "function",
+		function: {
+			name: "edit",
+			description: "Edit a file by replacing text",
+			parameters: {
+				type: "object",
+				properties: {
+					path: {
+						type: "string",
+						description:
+							"File path to edit. Relative paths resolve within the active Location.",
+					},
+					oldString: { type: "string", description: "The string in the file to be replaced" },
+					newString: { type: "string", description: "The string to replace oldString with" },
+					replaceAll: {
+						type: "boolean",
+						description: "Replace all occurrences of oldString (default false)",
+					},
+				},
+				required: ["path", "oldString", "newString"],
+			},
+		},
+	},
+	{
+		type: "function",
+		function: {
+			name: "glob",
+			description: "Find files matching a glob pattern",
+			parameters: {
+				type: "object",
+				properties: {
+					pattern: {
+						type: "string",
+						description: 'File pattern to include in the search (e.g. "*.js", "*.{ts,tsx}")',
+					},
+					path: {
+						type: "string",
+						description: "Relative directory to search in. Defaults to the active Location.",
+					},
+				},
+				required: ["pattern"],
+			},
+		},
+	},
+	{
+		type: "function",
+		function: {
+			name: "grep",
+			description: "Search file contents using regular expressions",
+			parameters: {
+				type: "object",
+				properties: {
+					pattern: {
+						type: "string",
+						description: "Regex pattern to search for in file contents",
+					},
+					path: {
+						type: "string",
+						description: "Relative directory to search in. Defaults to the active Location.",
+					},
+				},
+				required: ["pattern"],
+			},
+		},
+	},
+	{
+		type: "function",
+		function: {
+			name: "read",
+			description: "Read file contents",
+			parameters: {
+				type: "object",
+				properties: {
+					path: {
+						type: "string",
+						description:
+							"File path to read. Relative paths resolve within the active Location.",
+					},
+					offset: {
+						type: "number",
+						description: "The 1-based directory entry or text line offset",
+					},
+					limit: {
+						type: "number",
+						description: "The maximum number of lines to read (defaults to 2000)",
+					},
+				},
+				required: ["path"],
+			},
+		},
+	},
+	{
+		type: "function",
+		function: {
+			name: "write",
+			description: "Write or overwrite file contents",
+			parameters: {
+				type: "object",
+				properties: {
+					path: {
+						type: "string",
+						description:
+							"File path to write. Relative paths resolve within the active Location.",
+					},
+					content: {
+						type: "string",
+						description: "Content to write to the file",
+					},
+				},
+				required: ["path", "content"],
+			},
+		},
+	},
+];

package/src/session.ts

@@ -10,13 +10,22 @@
  * 3. 降序特性（descending）：时间越晚，按字典序排序越靠前。
  */
 
-import { webcrypto } from "node:crypto";
+import { createHash, webcrypto } from "node:crypto";
 
 const B62_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
 
 let lastTimestamp = 0;
 let sequenceCounter = 0;
 
+/**
+ * 生成符合 OpenCode 官方规约的项目标识符 (前缀 prj_)
+ * 基于工作目录哈希，保持确定性与隔离性
+ */
+export function generateZenProjectId(cwd: string = process.cwd()): string {
+	const hash = createHash("sha256").update(cwd).digest("hex").slice(0, 16);
+	return `prj_${hash}`;
+}
+
 /**
  * 生成符合 OpenCode 官方规约的 Session ID (前缀 ses_)
  * @param timestampMs 毫秒时间戳，默认为 Date.now()

package/src/sync.ts

@@ -24,6 +24,7 @@ import {
 import {
 	DEFAULT_SESSION_MAX_AGE_MS,
 	extractZenSessionTimestamp,
+	generateZenProjectId,
 	generateZenSessionId,
 	isZenSessionExpired,
 	isValidZenSessionId,
@@ -75,6 +76,15 @@ export async function fetchZenFreeModels(apiKey: string): Promise<string[]> {
  * 读取当前系统中已配置的 OpenCode Zen API Key
  */
 export function getStoredZenApiKey(authPath = defaultAuthPath(), modelsPath = defaultModelsPath()): string | null {
+	// 优先读取环境变量，支持免配置直接启动
+	const envKey =
+		process.env.OPENCODE_API_KEY ||
+		process.env.OPENCODE_ZEN_API_KEY ||
+		process.env.ZEN_API_KEY;
+	if (envKey && envKey.trim()) {
+		return envKey.trim();
+	}
+
 	try {
 		if (existsSync(authPath)) {
 			const auth = JSON.parse(readFileSync(authPath, "utf8")) as Record<string, { key?: string }>;
@@ -225,6 +235,7 @@ export async function syncZenConfiguration(options: ZenSyncOptions = {}): Promis
 			"User-Agent": ZEN_USER_AGENT,
 			"x-opencode-client": "cli",
 			"x-opencode-session": targetSession,
+			"x-opencode-project": generateZenProjectId(),
 			"x-session-affinity": targetSession,
 			"X-Session-Id": targetSession,
 		},
@@ -233,6 +244,7 @@ export async function syncZenConfiguration(options: ZenSyncOptions = {}): Promis
 			requiresReasoningContentOnAssistantMessages: true,
 			supportsDeveloperRole: false,
 			supportsStore: false,
+			supportsUsageInStreaming: true,
 		},
 		models: resolvedModels,
 	};
@@ -306,6 +318,7 @@ export function updateCcSwitchDb(
 						headers["User-Agent"] = ZEN_USER_AGENT;
 						headers["x-opencode-client"] = "cli";
 						headers["x-opencode-session"] = sessionId;
+						headers["x-opencode-project"] = generateZenProjectId();
 						headers["x-session-affinity"] = sessionId;
 						headers["X-Session-Id"] = sessionId;
 						cfg.headers = headers;
@@ -317,6 +330,7 @@ export function updateCcSwitchDb(
 						headers["User-Agent"] = ZEN_USER_AGENT;
 						headers["x-opencode-client"] = "cli";
 						headers["x-opencode-session"] = sessionId;
+						headers["x-opencode-project"] = generateZenProjectId();
 						headers["x-session-affinity"] = sessionId;
 						headers["X-Session-Id"] = sessionId;
 						opts.headers = headers;