@zhushanwen/pi-ask-user 0.1.0 → 0.2.0

package/src/index.ts

@@ -1,9 +1,18 @@
 // src/index.ts
+import { Box, Text, TruncatedText, truncateToWidth } from "@earendil-works/pi-tui";
 import type { AgentToolResult, AgentToolUpdateCallback, ExtensionAPI, ExtensionContext, ToolRenderResultOptions } from "@mariozechner/pi-coding-agent";
-import { Box, Text, TruncatedText, truncateToWidth } from "@mariozechner/pi-tui";
 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",
@@ -81,80 +237,53 @@ If you recommend an option, prefix its label with "(Recommended)" and list it fi
 		): 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）。
 			// abort 是 agent 被外部终止（goal 取消 / context compact / session 切换），
 			// 不是用户意图——文案必须区别于 step 5 的用户取消，避免 LLM 俊等用户。
 			if (signal?.aborted) {
-				return {
-					content: [
-						{
-							type: "text" as const,
-							text: "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.",
-						},
-					],
-					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,
 				};
@@ -162,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

@@ -26,6 +26,17 @@ export interface DisplayOption {
 	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;
 
@@ -112,14 +123,10 @@ const EDITOR_HINT = " ←/→ Home/End move · Backspace deletes · Enter submit
  *  freeform 模式下，Other 行**原地**变 [ ] <input> 反色光标（多选）/ <input> 反色光标（单选），
  *  不再依赖 buildEditorBlock 的下方独立编辑块。 */
 function buildOptionLines(
-	q: Question,
-	state: QuestionState,
-	theme: ThemeLike,
-	width: number,
+	ctx: RenderContext,
 	hideDescriptions: boolean,
-	draftText: 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 => {
@@ -145,7 +152,7 @@ function buildOptionLines(
 				const lead = `${prefix} ${marker} `;
 				const avail = Math.max(1, width - visibleWidth(lead));
 				// 编号 + 文本，光标用反色高亮当前字符（surrogate pair 安全，不占额外位置）
-				const cursorText = renderCursorText(draftText, state.cursorIndex);
+				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 {
@@ -195,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", "—")];
@@ -226,16 +230,12 @@ function buildPreviewLines(
  * comment 模式：保留独立编辑块（与 normal help 行解耦：comment 行有更长的 prompt）。
  */
 function buildEditorBlock(
-	theme: ThemeLike,
-	width: number,
-	mode: "freeform" | "comment",
-	draftText: string,
-	cursorIndex?: number,
+	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));
@@ -244,8 +244,7 @@ function buildEditorBlock(
 	const prompt = t.fg("muted", " Your comment (optional):");
 	add(prompt);
 	// 渲染当前编辑器文本，光标用反色高亮当前字符（surrogate pair 安全）
-	const pos = cursorIndex ?? draftText.length;
-	const cursorText = renderCursorText(draftText, pos);
+	const cursorText = renderCursorText(state.draftText, state.cursorIndex);
 	add(` ${t.fg("text", cursorText)}`);
 	add("");
 	add(t.fg("dim", EDITOR_HINT));
@@ -254,20 +253,18 @@ function buildEditorBlock(
 
 /** 渲染分屏模式下的左右双列（选项列表 + 详情预览）。 */
 function buildSplitPane(
-	q: Question,
-	state: QuestionState,
-	theme: ThemeLike,
+	ctx: RenderContext,
 	split: { left: number; right: number },
-	width: number,
-	draftText: 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, draftText);
-	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++) {
@@ -280,18 +277,9 @@ function buildSplitPane(
 
 /**
  * 渲染单个问题视图（spec FR-4）。
- * isSingle: 单问题模式（无 Tab 提示）。
- * draftText: freeform/comment 模式下当前编辑器草稿（来自 QuestionState.draftText）。
  */
-export function renderQuestionView(
-	q: Question,
-	state: QuestionState,
-	theme: ThemeLike,
-	width: number,
-	isSingle: boolean,
-	draftText: string,
-): string[] {
-	const t = theme;
+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));
@@ -323,10 +311,8 @@ export function renderQuestionView(
 	// 且右侧详情预览在输入自定义内容时无意义。隐藏 descriptions 以避免行数爆炸。
 	if (state.mode === "freeform" || state.mode === "comment") {
 		add("");
-		const optionLines = buildOptionLines(q, state, theme, width, false, draftText);
-		for (const line of optionLines) add(line);
-		const editorBlock = buildEditorBlock(theme, width, state.mode, draftText, state.cursorIndex);
-		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", EDITOR_HINT));
@@ -336,11 +322,10 @@ export function renderQuestionView(
 
 	if (!split) {
 		// 单列模式
-		const optionLines = buildOptionLines(q, state, theme, width, false, draftText);
-		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, draftText));
+		lines.push(...buildSplitPane(ctx, split));
 	}
 
 	add("");

package/src/submit-view.ts

@@ -1,8 +1,8 @@
 // src/submit-view.ts
 import { truncateToWidth } from "@mariozechner/pi-tui";
 
+import { formatAnswer } from "./answer-format";
 import {
-	ANSWER_COMMENT_SEPARATOR,
 	HEADER_MAX_CHARS,
 	type Question,
 	type QuestionState,
@@ -44,9 +44,7 @@ export function getAnswerText(q: Question, s: QuestionState): string | null {
 		if (label) parts.push(label);
 	}
 	if (s.freeTextValue !== null) parts.push(s.freeTextValue);
-	if (parts.length === 0) return null;
-	const base = parts.join(", ");
-	return s.commentValue ? `${base}${ANSWER_COMMENT_SEPARATOR}${s.commentValue}` : base;
+	return formatAnswer(parts, s.commentValue);
 }
 
 /**

package/src/validate.ts

@@ -55,6 +55,17 @@ export function validateInput(questions: Question[]): string | null {
 				return `Question "${q.question}" requires a non-empty header in multi-question mode (it labels the tab). Provide a header of <=12 chars.`;
 			}
 		}
+
+		// S3: 多问题时 header 唯一——重复 header 会导致 askUserKey 碰撞，
+		// 后一个 question 的 __other/__comment 覆盖前一个（协议 helper 用 header 作 answers 读取 key）。
+		const seenHeaders = new Set<string>();
+		for (const q of questions) {
+			const h = q.header!.trim();
+			if (seenHeaders.has(h)) {
+				return `Duplicate header "${h}" in questions. Headers must be unique in multi-question mode — shared headers cause answer key collisions (one question's Other/comment overwrites another's). Rephrase one header to differ.`;
+			}
+			seenHeaders.add(h);
+		}
 	}
 
 	// 4. header 长度上限（若提供）。单/多问题均校验：超出会在 tab 栏被静默截断，