@zhushanwen/pi-llm-shared 0.2.0

package/index.ts

@@ -0,0 +1 @@
+export * from "./src/index.ts";

package/package.json

@@ -0,0 +1,41 @@
+{
+  "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.",
+  "type": "module",
+  "main": "src/index.ts",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "llm",
+    "shared",
+    "model-resolution",
+    "config"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/",
+    "index.ts"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/call.test.ts

@@ -0,0 +1,209 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { callLLM, extractText } from "../call.ts";
+
+// mock completeSimple —— call.ts 顶层静态 import 会拿到此 mock（探针①已验证静态 import 机制可行，
+// 此处验证 callLLM 逻辑：凭证 narrow / options 构造 / 文本提取 / 错误归一化）。
+vi.mock("@earendil-works/pi-ai/compat", () => ({
+	completeSimple: vi.fn(),
+}));
+
+const mockComplete = vi.mocked(completeSimple);
+
+function makeModel(): Model<Api> {
+	return { id: "m", provider: "p", name: "m", api: "anthropic" as Api, baseUrl: "", reasoning: false } as unknown as Model<Api>;
+}
+
+function makeCtx(authResult: unknown): ExtensionContext {
+	return {
+		modelRegistry: { getApiKeyAndHeaders: vi.fn(async () => authResult) },
+	} as unknown as ExtensionContext;
+}
+
+beforeEach(() => {
+	mockComplete.mockReset();
+});
+
+describe("callLLM", () => {
+	it("TC11 成功：提取 text（trim）+ tools 传 []", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		mockComplete.mockResolvedValue({ content: [{ type: "text", text: "  hello  " }] });
+
+		const result = await callLLM(ctx, {
+			model: makeModel(),
+			systemPrompt: "s",
+			messages: [],
+			sessionId: "sess-1",
+		});
+
+		expect(result).toEqual({ ok: true, content: "hello" });
+		// 验证 completeSimple 被调用，第二参数 context 含 tools:[]，第三参数 options 含 apiKey + sessionId 透传
+		expect(mockComplete).toHaveBeenCalledTimes(1);
+		const [, contextArg, optionsArg] = mockComplete.mock.calls[0];
+		expect(contextArg).toMatchObject({ systemPrompt: "s", messages: [], tools: [] });
+		expect(optionsArg).toMatchObject({ apiKey: "k", sessionId: "sess-1" });
+	});
+
+	it("TC12 auth-fail → {ok:false, recoverable:true}，不调 completeSimple（narrow 不取 apiKey）", async () => {
+		const ctx = makeCtx({ ok: false, error: "no key" });
+
+		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
+
+		expect(result).toEqual({ ok: false, error: "no key", recoverable: true });
+		expect(mockComplete).not.toHaveBeenCalled();
+	});
+
+	it("TC13 completeSimple throw → {ok:false, recoverable:true, error 含错误信息}", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		mockComplete.mockRejectedValue(new Error("network timeout"));
+
+		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
+
+		expect(result.ok).toBe(false);
+		expect(result).toMatchObject({ recoverable: true, error: expect.stringContaining("network") });
+	});
+
+	it("TC1 stopReason=error → {ok:false, error, recoverable:true, stopReason:'error'}（不再 ok:true 返回错误文本）", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		// completeSimple 对错误也 resolve（带 stopReason），content 是错误文本
+		mockComplete.mockResolvedValue({ stopReason: "error", content: [{ type: "text", text: "API error: 429 rate limited" }] });
+
+		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
+
+		expect(result).toEqual({ ok: false, error: "API error: 429 rate limited", recoverable: true, stopReason: "error" });
+	});
+
+	it("TC2 stopReason=aborted → {ok:false, error, recoverable:true, stopReason:'aborted'}", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		mockComplete.mockResolvedValue({ stopReason: "aborted", content: [{ type: "text", text: "user aborted" }] });
+
+		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
+
+		expect(result).toEqual({ ok: false, error: "user aborted", recoverable: true, stopReason: "aborted" });
+	});
+
+	it("TC3 stopReason=stop（正常）→ 不受 stopReason 检查影响，ok:true 提取文本", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		mockComplete.mockResolvedValue({ stopReason: "stop", content: [{ type: "text", text: "  hello  " }] });
+
+		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
+
+		expect(result).toEqual({ ok: true, content: "hello" });
+	});
+
+	it("stopReason=error 且 content 无 text → error 回落 'unknown error'", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		mockComplete.mockResolvedValue({ stopReason: "error", content: [] });
+
+		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
+
+		expect(result).toEqual({ ok: false, error: "unknown error", recoverable: true, stopReason: "error" });
+	});
+
+	it("TC13 catch 路径不设 stopReason（错误原因不可知）", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		mockComplete.mockRejectedValue(new Error("boom"));
+
+		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
+
+		expect(result.ok).toBe(false);
+		if (result.ok === false) {
+			expect(result.stopReason).toBeUndefined();
+		}
+	});
+
+	it("review TF1: sessionId 透传到 options 第三参数", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		mockComplete.mockResolvedValue({ content: [{ type: "text", text: "x" }] });
+
+		await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [], sessionId: "abc-123" });
+
+		const optionsArg = mockComplete.mock.calls[0][2];
+		expect(optionsArg).toMatchObject({ sessionId: "abc-123" });
+	});
+
+	it("review TF1: 无 sessionId 时 options 不含 sessionId 字段（条件 spread 不传）", 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("sessionId" 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;
+
+		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
+
+		expect(result).toEqual({ ok: false, error: "registry exploded", recoverable: true });
+		// 凭证阶段就 reject，completeSimple 未被调用
+		expect(mockComplete).not.toHaveBeenCalled();
+	});
+
+	it("review C2: signal 透传到 options 第三参数", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		mockComplete.mockResolvedValue({ content: [{ type: "text", text: "x" }] });
+		const ac = new AbortController();
+
+		await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [], signal: ac.signal });
+
+		const optionsArg = mockComplete.mock.calls[0][2];
+		expect(optionsArg).toMatchObject({ signal: ac.signal });
+	});
+
+	it("review C2: maxTokens 透传到 options 第三参数", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		mockComplete.mockResolvedValue({ content: [{ type: "text", text: "x" }] });
+
+		await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [], maxTokens: 1024 });
+
+		const optionsArg = mockComplete.mock.calls[0][2];
+		expect(optionsArg).toMatchObject({ maxTokens: 1024 });
+	});
+
+	it("review C2: timeoutMs 透传到 options 第三参数", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		mockComplete.mockResolvedValue({ content: [{ type: "text", text: "x" }] });
+
+		await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [], timeoutMs: 5000 });
+
+		const optionsArg = mockComplete.mock.calls[0][2];
+		expect(optionsArg).toMatchObject({ timeoutMs: 5000 });
+	});
+
+	it("review C2: 不传 signal/maxTokens/timeoutMs 时 options 不含这些字段（条件 spread）", 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("signal" in optionsArg).toBe(false);
+		expect("maxTokens" in optionsArg).toBe(false);
+		expect("timeoutMs" in optionsArg).toBe(false);
+	});
+});
+
+describe("extractText", () => {
+	it("TC11 单个 text block 提取 + trim", () => {
+		expect(extractText({ content: [{ type: "text", text: "  hello  " }] })).toBe("hello");
+	});
+
+	it("review: 多个 text block 拼接 + trim", () => {
+		expect(extractText({ content: [{ type: "text", text: "a" }, { type: "text", text: "b" }] })).toBe("a b");
+	});
+
+	it("review: 无 text block（纯 ThinkingContent / ToolCall）→ ''", () => {
+		expect(extractText({ content: [{ type: "thinking", text: "..." }, { type: "tool_call" }] })).toBe("");
+	});
+
+	it("review: 空 content → ''", () => {
+		expect(extractText({ content: [] })).toBe("");
+	});
+});

