@zhushanwen/pi-ask-user 0.0.4 → 0.2.0

package/ARCHITECTURE.md

@@ -0,0 +1,171 @@
+# ask-user — Architecture
+
+Internals reference for maintainers. For the usage contract (what the tool does, when an agent should call it), see [README.md](./README.md). This document covers how the code is structured, the state machine, the defensive execute flow, and where each design invariant is enforced — so a change does not silently break an invariant.
+
+Source: 6 files in `src/`, ~1320 lines total.
+
+## File dependency graph
+
+```
+                          ┌─────────────┐
+                          │  types.ts   │  ← shared leaf; imports only typebox
+                          │ Schema +    │     holds QuestionState / ThemeLike /
+                          │ shared      │     createQuestionState here (NOT in
+                          │ state types │     component.ts) to break the cycle
+                          └──────▲──────┘
+                                 │ imported by all
+              ┌──────────────────┼──────────────────┐
+              │                  │                  │
+       ┌──────┴──────┐    ┌──────┴──────┐    ┌──────┴──────┐
+       │ validate.ts │    │question-view│    │ submit-view │
+       │ pure check  │    │ pure render │    │ pure render │
+       └──────▲──────┘    └──────▲──────┘    └──────▲──────┘
+              │                  │                  │
+              │           ┌──────┴──────────────────┘
+              │           │
+       ┌──────┴───────────┴──┐
+       │   component.ts      │  ← state machine + input routing + race guards
+       │                      │     imports question-view + submit-view
+       └──────────▲──────────┘
+                  │
+           ┌──────┴──────┐
+           │  index.ts   │  ← Tool factory + execute (6-step flow) + renderCall/renderResult
+           └─────────────┘     imports component + validate + types
+```
+
+**No cycles.** All imports flow one direction; `types.ts` is the single leaf depended on by everyone.
+
+**Why `QuestionState` / `ThemeLike` live in `types.ts`, not `component.ts`** (see the comment in `types.ts`): `question-view.ts` and `submit-view.ts` are pure render functions that read/write `QuestionState` and need the `ThemeLike` interface. If those types lived in `component.ts`, the render views would import `component.ts`, and `component.ts` imports the render views — a cycle. Sinking the shared types to the dependency-free leaf keeps every arrow monotone. **Do not move these types back** without reintroducing the cycle.
+
+## `execute` defensive flow (6 steps)
+
+`execute` in `src/index.ts` runs six ordered checks. Order is not arbitrary — each early step is cheaper than the next and some have side effects that must precede the rest.
+
+| Step | Check | Returns | Why this order |
+|------|-------|---------|----------------|
+| 1 | `validateInput(questions)` | `isError:true` + fix hint | Pure function, no side effects — cheapest gate. Reject before any UI/state work. |
+| 2 | `!ctx.hasUI` (headless) | `isError:true` + **`setActiveTools` removes ask_user** | Must run before the agent can retry. Physically removing the tool breaks a function-calling retry loop that plain `isError` cannot. |
+| 3 | `signal?.aborted` | `cancelled:true` | O(1) short-circuit before the expensive blocking `ctx.ui.custom` call. |
+| 4 | `try { ctx.ui.custom(...) } catch` | `isError:true` + `{ error }` | `ctx.ui.custom` is the only call that runs user interaction / editor construction / theme reads — the largest blast radius, so it is the only thing wrapped. |
+| 5 | `result === null \|\| result.cancelled` | `cancelled:true` | Component resolved to cancel. |
+| 6 | normal | `{ answers }` | Compose the summary. |
+
+**The order is load-bearing**: swapping 1↔2 wastes a UI check on invalid params; swapping 2↔3 lets an aborted agent enter a blocking UI; moving 4's try/catch wider catches nothing extra. The headless branch's `setActiveTools` is the key insight — returning `isError` alone does not stop an LLM from calling the tool again in the same turn, so the tool is removed from the session's active set and the error text says "do not retry".
+
+## `QuestionState` machine
+
+Each question has a `QuestionState` (`types.ts`). Its `mode` field is a three-state machine:
+
+```
+                       Enter (on Other row)
+            ┌────────────────────────────────────┐
+            ▼                                     │
+     ┌─────────────┐   Enter (normal opt,          ┌──────────────┐
+     │   options   │   allowComment=true) ────────▶│   comment    │
+     │  (default)  │                               │ (note input) │
+     └─────┬───▲───┘◀────────────────── afterConfirm└──────┬───▲───┘
+           │   │                                     Enter │   │ Esc
+   Enter   │   │ Esc (discard)              (save note)    │   │ (AC-17: skip,
+   (Other) │   │                                          │   │  keep old value)
+           ▼   │                                          ▼   │
+     ┌─────────────┐   Enter (text → save)          ┌─────────────┐
+     │  freeform   │───────────────────────────────▶│   options   │
+     │ (Other edit)│                                │ (back to list)│
+     └─────┬───▲───┘                                └─────────────┘
+           │   │
+           ▼   │ Esc (discard)
+     Enter (empty → clear freeTextValue)
+           │
+           ▼
+        options
+```
+
+Transitions live in `component.ts`: `options → freeform` (Enter on Other), `freeform → options` (Enter saves / Enter empty clears / Esc discards), `options → comment` (via `afterConfirm` when `allowComment`), `comment → options` (Enter saves / Esc skips per AC-17).
+
+### `confirmed` invariant
+
+> **`confirmed === true` ⟹ the question has at least one answer.**
+> I.e. `multiSelect ? selectedIndices.size > 0 : selectedIndex !== null`, **or** `freeTextValue !== null`.
+
+This invariant is what makes the Submit gate (`allConfirmed()`) sound — if it ever fails, Submit lets through a question whose answer is missing, and the LLM receives `(no answer)`.
+
+Four assignment sites maintain it (`component.ts`):
+
+| Site | Sets | Why safe / necessary |
+|------|------|----------------------|
+| `afterConfirm()` | `true` | Safe: caller has already set `selectedIndex` / `selectedIndices` / `freeTextValue`. |
+| `autoConfirmIfAnswered()` | `true` | Safe: guarded by `if (hasAnswer)` — never sets `true` without an answer. |
+| `toggleIndex()` when multi-select empties | `false` | Necessary: un-checking the last option must drop `confirmed` to preserve the contrapositive. |
+| `handleEditorInput` freeform empty-Enter | `false` | Necessary: clearing `freeTextValue` with no other answer must drop `confirmed`. |
+
+If you add a new path that changes the answer set, audit both directions of this invariant.
+
+### `autoConfirmIfAnswered` trigger
+
+Called only from `gotoTab()` — when the user navigates between tabs via Tab/Shift+Tab without pressing Enter. It promotes an implicitly-answered tab (toggled but not confirmed) to `confirmed`. It deliberately **skips the comment input** (a Tab navigation intent should not force a comment prompt); only the Enter path enters comment mode via `afterConfirm`.
+
+## Race guards
+
+Three independent guards protect against three different races. They are dimensionally orthogonal but easy to confuse — keep them distinct.
+
+| Guard | Kind | Location | Prevents | Mechanism |
+|-------|------|----------|----------|-----------|
+| `_resolved` | `boolean` field | `component.ts` | **Double `done()`**: user already submitted/cancelled, then a signal-abort listener or a late keypress fires `done` again → Pi receives two resolves. | `submit()`/`cancel()` set `_resolved = true` before `done(...)`; **both `handleInput` and `cancel()` itself early-return if already set** — so a signal-abort firing after resolution (the listener calls `comp.cancel()`) is a no-op (see `execute` step 4). |
+| `pendingCancel` | `boolean` field | `component.ts` | **Accidental cancel losing answers**: Esc on the first question (or single question) cancelling outright would discard everything. | Two-step confirm: first Esc sets `pendingCancel = true` and shows an overlay; a second Esc truly cancels; any other key exits the overlay and keeps the form. The Submit-tab Cancel button bypasses this (already at the terminus). |
+| `autoConfirmIfAnswered` | **method** (not a field) | `component.ts` | **Zombie unanswered tab**: in multi-question mode, toggling an option then Tab-ing away leaves a tab "answered but not confirmed", so the Submit gate (`allConfirmed()`) stays false and the user cannot tell why Submit is blocked. | `gotoTab()` calls it before switching; if the current state has an answer but `!confirmed`, it sets `confirmed = true`. |
+
+## Three-layer rendering
+
+Three independent render paths with non-overlapping jobs. Changing one layer never affects the others (unless you change the `details` schema, which feeds `renderResult`).
+
+| Layer | When | Location | Job | Returns |
+|-------|------|----------|-----|---------|
+| `renderCall` | tool invoked, while `execute` is running (during interaction) | `index.ts` | Compact title: `ask_user <headers>` — tells the user what the agent is asking. | one `TruncatedText` |
+| inline render (execute) | after `ctx.ui.custom` returns the component, the runtime loops `comp.render(width)` | factory in `index.ts`, render in `component.ts` | The live interactive TUI: option list / editor / tab bar / button bar / cancel overlay. | `string[]` (one per line) |
+| `renderResult` | after `execute` returns | `index.ts` | Final result display. Compact: `✓ header: answer`; when `options.expanded`: all options with `●`/`○` selection marks. | `Box` of `TruncatedText`s |
+
+## Split-pane adaptive layout
+
+`getSplitPaneWidths(width)` in `question-view.ts` is a pure function with three-level degradation:
+
+```
+width < 84                                    → null  (single column)
+available = width - len(" │ ")                // separator overhead
+available < 32 + 28 (= 60)                    → null  (too narrow)
+preferredLeft = floor(available * 0.42)
+left  = clamp(preferredLeft, 32, available - 28)
+right = available - left
+right < 28                                    → null  (fallback)
+```
+
+So the **left column (option list) takes 42%, the right column (option detail) takes 58%**, with floors of 32 and 28 respectively, and a total split threshold of 84 columns. `buildSplitPane` pads the shorter column to `max(leftLines, rightLines, 8)` so the two stay aligned row-for-row.
+
+Constants: `SPLIT_PANE_MIN_WIDTH = 84`, `SPLIT_PANE_LEFT_MIN = 32`, `SPLIT_PANE_RIGHT_MIN = 28`, `SPLIT_PANE_SEPARATOR = " │ "` (all in `types.ts`).
+
+## Spec cross-reference
+
+Design spec: `.xyz-harness/2026-06-15-ask-user/spec.md` (FR = functional requirement, AC = acceptance criterion). Implementation anchors:
+
+| Spec | Implemented in |
+|------|----------------|
+| FR-2 (param schema/validation) | `types.ts` schema + `validate.ts` |
+| FR-3 (inline render, no overlay) | `execute` → `ctx.ui.custom` without `options` |
+| FR-4 (question view) | `question-view.ts` `renderQuestionView` |
+| FR-6 (input handling) | `component.ts` `handleInput` / `handleEditorInput` |
+| FR-8 (headless disable) | `execute` step 2 |
+| FR-9 (custom render) | `renderCall` / `renderResult` |
+| FR-10 (signal abort) | `execute` step 3 + step 4 abort listener |
+| FR-12 (re-entry guard) | `_resolved` field + `cancel()` shared by abort listener |
+| FR-13 (error catch-all) | `execute` step 4 try/catch |
+| AC-17 (Esc in comment skips, keeps value) | `handleEditorInput` comment-mode Esc branch |
+
+When you change one of these behaviors, update both the code comment (which cites the FR/AC) and this table.
+
+## Resolved gaps
+
+Previously surfaced by review, now fixed (kept as a maintenance trail):
+
+- **Abort-vs-cancel text collision** (FR-10) — resolved: `execute` step 3 now returns `"Agent aborted..."`, distinct from step 5's user-cancel text. — `src/index.ts`.
+- **`question` length limit not in schema** — resolved: the `QuestionSchema` description now states "≤1000 chars". — `src/types.ts`.
+- **`header` >12 chars silently truncated** — resolved: `validate.ts` now rejects headers over `HEADER_MAX_CHARS` instead of silently truncating in the UI. — `src/validate.ts`.
+- **`cancel()` re-entry race** (FR-12) — resolved: `cancel()` now guards with `_resolved`; a signal abort firing after submit/cancel no longer calls `done` twice. — `src/component.ts`.

