@zhushanwen/pi-ask-user 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-ask-user",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Inline adaptive ask_user tool for Pi — single/multi-question structured input with split-pane preview, inline editor, and optional comments.",
   "type": "module",
   "main": "index.ts",

package/src/__tests__/index.test.ts

@@ -204,6 +204,24 @@ describe("execute — validation (FR-2 / AC-8 / AC-13)", () => {
 		);
 		expect(result.details.cancelled).toBe(true);
 	});
+
+	it("I-4b: string options (schema-relaxed) → execute → validateInput catches → isError + Correct hint", async () => {
+		// 端到端证明：schema 放宽（Union([OptionSchema, string])）后 string options
+		// 能穿过 TypeCompiler.Check、抵达 execute → validateInput 友好拦截。
+		// test-coverage reviewer 点名的“execute wiring 未测”缺口。
+		const tool = getTool();
+		const result = await tool.execute(
+			"id",
+			{ questions: [{ question: "Q", options: ["A", "B"] }] },
+			undefined,
+			undefined,
+			makeCtx(),
+		);
+		expect(result.isError).toBe(true);
+		expect(result.details.cancelled).toBe(true);
+		expect(result.content[0].text).toContain("not strings");
+		expect(result.content[0].text).toContain("Correct");
+	});
 });
 
 // ── I-5 ~ I-7: Headless（FR-8 / AC-7）──────────────────

package/src/__tests__/prompt-quality.test.ts

