@bachi/pi-coder 1.0.0

package/extensions/ask-user-question/view.ts

@@ -0,0 +1,262 @@
+/**
+ * view.ts — 问卷的 TUI 外壳：按键解码 + 渲染。状态语义全在 model.ts（纯），
+ * 这里只做两件事：把 pi-tui 的按键序列映射成 Intent、把 state 画成行。
+ *
+ * 用 `ctx.ui.custom()` 装载（非 overlay）：custom 组件临时接管编辑器区，
+ * 返回 `{ render, invalidate, handleInput }` 的普通对象即满足 pi-tui 的
+ * Component 结构（examples/extensions/question.ts 同款做法，不依赖 pi-tui
+ * 组件类）。自由输入行复用 pi-tui 的 Editor（多行、Shift+Enter 换行、
+ * 粘贴折叠），Enter 提交、Esc 退回选项列表。
+ *
+ * 本文件不进 `node --test`（真 TUI 无法无头构建，仓库约定）；可单测的逻辑
+ * 都在 model.ts / validate.ts / answers.ts / dialog.ts。
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	Editor,
+	type EditorTheme,
+	Key,
+	matchesKey,
+	type TUI,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+import { CUSTOM_ANSWER_LABEL, type AskParams, type AskResult } from "./types.ts";
+import { formatAnswerScalar } from "./answers.ts";
+import {
+	allAnswered,
+	createState,
+	hasSubmitTab,
+	type Intent,
+	isSubmitTab,
+	reduce,
+	unansweredHeaders,
+} from "./model.ts";
+
+/** 数字键 1-9 直接跳到对应行（含哨兵行）。 */
+const DIGIT_KEYS = ["1", "2", "3", "4", "5", "6", "7", "8", "9"] as const;
+
+export function createQuestionnaireView(
+	tui: TUI,
+	theme: Theme,
+	params: AskParams,
+	done: (result: AskResult) => void,
+): Component {
+	const state = createState(params);
+	let cachedLines: string[] | undefined;
+
+	const editorTheme: EditorTheme = {
+		borderColor: (s) => theme.fg("accent", s),
+		selectList: {
+			selectedPrefix: (t) => theme.fg("accent", t),
+			selectedText: (t) => theme.fg("accent", t),
+			description: (t) => theme.fg("muted", t),
+			scrollInfo: (t) => theme.fg("dim", t),
+			noMatch: (t) => theme.fg("warning", t),
+		},
+	};
+	const editor = new Editor(tui, editorTheme);
+
+	function refresh(): void {
+		cachedLines = undefined;
+		tui.requestRender();
+	}
+
+	function dispatch(intent: Intent): void {
+		const outcome = reduce(state, intent);
+		switch (outcome.status) {
+			case "submit":
+			case "cancel":
+				done(outcome.result);
+				return;
+			case "enterInput": {
+				// 重答时把上次打的字放回编辑器（切走再切回来不丢草稿）。
+				const previous = state.answers[state.currentTab];
+				editor.setText(previous?.kind === "custom" ? (previous.answer ?? "") : "");
+				refresh();
+				return;
+			}
+			case "exitInput":
+				editor.setText("");
+				refresh();
+				return;
+			case "continue":
+				refresh();
+				return;
+		}
+	}
+
+	editor.onSubmit = (value) => dispatch({ type: "inputSubmit", text: value });
+
+	function handleInput(data: string): void {
+		if (state.inputMode) {
+			if (matchesKey(data, Key.escape)) {
+				dispatch({ type: "inputCancel" });
+				return;
+			}
+			editor.handleInput(data);
+			refresh();
+			return;
+		}
+
+		if (matchesKey(data, Key.up)) return dispatch({ type: "up" });
+		if (matchesKey(data, Key.down)) return dispatch({ type: "down" });
+		if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) return dispatch({ type: "nextTab" });
+		if (matchesKey(data, Key.shift("tab")) || matchesKey(data, Key.left)) return dispatch({ type: "prevTab" });
+		if (matchesKey(data, Key.space)) return dispatch({ type: "toggle" });
+		if (matchesKey(data, Key.enter)) return dispatch({ type: "confirm" });
+		if (matchesKey(data, Key.escape)) return dispatch({ type: "cancel" });
+		for (let i = 0; i < DIGIT_KEYS.length; i++) {
+			if (matchesKey(data, DIGIT_KEYS[i])) return dispatch({ type: "digit", digit: i + 1 });
+		}
+	}
+
+	function render(width: number): string[] {
+		if (cachedLines) return cachedLines;
+		const lines: string[] = [];
+		const renderWidth = Math.max(1, width);
+
+		const addWrapped = (text: string): void => {
+			lines.push(...wrapTextWithAnsi(text, renderWidth));
+		};
+		const addWrappedWithPrefix = (prefix: string, text: string): void => {
+			const prefixWidth = visibleWidth(prefix);
+			if (prefixWidth >= renderWidth) {
+				addWrapped(prefix + text);
+				return;
+			}
+			const wrapped = wrapTextWithAnsi(text, renderWidth - prefixWidth);
+			const continuation = " ".repeat(prefixWidth);
+			for (let i = 0; i < wrapped.length; i++) {
+				lines.push(`${i === 0 ? prefix : continuation}${wrapped[i]}`);
+			}
+		};
+
+		lines.push(theme.fg("accent", "─".repeat(renderWidth)));
+
+		if (hasSubmitTab(state)) {
+			addWrappedWithPrefix(" ", renderTabBar());
+			lines.push("");
+		}
+
+		if (isSubmitTab(state)) {
+			renderSubmitTab();
+		} else {
+			renderQuestionTab();
+		}
+
+		lines.push("");
+		addWrappedWithPrefix(" ", theme.fg("dim", helpLine()));
+		lines.push(theme.fg("accent", "─".repeat(renderWidth)));
+
+		cachedLines = lines;
+		return lines;
+
+		function renderTabBar(): string {
+			const parts: string[] = [];
+			for (let i = 0; i < state.questions.length; i++) {
+				const q = state.questions[i];
+				const answered = state.answers[i] !== undefined;
+				const box = answered ? "■" : "□";
+				const label = ` ${box} ${q.header || `Q${i + 1}`} `;
+				const styled =
+					i === state.currentTab
+						? theme.bg("selectedBg", theme.fg("text", label))
+						: theme.fg(answered ? "success" : "muted", label);
+				parts.push(styled);
+			}
+			const submitActive = isSubmitTab(state);
+			const submitLabel = " ✓ Submit ";
+			const submitStyled = submitActive
+				? theme.bg("selectedBg", theme.fg("text", submitLabel))
+				: theme.fg(allAnswered(state) ? "success" : "dim", submitLabel);
+			parts.push(submitStyled);
+			return parts.join("");
+		}
+
+		function renderQuestionTab(): void {
+			const q = state.questions[state.currentTab];
+			if (!q) return;
+
+			for (const line of q.question.split("\n")) {
+				addWrappedWithPrefix(" ", theme.fg("text", line));
+			}
+			lines.push("");
+
+			for (let i = 0; i < q.options.length; i++) {
+				const opt = q.options[i];
+				const selected = i === state.cursor;
+				const prefix = selected ? theme.fg("accent", "> ") : "  ";
+				const check = q.multiSelect ? `[${state.toggles[state.currentTab][i] ? "x" : " "}] ` : "";
+				const label = `${i + 1}. ${check}${opt.label}`;
+				addWrappedWithPrefix(prefix, theme.fg(selected ? "accent" : "text", label));
+				if (opt.description) {
+					addWrappedWithPrefix("     ", theme.fg("muted", opt.description));
+				}
+			}
+
+			const sentinelSelected = state.cursor === q.options.length;
+			const sentinelPrefix = sentinelSelected ? theme.fg("accent", "> ") : "  ";
+			const sentinel = `${q.options.length + 1}. ${CUSTOM_ANSWER_LABEL}${state.inputMode ? " ✎" : ""}`;
+			addWrappedWithPrefix(sentinelPrefix, theme.fg(sentinelSelected || state.inputMode ? "accent" : "dim", sentinel));
+
+			if (state.inputMode) {
+				lines.push("");
+				addWrappedWithPrefix(" ", theme.fg("muted", "Your answer:"));
+				for (const line of editor.render(Math.max(1, renderWidth - 2))) {
+					lines.push(` ${line}`);
+				}
+			}
+		}
+
+		function renderSubmitTab(): void {
+			addWrappedWithPrefix(" ", theme.fg("accent", theme.bold("Review your answers")));
+			lines.push("");
+			for (let i = 0; i < state.questions.length; i++) {
+				const q = state.questions[i];
+				const answer = state.answers[i];
+				const head = theme.fg("muted", `${q.header || `Q${i + 1}`}: `);
+				if (answer) {
+					const text = answer.kind === "custom" ? `✎ ${formatAnswerScalar(answer)}` : formatAnswerScalar(answer);
+					addWrappedWithPrefix(` ${theme.fg("success", "✓")} `, head + theme.fg("text", text));
+				} else {
+					addWrappedWithPrefix(` ${theme.fg("warning", "○")} `, head + theme.fg("dim", "(unanswered)"));
+				}
+			}
+			lines.push("");
+			if (allAnswered(state)) {
+				addWrappedWithPrefix(" ", theme.fg("success", "Press Enter to submit"));
+			} else {
+				addWrappedWithPrefix(
+					" ",
+					theme.fg("warning", `Unanswered: ${unansweredHeaders(state).join(", ")} — Tab back to answer`),
+				);
+			}
+		}
+
+		function helpLine(): string {
+			if (state.inputMode) return "Enter submit · Esc back";
+			if (isSubmitTab(state)) return "Enter submit · Tab back · Esc cancel";
+			const q = state.questions[state.currentTab];
+			const parts: string[] = [];
+			if (hasSubmitTab(state)) parts.push("Tab switch question");
+			parts.push("↑↓ move");
+			if (q?.multiSelect) parts.push("Space toggle");
+			parts.push(`1-${q ? q.options.length + 1 : 9} jump`);
+			parts.push("Enter confirm");
+			parts.push("Esc cancel");
+			return parts.join(" · ");
+		}
+	}
+
+	return {
+		render,
+		invalidate: () => {
+			cachedLines = undefined;
+			editor.invalidate();
+		},
+		handleInput,
+	};
+}

