@zhushanwen/pi-permission 0.0.1

package/src/classifier/classifier.ts

@@ -0,0 +1,242 @@
+/**
+ * AI Classifier 主流程（I4 classifyRisk）
+ *
+ * 流程：resolveModel → 构造 Model<Api> + Context + Options → streamSimple →
+ *       检查 stopReason → 解析文本 → ClassifierResult。所有失败路径返回 fail-closed ask。
+ *
+ * 关键设计：
+ *   - 依赖注入 ClassifierDeps（streamSimple 注入，便于测试 mock，不直接 import）
+ *   - 超时/中止：传 provider 原生 timeoutMs + signal 给 streamSimple；外层再叠
+ *     Promise.race 兜底（防止 provider 不支持 timeoutMs 时 result() 永挂）
+ *   - G3 修正：EventStream.result() 只 resolve 不 reject，error/aborted 也 resolve
+ *     （带 stopReason）。因此 classifyRisk 在取 text 前显式检查 stopReason，
+ *     error/aborted → fallback ask
+ *   - fail-closed：timeout / 抛错 / 解析失败 / 无可用模型 → 一律 ask
+ */
+
+import type {
+	Api,
+	AssistantMessageEventStream,
+	Context,
+	Model,
+	SimpleStreamOptions,
+} from "@earendil-works/pi-ai";
+
+import type {
+	ClassifierConfig,
+	ClassifierResult,
+	ToolInvocationContext,
+} from "../types.js";
+import { parseClassifierResponse } from "./json-parser.js";
+import { type ResolvedModel } from "./model-resolver.js";
+import { buildClassifierUserPrompt, CLASSIFIER_SYSTEM_PROMPT } from "./prompt.js";
+
+// ──────────────────────── fail-closed fallback ────────────────────────
+
+/** 秒→毫秒换算系数（用于 timeout 字段转 provider 原生 timeoutMs） */
+const MILLIS_PER_SECOND = 1000;
+
+/** classifyRisk 所有失败路径的统一 fallback（fail-closed ask） */
+const CLASSIFY_FALLBACK_RESULT: ClassifierResult = {
+	outcome: "ask",
+	risk_level: "medium",
+	reasoning: "classifier unavailable",
+	confidence: 0,
+};
+
+// ──────────────────────── 依赖注入 ────────────────────────
+
+/**
+ * Classifier 的外部依赖（DI 便于测试 mock）。
+ *
+ * - resolveModel：把 ClassifierConfig.model 解析为 ResolvedModel（或 null）
+ * - streamSimple：pi-ai 的流式调用（同步返回 EventStream，result() 异步）
+ * - onLog：可选日志回调（调试/审计）
+ *
+ * 命名锁定为 streamSimple（G7：不是 callStreamSimple）。
+ */
+export interface ClassifierDeps {
+	resolveModel: (config: ClassifierConfig) => ResolvedModel | null;
+	streamSimple: (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+	onLog?: (msg: string) => void;
+}
+
+// ──────────────────────── AssistantMessage 最小子集 ────────────────────────
+
+/** AssistantMessage 的最小子集（只取 stopReason + content，避免泛型/依赖膨胀） */
+interface AssistantMessageLike {
+	stopReason?: string;
+	content?: { type: string; text?: string }[];
+}
+
+// ──────────────────────── 辅助：构造 Model<Api> ────────────────────────
+
+/**
+ * 从 ResolvedModel 构造 pi-ai 的 Model<Api>。
+ *
+ * ResolvedModel.api 是字符串（来自 models.json），断言为 Api 联合类型。
+ * cost 字段携带 input 真实值（G4），其余填 0（classifier 不关心 token 成本计量）。
+ */
+function buildModel(resolved: ResolvedModel): Model<Api> {
+	const inputCost = typeof resolved.inputCost === "number" ? resolved.inputCost : 0;
+	return {
+		id: resolved.id,
+		name: resolved.name ?? resolved.id,
+		api: resolved.api as Api,
+		provider: resolved.provider,
+		// G4：baseUrl 用真实值（无则空串，provider 内部会补默认）
+		baseUrl: resolved.baseUrl ?? "",
+		reasoning: false,
+		input: ["text"],
+		cost: { input: inputCost, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 128000,
+		maxTokens: 16384,
+	};
+}
+
+/** 构造无 transcript 的 Context（单轮 user message） */
+function buildContext(ctx: ToolInvocationContext): Context {
+	return {
+		systemPrompt: CLASSIFIER_SYSTEM_PROMPT,
+		messages: [
+			{
+				role: "user",
+				content: [{ type: "text", text: buildClassifierUserPrompt(ctx) }],
+				timestamp: Date.now(),
+			},
+		],
+	};
+}
+
+/** 从 AssistantMessage.content 抽取纯文本（拼接所有 text 块） */
+function extractAssistantText(content: { type: string; text?: string }[]): string {
+	return content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text" && typeof c.text === "string")
+		.map((c) => c.text)
+		.join("");
+}
+
+// ──────────────────────── 外层超时（兜底） ────────────────────────
+
+/**
+ * 给 result() 叠加外层超时（毫秒）+ abort 信号。
+ *
+ * 防御 provider 不支持 timeoutMs 时 result() 永挂。result() 自身只 resolve 不 reject，
+ * 故 race 不会因 provider 错误提前 reject——错误走 stopReason 路径。
+ */
+function raceResultWithDeadline(
+	resultPromise: Promise<AssistantMessageLike>,
+	timeoutMs: number | undefined,
+	signal: AbortSignal | undefined,
+): Promise<{ kind: "ok"; message: AssistantMessageLike } | { kind: "timeout" } | { kind: "aborted" }> {
+	type Outcome = { kind: "ok"; message: AssistantMessageLike } | { kind: "timeout" } | { kind: "aborted" };
+	const racers: Promise<Outcome>[] = [
+		resultPromise.then((message) => ({ kind: "ok" as const, message })),
+	];
+
+	let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+	if (timeoutMs !== undefined && timeoutMs > 0) {
+		racers.push(
+			new Promise<Outcome>((resolve) => {
+				timeoutHandle = setTimeout(() => resolve({ kind: "timeout" }), timeoutMs);
+			}),
+		);
+	}
+	if (signal !== undefined) {
+		if (signal.aborted) {
+			return Promise.resolve({ kind: "aborted" });
+		}
+		racers.push(
+			new Promise<Outcome>((resolve) => {
+				signal.addEventListener("abort", () => resolve({ kind: "aborted" }), { once: true });
+			}),
+		);
+	}
+
+	return Promise.race(racers).finally(() => {
+		if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
+	});
+}
+
+// ──────────────────────── createClassifier ────────────────────────
+
+/**
+ * 创建 classifier 实例（工厂，注入 deps）。
+ *
+ * 返回 classifyRisk 主函数。
+ */
+export function createClassifier(deps: ClassifierDeps): {
+	classifyRisk: (ctx: ToolInvocationContext, config: ClassifierConfig, signal?: AbortSignal) => Promise<ClassifierResult>;
+} {
+	const { resolveModel, streamSimple, onLog } = deps;
+
+	async function classifyRisk(
+		ctx: ToolInvocationContext,
+		config: ClassifierConfig,
+		signal?: AbortSignal,
+	): Promise<ClassifierResult> {
+		// 1. 解析模型；无可用模型 → fail-closed
+		const resolved = resolveModel(config);
+		if (resolved === null) {
+			onLog?.("[pi-permission] classifier: no model resolved, returning fallback");
+			return { ...CLASSIFY_FALLBACK_RESULT };
+		}
+
+		// 2. 构造 model/context/options（timeout 秒→毫秒，传 provider 原生 timeoutMs + signal + apiKey）
+		const model = buildModel(resolved);
+		const context = buildContext(ctx);
+		const timeoutMs = config.timeout > 0 ? config.timeout * MILLIS_PER_SECOND : undefined;
+		const options: SimpleStreamOptions = {
+			...(timeoutMs !== undefined ? { timeoutMs } : {}),
+			...(signal !== undefined ? { signal } : {}),
+			...(resolved.apiKey !== undefined ? { apiKey: resolved.apiKey } : {}),
+		};
+
+		// 3. 调用 streamSimple（同步返回 EventStream）。包裹 try/catch 防同步抛错。
+		let stream: AssistantMessageEventStream;
+		try {
+			stream = streamSimple(model, context, options);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			onLog?.(`[pi-permission] classifier: streamSimple threw: ${message}`);
+			return { ...CLASSIFY_FALLBACK_RESULT };
+		}
+
+		// 4. 等待 result() + 外层超时/中止兜底。
+		//    G3：result() 只 resolve 不 reject，error/aborted 也 resolve（带 stopReason）。
+		const resultPromise = stream.result() as Promise<AssistantMessageLike>;
+		let settled: { kind: "ok"; message: AssistantMessageLike } | { kind: "timeout" } | { kind: "aborted" };
+		try {
+			settled = await raceResultWithDeadline(resultPromise, timeoutMs, signal);
+		} catch (error) {
+			// result() 理论上不 reject，但防御性 catch（fail-closed）
+			const message = error instanceof Error ? error.message : String(error);
+			onLog?.(`[pi-permission] classifier: result race threw: ${message}`);
+			return { ...CLASSIFY_FALLBACK_RESULT };
+		}
+
+		if (settled.kind === "timeout") {
+			onLog?.(`[pi-permission] classifier: timed out after ${timeoutMs}ms`);
+			return { ...CLASSIFY_FALLBACK_RESULT };
+		}
+		if (settled.kind === "aborted") {
+			onLog?.(`[pi-permission] classifier: aborted by signal`);
+			return { ...CLASSIFY_FALLBACK_RESULT };
+		}
+
+		// 5. G3 关键修正：显式检查 stopReason。error/aborted → fallback（不能当成功）
+		const message = settled.message;
+		if (message?.stopReason === "error" || message?.stopReason === "aborted") {
+			const errorDetail = message?.content?.[0]?.text ?? "unknown error";
+			onLog?.(`[pi-permission] classifier: stream stopReason=${message.stopReason}, error=${errorDetail}, returning fallback`);
+			return { ...CLASSIFY_FALLBACK_RESULT };
+		}
+
+		// 6. 提取文本 → 三层容错解析
+		const content = Array.isArray(message?.content) ? (message.content as { type: string; text?: string }[]) : [];
+		const text = extractAssistantText(content);
+		return parseClassifierResponse(text);
+	}
+
+	return { classifyRisk };
+}

package/src/classifier/index.ts

@@ -0,0 +1,28 @@
+/**
+ * AI Classifier barrel（层 3 入口）
+ *
+ * 对外暴露 createClassifier + ClassifierDeps + prompt/json-parser/model-resolver 辅助 API。
+ * ClassifierResult / ClassifierConfig / ToolInvocationContext 从 ../types.js re-export，
+ * 单一类型来源（types.ts）。
+ */
+
+export type { ClassifierDeps } from "./classifier.js";
+export { createClassifier } from "./classifier.js";
+export { PARSE_FALLBACK_RESULT,parseClassifierResponse } from "./json-parser.js";
+export type { ResolvedModel, ResolvedModelEntry } from "./model-resolver.js";
+export {
+	agentDir,
+	findCheapestModel,
+	flattenModels,
+	loadModelsJson,
+	resolveClassifierModel,
+} from "./model-resolver.js";
+export { buildClassifierUserPrompt,CLASSIFIER_SYSTEM_PROMPT } from "./prompt.js";
+
+// 类型 re-export（单一来源：types.ts）
+export type {
+	ClassifierConfig,
+	ClassifierResult,
+	RiskLevel,
+	ToolInvocationContext,
+} from "../types.js";

package/src/classifier/json-parser.ts

@@ -0,0 +1,127 @@
+/**
+ * AI Classifier 输出解析（三层容错 → ClassifierResult）
+ *
+ * 对应 I4 classifyRisk 的「LLM 响应 → 结构化结果」环节。
+ *
+ * 三层容错：
+ *   1. 正则提取首个 JSON 对象（贪婪匹配）
+ *   2. JSON.parse（try/catch）
+ *   3. 字段验证（枚举 + 数值）
+ *
+ * 任意一层失败 → 返回 fail-closed fallback（outcome=ask, risk_level=medium, confidence=0）。
+ */
+
+import type { ClassifierResult, PermissionAction, RiskLevel } from "../types.js";
+
+/** 解析失败时的 fail-closed fallback（统一 medium/ask，绝不静默放行） */
+export const PARSE_FALLBACK_RESULT: ClassifierResult = {
+	outcome: "ask",
+	risk_level: "medium",
+	reasoning: "classifier output parse failed",
+	confidence: 0,
+};
+
+const VALID_ACTIONS: readonly PermissionAction[] = ["allow", "deny", "ask"];
+const VALID_RISKS: readonly RiskLevel[] = ["low", "medium", "high"];
+
+/**
+ * 提取首个 JSON 对象子串。
+ *
+ * 用贪婪正则 `/\{[\s\S]*\}/` 取最后一个 `}` 为止的子串。
+ *
+ * 已知 limitation（G5）：当 LLM 输出多个独立 JSON 对象（如 `{"a":1} {"b":2}`）时，
+ * 贪婪匹配会吞掉中间空格得到 `{...}{...}`，JSON.parse 失败 → fallback。
+ * 实际分类器场景下 LLM 只应返回单个对象，此权衡换取「单对象 + 尾随文本」的鲁棒性。
+ */
+function extractJsonObject(text: string): string | null {
+	const match = text.match(/\{[\s\S]*\}/);
+	return match ? match[0] : null;
+}
+
+function isStringRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** 验证并提取 outcome（容忍大小写） */
+function readAction(raw: unknown): PermissionAction | null {
+	if (typeof raw !== "string") return null;
+	const lower = raw.toLowerCase();
+	return VALID_ACTIONS.includes(lower as PermissionAction) ? (lower as PermissionAction) : null;
+}
+
+/** 验证并提取 risk_level（容忍大小写） */
+function readRiskLevel(raw: unknown): RiskLevel | null {
+	if (typeof raw !== "string") return null;
+	const lower = raw.toLowerCase();
+	return VALID_RISKS.includes(lower as RiskLevel) ? (lower as RiskLevel) : null;
+}
+
+/**
+ * 验证并提取 confidence：必须是有限数字，clamp 到 [0,1]。
+ *
+ * 接受字符串数字（LLM 偶发返回 `"0.8"`），拒绝 NaN/Infinity/非数字。
+ */
+function readConfidence(raw: unknown): number | null {
+	let num: number;
+	if (typeof raw === "number") {
+		num = raw;
+	} else if (typeof raw === "string" && raw.trim().length > 0) {
+		num = Number(raw);
+	} else {
+		return null;
+	}
+	if (!Number.isFinite(num)) return null;
+	if (num < 0) num = 0;
+	if (num > 1) num = 1;
+	return num;
+}
+
+/** 兼容 LLM 偶发把 reasoning 写成 reason（取先存在者） */
+function readReasoning(raw: unknown): string {
+	if (typeof raw === "string" && raw.length > 0) return raw;
+	return PARSE_FALLBACK_RESULT.reasoning;
+}
+
+/**
+ * 解析 classifier LLM 输出文本 → ClassifierResult。
+ *
+ * @param text LLM 返回的原始文本（可能含 markdown code fence / 前后 prose）
+ * @returns 始终返回 ClassifierResult；解析失败返回 PARSE_FALLBACK_RESULT（fail-closed ask）
+ */
+export function parseClassifierResponse(text: string): ClassifierResult {
+	if (typeof text !== "string" || text.length === 0) {
+		return { ...PARSE_FALLBACK_RESULT };
+	}
+
+	const jsonStr = extractJsonObject(text);
+	if (jsonStr === null) {
+		return { ...PARSE_FALLBACK_RESULT };
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(jsonStr);
+	} catch {
+		return { ...PARSE_FALLBACK_RESULT };
+	}
+
+	if (!isStringRecord(parsed)) {
+		return { ...PARSE_FALLBACK_RESULT };
+	}
+
+	const outcome = readAction(parsed.outcome);
+	const risk_level = readRiskLevel(parsed.risk_level);
+	const confidence = readConfidence(parsed.confidence ?? parsed.score);
+
+	// 三个核心字段必须全部有效；缺任一即 fail-closed
+	if (outcome === null || risk_level === null || confidence === null) {
+		return { ...PARSE_FALLBACK_RESULT };
+	}
+
+	return {
+		outcome,
+		risk_level,
+		reasoning: readReasoning(parsed.reasoning ?? parsed.reason),
+		confidence,
+	};
+}

package/src/classifier/model-resolver.ts

@@ -0,0 +1,295 @@
+/**
+ * Classifier 模型解析（model='auto' → 最便宜可用模型）
+ *
+ * 移植自 pi-coding-agent 的 ModelRegistry 思路，但只读 models.json（不刷新 OAuth、
+ * 不合并内置模型），保持轻量。核心：
+ *   - agentDir()：解析 agent 根目录（与 config.ts 同逻辑，G2 自实现，不依赖未导出的 getAgentDir）
+ *   - loadModelsJson()：读 <agentDir>/models.json，含 onWarning 回调（G6）
+ *   - findCheapestModel()：拍平 providers → 过滤 hasApiKey → 按 input cost 升序
+ *   - resolveClassifierModel()：'auto' / 'provider/model-id' 两路解析
+ *
+ * 不直接 import pi-ai 的 Model 类型用于返回（ResolvedModel 只携带构造 Model<Api> 必需的字段，
+ * 避免 here-stringing 一个完整 Model<Api>——api 是字符串联合类型，跨 provider 边界难捏造）。
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// ──────────────────────── agentDir（G2 自实现） ────────────────────────
+
+/**
+ * 解析 agent 根目录。
+ *
+ * 与 config.ts 的 getAgentDir 逻辑一致（env override 优先，否则 ~/.pi/agent），
+ * 但此处显式 export 供 classifier 子模块复用——config.ts 的 getAgentDir 未导出。
+ */
+export function agentDir(): string {
+	const override = process.env.PI_CODING_AGENT_DIR?.trim();
+	if (override) return override;
+	return join(homedir(), ".pi", "agent");
+}
+
+// ──────────────────────── models.json schema（最小子集） ────────────────────────
+
+/** 单个 model 的 cost 结构（与 pi-ai Model.cost 同形） */
+interface ModelCost {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+}
+
+/** models.json 中单个 model 定义的最小子集（参考 pi-coding-agent parseModels） */
+interface ModelsJsonModelDef {
+	id: string;
+	name?: string;
+	api?: string;
+	baseUrl?: string;
+	reasoning?: boolean;
+	input?: ("text" | "image")[];
+	cost?: ModelCost;
+	contextWindow?: number;
+	maxTokens?: number;
+}
+
+/** models.json 中 provider 定义的最小子集 */
+interface ModelsJsonProviderDef {
+	name?: string;
+	baseUrl?: string;
+	apiKey?: string;
+	api?: string;
+	models?: ModelsJsonModelDef[];
+}
+
+/** models.json 顶层结构 */
+interface ModelsJsonFile {
+	providers?: Record<string, ModelsJsonProviderDef>;
+}
+
+/**
+ * 解析后的「扁平 model 条目」：附带其 provider 名 + 是否有 apiKey（auth 可用）。
+ *
+ * 这是 findCheapestModel / resolveClassifierModel 的中间表示，避免直接构造
+ * pi-ai Model<Api>（api 联合类型难以跨 provider 安全构造）。
+ */
+export interface ResolvedModelEntry {
+	provider: string;
+	id: string;
+	name: string;
+	api: string;
+	baseUrl?: string;
+	cost: ModelCost;
+	/** 该 provider 在 models.json 是否配置了 apiKey（auth 可用） */
+	hasApiKey: boolean;
+	/** 该 provider 的 apiKey（用于 streamSimple 调用） */
+	apiKey?: string;
+}
+
+// ──────────────────────── loadModelsJson ────────────────────────
+
+/**
+ * 读取并解析 models.json。
+ *
+ * @param onWarning 非致命问题（文件缺失/解析失败）的警告回调；不抛错（fail-closed：返回 null）
+ * @returns 解析后的 ModelsJsonFile；文件不存在或解析失败返回 null
+ *
+ * G6：显式 onWarning 参数，让调用方决定如何上报（console.warn / telemetry / 静默）。
+ */
+export function loadModelsJson(
+	onWarning?: (msg: string) => void,
+	filePath?: string,
+): ModelsJsonFile | null {
+	const path = filePath ?? join(agentDir(), "models.json");
+	if (!existsSync(path)) {
+		return null;
+	}
+	try {
+		const raw = readFileSync(path, "utf-8");
+		const parsed: unknown = JSON.parse(raw);
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+			onWarning?.(`[pi-permission] models.json root is not an object: ${path}`);
+			return null;
+		}
+		return parsed as ModelsJsonFile;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		onWarning?.(`[pi-permission] Failed to parse models.json at '${path}': ${message}`);
+		return null;
+	}
+}
+
+// ──────────────────────── 拍平 + 查找 ────────────────────────
+
+const DEFAULT_COST: ModelCost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+
+/** 把 models.json 拍平成 ResolvedModelEntry 列表（每个 provider.model 一条） */
+export function flattenModels(data: ModelsJsonFile): ResolvedModelEntry[] {
+	const providers = data.providers ?? {};
+	const out: ResolvedModelEntry[] = [];
+	for (const [providerName, providerDef] of Object.entries(providers)) {
+		if (!providerDef || typeof providerDef !== "object") continue;
+		const hasApiKey = typeof providerDef.apiKey === "string" && providerDef.apiKey.length > 0;
+		const apiKey = hasApiKey ? providerDef.apiKey : undefined;
+		const modelDefs = Array.isArray(providerDef.models) ? providerDef.models : [];
+		for (const m of modelDefs) {
+			if (!m || typeof m.id !== "string") continue;
+			const api = m.api ?? providerDef.api;
+			if (typeof api !== "string" || api.length === 0) continue; // 无法构造 Model<Api>
+			out.push({
+				provider: providerName,
+				id: m.id,
+				name: typeof m.name === "string" ? m.name : m.id,
+				api,
+				baseUrl: typeof m.baseUrl === "string" ? m.baseUrl : typeof providerDef.baseUrl === "string" ? providerDef.baseUrl : undefined,
+				cost: m.cost ?? DEFAULT_COST,
+				hasApiKey,
+				apiKey,
+			});
+		}
+	}
+	return out;
+}
+
+/**
+ * 在可用模型（hasApiKey===true）中找 input cost 最低的。
+ *
+ * @returns 最便宜的 ResolvedModelEntry；无可用模型返回 null
+ */
+export function findCheapestModel(data: ModelsJsonFile): ResolvedModelEntry | null {
+	const entries = flattenModels(data).filter((m) => m.hasApiKey);
+	if (entries.length === 0) return null;
+	// 升序按 input cost，并列时取首个稳定项
+	entries.sort((a, b) => a.cost.input - b.cost.input);
+	return entries[0];
+}
+
+// ──────────────────────── listAvailableModels（W7 model picker 用） ────────────────────────
+
+/**
+ * 列出所有「可用」（provider 配了 apiKey）的模型，按 provider 分组成 Map。
+ *
+ * model picker（/permission model）用：第一级选 provider，第二级选该 provider 下的 model。
+ * 与 findCheapestModel 的区别：
+ *  - findCheapestModel 只返回单个最便宜模型（'auto' 解析用）
+ *  - listAvailableModels 返回全量分组（picker 展示用）
+ *
+ * 排序规则：
+ *  - provider 内 model 按 cost.input 升序，并列时按 id 字母序 tiebreaker
+ *  - provider 之间按字母序（Map 保持插入序，便于 picker 稳定展示）
+ *
+ * 文件缺失 / 解析失败 → 返回空 Map（不 throw，调用方据此降级为「无可选模型」提示）。
+ *
+ * @param onWarning 文件读取/解析问题的警告回调（透传给 loadModelsJson）
+ * @param filePath 可选，自定义 models.json 路径（测试用）
+ * @returns Map<providerName, ResolvedModelEntry[]>（仅含 hasApiKey=true 的 provider）
+ */
+export function listAvailableModels(
+	onWarning?: (msg: string) => void,
+	filePath?: string,
+): Map<string, ResolvedModelEntry[]> {
+	const file = loadModelsJson(onWarning, filePath);
+	if (file === null) return new Map();
+
+	const entries = flattenModels(file).filter((m) => m.hasApiKey);
+	// 按 provider 分组
+	const grouped = new Map<string, ResolvedModelEntry[]>();
+	for (const entry of entries) {
+		const list = grouped.get(entry.provider);
+		if (list === undefined) {
+			grouped.set(entry.provider, [entry]);
+		} else {
+			list.push(entry);
+		}
+	}
+
+	// provider 内排序：cost.input 升序 + id 字母序 tiebreaker
+	for (const list of grouped.values()) {
+		list.sort((a, b) => {
+			if (a.cost.input !== b.cost.input) return a.cost.input - b.cost.input;
+			return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+		});
+	}
+
+	// provider 间按字母序重排（新建 Map 保持插入序）
+	if (grouped.size > 1) {
+		const sortedProviders = [...grouped.keys()].sort();
+		const reordered = new Map<string, ResolvedModelEntry[]>();
+		for (const p of sortedProviders) {
+			reordered.set(p, grouped.get(p)!);
+		}
+		return reordered;
+	}
+	return grouped;
+}
+
+// ──────────────────────── resolveClassifierModel ────────────────────────
+
+/**
+ * classifier 解析后的模型规格（用于在 classifier.ts 构造 Model<Api> 调用 streamSimple）。
+ *
+ * G4：携带 baseUrl?/name?/inputCost?，让构造 Model<Api> 时能填真实值。
+ */
+export interface ResolvedModel {
+	provider: string;
+	id: string;
+	api: string;
+	name?: string;
+	baseUrl?: string;
+	inputCost?: number;
+	apiKey?: string;
+}
+
+/**
+ * 把 ClassifierConfig.model 规格解析为具体模型。
+ *
+ * - 'auto'：findCheapestModel（最便宜 + hasApiKey）
+ * - 'provider/model-id'：精确查找（hasApiKey 不强制，调用方负责报错）
+ * - 其他格式：视为无效，返回 null
+ *
+ * @param modelSpec ClassifierConfig.model（'auto' 或 'provider/model-id'）
+ * @param data 可选，预加载的 models.json（避免重复读盘）；未传则 loadModelsJson()
+ * @param onWarning 可选警告回调（仅传给 loadModelsJson）
+ */
+export function resolveClassifierModel(
+	modelSpec: string,
+	data?: ModelsJsonFile | null,
+	onWarning?: (msg: string) => void,
+): ResolvedModel | null {
+	const file = data !== undefined ? data : loadModelsJson(onWarning);
+	if (file === null) return null;
+
+	if (modelSpec === "auto") {
+		const cheapest = findCheapestModel(file);
+		if (cheapest === null) return null;
+		return {
+			provider: cheapest.provider,
+			id: cheapest.id,
+			api: cheapest.api,
+			name: cheapest.name,
+			baseUrl: cheapest.baseUrl,
+			inputCost: cheapest.cost.input,
+			apiKey: cheapest.apiKey,
+		};
+	}
+
+	// 'provider/model-id' 拆分查找
+	const slashIdx = modelSpec.indexOf("/");
+	if (slashIdx <= 0 || slashIdx === modelSpec.length - 1) {
+		return null;
+	}
+	const provider = modelSpec.slice(0, slashIdx);
+	const modelId = modelSpec.slice(slashIdx + 1);
+	const entries = flattenModels(file);
+	const found = entries.find((m) => m.provider === provider && m.id === modelId);
+	if (found === undefined) return null;
+	return {
+		provider: found.provider,
+		id: found.id,
+		api: found.api,
+		name: found.name,
+		baseUrl: found.baseUrl,
+		inputCost: found.cost.input,
+		apiKey: found.apiKey,
+	};
+}