@zhushanwen/pi-llm-shared 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-llm-shared",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Shared LLM invocation library for Pi extensions — model resolution (ref exact only), LLM calling (completeSimple), and config read/write with mtime+size caching. Shared library, not a Pi extension.",
   "type": "module",
   "main": "src/index.ts",
@@ -17,8 +17,9 @@
     "src/"
   ],
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.4.1",
-    "@zhushanwen/pi-file-lock": "0.2.1"
+    "@zhushanwen/pi-extension-logger": "0.6.0",
+    "@zhushanwen/pi-ext-guards": "0.4.0",
+    "@zhushanwen/pi-file-lock": "0.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.4",

package/src/__tests__/call.test.ts

@@ -3,7 +3,7 @@ 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";
+import { callLLM, extractText, joinTextBlocks } from "../call.ts";
 
 // mock completeSimple —— call.ts 顶层静态 import 会拿到此 mock（探针①已验证静态 import 机制可行，
 // 此处验证 callLLM 逻辑：凭证 narrow / options 构造 / 文本提取 / 错误归一化）。
@@ -281,3 +281,41 @@ describe("extractText", () => {
 		expect(extractText({ content: [] })).toBe("");
 	});
 });
+
+describe("joinTextBlocks（unknown 安全内核，D7）", () => {
+	it("text block 过滤拼接：只取 type==='text'，join(' ')，不 trim", () => {
+		expect(
+			joinTextBlocks([
+				{ type: "text", text: "  a" },
+				{ type: "thinking", text: "ignored" },
+				{ type: "text", text: "b  " },
+			]),
+		).toBe("  a b  ");
+	});
+
+	it("非 text block（thinking / tool_call）忽略", () => {
+		expect(joinTextBlocks([{ type: "thinking", text: "x" }, { type: "tool_call" }])).toBe("");
+	});
+
+	it("text 字段缺失的 text block 按 '' 拼接", () => {
+		expect(joinTextBlocks([{ type: "text" }, { type: "text", text: "x" }])).toBe(" x");
+	});
+
+	it("空数组 → ''", () => {
+		expect(joinTextBlocks([])).toBe("");
+	});
+
+	it.each([
+		["undefined", undefined],
+		["null", null],
+		["字符串", "hello"],
+		["数字", 42],
+		["单个 block 对象（非数组）", { type: "text", text: "x" }],
+	])("非数组输入 %s → 安全返回 ''（不 throw）", (_label, raw) => {
+		expect(joinTextBlocks(raw)).toBe("");
+	});
+
+	it("数组内非法元素（null / 非 block 对象）被过滤，不 throw", () => {
+		expect(joinTextBlocks([null, 42, { type: "text", text: "kept" }])).toBe("kept");
+	});
+});

package/src/__tests__/config.test.ts

