@zhushanwen/pi-ask-user 7.2.4 → 7.3.0

package/src/form-adapter.ts

@@ -0,0 +1,119 @@
+// src/form-adapter.ts
+//
+// ask-user 包内归一 adapter（设计 ui-presentation-protocol D3：askUserInteract 退役后，
+// AskUserQuestion↔FormQuestion 的归一职责从协议包下沉到本包）。
+//
+// 三种问题形态在此互转（答案编解码不在本模块——FormAnswers 的 choice/text 部分与
+// legacy AskUserAnswers 逐字兼容，解码统一走协议包 getAskUserAnswer/getAskUserOther）：
+//   internal Question     本包 TUI 组件 + tool details 的形态（options 必填）
+//   FormQuestion          统一表单协议 wire 形态（UI_FORM_MARKER + uiFormInteract）
+//   legacy AskUserQuestion 旧 npm 子进程经 channel 传入的形态（D9 双读的旧 payload）
+//
+// 键位规则（设计 D2，与 renderer 归一层 / FormOverlay 逐字对齐）：
+// key = header ?? question；多选 value = JSON.stringify(labels[])；
+// Other/自由文本答案键 `${key}__other`。
+// schedule 问题类型非 ask-user 产生（scheduler 域），Form→本包形态的转换中跳过。
+
+import type {
+	AskUserQuestion,
+	ChoiceQuestion,
+	FormQuestion,
+} from "@zhushanwen/extension-protocol";
+
+import type { Option, Question } from "./types";
+
+/** internal Question[] → ChoiceQuestion[]（ask_user 工具的 wire 形态）。
+ *  工具 schema 锁 options 必填（minItems 2）→ 恒映射为 choice；multiSelect → multi
+ *  重命名（D2）；allowOther 固定 true——ask-user 无条件自动追加 Other，schema 不暴露该字段。 */
+export function internalToFormQuestions(questions: Question[]): ChoiceQuestion[] {
+	return questions.map((q: Question): ChoiceQuestion => ({
+		type: "choice",
+		header: q.header,
+		question: q.question,
+		context: q.context,
+		options: q.options.map((o: Option) => ({
+			label: o.label,
+			description: o.description,
+		})),
+		multi: q.multiSelect,
+		allowOther: true,
+	}));
+}
+
+/** legacy AskUserQuestion[] → FormQuestion[]（D9 双读的旧 payload 归一）。
+ *  有 options → choice（multiSelect → multi）；无 options → text（协议值域完备保留，
+ *  答案只写 `${key}__other` 键，与现状纯 other 形态一致）。 */
+export function askUserToFormQuestions(legacy: AskUserQuestion[]): FormQuestion[] {
+	return legacy.map((q: AskUserQuestion): FormQuestion => {
+		if (q.options === undefined) {
+			return {
+				type: "text",
+				header: q.header,
+				question: q.question,
+				context: q.context,
+			};
+		}
+		return {
+			type: "choice",
+			header: q.header,
+			question: q.question,
+			context: q.context,
+			options: q.options.map((o) => ({
+				label: o.label,
+				description: o.description,
+			})),
+			multi: q.multiSelect,
+			allowOther: q.allowOther,
+		};
+	});
+}
+
+/** FormQuestion[] → legacy AskUserQuestion[]（解码视图：复用协议包
+ *  getAskUserAnswer/getAskUserOther 的解码 SSOT，multi 还原为 multiSelect）。
+ *  保持顺序、跳过 schedule（ask-user 链路不产生；与 formToInternalQuestions 同规则）。 */
+export function formToAskUserQuestions(form: FormQuestion[]): AskUserQuestion[] {
+	return form.flatMap((q: FormQuestion): AskUserQuestion[] => {
+		if (q.type === "schedule") return [];
+		const common = {
+			header: q.header,
+			question: q.question,
+			context: q.context,
+		};
+		return [
+			q.type === "choice"
+				? {
+						...common,
+						options: q.options,
+						multiSelect: q.multi,
+						allowOther: q.allowOther,
+					}
+				: common,
+		];
+	});
+}
+
+/** FormQuestion[] → internal Question[]（TUI 组件渲染形态）。
+ *  choice → options 原样（multiSelect 还原）；text → 空 options（组件渲染为仅 Other
+ *  行的自由输入，与旧 payload 无 options 问题的现状处理一致）；schedule 跳过
+ *  （防止把草稿题渲染成自由文本框——ask-user channel 不携带该类型）。 */
+export function formToInternalQuestions(form: FormQuestion[]): Question[] {
+	return form.flatMap((q: FormQuestion): Question[] => {
+		if (q.type === "schedule") return [];
+		const opts: Option[] =
+			q.type === "choice"
+				? q.options.map((o) => ({
+						label: o.label,
+						...(o.description !== undefined ? { description: o.description } : {}),
+					}))
+				: [];
+		return [
+			{
+				question: q.question,
+				...(q.header !== undefined ? { header: q.header } : {}),
+				...(q.context !== undefined ? { context: q.context } : {}),
+				options: opts,
+				...(q.type === "choice" && q.multi !== undefined ? { multiSelect: q.multi } : {}),
+			},
+		];
+	});
+}

