@bachi/pi-coder 1.0.0

package/docs/themes.md

@@ -0,0 +1,107 @@
+# Themes
+
+Three themes ship with this package: `summer-night` (the one `config/settings.json` selects), `catppuccin` and `ayu`.
+
+## Switching themes
+
+Two ways, both with the same result:
+
+- `/theme` — the picker from `theme-command.ts`. Arrow keys preview live, Enter persists to `settings.json`, Esc leaves settings untouched. `/theme summer-night` switches directly.
+- `/settings` → Theme — pi's built-in path, which also mixes in the light/dark auto modes.
+
+pi loads themes from three places:
+
+```
+~/.pi/agent/themes/*.json      # global
+.pi/themes/*.json              # project, after the project is trusted
+<package>/themes/*.json        # packages — this is how these three arrive
+```
+
+The copy commands in [installation.md](installation.md#apply-the-global-config-files) put them in the global directory as well; that is optional, since the package already provides them.
+
+## The three themes
+
+### `summer-night`
+
+The author's own palette and the current default: a near-black blue base with high-contrast accents. Body text sits at roughly 8.4–9.2:1 on panels. Its greys are deliberately dimmer than catppuccin's — `muted` around 3.3–3.8:1 and `dim` around 2.2–2.6:1 — so comments, `Think:` rows and settings hints read faintly. If that is too faint, raise `vars.muted` and `vars.dimmed`.
+
+`text` is `""`, the terminal's own default foreground. Three values are literals rather than `vars` references: `syntaxComment` (`#95a1b0`), `thinkingXhigh` and `thinkingMax` (both `#4b7cc2`). The Chinese handbook still describes this file as having no literal colors — the file has since changed; trust the file.
+
+### `catppuccin`
+
+A port of Catppuccin Mocha from [bacnh85/pi-extensions](https://github.com/bacnh85/pi-extensions). The palette lives in `vars` (36 of them) and `colors` only references it. Two entries are empty strings meaning "terminal default": `text` and `syntaxVariable`. The upstream file's single 256-color index (`toolPendingBg: 233`) was converted to hex `#140e1e`, so all three themes in this package are free of integer color values — `bgAnsi()` emits `48;5;N` for an integer, which mixes poorly with a truecolor palette.
+
+### `ayu`
+
+A port of the official `ayu-dark` palette from [iodic/pi-ayu-themes](https://github.com/iodic/pi-ayu-themes), reformatted to the same four-section shape as `catppuccin.json` and with all 55 colors going through `vars`. It is the only theme here that defines `bashOutput`.
+
+Three deliberate deviations from upstream:
+
+1. **Strings vs. added diff lines.** Upstream points `syntaxString` (strings in code) and `toolDiffAdded` (the foreground of added diff lines, including line numbers and `+`) at the same green `#AAD94C`. Here `syntaxString` points at a darker `stringGreen` (`#67a567`) so code strings and diff additions do not glow identically; diff additions keep the upstream green. Side effect: the new green is close in luminance to `muted`, so strings and comments are told apart mostly by hue.
+2. **Thinking borders.** Upstream paints `thinkingXhigh` red (`#D95757`). Here `thinkingXhigh` and `thinkingMax` are both a neutral grey (`#626262`), because the editor border takes the color of the current level and this setup defaults to `xhigh` — a red border reads as an error. The top two levels are now distinguished from each other only by luminance.
+3. **Pending and finished tool cards are inverted.** Upstream has `toolPendingBg: #10151F` (darker) and `toolSuccessBg: #171F24` (lighter); this file swaps them, so a tool call that is still running gets the lighter background and a finished one the darker. Nothing in the file explains the choice — it is a value inversion, not a renamed variable.
+
+## Anatomy of a theme file
+
+```jsonc
+{
+  "$schema": "...",
+  "name": "summer-night",     // must equal the file name (minus .json)
+  "vars": { "panelBg": "#0e1622", ... },
+  "colors": { "bg": "panelBg", ... },
+  "export": { "pageBg": "panelBg", "cardBg": "bg", "infoBg": "infoBg" }
+}
+```
+
+- Every non-`#` value in `colors` is looked up in `vars`. A missing reference throws `Variable reference not found`, **the whole theme fails to load**, and pi falls back to the built-in `dark` theme without an error message. This is the single most common way to break a theme.
+- An empty string means "terminal default foreground" — used by `text` and, in catppuccin, `syntaxVariable`.
+- `export` only affects HTML produced by `/export`; when it is missing, pi derives those colors from `userMessageBg`. In these files it is set explicitly (and `summer-night` uses literal hex there).
+
+## Custom tokens
+
+Three tokens in these files are **not** part of pi's official theme schema:
+
+| Token | Read by | Effect |
+| --- | --- | --- |
+| `toolDiffAddedBg` | `tool-diff.ts` | Full-line background of added diff lines. |
+| `toolDiffRemovedBg` | `tool-diff.ts` | Full-line background of removed diff lines. |
+| `bashOutput` | `bash-command-collapse.ts` | Foreground of bash output text only. |
+
+All three themes define the two diff backgrounds. Only `ayu` defines `bashOutput`.
+
+### Why they work at all
+
+Three things line up:
+
+1. Theme validation uses TypeBox's `Compile().Check()`, which **allows unknown keys** — the `additionalProperties: false` in pi's `theme-schema.json` is not on the executed path.
+2. `createTheme()` puts any color that is not one of the seven known background tokens into the `fgColors` table.
+3. `getFgAnsi()` looks colors up **by key**, without checking the key against the union type. Since a background SGR is a foreground SGR with `38` replaced by `48`, an unknown token can be resolved and used as a background.
+
+If pi ever validates strictly, these tokens stop resolving. Nothing breaks loudly: `tool-diff` silently falls back to the much flatter `toolSuccessBg` / `toolErrorBg`, and `bash-command-collapse` falls back to `toolOutput`.
+
+### `bashOutput` in detail
+
+pi's built-in bash renderer hardcodes output text to `toolOutput`, a slot shared by every tool (`read`, `grep`, `ls` all use it). To give bash output its own color, `bash-command-collapse.ts` temporarily swaps that one key in the module-level theme singleton while it delegates to the built-in renderer — the swap window must be synchronous, and it can only touch this one key.
+
+The extension probes for the token by calling `getFgAnsi("bashOutput")` and does nothing if it throws `Unknown theme color: ...`. So:
+
+- Themes without `bashOutput` (including pi's built-ins, `summer-night` and `catppuccin`) are unaffected — bash output simply uses `toolOutput`.
+- To split the color out for any theme, add one `vars` entry and one `colors` line, exactly as `ayu` does.
+- `bashOutput` does not appear in the `/theme` preview swatches, which only draw pi's standard token list.
+
+## Editing or porting a theme
+
+Renaming a theme means changing **three** places: the file name, the `name` field inside it, and `theme` in `settings.json`. `loadThemeJson()` resolves `${name}.json`, so a mismatch shows the old name in the picker or leaves `theme` pointing at nothing. If the theme lives in `~/.pi/agent/themes/`, only the file name and `name` field matter; pi matches the setting by name.
+
+A theme cannot verify itself. `toolDiffAddedBg` misspelled is silently ignored, and a bad `vars` reference silently drops you to `dark`. After writing a theme, at minimum:
+
+```js
+// parse with pi's own loader and resolve every token
+validateThemeJson(path, themeJson)
+const theme = loadThemeFromPath(path, "truecolor")   // and "256color"
+for (const key of Object.keys(colors)) {
+  theme.getFgAnsi(key); theme.getBgAnsi(key)   // throws on a missing vars reference
+}
+```
+
+If you are porting an upstream theme, parse both files and compare `getFgAnsi()` / `getBgAnsi()` per token name. Identical values mean a faithful port; a difference is either an oversight or a deviation that belongs in a comment.

package/extensions/ask-user-question/answers.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Tests for answers.ts — 结果封装 / 信封文本 / 错误路径。
+ *
+ * Run with:  node --test clients/pi/extensions/ask-user-question/answers.test.ts
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+	buildAnswerSegment,
+	buildEnvelopeText,
+	buildResponse,
+	DECLINE_MESSAGE,
+	ENVELOPE_PREFIX,
+	ENVELOPE_SUFFIX,
+	errorResult,
+	formatAnswerScalar,
+	NO_INPUT_PLACEHOLDER,
+	toolResult,
+} from "./answers.ts";
+import type { AskAnswer, AskParams, AskResult } from "./types.ts";
+
+const params: AskParams = {
+	questions: [
+		{ question: "Which library?", header: "Lib", options: [{ label: "A", description: "a" }, { label: "B", description: "b" }] },
+		{
+			question: "Which features?",
+			header: "Feat",
+			multiSelect: true,
+			options: [{ label: "X", description: "x" }, { label: "Y", description: "y" }],
+		},
+	],
+};
+
+const optionAnswer: AskAnswer = { questionIndex: 0, question: "Which library?", kind: "option", answer: "A" };
+const multiAnswer: AskAnswer = { questionIndex: 1, question: "Which features?", kind: "multi", answer: null, selected: ["X", "Y"] };
+const emptyMulti: AskAnswer = { questionIndex: 1, question: "Which features?", kind: "multi", answer: null, selected: [] };
+const customAnswer: AskAnswer = { questionIndex: 0, question: "Which library?", kind: "custom", answer: "use luxon" };
+const emptyCustom: AskAnswer = { questionIndex: 0, question: "Which library?", kind: "custom", answer: "" };
+
+test("formatAnswerScalar: option / custom / multi / 空值", () => {
+	assert.equal(formatAnswerScalar(optionAnswer), "A");
+	assert.equal(formatAnswerScalar(customAnswer), "use luxon");
+	assert.equal(formatAnswerScalar(multiAnswer), "X, Y");
+	assert.equal(formatAnswerScalar(emptyMulti), NO_INPUT_PLACEHOLDER);
+	assert.equal(formatAnswerScalar(emptyCustom), NO_INPUT_PLACEHOLDER);
+});
+
+test("buildAnswerSegment: \"问题\"=\"答案\".", () => {
+	assert.equal(buildAnswerSegment(optionAnswer), '"Which library?"="A".');
+	assert.equal(buildAnswerSegment(multiAnswer), '"Which features?"="X, Y".');
+});
+
+test("buildEnvelopeText: 全答 → 前缀 + 各段 + 后缀", () => {
+	const result: AskResult = { answers: [optionAnswer, multiAnswer], cancelled: false };
+	const text = buildEnvelopeText(result, params);
+	assert.ok(text.startsWith(`${ENVELOPE_PREFIX} `));
+	assert.ok(text.endsWith(` ${ENVELOPE_SUFFIX}`));
+	assert.ok(text.includes('"Which library?"="A".'));
+	assert.ok(text.includes('"Which features?"="X, Y".'));
+});
+
+test("buildEnvelopeText: 部分提交只产生已答段", () => {
+	const result: AskResult = { answers: [optionAnswer], cancelled: false };
+	const text = buildEnvelopeText(result, params);
+	assert.ok(text.includes('"Which library?"="A".'));
+	assert.ok(!text.includes("Which features?"));
+});
+
+test("buildEnvelopeText: 取消 / null / 零答案段都塌缩成 DECLINE_MESSAGE", () => {
+	assert.equal(buildEnvelopeText({ answers: [], cancelled: true }, params), DECLINE_MESSAGE);
+	assert.equal(buildEnvelopeText(null, params), DECLINE_MESSAGE);
+	assert.equal(buildEnvelopeText(undefined, params), DECLINE_MESSAGE);
+	assert.equal(buildEnvelopeText({ answers: [], cancelled: false }, params), DECLINE_MESSAGE);
+});
+
+test("buildResponse: 成功路径 content 是信封、details 原样带回", () => {
+	const result: AskResult = { answers: [optionAnswer], cancelled: false };
+	const out = buildResponse(result, params);
+	assert.equal(out.content.length, 1);
+	assert.equal(out.content[0].type, "text");
+	assert.ok(out.content[0].text.startsWith(ENVELOPE_PREFIX));
+	assert.equal(out.details, result);
+});
+
+test("buildResponse: 取消路径 content 是 DECLINE_MESSAGE、cancelled:true", () => {
+	const out = buildResponse({ answers: [optionAnswer], cancelled: true }, params);
+	assert.equal(out.content[0].text, DECLINE_MESSAGE);
+	assert.equal(out.details.cancelled, true);
+	// 已答部分仍保留在 details 里（回放/渲染用）
+	assert.equal(out.details.answers.length, 1);
+});
+
+test("errorResult: cancelled:true + error 码 + 写给模型的正文", () => {
+	const out = errorResult("Error: boom", "no_ui");
+	assert.equal(out.content[0].text, "Error: boom");
+	assert.deepEqual(out.details, { answers: [], cancelled: true, error: "no_ui" });
+});
+
+test("toolResult: 结构稳定", () => {
+	const out = toolResult("hi", { answers: [], cancelled: false });
+	assert.deepEqual(out.content, [{ type: "text", text: "hi" }]);
+	assert.deepEqual(out.details, { answers: [], cancelled: false });
+});

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

@@ -0,0 +1,72 @@
+/**
+ * answers.ts — 把问卷结果封装成给模型的 tool result（纯函数）。
+ *
+ * 成功：`User has answered your questions: "<问题>"="<答案>". … You can now
+ * continue with the user's answers in mind.`；多选答案用 ", " 连接。
+ * 取消 / 无答案段：统一塌缩成 DECLINE_MESSAGE 这一个规范信号，
+ * 模型不会把"没答"误读成"拒绝回答内容"之外的任何东西。
+ *
+ * 错误路径（no_ui / 校验失败等）也走 errorResult：`cancelled: true` +
+ * 空 answers + error 码 —— content 文本是写给模型看的，不是日志。
+ */
+
+import type { AskAnswer, AskErrorCode, AskParams, AskResult } from "./types.ts";
+
+export const DECLINE_MESSAGE = "User declined to answer the questions";
+export const ENVELOPE_PREFIX = "User has answered your questions:";
+export const ENVELOPE_SUFFIX = "You can now continue with the user's answers in mind.";
+export const NO_INPUT_PLACEHOLDER = "(no input)";
+
+export interface AskToolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: AskResult;
+}
+
+/** 单个答案的标量形式：option → label；custom → 输入文本；multi → ", " 连接。 */
+export function formatAnswerScalar(a: AskAnswer): string {
+	switch (a.kind) {
+		case "multi":
+			return a.selected && a.selected.length > 0 ? a.selected.join(", ") : NO_INPUT_PLACEHOLDER;
+		case "custom":
+			return a.answer && a.answer.length > 0 ? a.answer : NO_INPUT_PLACEHOLDER;
+		case "option":
+			return a.answer ?? NO_INPUT_PLACEHOLDER;
+	}
+}
+
+/** 单题答案段：`"<问题>"="<答案>".` */
+export function buildAnswerSegment(a: AskAnswer): string {
+	return `"${a.question}"="${formatAnswerScalar(a)}".`;
+}
+
+/**
+ * 结果 → 给模型的正文。cancelled / null / 零答案段都落到 DECLINE_MESSAGE；
+ * 部分提交允许：未回答的题不产生段。
+ */
+export function buildEnvelopeText(result: AskResult | null | undefined, params: AskParams): string {
+	if (!result || result.cancelled) return DECLINE_MESSAGE;
+	const segments: string[] = [];
+	for (let i = 0; i < params.questions.length; i++) {
+		const a = result.answers.find((x) => x.questionIndex === i);
+		if (a) segments.push(buildAnswerSegment(a));
+	}
+	if (segments.length === 0) return DECLINE_MESSAGE;
+	return `${ENVELOPE_PREFIX} ${segments.join(" ")} ${ENVELOPE_SUFFIX}`;
+}
+
+export function toolResult(text: string, details: AskResult): AskToolResult {
+	return { content: [{ type: "text", text }], details };
+}
+
+/** 完整成功/取消路径：result + params → tool result。 */
+export function buildResponse(result: AskResult | null | undefined, params: AskParams): AskToolResult {
+	if (!result || result.cancelled) {
+		return toolResult(DECLINE_MESSAGE, { answers: result?.answers ?? [], cancelled: true });
+	}
+	return toolResult(buildEnvelopeText(result, params), result);
+}
+
+/** 错误路径：content 写给模型的错误说明 + cancelled:true + error 码。 */
+export function errorResult(message: string, error: AskErrorCode, answers: AskAnswer[] = []): AskToolResult {
+	return toolResult(message, { answers, cancelled: true, error });
+}

package/extensions/ask-user-question/dialog.test.ts

@@ -0,0 +1,180 @@
+/**
+ * Tests for dialog.ts — 非 TUI 宿主的顺序 select/input 回退。
+ *
+ * Run with:  node --test clients/pi/extensions/ask-user-question/dialog.test.ts
+ *
+ * DialogUI 是鸭子类型，用脚本化的假 ui 覆盖：单选命中选项、哨兵行转自由输入、
+ * 多选编号解析、自由文本逃生、空提交、关掉对话框取消（含保留已答部分）、
+ * 宿主返回清单外内容按取消处理。
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { hasDialogUI, parseIndex, runDialogQuestionnaire, type DialogUI } from "./dialog.ts";
+import type { AskParams } from "./types.ts";
+
+/** 脚本化假 ui：select/input 按调用次序吐出预设值，undefined = 用户关掉对话框。 */
+function fakeUi(script: { select?: Array<string | undefined>; input?: Array<string | undefined> }): DialogUI & {
+	calls: { select: string[]; input: string[] };
+} {
+	const calls = { select: [] as string[], input: [] as string[] };
+	return {
+		calls,
+		async select(title, _options) {
+			calls.select.push(title);
+			return (script.select ?? []).shift();
+		},
+		async input(title, _placeholder) {
+			calls.input.push(title);
+			return (script.input ?? []).shift();
+		},
+	};
+}
+
+const single: AskParams = {
+	questions: [
+		{
+			question: "Which library?",
+			header: "Lib",
+			options: [
+				{ label: "date-fns", description: "functional" },
+				{ label: "dayjs", description: "tiny" },
+			],
+		},
+	],
+};
+
+const multi: AskParams = {
+	questions: [{ ...single.questions[0], question: "Which features?", header: "Feat", multiSelect: true }],
+};
+
+const twoQuestions: AskParams = {
+	questions: [single.questions[0], { ...single.questions[0], question: "Which style?", header: "Style" }],
+};
+
+test("hasDialogUI: 结构化判定", () => {
+	assert.equal(hasDialogUI({ select: async () => undefined, input: async () => undefined }), true);
+	assert.equal(hasDialogUI({ select: async () => undefined }), false);
+	assert.equal(hasDialogUI(null), false);
+	assert.equal(hasDialogUI(undefined), false);
+});
+
+test("parseIndex: 编号解析与越界", () => {
+	assert.equal(parseIndex("1", 3), 0);
+	assert.equal(parseIndex("3. dayjs — tiny", 3), 2);
+	assert.equal(parseIndex("0", 3), null);
+	assert.equal(parseIndex("4", 3), null);
+	assert.equal(parseIndex("abc", 3), null);
+});
+
+test("单选：选第 1 项 → option 答案", async () => {
+	const ui = fakeUi({ select: ["1. date-fns — functional"] });
+	const result = await runDialogQuestionnaire(ui, single);
+	assert.deepEqual(result, {
+		answers: [{ questionIndex: 0, question: "Which library?", kind: "option", answer: "date-fns" }],
+		cancelled: false,
+	});
+});
+
+test("单选：选哨兵行 → 转自由输入", async () => {
+	const ui = fakeUi({ select: ["3. Type something."], input: ["use luxon instead"] });
+	const result = await runDialogQuestionnaire(ui, single);
+	assert.equal(result.cancelled, false);
+	assert.equal(result.answers[0].kind, "custom");
+	assert.equal(result.answers[0].answer, "use luxon instead");
+});
+
+test("单选：哨兵行后关掉输入框 → 整份取消", async () => {
+	const ui = fakeUi({ select: ["3. Type something."], input: [undefined] });
+	const result = await runDialogQuestionnaire(ui, single);
+	assert.equal(result.cancelled, true);
+	assert.deepEqual(result.answers, []);
+});
+
+test("单选：关掉选择框 → 取消", async () => {
+	const ui = fakeUi({ select: [undefined] });
+	const result = await runDialogQuestionnaire(ui, single);
+	assert.equal(result.cancelled, true);
+});
+
+test("单选：宿主返回清单外的串 → 按取消处理，不编造答案", async () => {
+	const ui = fakeUi({ select: ["99. not in list"] });
+	const result = await runDialogQuestionnaire(ui, single);
+	assert.equal(result.cancelled, true);
+});
+
+test("多选：\"1,3\" → 两个 label（但只有 2 个选项时 3 越界 → 走自由文本）", async () => {
+	const three = {
+		questions: [
+			{
+				...multi.questions[0],
+				options: [
+					{ label: "X", description: "x" },
+					{ label: "Y", description: "y" },
+					{ label: "Z", description: "z" },
+				],
+			},
+		],
+	};
+	const ui = fakeUi({ input: ["1,3"] });
+	const result = await runDialogQuestionnaire(ui, three);
+	assert.equal(result.cancelled, false);
+	assert.deepEqual(result.answers[0], {
+		questionIndex: 0,
+		question: "Which features?",
+		kind: "multi",
+		answer: null,
+		selected: ["X", "Z"],
+	});
+});
+
+test("多选：带空格与点号的编号也能解析，且去重", async () => {
+	const ui = fakeUi({ input: [" 1. , 2 , 2 "] });
+	const result = await runDialogQuestionnaire(ui, multi);
+	assert.deepEqual(result.answers[0].selected, ["date-fns", "dayjs"]);
+});
+
+test("多选：空提交 → selected 为空数组", async () => {
+	const ui = fakeUi({ input: ["   "] });
+	const result = await runDialogQuestionnaire(ui, multi);
+	assert.equal(result.answers[0].kind, "multi");
+	assert.deepEqual(result.answers[0].selected, []);
+});
+
+test("多选：非编号文本 → 原样保留为 custom（自由文本逃生口）", async () => {
+	const ui = fakeUi({ input: ["let's just use luxon"] });
+	const result = await runDialogQuestionnaire(ui, multi);
+	assert.equal(result.answers[0].kind, "custom");
+	assert.equal(result.answers[0].answer, "let's just use luxon");
+});
+
+test("多选：越界编号（13）混在编号里 → 整体当自由文本", async () => {
+	const ui = fakeUi({ input: ["1, 13"] });
+	const result = await runDialogQuestionnaire(ui, multi);
+	assert.equal(result.answers[0].kind, "custom");
+	assert.equal(result.answers[0].answer, "1, 13");
+});
+
+test("多题：第二题被关掉 → 取消但保留第一题答案", async () => {
+	const ui = fakeUi({ select: ["1. date-fns — functional", undefined] });
+	const result = await runDialogQuestionnaire(ui, twoQuestions);
+	assert.equal(result.cancelled, true);
+	assert.equal(result.answers.length, 1);
+	assert.equal(result.answers[0].answer, "date-fns");
+});
+
+test("多题：全部回答 → cancelled:false 且按题序", async () => {
+	const ui = fakeUi({ select: ["2. dayjs — tiny", "1. date-fns — functional"] });
+	const result = await runDialogQuestionnaire(ui, twoQuestions);
+	assert.equal(result.cancelled, false);
+	assert.deepEqual(
+		result.answers.map((a) => a.answer),
+		["dayjs", "date-fns"],
+	);
+});
+
+test("对话框标题带 header 前缀", async () => {
+	const ui = fakeUi({ select: ["1. date-fns — functional"] });
+	await runDialogQuestionnaire(ui, single);
+	assert.ok(ui.calls.select[0].startsWith("[Lib] Which library?"));
+});

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

@@ -0,0 +1,102 @@
+/**
+ * dialog.ts — 非 TUI 宿主（RPC / ACP，如 VS Code pendant、Zed）的顺序对话框回退。
+ *
+ * `ctx.ui.custom()` 在这些宿主上渲染不出来，但 select / input 对话框子协议
+ * （extension_ui_request/response）是好用的，所以逐题走原生对话框，产出与 TUI
+ * 完全相同的 AskResult，喂给同一个 buildResponse 封装。纯函数（鸭子类型的
+ * DialogUI），不 import pi —— 单测用假 ui 覆盖。
+ *
+ * 与 TUI 的取舍：没有 tab 式多题总览（一题一个对话框）；多选退化成
+ * "输入编号，逗号分隔" 的文本输入；任何非编号输入都当自由回答原样保留
+ * （这也是多选的 "Type something." 逃生口）。任一对话框被关掉（resolve
+ * undefined）= 整份问卷取消，与 TUI 里按 Esc 同义。
+ */
+
+import { CUSTOM_ANSWER_LABEL, type AskAnswer, type AskParams, type AskQuestion, type AskResult } from "./types.ts";
+
+/** ExtensionUIContext 上本模块需要的切片。结构化类型 + hasDialogUI 运行时闸门。 */
+export type DialogUI = {
+	select: (title: string, options: string[]) => Promise<string | undefined>;
+	input: (title: string, placeholder?: string) => Promise<string | undefined>;
+};
+
+export function hasDialogUI(ui: unknown): ui is DialogUI {
+	const u = ui as Partial<Record<"select" | "input", unknown>> | null | undefined;
+	return typeof u?.select === "function" && typeof u?.input === "function";
+}
+
+function formatOptionLine(q: AskQuestion, index: number): string {
+	const o = q.options[index];
+	return `${index + 1}. ${o.label} — ${o.description}`;
+}
+
+/** 把 "2. Label — desc" 或 "2" 这样的选择串解析成 0 基下标；越界 / 非数字 → null。 */
+export function parseIndex(token: string, count: number): number | null {
+	const i = Number.parseInt(token, 10) - 1;
+	return Number.isFinite(i) && i >= 0 && i < count ? i : null;
+}
+
+/** 逐题走原生对话框。undefined（关掉对话框）= 取消整份问卷，保留已答部分。 */
+export async function runDialogQuestionnaire(ui: DialogUI, params: AskParams): Promise<AskResult> {
+	const answers: AskAnswer[] = [];
+	for (let qi = 0; qi < params.questions.length; qi++) {
+		const q = params.questions[qi];
+		const header = q.header ? `[${q.header}] ` : "";
+		const answer = q.multiSelect ? await askMultiSelect(ui, q, qi, header) : await askSingleSelect(ui, q, qi, header);
+		if (answer === undefined) return { answers, cancelled: true };
+		answers.push(answer);
+	}
+	return { answers, cancelled: false };
+}
+
+async function askSingleSelect(
+	ui: DialogUI,
+	q: AskQuestion,
+	questionIndex: number,
+	header: string,
+): Promise<AskAnswer | undefined> {
+	const options = q.options.map((_o, i) => formatOptionLine(q, i));
+	options.push(`${q.options.length + 1}. ${CUSTOM_ANSWER_LABEL}`);
+	const chosen = await ui.select(`${header}${q.question}`, options);
+	if (chosen == null) return undefined;
+	const idx = parseIndex(chosen, options.length);
+	// 宿主返回了清单外的东西与关掉对话框无法区分，一律当取消，不编造答案。
+	if (idx == null) return undefined;
+	if (idx < q.options.length) {
+		return { questionIndex, question: q.question, kind: "option", answer: q.options[idx].label };
+	}
+	const typed = await ui.input(`${header}${q.question}\n\nType your answer:`, "");
+	if (typed == null) return undefined;
+	return { questionIndex, question: q.question, kind: "custom", answer: typed };
+}
+
+const MULTI_INSTRUCTIONS = 'Enter the numbers of all that apply, comma-separated (e.g. "1,3"), or type a custom answer as plain text.';
+
+async function askMultiSelect(
+	ui: DialogUI,
+	q: AskQuestion,
+	questionIndex: number,
+	header: string,
+): Promise<AskAnswer | undefined> {
+	const list = q.options.map((_o, i) => formatOptionLine(q, i)).join("\n");
+	const value = await ui.input(`${header}${q.question}\n\n${list}\n\n${MULTI_INSTRUCTIONS}`, "1,3");
+	if (value == null) return undefined;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) {
+		// 空提交 = 一个都不选，与 TUI 里不勾任何项直接 Enter 同义。
+		return { questionIndex, question: q.question, kind: "multi", answer: null, selected: [] };
+	}
+	const tokens = trimmed.split(/[,\s]+/).filter((tok) => tok.length > 0);
+	const indices = tokens.map((tok) => (/^\d+\.?$/.test(tok) ? parseIndex(tok, q.options.length) : null));
+	if (indices.every((i): i is number => i != null)) {
+		const selected: string[] = [];
+		for (const i of indices) {
+			const label = q.options[i].label;
+			if (!selected.includes(label)) selected.push(label);
+		}
+		return { questionIndex, question: q.question, kind: "multi", answer: null, selected };
+	}
+	// 出现任何非编号 token（文字、或 "13" 这种越界编号）= 用户在打字回答，
+	// 原样保留为 custom，不静默丢弃。
+	return { questionIndex, question: q.question, kind: "custom", answer: trimmed };
+}