package/src/__tests__/config.test.ts

@@ -0,0 +1,217 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, 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";
+
+// node:fs 的 ESM namespace 不可配置，vi.spyOn 对具名导出失效（vitest 限制）。
+// 用 vi.mock 包装 readFileSync/renameSync（默认走 actual，个别 test override），
+// 其他 fs 操作（writeFileSync/existsSync/statSync/mkdirSync...）原样透传 actual。
+vi.mock("node:fs", async (importOriginal) => {
+	const actual = await importOriginal() as typeof import("node:fs");
+	return {
+		...actual,
+		readFileSync: vi.fn(actual.readFileSync),
+		renameSync: vi.fn(actual.renameSync),
+	};
+});
+
+let dir: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "llm-shared-cfg-"));
+	vi.stubEnv("PI_CODING_AGENT_DIR", dir);
+	clearConfigCache();
+	// 预创建 config/ 子目录（loadConfig fixture 直接 writeFileSync 需要目录已存在；
+	// saveConfig 内部会自己 mkdir，但 loadConfig fixture 不会）
+	mkdirSync(join(dir, "config"), { recursive: true });
+});
+
+afterEach(() => {
+	vi.mocked(fs.readFileSync).mockClear();
+	vi.mocked(fs.renameSync).mockClear();
+	rmSync(dir, { recursive: true, force: true });
+	vi.unstubAllEnvs();
+});
+
+/** 测试用 normalize：对象含 a → 原样，否则默认 {a:0}。 */
+const normalize = (raw: unknown): { a: number } => {
+	if (typeof raw === "object" && raw !== null && !Array.isArray(raw) && "a" in raw) {
+		return { a: (raw as { a: number }).a };
+	}
+	return { a: 0 };
+};
+
+describe("getConfigPath", () => {
+	it("TC17 走 getAgentDir（PI_CODING_AGENT_DIR 覆盖生效）", () => {
+		expect(getConfigPath("rename-session")).toBe(join(dir, "config", "rename-session-ext-config.json"));
+	});
+});
+
+describe("loadConfig", () => {
+	it("TC14 文件存在 → 解析 + normalize", () => {
+		writeFileSync(join(dir, "config", "test-ext-config.json"), JSON.stringify({ a: 1 }));
+		expect(loadConfig("test", { a: 0 }, normalize)).toEqual({ a: 1 });
+	});
+
+	it("TC14 mtime+size 不变 → 命中缓存（readFileSync 只调一次）", () => {
+		writeFileSync(join(dir, "config", "test-ext-config.json"), JSON.stringify({ a: 1 }));
+		vi.mocked(fs.readFileSync).mockClear();
+
+		const r1 = loadConfig("test", { a: 0 }, normalize);
+		const r2 = loadConfig("test", { a: 0 }, normalize);
+
+		expect(r1).toEqual({ a: 1 });
+		expect(r2).toEqual({ a: 1 });
+		// statSync 命中缓存，readFileSync 只调一次
+		expect(vi.mocked(fs.readFileSync)).toHaveBeenCalledTimes(1);
+	});
+
+	it("TC14 缓存返回值是深拷贝（改返回值不污染缓存）", () => {
+		writeFileSync(join(dir, "config", "test-ext-config.json"), JSON.stringify({ a: 1 }));
+		const r1 = loadConfig("test", { a: 0 }, normalize);
+		r1.a = 999; // 篡改返回值
+		const r2 = loadConfig("test", { a: 0 }, normalize);
+		expect(r2).toEqual({ a: 1 }); // 缓存未被污染
+	});
+
+	it("TC15 文件不存在 → defaults", () => {
+		expect(loadConfig("missing", { a: 0 }, normalize)).toEqual({ a: 0 });
+	});
+
+	it("TC15 坏 JSON → defaults + onWarning 回调", () => {
+		writeFileSync(join(dir, "config", "bad-ext-config.json"), "{not json");
+		const onWarning = vi.fn();
+		expect(loadConfig("bad", { a: 0 }, normalize, onWarning)).toEqual({ a: 0 });
+		expect(onWarning).toHaveBeenCalledTimes(1);
+	});
+
+	it("C1: mtime 变化（size 不变）→ 重新 readFileSync（缓存失效重读）", () => {
+		const cfgPath = join(dir, "config", "test-ext-config.json");
+		// v1: {"a":1}（7 字节），mtime 固定 1s → mtimeMs=1000
+		writeFileSync(cfgPath, JSON.stringify({ a: 1 }));
+		utimesSync(cfgPath, 1, 1);
+		loadConfig("test", { a: 0 }, normalize); // 首次读，cache=(1000ms, 7)
+
+		// v2: {"a":2}（仍 7 字节，size 不变），mtime 改为 2s → mtimeMs=2000
+		writeFileSync(cfgPath, JSON.stringify({ a: 2 }));
+		utimesSync(cfgPath, 2, 2);
+
+		vi.mocked(fs.readFileSync).mockClear();
+		const loaded = loadConfig("test", { a: 0 }, normalize);
+
+		expect(loaded).toEqual({ a: 2 });
+		// mtime 变化 → 缓存失效 → 重读
+		expect(vi.mocked(fs.readFileSync)).toHaveBeenCalledTimes(1);
+	});
+
+	it("C1: size 变化但 mtime 不变（APFS 截断模拟）→ 触发重读（双 key 设计核心验证）", () => {
+		const cfgPath = join(dir, "config", "test-ext-config.json");
+		// v1: {"a":1}（7 字节），mtime 固定 1s
+		writeFileSync(cfgPath, JSON.stringify({ a: 1 }));
+		utimesSync(cfgPath, 1, 1);
+		loadConfig("test", { a: 0 }, normalize); // cache=(1000ms, 7)
+
+		// v2: {"a":99}（8 字节，size 变），mtime 强制回 1s（模拟 APFS 精度截断：内容变了 mtime 没变）
+		writeFileSync(cfgPath, JSON.stringify({ a: 99 }));
+		utimesSync(cfgPath, 1, 1);
+
+		vi.mocked(fs.readFileSync).mockClear();
+		const loaded = loadConfig("test", { a: 0 }, normalize);
+
+		expect(loaded).toEqual({ a: 99 });
+		// size 变化 → 缓存失效 → 重读（即使 mtimeMs 相同，双 key 设计的核心价值）
+		expect(vi.mocked(fs.readFileSync)).toHaveBeenCalledTimes(1);
+	});
+});
+
+describe("saveConfig", () => {
+	it("TC16 原子写：文件落盘 + 内容正确 + 无 tmp 残留", () => {
+		const result = saveConfig("test", { b: 2 });
+		expect(result.success).toBe(true);
+
+		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 残留
+	});
+
+	it("TC16 文件 mode 0o600", () => {
+		saveConfig("test", { b: 2 });
+		const cfgPath = join(dir, "config", "test-ext-config.json");
+		const mode = statSync(cfgPath).mode & 0o777;
+		expect(mode).toBe(0o600);
+	});
+
+	it("TC16 写后 loadConfig 命中缓存返回新值（写后读竞态覆盖）", () => {
+		saveConfig("test", { a: 5 });
+		// saveConfig 写后已更新缓存，loadConfig 直接命中（不重读盘）
+		vi.mocked(fs.readFileSync).mockClear();
+		const loaded = loadConfig("test", { a: 0 }, normalize);
+		expect(loaded).toEqual({ a: 5 });
+		expect(vi.mocked(fs.readFileSync)).not.toHaveBeenCalled();
+	});
+
+	it("review RK3: renameSync throw → {success:false} + tmp 被清理", () => {
+		// mock renameSync 抛 EPERM，模拟 rename 失败（writeFileSync 已创建 tmp）
+		vi.mocked(fs.renameSync).mockImplementationOnce(() => {
+			throw new Error("EPERM: operation not permitted, rename");
+		});
+
+		const result = saveConfig("fail", { x: 1 });
+
+		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);
+		// 目标文件未被创建（rename 失败）
+		expect(existsSync(join(dir, "config", "fail-ext-config.json"))).toBe(false);
+	});
+
+	it("探针 4: renameSync ENOENT → {success:false} + onWarning 含 Failed to save config + tmp 清理", () => {
+		// mock renameSync 抛 ENOENT（目标目录被删/路径无效场景）
+		vi.mocked(fs.renameSync).mockImplementationOnce(() => {
+			throw new Error("ENOENT: no such file or directory, rename");
+		});
+		const onWarning = vi.fn();
+
+		const result = saveConfig("enoent", { x: 1 }, onWarning);
+
+		expect(result.success).toBe(false);
+		expect(result.error).toContain("ENOENT");
+		// onWarning 输出前缀契约：`[llm-shared] Failed to save config at '<path>': <message>`
+		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("ENOENT");
+		// tmp 清理 + 目标未创建
+		expect(existsSync(join(dir, "config", "enoent-ext-config.json.tmp"))).toBe(false);
+		expect(existsSync(join(dir, "config", "enoent-ext-config.json"))).toBe(false);
+	});
+
+	it("探针 4: renameSync EPERM → onWarning 输出契约 + {success:false}（Windows 目标占用模拟）", () => {
+		vi.mocked(fs.renameSync).mockImplementationOnce(() => {
+			throw new Error("EPERM: operation not permitted, rename");
+		});
+		const onWarning = vi.fn();
+
+		const result = saveConfig("eperm", { x: 1 }, onWarning);
+
+		expect(result.success).toBe(false);
+		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", "eperm-ext-config.json") + "'");
+		expect(warning).toContain("EPERM");
+		// tmp 清理（Windows 目标占用场景 rename 失败后 tmp 残留被清理）
+		expect(existsSync(join(dir, "config", "eperm-ext-config.json.tmp"))).toBe(false);
+		expect(existsSync(join(dir, "config", "eperm-ext-config.json"))).toBe(false);
+	});
+
+	it("saveConfig 多次写同文件 → 每次成功 + 最新内容", () => {
+		expect(saveConfig("test", { v: 1 }).success).toBe(true);
+		expect(saveConfig("test", { v: 2 }).success).toBe(true);
+		expect(JSON.parse(readFileSync(join(dir, "config", "test-ext-config.json"), "utf-8"))).toEqual({ v: 2 });
+	});
+});