package/src/index.ts

@@ -4,14 +4,15 @@ import type { AgentToolResult, AgentToolUpdateCallback, ExtensionAPI, ExtensionC
 import { type Static } from "typebox";
 import {
 	type AskUserAnswers,
-	askUserInteract,
 	type AskUserQuestion,
 	getAskUserAnswer,
 	getAskUserOther,
+	uiFormInteract,
 } from "@zhushanwen/extension-protocol";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 import { createAskUserChannelHandler } from "./channel-handler";
+import { internalToFormQuestions } from "./form-adapter";
 import { registerAskUserChannelHandler } from "./channel-registry-register";
 import { AskUserComponent } from "./component";
 import { answerValueText } from "./submit-view";
@@ -178,8 +179,11 @@ function protoAnswersToResult(
 /**
  * RPC 模式（taiji GUI）交互入口。
  *
- * 走 askUserInteract（select 通道 + ASK_USER_MARKER），前端 AskUserOverlay 渲染富交互 UI。
- * 返回 Result（正常/取消），或抛错（select 异常 / 非 RPC 模式调用了此函数）。
+ * 走 uiFormInteract（统一表单协议：select 通道 + UI_FORM_MARKER），问题经包内归一
+ * adapter 转为 FormQuestion 家族（choice 形态），前端 FormOverlay 渲染表单。
+ * 回包 FormAnswers 的 choice 部分与旧 AskUserAnswers 逐字兼容（键位规则 D2），
+ * 解码复用 getAskUserAnswer/getAskUserOther 零改动。
+ * 返回 Result（正常/取消），或抛错（通道契约破坏 / 非 RPC 模式调用了此函数）。
  *
  * 注意：从 ExtensionContext 构造 GuiContext 子集传入，而非直接传 ctx——
  * ExtensionContext.ui.custom 的泛型签名与 GuiContext.ui.custom 不兼容（前者复杂泛型，后者简化签名），
@@ -191,19 +195,38 @@ async function runRpcInteraction(
 	ctx: ExtensionContext,
 ): Promise<Result> {
 	const protoQuestions = toProtoQuestions(questions);
+	const formQuestions = internalToFormQuestions(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 });
+	// 通道失败留痕（select throw / echo 命中）：channel-error 折叠 throw 时透出根因
+	let lastChannelLog = "";
+	const interact = await uiFormInteract(guiCtx, formQuestions, {
+		signal,
+		allowCancel: true,
+		log: (msg, detail) => {
+			lastChannelLog = detail === undefined ? msg : `${msg} ${JSON.stringify(detail)}`;
+		},
+	});
 
-	if (answers === null) {
+	if (!interact.ok) {
+		if (interact.reason === "channel-error") {
+			// 通道契约破坏：echo 检测命中的旧宿主组合（D7 下三角，message 携带升级指引）
+			// 或 select 抛错。throw 而非折叠 cancelled——「明确报错」让用户与 LLM 拿到
+			// 恢复动作，误报「用户取消」会诱导 LLM 俊等用户。
+			throw new Error(
+				interact.message ?? `form channel error${lastChannelLog ? ` (${lastChannelLog})` : ""}`,
+			);
+		}
+		// cancelled / timeout / non-json → 用户未作答或回包不可解，与旧 askUserInteract
+		// 的 null 语义一致，折叠 cancelled result
 		return { questions, answers: {}, cancelled: true };
 	}
 	return {
 		questions,
-		answers: protoAnswersToResult(questions, protoQuestions, answers),
+		answers: protoAnswersToResult(questions, protoQuestions, interact.answers),
 		cancelled: false,
 	};
 }
@@ -295,7 +318,7 @@ Don't:
 				);
 			}
 
-			// 4. 交互执行：TUI 走 ctx.ui.custom，RPC（taiji GUI）走 askUserInteract。
+			// 4. 交互执行：TUI 走 ctx.ui.custom，RPC（taiji GUI）走 uiFormInteract（统一表单协议）。
 			// 注意：hasUI 在 TUI 和 RPC 模式都为 true（dialog-capable），不能用于区分——
 			// 用 ctx.mode === 'rpc' 判定 GUI 渲染通道。
 			const useRpc = ctx.mode === "rpc";