@zhushanwen/pi-ask-user 0.0.4 → 0.2.0

package/src/index.ts

@@ -1,9 +1,18 @@
 // src/index.ts
-import type { AgentToolResult, ExtensionAPI, ExtensionContext, ToolRenderResultOptions } from "@mariozechner/pi-coding-agent";
-import { Box, Text, TruncatedText, truncateToWidth } from "@mariozechner/pi-tui";
+import { Box, Text, TruncatedText, truncateToWidth } from "@earendil-works/pi-tui";
+import type { AgentToolResult, AgentToolUpdateCallback, ExtensionAPI, ExtensionContext, ToolRenderResultOptions } from "@mariozechner/pi-coding-agent";
 import { type Static } from "@sinclair/typebox";
+import {
+	type AskUserAnswers,
+	askUserInteract,
+	type AskUserQuestion,
+	getAskUserAnswer,
+	getAskUserComment,
+	getAskUserOther,
+} from "@xyz-agent/extension-protocol";
 
 import { AskUserComponent } from "./component";
+import { formatAnswer, parseAnswerParts } from "./answer-format";
 import {
 	type AskUserDetails,
 	type ErrorDetails,
@@ -22,9 +31,53 @@ import { validateInput } from "./validate";
  */
 type ExecuteResult = AgentToolResult<AskUserDetails> & { isError?: boolean };
 
+/** 禁用 ask_user 工具（headless / RPC 通道不可用时调用，防 LLM 反复重试）。 */
+function disableAskUser(pi: ExtensionAPI): void {
+	pi.setActiveTools(
+		pi
+			.getAllTools()
+			.map((t: { name: string }) => t.name)
+			.filter((n: string) => n !== "ask_user"),
+	);
+}
+
+/** 构造 cancelled 结果（用户取消 / abort / 校验失败共用）。 */
+function cancelledResult(questions: Question[], text: string, isError = false): ExecuteResult {
+	return {
+		content: [{ type: "text" as const, text }],
+		isError: isError || undefined,
+		details: { questions, answers: {}, cancelled: true } satisfies Result,
+	};
+}
+
+/** TUI 模式交互（自定义 Component 实时交互）。 */
+async function runTuiInteraction(
+	questions: Question[],
+	signal: AbortSignal | undefined,
+	ctx: ExtensionContext,
+): Promise<Result | null> {
+	return ctx.ui.custom<Result | null>(
+		(tui: unknown, theme: unknown, _kb: unknown, done: (r: Result | null) => void) => {
+			const comp = new AskUserComponent(
+				questions,
+				tui as { requestRender(): void },
+				theme as ThemeLike,
+				done,
+			);
+			// signal abort 监听（spec FR-10）：走组件 cancel() 复用 _resolved 守卫，
+			// 避免用户已 submit/cancel 后 signal 才 abort 二次调 done（FR-12 竞态）
+			if (signal) {
+				signal.addEventListener("abort", () => comp.cancel(), { once: true });
+			}
+			return comp;
+		},
+		// 不传 options → inline 渲染（spec FR-3）
+	);
+}
+
 /**
  * expanded 渲染辅助：展开某问题的全部选项，用 ●/○ 标记是否被选中（spec FR-9）。
- * 选中判定：answer 含该 option label（answer 形如 "Postgres" / "A, B" / "X — comment"）。
+ * 选中判定：用 parseAnswerParts 精确匹配 label（而非子串匹配），避免 "A" 是 "AB" 子串时的误判。
  * 返回 TruncatedText 数组供 box.addChild 展开。
  */
 function renderExpandedOptions(
@@ -32,9 +85,11 @@ function renderExpandedOptions(
 	answer: string,
 	theme: ThemeLike,
 ): TruncatedText[] {
-	const answerTokens = new Set(answer.split(/\s*[,—]\s*|\s*,\s*/).filter(Boolean));
+	const labels = q.options.map((o: Option) => o.label);
+	const { selected } = parseAnswerParts(answer, labels);
+	const selectedSet = new Set(selected);
 	const mark = (opt: Option): string =>
-		answerTokens.has(opt.label) || answer.includes(opt.label)
+		selectedSet.has(opt.label)
 			? theme.fg("success", "●")
 			: theme.fg("dim", "○");
 	// 只展开真实选项（不含自动追加的 Other）；Other 文本单独显示
@@ -51,6 +106,107 @@ function renderExpandedOptions(
 	return out;
 }
 
+/**
+ * 把 ask-user 内部 Question[] 映射为协议包 AskUserQuestion[]（RPC 交互声明）。
+ *
+ * ask-user 的 Question.options 必填且只有 label/description（无 value 字段），
+ * 协议的 AskUserOption.value 缺失时前端用 label 做回传值——与 ask-user 语义一致
+ * （TUI 版 buildResult 也是用 label 拼 answers）。
+ * allowOther 固定 true：ask-user 无条件自动追加 Other（schema 不暴露此字段）。
+ */
+function toProtoQuestions(questions: Question[]): AskUserQuestion[] {
+	return questions.map((q: Question) => ({
+		header: q.header,
+		question: q.question,
+		context: q.context,
+		options: q.options.map((o: Option) => ({
+			label: o.label,
+			value: o.label, // ask-user 用 label 做回传值（与 TUI buildResult 语义一致）
+			description: o.description,
+		})),
+		multiSelect: q.multiSelect,
+		allowOther: true,
+		allowComment: q.allowComment ?? false,
+	}));
+}
+
+/**
+ * 把协议包 AskUserAnswers 转换为 ask-user 内部 Result.answers。
+ *
+ * 协议格式：key=header/question, 单选=string, 多选=JSON数组, Other=__other, comment=__comment
+ * ask-user 格式：key=question 全文, value=逗号分隔 label + Other, comment 内联（` — `）
+ *
+ * 拼装逻辑复用 formatAnswer（与 TUI 版 getAnswerText 共享同一格式函数），
+ * 确保 RPC 和 TUI 两条路径产出的 Result.answers 格式一致。
+ */
+function protoAnswersToResult(
+	questions: Question[],
+	protoQuestions: AskUserQuestion[],
+	answers: AskUserAnswers,
+): Result["answers"] {
+	const out: Record<string, string> = {};
+	for (let i = 0; i < questions.length; i++) {
+		const q = questions[i]!;
+		const iq = protoQuestions[i]!;
+		const selected = getAskUserAnswer(answers, iq);
+		const other = getAskUserOther(answers, iq);
+		const comment = getAskUserComment(answers, iq);
+
+		const parts: string[] = [];
+		if (Array.isArray(selected)) {
+			// 多选按 question.options 中的定义顺序排序（S#3），
+			// 与 TUI 版 submit-view.ts 的 selectedIndices.sort() 语义一致，
+			// 确保 RPC 和 TUI 产出相同文本（"A, C" 而非前端回传顺序的 "C, A"）。
+			const orderMap = new Map(q.options.map((o: Option, idx: number) => [o.label, idx]));
+			const unknownOrder = q.options.length;
+			parts.push(...[...selected].sort((a, b) => {
+				const ai = orderMap.get(a) ?? unknownOrder;
+				const bi = orderMap.get(b) ?? unknownOrder;
+				return ai - bi;
+			}));
+		} else if (selected) {
+			parts.push(selected);
+		}
+		if (other) parts.push(other);
+		const formatted = formatAnswer(parts, comment);
+		if (formatted !== null) out[q.question] = formatted;
+	}
+	return out;
+}
+
+/**
+ * RPC 模式（xyz-agent GUI）交互入口。
+ *
+ * 走 askUserInteract（select 通道 + ASK_USER_MARKER），前端 AskUserOverlay 渲染富交互 UI。
+ * 返回 Result（正常/取消），或抛错（select 异常 / 非 RPC 模式调用了此函数）。
+ *
+ * 注意：从 ExtensionContext 构造 GuiContext 子集传入，而非直接传 ctx——
+ * ExtensionContext.ui.custom 的泛型签名与 GuiContext.ui.custom 不兼容（前者复杂泛型，后者简化签名），
+ * 直接传会导致类型不兼容。GuiContext 只需要 mode/hasUI/ui.select，构造最小子集避免签名冲突。
+ */
+async function runRpcInteraction(
+	questions: Question[],
+	signal: AbortSignal | undefined,
+	ctx: ExtensionContext,
+): Promise<Result> {
+	const protoQuestions = toProtoQuestions(questions);
+	const guiCtx = {
+		mode: ctx.mode,
+		hasUI: ctx.hasUI,
+		ui: { select: ctx.ui.select.bind(ctx.ui) },
+	};
+	const answers = await askUserInteract(guiCtx, protoQuestions, { signal, allowCancel: true });
+
+	if (answers === null) {
+		return { questions, answers: {}, cancelled: true };
+	}
+	return {
+		questions,
+		answers: protoAnswersToResult(questions, protoQuestions, answers),
+		cancelled: false,
+	};
+}
+
 export default function (pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "ask_user",
@@ -76,83 +232,58 @@ If you recommend an option, prefix its label with "(Recommended)" and list it fi
 			_toolCallId: string,
 			params: Static<typeof InputSchema>,
 			signal: AbortSignal | undefined,
-			_onUpdate: unknown,
+			_onUpdate: AgentToolUpdateCallback<AskUserDetails> | undefined,
 			ctx: ExtensionContext,
 		): Promise<ExecuteResult> {
 			const questions = params.questions;
 
-			// 1. 参数校验（spec FR-2）→ isError
+			// 1. 参数校验（spec FR-2）
 			const validationError = validateInput(questions);
 			if (validationError) {
-				return {
-					content: [{ type: "text" as const, text: `Error: ${validationError}` }],
-					isError: true,
-					details: { questions, answers: {}, cancelled: true } satisfies Result,
-				};
+				return cancelledResult(questions, `Error: ${validationError}`, true);
 			}
 
-			// 2. Headless 检查（spec FR-8）→ isError + 禁用工具
-			if (!ctx.hasUI) {
-				pi.setActiveTools(
-					pi
-						.getAllTools()
-						.map((t: { name: string }) => t.name)
-						.filter((n: string) => n !== "ask_user"),
+			// 2. Headless 检查（spec FR-8）：mode 非 tui 非 rpc = 无交互通道
+			if (ctx.mode !== "tui" && ctx.mode !== "rpc") {
+				disableAskUser(pi);
+				return cancelledResult(
+					questions,
+					"Error: ask_user requires an interactive session. The tool has been disabled for this session. Do not retry — proceed without user input (make a defensible decision and state it) or wait for the user to reconnect.",
+					true,
 				);
-				return {
-					content: [
-						{
-							type: "text" as const,
-							text: "Error: ask_user requires an interactive session. The tool has been disabled for this session. Do not retry — proceed without user input (make a defensible decision and state it) or wait for the user to reconnect.",
-						},
-					],
-					isError: true,
-					details: { questions, answers: {}, cancelled: true } satisfies Result,
-				};
 			}
 
-			// 3. Signal abort 入口检查（spec FR-10）
+			// 3. Signal abort 入口检查（spec FR-10）。
+			// abort 是 agent 被外部终止（goal 取消 / context compact / session 切换），
+			// 不是用户意图——文案必须区别于 step 5 的用户取消，避免 LLM 俊等用户。
 			if (signal?.aborted) {
-				return {
-					content: [
-						{
-							type: "text" as const,
-							text: "User cancelled. Do not assume an answer or continue the task — wait for new instructions or re-ask with refined options if the decision is still required.",
-						},
-					],
-					details: { questions, answers: {}, cancelled: true } satisfies Result,
-				};
+				return cancelledResult(
+					questions,
+					"Agent aborted (goal cancelled, context compacted, or session switched). Do not assume an answer; do not retry ask_user — propagate the abort, or wait for new instructions if the decision is still required.",
+				);
 			}
 
-			// 4. 顶层 try/catch（spec FR-13）
+			// 4. 交互执行：TUI 走 ctx.ui.custom，RPC（xyz-agent GUI）走 askUserInteract。
+			// 注意：hasUI 在 TUI 和 RPC 模式都为 true（dialog-capable），不能用于区分——
+			// 用 ctx.mode === 'rpc' 判定 GUI 渲染通道。
+			const useRpc = ctx.mode === "rpc";
 			let result: Result | null;
 			try {
-				result = await ctx.ui.custom<Result | null>(
-					(tui: unknown, theme: unknown, _kb: unknown, done: (r: Result | null) => void) => {
-						const comp = new AskUserComponent(
-							questions,
-							tui as { requestRender(): void },
-							theme as ThemeLike,
-							done,
-						);
-						// signal abort 监听（spec FR-10）：走组件 cancel() 复用 _resolved 守卫，
-						// 避免用户已 submit/cancel 后 signal 才 abort 二次调 done（FR-12 竞态）
-						if (signal) {
-							signal.addEventListener("abort", () => comp.cancel(), { once: true });
-						}
-						return comp;
-					},
-					// 不传 options → inline 渲染（spec FR-3）
-				);
+				result = useRpc
+					? await runRpcInteraction(questions, signal, ctx)
+					: await runTuiInteraction(questions, signal, ctx);
 			} catch (err) {
+				// RPC 通道不可用（真 headless / select 缺失）→ 禁用工具（spec FR-8）。
+				// TUI 分支不禁用——custom 抛错通常是组件临时故障，允许 LLM 重试。
 				const message = err instanceof Error ? err.message : String(err);
+				if (useRpc) disableAskUser(pi);
 				return {
-					content: [
-						{
-							type: "text" as const,
-							text: `ask_user failed: ${message}. Treat as cancelled — do not assume an answer; retry the call with corrected parameters, or proceed with a defensible decision if the user cannot be reached.`,
-						},
-					],
+					content: [{
+						type: "text" as const,
+						text: useRpc
+							? `ask_user failed: ${message}. The tool has been disabled for this session. Do not retry — proceed without user input (make a defensible decision and state it) or wait for the user to reconnect.`
+							: `ask_user failed: ${message}. Treat as cancelled — do not assume an answer; retry the call with corrected parameters, or proceed with a defensible decision if the user cannot be reached.`,
+					}],
 					isError: true,
 					details: { error: message } satisfies ErrorDetails,
 				};
@@ -160,15 +291,10 @@ If you recommend an option, prefix its label with "(Recommended)" and list it fi
 
 			// 5. 取消（null / cancelled）
 			if (result === null || result.cancelled) {
-				return {
-					content: [
-						{
-							type: "text" as const,
-							text: "User cancelled. Do not assume an answer or continue the task — wait for new instructions or re-ask with refined options if the decision is still required.",
-						},
-					],
-					details: { questions, answers: {}, cancelled: true } satisfies Result,
-				};
+				return cancelledResult(
+					questions,
+					"User cancelled. Do not assume an answer or continue the task — wait for new instructions or re-ask with refined options if the decision is still required.",
+				);
 			}
 
 			// 6. 正常返回

package/src/question-view.ts

@@ -2,6 +2,7 @@
 import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
 
 import {
+	isHighSurrogate,
 	OTHER_LABEL,
 	type Question,
 	type QuestionState,
@@ -9,18 +10,51 @@ import {
 	SPLIT_PANE_MIN_WIDTH,
 	SPLIT_PANE_RIGHT_MIN,
 	SPLIT_PANE_SEPARATOR,
+	SURROGATE_PAIR_LEN,
 	type ThemeLike,
 } from "./types";
 
+const SPLIT_PANE_LEFT_RATIO = 0.42;
+const DESCRIPTION_INDENT_MULTI = 10;
+const DESCRIPTION_INDENT_SINGLE = 8;
+const PREVIEW_MIN_WIDTH = 10;
+const QUESTION_TEXT_MARGIN = 2;
+
 export interface DisplayOption {
 	label: string;
 	description?: string;
 	isOther?: boolean;
 }
 
+/** 渲染上下文——收拢 q/state/theme/width 四个总是成对出现的参数。
+ *  draftText 从 state.draftText 取（不再重复传递）。 */
+export interface RenderContext {
+	question: Question;
+	state: QuestionState;
+	theme: ThemeLike;
+	width: number;
+	/** 单问题模式（无 Tab 提示）。 */
+	isSingle: boolean;
+}
+
 /** Other 自由输入 / 已保存预览的软换行行数上限。超出则截断并加省略号。 */
 const MAX_EDITOR_LINES = 5;
 
+/**
+ * 渲染编辑器文本，光标位置用反色高亮（ANSI SGR 7/27），不占额外列。
+ * surrogate pair 安全：光标在高代理前时反色高亮整个 code point（2 个 code unit），
+ * 与光标移动/Backspace 的跳过逻辑对称，避免拆散 emoji 导致终端显示替换字符。
+ * 光标在文本末尾（超出范围）时反色高亮一个空格占位。
+ */
+function renderCursorText(text: string, cursorPos: number): string {
+	const before = text.slice(0, cursorPos);
+	// 光标在高代理前 → 反色高亮整个 surrogate pair
+	const charLen = isHighSurrogate(text, cursorPos) ? SURROGATE_PAIR_LEN : 1;
+	const charAtCursor = text.slice(cursorPos, cursorPos + charLen) || " ";
+	const after = text.slice(cursorPos + charLen);
+	return `${before}\x1b[7m${charAtCursor}\x1b[27m${after}`;
+}
+
 /**
  * 把一段带样式的文本按 availWidth 软换行输出为多行，最多 maxLines 行。
  * - 首行前缀 lead（如 "> [ ] "），后续行用等宽空格缩进到 input 起始列对齐。
@@ -29,7 +63,7 @@ const MAX_EDITOR_LINES = 5;
  *
  * @param push      输出回调（通常为带 truncateToWidth 的 add，提供安全兜底）
  * @param lead      首行前缀（含选中标记 / 勾选框）
- * @param content   待换行展示的已样式化文本（可含 ANSI + 末尾光标 █），为空则只输出 lead
+ * @param content   待换行展示的已样式化文本（可含 ANSI + 末尾反色光标），为空则只输出 lead
  * @param availWidth 单行可用宽度
  * @param maxLines  最多行数
  */
@@ -71,7 +105,7 @@ export function getSplitPaneWidths(width: number): { left: number; right: number
 	if (width < SPLIT_PANE_MIN_WIDTH) return null;
 	const available = width - SPLIT_PANE_SEPARATOR.length;
 	if (available < SPLIT_PANE_LEFT_MIN + SPLIT_PANE_RIGHT_MIN) return null;
-	const preferredLeft = Math.floor(available * 0.42);
+	const preferredLeft = Math.floor(available * SPLIT_PANE_LEFT_RATIO);
 	const left = Math.max(
 		SPLIT_PANE_LEFT_MIN,
 		Math.min(preferredLeft, available - SPLIT_PANE_RIGHT_MIN),
@@ -81,18 +115,18 @@ export function getSplitPaneWidths(width: number): { left: number; right: number
 	return { left, right };
 }
 
+/** 编辑器底部操作提示：随实现能力更新（实现偏差 D-005 已支持光标移动）。
+ *  反色光标占位已暗示可输入，故突出新增的方向键/移动能力。 */
+const EDITOR_HINT = " ←/→ Home/End move · Backspace deletes · Enter submit · Esc back";
+
 /** 构建选项列表行（不含分屏预览）。hideDescriptions 用于分屏模式左列。
- *  freeform 模式下，Other 行**原地**变 [ ] <input>█（多选）/ <input>█（单选），
+ *  freeform 模式下，Other 行**原地**变 [ ] <input> 反色光标（多选）/ <input> 反色光标（单选），
  *  不再依赖 buildEditorBlock 的下方独立编辑块。 */
 function buildOptionLines(
-	q: Question,
-	state: QuestionState,
-	theme: ThemeLike,
-	width: number,
+	ctx: RenderContext,
 	hideDescriptions: boolean,
-	editorText: string = "",
 ): string[] {
-	const t = theme;
+	const { question: q, state, theme: t, width } = ctx;
 	const opts = allOptions(q);
 	const lines: string[] = [];
 	const add = (s: string): void => {
@@ -101,7 +135,9 @@ function buildOptionLines(
 
 	for (let i = 0; i < opts.length; i++) {
 		const opt = opts[i]!;
-		const isSelected = i === state.cursorIndex;
+		// 编辑器模式下用 savedOptionsCursorIndex 判断选项高亮，cursorIndex 此时是文本光标
+		const activeOptionCursor = (state.mode === "freeform" || state.mode === "comment") ? state.savedOptionsCursorIndex : state.cursorIndex;
+		const isSelected = i === activeOptionCursor;
 		const isOther = opt.isOther === true;
 		const prefix = isSelected ? t.fg("accent", ">") : " ";
 
@@ -115,15 +151,16 @@ function buildOptionLines(
 				const num = i + 1;
 				const lead = `${prefix} ${marker} `;
 				const avail = Math.max(1, width - visibleWidth(lead));
-				// 编号 + 文本 + 末尾光标 █ 整体软换行（空 input 时仅编号 + 光标，wrapTextWithAnsi 单行）
-				const styled = `${t.fg("muted", `${num}. `)}${t.fg("text", editorText)}${t.fg("accent", "█")}`;
+				// 编号 + 文本，光标用反色高亮当前字符（surrogate pair 安全，不占额外位置）
+				const cursorText = renderCursorText(state.draftText, state.cursorIndex);
+				const styled = `${t.fg("muted", `${num}. `)}${t.fg("text", cursorText)}`;
 				addWrappedInput(add, lead, styled, avail, MAX_EDITOR_LINES);
 			} else {
 				const hasFreeText = state.freeTextValue !== null;
 				const marker = q.multiSelect
 					? (hasFreeText ? t.fg("success", "[✓]") : t.fg("dim", "[ ]"))
 					: (hasFreeText ? t.fg("success", "✓") : " ");
-				const labelColor = isSelected ? "accent" : "muted";
+				const labelColor = isSelected ? "accent" : "text";
 				const num = i + 1;
 				add(`${prefix} ${marker} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
 				if (hasFreeText) {
@@ -145,7 +182,7 @@ function buildOptionLines(
 			const num = i + 1;
 			add(`${prefix} ${box} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
 			if (opt.description && !hideDescriptions) {
-				const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - 10);
+				const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - DESCRIPTION_INDENT_MULTI);
 				for (const line of wrapped) add(`          ${line}`);
 			}
 		} else {
@@ -155,7 +192,7 @@ function buildOptionLines(
 			const num = i + 1;
 			add(`${prefix} ${check} ${t.fg(labelColor, `${num}. ${opt.label}`)}`);
 			if (opt.description && !hideDescriptions) {
-				const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - 8);
+				const wrapped = wrapTextWithAnsi(t.fg("muted", opt.description), width - DESCRIPTION_INDENT_SINGLE);
 				for (const line of wrapped) add(`        ${line}`);
 			}
 		}
@@ -165,13 +202,10 @@ function buildOptionLines(
 
 /** 构建分屏右侧 Markdown 详情预览。 */
 function buildPreviewLines(
-	q: Question,
-	state: QuestionState,
-	theme: ThemeLike,
-	width: number,
+	ctx: RenderContext,
 	maxLines: number,
 ): string[] {
-	const t = theme;
+	const { question: q, state, theme: t, width } = ctx;
 	const opts = allOptions(q);
 	const opt = opts[state.cursorIndex];
 	if (!opt) return [t.fg("dim", "—")];
@@ -184,32 +218,24 @@ function buildPreviewLines(
 		if (opt.description?.trim()) text += `\n\n${opt.description}`;
 	}
 
-	const wrapped = wrapTextWithAnsi(t.fg("muted", text), Math.max(10, width));
+	const wrapped = wrapTextWithAnsi(t.fg("muted", text), Math.max(PREVIEW_MIN_WIDTH, width));
 	const lines = wrapped.slice(0, maxLines);
 	if (wrapped.length > maxLines) lines.push(t.fg("dim", "…"));
 	return lines;
 }
 
 /**
- * 渲染单个问题视图（spec FR-4）。
- * isSingle: 单问题模式（无 Tab 提示）。
- * editorText: freeform/comment 模式下当前编辑器文本（纯 string，由 component 持有）。
- */
-/**
- * freeform 模式：editor 已在 buildOptionLines 中原地渲染（[ ] <input>█ 行），
+ * freeform 模式：editor 已在 buildOptionLines 中原地渲染（[ ] <input> 反色光标 行），
  * buildEditorBlock 在此模式下不重复输出，**仅留出与正常 help 行同位置的视觉空隙**。
  * comment 模式：保留独立编辑块（与 normal help 行解耦：comment 行有更长的 prompt）。
  */
 function buildEditorBlock(
-	theme: ThemeLike,
-	width: number,
-	mode: "freeform" | "comment",
-	editorText: string,
+	ctx: RenderContext,
 ): string[] {
-	if (mode === "freeform") {
+	const { state, theme: t, width } = ctx;
+	if (state.mode === "freeform") {
 		return [""];
 	}
-	const t = theme;
 	const lines: string[] = [];
 	const add = (s: string): void => {
 		lines.push(truncateToWidth(s, width));
@@ -217,31 +243,28 @@ function buildEditorBlock(
 	add("");
 	const prompt = t.fg("muted", " Your comment (optional):");
 	add(prompt);
-	// 渲染当前编辑器文本（单行；多行时按 \n 拆分）
-	for (const line of editorText.split("\n")) add(` ${line}`);
-	// 光标行
-	add(` ${t.fg("accent", "█")}`);
+	// 渲染当前编辑器文本，光标用反色高亮当前字符（surrogate pair 安全）
+	const cursorText = renderCursorText(state.draftText, state.cursorIndex);
+	add(` ${t.fg("text", cursorText)}`);
 	add("");
-	add(t.fg("dim", " Enter submit · Esc back"));
+	add(t.fg("dim", EDITOR_HINT));
 	return lines;
 }
 
 /** 渲染分屏模式下的左右双列（选项列表 + 详情预览）。 */
 function buildSplitPane(
-	q: Question,
-	state: QuestionState,
-	theme: ThemeLike,
+	ctx: RenderContext,
 	split: { left: number; right: number },
-	width: number,
-	editorText: string = "",
 ): string[] {
-	const t = theme;
+	const { theme: t, width } = ctx;
 	const lines: string[] = [];
 	const add = (s: string): void => {
 		lines.push(truncateToWidth(s, width));
 	};
-	const leftLines = buildOptionLines(q, state, theme, split.left, true, editorText);
-	const rightLines = buildPreviewLines(q, state, theme, split.right, Math.max(leftLines.length, 8));
+	const leftCtx: RenderContext = { ...ctx, width: split.left };
+	const rightCtx: RenderContext = { ...ctx, width: split.right };
+	const leftLines = buildOptionLines(leftCtx, true);
+	const rightLines = buildPreviewLines(rightCtx, Math.max(leftLines.length, 8));
 	const rowCount = Math.max(leftLines.length, rightLines.length);
 	const sep = t.fg("dim", SPLIT_PANE_SEPARATOR);
 	for (let i = 0; i < rowCount; i++) {
@@ -252,15 +275,11 @@ function buildSplitPane(
 	return lines;
 }
 
-export function renderQuestionView(
-	q: Question,
-	state: QuestionState,
-	theme: ThemeLike,
-	width: number,
-	isSingle: boolean,
-	editorText: string,
-): string[] {
-	const t = theme;
+/**
+ * 渲染单个问题视图（spec FR-4）。
+ */
+export function renderQuestionView(ctx: RenderContext): string[] {
+	const { question: q, state, theme: t, width, isSingle } = ctx;
 	const lines: string[] = [];
 	const add = (s: string): void => {
 		lines.push(truncateToWidth(s, width));
@@ -268,13 +287,13 @@ export function renderQuestionView(
 	const divider = (): void => add(t.fg("dim", "─".repeat(Math.max(0, width))));
 
 	// 问题文本（word-wrap）
-	const wrapped = wrapTextWithAnsi(t.fg("text", ` ${q.question}`), width - 2);
+	const wrapped = wrapTextWithAnsi(t.fg("text", ` ${q.question}`), width - QUESTION_TEXT_MARGIN);
 	for (const line of wrapped) add(line);
 
 	// 上下文（如有）
 	if (q.context?.trim()) {
 		divider();
-		const ctxWrapped = wrapTextWithAnsi(t.fg("muted", q.context), width - 2);
+		const ctxWrapped = wrapTextWithAnsi(t.fg("muted", q.context), width - QUESTION_TEXT_MARGIN);
 		for (const line of ctxWrapped) add(line);
 	}
 
@@ -292,24 +311,21 @@ export function renderQuestionView(
 	// 且右侧详情预览在输入自定义内容时无意义。隐藏 descriptions 以避免行数爆炸。
 	if (state.mode === "freeform" || state.mode === "comment") {
 		add("");
-		const optionLines = buildOptionLines(q, state, theme, width, false, editorText);
-		for (const line of optionLines) add(line);
-		const editorBlock = buildEditorBlock(theme, width, state.mode, editorText);
-		lines.push(...editorBlock);
+		for (const line of buildOptionLines(ctx, false)) add(line);
+		lines.push(...buildEditorBlock(ctx));
 		if (state.mode === "freeform") {
 			// freeform 模式 help 行：光标锁在 Other 上，正在输入
-			add(t.fg("dim", " Enter submit · Esc back"));
+			add(t.fg("dim", EDITOR_HINT));
 		}
 		return lines;
 	}
 
 	if (!split) {
 		// 单列模式
-		const optionLines = buildOptionLines(q, state, theme, width, false, editorText);
-		for (const line of optionLines) add(line);
+		for (const line of buildOptionLines(ctx, false)) add(line);
 	} else {
 		// 分屏模式
-		lines.push(...buildSplitPane(q, state, theme, split, width, editorText));
+		lines.push(...buildSplitPane(ctx, split));
 	}
 
 	add("");