@zhushanwen/pi-ask-user 7.2.3 → 7.3.0

package/src/__tests__/form-adapter.test.ts

@@ -0,0 +1,156 @@
+// src/__tests__/form-adapter.test.ts
+//
+// 包内归一 adapter（form-adapter.ts）的映射规则单测——设计 ui-presentation-protocol
+// D2/D3：askUserInteract 退役后 AskUserQuestion↔FormQuestion 归一职责下沉本包。
+// 键位规则对拍基准 = e2e/ask-user-real.spec.ts A1 协议面：无 allowComment、Other 保留
+// （__other 键）、多选 JSON 序列化。
+import { describe, expect, it } from "vitest";
+
+import {
+	askUserToFormQuestions,
+	formToAskUserQuestions,
+	formToInternalQuestions,
+	internalToFormQuestions,
+} from "../form-adapter";
+import type { Question } from "../types";
+
+// ── 样例 internal Question（tool 路径的源形态）──────────────
+const internalSingle: Question = {
+	question: "Which DB?",
+	options: [
+		{ label: "Postgres", description: "Mature" },
+		{ label: "SQLite" },
+	],
+};
+const internalMulti: Question = {
+	question: "Which tools?",
+	header: "Tools",
+	context: "pick many",
+	options: [{ label: "A" }, { label: "B" }],
+	multiSelect: true,
+};
+
+describe("internalToFormQuestions（wire 形态构造）", () => {
+	it("options 必填 → 恒 choice；multiSelect → multi 重命名；allowOther 固定 true", () => {
+		const [q] = internalToFormQuestions([internalSingle]);
+		expect(q).toEqual({
+			type: "choice",
+			question: "Which DB?",
+			options: [
+				{ label: "Postgres", description: "Mature" },
+				{ label: "SQLite" },
+			],
+			allowOther: true,
+		});
+		const [m] = internalToFormQuestions([internalMulti]);
+		expect(m.type).toBe("choice");
+		expect(m.multi).toBe(true);
+		expect(m.multiSelect).toBeUndefined();
+		expect(m.header).toBe("Tools");
+		expect(m.context).toBe("pick many");
+	});
+
+	it("wire 形态无 allowComment / 无 comment 类字段（A1 对拍基准）", () => {
+		for (const q of internalToFormQuestions([internalSingle, internalMulti])) {
+			for (const key of Object.keys(q)) {
+				expect(key.includes("comment"), `字段 ${key} 不应含 comment`).toBe(false);
+			}
+		}
+	});
+});
+
+describe("askUserToFormQuestions（D9 旧 payload 归一）", () => {
+	it("有 options → choice（multiSelect → multi）", () => {
+		const [q] = askUserToFormQuestions([
+			{ question: "q", header: "h", multiSelect: true, options: [{ label: "A" }] },
+		]);
+		expect(q).toEqual({
+			type: "choice",
+			header: "h",
+			question: "q",
+			options: [{ label: "A" }],
+			multi: true,
+		});
+	});
+
+	it("无 options → text（协议值域完备保留）", () => {
+		const [q] = askUserToFormQuestions([{ question: "free text q", header: "h" }]);
+		expect(q).toEqual({ type: "text", header: "h", question: "free text q" });
+	});
+});
+
+describe("formToAskUserQuestions（解码视图）", () => {
+	it("choice：multi 还原为 multiSelect，保持解码 helper 契约", () => {
+		const [q] = formToAskUserQuestions([
+			{ type: "choice", question: "q", options: [{ label: "A" }], multi: true },
+		]);
+		expect(q).toEqual({ question: "q", options: [{ label: "A" }], multiSelect: true });
+	});
+
+	it("text：无 options 字段（答案经 __other 键解码）", () => {
+		const [q] = formToAskUserQuestions([{ type: "text", question: "q" }]);
+		expect(q).toEqual({ question: "q" });
+	});
+
+	it("schedule：跳过（ask-user 链路不产生）", () => {
+		const out = formToAskUserQuestions([
+			{ type: "schedule", question: "when?" },
+			{ type: "text", question: "q" },
+		]);
+		expect(out).toEqual([{ question: "q" }]);
+	});
+
+	it("round trip：internal → Form → AskUser 与旧 toProtoQuestions 语义等价", () => {
+		const form = internalToFormQuestions([internalSingle, internalMulti]);
+		const decodeView = formToAskUserQuestions(form);
+		expect(decodeView[0]).toEqual({
+			question: "Which DB?",
+			options: [
+				{ label: "Postgres", description: "Mature" },
+				{ label: "SQLite" },
+			],
+			allowOther: true,
+		});
+		expect(decodeView[1]).toEqual({
+			question: "Which tools?",
+			header: "Tools",
+			context: "pick many",
+			options: [{ label: "A" }, { label: "B" }],
+			multiSelect: true,
+			allowOther: true,
+		});
+	});
+});
+
+describe("formToInternalQuestions（TUI 组件形态）", () => {
+	it("choice → options 原样 + multiSelect 还原", () => {
+		const [q] = formToInternalQuestions([
+			{
+				type: "choice",
+				question: "q",
+				header: "h",
+				options: [{ label: "A", description: "d" }],
+				multi: true,
+			},
+		]);
+		expect(q).toEqual({
+			question: "q",
+			header: "h",
+			options: [{ label: "A", description: "d" }],
+			multiSelect: true,
+		});
+	});
+
+	it("text → 空 options（组件渲染为自由输入，与旧无 options payload 现状一致）", () => {
+		const [q] = formToInternalQuestions([{ type: "text", question: "q" }]);
+		expect(q).toEqual({ question: "q", options: [] });
+	});
+
+	it("schedule → 跳过", () => {
+		const out = formToInternalQuestions([
+			{ type: "schedule", question: "when?" },
+			{ type: "text", question: "q" },
+		]);
+		expect(out).toEqual([{ question: "q", options: [] }]);
+	});
+});