package/src/__tests__/migrate.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { migrateLegacyConfig } from "../migrate.ts";
+
+describe("migrateLegacyConfig", () => {
+	let dir: string;
+	beforeEach(() => {
+		dir = mkdtempSync(join(tmpdir(), "pi-migrate-test-"));
+	});
+	afterEach(() => {
+		rmSync(dir, { recursive: true, force: true });
+	});
+
+	it("旧路径不存在 → noop（migrated: false，不动文件系统）", () => {
+		const result = migrateLegacyConfig(dir, "old.json", "config/new.json");
+		expect(result.migrated).toBe(false);
+		expect(existsSync(join(dir, "config/new.json"))).toBe(false);
+	});
+
+	it("旧路径存在 + 新路径不存在 → 原子搬移（旧消失、新出现、内容一致）", () => {
+		writeFileSync(join(dir, "old.json"), '{"mode":"strict"}', "utf-8");
+		const result = migrateLegacyConfig(dir, "old.json", "config/new.json");
+		expect(result.migrated).toBe(true);
+		expect(existsSync(join(dir, "old.json"))).toBe(false);
+		expect(existsSync(join(dir, "config/new.json"))).toBe(true);
+		expect(readFileSync(join(dir, "config/new.json"), "utf-8")).toBe('{"mode":"strict"}');
+	});
+
+	it("旧路径存在 + 新路径已存在 → 删除旧文件（新的是当前配置，旧的是残留副本）", () => {
+		mkdirSync(join(dir, "config"), { recursive: true });
+		writeFileSync(join(dir, "old.json"), "OLD", "utf-8");
+		writeFileSync(join(dir, "config/new.json"), "NEW", "utf-8");
+		const result = migrateLegacyConfig(dir, "old.json", "config/new.json");
+		expect(result.migrated).toBe(false);
+		expect(result.removedLegacy).toBe(true);
+		// 旧文件被删（清理残留），新文件保留不被覆盖
+		expect(existsSync(join(dir, "old.json"))).toBe(false);
+		expect(readFileSync(join(dir, "config/new.json"), "utf-8")).toBe("NEW");
+	});
+
+	it("迁移失败 → 不抛错，返回 error（best-effort，旧文件仍在）", () => {
+		// blocking-file 是文件不是目录，newRel 的父目录 mkdirSync 失败
+		writeFileSync(join(dir, "blocking-file"), "", "utf-8");
+		writeFileSync(join(dir, "old.json"), "X", "utf-8");
+		const result = migrateLegacyConfig(dir, "old.json", "blocking-file/new.json");
+		expect(result.migrated).toBe(false);
+		expect(result.error).toBeDefined();
+		expect(existsSync(join(dir, "old.json"))).toBe(true);
+	});
+});

