MailUI4Agents/plugins/opencode-mail-bridge/lib/user-question.js

/**
 * `ask_user_question` ↔ AgentMail 询问邮件 的双向映射（纯函数）。
 *
 * # 为什么需要它
 *
 * DSH 的 `ask_user_question` 走 `ctx.userQuestions` 这个 UI seam，而邮件驱动的
 * 会话**没有本地 UI**。不桥接的后果是模型主动提问后永久挂死：`ask()` 的
 * promise 永远不 resolve，那一轮工具调用卡在那里，人却什么也看不到。
 *
 * # 两个模型的形状差异
 *
 * DSH：`{ questions: [{ id, question, header?, options?: [{label, description?}],
 *                       multiSelect? }] }` → `{ answers: [{ id, selected[], custom? }] }`
 *   - 一次可以问**多个**问题，每个问题可有自己的选项与多选语义
 *   - 答案按问题 id 回填，选项用 label 字符串
 *
 * AgentMail：一封询问邮件 = 一个问题 + 一个选项列表 + 一个 multi_select 标志
 *   - 只有单问题结构，因此多问题时必须摊平
 *
 * # 摊平策略（多问题时）
 *
 * 选项取所有问题 label 的并集（去重、保持首次出现顺序），并把每个问题的
 * 原文、选项与说明枚举进 context 正文。回信时按「label 属于哪个问题」把
 * 选择分配回去。这比「一问一封邮件」简单得多 —— 后者要等人分别回复多封
 * 才能凑齐一次 `ask()` 的答案，而 `ask()` 是**单次**调用，凑不齐就还是挂死。
 *
 * # fail closed
 *
 * 认不出的答案一律不猜测；没有匹配到任何选项的问题返回空选择 + 把自由文本
 * 放进 custom，而不是随便挑一个 label 放行。
 */

/** 问题是否带可选项。 */
export function hasOptions(question) {
	return Array.isArray(question?.options) && question.options.length > 0;
}

/** 一个 DSH 问题的可选项 label 列表（保序）。 */
export function optionLabels(question) {
	if (!hasOptions(question)) return [];
	return question.options
		.map((o) => (typeof o === "string" ? o : o?.label))
		.filter((l) => typeof l === "string" && l.length > 0);
}

/** 一个问题的展示标题：header 有就用它做前缀，否则只用 question。 */
export function questionTitle(question) {
	const header =
		typeof question?.header === "string" ? question.header.trim() : "";
	const text =
		typeof question?.question === "string" ? question.question.trim() : "";
	if (header && text) return `${header}: ${text}`;
	return header || text || "(未提供问题)";
}

/**
 * 把 DSH 的 questions 摊平成一封 AgentMail 询问邮件的正文与元数据。
 *
 * @param {Array<object>} questions DSH AskUserQuestionItem[]
 * @returns {{ question: string, options: string[], context: string, multiSelect: boolean }}
 */
export function flattenQuestions(questions) {
	const list = Array.isArray(questions) ? questions.filter(Boolean) : [];
	if (list.length === 0) {
		throw new Error("ask_user_question 至少需要一个 question");
	}

	const lines = [];
	const options = [];
	const seen = new Set();
	let anyMulti = false;

	list.forEach((q, i) => {
		const title = questionTitle(q);
		lines.push(`${i + 1}. ${title}`);
		const detail = typeof q?.detail === "string" ? q.detail.trim() : "";
		if (detail) lines.push(`   ${detail}`);

		const labels = optionLabels(q);
		if (labels.length > 0) {
			lines.push(
				`   可选项：${labels.join(" / ")}${q.multiSelect ? "（可多选）" : ""}`,
			);
			for (const label of labels) {
				if (!seen.has(label)) {
					seen.add(label);
					options.push(label);
				}
			}
		} else {
			lines.push("   （请直接填写回答）");
		}
		if (q?.multiSelect === true) anyMulti = true;
	});

	// 多问题时必须允许多选：不同问题的选项要能一起勾选。
	const multiSelect = list.length > 1 ? options.length > 0 : anyMulti;

	const question =
		list.length === 1 ? questionTitle(list[0]) : `${list.length} 个问题待回答`;
	const context = [
		list.length === 1 ? "" : "模型提出了多个问题，请在「回复」里一并回答：",
		...lines,
		"",
		options.length > 0
			? "可直接勾选下方的选项；补充说明写在备注里。"
			: "这题没有预设选项，请把回答写在备注里。",
	]
		.filter((l) => l !== "")
		.join("\n");

	return { question, options, context, multiSelect };
}

/**
 * 把人类的决策回写成 DSH 的 answers[]。
 *
 * @param {Array<object>} questions 原始 DSH questions（回填 id 用）
 * @param {string} decision 人类选的选项原文（多选时前端用换行分隔）
 * @param {string} [note] 自由文本/备注
 * @returns {{ answers: Array<{id: string, selected: string[], custom?: string}> }}
 */
export function answersFromDecision(questions, decision, note) {
	const list = Array.isArray(questions) ? questions.filter(Boolean) : [];
	const labels = String(decision || "")
		.split("\n")
		.map((s) => s.trim())
		.filter(Boolean);
	const custom = typeof note === "string" ? note.trim() : "";

	// 单问题：忠实映射（选项 → selected，备注 → custom）。
	if (list.length === 1) {
		const q = list[0];
		const id = String(q?.id ?? "0");
		if (!hasOptions(q)) {
			// 无选项题：人类把答案写在决策文本或备注里，都属于「自由文本回答」。
			const text = custom || labels.join("\n");
			return {
				answers: [{ id, selected: [], ...(text ? { custom: text } : {}) }],
			};
		}
		return {
			answers: [
				{
					id,
					selected: labels,
					...(custom ? { custom } : {}),
				},
			],
		};
	}

	// 多问题：按 label 归属把选择分配给各自的问题；备注归给第一个问题。
	let customUsed = false;
	const answers = list.map((q, i) => {
		const id = String(q?.id ?? String(i));
		const labels_q = optionLabels(q);
		const selected = labels.filter((l) => labels_q.includes(l));
		let qCustom;
		if (custom && !customUsed) {
			qCustom = custom;
			customUsed = true;
		}
		// 无选项题且人没写备注：退而把决策文本整段给它（否则它的答案永远是空的）。
		if (qCustom === undefined && !hasOptions(q) && note === undefined) {
			const text = labels.join("\n");
			if (text) qCustom = text;
		}
		return { id, selected, ...(qCustom ? { custom: qCustom } : {}) };
	});

	return { answers };
}

/**
 * 决策是否「什么都没答」——用来在提交前拦住空回答（不把空答案喂给模型）。
 *
 * 允许多选时空 selected 但有 custom 也算答了；两者都空才算没答。
 */
export function isBlankAnswer(questions, decision, note) {
	const labels = String(decision || "")
		.split("\n")
		.map((s) => s.trim())
		.filter(Boolean);
	const custom = typeof note === "string" ? note.trim() : "";
	if (labels.length > 0 || custom) return false;
	// 全部问题都没有选项、人也没写字 → 确实什么都没答
	const list = Array.isArray(questions) ? questions.filter(Boolean) : [];
	return list.some((q) => hasOptions(q)) || list.length === 0;
}