package/src/__tests__/index.test.ts

@@ -523,9 +523,11 @@ describe("execute — inline render (FR-3)", () => {
 });
 
 // ── RPC 模式（taiji GUI 富交互协议）──────────────────
-// hasUI=false + ui.select 存在 → 走 askUserInteract（select 通道 + ASK_USER_MARKER）。
-// select 的返回值是前端 JSON.stringify 的 AskUserAnswers，index.ts 做格式转换。
-describe("execute — RPC mode (askUserInteract via select channel)", () => {
+// mode='rpc' + ui.select 存在 → 走 uiFormInteract（统一表单协议：select 通道 +
+// UI_FORM_MARKER，问题经 form-adapter 转 FormQuestion choice 形态）。
+// select 的返回值是前端 FormOverlay JSON.stringify 的 FormAnswers（choice 部分与旧
+// AskUserAnswers 逐字兼容），index.ts 做格式转换。
+describe("execute — RPC mode (uiFormInteract via select channel)", () => {
 	it("R-1: single-select answer → converted to Result.answers (key=question)", async () => {
 		const tool = getTool();
 		// 协议 answers：key=header（单问题无 header → question 全文），value=选中 label
@@ -725,4 +727,125 @@ describe("execute — RPC mode (askUserInteract via select channel)", () => {
 		expect(result.details.answers["Which region?"]).toBeUndefined();
 	});
 
+	it("R-9: select 收到 title=UI_FORM_MARKER + options[0]={formQuestions, allowCancel}（D2 adapter 形态）", async () => {
+		const tool = getTool();
+		let capturedTitle = "";
+		let capturedOptions: string[] = [];
+		const ctx = {
+			mode: "rpc" as const,
+			hasUI: true,
+			signal: undefined as AbortSignal | undefined,
+			ui: {
+				select: async (
+					title: string,
+					options: string[],
+				): Promise<string> => {
+					capturedTitle = title;
+					capturedOptions = options;
+					return JSON.stringify({ "Which DB?": "Postgres" });
+				},
+				custom: async <T = void>(): Promise<T> => undefined as T,
+			},
+		};
+		await tool.execute("id", validSingle, undefined, undefined, ctx);
+
+		// wire 形态：统一表单协议 marker + 单元素 options
+		expect(capturedTitle).toBe("\x00TAIJI_UI_FORM");
+		expect(capturedOptions).toHaveLength(1);
+		const payload = JSON.parse(capturedOptions[0]!) as {
+			formQuestions?: Array<Record<string, unknown>>;
+			questions?: unknown;
+			allowCancel?: boolean;
+		};
+		expect(payload.questions).toBeUndefined();
+		expect(payload.allowCancel).toBe(true);
+		expect(payload.formQuestions).toEqual([
+			{
+				type: "choice",
+				question: "Which DB?",
+				options: [
+					{ label: "Postgres", description: undefined },
+					{ label: "SQLite", description: undefined },
+				],
+				allowOther: true,
+			},
+		]);
+		// A1 对拍基准：问题对象无 allowComment / comment 类字段
+		for (const key of Object.keys(payload.formQuestions![0]!)) {
+			expect(key.includes("comment"), `字段 ${key} 不应含 comment`).toBe(false);
+		}
+	});
+
+	it("R-9b: multiSelect → multi 重命名进 wire 形态", async () => {
+		const tool = getTool();
+		let capturedOptions: string[] = [];
+		const ctx = {
+			mode: "rpc" as const,
+			hasUI: true,
+			signal: undefined as AbortSignal | undefined,
+			ui: {
+				select: async (_title: string, options: string[]): Promise<string> => {
+					capturedOptions = options;
+					return JSON.stringify({ Tools: JSON.stringify(["A"]) });
+				},
+				custom: async <T = void>(): Promise<T> => undefined as T,
+			},
+		};
+		const multi = {
+			questions: [
+				{
+					question: "Which tools?",
+					header: "Tools",
+					options: [{ label: "A" }, { label: "B" }],
+					multiSelect: true,
+				},
+			],
+		};
+		await tool.execute("id", multi, undefined, undefined, ctx);
+		const payload = JSON.parse(capturedOptions[0]!) as {
+			formQuestions?: Array<Record<string, unknown>>;
+		};
+		expect(payload.formQuestions![0]!.multi).toBe(true);
+		expect(payload.formQuestions![0]!.multiSelect).toBeUndefined();
+	});
+
+	it("R-10: select 回显 payload（echo，旧 taiji 宿主）→ channel-error throw 带升级指引 + 工具禁用", async () => {
+		let capturedActive: string[] | null = null;
+		const tool = getTool({
+			getAllTools: () => [{ name: "ask_user" }, { name: "other" }],
+			setActiveTools: (names: string[]) => {
+				capturedActive = names;
+			},
+		});
+		// 旧宿主不识别 UI_FORM_MARKER → band 单选项 = payload 自身，点选回显
+		const ctx = {
+			mode: "rpc" as const,
+			hasUI: true,
+			signal: undefined as AbortSignal | undefined,
+			ui: {
+				select: async (_title: string, options: string[]): Promise<string> => options[0]!,
+				custom: async <T = void>(): Promise<T> => undefined as T,
+			},
+		};
+		await expect(
+			tool.execute("id", validSingle, undefined, undefined, ctx),
+		).rejects.toThrow(/ask_user failed[\s\S]*upgrade taiji/);
+		// channel-error 折叠 = 禁用工具（防 LLM 反复重试），与 R-6 一致
+		expect(capturedActive).not.toContain("ask_user");
+		expect(capturedActive).toContain("other");
+	});
+
+	it("R-11: select 返回合法 JSON 但非 FormAnswers 形状（JSON 数组）→ 折叠 cancelled（非 throw）", async () => {
+		const tool = getTool();
+		const result = await tool.execute(
+			"id",
+			validSingle,
+			undefined,
+			undefined,
+			makeCtx({ mode: "rpc", selectResult: JSON.stringify(["A", "B"]) }),
+		);
+		expect(result.content[0].text).toContain("User cancelled");
+		expect(result.details.cancelled).toBe(true);
+	});
+
 });

package/src/channel-handler.ts

@@ -2,30 +2,47 @@
 //
 // ask_user channel handler：把 subagent 子进程的 ask_user 请求透传到主进程 UI 渲染。
 //
-// 设计（关键决策）：askUserInteract（@zhushanwen/extension-protocol）只在 RPC 模式可用
+// 设计（关键决策）：uiFormInteract（@zhushanwen/extension-protocol）只在 RPC 模式可用
 // （内部 isGuiCapable 检查 mode==='rpc'，TUI 下抛错）。所以 handler 按 ctx.mode 分流：
-//   - RPC：转发器——调 askUserInteract(guiCtx, protoQuestions)，复用 select 通道 +
-//     ASK_USER_MARKER 契约，主进程 ctx.ui.select 经 GUI sidecar 渲染（不进 parseSpawnLine，
+//   - RPC：转发器——调 uiFormInteract(guiCtx, formQuestions)，复用 select 通道 +
+//     UI_FORM_MARKER 契约，主进程 ctx.ui.select 经 GUI sidecar 渲染（不进 parseSpawnLine，
 //     不循环）。返回 {value: JSON.stringify(answers)} 让子进程 JSON.parse(value) decode。
-//   - TUI：走 ctx.ui.custom + AskUserComponent。三步：(1) protoQuestions → 内部 Question[]，
+//   - TUI：走 ctx.ui.custom + AskUserComponent。三步：(1) formQuestions → 内部 Question[]，
 //     (2) ctx.ui.custom 渲染拿内部 Result，(3) 内部 Result.answers（key=question 全文，
-//     value=结构化 AnswerValue）→ 用 encodeAnswer 重新编码为 proto AskUserAnswers
+//     value=结构化 AnswerValue）→ 用 encodeAnswer 重新编码为 proto FormAnswers
 //     （key=header/question，单选=string，多选=JSON 数组，Other→__other），让子进程 decode 一致。
 //
-// handler 收到的 req.channelPayload = {questions: AskUserQuestion[], allowCancel}（proto 格式，
-// 由子进程 askUserInteract 编码、packages/subagent-core 的 parseChannel（execution/ui/ui-channels.ts）
-// 解析 options[0] JSON 得到）。
+// D9 双名双读（subagent 间接链双维兼容）：subagent 孙进程跑 npm 版 ask-user，版本不可控——
+//   - channel 名由 marker 派生（subagent-engine-sdk ui-channels.ts normalizeChannelName：
+//     剥 \x00TAIJI_ 前缀 + 小写化）——新孙进程发 ui_form、旧孙进程发 ask_user，
+//     channel-registry-register 双名注册两代通道，本 handler 同一实现服务两名；
+//   - 入口 payload 双读 `formQuestions ?? questions`：新 payload {formQuestions: FormQuestion[]}
+//     （逐项 isFormQuestion 守卫过滤），旧 payload {questions: AskUserQuestion[]} 经包内
+//     归一 adapter 转 FormQuestion。旧读与旧名随 D7 窗口退役。
+//
+// handler 收到的 req.channelPayload 由 packages/subagent-core 的 parseChannel
+// （execution/ui/ui-channels.ts）解析 select options[0] JSON 得到。
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
-	type AskUserAnswers,
-	askUserInteract,
 	type AskUserQuestion,
+	type FormAnswers,
+	type FormQuestion,
+	isFormQuestion,
+	uiFormInteract,
 } from "@zhushanwen/extension-protocol";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import { AskUserComponent } from "./component";
 import { encodeAnswer } from "./answer-codec";
-import { type AnswerValue, type Option, type Question, type Result, type ThemeLike } from "./types";
+import {
+	askUserToFormQuestions,
+	formToAskUserQuestions,
+	formToInternalQuestions,
+} from "./form-adapter";
+import { type AnswerValue, type Result, type ThemeLike } from "./types";
+
+const logger = getLogger("ask-user");
 
 /**
  * channel handler 签名——与 packages/subagent-core 的 UiChannelRegistry.ChannelHandler 一致
@@ -41,37 +58,44 @@ export type ChannelHandler = (req: unknown) => Promise<unknown>;
 type ChannelResponse = { value: string } | { cancelled: true };
 
 /** handler 收到的 req 形状收窄（ChannelHandler 签名是 unknown，按形状 as 收窄）。
- *  channelPayload 由 packages/subagent-core 的 parseChannel 填充。 */
+ *  channelPayload 由 packages/subagent-core 的 parseChannel 填充（D9 双 payload）：
+ *  新形态 {formQuestions, allowCancel} / 旧形态 {questions, allowCancel}。 */
 interface ChannelRequest {
-	channelPayload?: { questions?: AskUserQuestion[]; allowCancel?: boolean };
+	channelPayload?: {
+		formQuestions?: FormQuestion[];
+		questions?: AskUserQuestion[];
+		allowCancel?: boolean;
+	};
 }
 
-/** proto AskUserQuestion → 内部 Question（AskUserComponent 接受内部格式）。
- *  proto options 可选（无 options=纯自由文本），内部 options 必填——无 options 的 protoQuestion
- *  这里仍映射出 options（从子进程 ask-user 调用方保证 protoQuestions 总带 options；若缺则返 [] 由调用方判）。 */
-function protoToInternalQuestions(protoQuestions: AskUserQuestion[]): Question[] {
-	return protoQuestions.map((pq: AskUserQuestion): Question => {
-		const opts: Option[] = (pq.options ?? []).map((o: { label: string; description?: string }): Option => ({
-			label: o.label,
-			...(o.description !== undefined ? { description: o.description } : {}),
-		}));
-		return {
-			question: pq.question,
-			...(pq.header !== undefined ? { header: pq.header } : {}),
-			...(pq.context !== undefined ? { context: pq.context } : {}),
-			options: opts,
-			...(pq.multiSelect !== undefined ? { multiSelect: pq.multiSelect } : {}),
-		};
-	});
+/**
+ * D9 双读：channelPayload 归一为 FormQuestion[]。
+ *  - 新 payload formQuestions 逐项 isFormQuestion 守卫过滤（不合法项跳过——与
+ *    event-adapter / renderer 的逐项过滤失败策略一致，D2）
+ *  - 旧 payload questions 经包内归一 adapter 转 FormQuestion（legacy 子进程产出，
+ *    其自身 schema 已保证形状，不做二次守卫——与迁移前行为一致）
+ * 返回 undefined = 无可用问题（payload 缺失/空/全不合法），调用方折 {cancelled: true}。
+ */
+function payloadToFormQuestions(payload: ChannelRequest["channelPayload"]): FormQuestion[] | undefined {
+	if (payload === undefined) return undefined;
+	if (Array.isArray(payload.formQuestions)) {
+		const filtered = payload.formQuestions.filter((q: unknown) => isFormQuestion(q));
+		return filtered.length > 0 ? filtered : undefined;
+	}
+	if (Array.isArray(payload.questions) && payload.questions.length > 0) {
+		return askUserToFormQuestions(payload.questions);
+	}
+	return undefined;
 }
 
 /**
- * 把 TUI 路径产出的内部 Result.answers 重新编码为 proto AskUserAnswers。
+ * 把 TUI 路径产出的内部 Result.answers 重新编码为 proto FormAnswers。
  *
  * 内部 Result.answers：key = question 全文，value = 结构化 AnswerValue
  * （selected = option label 数组，other = Other 自由文本）。
  *
- * proto AskUserAnswers 契约（@zhushanwen/extension-protocol）：
+ * proto FormAnswers 契约（@zhushanwen/extension-protocol，choice/text 部分与旧
+ * AskUserAnswers 逐字兼容）：
  *   - key = question.header ?? question 全文
  *   - 单选：value = 选中项 label string
  *   - 多选：value = JSON.stringify(选中项 label 数组)
@@ -83,8 +107,8 @@ function protoToInternalQuestions(protoQuestions: AskUserQuestion[]): Question[]
 function encodeTuiResultToProto(
 	protoQuestions: AskUserQuestion[],
 	result: Result,
-): AskUserAnswers {
-	const answers: AskUserAnswers = {};
+): FormAnswers {
+	const answers: FormAnswers = {};
 	for (const pq of protoQuestions) {
 		const av: AnswerValue | undefined = result.answers[pq.question];
 		if (av === undefined) continue; // 该问题未答（buildResult 跳过未答）
@@ -106,11 +130,11 @@ function encodeTuiResultToProto(
  *  支持禁用 Esc 后，应把 allowCancel 下传给 AskUserComponent 构造函数。当前 allowCancel=false
  *  时 TUI 与 RPC 路径仍有分裂，但 handler 层已不再吞掉 allowCancel（修复分裂的第一步）。 */
 async function runTuiProtoInteraction(
-	protoQuestions: AskUserQuestion[],
+	formQuestions: FormQuestion[],
 	ctx: ExtensionContext,
 	allowCancel: boolean,
-): Promise<AskUserAnswers | null> {
-	const questions = protoToInternalQuestions(protoQuestions);
+): Promise<FormAnswers | null> {
+	const questions = formToInternalQuestions(formQuestions);
 	// 预留：组件升级后此处改为 new AskUserComponent(questions, tui, theme, done, allowCancel)
 	void allowCancel;
 	const result = await ctx.ui.custom<Result | null>(
@@ -128,14 +152,14 @@ async function runTuiProtoInteraction(
 	// 显式 undefined 守卫：裸 result.cancelled 对 undefined 会抛 TypeError（W4 修复前
 	// 靠 dialog-queue 兜底为 {cancelled:true}，现源头短路，语义等价且不再依赖兜底）。
 	if (result === null || result === undefined || result.cancelled) return null;
-	return encodeTuiResultToProto(protoQuestions, result);
+	return encodeTuiResultToProto(formToAskUserQuestions(formQuestions), result);
 }
 
 /**
  * 创建 ask_user channel handler。
  *
  * @param ctx 主进程 ExtensionContext（session_start 时注入）
- * @returns ChannelHandler——req.channelPayload = {questions, allowCancel}（proto 格式），
+ * @returns ChannelHandler——req.channelPayload = {formQuestions} 或 {questions}（D9 双读），
  *          返回 {value: JSON.stringify(answers)} 或 {cancelled: true}
  */
 export function createAskUserChannelHandler(ctx: ExtensionContext): ChannelHandler {
@@ -146,20 +170,20 @@ export function createAskUserChannelHandler(ctx: ExtensionContext): ChannelHandl
 			return { cancelled: true } satisfies ChannelResponse;
 		}
 		const r = req as ChannelRequest;
-		const payload = r.channelPayload;
-		if (!payload || !Array.isArray(payload.questions) || payload.questions.length === 0) {
+		const formQuestions = payloadToFormQuestions(r.channelPayload);
+		if (formQuestions === undefined) {
 			return { cancelled: true } satisfies ChannelResponse;
 		}
-		const { questions, allowCancel } = payload;
+		const allowCancel = r.channelPayload?.allowCancel ?? true;
 
-		// 按 ctx.mode 分流（PR #85 #13 / #M6）：rpc 走 askUserInteract（select 通道+sidecar），
+		// 按 ctx.mode 分流（PR #85 #13 / #M6）：rpc 走 uiFormInteract（select 通道+sidecar），
 		// 其余（tui/json/print/undefined）走 ctx.ui.custom+AskUserComponent。
 		// 用 ctx.mode === "rpc" 二值判定（与 index.ts execute 的 useRpc 判定一致）；
 		// 三值分类不需要——handler 只关心「rpc 转发」vs「TUI 内部渲染」两条路径。
 		const answers =
 			ctx.mode === "rpc"
-				? await runRpcForward(questions, ctx, allowCancel ?? true)
-				: await runTuiProtoInteraction(questions, ctx, allowCancel ?? true);
+				? await runRpcForward(formQuestions, ctx, allowCancel)
+				: await runTuiProtoInteraction(formQuestions, ctx, allowCancel);
 
 		if (answers === null) return { cancelled: true } satisfies ChannelResponse;
 		return { value: JSON.stringify(answers) } satisfies ChannelResponse;
@@ -167,16 +191,22 @@ export function createAskUserChannelHandler(ctx: ExtensionContext): ChannelHandl
 }
 
 /** RPC 转发器：主进程 ctx.ui.select 经 GUI sidecar 渲染（不进 parseSpawnLine，不循环）。
- *  完整复用 askUserInteract 的 encode/decode 契约。 */
+ *  完整复用 uiFormInteract 的 encode/decode 契约（FormAnswers ≡ 旧 AskUserAnswers）。
+ *  间接链的通道失败（含 echo 命中的旧宿主组合）折叠 cancelled + 留痕——回包形状只有
+ *  {value}|{cancelled} 两态，throw 会被 dialog-queue 兜底成同一结果，日志是唯一留痕面。 */
 async function runRpcForward(
-	questions: AskUserQuestion[],
+	formQuestions: FormQuestion[],
 	ctx: ExtensionContext,
 	allowCancel: boolean,
-): Promise<AskUserAnswers | null> {
+): Promise<FormAnswers | null> {
 	const guiCtx = {
 		mode: ctx.mode,
 		hasUI: ctx.hasUI,
 		ui: { select: ctx.ui.select.bind(ctx.ui) },
 	};
-	return askUserInteract(guiCtx, questions, { allowCancel });
+	const result = await uiFormInteract(guiCtx, formQuestions, {
+		allowCancel,
+		log: (msg, detail) => logger.warn(msg, detail),
+	});
+	return result.ok ? result.answers : null;
 }

package/src/channel-registry-register.ts

@@ -33,8 +33,13 @@ export const CHANNEL_HANDSHAKE_KEY = Symbol.for(
 /** 握手协议版本号。读写 slot 时校验 version !== 1 视为不兼容（warn + 重建 slot）。 */
 const HANDSHAKE_VERSION = 1;
 
-/** channel 名称（ask-user 固定注册 "ask_user"）。 */
-const ASK_USER_CHANNEL = "ask_user";
+/** 注册的 channel 名（D9 双名注册两代通道）。
+ *  channel 名由孙进程 select title 的 marker 经 normalizeChannelName 派生
+ *  （subagent-engine-sdk ui-channels.ts：剥 "\x00TAIJI_" 前缀 + 小写化）：
+ *    - 旧孙进程（askUserInteract / ASK_USER_MARKER "\x00TAIJI_ASK_USER"）→ "ask_user"
+ *    - 新孙进程（uiFormInteract / UI_FORM_MARKER "\x00TAIJI_UI_FORM"）→ "ui_form"
+ *  孙进程 npm 版本不可控，同名 handler 注册两代通道名；旧名随 D7 窗口退役。 */
+const ASK_USER_CHANNELS = ["ask_user", "ui_form"] as const;
 
 /**
  * channel registry 的本地等价接口（与 packages/subagent-core 的 UiChannelRegistry 形状一致，
@@ -91,24 +96,26 @@ function ensureSlot(): ChannelRegistryHandshake {
 }
 
 /**
- * 注册 ask_user channel handler 到 globalThis 握手 slot。
+ * 注册 ask_user channel handler 到 globalThis 握手 slot（D9 双名：ask_user + ui_form）。
  *
  * 行为：
- *   1. slot 不存在或 version 不兼容 → 建 slot（仅 pending），handler 入 pending；
- *      **slot.registry 保持 undefined**（M4 核心：ask-user 不建 registry）
- *   2. slot 存在但 registry 未就绪 → handler 入 pending
- *   3. slot 存在且 registry 就绪 → 直接调 registry.register("ask_user", handler)
+ *   1. slot 不存在或 version 不兼容 → 建 slot（仅 pending），handler 按 ASK_USER_CHANNELS
+ *      逐名入 pending；**slot.registry 保持 undefined**（M4 核心：ask-user 不建 registry）
+ *   2. slot 存在但 registry 未就绪 → handler 逐名入 pending
+ *   3. slot 存在且 registry 就绪 → 对每个 channel 名调 registry.register(name, handler)
  *
  * 多次调用幂等：registry 就绪时 register 同名覆盖；未就绪时 pending.length 增长
  * （packages/subagent-core flush 时一次性消费所有 pending）。
  *
- * @param handler ask_user channel handler（createAskUserChannelHandler 产出）
+ * @param handler ask_user channel handler（createAskUserChannelHandler 产出，双名共用同一实现）
  */
 export function registerAskUserChannelHandler(handler: ChannelHandler): void {
 	const slot = readSlot() ?? ensureSlot();
-	if (slot.registry !== undefined) {
-		slot.registry.register(ASK_USER_CHANNEL, handler);
-		return;
+	for (const channel of ASK_USER_CHANNELS) {
+		if (slot.registry !== undefined) {
+			slot.registry.register(channel, handler);
+		} else {
+			slot.pending.push({ channel, handler });
+		}
 	}
-	slot.pending.push({ channel: ASK_USER_CHANNEL, handler });
 }