@zhushanwen/pi-llm-shared 0.2.0 → 0.3.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/pi-llm-shared",
-  "version": "0.2.0",
-  "description": "Shared LLM invocation library for Pi extensions — model resolution (ref/fallback/available/scoped), LLM calling (completeSimple), and config read/write with mtime caching. Shared library, not a Pi extension.",
+  "version": "0.3.1",
+  "description": "Shared LLM invocation library for Pi extensions — model resolution (ref exact only), LLM calling (completeSimple), and config read/write with mtime caching. Shared library, not a Pi extension.",
   "type": "module",
   "main": "src/index.ts",
   "keywords": [
@@ -17,6 +17,9 @@
     "src/",
     "index.ts"
   ],
+  "dependencies": {
+    "@zhushanwen/pi-file-lock": "0.1.1"
+  },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*"
@@ -32,6 +35,7 @@
   "devDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
+    "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8"
   },
   "scripts": {

package/src/__tests__/call.test.ts

@@ -135,6 +135,47 @@ describe("callLLM", () => {
 		expect("sessionId" in optionsArg).toBe(false);
 	});
 
+	it("reasoning 透传：传 reasoning=high → options 含 reasoning:high", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		mockComplete.mockResolvedValue({ content: [{ type: "text", text: "x" }] });
+
+		await callLLM(ctx, {
+			model: makeModel(),
+			systemPrompt: "s",
+			messages: [],
+			reasoning: "high",
+		});
+
+		const optionsArg = mockComplete.mock.calls[0][2];
+		expect(optionsArg).toMatchObject({ reasoning: "high" });
+	});
+
+	it("reasoning 不传 → options 不含 reasoning 字段（条件 spread，provider 默认）", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		mockComplete.mockResolvedValue({ content: [{ type: "text", text: "x" }] });
+
+		await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
+
+		const optionsArg = mockComplete.mock.calls[0][2] as Record<string, unknown>;
+		expect("reasoning" in optionsArg).toBe(false);
+	});
+
+	it("reasoning=off → options 不含 reasoning 字段（off 由本库映射为不传）", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		mockComplete.mockResolvedValue({ content: [{ type: "text", text: "x" }] });
+
+		await callLLM(ctx, {
+			model: makeModel(),
+			systemPrompt: "s",
+			messages: [],
+			reasoning: "off",
+		});
+
+		const optionsArg = mockComplete.mock.calls[0][2] as Record<string, unknown>;
+		expect("reasoning" in optionsArg).toBe(false);
+	});
+
+
 	it("B5: getApiKeyAndHeaders reject（抛异常）→ {ok:false, recoverable:true}（归一入 catch，不向上抛）", async () => {
 		const getApiKeyAndHeaders = vi.fn().mockRejectedValueOnce(new Error("registry exploded"));
 		const ctx = { modelRegistry: { getApiKeyAndHeaders } } as unknown as ExtensionContext;

package/src/__tests__/config.test.ts

@@ -1,10 +1,11 @@
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
 import * as fs from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { clearConfigCache, getConfigPath, loadConfig, saveConfig } from "../config.ts";
+import * as fileLock from "@zhushanwen/pi-file-lock";
 
 // node:fs 的 ESM namespace 不可配置，vi.spyOn 对具名导出失效（vitest 限制）。
 // 用 vi.mock 包装 readFileSync/renameSync（默认走 actual，个别 test override），
@@ -128,6 +129,12 @@ describe("loadConfig", () => {
 });
 
 describe("saveConfig", () => {
+	/** tmp 残留断言（D1e 唯一化后 tmp 名为 <path>.tmp_<pid>_<rand>，用前缀 glob 断言）。 */
+	function tmpResidues(pkg: string): string[] {
+		const cfgDir = join(dir, "config");
+		return readdirSync(cfgDir).filter((f) => f.startsWith(`${pkg}-ext-config.json.tmp`));
+	}
+
 	it("TC16 原子写：文件落盘 + 内容正确 + 无 tmp 残留", () => {
 		const result = saveConfig("test", { b: 2 });
 		expect(result.success).toBe(true);
@@ -135,7 +142,7 @@ describe("saveConfig", () => {
 		const cfgPath = join(dir, "config", "test-ext-config.json");
 		expect(existsSync(cfgPath)).toBe(true);
 		expect(JSON.parse(readFileSync(cfgPath, "utf-8"))).toEqual({ b: 2 });
-		expect(existsSync(`${cfgPath}.tmp`)).toBe(false); // 无 tmp 残留
+		expect(tmpResidues("test")).toEqual([]); // 无 tmp 残留（唯一化 tmp 名，前缀断言）
 	});
 
 	it("TC16 文件 mode 0o600", () => {
@@ -164,8 +171,8 @@ describe("saveConfig", () => {
 
 		expect(result.success).toBe(false);
 		expect(result.error).toContain("EPERM");
-		// tmp 文件被 catch 块的 unlinkSync 清理
-		expect(existsSync(join(dir, "config", "fail-ext-config.json.tmp"))).toBe(false);
+		// tmp 文件被 catch 块的 unlinkSync 清理（唯一化 tmp 名，前缀断言）
+		expect(tmpResidues("fail")).toEqual([]);
 		// 目标文件未被创建（rename 失败）
 		expect(existsSync(join(dir, "config", "fail-ext-config.json"))).toBe(false);
 	});
@@ -185,9 +192,10 @@ describe("saveConfig", () => {
 		expect(onWarning).toHaveBeenCalledTimes(1);
 		const warning = String(onWarning.mock.calls[0][0]);
 		expect(warning).toContain("[llm-shared] Failed to save config at '" + join(dir, "config", "enoent-ext-config.json") + "'");
+		expect(warning).toContain("[llm-shared] Failed to save config at '" + join(dir, "config", "enoent-ext-config.json") + "'");
 		expect(warning).toContain("ENOENT");
-		// tmp 清理 + 目标未创建
-		expect(existsSync(join(dir, "config", "enoent-ext-config.json.tmp"))).toBe(false);
+		// tmp 清理（前缀断言）+ 目标未创建
+		expect(tmpResidues("enoent")).toEqual([]);
 		expect(existsSync(join(dir, "config", "enoent-ext-config.json"))).toBe(false);
 	});
 
@@ -204,8 +212,8 @@ describe("saveConfig", () => {
 		const warning = String(onWarning.mock.calls[0][0]);
 		expect(warning).toContain("[llm-shared] Failed to save config at '" + join(dir, "config", "eperm-ext-config.json") + "'");
 		expect(warning).toContain("EPERM");
-		// tmp 清理（Windows 目标占用场景 rename 失败后 tmp 残留被清理）
-		expect(existsSync(join(dir, "config", "eperm-ext-config.json.tmp"))).toBe(false);
+		// tmp 清理（Windows 目标占用场景 rename 失败后 tmp 残留被清理；前缀断言）
+		expect(tmpResidues("eperm")).toEqual([]);
 		expect(existsSync(join(dir, "config", "eperm-ext-config.json"))).toBe(false);
 	});
 
@@ -214,4 +222,26 @@ describe("saveConfig", () => {
 		expect(saveConfig("test", { v: 2 }).success).toBe(true);
 		expect(JSON.parse(readFileSync(join(dir, "config", "test-ext-config.json"), "utf-8"))).toEqual({ v: 2 });
 	});
+
+	it("W4 锁不可用（ELOCKED 预算耗尽）→ {success:false} + 不降级无锁写（目标文件不落盘）", () => {
+		// 模拟 runtime 对端长期持锁：withFileLockSync 抛 ELOCKED。扩展侧契约 =
+		// 不降级无锁写（降级会与 runtime 持锁写交错丢字段），按保存失败返回。
+		const lockErr = Object.assign(new Error("[file-lock] lock unavailable: ELOCKED"), { code: "ELOCKED" });
+		const spy = vi.spyOn(fileLock, "withFileLockSync").mockImplementation(() => {
+			throw lockErr;
+		});
+		const onWarning = vi.fn();
+
+		try {
+			const result = saveConfig("lockbusy", { x: 1 }, onWarning);
+
+			expect(result.success).toBe(false);
+			expect(result.error).toContain("lock unavailable");
+			expect(onWarning).toHaveBeenCalledTimes(1);
+			// 关键：未降级写盘（无锁写会破坏与 runtime 的互斥）
+			expect(existsSync(join(dir, "config", "lockbusy-ext-config.json"))).toBe(false);
+		} finally {
+			spy.mockRestore();
+		}
+	});
 });

package/src/__tests__/resolve.test.ts

@@ -12,112 +12,53 @@ function makeModel(provider: string, id: string): Model<Api> {
 /** 构造 mock ExtensionContext（只填 modelRegistry 的 resolveModel 依赖的方法）。 */
 function makeCtx(registry: {
 	find?: (provider: string, modelId: string) => Model<Api> | undefined;
-	getAll?: () => Model<Api>[];
-	getAvailable?: () => Model<Api>[];
 	hasConfiguredAuth?: (model: Model<Api>) => boolean;
 }): ExtensionContext {
 	return {
 		modelRegistry: {
 			find: vi.fn(registry.find ?? (() => undefined)),
-			getAll: vi.fn(registry.getAll ?? (() => [])),
-			getAvailable: vi.fn(registry.getAvailable ?? (() => [])),
 			hasConfiguredAuth: vi.fn(registry.hasConfiguredAuth ?? (() => false)),
 			getApiKeyAndHeaders: vi.fn(),
 		},
 	} as unknown as ExtensionContext;
 }
 
-describe("resolveModel", () => {
-	describe("ref 精确匹配", () => {
-		it("TC3 find 命中 + hasConfiguredAuth → 返回 model", () => {
-			const m = makeModel("deepseek-router", "deepseek-chat");
-			const ctx = makeCtx({ find: () => m, hasConfiguredAuth: () => true });
-			expect(resolveModel(ctx, { type: "ref", ref: "deepseek-router/deepseek-chat" })).toBe(m);
-		});
-
-		it("TC4 find 命中但 hasConfiguredAuth=false → null", () => {
-			const m = makeModel("a", "1");
-			const ctx = makeCtx({ find: () => m, hasConfiguredAuth: () => false });
-			expect(resolveModel(ctx, { type: "ref", ref: "a/1" })).toBeNull();
-		});
-
-		it("TC4 find 未命中（undefined）→ null（静默降级不抛错）", () => {
-			const ctx = makeCtx({ find: () => undefined, hasConfiguredAuth: () => true });
-			expect(resolveModel(ctx, { type: "ref", ref: "x/9" })).toBeNull();
-		});
+describe("resolveModel（仅 ref 精确指定）", () => {
+	it("find 命中 + hasConfiguredAuth → 返回 model", () => {
+		const m = makeModel("deepseek-router", "deepseek-chat");
+		const ctx = makeCtx({ find: () => m, hasConfiguredAuth: () => true });
+		expect(resolveModel(ctx, { type: "ref", ref: "deepseek-router/deepseek-chat" })).toBe(m);
 	});
 
-	describe("fallback 按序", () => {
-		it("TC5 遍历 refs，首个可用的返回（提前返回不遍历完）", () => {
-			const m1 = makeModel("a", "1");
-			const m2 = makeModel("b", "2");
-			const m3 = makeModel("c", "3");
-			const find = vi.fn((p: string, id: string) => {
-				if (p === "a" && id === "1") return m1;
-				if (p === "b" && id === "2") return m2;
-				if (p === "c" && id === "3") return m3;
-				return undefined;
-			});
-			const hasAuth = vi.fn((m: Model<Api>) => m === m2); // 只有 m2 有 auth
-			const ctx = makeCtx({ find, hasConfiguredAuth: hasAuth });
-
-			expect(resolveModel(ctx, { type: "fallback", refs: ["a/1", "b/2", "c/3"] })).toBe(m2);
-			expect(find).toHaveBeenCalledWith("a", "1");
-			expect(find).toHaveBeenCalledWith("b", "2");
-			// m1 无 auth 提前跳过，m2 命中后立即返回，不查 c/3
-			expect(find).not.toHaveBeenCalledWith("c", "3");
-		});
-
-		it("TC5 全部无 auth → null", () => {
-			const m1 = makeModel("a", "1");
-			const ctx = makeCtx({ find: () => m1, hasConfiguredAuth: () => false });
-			expect(resolveModel(ctx, { type: "fallback", refs: ["a/1", "b/2"] })).toBeNull();
-		});
+	it("find 命中但 hasConfiguredAuth=false → null", () => {
+		const m = makeModel("a", "1");
+		const ctx = makeCtx({ find: () => m, hasConfiguredAuth: () => false });
+		expect(resolveModel(ctx, { type: "ref", ref: "a/1" })).toBeNull();
 	});
 
-	describe("available", () => {
-		it("TC6 非空数组取首个", () => {
-			const mA = makeModel("a", "1");
-			const mB = makeModel("b", "2");
-			const ctx = makeCtx({ getAvailable: () => [mA, mB] });
-			expect(resolveModel(ctx, { type: "available" })).toBe(mA);
-		});
-
-		it("TC6 空数组 → null", () => {
-			const ctx = makeCtx({ getAvailable: () => [] });
-			expect(resolveModel(ctx, { type: "available" })).toBeNull();
-		});
+	it("find 未命中（undefined）→ null（静默降级不抛错）", () => {
+		const ctx = makeCtx({ find: () => undefined, hasConfiguredAuth: () => true });
+		expect(resolveModel(ctx, { type: "ref", ref: "x/9" })).toBeNull();
 	});
 
-	describe("ref 非法格式（parseRef 防护）", () => {
-		it("C3: ref 无 '/'（如 'abc'）→ null，不调 find", () => {
-			const find = vi.fn((_provider: string, _modelId: string): Model<Api> | undefined => undefined);
-			const ctx = makeCtx({ find, hasConfiguredAuth: () => true });
-			expect(resolveModel(ctx, { type: "ref", ref: "abc" })).toBeNull();
-			expect(find).not.toHaveBeenCalled();
-		});
-
-		it("C3: ref 以 '/' 开头（如 '/model'）→ null，不调 find", () => {
-			const find = vi.fn((_provider: string, _modelId: string): Model<Api> | undefined => undefined);
-			const ctx = makeCtx({ find, hasConfiguredAuth: () => true });
-			expect(resolveModel(ctx, { type: "ref", ref: "/model" })).toBeNull();
-			expect(find).not.toHaveBeenCalled();
-		});
+	it("ref 无 '/'（如 'abc'）→ null，不调 find", () => {
+		const find = vi.fn((_provider: string, _modelId: string): Model<Api> | undefined => undefined);
+		const ctx = makeCtx({ find, hasConfiguredAuth: () => true });
+		expect(resolveModel(ctx, { type: "ref", ref: "abc" })).toBeNull();
+		expect(find).not.toHaveBeenCalled();
+	});
 
-		it("C3: ref 以 '/' 结尾（如 'provider/'）→ null，不调 find", () => {
-			const find = vi.fn((_provider: string, _modelId: string): Model<Api> | undefined => undefined);
-			const ctx = makeCtx({ find, hasConfiguredAuth: () => true });
-			expect(resolveModel(ctx, { type: "ref", ref: "provider/" })).toBeNull();
-			expect(find).not.toHaveBeenCalled();
-		});
+	it("ref 以 '/' 开头（如 '/model'）→ null，不调 find", () => {
+		const find = vi.fn((_provider: string, _modelId: string): Model<Api> | undefined => undefined);
+		const ctx = makeCtx({ find, hasConfiguredAuth: () => true });
+		expect(resolveModel(ctx, { type: "ref", ref: "/model" })).toBeNull();
+		expect(find).not.toHaveBeenCalled();
 	});
 
-	describe("fallback 空数组", () => {
-		it("C3: {type:'fallback', refs:[]} → null，不调 find", () => {
-			const find = vi.fn((_provider: string, _modelId: string): Model<Api> | undefined => undefined);
-			const ctx = makeCtx({ find, hasConfiguredAuth: () => true });
-			expect(resolveModel(ctx, { type: "fallback", refs: [] })).toBeNull();
-			expect(find).not.toHaveBeenCalled();
-		});
+	it("ref 以 '/' 结尾（如 'provider/'）→ null，不调 find", () => {
+		const find = vi.fn((_provider: string, _modelId: string): Model<Api> | undefined => undefined);
+		const ctx = makeCtx({ find, hasConfiguredAuth: () => true });
+		expect(resolveModel(ctx, { type: "ref", ref: "provider/" })).toBeNull();
+		expect(find).not.toHaveBeenCalled();
 	});
 });

package/src/call.ts

@@ -14,8 +14,11 @@
 
 // 顶层静态 import —— 探针①已验证加载阶段不 throw（见模块注释）
 import { completeSimple } from "@earendil-works/pi-ai/compat";
-import type { Context as LlmContext, SimpleStreamOptions } from "@earendil-works/pi-ai/compat";
-import type { Api, Message, Model } from "@earendil-works/pi-ai";
+import type {
+	Context as LlmContext,
+	SimpleStreamOptions,
+} from "@earendil-works/pi-ai/compat";
+import type { Api, Message, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 // ──────────────────────── 类型 ────────────────────────
@@ -33,6 +36,12 @@ export interface CallLLMOptions {
 	timeoutMs?: number;
 	/** 透传给 SimpleStreamOptions.sessionId（provider 用于 session 缓存 / 路由）。review TF1 新增。 */
 	sessionId?: string;
+	/**
+	 * thinking/reasoning 级别，透传给 SimpleStreamOptions.reasoning（pi 的 THINKING_ORDER SSOT：
+	 * minimal/low/medium/high/xhigh/max）。"off" 表示关闭 thinking，由本库映射为「不传 reasoning 字段」
+	 * （provider 默认行为）；不传 = 同样 provider 默认。
+	 */
+	reasoning?: ModelThinkingLevel;
 }
 
 /**
@@ -113,6 +122,7 @@ export async function callLLM(
 			...(opts.maxTokens ? { maxTokens: opts.maxTokens } : {}),
 			...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}),
 			...(opts.sessionId ? { sessionId: opts.sessionId } : {}),
+			...(opts.reasoning && opts.reasoning !== "off" ? { reasoning: opts.reasoning } : {}),
 		};
 		const resp = await completeSimple(opts.model, context, options);
 		// G3/C1a：completeSimple 对 error/aborted 也 resolve（带 stopReason，不 reject）。

package/src/config.ts

@@ -23,6 +23,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync,
 import { dirname, join } from "node:path";
 
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { withFileLockSync } from "@zhushanwen/pi-file-lock";
 
 /** JSON 序列化缩进格数（permission/config.ts 同款）。 */
 const JSON_INDENT = 2;
@@ -114,13 +115,35 @@ export function loadConfig<T>(
 	}
 }
 
-// ──────────────────────── 保存（原子写） ────────────────────────
+// ──────────────────────── 保存（锁内原子写） ────────────────────────
 
 /**
- * 保存配置（原子写：tmp 文件 + rename）。
+ * 生成并发唯一的 tmp 文件名（D1e 附带风险修复：双侧 tmp 中间文件同名 `<path>.tmp`
+ * 并发可碰撞——runtime 侧 atomicWrite 未传 uniqueSuffix 也是固定名，扩展侧唯一化
+ * 后两侧名字空间不相交，碰撞面消除）。
+ *
+ * 后缀 = pid + 36 进制随机段：同进程多写方（多 session）与跨进程写方均不重名。
+ */
+const TMP_RANDOM_BASE = 36;
+const TMP_RANDOM_SLICE_START = 2; // 跳过 Math.random 字符串的 "0." 前缀
+const TMP_RANDOM_SLICE_END = 10;
+function uniqueTmpPath(configPath: string): string {
+	return `${configPath}.tmp_${process.pid}_${Math.random().toString(TMP_RANDOM_BASE).slice(TMP_RANDOM_SLICE_START, TMP_RANDOM_SLICE_END)}`;
+}
+
+/**
+ * 保存配置（锁内原子写：withFileLockSync + tmp 文件 + rename）。
  *
  * @returns 成功 {success:true}；失败 {success:false, error}
  *
+ * 🔒 跨进程锁（D1e/W4，integrity-hardening.md §3.1，登记表 §6 rename-session 行）：
+ * ext-config 家族被 xyz runtime（如 setRenameModel 写 model 字段，W1b 已持锁）与
+ * pi 子进程内扩展（本函数）双写。互斥只依赖同一 lockfile（<config>.lock），本侧
+ * withFileLockSync 协议与 runtime 侧 settings.json 写锁逐字对齐（realpath:false +
+ * stale 30s + busy-wait 1s 预算 fail-fast）。锁获取失败不降级无锁写——对端
+ * runtime 可能正持锁写，无锁写会交错丢字段；返回 {success:false} 由调用方按
+ * 保存失败处理（下次 save 重试）。
+ *
  * 原子性：writeFileSync(tmp) + renameSync(tmp→target)，rename 是原子的（POSIX/Windows）。
  * tmp 失败清理（review RK3）：writeFileSync 或 renameSync 抛错时，catch 块 unlinkSync(tmp)
  * 清理残留 tmp 文件（unlink 本身 try/catch，避免二次抛错）。
@@ -137,44 +160,55 @@ export function saveConfig(
 	onWarning?: (msg: string) => void,
 ): { success: boolean; error?: string } {
 	const configPath = getConfigPath(pkgName);
-	const tmpPath = `${configPath}.tmp`;
+	const tmpPath = uniqueTmpPath(configPath);
 	const content = `${JSON.stringify(config, null, JSON_INDENT)}\n`;
 
-	try {
-		mkdirSync(dirname(configPath), { recursive: true });
-		writeFileSync(tmpPath, content, { encoding: "utf-8", mode: 0o600 });
-		renameSync(tmpPath, configPath);
-
-		// 写后更新缓存（用新文件 mtime+size + 写入的 config）
+	const writeLocked = (): { success: boolean; error?: string } => {
 		try {
-			const newStat = statSync(configPath);
-			configCache.set(configPath, {
-				mtimeMs: newStat.mtimeMs,
-				size: newStat.size,
-				config: clone(config),
-			});
-		} catch (statErr) {
-			// stat 失败不影响保存成功；缓存下次 load 时会重读
-			console.warn(
-				`[llm-shared] saveConfig stat after write failed:`,
-				statErr instanceof Error ? statErr.message : String(statErr),
-			);
+			mkdirSync(dirname(configPath), { recursive: true });
+			writeFileSync(tmpPath, content, { encoding: "utf-8", mode: 0o600 });
+			renameSync(tmpPath, configPath);
+
+			// 写后更新缓存（用新文件 mtime+size + 写入的 config）
+			try {
+				const newStat = statSync(configPath);
+				configCache.set(configPath, {
+					mtimeMs: newStat.mtimeMs,
+					size: newStat.size,
+					config: clone(config),
+				});
+			} catch (statErr) {
+				// stat 失败不影响保存成功；缓存下次 load 时会重读
+				console.warn(
+					`[llm-shared] saveConfig stat after write failed:`,
+					statErr instanceof Error ? statErr.message : String(statErr),
+				);
+			}
+
+			return { success: true };
+		} catch (error) {
+			// RK3: 清理残留 tmp 文件（writeFileSync 或 renameSync 失败时 tmp 可能残留）
+			try {
+				if (existsSync(tmpPath)) unlinkSync(tmpPath);
+			} catch (cleanupErr) {
+				// tmp 清理失败不能阻塞保存失败的返回；记录原因
+				console.warn(
+					`[llm-shared] saveConfig tmp cleanup failed:`,
+					cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr),
+				);
+			}
+			const message = error instanceof Error ? error.message : String(error);
+			onWarning?.(`[llm-shared] Failed to save config at '${configPath}': ${message}`);
+			return { success: false, error: `Failed to save config at '${configPath}': ${message}` };
 		}
+	};
 
-		return { success: true };
-	} catch (error) {
-		// RK3: 清理残留 tmp 文件（writeFileSync 或 renameSync 失败时 tmp 可能残留）
-		try {
-			if (existsSync(tmpPath)) unlinkSync(tmpPath);
-		} catch (cleanupErr) {
-			// tmp 清理失败不能阻塞保存失败的返回；记录原因
-			console.warn(
-				`[llm-shared] saveConfig tmp cleanup failed:`,
-				cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr),
-			);
-		}
-		const message = error instanceof Error ? error.message : String(error);
-		onWarning?.(`[llm-shared] Failed to save config at '${configPath}': ${message}`);
-		return { success: false, error: `Failed to save config at '${configPath}': ${message}` };
+	try {
+		return withFileLockSync(configPath, writeLocked);
+	} catch (lockErr) {
+		// 锁获取失败（ELOCKED 预算耗尽等）：不降级无锁写（见 docstring），按保存失败返回
+		const message = lockErr instanceof Error ? lockErr.message : String(lockErr);
+		onWarning?.(`[llm-shared] Config write lock unavailable at '${configPath}': ${message}`);
+		return { success: false, error: `Config write lock unavailable at '${configPath}': ${message}` };
 	}
 }

package/src/index.ts

@@ -1,8 +1,8 @@
 // @zhushanwen/pi-llm-shared —— 统一 public API 出口。
-// resolve: 模型解析（四形式 selector）
+// resolve: 模型解析（仅 ref 精确指定）
 // call: LLM 调用（completeSimple + 凭证 + 文本提取）
 // config: 泛型配置读写（mtime 缓存 + 原子写）
-export { resolveModel, readEnabledModels, matchGlob, type ModelSelector } from "./resolve.ts";
+export { resolveModel, type ModelSelector } from "./resolve.ts";
 export { callLLM, extractText, type CallLLMOptions, type CallLLMResult } from "./call.ts";
 export { getConfigPath, loadConfig, saveConfig, clearConfigCache } from "./config.ts";
 export { migrateLegacyConfig, type MigrationResult } from "./migrate.ts";

package/src/resolve.ts

@@ -1,83 +1,21 @@
 /**
- * 模型解析：把 ModelSelector（四形式）解析成可用的 Model，或 null（不可用，调用方静默跳过）。
+ * 模型解析：把 ModelSelector（仅 ref 精确指定）解析成可用的 Model，或 null（不可用，调用方静默跳过）。
  *
- * 设计依据：design.md §3.4 + slice 6 决策。scoped 形式自读 <agentDir>/settings.json 的
- * enabledModels（string[]，"provider/modelId" 格式可含 * glob），不依赖调用方传入列表 ——
- * 这样 rename-session / permission 等 consumer 无需各自重复读 settings.json 的逻辑。
+ * 只支持精确指定 provider/modelId；不再支持 fallback / available / scoped。
+ * 需要自动选模的调用方（如 permission 的 "auto"）应在自己这一层基于 ctx.modelRegistry 实现，
+ * 不通过 ModelSelector 表达非精确语义。
  */
 
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
 import type { Api, Model } from "@earendil-works/pi-ai";
-import { getAgentDir, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 // ──────────────────────── 类型 ────────────────────────
 
 /**
- * 模型选择器（四形式）。
+ * 模型选择器：只支持精确指定。
  * - ref: "provider/modelId" 精确，需 hasConfiguredAuth
- * - fallback: 按序尝试 refs，首个可用的返回
- * - available: getAvailable()[0]（pi 已配置 auth 的全量模型池）
- * - scoped: 读 settings.json enabledModels glob 匹配 getAll()，按用户排序取首个可用
- */
-export type ModelSelector =
-	| { type: "ref"; ref: string }
-	| { type: "fallback"; refs: string[] }
-	| { type: "available" }
-	| { type: "scoped" };
-
-// ──────────────────────── glob 匹配 ────────────────────────
-
-/**
- * 自实现 * 通配匹配（不引入 minimatch 依赖）。
- *
- * 只支持 `*`（匹配任意字符序列），不支持 `?` / `**` / 字符类 —— enabledModels 的 pattern
- * 只需 "provider/*" 这种简单通配。实现：把 pattern 转成正则，特殊字符转义（`*` 单独转成 `.*`），
- * 全程 `^...$` 锚定。
- *
- * 例：`*` 匹配任意；`anthropic/*` 匹配 `anthropic/claude`；`openai/gpt-4o` 精确匹配。
- */
-export function matchGlob(pattern: string, str: string): boolean {
-	const re = pattern.replace(/[\\^$.|?*+(){}[\]]/g, (ch) => (ch === "*" ? ".*" : `\\${ch}`));
-	return new RegExp(`^${re}$`).test(str);
-}
-
-// ──────────────────────── settings.json 读取 ────────────────────────
-
-/**
- * 读取 <agentDir>/settings.json 的 enabledModels 字段（string[]）。
- *
- * 降级策略（scoped 形式据此返回 null，绝不抛错）：
- * - 文件不存在 / 读失败 → []
- * - 坏 JSON / 顶层非对象 → []
- * - enabledModels 缺失 / 非数组 → []
- * - 非 string 元素过滤掉，保持剩余元素顺序
- *
- * 用 pi 导出的 getAgentDir（尊重 PI_CODING_AGENT_DIR 覆盖）。
  */
-export function readEnabledModels(): string[] {
-	const filePath = join(getAgentDir(), "settings.json");
-
-	let raw: string;
-	try {
-		raw = readFileSync(filePath, "utf-8");
-	} catch {
-		return [];
-	}
-
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		return [];
-	}
-
-	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return [];
-	const enabled = (parsed as Record<string, unknown>).enabledModels;
-	if (!Array.isArray(enabled)) return [];
-	return enabled.filter((x): x is string => typeof x === "string");
-}
+export type ModelSelector = { type: "ref"; ref: string };
 
 // ──────────────────────── 模型解析 ────────────────────────
 
@@ -98,50 +36,11 @@ function resolveRef(ctx: ExtensionContext, ref: string): Model<Api> | null {
 	return model;
 }
 
-/** fallback：按序尝试 refs，首个可用的返回（提前返回，不遍历完）。 */
-function resolveFallback(ctx: ExtensionContext, refs: string[]): Model<Api> | null {
-	for (const ref of refs) {
-		const model = resolveRef(ctx, ref);
-		if (model) return model;
-	}
-	return null;
-}
-
-/** available：getAvailable()[0]（pi 已配置 auth 的模型池，取首个）。空池返回 null。 */
-function resolveAvailable(ctx: ExtensionContext): Model<Api> | null {
-	const list = ctx.modelRegistry.getAvailable();
-	return list.length > 0 ? list[0] : null;
-}
-
-/**
- * scoped：读 settings.json enabledModels，按用户排序遍历 pattern，
- * 每个 pattern 对 getAll() 的 `${provider}/${id}` 做 matchGlob，首个 hasConfiguredAuth 命中即返回。
- *
- * 命中序：外层按 enabledModels 顺序（用户排序优先级），内层按 getAll() 返回顺序（pi 注册序）。
- * 即 enabledModels 首个 pattern 的首个可用匹配优先 —— 符合「用户排序首位」语义。
- */
-function resolveScoped(ctx: ExtensionContext): Model<Api> | null {
-	const patterns = readEnabledModels();
-	if (patterns.length === 0) return null;
-	const all = ctx.modelRegistry.getAll();
-	for (const pattern of patterns) {
-		for (const model of all) {
-			if (matchGlob(pattern, `${model.provider}/${model.id}`) && ctx.modelRegistry.hasConfiguredAuth(model)) {
-				return model;
-			}
-		}
-	}
-	return null;
-}
-
 /**
- * 按 selector 形式解析模型。返回 null = 不可用，调用方静默跳过（不抛错）。
+ * 按 selector 解析模型。返回 null = 不可用，调用方静默跳过（不抛错）。
  *
  * 走 ctx.modelRegistry（pi 三源合并后的模型注册表）。hasConfiguredAuth 过滤掉未配置凭证的模型。
  */
 export function resolveModel(ctx: ExtensionContext, selector: ModelSelector): Model<Api> | null {
-	if (selector.type === "ref") return resolveRef(ctx, selector.ref);
-	if (selector.type === "fallback") return resolveFallback(ctx, selector.refs);
-	if (selector.type === "available") return resolveAvailable(ctx);
-	return resolveScoped(ctx); // selector.type === "scoped"
+	return resolveRef(ctx, selector.ref);
 }

package/src/__tests__/scoped.test.ts

@@ -1,139 +0,0 @@
-import type { Api, Model } from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-import { matchGlob, readEnabledModels, resolveModel } from "../resolve.ts";
-
-function makeModel(provider: string, id: string): Model<Api> {
-	return { id, provider, name: id, api: "anthropic" as Api, baseUrl: "", reasoning: false } as unknown as Model<Api>;
-}
-
-function makeCtx(all: Model<Api>[], hasAuth: (m: Model<Api>) => boolean): ExtensionContext {
-	return {
-		modelRegistry: {
-			getAll: () => all,
-			hasConfiguredAuth: hasAuth,
-		},
-	} as unknown as ExtensionContext;
-}
-
-let dir: string;
-
-beforeEach(() => {
-	dir = mkdtempSync(join(tmpdir(), "llm-shared-scoped-"));
-	vi.stubEnv("PI_CODING_AGENT_DIR", dir);
-});
-
-afterEach(() => {
-	rmSync(dir, { recursive: true, force: true });
-	vi.unstubAllEnvs();
-});
-
-describe("resolveModel scoped", () => {
-	it("TC7 glob 匹配按 enabledModels 顺序取首个可用", () => {
-		writeFileSync(join(dir, "settings.json"), JSON.stringify({ enabledModels: ["anthropic/*", "openai/gpt-4o"] }));
-		const claude = makeModel("anthropic", "claude");
-		const gpt = makeModel("openai", "gpt-4o");
-		const gemini = makeModel("google", "gemini");
-		const ctx = makeCtx([claude, gpt, gemini], () => true);
-
-		// enabledModels 首个 pattern anthropic/* 命中 claude
-		expect(resolveModel(ctx, { type: "scoped" })).toBe(claude);
-	});
-
-	it("TC7 首个 pattern 无可用 model → 回退到下一个 pattern", () => {
-		writeFileSync(join(dir, "settings.json"), JSON.stringify({ enabledModels: ["google/*", "openai/gpt-4o"] }));
-		const gpt = makeModel("openai", "gpt-4o");
-		// getAll 不含 google，含 openai
-		const ctx = makeCtx([gpt], () => true);
-		expect(resolveModel(ctx, { type: "scoped" })).toBe(gpt);
-	});
-
-	it("review: scoped 同 pattern 多 model 命中序 —— 取 getAll() 遍历序首个", () => {
-		writeFileSync(join(dir, "settings.json"), JSON.stringify({ enabledModels: ["anthropic/*"] }));
-		const claude = makeModel("anthropic", "claude");
-		const haiku = makeModel("anthropic", "haiku");
-
-		// getAll 返回 [claude, haiku]，pattern anthropic/* 都匹配，取遍历序首个 claude
-		const ctx1 = makeCtx([claude, haiku], () => true);
-		expect(resolveModel(ctx1, { type: "scoped" })).toBe(claude);
-
-		// 反序验证：取首个 haiku
-		const ctx2 = makeCtx([haiku, claude], () => true);
-		expect(resolveModel(ctx2, { type: "scoped" })).toBe(haiku);
-	});
-
-	it("TC8 enabledModels 缺失（无 settings.json）→ null（不抛错）", () => {
-		const ctx = makeCtx([makeModel("a", "1")], () => true);
-		expect(resolveModel(ctx, { type: "scoped" })).toBeNull();
-	});
-
-	it("TC8 settings.json 无 enabledModels 字段 → null", () => {
-		writeFileSync(join(dir, "settings.json"), JSON.stringify({ other: "field" }));
-		const ctx = makeCtx([makeModel("a", "1")], () => true);
-		expect(resolveModel(ctx, { type: "scoped" })).toBeNull();
-	});
-
-	it("TC8 enabledModels 空数组 → null", () => {
-		writeFileSync(join(dir, "settings.json"), JSON.stringify({ enabledModels: [] }));
-		const ctx = makeCtx([makeModel("a", "1")], () => true);
-		expect(resolveModel(ctx, { type: "scoped" })).toBeNull();
-	});
-
-	it("scoped glob 命中但全部无 auth → null", () => {
-		writeFileSync(join(dir, "settings.json"), JSON.stringify({ enabledModels: ["anthropic/*"] }));
-		const claude = makeModel("anthropic", "claude");
-		const ctx = makeCtx([claude], () => false);
-		expect(resolveModel(ctx, { type: "scoped" })).toBeNull();
-	});
-});
-
-describe("matchGlob", () => {
-	it("TC9 * 通配 / 精确 / 多段匹配", () => {
-		expect(matchGlob("*", "anything")).toBe(true);
-		expect(matchGlob("*", "a/b/c")).toBe(true);
-		expect(matchGlob("anthropic/*", "anthropic/claude")).toBe(true);
-		expect(matchGlob("anthropic/*", "openai/gpt")).toBe(false);
-		expect(matchGlob("openai/gpt-4o", "openai/gpt-4o")).toBe(true);
-		// 精确匹配不含通配，后缀不同不匹配
-		expect(matchGlob("openai/gpt-4o", "openai/gpt-4o-mini")).toBe(false);
-		expect(matchGlob("*-router/*", "deepseek-router/deepseek-chat")).toBe(true);
-		expect(matchGlob("*-router/*", "deepseek/deepseek-chat")).toBe(false);
-	});
-
-	it("TC9 特殊字符转义（pattern 含 . 等正则元字符，按字面匹配）", () => {
-		// gpt-4o 中的 . 若不被转义会匹配任意字符；这里无 . 但有 -，- 在字符类外非特殊
-		expect(matchGlob("v1.0/stable", "v1.0/stable")).toBe(true);
-		expect(matchGlob("v1.0/stable", "v1X0/stable")).toBe(false); // . 被转义，不匹配任意字符
-	});
-});
-
-describe("readEnabledModels", () => {
-	it("TC10 解析 + 顺序保持（非字母序原样）", () => {
-		writeFileSync(join(dir, "settings.json"), JSON.stringify({ enabledModels: ["b/2", "a/1", "c/3"] }));
-		expect(readEnabledModels()).toEqual(["b/2", "a/1", "c/3"]);
-	});
-
-	it("TC10 过滤非 string 元素", () => {
-		writeFileSync(join(dir, "settings.json"), JSON.stringify({ enabledModels: [1, "a/1", null, true, "b/2"] }));
-		expect(readEnabledModels()).toEqual(["a/1", "b/2"]);
-	});
-
-	it("TC10 坏 JSON → []", () => {
-		writeFileSync(join(dir, "settings.json"), "{not json");
-		expect(readEnabledModels()).toEqual([]);
-	});
-
-	it("TC10 enabledModels 非数组 → []", () => {
-		writeFileSync(join(dir, "settings.json"), JSON.stringify({ enabledModels: "anthropic/*" }));
-		expect(readEnabledModels()).toEqual([]);
-	});
-
-	it("TC10 顶层非对象 → []", () => {
-		writeFileSync(join(dir, "settings.json"), JSON.stringify(["a/1"]));
-		expect(readEnabledModels()).toEqual([]);
-	});
-});