package/src/__tests__/resolve.test.ts

@@ -0,0 +1,123 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { describe, expect, it, vi } from "vitest";
+
+import { resolveModel } from "../resolve.ts";
+
+/** 构造最小 Model（cast 绕过必填字段，单测只关心 provider/id）。 */
+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>;
+}
+
+/** 构造 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("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();
+		});
+	});
+
+	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();
+		});
+	});
+
+	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("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();
+		});
+	});
+
+	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();
+		});
+	});
+});

package/src/__tests__/scoped.test.ts

@@ -0,0 +1,139 @@
+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([]);
+	});
+});

package/src/call.ts

@@ -0,0 +1,128 @@
+/**
+ * LLM 调用封装：completeSimple + 凭证注入 + 文本提取 + 错误归一化。
+ *
+ * import 方式：顶层【静态】import completeSimple。
+ * 探针①（2026-08-12，pi 0.84.0）实测：pi extension loader 加载含顶层
+ * `import { completeSimple } from "@earendil-works/pi-ai/compat"` 的 extension 不 throw，
+ * typeof completeSimple === "function"。compat.js 本身是真实模块（非 throwing stub），
+ * rename-session/llm.ts 旧注释「加载阶段 compat 是 throwing stub」已过时（其代码用 import type +
+ * 动态 import，从未真正测过顶层静态运行时 import）。故本库用静态 import，更简单且 tree-shake 友好。
+ *
+ * 凭证：getApiKeyAndHeaders 返回判别联合 ResolvedRequestAuth，必须 `if(!auth.ok) return` narrow
+ * 后才能取 apiKey/headers/env（否则 TS 报错、运行时 auth.error 不存在）。
+ */
+
+// 顶层静态 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 { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+// ──────────────────────── 类型 ────────────────────────
+
+/** callLLM 入参。tools 不在此 —— callLLM 内部显式传 tools:[] 给 Context（不塞工具，best-effort 语义）。 */
+export interface CallLLMOptions {
+	/** resolveModel 返回的 Model 对象（不是字符串）。 */
+	model: Model<Api>;
+	/** 独立 system prompt，调用方负责构造（不复用 ctx.getSystemPrompt）。 */
+	systemPrompt: string;
+	/** pi-ai Message[]（对话历史 + 当前指令）。 */
+	messages: Message[];
+	maxTokens?: number;
+	signal?: AbortSignal;
+	timeoutMs?: number;
+	/** 透传给 SimpleStreamOptions.sessionId（provider 用于 session 缓存 / 路由）。review TF1 新增。 */
+	sessionId?: string;
+}
+
+/**
+ * callLLM 出参。
+ * - ok:true → content 为提取并 trim 的文本
+ * - ok:false → recoverable 表示可恢复性（C2b：当前实现统一 true，细分待未来有消费者）；
+ *   stopReason 是独立透传字段（失败原因维度，不映射 recoverable），供调用方保留
+ *   error/aborted 的日志区分（如 permission classifier 的 G3 语义）。
+ */
+export type CallLLMResult =
+	| { ok: true; content: string }
+	| { ok: false; error: string; recoverable: boolean; stopReason?: "error" | "aborted" };
+
+// ──────────────────────── 文本提取 ────────────────────────
+
+/**
+ * 从 AssistantMessage.content 提取所有 text block 拼接并 trim。
+ *
+ * 参数用结构类型（不直接依赖 AssistantMessage），便于测试 mock —— 调用方传 completeSimple 返回值即可。
+ * 无 text block（如纯 ThinkingContent / ToolCall）→ 返回 ""。
+ */
+export function extractText(resp: {
+	content: ReadonlyArray<{ type: string; text?: string }>;
+}): string {
+	return resp.content
+		.filter((block) => block.type === "text")
+		.map((block) => block.text ?? "")
+		.join(" ")
+		.trim();
+}
+
+// ──────────────────────── 调用 ────────────────────────
+
+/**
+ * 发起一次 LLM 调用（completeSimple），返回归一化结果。
+ *
+ * 流程：
+ * 1. 凭证：getApiKeyAndHeaders(model) → narrow（auth.ok 判别联合）→ 返回 {ok:false} 提前返回；
+ *    reject（抛异常，非返回 {ok:false}）也落入步骤 5（B5：凭证注入与 completeSimple 同处 try，
+ *    保证 reject 归一为 {ok:false}，调用方日志前缀一致）
+ * 2. 调用：completeSimple(model, {systemPrompt, messages, tools:[]}, {apiKey, headers?, env?, signal?, maxTokens?, timeoutMs?, sessionId?})
+ * 3. 检查 resp.stopReason：error/aborted（completeSimple 对错误/中止也 resolve 带 stopReason，G3）
+ *    → {ok:false, error: 提取错误文本, recoverable:true, stopReason}（不再当正常内容提取）
+ * 4. 提取 text → {ok:true, content}
+ * 5. throw（getApiKeyAndHeaders reject / 网络 / 超时 / 解析）→ catch → {ok:false, error:String(e), recoverable:true}
+ *    （C2b：catch 路径不细分 recoverable，统一 true；stopReason 不设——错误原因不可知）
+ *
+ * tools 显式传 []（不塞工具）—— 本库用于标题生成等 best-effort 场景，不需要工具调用。
+ */
+export async function callLLM(
+	ctx: ExtensionContext,
+	opts: CallLLMOptions,
+): Promise<CallLLMResult> {
+	// 整个流程纳入 try：getApiKeyAndHeaders / completeSimple 任一 reject/throw 都归一为
+	// {ok:false, recoverable:true}，保证调用方日志前缀一致（B5：凭证注入原在 try 外，reject 时
+	// callLLM 直接 reject，上游走外层 .catch 输出不一致前缀，如 [pi-rename-session] 而非 [rename-session]）。
+	try {
+		// 1. 凭证（判别联合必须 narrow）：返回 {ok:false} → 提前返回；reject（抛异常）→ 进 catch
+		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(opts.model);
+		if (!auth.ok) {
+			return { ok: false, error: auth.error, recoverable: true };
+		}
+
+		// 2. 调用 completeSimple（字段名经探针⑤对齐：Context{systemPrompt?,messages,tools?},
+		//    SimpleStreamOptions extends StreamOptions{apiKey?,headers?,env?,signal?,maxTokens?,timeoutMs?,sessionId?}）
+		const context: LlmContext = {
+			systemPrompt: opts.systemPrompt,
+			messages: opts.messages,
+			tools: [],
+		};
+		// apiKey/headers/env 来自 auth（即使 undefined 也传，让 completeSimple 用默认）；
+		// signal/maxTokens/timeoutMs/sessionId 条件 spread（不设置则不传，保留 completeSimple 默认）。
+		const options: SimpleStreamOptions = {
+			apiKey: auth.apiKey,
+			headers: auth.headers,
+			env: auth.env,
+			...(opts.signal ? { signal: opts.signal } : {}),
+			...(opts.maxTokens ? { maxTokens: opts.maxTokens } : {}),
+			...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}),
+			...(opts.sessionId ? { sessionId: opts.sessionId } : {}),
+		};
+		const resp = await completeSimple(opts.model, context, options);
+		// G3/C1a：completeSimple 对 error/aborted 也 resolve（带 stopReason，不 reject）。
+		// 归一为 ok:false + stopReason 独立透传（recoverable 统一 true，与 C2b 一致不触发细分）。
+		if (resp.stopReason === "error" || resp.stopReason === "aborted") {
+			const errorText = extractText(resp) || "unknown error";
+			return { ok: false, error: errorText, recoverable: true, stopReason: resp.stopReason };
+		}
+		return { ok: true, content: extractText(resp) };
+	} catch (error) {
+		return { ok: false, error: error instanceof Error ? error.message : String(error), recoverable: true };
+	}
+}