package/extensions/auto-default-model/default-model.test.ts

@@ -0,0 +1,268 @@
+/**
+ * auto-default-model 的验证：**不 mock pi**，而是用 pi 自己的扩展加载器（
+ * `discoverAndLoadExtensions`）真加载 `index.ts`，再直接调用它注册的 `model_select` handler，
+ * 最后检查假 agent 目录里的 `settings.json`。
+ *
+ * 这样测到的是真链路：扩展里 `import { SettingsManager } from "@earendil-works/pi-coding-agent"`
+ * 这句走的正是 pi 加载器给扩展准备的 alias / virtualModules（import 失败会让 pi 的 loader 报错、
+ * `extensions` 为空 —— 第一个用例就是在断言它），落盘走的也是真 `FileSettingsStorage`
+ * （proper-lockfile + 只合并改动字段的读改写），而不是测试自己拼的假对象。
+ *
+ * 需要本机装过 pi（先从 `pi` 可执行文件的 shim 反查真正安装位置，再退回
+ * `~/.pi/agent/npm/node_modules/`，或直接给 `PI_TEST_PI_ENTRY` 指路）；找不到就整体 skip，
+ * 不假装通过。`~/.pi/agent/npm` 那份副本不能只看文件在不在：`pi update --extensions` 会把
+ * 自动装进去的 `@earendil-works/pi-*` 同伴包剪掉，副本会变成 import 就报错的空壳。
+ *
+ *   node --test clients/pi/extensions/auto-default-model/default-model.test.ts
+ */
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "index.ts");
+
+/**
+ * pi 的库入口（非 CLI）：bundle 是 `pi` 实际跑的形态，dist 是 node 构建形态，两个都能加载扩展。
+ *
+ * 先从 `pi` 可执行文件反查**真正的安装位置**（pnpm/npm 的 shim 脚本里留有
+ * `# cmd-shim-target=<绝对路径>`；npm 在 Unix 上则是符号链接，两种都试），再退回
+ * `~/.pi/agent/npm` 那份副本 —— 后者是**扩展包的安装根**，`pi update --extensions` 会用
+ * `--config.auto-install-peers=false` 把自动装进去的 `@earendil-works/pi-*` 同伴包剪掉，
+ * 于是那份副本只剩空壳（文件都在、import 报 `ERR_MODULE_NOT_FOUND`；2026-09 升
+ * pi-subagents 0.68.0 时实测踩到）。
+ *
+ * 判定方式是**能不能真 import**，不是路径存不存在 —— 只有真 import 一次才分得清空壳。
+ * 全都不行就返回 undefined，调用方整体 skip（不假装通过）。
+ */
+async function findPiLibraryEntry(): Promise<string | undefined> {
+	const candidates: string[] = [];
+	if (process.env.PI_TEST_PI_ENTRY) candidates.push(process.env.PI_TEST_PI_ENTRY);
+
+	for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+		if (!dir) continue;
+		const shimPath = path.join(dir, "pi");
+		try {
+			// npm 的 shim 是符号链接
+			const real = fs.realpathSync(shimPath);
+			if (real !== shimPath) candidates.push(path.join(path.dirname(real), "index.js"));
+		} catch {
+			// 不是符号链接 / 不存在：看下面的 shim 脚本
+		}
+		try {
+			const match = /^# cmd-shim-target=(.+)$/m.exec(fs.readFileSync(shimPath, "utf8"));
+			if (match?.[1]) candidates.push(path.join(path.dirname(match[1].trim()), "index.js"));
+		} catch {
+			// 读不到这个 shim：跳过
+		}
+	}
+
+	const packageDir = path.join(os.homedir(), ".pi/agent/npm/node_modules/@earendil-works/pi-coding-agent");
+	candidates.push(path.join(packageDir, "dist/bundle/index.js"), path.join(packageDir, "dist/index.js"));
+
+	for (const candidate of candidates) {
+		if (!fs.existsSync(candidate)) continue;
+		try {
+			await import(pathToFileURL(candidate).href);
+			return candidate;
+		} catch {
+			// 空壳副本：换下一个候选
+		}
+	}
+	return undefined;
+}
+
+const piEntry = await findPiLibraryEntry();
+const skip = piEntry === undefined ? "找不到本机 pi 的库入口（装过 pi 才有）" : false;
+
+type Handler = (event: unknown, ctx: unknown) => Promise<unknown> | unknown;
+type Notify = { type: string | undefined; message: string };
+
+/** 真加载扩展，返回它注册的 model_select handler。 */
+async function loadModelSelectHandler(agentDir: string, projectDir: string): Promise<Handler> {
+	const pi = (await import(pathToFileURL(piEntry as string).href)) as {
+		discoverAndLoadExtensions: (
+			configuredPaths: string[],
+			cwd: string,
+			agentDir?: string,
+		) => Promise<{ extensions: Array<{ handlers: Map<string, Handler[]> }>; errors: Array<{ path: string; error: string }> }>;
+	};
+	const loaded = await pi.discoverAndLoadExtensions([EXTENSION_PATH], projectDir, agentDir);
+	assert.deepEqual(loaded.errors, [], "pi 的扩展加载器不应该报错");
+	assert.equal(loaded.extensions.length, 1, "应该只加载到 auto-default-model 这一个扩展");
+	const handler = loaded.extensions[0]?.handlers.get("model_select")?.[0];
+	assert.ok(handler, "扩展应该注册了 model_select handler");
+	return handler;
+}
+
+function makeWorkspace(): { agentDir: string; projectDir: string; cleanup: () => void } {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-auto-default-model-"));
+	const agentDir = path.join(root, "agent");
+	const projectDir = path.join(root, "project");
+	fs.mkdirSync(agentDir);
+	fs.mkdirSync(projectDir);
+	return {
+		agentDir,
+		projectDir,
+		cleanup: () => fs.rmSync(root, { recursive: true, force: true }),
+	};
+}
+
+function writeSettings(agentDir: string, settings: unknown, raw?: string): void {
+	fs.writeFileSync(path.join(agentDir, "settings.json"), raw ?? `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
+}
+
+function readSettings(agentDir: string): Record<string, unknown> {
+	return JSON.parse(fs.readFileSync(path.join(agentDir, "settings.json"), "utf-8"));
+}
+
+/** 驱动一次模型切换（默认 `/model` 选择器那条路径），返回 UI 收到的通知。 */
+async function switchModel(
+	agentDir: string,
+	projectDir: string,
+	provider: string,
+	id: string,
+	options: { source?: string; hasUI?: boolean } = {},
+): Promise<{ notifications: Notify[]; fileExisted: boolean }> {
+	const handler = await loadModelSelectHandler(agentDir, projectDir);
+	const notifications: Notify[] = [];
+	const previousAgentDir = process.env.PI_CODING_AGENT_DIR;
+	process.env.PI_CODING_AGENT_DIR = agentDir;
+	try {
+		await handler(
+			{
+				type: "model_select",
+				model: { provider, id },
+				previousModel: { provider: "litellm-any", id: "qwen3.8-df-qd-claude" },
+				source: options.source ?? "set",
+			},
+			{
+				cwd: projectDir,
+				hasUI: options.hasUI ?? false,
+				ui: {
+					notify: (message: string, type?: string) => {
+						notifications.push({ message, type });
+					},
+				},
+			},
+		);
+	} finally {
+		if (previousAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = previousAgentDir;
+	}
+	return { notifications, fileExisted: fs.existsSync(path.join(agentDir, "settings.json")) };
+}
+
+test("切模型后把 defaultProvider/defaultModel 写成启动默认，settings.json 其它字段不动", { skip }, async () => {
+	const workspace = makeWorkspace();
+	try {
+		writeSettings(workspace.agentDir, {
+			theme: "coffee",
+			defaultProvider: "litellm-any",
+			defaultModel: "qwen3.8-df-qd-claude",
+			markdown: { mermaid: "streaming" },
+			packages: ["npm:pi-subagents"],
+		});
+
+		const { notifications, fileExisted } = await switchModel(workspace.agentDir, workspace.projectDir, "litellm-any", "deepseek-flash");
+
+		assert.deepEqual(notifications, []);
+		assert.equal(fileExisted, true);
+		assert.deepEqual(readSettings(workspace.agentDir), {
+			theme: "coffee",
+			defaultProvider: "litellm-any",
+			defaultModel: "deepseek-flash",
+			markdown: { mermaid: "streaming" },
+			packages: ["npm:pi-subagents"],
+		});
+	} finally {
+		workspace.cleanup();
+	}
+});
+
+test("settings.json 还不存在时按需创建（新机器）", { skip }, async () => {
+	const workspace = makeWorkspace();
+	try {
+		assert.equal(fs.existsSync(path.join(workspace.agentDir, "settings.json")), false);
+
+		await switchModel(workspace.agentDir, workspace.projectDir, "litellm-any", "deepseek-flash");
+
+		assert.deepEqual(readSettings(workspace.agentDir), {
+			defaultProvider: "litellm-any",
+			defaultModel: "deepseek-flash",
+		});
+	} finally {
+		workspace.cleanup();
+	}
+});
+
+test("磁盘上已经是同一个模型就不写（不白动 settings.json）", { skip }, async () => {
+	const workspace = makeWorkspace();
+	try {
+		// 紧凑格式 + 无换行：pi 自己的写入会重排成 2 空格缩进，所以「字节不变」= 真的一次都没写。
+		const raw = '{"defaultProvider":"litellm-any","defaultModel":"deepseek-flash"}';
+		writeSettings(workspace.agentDir, undefined, raw);
+
+		await switchModel(workspace.agentDir, workspace.projectDir, "litellm-any", "deepseek-flash");
+
+		assert.equal(fs.readFileSync(path.join(workspace.agentDir, "settings.json"), "utf-8"), raw);
+	} finally {
+		workspace.cleanup();
+	}
+});
+
+test("source=restore（恢复旧会话带回的模型）不改全局默认", { skip }, async () => {
+	const workspace = makeWorkspace();
+	try {
+		const raw = '{"defaultProvider":"litellm-any","defaultModel":"qwen3.8-df-qd-claude"}';
+		writeSettings(workspace.agentDir, undefined, raw);
+
+		await switchModel(workspace.agentDir, workspace.projectDir, "litellm-any", "deepseek-flash", { source: "restore" });
+
+		assert.equal(fs.readFileSync(path.join(workspace.agentDir, "settings.json"), "utf-8"), raw);
+	} finally {
+		workspace.cleanup();
+	}
+});
+
+test("PI_AUTO_DEFAULT_MODEL=off 整体关闭", { skip }, async () => {
+	const workspace = makeWorkspace();
+	try {
+		const raw = '{"defaultProvider":"litellm-any","defaultModel":"qwen3.8-df-qd-claude"}';
+		writeSettings(workspace.agentDir, undefined, raw);
+		process.env.PI_AUTO_DEFAULT_MODEL = "off";
+		try {
+			await switchModel(workspace.agentDir, workspace.projectDir, "litellm-any", "deepseek-flash");
+		} finally {
+			delete process.env.PI_AUTO_DEFAULT_MODEL;
+		}
+
+		assert.equal(fs.readFileSync(path.join(workspace.agentDir, "settings.json"), "utf-8"), raw);
+	} finally {
+		workspace.cleanup();
+	}
+});
+
+test("settings.json 坏掉时不当成写成功（notify 警告，文件保持原样）", { skip }, async () => {
+	const workspace = makeWorkspace();
+	try {
+		const raw = "{ this is not json }";
+		writeSettings(workspace.agentDir, undefined, raw);
+
+		const { notifications } = await switchModel(workspace.agentDir, workspace.projectDir, "litellm-any", "deepseek-flash", {
+			hasUI: true,
+		});
+
+		assert.equal(notifications.length, 1);
+		assert.equal(notifications[0]?.type, "warning");
+		// 警告里要带上是哪个模型、以及 pi 记下的真实错误（解析失败原文），否则用户无从下手。
+		assert.match(notifications[0]?.message ?? "", /deepseek-flash/);
+		assert.match(notifications[0]?.message ?? "", /启动默认模型/);
+		assert.equal(fs.readFileSync(path.join(workspace.agentDir, "settings.json"), "utf-8"), raw);
+	} finally {
+		workspace.cleanup();
+	}
+});

package/extensions/auto-default-model/index.ts

@@ -0,0 +1,87 @@
+/**
+ * auto-default-model — 换模型时顺手把它写成「启动默认模型」，省掉那次 Ctrl+S。
+ *
+ * 为什么需要它：pi 的 `/model` 选择器**只改当前会话**的模型，想让下次启动停在某个模型上，
+ * 必须额外按一次 Ctrl+S（`app.models.save` → `setModel(model, {persist: true})` →
+ * `settingsManager.setDefaultModelAndProvider`，写 `~/.pi/agent/settings.json` 的
+ * `defaultProvider` / `defaultModel`）。这是上游刻意的行为（CHANGELOG：「Fixed `/model` and
+ * `/thinking` selections being persisted globally unless explicitly saved with Ctrl+S」），
+ * 但对单人机器是多余的仪式：换完模型常常忘了按 Ctrl+S，下次启动又回到旧模型。
+ * 本扩展把这一步自动化 —— 任何一次模型切换（`/model` 选择器、Ctrl+P 循环、
+ * `pi-subagents` 的 profile 切换这类 `pi.setModel()` 调用）都立刻落盘。
+ *
+ * 落盘走的是 **pi 自己的公开 API**（`SettingsManager`，从 `@earendil-works/pi-coding-agent`
+ * 导入，加载器对这个 specifier 做了 alias / virtualModules 映射，所以扩展里 on-demand import 它
+ 就是 pi 自己那份实现），也就是和 Ctrl+S 完全相同的那条持久化路径：
+ * `FileSettingsStorage` + proper-lockfile 文件锁 + 「只把本次改动的字段合并进磁盘上最新内容」的
+ * 读改写。所以①settings.json 里的其它字段（包括本扩展不认识的未来字段）不会被覆盖，
+ * ②和 pi 自己的写入共用同一把锁，不会互相丢更新。**刻意不自己 `fs.writeFile`**：那样就会绕过
+ * 那把锁，在用户同时改设置（`/theme`、`/settings`）时丢掉对方刚写进去的内容。
+ *
+ * 三个刻意的取舍：
+ *   - `source === "restore"` **不落盘**。恢复会话时 pi 会把模型带回该会话自己的那条，
+ *     那是「打开旧会话」而不是「我换了个模型」，让它改写全局默认会很意外。
+ *     （pi 0.85.1 只在 `setModel()` / `cycleModel()` 里发 `model_select`，恢复走的是直接设
+ *      `agent.state.model`，所以当前版本这个分支根本不会触发；写在这里是为了将来 pi 把
+ *     `restore` 接上以后，语义仍然明确。）
+ *   - 值没变就不写。选中同一个模型、或 pi 自己已经 persist 过一次（Ctrl+S、`/login` 后自动选
+ *     该 provider 的默认模型）时 `model_select` 也会触发，重复写只会白白动 settings.json。
+ *   - 只在失败时提示（`ctx.ui.notify`），成功不打扰：当前模型名在 statusline 上本来就看得见，
+ *     换模型时再弹一条通知是噪音。
+ *
+ * 关掉：`PI_AUTO_DEFAULT_MODEL=off`（每次切换时读，不缓存）。
+ */
+
+import { SettingsManager } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ModelSelectEvent } from "@earendil-works/pi-coding-agent";
+
+type PersistOutcome = "written" | "unchanged" | "failed";
+type PersistResult = { outcome: PersistOutcome; detail?: string };
+
+function isDisabled(): boolean {
+	return (process.env.PI_AUTO_DEFAULT_MODEL ?? "").trim().toLowerCase() === "off";
+}
+
+function modelLabel(event: ModelSelectEvent): string {
+	return `${event.model.provider}/${event.model.id}`;
+}
+
+function notify(ctx: ExtensionContext, message: string): void {
+	if (ctx.hasUI) ctx.ui.notify(message, "warning");
+}
+
+/**
+ * 把 `provider/modelId` 写成全局启动默认模型。返回 "unchanged" 表示磁盘上已经是它。
+ */
+async function persistAsStartupDefault(cwd: string, provider: string, modelId: string): Promise<PersistResult> {
+	const settings = SettingsManager.create(cwd);
+	// 比的是**全局**设置而不是合并后的值：项目级 `.pi/settings.json` 里的 defaultProvider /
+	// defaultModel 会盖过全局值（那条启动路径本扩展也管不了），拿合并值去比会误判成「已经写过了」。
+	const global = settings.getGlobalSettings();
+	if (global.defaultProvider === provider && global.defaultModel === modelId) {
+		return { outcome: "unchanged" };
+	}
+	settings.setDefaultModelAndProvider(provider, modelId);
+	await settings.flush();
+	// settings.json 解析失败 / 写不进去时 `save()` 是**静默跳过**的（`globalSettingsLoadError`
+	// 直接 return，`enqueueWrite` 的 catch 只记错误），`flush()` 也不抛 —— 结果只能从
+	// `drainErrors()` 里读，否则扩展会假装写成功了。错误原文一并带出去，警告才有诊断价值。
+	const failure = settings.drainErrors()[0];
+	if (failure) return { outcome: "failed", detail: failure.error.message };
+	return { outcome: "written" };
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("model_select", async (event, ctx) => {
+		if (isDisabled()) return;
+		if (event.source === "restore") return;
+		try {
+			const result = await persistAsStartupDefault(ctx.cwd, event.model.provider, event.model.id);
+			if (result.outcome === "failed") {
+				notify(ctx, `${modelLabel(event)} 没能写成启动默认模型：${result.detail ?? "settings.json 读取或写入失败"}`);
+			}
+		} catch (error) {
+			notify(ctx, `写启动默认模型失败：${error instanceof Error ? error.message : String(error)}`);
+		}
+	});
+}