@bachi/pi-coder 1.0.0

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

@@ -0,0 +1,259 @@
+/**
+ * model.ts — 问卷的纯状态机（不 import pi / pi-tui），view.ts 只是它的一层
+ * 按键解码 + 渲染外壳。所有交互语义（tab 切换、光标、多选勾选、单选/多选/
+ * 自由输入的提交、提交页闸门、取消）都集中在这里，`node --test` 直接覆盖。
+ *
+ * 状态约定：
+ * - `currentTab` 0..n-1 是问题页；`n`（=questions.length）是提交页，**只有
+ *   多题（n>1）才有提交页**——单题选完即提交，没有可切换的页。
+ * - `cursor` 是当前问题页内的行号：0..options.length-1 是模型给的选项，
+ *   options.length 是自动追加的 "Type something." 哨兵行。
+ * - `toggles[i][j]` 是第 i 题多选下第 j 个选项的勾选态（单选不用）。
+ * - `answers[i]` 是第 i 题已提交的答案；重答覆盖旧值。
+ *
+ * reduce 原地改 state、返回 Outcome 告诉外壳下一步做什么（继续 / 进自由输入 /
+ * 出自由输入 / 提交 / 取消）。提交与取消的 result 都是**已答部分**的快照。
+ */
+
+import type { AskAnswer, AskParams, AskQuestion, AskResult } from "./types.ts";
+
+export interface QuestionnaireState {
+	readonly questions: AskQuestion[];
+	currentTab: number;
+	cursor: number;
+	inputMode: boolean;
+	answers: Array<AskAnswer | undefined>;
+	toggles: boolean[][];
+}
+
+export type Intent =
+	| { type: "up" }
+	| { type: "down" }
+	| { type: "nextTab" }
+	| { type: "prevTab" }
+	| { type: "toggle" }
+	| { type: "digit"; digit: number }
+	| { type: "confirm" }
+	| { type: "cancel" }
+	| { type: "inputSubmit"; text: string }
+	| { type: "inputCancel" };
+
+export type Outcome =
+	| { status: "continue" }
+	| { status: "enterInput" }
+	| { status: "exitInput" }
+	| { status: "submit"; result: AskResult }
+	| { status: "cancel"; result: AskResult };
+
+const CONTINUE: Outcome = { status: "continue" };
+
+export function createState(params: AskParams): QuestionnaireState {
+	return {
+		questions: params.questions,
+		currentTab: 0,
+		cursor: 0,
+		inputMode: false,
+		answers: params.questions.map(() => undefined),
+		toggles: params.questions.map((q) => q.options.map(() => false)),
+	};
+}
+
+/** 多题才有提交页。 */
+export function hasSubmitTab(state: QuestionnaireState): boolean {
+	return state.questions.length > 1;
+}
+
+export function isSubmitTab(state: QuestionnaireState): boolean {
+	return hasSubmitTab(state) && state.currentTab === state.questions.length;
+}
+
+/** 当前问题页的行数 = 选项数 + 1（哨兵行）。提交页无意义，返回 0。 */
+export function rowCount(state: QuestionnaireState): number {
+	const q = state.questions[state.currentTab];
+	return q ? q.options.length + 1 : 0;
+}
+
+export function allAnswered(state: QuestionnaireState): boolean {
+	return state.answers.every((a) => a !== undefined);
+}
+
+/** 未回答问题的 header 列表（提交页提示用）。 */
+export function unansweredHeaders(state: QuestionnaireState): string[] {
+	const headers: string[] = [];
+	for (let i = 0; i < state.questions.length; i++) {
+		if (state.answers[i] === undefined) headers.push(state.questions[i].header || `Q${i + 1}`);
+	}
+	return headers;
+}
+
+/** 已答部分（去掉 undefined）的快照，按题序。 */
+function compactAnswers(state: QuestionnaireState): AskAnswer[] {
+	return state.answers.filter((a): a is AskAnswer => a !== undefined);
+}
+
+function currentQuestion(state: QuestionnaireState): AskQuestion | undefined {
+	return state.questions[state.currentTab];
+}
+
+function selectedLabels(state: QuestionnaireState): string[] {
+	const q = currentQuestion(state);
+	if (!q) return [];
+	const toggles = state.toggles[state.currentTab];
+	const labels: string[] = [];
+	for (let i = 0; i < q.options.length; i++) {
+		if (toggles[i]) labels.push(q.options[i].label);
+	}
+	return labels;
+}
+
+/** 提交当前题后前进：单题直接提交；多题去下一题，最后一题去提交页。 */
+function advance(state: QuestionnaireState): Outcome {
+	if (state.questions.length === 1) {
+		return { status: "submit", result: { answers: compactAnswers(state), cancelled: false } };
+	}
+	if (state.currentTab < state.questions.length - 1) {
+		focusTab(state, state.currentTab + 1);
+	} else {
+		state.currentTab = state.questions.length; // 提交页
+		state.cursor = 0;
+	}
+	return CONTINUE;
+}
+
+/** 切到某页并按已有答案恢复光标位置（重答时停在原选择上）。 */
+function focusTab(state: QuestionnaireState, tab: number): void {
+	state.currentTab = tab;
+	state.cursor = 0;
+	state.inputMode = false;
+	const q = state.questions[tab];
+	const answer = state.answers[tab];
+	if (!q || !answer) return;
+	if (answer.kind === "custom") {
+		state.cursor = q.options.length; // 哨兵行
+	} else if (answer.kind === "option" && answer.answer != null) {
+		const idx = q.options.findIndex((o) => o.label === answer.answer);
+		if (idx >= 0) state.cursor = idx;
+	} else if (answer.kind === "multi" && answer.selected) {
+		const first = q.options.findIndex((o) => answer.selected!.includes(o.label));
+		if (first >= 0) state.cursor = first;
+	}
+}
+
+function recordOption(state: QuestionnaireState): void {
+	const q = currentQuestion(state);
+	if (!q) return;
+	const opt = q.options[state.cursor];
+	if (!opt) return;
+	state.answers[state.currentTab] = {
+		questionIndex: state.currentTab,
+		question: q.question,
+		kind: "option",
+		answer: opt.label,
+	};
+}
+
+function recordMulti(state: QuestionnaireState): void {
+	const q = currentQuestion(state);
+	if (!q) return;
+	state.answers[state.currentTab] = {
+		questionIndex: state.currentTab,
+		question: q.question,
+		kind: "multi",
+		answer: null,
+		selected: selectedLabels(state),
+	};
+}
+
+function recordCustom(state: QuestionnaireState, text: string): void {
+	const q = currentQuestion(state);
+	if (!q) return;
+	state.answers[state.currentTab] = {
+		questionIndex: state.currentTab,
+		question: q.question,
+		kind: "custom",
+		answer: text,
+	};
+}
+
+export function reduce(state: QuestionnaireState, intent: Intent): Outcome {
+	switch (intent.type) {
+		case "up": {
+			if (!isSubmitTab(state)) state.cursor = Math.max(0, state.cursor - 1);
+			return CONTINUE;
+		}
+		case "down": {
+			if (!isSubmitTab(state)) state.cursor = Math.min(rowCount(state) - 1, state.cursor + 1);
+			return CONTINUE;
+		}
+		case "nextTab":
+		case "prevTab": {
+			if (!hasSubmitTab(state)) return CONTINUE;
+			const total = state.questions.length + 1; // 含提交页
+			const delta = intent.type === "nextTab" ? 1 : -1;
+			const next = (state.currentTab + delta + total) % total;
+			focusTab(state, next);
+			return CONTINUE;
+		}
+		case "toggle": {
+			const q = currentQuestion(state);
+			if (!q || isSubmitTab(state) || !q.multiSelect) return CONTINUE;
+			if (state.cursor >= q.options.length) return CONTINUE; // 哨兵行不可勾
+			state.toggles[state.currentTab][state.cursor] = !state.toggles[state.currentTab][state.cursor];
+			return CONTINUE;
+		}
+		case "digit": {
+			const q = currentQuestion(state);
+			if (!q || isSubmitTab(state)) return CONTINUE;
+			const d = intent.digit;
+			if (d >= 1 && d <= q.options.length) {
+				if (q.multiSelect) {
+					state.cursor = d - 1;
+					state.toggles[state.currentTab][d - 1] = !state.toggles[state.currentTab][d - 1];
+					return CONTINUE;
+				}
+				state.cursor = d - 1;
+				recordOption(state);
+				return advance(state);
+			}
+			if (d === q.options.length + 1) {
+				state.cursor = q.options.length;
+				state.inputMode = true;
+				return { status: "enterInput" };
+			}
+			return CONTINUE;
+		}
+		case "confirm": {
+			if (isSubmitTab(state)) {
+				if (!allAnswered(state)) return CONTINUE;
+				return { status: "submit", result: { answers: compactAnswers(state), cancelled: false } };
+			}
+			const q = currentQuestion(state);
+			if (!q) return CONTINUE;
+			if (state.cursor === q.options.length) {
+				state.inputMode = true;
+				return { status: "enterInput" };
+			}
+			if (q.multiSelect) {
+				recordMulti(state);
+			} else {
+				recordOption(state);
+			}
+			return advance(state);
+		}
+		case "cancel":
+			return { status: "cancel", result: { answers: compactAnswers(state), cancelled: true } };
+		case "inputSubmit": {
+			const text = intent.text.trim();
+			if (text.length === 0) {
+				state.inputMode = false;
+				return { status: "exitInput" };
+			}
+			recordCustom(state, text);
+			state.inputMode = false;
+			return advance(state);
+		}
+		case "inputCancel":
+			state.inputMode = false;
+			return { status: "exitInput" };
+	}
+}

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