package/src/config.ts

@@ -0,0 +1,180 @@
+/**
+ * 泛型配置读写：getConfigPath + loadConfig<T> + saveConfig + mtime+size 缓存 + 原子写。
+ *
+ * 与 permission/config.ts 的区别：本库是泛型版（pkgName 参数化，normalize 由调用方传），
+ * 不内置任何 schema —— rename-session / permission / scheduler 等 consumer 各自定义 normalize。
+ * 范式（mtime+size 双 key 缓存、原子写 tmp+rename、tmp 失败清理）借鉴 permission/config.ts。
+ *
+ * 路径解析用 pi 导出的 getAgentDir（尊重 PI_CODING_AGENT_DIR 覆盖），禁止自实现 ——
+ * permission/config.ts:18-22 有重复自实现待 P3 清理，本库直接用 pi 导出版。
+ *
+ * ── 热重载契约（consumer 必读） ──
+ * 本库的 loadConfig 提供「读时刷新（pull-based）热重载」：每次调用 statSync 文件 mtime+size，
+ * 变了才重读+重新 normalize，没变返回深拷贝（成本≈一次 metadata stat，不读文件内容）。
+ * 这是框架对 consumer 统一提供的热重载能力——consumer 应在【每次需要配置时直接调 loadConfig】，
+ * 禁止在上层套手动缓存/闭包缓存（如 `let config = loadXxx()` + 手动 refresh 调用点），否则阻断
+ * 读时刷新，导致「同进程内改文件不生效」。
+ * 历史教训：permission 曾用闭包缓存架空了 loadConfig 的读时刷新——tool_call handler 拿闭包
+ * 里的旧 config，传了 refresh 参数却未调用（_refreshConfig 下划线=未用），同一 session 改配置
+ * 文件后下次工具调用仍用旧 config。正确范式见 rename-session（每次 turn_end 直接 load）。
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+/** JSON 序列化缩进格数（permission/config.ts 同款）。 */
+const JSON_INDENT = 2;
+
+// ──────────────────────── 路径 ────────────────────────
+
+/** 配置文件完整路径：<agentDir>/config/<pkgName>-ext-config.json（与 config skill 名 `<简名>-ext-config` 统一）。 */
+export function getConfigPath(pkgName: string): string {
+	return join(getAgentDir(), "config", `${pkgName}-ext-config.json`);
+}
+
+// ──────────────────────── mtime+size 缓存 ────────────────────────
+
+interface CacheEntry<T> {
+	mtimeMs: number;
+	size: number;
+	config: T;
+}
+
+/**
+ * 模块级缓存：path → {mtimeMs, size, config}。单进程多 session 共享读缓存安全（配置只读）。
+ * mtime + size 双 key：防 APFS 等文件系统 mtime 精度截断导致快速连续保存后缓存失效。
+ * 已知 limitation：「同毫秒同字节大小但内容不同」的写入会误命中（概率极低，权衡采用 mtime+size）。
+ */
+const configCache = new Map<string, CacheEntry<unknown>>();
+
+/** 测试用：清空缓存。 */
+export function clearConfigCache(): void {
+	configCache.clear();
+}
+
+/** 深拷贝（防调用方修改返回值污染缓存）。Node 22+ 内置 structuredClone。 */
+function clone<T>(value: T): T {
+	return typeof structuredClone === "function"
+		? structuredClone(value)
+		: (JSON.parse(JSON.stringify(value)) as T);
+}
+
+// ──────────────────────── 加载（带缓存） ────────────────────────
+
+/**
+ * 加载配置，文件未变化时返回缓存（深拷贝，防调用方修改污染缓存）。
+ *
+ * @param pkgName 包名（决定文件路径 <agentDir>/config/<pkgName>.json）
+ * @param defaults 文件缺失/坏 JSON/normalize 失败时的默认值
+ * @param normalize 把 JSON.parse 的 unknown 归一化成 T（调用方负责校验 + 默认值填充）
+ * @param onWarning 非致命问题（解析失败）的警告回调
+ *
+ * 降级：文件不存在 → defaults；坏 JSON / normalize throw → defaults（onWarning 回调）。
+ * 坏文件也更新缓存 mtime+size（缓存 defaults），避免每次重读损坏文件；mtime 变化时缓存自动失效。
+ *
+ * 【热重载契约】本函数自带读时刷新：文件 mtime/size 变化时自动重读。consumer 每次需要配置直接
+ * 调用本函数即可（文件未变时零额外 IO——只 statSync 不读内容），禁止在上层套闭包/手动缓存阻断
+ * 刷新。详见文件头「热重载契约」段。
+ */
+export function loadConfig<T>(
+	pkgName: string,
+	defaults: T,
+	normalize: (raw: unknown) => T,
+	onWarning?: (msg: string) => void,
+): T {
+	const configPath = getConfigPath(pkgName);
+
+	let stat;
+	try {
+		stat = statSync(configPath);
+	} catch {
+		// 文件不存在 / 不可 stat → defaults（不缓存，下次仍尝试读，文件创建后自动生效）
+		return clone(defaults);
+	}
+
+	const cached = configCache.get(configPath) as CacheEntry<T> | undefined;
+	if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+		return clone(cached.config);
+	}
+
+	try {
+		const raw = readFileSync(configPath, "utf-8");
+		const parsed: unknown = JSON.parse(raw);
+		const config = normalize(parsed);
+		configCache.set(configPath, { mtimeMs: stat.mtimeMs, size: stat.size, config });
+		return clone(config);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		onWarning?.(`[llm-shared] Config parse failed at '${configPath}', using default: ${message}`);
+		// 缓存 defaults + 当前 mtime/size，避免每次重读损坏文件（mtime 变化时缓存自动失效）
+		configCache.set(configPath, { mtimeMs: stat.mtimeMs, size: stat.size, config: clone(defaults) });
+		return clone(defaults);
+	}
+}
+
+// ──────────────────────── 保存（原子写） ────────────────────────
+
+/**
+ * 保存配置（原子写：tmp 文件 + rename）。
+ *
+ * @returns 成功 {success:true}；失败 {success:false, error}
+ *
+ * 原子性：writeFileSync(tmp) + renameSync(tmp→target)，rename 是原子的（POSIX/Windows）。
+ * tmp 失败清理（review RK3）：writeFileSync 或 renameSync 抛错时，catch 块 unlinkSync(tmp)
+ * 清理残留 tmp 文件（unlink 本身 try/catch，避免二次抛错）。
+ * 写后立即 statSync 更新缓存（覆盖最常见的「写后读」竞态）。
+ *
+ * Windows 行为说明（探针 4）：renameSync 在目标文件被占用（打开句柄未关闭）时抛 EPERM，
+ * 无 fallback —— catch 路径返回 {success:false} + onWarning + tmp 清理，调用方（配置写入方）
+ * 应视保存失败处理（如保留内存态、下次触发重写）。非致命：配置写入失败不影响运行，
+ * 下次 save 仍会重试。单测见 __tests__/config.test.ts 的 ENOENT/EPERM 用例。
+ */
+export function saveConfig(
+	pkgName: string,
+	config: unknown,
+	onWarning?: (msg: string) => void,
+): { success: boolean; error?: string } {
+	const configPath = getConfigPath(pkgName);
+	const tmpPath = `${configPath}.tmp`;
+	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）
+		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}` };
+	}
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+// @zhushanwen/pi-llm-shared —— 统一 public API 出口。
+// resolve: 模型解析（四形式 selector）
+// call: LLM 调用（completeSimple + 凭证 + 文本提取）
+// config: 泛型配置读写（mtime 缓存 + 原子写）
+export { resolveModel, readEnabledModels, matchGlob, 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/migrate.ts

@@ -0,0 +1,52 @@
+/**
+ * 历史配置路径迁移工具（幂等，过渡性——供 extension session_start hook 调用）。
+ *
+ * 迁移语义：
+ * - 旧路径不存在 → noop
+ * - 旧路径存在 + 新路径不存在 → renameSync 原子搬移
+ * - 旧路径存在 + 新路径已存在 → 删除旧文件（新的是当前配置，旧的是残留副本；pi 运行时只读新路径）
+ * - 失败 → warn 不抛错（best-effort，下次启动重试）
+ *
+ * 调用方在 session_start hook 里用模块级 once flag 防同进程重复触发。
+ * agentDir 由调用方传入（通常 getAgentDir()），便于测试传 tmp dir。
+ *
+ * 设计依据见 docs/extensions/extension-conventions.md §配置路径约定「历史路径迁移」。
+ */
+import { existsSync, mkdirSync, renameSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface MigrationResult {
+	migrated: boolean;
+	/** 新路径已存在时已删除旧文件（清理残留副本），true 表示旧文件被删。 */
+	removedLegacy?: boolean;
+	/** 迁移失败时的错误对象（best-effort，不抛错）。 */
+	error?: unknown;
+}
+
+/**
+ * 迁移单个配置文件：`<agentDir>/<oldRel>` → `<agentDir>/<newRel>`。
+ * 幂等、best-effort，重复调用安全。
+ */
+export function migrateLegacyConfig(agentDir: string, oldRel: string, newRel: string): MigrationResult {
+	const oldPath = join(agentDir, oldRel);
+	if (!existsSync(oldPath)) return { migrated: false };
+
+	const newPath = join(agentDir, newRel);
+	try {
+		mkdirSync(dirname(newPath), { recursive: true });
+		if (existsSync(newPath)) {
+			// 新已存在 = 已迁移过（或用户用新路径），旧的是残留副本——删除清理。
+			// pi 运行时只读新路径，旧文件无用。安全前提：session_start 迁移在 pi 进程内、
+			// 用户主动启动时触发（非 postinstall 开发环境误触发；e112a14fc 场景随 session_start 消除）。
+			unlinkSync(oldPath);
+			console.warn(`[migrate-config] new config already exists, removed legacy file: ${oldPath}`);
+			return { migrated: false, removedLegacy: true };
+		}
+		renameSync(oldPath, newPath);
+		console.warn(`[migrate-config] migrated: ${oldPath} -> ${newPath}`);
+		return { migrated: true };
+	} catch (e) {
+		console.warn(`[migrate-config] migration failed for ${oldPath} -> ${newPath}:`, e);
+		return { migrated: false, error: e };
+	}
+}

package/src/resolve.ts

@@ -0,0 +1,147 @@
+/**
+ * 模型解析：把 ModelSelector（四形式）解析成可用的 Model，或 null（不可用，调用方静默跳过）。
+ *
+ * 设计依据：design.md §3.4 + slice 6 决策。scoped 形式自读 <agentDir>/settings.json 的
+ * enabledModels（string[]，"provider/modelId" 格式可含 * glob），不依赖调用方传入列表 ——
+ * 这样 rename-session / permission 等 consumer 无需各自重复读 settings.json 的逻辑。
+ */
+
+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";
+
+// ──────────────────────── 类型 ────────────────────────
+
+/**
+ * 模型选择器（四形式）。
+ * - 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");
+}
+
+// ──────────────────────── 模型解析 ────────────────────────
+
+/** "provider/modelId" → 拆分（用 indexOf 而非 split，modelId 理论上可含 /，取首个 / 作分隔）。 */
+function parseRef(ref: string): { provider: string; modelId: string } | null {
+	const idx = ref.indexOf("/");
+	if (idx <= 0 || idx >= ref.length - 1) return null; // 缺 / 或前后为空
+	return { provider: ref.slice(0, idx), modelId: ref.slice(idx + 1) };
+}
+
+/** ref 精确匹配：find 命中 + hasConfiguredAuth。任一失败返回 null（静默降级）。 */
+function resolveRef(ctx: ExtensionContext, ref: string): Model<Api> | null {
+	const parsed = parseRef(ref);
+	if (!parsed) return null;
+	const model = ctx.modelRegistry.find(parsed.provider, parsed.modelId);
+	if (!model) return null;
+	if (!ctx.modelRegistry.hasConfiguredAuth(model)) return 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 = 不可用，调用方静默跳过（不抛错）。
+ *
+ * 走 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"
+}