package/README.md

@@ -1,6 +1,8 @@
 # @zhushanwen/pi-ask-user
 
-Inline adaptive `ask_user` tool for Pi coding agent. Single question (no tabs) or 1-4 questions (tab view + submit). Split-pane Markdown preview on wide terminals, inline free-text editor, optional comments.
+Inline adaptive `ask_user` tool for the Pi coding agent. Resolves ambiguity the agent cannot resolve itself — a single question (no tab bar) or 1-4 questions (tabbed view + submit), with split-pane option preview on wide terminals, an inline free-text editor, and optional comments.
+
+The tool's primary caller is the LLM. This README covers both **how an agent should use it** (top sections) and **how a maintainer reads the code** (File structure → Design notes).
 
 ## Install
 
@@ -8,15 +10,139 @@ Inline adaptive `ask_user` tool for Pi coding agent. Single question (no tabs) o
 pi install npm:@zhushanwen/pi-ask-user
 ```
 
-## Tool
+> **Dev-only symlink**: during local development you may symlink this package into `~/.pi/agent/extensions/` for debugging, but **never use the symlinked copy for daily work**. Local directory discovery has an `index.ts` fallback that masks a missing `pi` manifest field — npm-installed copies then silently fail to load. See the repo root CLAUDE.md "扩展安装红线".
+
+## When to use
+
+Call `ask_user` **only when all three hold**:
+
+1. The request has ≥2 reasonable approaches.
+2. You have already gathered context (read/grep) and the answer is still genuinely ambiguous.
+3. Picking wrong means redoing real work.
+
+If you can form a defensible recommendation from the codebase, **proceed and state your choice** — do not ask. Models over-ask because asking feels safer than deciding; resist this.
+
+## When NOT to use
+
+- **Trivia answerable by reading code/docs** — plain text suffices.
+- **Simple confirmations** ("I'll delete X") — plain text suffices.
+- **Outsourcing judgment you should make** — if context makes the answer clear, decide.
+- **Free-form requirements / long-form feedback** — this tool returns short selections only.
+- **High-frequency grilling** — do not chain `ask_user` calls as a default fallback when stuck. If you have no context to pass, you are not ready to ask — read code first.
+- **Reversible decisions** — if a wrong guess is cheap to roll back, just decide.
+
+If you recommend an option, prefix its label with `(Recommended)` and list it first.
+
+## Parameters
+
+```typescript
+{
+  questions: Array<{
+    question: string;        // one self-contained decision; ≤1000 chars; no control chars (incl. \n)
+    header?: string;         // tab label ≤12 chars; REQUIRED (non-empty) when questions.length > 1
+    context?: string;        // 1-3 sentences of what you learned; shown above the question
+    options: Array<{         // 2-4 mutually exclusive options; do NOT add an 'Other' — it is automatic
+      label: string;         // ≤ ~40 chars (longer overflows the split-pane UI); also the answer value
+      description?: string;  // short rationale shown under the label and in the preview pane
+    }>;
+    multiSelect?: boolean;   // default false; true only when several options can validly apply
+    allowComment?: boolean;  // default false; lets the user append a free-text note after selecting
+  }>
+}  // questions: 1-4 entries
+```
+
+**Constraints at a glance**
+
+| Field | Constraint | Enforced by |
+|-------|-----------|-------------|
+| `questions` | 1-4 entries | schema (`minItems`/`maxItems`) |
+| `options` | 2-4 entries | schema |
+| `question` | ≤1000 chars, no control chars (incl. `\n`), unique within the call | schema description + `validate.ts` |
+| `header` | ≤12 chars; required when `questions.length > 1` | `validate.ts` (length + non-empty) |
+| `options[].label` | non-empty, unique within the question | `validate.ts` |
+
+Validation errors are returned as `isError: true` with a message that names the violation and tells you how to fix it — correct the parameters and retry.
+
+## Result format
+
+On success the tool returns the answers joined as `"question" = "answer"` lines. Answer composition rules:
+
+- **Single-select**: the chosen `label`.
+- **Multi-select**: selected labels joined with `, ` (e.g. `A, B`).
+- **Free-text (Other)**: whatever the user typed.
+- **Comment**: if `allowComment` was set, the user's note is appended after ` — ` (e.g. `Postgres — needs TLS`).
+
+A question with no answer reports as `(no answer)`.
+
+## Behavior on failure / cancellation
 
-`ask_user` — structured clarifying questions with 2-4 options each. Users can always pick "Other" for free-text input. Supports `multiSelect` and optional per-question comments.
+| Situation | Return | What the agent should do |
+|-----------|--------|--------------------------|
+| Parameter validation fails | `isError: true` + fix hint | Correct params and retry |
+| No interactive UI (headless) | `isError: true`, tool **disabled for the session** | Proceed with a defensible decision stated in text, or wait for the user — **do not retry** |
+| Agent aborted (goal cancelled / context compacted) | `cancelled: true` | The text identifies it as an agent abort, not a user cancel. Do not assume an answer; do not retry ask_user — propagate the abort, or wait for new instructions if the decision is still required. |
+| User cancels (Esc → confirm, or Cancel button) | `cancelled: true` | Wait for new instructions, or re-ask with refined options if the decision is still required |
+| Unexpected error | `isError: true` + `{ error }` | Retry once with corrected parameters, or proceed with a defensible decision |
+
+The headless branch physically removes the tool from the session (`setActiveTools`) — this is deliberate, so a function-calling loop cannot keep retrying `ask_user` in a non-interactive context.
 
 ## Features
 
-- **Adaptive layout**: single question → no tab bar; 1-4 questions → tabbed view + Submit tab
-- **Split-pane preview** (≥84 cols): option list left, selected option details right
-- **Inline free-text editor**: select "Other" → Enter → type custom answer
-- **Optional comments**: `allowComment: true` → after selection, prompt for a comment
-- **Multi-select**: `multiSelect: true` → toggle checkboxes, Enter to confirm
-- **Headless-safe**: disables the tool and returns `isError` when no UI available
+- **Adaptive layout**: single question → no tab bar; 1-4 questions → tabbed view + Submit tab.
+- **Split-pane preview** (≥84 cols): option list left, selected option detail right. The right pane is **plain-text** option detail (label + description), not a Markdown renderer.
+- **Inline free-text editor**: select "Other" → Enter → type a custom answer. Multi-line aware, soft-wrapped.
+- **Optional comments**: `allowComment: true` → after selecting, the user may append a short note.
+- **Multi-select**: `multiSelect: true` → toggle checkboxes with Space, Enter to confirm.
+- **Esc confirm-to-cancel**: Esc on the first question opens a confirm overlay (a second Esc cancels; any other key stays).
+- **Headless-safe**: disables the tool and returns `isError` when no UI is available.
+
+## File structure
+
+```
+extensions/ask-user/
+├── index.ts                  # re-export entry (Pi loads via package.json pi.extensions)
+├── package.json
+├── README.md                 # this file — usage contract for LLM callers + overview
+├── ARCHITECTURE.md           # internals: dependency graph, state machine, defensive flow
+├── vitest.config.ts
+└── src/
+    ├── index.ts              # Tool factory: registerTool + execute (6-step defensive flow) + renderCall/renderResult
+    ├── types.ts              # Input schema, Result schema, shared state types (QuestionState/ThemeLike) — dependency leaf
+    ├── validate.ts           # pure parameter validation; error messages aimed at LLM fixability
+    ├── component.ts          # AskUserComponent: state machine, input routing, race guards
+    ├── question-view.ts      # pure render: option list, split-pane, inline editor
+    └── submit-view.ts        # pure render: Submit tab, answer summary, buildResult
+```
+
+`types.ts` is intentionally the shared dependency leaf — it holds `QuestionState`/`ThemeLike` (not `component.ts`) so the two pure-render views depend only on the leaf, breaking a would-be `component → view → component` cycle. See ARCHITECTURE.md for the full graph.
+
+## Steer mechanism
+
+The tool registers three steering channels to discourage over-asking:
+
+- **`description`** — the long tool description shown in the agent's tool catalog (the three preconditions + negative cases).
+- **`promptSnippet`** — one-line summary injected into the system prompt.
+- **`promptGuidelines`** — six focused rules reinforcing: gather context first, one decision per question, no trivia, don't outsource judgment, don't add an `Other` option.
+
+All three are consistent and point the same direction. If you tune behavior, edit all three together in `src/index.ts` to avoid drift.
+
+## Design notes
+
+- **Why inline, not overlay** (`execute` → `ctx.ui.custom` without `options`): the question belongs in the conversation flow, not a modal that obscures context.
+- **Why `Other` is auto-appended, not in the schema**: free-text input is the user's escape hatch and must not be something the LLM can omit or mislabel. Keeping it out of `options` guarantees it is always present and always last.
+- **Why `←/→` does not switch tabs**: left/right is reserved for the Submit tab's Submit/Cancel focus toggle, so it does not yank focus away while navigating an option list.
+- **Why validation messages are verbose**: every message names the violation and gives a fix path, because the reader is an LLM that will retry.
+
+## Spec reference
+
+The original design spec, acceptance criteria (FR-x / AC-x), and E2E test cases live under `.xyz-harness/2026-06-15-ask-user/`:
+
+- `spec.md` — requirements + functional/acceptance criteria
+- `e2e-test-cases.md` — end-to-end scenarios
+- `clarification.md` / `plan.md` — design rationale
+
+Cross-references between these and the implementation are in ARCHITECTURE.md.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-ask-user",
-  "version": "0.0.4",
+  "version": "0.2.0",
   "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",
@@ -22,8 +22,12 @@
   "files": [
     "index.ts",
     "src/",
-    "README.md"
+    "README.md",
+    "ARCHITECTURE.md"
   ],
+  "dependencies": {
+    "@xyz-agent/extension-protocol": "^0.2.0"
+  },
   "devDependencies": {
     "@earendil-works/pi-tui": "*",
     "@sinclair/typebox": "*",

package/src/__tests__/answer-format.test.ts

@@ -0,0 +1,107 @@
+// src/__tests__/answer-format.test.ts
+//
+// answer-format.ts 独立单元测试。
+// 覆盖审查 S5 发现的覆盖盲区：
+//   - parseAnswerParts 子串误匹配（"A" 不应命中 "AB"）
+//   - formatAnswer 空 parts → null
+//   - comment 分隔符边界
+
+import { describe, expect, it } from "vitest";
+
+import { formatAnswer, parseAnswerParts } from "../answer-format.js";
+import { ANSWER_COMMENT_SEPARATOR } from "../types.js";
+
+describe("formatAnswer", () => {
+	it("returns null for empty parts (unanswered)", () => {
+		expect(formatAnswer([])).toBeNull();
+	});
+
+	it("returns null for empty parts even with comment", () => {
+		// parts 空 = 没有选中选项，即使有 comment 也不应产出有效答案行
+		expect(formatAnswer([], "some comment")).toBeNull();
+	});
+
+	it("joins single part without separator", () => {
+		expect(formatAnswer(["yes"])).toBe("yes");
+	});
+
+	it("joins multiple parts with ', '", () => {
+		expect(formatAnswer(["A", "B", "C"])).toBe("A, B, C");
+	});
+
+	it("appends comment with ANSWER_COMMENT_SEPARATOR", () => {
+		const result = formatAnswer(["A", "B"], "my comment");
+		expect(result).toBe(`A, B${ANSWER_COMMENT_SEPARATOR}my comment`);
+	});
+
+	it("handles null comment (no separator appended)", () => {
+		expect(formatAnswer(["A"], null)).toBe("A");
+	});
+});
+
+describe("parseAnswerParts", () => {
+	it("extracts selected labels by exact match", () => {
+		const labels = ["yes", "no", "maybe"];
+		const result = parseAnswerParts("yes, no", labels);
+		expect(result.selected).toEqual(["yes", "no"]);
+		expect(result.comment).toBeUndefined();
+	});
+
+	// S5 核心：防子串误匹配——"A" 不应命中 label "AB"
+	it("does NOT match substring labels (A vs AB)", () => {
+		const labels = ["A", "AB", "ABC"];
+		// 答案 "A, AB" 应精确匹配两个 label，而非 "A" 匹配三次
+		const result = parseAnswerParts("A, AB", labels);
+		expect(result.selected).toEqual(["A", "AB"]);
+	});
+
+	it("does NOT match 'A' when only 'AB' is in answer", () => {
+		const labels = ["A", "AB"];
+		// 答案 "AB" 只应命中 "AB"，不应命中 "A"
+		const result = parseAnswerParts("AB", labels);
+		expect(result.selected).toEqual(["AB"]);
+	});
+
+	it("preserves order of appearance in answer (not label order)", () => {
+		const labels = ["A", "B", "C"];
+		// 用户选择顺序可能与 options 定义顺序不同
+		const result = parseAnswerParts("C, A", labels);
+		expect(result.selected).toEqual(["C", "A"]);
+	});
+
+	it("extracts comment after ANSWER_COMMENT_SEPARATOR", () => {
+		const labels = ["yes"];
+		const answer = `yes${ANSWER_COMMENT_SEPARATOR}because reasons`;
+		const result = parseAnswerParts(answer, labels);
+		expect(result.selected).toEqual(["yes"]);
+		expect(result.comment).toBe("because reasons");
+	});
+
+	it("handles full-width comma (，) as separator", () => {
+		const labels = ["A", "B"];
+		const result = parseAnswerParts("A，B", labels);
+		expect(result.selected).toEqual(["A", "B"]);
+	});
+
+	it("returns non-matching tokens as neither selected nor comment (Other free text)", () => {
+		const labels = ["yes", "no"];
+		// "custom text" 不匹配任何 label → 是 Other 自由文本
+		const result = parseAnswerParts("custom text", labels);
+		expect(result.selected).toEqual([]);
+		expect(result.comment).toBeUndefined();
+	});
+
+	it("handles empty answer string", () => {
+		const result = parseAnswerParts("", ["A", "B"]);
+		expect(result.selected).toEqual([]);
+		expect(result.comment).toBeUndefined();
+	});
+
+	it("handles answer with only comment (no selected labels)", () => {
+		const labels = ["A"];
+		const answer = `${ANSWER_COMMENT_SEPARATOR}just a comment`;
+		const result = parseAnswerParts(answer, labels);
+		expect(result.selected).toEqual([]);
+		expect(result.comment).toBe("just a comment");
+	});
+});