@@ -0,0 +1,49 @@
+/**
+ * schema.ts — ask_user_question 的 TypeBox 参数 schema（只在 pi 运行时加载）。
+ *
+ * 刻意**不设 maxLength**：pi 在 execute 之前用 schema 校验参数
+ * （pi-ai `validateToolArguments`），header/label 超长会让整次调用直接失败、
+ * 白烧一个回合；而 chip 标签截断显示毫无危害，所以长度上限交给
+ * validate.ts 的运行时归一化（截断 + 补 `…`），schema 的 description 里
+ * 仍然写明软上限教模型。数量约束（1-4 题、每题 2-4 项）**保留在 schema 里**：
+ * 悄悄丢掉第 5 个选项会歪曲模型本意，让它拿到明确校验错误去重试才对。
+ */
+
+import { Type } from "typebox";
+import { CUSTOM_ANSWER_LABEL, MAX_HEADER_LENGTH, MAX_LABEL_LENGTH, MAX_OPTIONS, MAX_QUESTIONS, MIN_OPTIONS } from "./types.ts";
+
+export const AskOptionSchema = Type.Object({
+	label: Type.String({
+		description: `Display text for this option that the user will see and select. Concise (1-5 words; soft limit ${MAX_LABEL_LENGTH} characters, longer labels are truncated in the UI). Do NOT author "${CUSTOM_ANSWER_LABEL}" or "Other" — reserved.`,
+	}),
+	description: Type.String({
+		description: "Explanation of what this option means or what will happen if chosen. Use it for trade-offs and implications.",
+	}),
+});
+
+export const AskQuestionSchema = Type.Object({
+	question: Type.String({
+		description: 'The complete question to ask the user. Clear, specific, ends with a question mark. Example: "Which library should we use for date formatting?" If multiSelect is true, phrase it accordingly, e.g. "Which features do you want to enable?"',
+	}),
+	header: Type.String({
+		description: `Very short chip/tag shown next to the question, max ${MAX_HEADER_LENGTH} characters (longer headers are truncated). Examples: "Auth method", "Library", "Approach".`,
+	}),
+	options: Type.Array(AskOptionSchema, {
+		minItems: MIN_OPTIONS,
+		maxItems: MAX_OPTIONS,
+		description: `The available choices, ${MIN_OPTIONS}-${MAX_OPTIONS} distinct mutually exclusive options (unless multiSelect). The "${CUSTOM_ANSWER_LABEL}" row is appended automatically — do NOT author it. If you recommend an option, put it first and append "(Recommended)" to its label.`,
+	}),
+	multiSelect: Type.Optional(
+		Type.Boolean({
+			description: "Set to true to allow the user to select multiple options instead of just one. Use when choices are not mutually exclusive. Default false.",
+		}),
+	),
+});
+
+export const AskParamsSchema = Type.Object({
+	questions: Type.Array(AskQuestionSchema, {
+		minItems: 1,
+		maxItems: MAX_QUESTIONS,
+		description: `Questions to ask the user (1-${MAX_QUESTIONS} per invocation). Group all clarifying questions into one invocation.`,
+	}),
+});

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

