min-agent 0.4.1 → 0.5.0

package/docs/superpowers/plans/2026-08-23-input-paste-attachments.md

@@ -0,0 +1,475 @@
+# 输入框粘贴图片与文本片段 — 实现计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 输入框 Ctrl+V 把剪贴板图片挂成 `[图片 #N]`；一次粘贴超过一行收成 `[粘贴 #N · X 行]`；Enter 时图片进 image part、片段展开全文；短标记留在对话区和输入历史。
+
+**Architecture:** 粘贴判定、附件表、展开逻辑放在无 React 的 `paste-draft.ts`；bracketed paste 扫包装在 `bracketed-paste.ts`；cluster 显示宽可注入，让现有 `visualRows` / 点击换算把私有区码点当成一块。InputBar 只持有草稿表并接线。`onSubmit` 改为 `SubmittedPrompt`。
+
+**Tech Stack:** TypeScript, React 18 + Ink 5, bun:test
+
+**Spec:** `docs/superpowers/specs/2026-08-23-input-paste-attachments-design.md`
+
+测试命令（`packages/min-agent` 下）：`bun test tests/<file>`；类型：`npx tsc --noEmit`；仓库根目录：`bun run typecheck`、`bun run check`。
+
+---
+
+## 文件结构
+
+| 文件 | 职责 |
+|------|------|
+| `src/tui/paste-draft.ts`（新） | 规范化粘贴、单行/多行、附件表、标记文案、展开 `display`/`content`、孤儿回收 |
+| `src/tui/bracketed-paste.ts`（新） | 启用序列、stdin 扫包、`useInput` 应忽略的碎片 |
+| `src/tui/text-width.ts`（改） | `wrapByWidth` 可选 cluster 宽度覆盖 |
+| `src/tui/caret-pos.ts`（改） | `visualRows` / `caretIndexFromClick` / `moveCaretVertical` 透传宽度覆盖 |
+| `src/tui/types.ts`（改） | 导出 `SubmittedPrompt`（或从 paste-draft 再导出） |
+| `src/tui/InputBar.tsx`（改） | bracketed paste、Ctrl+V、旁路表、绘制标记、`onNotice`、按 `SubmittedPrompt` 提交 |
+| `src/tui/App.tsx` `index.tsx`（改） | `onSubmit` / `onNotice` |
+| `src/tui-chat.ts`（改） | `display`/`content` 入列；`/` 走命令；`onNotice` → `sysMsg` |
+| `src/tui/slash-handler.ts`（改） | `/help` 快捷键 |
+| `README.md`（改） | 中英快捷键 |
+| `tests/paste-draft.test.ts`（新） | |
+| `tests/bracketed-paste.test.ts`（新） | |
+| `tests/caret-pos.test.ts`（改） | 宽标记点击 |
+
+`docs/API.md`、`skills/self-config/`、`/paste`、`/attach`、CLI `-i` 不改。
+
+---
+
+## Task 1: paste-draft.ts
+
+**Files:**
+- Create: `src/tui/paste-draft.ts`
+- Test: `tests/paste-draft.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+```ts
+import { expect, test } from "bun:test"
+import {
+  IMAGE_MAX_BYTES,
+  SNIPPET_MAX_CHARS,
+  NOTICE_IMAGE_TOO_LARGE,
+  NOTICE_SNIPPET_TOO_LARGE,
+  createPasteDraft,
+  normalizePastedText,
+  applyPastedText,
+  applyClipboardImage,
+  pruneAttachments,
+  expandDisplay,
+  expandContent,
+  resetPasteDraft,
+  chipClusterWidth,
+  imageLabel,
+  snippetLabel,
+} from "../src/tui/paste-draft.js"
+
+test("normalizePastedText maps CRLF and strips one trailing newline", () => {
+  expect(normalizePastedText("a\r\nb\r\n")).toBe("a\nb")
+  expect(normalizePastedText("hello\n")).toBe("hello")
+  expect(normalizePastedText("hello")).toBe("hello")
+  expect(normalizePastedText("\n")).toBe("")
+})
+
+test("single-line paste including a trailing newline inserts as text", () => {
+  const r = applyPastedText(createPasteDraft(), "hello\n")
+  expect(r.kind).toBe("text")
+  if (r.kind === "text") expect(r.text).toBe("hello")
+})
+
+test("paste with a remaining newline becomes a snippet chip", () => {
+  const r = applyPastedText(createPasteDraft(), "a\nb\n")
+  expect(r.kind).toBe("snippet")
+  if (r.kind !== "snippet") return
+  expect(expandDisplay(r.char, r.draft)).toBe("[粘贴 #1 · 2 行]")
+  expect(snippetLabel(1, 2)).toBe("[粘贴 #1 · 2 行]")
+})
+
+test("two snippets number independently from images", () => {
+  let draft = createPasteDraft()
+  const s1 = applyPastedText(draft, "a\nb")
+  if (s1.kind !== "snippet") throw new Error("expected snippet")
+  const img = applyClipboardImage(s1.draft, { data: Buffer.from("png"), mimeType: "image/png" })
+  if (img.kind !== "image") throw new Error("expected image")
+  const s2 = applyPastedText(img.draft, "c\nd")
+  if (s2.kind !== "snippet") throw new Error("expected snippet")
+  expect(expandDisplay(s1.char + img.char + s2.char, s2.draft)).toBe("[粘贴 #1 · 2 行][图片 #1][粘贴 #2 · 2 行]")
+})
+
+test("snippet over SNIPPET_MAX_CHARS is rejected", () => {
+  const r = applyPastedText(createPasteDraft(), `a\n${"x".repeat(SNIPPET_MAX_CHARS)}`)
+  expect(r).toEqual({ kind: "reject", notice: NOTICE_SNIPPET_TOO_LARGE, draft: expect.anything() })
+})
+
+test("clipboard image over IMAGE_MAX_BYTES is rejected", () => {
+  const r = applyClipboardImage(createPasteDraft(), {
+    data: Buffer.alloc(IMAGE_MAX_BYTES + 1),
+    mimeType: "image/png",
+  })
+  expect(r.kind).toBe("reject")
+  if (r.kind === "reject") expect(r.notice).toBe(NOTICE_IMAGE_TOO_LARGE)
+})
+
+test("clipboard image null is a no-op", () => {
+  const draft = createPasteDraft()
+  const r = applyClipboardImage(draft, null)
+  expect(r.kind).toBe("none")
+  expect(r.draft).toBe(draft)
+})
+
+test("expandContent keeps text+snippet as a string and interleaves images", () => {
+  let draft = createPasteDraft()
+  const s = applyPastedText(draft, "a\nb")
+  if (s.kind !== "snippet") throw new Error("expected snippet")
+  const textOnly = expandContent(`看${s.char}`, s.draft)
+  expect(textOnly).toBe(`看\n--- 粘贴 #1 ---\na\nb\n--- 粘贴 #1 ---`)
+
+  const img = applyClipboardImage(s.draft, { data: Buffer.from("png"), mimeType: "image/png" })
+  if (img.kind !== "image") throw new Error("expected image")
+  const mixed = expandContent(`看${img.char}${s.char}`, img.draft)
+  expect(Array.isArray(mixed)).toBe(true)
+  if (!Array.isArray(mixed)) return
+  expect(mixed[0]).toEqual({ type: "text", text: "看" })
+  expect(mixed[1]).toMatchObject({ type: "image", mimeType: "image/png" })
+  expect(mixed[2]).toEqual({
+    type: "text",
+    text: `\n--- 粘贴 #1 ---\na\nb\n--- 粘贴 #1 ---`,
+  })
+})
+
+test("pruneAttachments drops chips no longer in value and resetPasteDraft restarts ids", () => {
+  const s = applyPastedText(createPasteDraft(), "a\nb")
+  if (s.kind !== "snippet") throw new Error("expected snippet")
+  const pruned = pruneAttachments(s.draft, "")
+  expect(expandDisplay(s.char, pruned)).toBe("�")
+  const again = applyPastedText(resetPasteDraft(), "c\nd")
+  if (again.kind !== "snippet") throw new Error("expected snippet")
+  expect(expandDisplay(again.char, again.draft)).toBe("[粘贴 #1 · 2 行]")
+})
+
+test("chipClusterWidth is the painted label width capped by maxWidth", () => {
+  const s = applyPastedText(createPasteDraft(), "a\nb")
+  if (s.kind !== "snippet") throw new Error("expected snippet")
+  const full = chipClusterWidth(s.char, s.draft, 80)
+  const cap = chipClusterWidth(s.char, s.draft, 4)
+  expect(full).toBeGreaterThan(4)
+  expect(cap).toBe(4)
+  expect(chipClusterWidth("x", s.draft, 80)).toBeUndefined()
+})
+
+test("imageLabel format", () => {
+  expect(imageLabel(1)).toBe("[图片 #1]")
+})
+```
+
+- [ ] **Step 2: 运行确认失败**
+
+Run: `cd packages/min-agent && bun test tests/paste-draft.test.ts`
+Expected: FAIL（模块不存在）
+
+- [ ] **Step 3: 实现**
+
+要点（函数式，不 `any`）：
+
+- `PASTE_CHIP_BASE = 0xe000`；每条草稿 `nextCodePoint` 递增，本条内不复用。
+- 附件表 `Map<string, DraftAttachment>`，key 为那一个私有区字符。
+- `normalizePastedText`：`\r\n`/`\r` → `\n`，再去掉末尾一个 `\n`。
+- `applyPastedText`：规范化后 `length > SNIPPET_MAX_CHARS`（`1_000_000`）→ `reject`；仍含 `\n` → 分配 snippet（`id` 按 snippet 递增，`lineCount = text.split("\n").length`）；否则 `{ kind: "text", text }`，draft 不变。
+- `applyClipboardImage`：`null` → `{ kind: "none" }`；`data.length > IMAGE_MAX_BYTES`（`5 * 1024 * 1024`，与 `agent.ts` 的上限相同）→ `reject`；否则分配 image。
+- `expandDisplay`：已登记码点换成 `imageLabel` / `snippetLabel`，未登记私有区（`0xE000–0xF8FF`）画 `�`。
+- `expandContent`：从左到右，连续普通字（含未登记私有区按 `�`）合成 text；snippet 单独 text part，格式为若前面已有内容且不以 `\n` 结尾则先补 `\n`，再 `` `--- 粘贴 #${id} ---\n${text}\n--- 粘贴 #${id} ---` ``；image 为 `{ type: "image", image: Buffer, mimeType }`。无 image part 时把所有 text part 拼成一个 `string`。
+- `pruneAttachments`：留下 `value` 里还出现的 key。
+- `resetPasteDraft`：等同 `createPasteDraft()`。
+- `chipClusterWidth`：已登记则 `min(displayWidth(label), maxWidth)`，否则 `undefined`。
+- 导出 `SubmittedPrompt`：`{ display: string; content: string | Array<{ type: "text"; text: string } | { type: "image"; image: Buffer; mimeType: string }> }`。
+- 导出 `buildSubmittedPrompt(value, draft): SubmittedPrompt`（`display` + `content`）。
+
+- [ ] **Step 4: 运行确认通过**
+
+Run: `cd packages/min-agent && bun test tests/paste-draft.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/tui/paste-draft.ts tests/paste-draft.test.ts
+git commit -m "feat: 输入草稿附件表与粘贴展开"
+```
+
+---
+
+## Task 2: bracketed-paste.ts
+
+**Files:**
+- Create: `src/tui/bracketed-paste.ts`
+- Test: `tests/bracketed-paste.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+```ts
+import { expect, test } from "bun:test"
+import {
+  BRACKETED_PASTE_ENABLE,
+  BRACKETED_PASTE_DISABLE,
+  scanBracketedPaste,
+  shouldIgnorePasteInput,
+} from "../src/tui/bracketed-paste.js"
+
+test("enable/disable sequences", () => {
+  expect(BRACKETED_PASTE_ENABLE).toBe("\x1b[?2004h")
+  expect(BRACKETED_PASTE_DISABLE).toBe("\x1b[?2004l")
+})
+
+test("scanBracketedPaste extracts a complete paste in one chunk", () => {
+  const r = scanBracketedPaste("", "\x1b[200~hello\nworld\x1b[201~")
+  expect(r).toEqual({ buffer: "", pastes: ["hello\nworld"], active: false })
+})
+
+test("scanBracketedPaste spans chunks and stays active until the end marker", () => {
+  const a = scanBracketedPaste("", "\x1b[200~hel")
+  expect(a.pastes).toEqual([])
+  expect(a.active).toBe(true)
+  const b = scanBracketedPaste(a.buffer, "lo\x1b[201~more")
+  expect(b.pastes).toEqual(["hello"])
+  expect(b.active).toBe(false)
+  expect(b.buffer).toBe("more")
+})
+
+test("scanBracketedPaste keeps an incomplete ESC prefix", () => {
+  const r = scanBracketedPaste("", "pre\x1b[200")
+  expect(r.pastes).toEqual([])
+  expect(r.buffer.endsWith("\x1b[200")).toBe(true)
+})
+
+test("shouldIgnorePasteInput covers ink-stripped markers and active paste", () => {
+  expect(shouldIgnorePasteInput("abc", false)).toBe(false)
+  expect(shouldIgnorePasteInput("[200~hi", false)).toBe(true)
+  expect(shouldIgnorePasteInput("hi[201~", false)).toBe(true)
+  expect(shouldIgnorePasteInput("\x1b[200~x", false)).toBe(true)
+  expect(shouldIgnorePasteInput("x", true)).toBe(true)
+})
+```
+
+- [ ] **Step 2: 运行确认失败**
+
+Run: `cd packages/min-agent && bun test tests/bracketed-paste.test.ts`
+Expected: FAIL
+
+- [ ] **Step 3: 实现**
+
+`scanBracketedPaste(buffer, chunk)`：拼串后循环找 `\x1b[200~` … `\x1b[201~`。开始标记之后、结束标记之前的正文进 `pastes`（可多段）。若已开始未结束：`active: true`，`buffer` 为开始标记后的正文（可再含不完整的 `\x1b[201` 前缀）。若未开始：把最后的不完整 `\x1b` 前缀留在 `buffer`，其它非粘贴字节丢弃（与 Kitty 累加器一样，粘贴通道不把普通键当正文；普通键仍走 `useInput`）。
+
+注意：未处于粘贴态时，chunk 里开始标记之前的普通字符不要当 paste；也**不要**从 raw 通道插入它们（避免与 `useInput` 双写）。`buffer` 在未开始时只保留可能的 `ESC[200~` 前缀。
+
+`shouldIgnorePasteInput(input, active)`：`active` 为真，或 `input` 含 `\x1b[200~` / `\x1b[201~` / `[200~` / `[201~`。
+
+- [ ] **Step 4: 运行确认通过**
+
+Run: `cd packages/min-agent && bun test tests/bracketed-paste.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/tui/bracketed-paste.ts tests/bracketed-paste.test.ts
+git commit -m "feat: 扫描终端 bracketed paste 数据包"
+```
+
+---
+
+## Task 3: cluster 宽度注入
+
+**Files:**
+- Modify: `src/tui/text-width.ts`
+- Modify: `src/tui/caret-pos.ts`
+- Test: `tests/caret-pos.test.ts`（追加）
+- Test: `tests/text-width.test.ts`（若改了 `wrapByWidth` 签名，现有测试必须仍过）
+
+- [ ] **Step 1: 写失败测试**
+
+在 `tests/caret-pos.test.ts` 追加：
+
+```ts
+test("visualRows keeps a wide chip on one row using cluster width lookup", () => {
+  const chip = "\uE000"
+  const rows = visualRows(`ab${chip}cd`, 80, (c) => (c === chip ? 10 : undefined))
+  expect(rows).toEqual([{ text: `ab${chip}cd`, startIndex: 0 }])
+})
+
+test("caretIndexFromClick maps the whole chip width to one code point", () => {
+  const chip = "\uE000"
+  const rows = visualRows(chip, 80, (c) => (c === chip ? 10 : undefined))
+  expect(caretIndexFromClick(rows, 0, 5, 5, (c) => (c === chip ? 10 : undefined))).toBe(0)
+  expect(caretIndexFromClick(rows, 0, 14, 5, (c) => (c === chip ? 10 : undefined))).toBe(0)
+  expect(caretIndexFromClick(rows, 0, 15, 5, (c) => (c === chip ? 10 : undefined))).toBe(1)
+})
+
+test("a chip wider than maxWidth still occupies one visual row", () => {
+  const chip = "\uE000"
+  const rows = visualRows(chip, 4, (c) => (c === chip ? 4 : undefined))
+  expect(rows).toEqual([{ text: chip, startIndex: 0 }])
+})
+```
+
+- [ ] **Step 2: 运行确认失败**
+
+Run: `cd packages/min-agent && bun test tests/caret-pos.test.ts`
+Expected: FAIL（多余参数 / 宽标记被拆行）
+
+- [ ] **Step 3: 实现**
+
+```ts
+export type ClusterWidthLookup = (cluster: string) => number | undefined
+```
+
+- `wrapByWidth(line, maxWidth, lookup?)`：对每个 cluster，`w = lookup?.(g) ?? clusterWidth(g)`。`lookup` 已把过宽标记收成 `<= maxWidth`，因此不会拆开。
+- `visualRows(value, maxWidth, lookup?)` 把 `lookup` 传给 `wrapByWidth`。
+- `caretIndexFromClick(rows, rowIndex, clickColumn, textStartColumn, lookup?)`：累加宽度时用 `lookup?.(g) ??` 现有 `clustersOf` 宽度。
+- `moveCaretVertical(..., maxWidth, lookup?)`：内部 `visualRows` / `caretIndexFromClick` 都传入 `lookup`。
+- 现有调用不传 `lookup`，行为与现在完全相同。
+
+- [ ] **Step 4: 运行确认通过**
+
+Run: `cd packages/min-agent && bun test tests/caret-pos.test.ts tests/text-width.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/tui/text-width.ts src/tui/caret-pos.ts tests/caret-pos.test.ts tests/text-width.test.ts
+git commit -m "feat: 输入折行与点击识别宽标记"
+```
+
+---
+
+## Task 4: `SubmittedPrompt` 接线
+
+**Files:**
+- Modify: `src/tui/types.ts`（若类型放这里，从 `paste-draft` re-export 亦可，只选一处）
+- Modify: `src/tui/index.tsx`
+- Modify: `src/tui/App.tsx`
+- Modify: `src/tui/InputBar.tsx`（本步只改提交形状：无附件时 `{ display: text, content: text }`）
+- Modify: `src/tui-chat.ts`
+
+- [ ] **Step 1: 改类型并让现有路径等价**
+
+`TuiCallbacks.onSubmit: (prompt: SubmittedPrompt) => void`
+
+`App` / `InputBar` 同步。InputBar 现有 `submit(text)` 改为：
+
+```ts
+onSubmit({ display: text, content: text })
+```
+
+`tui-chat`：
+
+```ts
+onSubmit: async (prompt) => {
+  const text = prompt.display
+  if (text.trim().startsWith("/")) {
+    // 现有 handleSlashCommand(text, ...)，附件已不在 content 里
+    ...
+    return
+  }
+  lastUserMessage = text
+  tui.addMessage({ id: `user-${Date.now()}`, role: "user", content: text, timestamp: Date.now() })
+  messages.push({ role: "user", content: prompt.content })
+  ...
+}
+```
+
+增加 `onNotice?: (text: string) => void`：`tui-chat` 里 `sysMsg(tui, text)`；`TuiRenderer` → `App` → `InputBar` 透传（本步 InputBar 可先接 prop 暂不调用）。
+
+- [ ] **Step 2: 类型检查**
+
+Run: `cd packages/min-agent && npx tsc --noEmit`
+Expected: PASS（无其它 `onSubmit` 调用方）
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add src/tui/types.ts src/tui/index.tsx src/tui/App.tsx src/tui/InputBar.tsx src/tui-chat.ts
+git commit -m "feat: 输入提交改为 display 与 content"
+```
+
+---
+
+## Task 5: InputBar 粘贴与标记
+
+**Files:**
+- Modify: `src/tui/InputBar.tsx`
+
+- [ ] **Step 1: 集成行为（无 Ink 渲染测试；逻辑用 Task 1–2 的纯函数）**
+
+1. `draftRef = useRef(createPasteDraft())`。`applyEdit` 之后 `draftRef.current = pruneAttachments(draftRef.current, after.value)`。
+2. 打开/关闭 bracketed paste：与鼠标协议同一 `useEffect`，stdout 写 `BRACKETED_PASTE_ENABLE` / `DISABLE`（先 enable 再 mouse，卸载时先 mouse disable 再 paste disable，或与 mouse 写在同一串，但必须成对）。
+3. raw `handleData` 里对 chunk 调 `scanBracketedPaste`；`pasteActiveRef` 跟随 `active`。每个 `pastes[]` 项：`applyPastedText`；`text` 则 `insertAt`；`snippet` 则更新 `draftRef` 后 `insertAt` 该码点；`reject` 则 `onNotice(notice)`。
+4. `useInput` 在处理 Enter 之前：若 `shouldIgnorePasteInput(input, pasteActiveRef.current)` 则 `return`。删掉现在那套「字符串里含 `[200~` 就当普通插入」的分支。
+5. `key.ctrl && input === "v"`：放在 `Ctrl+B` 之后、`if (key.ctrl || key.meta) return` 之前。`getClipboardImage()` → `applyClipboardImage`；`image` 插入码点；`reject` 则 `onNotice`；`none` 静默。
+6. 绘制：`visualRows(value, textWidth, lookup)`，`lookup = (c) => chipClusterWidth(c, draftRef.current, textWidth)`。画每一行时把已登记码点换成标记文案（过宽用 `…` 截到 `textWidth`，与 `chipClusterWidth` 一致）。caret 列用同一套宽度。`moveCaretVertical` / 点击同样传 `lookup`。
+7. Enter：`buildSubmittedPrompt(value, draft)`；`display.trim()` 或 `draft.attachments.size > 0` 才 `onSubmit`；随后 `draftRef.current = resetPasteDraft()`。历史 `pushInput` 用 `display`。
+8. Ctrl+C 清空：`applyEdit` 清空 value 后 prune，再 `resetPasteDraft()`（计数回到 1）。
+9. 从历史上召回：只改 `value`，不要往旁路表里塞东西（召回的 `[粘贴 #1 · 2 行]` 是普通字）。
+
+标记过宽截断：若 `displayWidth(label) > maxWidth`，按 cluster 累加到 `maxWidth - displayWidth("…")` 再加 `…`。`chipClusterWidth` 已是 `min(labelWidth, maxWidth)`，绘制宽度必须与它相同，否则点击会偏。
+
+- [ ] **Step 2: 运行相关测试 + 类型**
+
+Run: `cd packages/min-agent && bun test tests/paste-draft.test.ts tests/bracketed-paste.test.ts tests/caret-pos.test.ts tests/kitty-input.test.ts && npx tsc --noEmit`
+Expected: PASS
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add src/tui/InputBar.tsx
+git commit -m "feat: 输入框粘贴图片与多行文本片段"
+```
+
+---
+
+## Task 6: README 与 /help
+
+**Files:**
+- Modify: `README.md`
+- Modify: `src/tui/slash-handler.ts`
+
+- [ ] **Step 1: 文案**
+
+英文快捷键行（约第 81 行）改为同时提到 Ctrl+V 贴图、多行粘贴收成片段，例如：
+
+`Shortcuts: **Ctrl+C** clears the input (press twice to exit) · **Ctrl+V** pastes an image · a multi-line paste becomes a snippet · **Ctrl+B** selects text to copy · mouse drag-select also copies on release.`
+
+中文（约第 185 行）对称：
+
+`快捷键：**Ctrl+C** 清空输入框（连按两次退出）· **Ctrl+V** 粘贴图片 · 多行粘贴会收成片段 · **Ctrl+B** 选中文本以复制 · 也支持鼠标拖拽选中并自动复制。`
+
+`/help` 快捷键段在 `Ctrl+J` 旁增加两行（对齐现有空格）：
+
+```
+  Ctrl+V        粘贴剪贴板图片到输入框
+  多行粘贴      收成片段，发送时带上全文
+```
+
+不要写私有区码点、bracketed paste、Ink 等实现词。
+
+- [ ] **Step 2: 提交**
+
+```bash
+git add README.md src/tui/slash-handler.ts
+git commit -m "docs: 说明输入框贴图与多行片段"
+```
+
+---
+
+## 手工验收
+
+在 `packages/min-agent` 下 `bun run src/cli.ts`（或仓库根目录 `bun run dev:agent`）：
+
+1. 粘贴一行 `hello` → 输入框出现 `hello`，不发送
+2. 粘贴两行 → 出现 `[粘贴 #1 · 2 行]`，左右键一次跳过整块，退格整块消失
+3. 在标记前后打字再 Enter → 对话区是短标记；模型侧应能读到 `--- 粘贴 #1 ---` 包着的原文（可看会话文件或临时 log）
+4. 复制一张截图后 **Ctrl+V** → `[图片 #1]`；再写「这是什么」发送
+5. Ctrl+V 在剪贴板只有文字时无提示、不插入 `v`
+6. `/paste` 仍立刻发送剪贴板图片
+7. 输入 `/help` 仍走命令
+8. 只贴一张图不打字，Enter 能发送