@@ -21,7 +21,7 @@ vi.mock("@zhushanwen/pi-extension-logger", () => ({
 // 用 vi.mock 包装 readFileSync/renameSync/statSync/unlinkSync（默认走 actual，
 // 个别 test override），其他 fs 操作（writeFileSync/existsSync/mkdirSync...）原样
 // 透传 actual。statSync/unlinkSync 供 U4 logger.warn 留痕用例 override。
-// 注意：proper-lockfile（withFileLockSync 内部）走 graceful-fs，不受本 mock 影响。
+// 注意：withFileLockSync 内部为自实现 mkdir-lock（lock-core.ts，零依赖直用 node:fs，非 proper-lockfile）；本 mock 默认透传 actual，锁行为不受影响。
 vi.mock("node:fs", async (importOriginal) => {
 	const actual = await importOriginal() as typeof import("node:fs");
 	return {

package/src/__tests__/resolve.test.ts

@@ -2,7 +2,7 @@ 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";
+import { isThinkingLevel, normalizeModelSelector, parseModelRef, resolveModel } from "../resolve.ts";
 
 /** 构造最小 Model（cast 绕过必填字段，单测只关心 provider/id）。 */
 function makeModel(provider: string, id: string): Model<Api> {
@@ -62,3 +62,87 @@ describe("resolveModel（仅 ref 精确指定）", () => {
 		expect(find).not.toHaveBeenCalled();
 	});
 });
+
+describe("isThinkingLevel（V2 七值钉值，与 pi-ai ModelThinkingLevel 联合一致）", () => {
+	it.each(["off", "minimal", "low", "medium", "high", "xhigh", "max"])(
+		"合法值 %j → true",
+		(level) => {
+			expect(isThinkingLevel(level)).toBe(true);
+		},
+	);
+
+	it.each([
+		["未知档位 ultra", "ultra"],
+		["空串", ""],
+		["大小写不符 OFF", "OFF"],
+		["undefined", undefined],
+		["null", null],
+		["数字", 1],
+		["对象", {}],
+		["数组（元素为合法值也不接受）", ["high"]],
+	])("非法值 %s → false", (_label, raw) => {
+		expect(isThinkingLevel(raw)).toBe(false);
+	});
+
+	it("类型收窄：合法值通过谓词后可赋给 ModelThinkingLevel", () => {
+		const raw: unknown = "xhigh";
+		if (isThinkingLevel(raw)) {
+			const narrowed: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" = raw;
+			expect(narrowed).toBe("xhigh");
+		} else {
+			throw new Error("xhigh 应通过谓词");
+		}
+	});
+});
+
+describe("parseModelRef（V2 五形态钉值，ext-simplify-18 D4）", () => {
+	it("合法 ref → {provider, modelId}", () => {
+		expect(parseModelRef("anthropic/claude-5.3")).toEqual({ provider: "anthropic", modelId: "claude-5.3" });
+	});
+
+	it("缺斜杠（'foo'）→ null", () => {
+		expect(parseModelRef("foo")).toBeNull();
+	});
+
+	it("尾空 modelId（'provider/'）→ null", () => {
+		expect(parseModelRef("provider/")).toBeNull();
+	});
+
+	it("首空 provider（'/model'）→ null", () => {
+		expect(parseModelRef("/model")).toBeNull();
+	});
+
+	it("modelId 含斜杠（'a/b/c'）→ 取首个 / 分隔 → {provider:'a', modelId:'b/c'}", () => {
+		expect(parseModelRef("a/b/c")).toEqual({ provider: "a", modelId: "b/c" });
+	});
+});
+
+describe("normalizeModelSelector", () => {
+	it("合法 ref selector → 通过（仅取 type/ref 两字段）", () => {
+		expect(normalizeModelSelector({ type: "ref", ref: "deepseek-router/deepseek-chat" })).toEqual({
+			type: "ref",
+			ref: "deepseek-router/deepseek-chat",
+		});
+	});
+
+	it("多余字段不透传（构造干净对象）", () => {
+		expect(normalizeModelSelector({ type: "ref", ref: "a/b", extra: 1 })).toEqual({
+			type: "ref",
+			ref: "a/b",
+		});
+	});
+
+	it.each([
+		["字符串", "ref"],
+		["数字", 42],
+		["null", null],
+		["undefined", undefined],
+		["数组", [{ type: "ref", ref: "a/b" }]],
+		["type 非 ref", { type: "available" }],
+		["ref 非字符串", { type: "ref", ref: 123 }],
+		["缺 ref", { type: "ref" }],
+		["空对象", {}],
+	])("%s → null", (_label, raw) => {
+		expect(normalizeModelSelector(raw)).toBeNull();
+	});
+});

package/src/call.ts

@@ -20,6 +20,7 @@ import type {
 } from "@earendil-works/pi-ai/compat";
 import type { Api, Message, Model, ModelThinkingLevel, Usage } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isRecord, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 // ──────────────────────── 类型 ────────────────────────
 
@@ -61,20 +62,37 @@ export type CallLLMResult =
 
 // ──────────────────────── 文本提取 ────────────────────────
 
+/** 类型谓词：content 数组元素是否为 text block（text 字段可缺失，拼接时按 "" 处理）。 */
+function isTextBlock(block: unknown): block is { type: string; text?: string } {
+	return isRecord(block) && block.type === "text";
+}
+
+/**
+ * unknown 安全的 text block 拼接内核：过滤 `type==="text"` 的 block 并 `join(" ")`（不 trim）。
+ *
+ * 非数组输入（含 undefined / 非法 block 元素）安全返回 ""，供消费方对任意 LLM 响应/会话
+ * entry 形状直接调用（ext-simplify-17 D7——rename-session 等包的本地 joinTextBlocks 副本收敛于此）。
+ * trim 是调用方策略（extractText trim，其余调用方自定），内核不含。
+ */
+export function joinTextBlocks(content: unknown): string {
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter(isTextBlock)
+		.map((block) => block.text ?? "")
+		.join(" ");
+}
+
 /**
  * 从 AssistantMessage.content 提取所有 text block 拼接并 trim。
  *
  * 参数用结构类型（不直接依赖 AssistantMessage），便于测试 mock —— 调用方传 completeSimple 返回值即可。
  * 无 text block（如纯 ThinkingContent / ToolCall）→ 返回 ""。
+ * trim 契约不变：内部委托 joinTextBlocks 内核再 trim（ext-simplify-17 D7，行为等价由等价探针验证）。
  */
 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();
+	return joinTextBlocks(resp.content).trim();
 }
 
 // ──────────────────────── 调用 ────────────────────────
@@ -143,6 +161,6 @@ export async function callLLM(
 			...(resp.usage ? { usage: resp.usage } : {}),
 		};
 	} catch (error) {
-		return { ok: false, error: error instanceof Error ? error.message : String(error) };
+		return { ok: false, error: toErrorMessage(error) };
 	}
 }

package/src/config.ts

@@ -25,6 +25,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync,
 import { dirname, join } from "node:path";
 
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { withFileLockSync } from "@zhushanwen/pi-file-lock";
 
@@ -112,7 +113,7 @@ export function loadConfig<T>(
 		configCache.set(configPath, { mtimeMs: stat.mtimeMs, size: stat.size, config });
 		return clone(config);
 	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
+		const message = toErrorMessage(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) });
@@ -184,7 +185,7 @@ export function saveConfig(
 				});
 			} catch (statErr) {
 				// stat 失败不影响保存成功；缓存下次 load 时会重读
-				logger.warn("saveConfig stat after write failed", { detail: { err: statErr instanceof Error ? statErr.message : String(statErr) } });
+				logger.warn("saveConfig stat after write failed", { detail: { err: toErrorMessage(statErr) } });
 			}
 
 			return { success: true };