@@ -0,0 +1,95 @@
+// src/__tests__/prompt-quality.test.ts
+//
+// 提示词质量回归：ask_user tool 的 description 与 validate.ts 文案必须能让弱模型
+// 首次调用就用对参数形状，用错了也能拿到带 Correct 正例的纠正。
+//
+// 背景（系统性债务）：
+//  - description 缺 JSON 正例：弱模型最高频错误是把 options 当字符串数组传
+//    （"options":["A","B"] 而非 [{"label","description"}]）。
+//  - 条件必填（header）用 Type.Optional 表达，弱模型批量时漏 header。
+//  - schema 层 ajv 干报错先于 validate.ts 友好文案——故 InputSchema 故意放宽 options
+//    元素到 string，让误用能抵达 validateInput 的带正例纠正。
+//
+// 本测试用源码断言（读 .ts 文件文本）锁定这些约束，防止后续重构把正例/反例/调用信号
+// 删掉或弱化。读源码而非 import，避免 mock 链（index.ts 依赖 pi-tui/ExtensionAPI 等）。
+
+import { readFileSync } from "node:fs";
+import { dirname,join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const INDEX_SRC = readFileSync(join(__dirname, "../index.ts"), "utf-8");
+const VALIDATE_SRC = readFileSync(join(__dirname, "../validate.ts"), "utf-8");
+
+/** 提取 description: `...` 模板字符串的原始内容（模板内无反引号，匹配到闭合 `,）。 */
+function extractDescription(src: string): string {
+	const m = src.match(/description:\s*`([\s\S]*?)`,/);
+	if (!m) throw new Error("description template literal not found in index.ts");
+	return m[1];
+}
+
+const DESCRIPTION = extractDescription(INDEX_SRC);
+
+describe("ask_user description — 参数形状正例（B. 补正例）", () => {
+	it("含单问题 JSON 正例，options 为 {label, description} 对象数组", () => {
+		// 弱模型最高频错误是把 options 当字符串数组传；正例必须显式给出对象形态。
+		expect(DESCRIPTION).toContain('"options":[{"label"');
+		expect(DESCRIPTION).toContain('"question"');
+	});
+
+	it("含批量 JSON 正例，每个 question 带 header", () => {
+		// 批量模式下 header 是条件必填，正例必须展示 header 字段。
+		expect(DESCRIPTION).toContain('"header"');
+		// 批量正例含多个 question（questions 数组里至少两个 header）
+		const headerMatches = DESCRIPTION.match(/"header"/g) || [];
+		expect(headerMatches.length).toBeGreaterThanOrEqual(2);
+	});
+
+	it("正例里的 label 可带 (Recommended) 前缀（调用信号未被破坏）", () => {
+		expect(DESCRIPTION).toContain("(Recommended)");
+	});
+});
+
+describe("ask_user description — 参数结构反例（B. 补反例）", () => {
+	it("含 ≥2 条参数结构反例（string array / flatten / Other 等）", () => {
+		// 锁定关键反例措辞，防止后续精简掉。
+		const antiPatterns = [
+			"string array", // options 不能当字符串数组传
+			"Flatten", // 不能把字段铺到顶层（匹配 Flattening/Flatten）
+			"Other", // 不能手动加 Other
+		];
+		const hits = antiPatterns.filter((p) => DESCRIPTION.includes(p));
+		expect(hits.length).toBeGreaterThanOrEqual(2);
+	});
+});
+
+describe("ask_user description — 调用信号保留（不要破坏亮点）", () => {
+	it("保留 'Use ONLY when ALL hold' 调用门槛", () => {
+		// 这是 ask_user 写得比 subagent 原版好的调用信号引导，必须保留。
+		expect(DESCRIPTION).toContain("Use ONLY when");
+	});
+
+	it("保留 'Do NOT use' 边界段", () => {
+		expect(DESCRIPTION).toContain("Do NOT use");
+	});
+});
+
+describe("validate.ts — runtime 友好纠错（A. 带正例）", () => {
+	it("含 options 字符串元素检测（'objects, not strings'）", () => {
+		// schema 层已放宽让 string options 进到这里；validate 必须友好拦截。
+		expect(VALIDATE_SRC).toContain("objects, not strings");
+	});
+
+	it("options 字符串错误带 Correct 正例", () => {
+		// 友好文案必须给出最小可用形状，让弱模型直接抄。
+		expect(VALIDATE_SRC).toContain('Correct: "options":[{"label"');
+	});
+
+	it("header 缺失错误带 Correct 正例", () => {
+		// 多问题模式漏 header 是弱模型批量时的常见错误，纠正文案要带正例。
+		expect(VALIDATE_SRC).toContain("Correct: {\"header\"");
+	});
+});

package/src/__tests__/validate.test.ts

@@ -1,7 +1,8 @@
 // src/__tests__/validate.test.ts
+import { Value } from "@sinclair/typebox/value";
 import { describe, expect, it } from "vitest";
 
-import { HEADER_MAX_CHARS, type Question } from "../types";
+import { HEADER_MAX_CHARS, InputSchema, type Question } from "../types";
 import { validateInput } from "../validate";
 
 const q = (overrides: Partial<Question> = {}): Question => ({
@@ -136,4 +137,67 @@ describe("validateInput", () => {
 	it("accepts header at exactly HEADER_MAX_CHARS (12)", () => {
 		expect(validateInput([q({ header: "123456789012" })])).toBeNull();
 	});
+
+	// V-17: options 元素是 string（弱模型最高频误用 "options":["A","B"]）→ 友好错误带 Correct 正例。
+	// schema 层已放宽让 string options 能进到这里（见 types.ts InputSchema），故可直接传 string[]。
+	it("rejects string option elements with a Correct example (weak-model misuse)", () => {
+		const result = validateInput([
+			{ question: "Which DB?", options: ["Postgres", "SQLite"] },
+		]);
+		expect(result).not.toBeNull();
+		expect(result).toContain("objects, not strings");
+		expect(result).toContain('Correct: "options":[{"label"');
+	});
+
+	// V-18: 混合 [string, object] → 仍友好拦截第一个 string 元素
+	it("rejects mixed string/object options", () => {
+		const result = validateInput([
+			{ question: "Q", options: ["A", { label: "B" }] },
+		]);
+		expect(result).toContain("objects, not strings");
+	});
+
+	// V-19: header 缺失错误带 Correct 正例（A. runtime 友好纠错）
+	it("header-missing error includes a Correct example", () => {
+		const result = validateInput([
+			q({ question: "Q1", header: "H1" }),
+			q({ question: "Q2" }), // no header
+		]);
+		expect(result).toContain("Correct:");
+		expect(result).toContain('"header"');
+	});
+});
+
+// ── options 字符串「下沉」机制集成证明 ──────────────────
+// 目标（任务核心）：弱模型误用 "options":["A","B"] 不能被 schema 层干报错拦死，
+// 必须能进 validateInput 拿到带 Correct 正例的友好文案。Value.Check 是 Pi 运行时
+// TypeCompiler.Check 的等价校验（同一引擎），这里直接断言 schema 行为。
+describe("schema-vs-validate integration (options 字符串下沉)", () => {
+	it("string options PASS the schema layer (reach execute, not raw ajv error)", () => {
+		const malformed = {
+			questions: [{ question: "Which DB?", options: ["Postgres", "SQLite"] }],
+		};
+		expect(Value.Check(InputSchema, malformed)).toBe(true);
+	});
+
+	it("string options then caught by validateInput with a friendly Correct example", () => {
+		const result = validateInput([
+			{ question: "Which DB?", options: ["Postgres", "SQLite"] },
+		]);
+		expect(result).not.toBeNull();
+		expect(result).toContain("objects, not strings");
+		expect(result).toContain('Correct: "options":[{"label"');
+	});
+
+	it("well-formed object options still pass schema AND validateInput", () => {
+		const wellFormed = {
+			questions: [
+				{ question: "Which DB?", options: [{ label: "A" }, { label: "B" }] },
+			],
+		};
+		expect(Value.Check(InputSchema, wellFormed)).toBe(true);
+		expect(
+			validateInput([{ question: "Which DB?", options: [{ label: "A" }, { label: "B" }] }]),
+		).toBeNull();
+	});
 });

package/src/index.ts

@@ -233,7 +233,18 @@ export default function (pi: ExtensionAPI): void {
 
 Do NOT use this tool to outsource judgment you should make — if you can form a defensible recommendation from the codebase, proceed and state your choice. Do NOT use for trivia answerable by reading code/docs, or for simple confirmations ("I'll delete X") where plain text suffices. You cannot use this tool to collect free-form requirements, long-form feedback, or multi-paragraph input — it returns short selections only.
 
-If you recommend an option, prefix its label with "(Recommended)" and list it first. For structured multi-option decisions, prefer this tool over plain-text questions; for everything else, reply in plain text.`,
+If you recommend an option, prefix its label with "(Recommended)" and list it first. For structured multi-option decisions, prefer this tool over plain-text questions; for everything else, reply in plain text.
+
+Examples:
+{"questions":[{"question":"Which DB?","context":"Need ACID + JSON columns.","options":[{"label":"(Recommended) Postgres","description":"Mature, strong consistency."},{"label":"SQLite","description":"Zero-ops, embedded."}]}]}
+
+{"questions":[{"header":"DB","question":"Which database?","options":[{"label":"Postgres","description":"..."},{"label":"SQLite","description":"..."}]},{"header":"Region","question":"Which region?","options":[{"label":"us-east-1","description":"..."},{"label":"eu-west-1","description":"..."}]}]}
+
+Don't:
+- Passing options as a string array ("options":["A","B"]) — each option must be {"label","description"}.
+- Forgetting header in multi-question mode (questions.length > 1).
+- Flattening question/header/options to the top level — wrap them in questions:[...].
+- Including an "Other" option — it is added automatically.`,
 		promptSnippet:
 			"Ask the user structured clarifying questions with options — only when you cannot resolve the ambiguity yourself",
 		promptGuidelines: [
@@ -253,9 +264,11 @@ If you recommend an option, prefix its label with "(Recommended)" and list it fi
 			_onUpdate: AgentToolUpdateCallback<AskUserDetails> | undefined,
 			ctx: ExtensionContext,
 		): Promise<ExecuteResult> {
-			const questions = params.questions;
+			const questions = params.questions as Question[];
 
-			// 1. 参数校验（spec FR-2）
+			// 1. 参数校验（spec FR-2）。validateInput 接收宽松 InputQuestion[]：
+			// options 可能含 string 误用（schema 已故意放宽以抵达这里的友好文案），
+			// validateInput 会先拦截 string options 再跑其余校验。通过后 questions 已是干净 Question[]。
 			const validationError = validateInput(questions);
 			if (validationError) {
 				return cancelledResult(questions, `Error: ${validationError}`, true);
@@ -326,7 +339,8 @@ If you recommend an option, prefix its label with "(Recommended)" and list it fi
 		},
 
 		renderCall(args: Static<typeof InputSchema>, theme: ThemeLike) {
-			const questions: Question[] = args.questions ?? [];
+			// args 来自 LLM 原始入参（options 可能是 string），只读 header/question 不碰 options。
+			const questions = (args.questions ?? []) as Question[];
 			const topics = questions.map((q) => q.header ?? truncateToWidth(q.question, HEADER_MAX_CHARS)).join(", ");
 			return new TruncatedText(
 				theme.fg("toolTitle", theme.bold("ask_user ")) + theme.fg("muted", topics),

package/src/types.ts

@@ -52,17 +52,47 @@ export const QuestionSchema = Type.Object({
 	),
 });
 
+/**
+ * LLM-facing input schema (宽松版 options 元素)。
+ *
+ * options 元素故意放宽为 `OptionSchema | string`：弱模型最高频误用是把 options
+ * 当字符串数组传（`"options":["A","B"]`）。严格 schema 会让 Pi 运行时的 typebox
+ * TypeCompiler.Check 直接拦截（干报错 "must be object"），根本进不了 validateInput
+ * 的友好文案。这里放宽让 string 元素通过 schema 层、抵达 validateInput，由它返回带
+ * Correct 正例的纠正错误（runtime 友好纠错）。
+ *
+ * 字段描述复用 QuestionSchema.properties（只覆盖 options 数组元素类型），避免描述
+ * 双份维护。Static 派生的 InputQuestion.options 是 `(Option | string)[]`，让
+ * validateInput 里的 `typeof opt === "string"` 检查在 TS 层 sound（而非死分支）。
+ * 通过 validateInput 后，运行时已保证无 string，index.ts 以 `as Question[]` 收窄使用。
+ */
+const inputOptionElement = Type.Union([OptionSchema, Type.String()]);
+
 export const InputSchema = Type.Object({
-	questions: Type.Array(QuestionSchema, {
-		minItems: 1,
-		maxItems: 4,
-		description: "1-4 questions, each a single decision. Batch only related decisions that the user should resolve together; otherwise ask the most important one alone.",
-	}),
+	questions: Type.Array(
+		Type.Object({
+			...QuestionSchema.properties,
+			options: Type.Array(inputOptionElement, {
+				minItems: 2,
+				maxItems: 4,
+				description:
+					"2-4 mutually exclusive options. Each must be a {label, description} OBJECT, never a bare string; do NOT include an 'Other' option — it is added automatically.",
+			}),
+		}),
+		{
+			minItems: 1,
+			maxItems: 4,
+			description: "1-4 questions, each a single decision. Batch only related decisions that the user should resolve together; otherwise ask the most important one alone.",
+		},
+	),
 });
 
 // ── 派生类型 ─────────────────────────────────────────
 export type Option = Static<typeof OptionSchema>;
+/** 内部使用的严格 question 形状（options 为干净 Option[]）。validateInput 通过后使用。 */
 export type Question = Static<typeof QuestionSchema>;
+/** LLM 入参 question 形状：options 可能含 string 误用，validateInput 负责友好拦截。 */
+export type InputQuestion = Static<typeof InputSchema>["questions"][number];
 
 // ── Result schema（details，renderResult 数据源） ─────
 export const ResultSchema = Type.Object({

package/src/validate.ts

@@ -1,20 +1,29 @@
 // src/validate.ts
-import { HEADER_MAX_CHARS, type Question, QUESTION_MAX_CHARS } from "./types";
+import { HEADER_MAX_CHARS, type InputQuestion, QUESTION_MAX_CHARS } from "./types";
 
 /** 控制字符（含 \n \r \t 等）：question 文本禁止包含，避免 answers key 含不可见字符（spec FR-2） */
 const CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
 
+/** 错误消息里 question/header 文本预览的截断长度（避免长文本撑爆错误消息）。 */
+const ERROR_PREVIEW_CHARS = 20;
+
 /**
  * 校验输入参数。通过返回 null，失败返回错误消息字符串。
+ *
+ * 入参类型是宽松的 InputQuestion[]（options 元素可能是 string 误用）——见 types.ts
+ * InputSchema 注释。Pi 运行时只放宽到让 string options 能进到这里被友好拦截；这里先
+ * 预检 string options，再跑原有结构/语义校验。
+ *
  * 校验项（spec FR-2）：
+ * - options 元素必须是 {label, description} 对象，不能是 string（弱模型高频误用）
  * - question 文本长度上限与无控制字符（保证 answers key 有界、可预测）
  * - question 文本在数组内唯一
  * - 同问题内 option label 唯一
  * - 多问题（questions.length > 1）时每个 question 必须有非空 header
  *
- * 错误消息面向 LLM：除描述违规外，附带一句修复指引（如何改）。
+ * 错误消息面向 LLM：除描述违规外，附带一句修复指引（如何改），对结构误用附 Correct 正例。
  */
-export function validateInput(questions: Question[]): string | null {
+export function validateInput(questions: InputQuestion[]): string | null {
 	const seenQuestions = new Set<string>();
 
 	for (const q of questions) {
@@ -22,11 +31,11 @@ export function validateInput(questions: Question[]): string | null {
 
 		// 1a. question 文本长度上限（key 有界）
 		if (qt.length > QUESTION_MAX_CHARS) {
-			return `Question text exceeds ${QUESTION_MAX_CHARS} chars: "${qt.slice(0, 20)}...". Shorten it to a single concise decision; move extra context into the context field.`;
+			return `Question text exceeds ${QUESTION_MAX_CHARS} chars: "${qt.slice(0, ERROR_PREVIEW_CHARS)}...". Shorten it to a single concise decision; move extra context into the context field.`;
 		}
 		// 1b. question 文本无控制字符（key 可预测，不影响下游渲染/解析）
 		if (CONTROL_CHAR_RE.test(qt)) {
-			return `Question text must not contain control characters (incl. newlines): "${qt.slice(0, 20)}...". Use plain single-line text; split multi-part questions into separate entries.`;
+			return `Question text must not contain control characters (incl. newlines): "${qt.slice(0, ERROR_PREVIEW_CHARS)}...". Use plain single-line text; split multi-part questions into separate entries.`;
 		}
 
 		// 1c. question 文本唯一
@@ -35,14 +44,20 @@ export function validateInput(questions: Question[]): string | null {
 		}
 		seenQuestions.add(qt);
 
-		// 2. option label 唯一且非空（空 label 会污染 details.answers 的值）
+		// 2. option 元素必须是 {label, description} 对象，不能是 string。
+		//    弱模型最高频误用："options":["A","B"]。schema 层已放宽让 string 进来，这里友好拦截
+		//    （InputQuestion.options 是 (Option | string)[]，typeof 收窄后 opt 为 Option）。
 		const seenLabels = new Set<string>();
 		for (const opt of q.options) {
+			if (typeof opt === "string") {
+				return `Options for question "${qt}" must be an array of {label, description} objects, not strings. Correct: "options":[{"label":"A","description":"..."},{"label":"B","description":"..."}]`;
+			}
+			// opt 已收窄为 Option
 			if (opt.label.trim() === "") {
-				return `Option label must not be empty in question "${q.question}". Give every option a distinct, descriptive label.`;
+				return `Option label must not be empty in question "${qt}". Give every option a distinct, descriptive label.`;
 			}
 			if (seenLabels.has(opt.label)) {
-				return `Duplicate option label "${opt.label}" in question "${q.question}". Options must be mutually exclusive — reword one so each label maps to a distinct choice.`;
+				return `Duplicate option label "${opt.label}" in question "${qt}". Options must be mutually exclusive — reword one so each label maps to a distinct choice.`;
 			}
 			seenLabels.add(opt.label);
 		}
@@ -52,7 +67,7 @@ export function validateInput(questions: Question[]): string | null {
 	if (questions.length > 1) {
 		for (const q of questions) {
 			if (!q.header || q.header.trim() === "") {
-				return `Question "${q.question}" requires a non-empty header in multi-question mode (it labels the tab). Provide a header of <=12 chars.`;
+				return `Question "${q.question}" requires a non-empty header in multi-question mode (it labels the tab). Provide a header of <=12 chars. Correct: {"header":"DB","question":"...","options":[{"label":"...","description":"..."}]}`;
 			}
 		}
 
@@ -72,7 +87,7 @@ export function validateInput(questions: Question[]): string | null {
 	//    这里提前拒绝，让 LLM 拿到可修复错误而非残缺 UI（兑现 schema description 的 ≤12 契约）。
 	for (const q of questions) {
 		if (q.header !== undefined && q.header.length > HEADER_MAX_CHARS) {
-			return `Header exceeds ${HEADER_MAX_CHARS} chars: "${q.header.slice(0, 20)}..." in question "${q.question}". Shorten it; longer headers are truncated in the tab bar.`;
+			return `Header exceeds ${HEADER_MAX_CHARS} chars: "${q.header.slice(0, ERROR_PREVIEW_CHARS)}..." in question "${q.question}". Shorten it; longer headers are truncated in the tab bar.`;
 		}
 	}