@@ -0,0 +1,86 @@
+/**
+ * types.ts — ask_user_question 的纯数据模型与常量（单一事实来源）。
+ *
+ * 刻意不 import typebox / pi / pi-tui：validate.ts / answers.ts / dialog.ts /
+ * model.ts 只依赖本文件，所以 `node --test` 能直接跑它们的单测（Node 的类型擦除
+ * 只擦标注、不解析运行时依赖）。TypeBox schema 单独放 schema.ts，只在 pi 运行时
+ * 被 index.ts 加载。
+ *
+ * 形状对齐 Claude Code 的 AskUserQuestion（1-4 个问题、每题 2-4 个带说明的选项、
+ * 可选 multiSelect），刻意砍掉参考实现（npm:@juicesharp/rpiv-ask-user-question）
+ * 里的 preview 侧栏、逐题 note、全局 note 与 i18n —— 自由文本由每题自动追加的
+ * "Type something." 哨兵行承担，够用且 UI 简单一个量级。
+ */
+
+/** 一次调用最多问几个问题。 */
+export const MAX_QUESTIONS = 4;
+/** 每题最少选项数。 */
+export const MIN_OPTIONS = 2;
+/** 每题最多选项数（不含自动追加的哨兵行）。 */
+export const MAX_OPTIONS = 4;
+/** 问题 chip 标签的显示上限；超长在运行时截断（不报错）。 */
+export const MAX_HEADER_LENGTH = 16;
+/** 选项 label 的显示上限；超长在运行时截断（不报错）。 */
+export const MAX_LABEL_LENGTH = 60;
+
+/** 每题自动追加的自由输入行。模型不许自己写这个 label（reserved_label 拒绝）。 */
+export const CUSTOM_ANSWER_LABEL = "Type something.";
+
+/**
+ * 保留 label："Other" 是因为模型被 Claude Code 条件化、总想自己写一个 Other 选项，
+ * 而这里哨兵行是唯一来源；CUSTOM_ANSWER_LABEL 是哨兵行本身。
+ */
+export const RESERVED_LABELS: readonly string[] = ["Other", CUSTOM_ANSWER_LABEL];
+
+export interface AskOption {
+	label: string;
+	description: string;
+}
+
+export interface AskQuestion {
+	question: string;
+	header: string;
+	options: AskOption[];
+	multiSelect?: boolean;
+}
+
+export interface AskParams {
+	questions: AskQuestion[];
+}
+
+/**
+ * 单题答案意图（判别联合，`kind` 是唯一判别子）：
+ * - `option`：单选，选中模型给的选项；`answer` = 选项 label
+ * - `custom`：用户在 "Type something." 行自由输入；`answer` = 输入文本
+ * - `multi`：多选提交；`selected` = 选中的 label 列表，`answer` 恒为 null
+ */
+export type AskAnswerKind = "option" | "custom" | "multi";
+
+export interface AskAnswer {
+	questionIndex: number;
+	question: string;
+	kind: AskAnswerKind;
+	answer: string | null;
+	selected?: string[];
+}
+
+/**
+ * 失败码。`no_ui` / `no_dialog_ui` 依赖宿主能力、在执行路径上判定；
+ * 其余由 validateQuestionnaire 产出。
+ */
+export type AskErrorCode =
+	| "no_ui"
+	| "no_dialog_ui"
+	| "no_questions"
+	| "too_many_questions"
+	| "duplicate_question"
+	| "too_few_options"
+	| "too_many_options"
+	| "reserved_label"
+	| "duplicate_option_label";
+
+export interface AskResult {
+	answers: AskAnswer[];
+	cancelled: boolean;
+	error?: AskErrorCode;
+}

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