@@ -194,9 +195,9 @@ export function saveConfig(
 				if (existsSync(tmpPath)) unlinkSync(tmpPath);
 			} catch (cleanupErr) {
 				// tmp 清理失败不能阻塞保存失败的返回；记录原因
-				logger.warn("saveConfig tmp cleanup failed", { detail: { err: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr) } });
+				logger.warn("saveConfig tmp cleanup failed", { detail: { err: toErrorMessage(cleanupErr) } });
 			}
-			const message = error instanceof Error ? error.message : String(error);
+			const message = toErrorMessage(error);
 			onWarning?.(`[llm-shared] Failed to save config at '${configPath}': ${message}`);
 			return { success: false, error: `Failed to save config at '${configPath}': ${message}` };
 		}
@@ -206,7 +207,7 @@ export function saveConfig(
 		return withFileLockSync(configPath, writeLocked);
 	} catch (lockErr) {
 		// 锁获取失败（ELOCKED 预算耗尽等）：不降级无锁写（见 docstring），按保存失败返回
-		const message = lockErr instanceof Error ? lockErr.message : String(lockErr);
+		const message = toErrorMessage(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,15 @@
 // @zhushanwen/pi-llm-shared —— 统一 public API 出口。
-// resolve: 模型解析（仅 ref 精确指定）
+// resolve: 模型解析（仅 ref 精确指定）+ selector 归一化 + thinking 级别校验
 // call: LLM 调用（completeSimple + 凭证 + 文本提取）
 // config: 泛型配置读写（mtime+size 双 key 缓存 + 原子写）
-export { resolveModel, getCurrentModelId, type ModelSelector } from "./resolve.ts";
-export { callLLM, type CallLLMOptions, type CallLLMResult } from "./call.ts";
+export {
+	resolveModel,
+	parseModelRef,
+	getCurrentModelId,
+	normalizeModelSelector,
+	isThinkingLevel,
+	type ModelSelector,
+} from "./resolve.ts";
+export { callLLM, joinTextBlocks, extractText, type CallLLMOptions, type CallLLMResult } from "./call.ts";
 export { getConfigPath, loadConfig, saveConfig, clearConfigCache } from "./config.ts";
-export { migrateLegacyConfig, type MigrationResult } from "./migrate.ts";
+export { migrateLegacyConfig } from "./migrate.ts";

package/src/resolve.ts

@@ -6,8 +6,9 @@
  * 不通过 ModelSelector 表达非精确语义。
  */
 
-import type { Api, Model } from "@earendil-works/pi-ai";
+import type { Api, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "@zhushanwen/pi-ext-guards";
 
 // ──────────────────────── 类型 ────────────────────────
 
@@ -17,10 +18,56 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
  */
 export type ModelSelector = { type: "ref"; ref: string };
 
+// ──────────────────────── selector 归一化 ────────────────────────
+
+/**
+ * 从 unknown（如 JSON.parse 的配置文件内容）恢复 ModelSelector，非法形态返回 null。
+ *
+ * 只接受 `{ type: "ref", ref: string }`（仅取这两个字段，多余字段不透传）；非对象 /
+ * 数组 / type 非 "ref" / ref 非字符串 → null，调用方自行决定回退（如 `?? 默认值`）。
+ * canonical 来自 ext-simplify-17 D6——rename-session / smart-context 两份同构本地
+ * 副本的公共核心谓词（排数组严版，与 ext-guards isRecord 语义一致）。
+ */
+export function normalizeModelSelector(raw: unknown): ModelSelector | null {
+	if (!isRecord(raw)) return null;
+	if (raw.type === "ref" && typeof raw.ref === "string") {
+		return { type: "ref", ref: raw.ref };
+	}
+	return null;
+}
+
+// ──────────────────────── thinking level 校验 ────────────────────────
+
+/**
+ * 合法 thinking 级别清单（与 pi-ai ModelThinkingLevel 七值联合一致；normalize 校验用）。
+ * Set 免 as 断言。
+ */
+const THINKING_LEVELS: ReadonlySet<string> = new Set([
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max",
+]);
+
+/**
+ * 类型谓词：unknown 是否为合法 thinking 级别（配置 normalize 校验用，单点断言）。
+ * Set.has 运行时兜底 + 类型收窄，调用方无需再断言。
+ *
+ * extensions 侧唯一副本（ext-simplify-17 D5）；与 packages/subagent-core 的
+ * THINKING_ORDER（src/shared/model-ref.ts）注释互指，不建跨包 import（分层约束：
+ * universal 角色包禁 import subagent-core，反向则 shared 库依赖 packages/ 破坏分层）。
+ */
+export function isThinkingLevel(raw: unknown): raw is ModelThinkingLevel {
+	return typeof raw === "string" && THINKING_LEVELS.has(raw);
+}
+
 // ──────────────────────── 模型解析 ────────────────────────
 
 /** "provider/modelId" → 拆分（用 indexOf 而非 split，modelId 理论上可含 /，取首个 / 作分隔）。 */
-function parseRef(ref: string): { provider: string; modelId: string } | null {
+export function parseModelRef(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) };
@@ -28,7 +75,7 @@ function parseRef(ref: string): { provider: string; modelId: string } | null {
 
 /** ref 精确匹配：find 命中 + hasConfiguredAuth。任一失败返回 null（静默降级）。 */
 function resolveRef(ctx: ExtensionContext, ref: string): Model<Api> | null {
-	const parsed = parseRef(ref);
+	const parsed = parseModelRef(ref);
 	if (!parsed) return null;
 	const model = ctx.modelRegistry.find(parsed.provider, parsed.modelId);
 	if (!model) return null;