@@ -0,0 +1,183 @@
+/**
+ * Tests for validate.ts — 归一化（行终止符 / 单行化 / 截断）+ 运行时校验。
+ *
+ * Run with:  node --test clients/pi/extensions/ask-user-question/validate.test.ts
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+	ERROR_DUPLICATE_OPTION_LABEL,
+	ERROR_DUPLICATE_QUESTION,
+	ERROR_NO_QUESTIONS,
+	ERROR_RESERVED_LABEL,
+	ERROR_TOO_FEW_OPTIONS,
+	ERROR_TOO_MANY_OPTIONS,
+	ERROR_TOO_MANY_QUESTIONS,
+	normalizeLineTerminators,
+	normalizeParams,
+	validateQuestionnaire,
+} from "./validate.ts";
+import { MAX_HEADER_LENGTH, MAX_LABEL_LENGTH, type AskParams } from "./types.ts";
+
+function option(label: string, description = "desc") {
+	return { label, description };
+}
+
+function params(overrides: Partial<AskParams> = {}): AskParams {
+	return {
+		questions: [
+			{
+				question: "Which library should we use?",
+				header: "Library",
+				options: [option("date-fns"), option("dayjs")],
+			},
+		],
+		...overrides,
+	};
+}
+
+test("normalizeLineTerminators: CRLF 折成 LF，落单 CR 删除", () => {
+	assert.equal(normalizeLineTerminators("a\r\nb"), "a\nb");
+	assert.equal(normalizeLineTerminators("GEMBA\r_LOG\r_FILE"), "GEMBA_LOG_FILE");
+	assert.equal(normalizeLineTerminators("a\nb"), "a\nb");
+});
+
+test("normalizeParams: header 超长截断补 …", () => {
+	const long = "x".repeat(MAX_HEADER_LENGTH + 10);
+	const out = normalizeParams(params({ questions: [{ ...params().questions[0], header: long }] }));
+	const header = out.questions[0].header;
+	assert.equal(header.length, MAX_HEADER_LENGTH);
+	assert.ok(header.endsWith("…"));
+});
+
+test("normalizeParams: label 超长截断补 …", () => {
+	const long = "y".repeat(MAX_LABEL_LENGTH + 5);
+	const out = normalizeParams(
+		params({ questions: [{ ...params().questions[0], options: [option(long), option("b")] }] }),
+	);
+	assert.equal(out.questions[0].options[0].label.length, MAX_LABEL_LENGTH);
+	assert.ok(out.questions[0].options[0].label.endsWith("…"));
+});
+
+test("normalizeParams: header/label/description 单行化（空白串折叠），question 保留换行", () => {
+	const out = normalizeParams(
+		params({
+			questions: [
+				{
+					question: "line one\r\nline two",
+					header: "  Auth\r\nmethod  ",
+					options: [{ label: "  A\r\nB ", description: "d1\n\n  d2 " }],
+				},
+				{ ...params().questions[0], question: "other" },
+			],
+		}),
+	);
+	assert.equal(out.questions[0].question, "line one\nline two");
+	assert.equal(out.questions[0].header, "Auth method");
+	assert.equal(out.questions[0].options[0].label, "A B");
+	assert.equal(out.questions[0].options[0].description, "d1 d2");
+});
+
+test("normalizeParams: multiSelect 归一成布尔，不改入参", () => {
+	const input = params({ questions: [{ ...params().questions[0], multiSelect: undefined }] });
+	const out = normalizeParams(input);
+	assert.equal(out.questions[0].multiSelect, false);
+	assert.equal(input.questions[0].multiSelect, undefined);
+});
+
+test("validateQuestionnaire: 合法问卷通过", () => {
+	assert.deepEqual(validateQuestionnaire(normalizeParams(params())), { ok: true });
+});
+
+test("validateQuestionnaire: 空 questions → no_questions", () => {
+	const result = validateQuestionnaire({ questions: [] });
+	assert.equal(result.ok, false);
+	if (!result.ok) {
+		assert.equal(result.error, "no_questions");
+		assert.equal(result.message, ERROR_NO_QUESTIONS);
+	}
+});
+
+test("validateQuestionnaire: 超过 4 题 → too_many_questions", () => {
+	const q = params().questions[0];
+	const five = {
+		questions: [1, 2, 3, 4, 5].map((i) => ({ ...q, question: `Q${i}?`, header: `H${i}` })),
+	};
+	const result = validateQuestionnaire(five);
+	assert.equal(result.ok, false);
+	if (!result.ok) {
+		assert.equal(result.error, "too_many_questions");
+		assert.equal(result.message, ERROR_TOO_MANY_QUESTIONS);
+	}
+});
+
+test("validateQuestionnaire: 重复问题文本 → duplicate_question", () => {
+	const q = params().questions[0];
+	const result = validateQuestionnaire({ questions: [q, { ...q, header: "Again" }] });
+	assert.equal(result.ok, false);
+	if (!result.ok) {
+		assert.equal(result.error, "duplicate_question");
+		assert.equal(result.message, ERROR_DUPLICATE_QUESTION);
+	}
+});
+
+test("validateQuestionnaire: 选项太少 / 太多", () => {
+	const q = params().questions[0];
+	const tooFew = validateQuestionnaire({ questions: [{ ...q, options: [option("only")] }] });
+	assert.equal(tooFew.ok, false);
+	if (!tooFew.ok) {
+		assert.equal(tooFew.error, "too_few_options");
+		assert.equal(tooFew.message, ERROR_TOO_FEW_OPTIONS);
+	}
+	const tooMany = validateQuestionnaire({
+		questions: [{ ...q, options: [option("a"), option("b"), option("c"), option("d"), option("e")] }],
+	});
+	assert.equal(tooMany.ok, false);
+	if (!tooMany.ok) {
+		assert.equal(tooMany.error, "too_many_options");
+		assert.equal(tooMany.message, ERROR_TOO_MANY_OPTIONS);
+	}
+});
+
+test("validateQuestionnaire: 保留 label（Other / Type something.）被拒", () => {
+	for (const label of ["Other", "Type something."]) {
+		const result = validateQuestionnaire({
+			questions: [{ ...params().questions[0], options: [option(label), option("b")] }],
+		});
+		assert.equal(result.ok, false, `label ${label} should be rejected`);
+		if (!result.ok) {
+			assert.equal(result.error, "reserved_label");
+			assert.equal(result.message, ERROR_RESERVED_LABEL);
+		}
+	}
+});
+
+test("validateQuestionnaire: 同题重复 label → duplicate_option_label", () => {
+	const result = validateQuestionnaire({
+		questions: [{ ...params().questions[0], options: [option("same"), option("same")] }],
+	});
+	assert.equal(result.ok, false);
+	if (!result.ok) {
+		assert.equal(result.error, "duplicate_option_label");
+		assert.equal(result.message, ERROR_DUPLICATE_OPTION_LABEL);
+	}
+});
+
+test("reserved_label 短路在 duplicate_option_label 之前（两个 Other）", () => {
+	const result = validateQuestionnaire({
+		questions: [{ ...params().questions[0], options: [option("Other"), option("Other")] }],
+	});
+	assert.equal(result.ok, false);
+	if (!result.ok) assert.equal(result.error, "reserved_label");
+});
+
+test("归一化后再校验：\"Other\\r\" 不能溜过 reserved_label", () => {
+	const normalized = normalizeParams({
+		questions: [{ ...params().questions[0], options: [option("Other\r"), option("b")] }],
+	});
+	assert.equal(normalized.questions[0].options[0].label, "Other");
+	const result = validateQuestionnaire(normalized);
+	assert.equal(result.ok, false);
+	if (!result.ok) assert.equal(result.error, "reserved_label");
+});

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

@@ -0,0 +1,110 @@
+/**
+ * validate.ts — 参数归一化 + 运行时校验（纯函数，不 import pi / pi-tui / typebox）。
+ *
+ * 归一化在 execute 入口跑一次、校验之前，所以下游所有消费者（校验器、TUI、
+ * 对话框回退、答案封装）看到的都是同一份干净文本：
+ * - 行终止符：`\r\n` → `\n`、落单 `\r` 删除（CR 是光标控制字节不是文本，
+ *   直接进渲染会把行首指针冲掉；与 pi 自己的显示归一化口径一致）
+ * - header / label / description 是单行 chip / 列表行，空白串（含换行）折叠成
+ *   一个空格再截断；question 保留换行（渲染端逐行折行）
+ * - 截断补 `…`，上限见 types.ts（刻意不在 schema 里设 maxLength，理由见 schema.ts）
+ *
+ * 校验覆盖数量与重复/保留 label；`reserved_label` 必须短路在
+ * `duplicate_option_label` 之前（两个 "Other" 首先是保留字问题）。
+ */
+
+import {
+	MAX_HEADER_LENGTH,
+	MAX_LABEL_LENGTH,
+	MAX_OPTIONS,
+	MAX_QUESTIONS,
+	MIN_OPTIONS,
+	RESERVED_LABELS,
+	type AskErrorCode,
+	type AskParams,
+} from "./types.ts";
+
+export const ERROR_NO_QUESTIONS = "Error: At least one question is required";
+export const ERROR_TOO_MANY_QUESTIONS = `Error: At most ${MAX_QUESTIONS} questions are allowed per invocation — group them into one call with fewer questions`;
+export const ERROR_DUPLICATE_QUESTION = "Error: Question text must be unique within an invocation";
+export const ERROR_TOO_FEW_OPTIONS = `Error: Each question requires at least ${MIN_OPTIONS} options`;
+export const ERROR_TOO_MANY_OPTIONS = `Error: Each question allows at most ${MAX_OPTIONS} options`;
+export const ERROR_RESERVED_LABEL = `Error: Option label is reserved (${RESERVED_LABELS.join(", ")}) — the custom-answer row is appended automatically`;
+export const ERROR_DUPLICATE_OPTION_LABEL = "Error: Option labels must be unique within a question";
+
+const RESERVED_LABEL_SET: ReadonlySet<string> = new Set(RESERVED_LABELS);
+
+export type ValidationResult = { ok: true } | { ok: false; error: AskErrorCode; message: string };
+
+/** `\r\n` → `\n`，落单 `\r` 删除（不是空格：会在词中间留幻影间隙）。 */
+export function normalizeLineTerminators(text: string): string {
+	return text.replace(/\r\n/g, "\n").replace(/\r/g, "");
+}
+
+/** 单行化：行终止符归一 + 空白串折叠成一个空格 + 去首尾。 */
+function toSingleLine(text: string): string {
+	return normalizeLineTerminators(text).replace(/\s+/g, " ").trim();
+}
+
+/** 按**字符数**截断到 max，超长补 `…`（max ≥ 2 才有意义）。 */
+function clip(text: string, max: number): string {
+	if (text.length <= max) return text;
+	return `${text.slice(0, max - 1)}…`;
+}
+
+/**
+ * 返回参数副本：所有展示字符串归一化，header/label 截断。纯函数，不改入参。
+ * 保留 label 的**比较**发生在归一化之后（`"Other\r"` 不能溜过 reserved_label）。
+ */
+export function normalizeParams(params: AskParams): AskParams {
+	return {
+		questions: params.questions.map((q) => ({
+			question: normalizeLineTerminators(q.question).trim(),
+			header: clip(toSingleLine(q.header), MAX_HEADER_LENGTH),
+			multiSelect: q.multiSelect === true,
+			options: q.options.map((o) => ({
+				label: clip(toSingleLine(o.label), MAX_LABEL_LENGTH),
+				description: toSingleLine(o.description),
+			})),
+		})),
+	};
+}
+
+/** 纯运行时校验器。no_ui / no_dialog_ui 依赖宿主能力，留在执行路径上判。 */
+export function validateQuestionnaire(params: AskParams): ValidationResult {
+	if (params.questions.length === 0) {
+		return { ok: false, error: "no_questions", message: ERROR_NO_QUESTIONS };
+	}
+	if (params.questions.length > MAX_QUESTIONS) {
+		return { ok: false, error: "too_many_questions", message: ERROR_TOO_MANY_QUESTIONS };
+	}
+
+	const seenQuestions = new Set<string>();
+	for (const q of params.questions) {
+		if (seenQuestions.has(q.question)) {
+			return { ok: false, error: "duplicate_question", message: ERROR_DUPLICATE_QUESTION };
+		}
+		seenQuestions.add(q.question);
+	}
+
+	for (const q of params.questions) {
+		if (q.options.length < MIN_OPTIONS) {
+			return { ok: false, error: "too_few_options", message: ERROR_TOO_FEW_OPTIONS };
+		}
+		if (q.options.length > MAX_OPTIONS) {
+			return { ok: false, error: "too_many_options", message: ERROR_TOO_MANY_OPTIONS };
+		}
+		const seenLabels = new Set<string>();
+		for (const o of q.options) {
+			if (RESERVED_LABEL_SET.has(o.label)) {
+				return { ok: false, error: "reserved_label", message: ERROR_RESERVED_LABEL };
+			}
+			if (seenLabels.has(o.label)) {
+				return { ok: false, error: "duplicate_option_label", message: ERROR_DUPLICATE_OPTION_LABEL };
+			}
+			seenLabels.add(o.label);
+		}
+	}
+
+	return { ok: true };
+}