min-agent 0.4.0 → 0.5.0

package/docs/superpowers/plans/2026-08-23-thinking-wire-profile.md

@@ -0,0 +1,450 @@
+# 思考线协议适配 — 实现计划
+
+> **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:** 用户仍只配置 `off|low|medium|high|max`；发出 chat 请求时按 `(host, model)` 选择 `thinking.type` / `reasoning_effort` 的线协议。MiniMax 启发式先发 `adaptive`；其余若 400 且错误可解析，静默改 profile、同一请求只重试一次，并缓存 7 天。
+
+**Architecture:** 用户意图留在 `ThinkingRequestBody`（ALS）。新建 `thinking-wire.ts`：启发式、学习缓存、`parseThinkingWireHint`、`fetchWithThinkingWire`。`applyThinkingToChatBody` 增加 profile 参数。`modelFetch` 改为 `fetchWithThinkingWire(inner, …).then(foldReasoningInChatResponse)`。Lonae 目录不改。
+
+**Tech Stack:** TypeScript, bun:test
+
+**Spec:** `docs/superpowers/specs/2026-08-23-thinking-wire-profile-design.md`
+
+测试命令（`packages/min-agent` 下）：`bun test tests/<file>`；类型：`npx tsc --noEmit`；仓库根目录：`bun run typecheck`、`bun run check`。
+
+---
+
+## 文件结构
+
+| 文件 | 职责 |
+|------|------|
+| `src/thinking-wire.ts`（新） | profile 类型、默认值、缓存键、启发式、缓存、hint 解析、`fetchWithThinkingWire` |
+| `src/thinking.ts`（改） | `applyThinkingToChatBody(body, spec, profile?)` |
+| `src/provider.ts`（改） | `modelFetch` 走 `fetchWithThinkingWire` |
+| `tests/thinking-wire.test.ts`（新） | 启发式、hint、缓存、fetch 重试 |
+| `tests/thinking.test.ts`（改） | 三种 thinkingType × 开/关、effort omit |
+| `skills/self-config/SKILL.md`（改） | 映射说明 + 缓存文件名 |
+| `skills/self-config/reference.md`（改） | `MIN_AGENT_CONFIG_DIR` 旁注明缓存文件 |
+
+`docs/API.md`、`README.md`、`/help`、Lonae catalog、`/think` UI **不改**。
+
+---
+
+## Task 1: thinking-wire 纯函数与缓存
+
+**Files:**
+- Create: `src/thinking-wire.ts`
+- Test: `tests/thinking-wire.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+```ts
+import { expect, test, afterEach } from "bun:test"
+import { mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "fs"
+import os from "os"
+import path from "path"
+import {
+  DEFAULT_THINKING_WIRE,
+  THINKING_WIRE_TTL,
+  clearThinkingWireCache,
+  inferThinkingWire,
+  parseThinkingWireHint,
+  resolveThinkingWireProfile,
+  saveLearnedThinkingWire,
+  thinkingWireCacheKey,
+} from "../src/thinking-wire.js"
+
+function withIsolatedConfig(fn: () => void): void {
+  const home = realpathSync(mkdtempSync(path.join(os.tmpdir(), "min-agent-wire-")))
+  const old = process.env.MIN_AGENT_CONFIG_DIR
+  process.env.MIN_AGENT_CONFIG_DIR = home
+  clearThinkingWireCache()
+  try {
+    fn()
+  } finally {
+    clearThinkingWireCache()
+    if (old) process.env.MIN_AGENT_CONFIG_DIR = old
+    else delete process.env.MIN_AGENT_CONFIG_DIR
+    rmSync(home, { recursive: true, force: true })
+  }
+}
+
+afterEach(() => clearThinkingWireCache())
+
+test("cache key lowercases host and model", () => {
+  expect(thinkingWireCacheKey("Api.Example.COM", "MiniMax-M3")).toBe("api.example.com::minimax-m3")
+  expect(thinkingWireCacheKey("", "m")).toBe("m")
+})
+
+test("inferThinkingWire prefers minimax then openai then default", () => {
+  expect(inferThinkingWire("minimax-m3", "api.console.go", "openai-compatible")).toEqual({
+    thinkingType: "adaptive-disabled",
+    effort: "reasoning_effort",
+  })
+  expect(inferThinkingWire("gpt-4", "api.minimax.io", undefined)).toEqual({
+    thinkingType: "adaptive-disabled",
+    effort: "reasoning_effort",
+  })
+  expect(inferThinkingWire("gpt-5", "api.openai.com", "openai")).toEqual({
+    thinkingType: "omit",
+    effort: "reasoning_effort",
+  })
+  expect(inferThinkingWire("deepseek-v3", "api.deepseek.com", "openai-compatible")).toEqual({
+    thinkingType: "enabled-disabled",
+    effort: "reasoning_effort",
+  })
+})
+
+test("parseThinkingWireHint reads MiniMax allowed list", () => {
+  const raw =
+    'AI_APICallError: Error from provider (Console Go): Upstream request failed: [bad_request_error] invalid params, invalid thinking.type: "enabled" (allowed: adaptive, disabled) (2013)'
+  expect(parseThinkingWireHint(raw)).toEqual({ thinkingType: "adaptive-disabled" })
+  expect(parseThinkingWireHint('invalid thinking.type: "adaptive" (allowed: enabled, disabled)')).toEqual({
+    thinkingType: "enabled-disabled",
+  })
+})
+
+test("parseThinkingWireHint reads unknown parameter", () => {
+  expect(parseThinkingWireHint("Unknown parameter: 'thinking'")).toEqual({ thinkingType: "omit" })
+  expect(parseThinkingWireHint("unknown parameter: reasoning_effort")).toEqual({ effort: "omit" })
+  expect(parseThinkingWireHint("rate limit exceeded")).toBeNull()
+})
+
+test("resolveThinkingWireProfile prefers learned cache over heuristic", () => {
+  withIsolatedConfig(() => {
+    expect(resolveThinkingWireProfile("h.example", "minimax-m3").thinkingType).toBe("adaptive-disabled")
+    saveLearnedThinkingWire("h.example", "minimax-m3", {
+      ...DEFAULT_THINKING_WIRE,
+      thinkingType: "omit",
+      effort: "omit",
+    })
+    const learned = resolveThinkingWireProfile("h.example", "minimax-m3")
+    expect(learned.thinkingType).toBe("omit")
+    expect(learned.effort).toBe("omit")
+    const disk = JSON.parse(readFileSync(path.join(process.env.MIN_AGENT_CONFIG_DIR!, "thinking-wire-cache.json"), "utf-8"))
+    expect(disk["h.example::minimax-m3"].thinkingType).toBe("omit")
+  })
+})
+
+test("expired or wrong version cache is ignored", () => {
+  withIsolatedConfig(() => {
+    const file = path.join(process.env.MIN_AGENT_CONFIG_DIR!, "thinking-wire-cache.json")
+    writeFileSync(
+      file,
+      JSON.stringify({
+        "h::m": { version: 1, thinkingType: "omit", effort: "omit", timestamp: Date.now() - THINKING_WIRE_TTL - 1 },
+        "h::old": { version: 99, thinkingType: "omit", effort: "omit", timestamp: Date.now() },
+      }),
+    )
+    expect(resolveThinkingWireProfile("h", "m", "openai-compatible").thinkingType).toBe("enabled-disabled")
+    expect(resolveThinkingWireProfile("h", "old", "openai-compatible").thinkingType).toBe("enabled-disabled")
+  })
+})
+```
+
+先跑确认失败：
+
+```bash
+cd packages/min-agent && bun test tests/thinking-wire.test.ts
+```
+
+- [ ] **Step 2: 实现**
+
+`src/thinking-wire.ts`（与 `model-catalog.ts` 同样用 `getConfigDir()` + `atomicWriteFileSync`）：
+
+```ts
+export const THINKING_WIRE_VERSION = 1
+export const THINKING_WIRE_TTL = 7 * 24 * 60 * 60 * 1000
+export const DEFAULT_THINKING_WIRE = {
+  version: THINKING_WIRE_VERSION,
+  thinkingType: "enabled-disabled" as const,
+  effort: "reasoning_effort" as const,
+}
+
+export type ThinkingTypeMode = "enabled-disabled" | "adaptive-disabled" | "omit"
+export type EffortMode = "reasoning_effort" | "omit"
+export interface ThinkingWireProfile {
+  version: number
+  thinkingType: ThinkingTypeMode
+  effort: EffortMode
+  timestamp: number
+}
+export type ThinkingWireHint = Partial<Pick<ThinkingWireProfile, "thinkingType" | "effort">>
+```
+
+- `thinkingWireCacheKey(host, modelId)`：都 `toLowerCase()`；host 空则只要 modelId
+- `inferThinkingWire(modelId, host, providerType?)`：`minimax` 出现在 model 或 host（大小写不敏感）→ adaptive-disabled；`providerType === "openai"` → omit thinking；否则默认
+- `resolveThinkingWireProfile(host, modelId, providerType?)`：有效学习缓存 → 否则启发式填 `timestamp: Date.now()`（启发式**不写盘**）
+- `saveLearnedThinkingWire` 写内存 + `thinking-wire-cache.json`
+- `clearThinkingWireCache()` 清内存（测试用）；磁盘随 `MIN_AGENT_CONFIG_DIR` 隔离
+- `parseThinkingWireHint(text)`：
+  - `/thinking\.type[\s\S]*?allowed:\s*([^)]+)/i`，列表按逗号拆、trim、去引号、小写；含 `adaptive` 且含 `disabled` → `adaptive-disabled`；含 `enabled` 且含 `disabled` → `enabled-disabled`
+  - `/unknown parameter[:\s]+['"`]?thinking['"`]?/i` → omit thinking（不要误匹配 `thinking.type` 那段里的 thinking）
+  - `/unknown parameter[:\s]+['"`]?reasoning_effort['"`]?/i` → omit effort
+  - 都不中 → `null`
+- 未知 `version` 或过期 → 当未命中。损坏 JSON → `{}`
+
+本任务**不要**实现 fetch 包装。
+
+- [ ] **Step 3: 测试通过并提交**
+
+```bash
+cd packages/min-agent && bun test tests/thinking-wire.test.ts
+git add src/thinking-wire.ts tests/thinking-wire.test.ts
+git commit -m "feat: 增加思考线协议 profile 与错误 hint 解析"
+```
+
+---
+
+## Task 2: applyThinkingToChatBody 按 profile 拼 body
+
+**Files:**
+- Modify: `src/thinking.ts`
+- Modify: `tests/thinking.test.ts`
+
+- [ ] **Step 1: 改测试**
+
+把现有「injects reasoning_effort and thinking.type」扩成显式 profile（缺省第三参 = `DEFAULT_THINKING_WIRE` 的 type/effort）：
+
+```ts
+import { DEFAULT_THINKING_WIRE } from "../src/thinking-wire.js"
+
+test("applyThinkingToChatBody follows thinkingType and effort modes", () => {
+  const specOn = { reasoningEffort: "high", thinkingEnabled: true }
+  const specOff = { reasoningEffort: "none", thinkingEnabled: false }
+  expect(applyThinkingToChatBody({ model: "m" }, specOn)).toEqual({
+    model: "m",
+    reasoning_effort: "high",
+    thinking: { type: "enabled" },
+  })
+  expect(
+    applyThinkingToChatBody({ model: "m" }, specOn, { ...DEFAULT_THINKING_WIRE, thinkingType: "adaptive-disabled" }),
+  ).toEqual({
+    model: "m",
+    reasoning_effort: "high",
+    thinking: { type: "adaptive" },
+  })
+  expect(applyThinkingToChatBody({ model: "m" }, specOff, { ...DEFAULT_THINKING_WIRE, thinkingType: "adaptive-disabled" })).toEqual({
+    model: "m",
+    reasoning_effort: "none",
+    thinking: { type: "disabled" },
+  })
+  expect(applyThinkingToChatBody({ thinking: { type: "enabled" }, reasoning_effort: "x" }, specOn, {
+    ...DEFAULT_THINKING_WIRE,
+    thinkingType: "omit",
+    effort: "omit",
+  })).toEqual({})
+})
+```
+
+- [ ] **Step 2: 实现**
+
+```ts
+export function applyThinkingToChatBody(
+  body: Record<string, unknown>,
+  spec: ThinkingRequestBody,
+  profile: Pick<ThinkingWireProfile, "thinkingType" | "effort"> = DEFAULT_THINKING_WIRE,
+): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...body }
+  if (profile.effort === "omit") delete next.reasoning_effort
+  else next.reasoning_effort = spec.reasoningEffort
+  if (profile.thinkingType === "omit") delete next.thinking
+  else {
+    const on = profile.thinkingType === "adaptive-disabled" ? "adaptive" : "enabled"
+    next.thinking = { type: spec.thinkingEnabled ? on : "disabled" }
+  }
+  return next
+}
+```
+
+`ThinkingRequestBody` 不变。`resolveThinkingRequest` / `toWireEffort` 不变。
+
+- [ ] **Step 3: 测试通过并提交**
+
+```bash
+cd packages/min-agent && bun test tests/thinking.test.ts
+git add src/thinking.ts tests/thinking.test.ts
+git commit -m "feat: 按 wire profile 组装思考请求体"
+```
+
+---
+
+## Task 3: fetch 400 改参并只重试一次
+
+**Files:**
+- Modify: `src/thinking-wire.ts`
+- Modify: `tests/thinking-wire.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+在 `thinking-wire.test.ts` 增加（仍用隔离 `MIN_AGENT_CONFIG_DIR` + `thinkingRequestStore.run`）：
+
+```ts
+import { thinkingRequestStore } from "../src/thinking.js"
+import { fetchWithThinkingWire } from "../src/thinking-wire.js"
+
+test("fetchWithThinkingWire retries once when 400 names adaptive", async () => {
+  withIsolatedConfig(() => {
+    const bodies: string[] = []
+    const inner: FetchLike = async (_input, init) => {
+      bodies.push(String(init?.body ?? ""))
+      if (bodies.length === 1) {
+        return new Response(
+          'invalid thinking.type: "enabled" (allowed: adaptive, disabled)',
+          { status: 400 },
+        )
+      }
+      return new Response("{}", { status: 200 })
+    }
+    return thinkingRequestStore.run({ reasoningEffort: "high", thinkingEnabled: true }, async () => {
+      const res = await fetchWithThinkingWire(inner, "https://gw.example/v1/chat/completions", {
+        method: "POST",
+        body: JSON.stringify({ model: "other-model", messages: [] }),
+      })
+      expect(res.status).toBe(200)
+      expect(bodies).toHaveLength(2)
+      expect(JSON.parse(bodies[0]!).thinking).toEqual({ type: "enabled" })
+      expect(JSON.parse(bodies[1]!).thinking).toEqual({ type: "adaptive" })
+    })
+  })
+})
+
+test("fetchWithThinkingWire does not retry unrelated 400", async () => {
+  withIsolatedConfig(() => {
+    let n = 0
+    const inner: FetchLike = async () => {
+      n++
+      return new Response("insufficient quota", { status: 400 })
+    }
+    return thinkingRequestStore.run({ reasoningEffort: "high", thinkingEnabled: true }, async () => {
+      const res = await fetchWithThinkingWire(inner, "https://gw.example/v1/chat/completions", {
+        method: "POST",
+        body: JSON.stringify({ model: "m" }),
+      })
+      expect(res.status).toBe(400)
+      expect(await res.text()).toBe("insufficient quota")
+      expect(n).toBe(1)
+    })
+  })
+})
+```
+
+`withIsolatedConfig` 若目前是同步的，改成支持 `fn: () => void | Promise<void>` 并 `await`。`FetchLike` 从 `fetch-timeout.js` 导入。
+
+再加一条：hint 相对当前 profile 无变化（已经是 adaptive，400 仍说 allowed adaptive）→ 不重试。可用 minimax 模型名让第一次就发 adaptive，inner 只 400 一次。
+
+- [ ] **Step 2: 实现 `fetchWithThinkingWire`**
+
+签名：
+
+```ts
+export async function fetchWithThinkingWire(
+  inner: FetchLike,
+  input: string | URL | Request,
+  init?: RequestInit,
+  opts?: { providerType?: string },
+): Promise<Response>
+```
+
+逻辑：
+
+1. `spec = thinkingRequestStore.getStore()`；无 spec 或 `init.body` 非字符串 → `return inner(input, init)`
+2. JSON.parse body；非对象 → `return inner(input, init)`
+3. `host` 从 `input` 解析 `URL.hostname`（`Request` 用 `.url`）；失败则 `""`
+4. `modelId` = body.model 字符串，否则 `""`
+5. `providerType` = `opts?.providerType ?? getActiveProvider(getEffectiveConfig())?.type`
+6. `profile = resolveThinkingWireProfile(host, modelId, providerType)`
+7. `firstInit = { ...init, body: JSON.stringify(applyThinkingToChatBody(parsed, spec, profile)) }`
+8. `first = await inner(input, firstInit)`；`first.status !== 400` → `return first`
+9. `text = await first.text()`；`hint = parseThinkingWireHint(text)`
+10. 合并 hint：`next = { ...profile, ...hint, version: 1, timestamp: Date.now() }`；`thinkingType` 与 `effort` 都与当前相同 → `return rebuild400(first, text)`
+11. `saveLearnedThinkingWire(host, modelId, next)`；第二次 `inner(input, { ...init, body: JSON.stringify(applyThinkingToChatBody(parsed, spec, next)) })`，**不再**根据第二次状态重试
+12. `rebuild400`：`new Response(text, { status: 400, statusText: first.statusText, headers: first.headers })`
+
+`getActiveProvider` 在 `thinking-wire.ts` 引用 `config.js` 可以；测试不依赖真实 config（默认走 enabled-disabled）。
+
+- [ ] **Step 3: 测试通过并提交**
+
+```bash
+cd packages/min-agent && bun test tests/thinking-wire.test.ts
+git add src/thinking-wire.ts tests/thinking-wire.test.ts
+git commit -m "feat: 思考字段 400 时改 profile 并只重试一次"
+```
+
+---
+
+## Task 4: 接入 modelFetch
+
+**Files:**
+- Modify: `src/provider.ts`
+
+- [ ] **Step 1: 接线**
+
+删除 `withThinkingBody`。`modelFetch`：
+
+```ts
+return (input, init) => fetchWithThinkingWire(inner, input, init).then(foldReasoningInChatResponse)
+```
+
+从 `thinking-wire.js` 导入 `fetchWithThinkingWire`；`thinking.ts` 不再被 `provider.ts` 直接用来拼 body（ALS 仍由 agent 设置，fetch 内部读）。
+
+现有 `tests/provider.test.ts` 应仍通过（不发真实请求）。
+
+- [ ] **Step 2: 测试并提交**
+
+```bash
+cd packages/min-agent && bun test tests/provider.test.ts tests/thinking-wire.test.ts tests/thinking.test.ts
+git add src/provider.ts
+git commit -m "feat: 模型请求走思考线协议适配"
+```
+
+---
+
+## Task 5: self-config 文档
+
+**Files:**
+- Modify: `skills/self-config/SKILL.md`
+- Modify: `skills/self-config/reference.md`
+
+- [ ] **Step 1: 文案**
+
+`SKILL.md` 思考段落里「The request sends `reasoning_effort` plus `thinking.type`」改为：请求会按当前模型和网关映射思考字段（例如 MiniMax 用 `adaptive`/`disabled`，官方 OpenAI 不发 `thinking` 对象）；学到的映射缓存在 `~/.min-agent/thinking-wire-cache.json`（7 天）。官方 OpenAI 仍把 `max` 映射为 `xhigh`。不要写 400 重试、fetch 包装、profile 类型名。
+
+`reference.md` 环境变量表 `MIN_AGENT_CONFIG_DIR` 一行改为同时提到目录缓存与思考映射缓存，例如：`Replaces ~/.min-agent`（含 `model-catalog-cache.json`、`thinking-wire-cache.json`）。
+
+README / API.md / `/help` 不改。
+
+- [ ] **Step 2: 提交**
+
+```bash
+git add packages/min-agent/skills/self-config/SKILL.md packages/min-agent/skills/self-config/reference.md
+git commit -m "docs: 说明思考请求按模型映射线协议"
+```
+
+（在仓库根目录 add 时用上表路径；在 `packages/min-agent` 内则用 `skills/self-config/…`。）
+
+---
+
+## Task 6: 回归
+
+- [ ] **Step 1: 全量相关测试与检查**
+
+```bash
+cd packages/min-agent && bun test tests/thinking.test.ts tests/thinking-wire.test.ts tests/provider.test.ts
+# 仓库根目录
+bun run typecheck
+bun run check
+```
+
+- [ ] **Step 2: 若有格式问题则 `bun run format` 后再 check，不要 `--no-verify`**
+
+---
+
+## 手工验收
+
+在 `packages/min-agent` 下用 MiniMax-M3（思考非 off）发一句 `hello`：
+
+1. 不应再出现 `invalid thinking.type: "enabled"`
+2. 状态栏仍是「思考 high」这类用户档位，不出现 `adaptive`
+3. 换一个会 400 且错误带 `allowed: adaptive, disabled` 的网关：第一次失败后同一句应自动成功；`~/.min-agent/thinking-wire-cache.json` 出现对应 host+model 条目
+4. `/think off` 发送 `disabled`，对话仍可用

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

@@ -0,0 +1,174 @@
+# 输入框粘贴图片与文本片段设计
+
+日期: 2026-08-23
+状态: 已批准（方案 1：输入框内原子标记）
+
+## 问题
+
+交互会话的输入框不能把剪贴板图片挂到当前草稿：贴图只能 `/paste`（立刻发送）或 `/attach <路径>`。多行文本粘贴会整段铺进输入框，末尾换行还可能被当成 Enter 误发送。
+
+## 目标
+
+1. 剪贴板图片用 Ctrl+V 插到光标处，显示为 `[图片 #N]`，写完说明再 Enter 发送
+2. 一次粘贴只要超过一行，收成 `[粘贴 #N · X 行]`，发送时带上全文
+3. 单行粘贴仍直接插入
+4. 标记在输入框里是原子块：左右移、退格、Delete、点击都不拆开
+5. 只有附件、没打字也可以发送
+
+## 不做
+
+- 不改 HTTP `/v1/paste`，不新增配置项，不改 `skills/self-config`
+- 不把 Cmd+V 从终端抢过来（macOS 贴图用 Ctrl+V）
+- 不把附件正文写入 `input-history.json`
+- 不做拖拽文件进终端、不做输入框内 Shift 选区
+- `/paste [t]` 仍是立刻发送剪贴板图片，不改成挂草稿
+
+## 设计决策
+
+| 决策 | 结论 |
+|------|------|
+| 呈现 | 草稿字符串里每个附件一个私有区码点；屏幕上画成标记 |
+| 文本门槛 | 规范化后仍含换行 → 片段；否则当普通字插入 |
+| 贴图快捷键 | Ctrl+V 读系统剪贴板；无图时静默 |
+| `/paste` | 保持立刻发送 |
+| 斜杠命令 | `display` 去空白后以 `/` 开头则走现有命令处理，附件不进入对话 |
+| 历史 | 只存展开后的短标记字面量，不存图片/长文；翻历史不会恢复附件 |
+
+---
+
+## 1. 数据模型
+
+`InputBar` 继续用 `{ value, caretIndex }`。`caretIndex` 仍是 `Array.from(value)` 的码点下标。
+
+每个附件占用 **一个** Unicode 私有区码点，从 `U+E000` 起按插入顺序分配，本条草稿内不复用。旁路表：
+
+```ts
+type DraftAttachment =
+  | { kind: "image"; id: number; data: Buffer; mimeType: string }
+  | { kind: "snippet"; id: number; text: string; lineCount: number }
+```
+
+`id` 按类型分开从 1 递增：`[图片 #1]` 与 `[粘贴 #1 · 3 行]` 可以同时存在。
+
+屏幕标记（用户可见，无实现细节）：
+
+- 图片：`[图片 #${id}]`
+- 片段：`[粘贴 #${id} · ${lineCount} 行]`
+
+未在旁路表中的私有区字符按宽 1 的 `�` 绘制，不当附件。
+
+每次编辑后扫描 `value`：旁路表里码点已不在 `value` 中的条目删除（退格、Ctrl+U/K/W、Ctrl+C 清空都走这条）。Ctrl+C 清空或提交成功后：`value` 清空，旁路表清空，两个计数器回到 1。
+
+折行与点击：该码点是一个 cluster，显示宽度为 `min(displayWidth(标记), 输入区宽度)`。过宽时单独占一行，绘制时末尾用 `…` 截断；点击该行任一单元格都落在这一个码点上。硬件光标列用展开后的显示宽度计算，与现有 IME 锚点一致。
+
+---
+
+## 2. 文本粘贴
+
+挂载输入框时打开 bracketed paste（`CSI ? 2004 h`），卸载时关闭（`CSI ? 2004 l`），与现有鼠标协议一起写 stdout。
+
+在 InputBar 已有的 raw stdin 监听里拼包：`ESC[200~` 起、`ESC[201~` 止。包收齐前 `useInput` 丢掉这段输入（含 Ink 剥掉 ESC 后的 `[200~` / `[201~` 碎片），避免插两遍，也避免粘贴里的换行走现有「末尾 `\r`/`\n` 当 Enter」逻辑。
+
+粘贴正文处理（纯函数，可单测）：
+
+1. `\r\n` 与 `\r` 全部变成 `\n`
+2. 去掉**末尾一个** `\n`（编辑器复制常带）
+3. 若仍含 `\n`：分配片段码点，插入光标处，`lineCount = text.split("\n").length`
+4. 否则：当普通文本插入（与打字相同）
+
+片段正文上限 **1_000_000** 个 UTF-16 码元。超过则不插入，系统提示 `粘贴内容过大，未附加`。
+
+单行过长仍插入，不收成片段。
+
+---
+
+## 3. 图片粘贴
+
+`useInput` 在现有 `Ctrl+B` 之后、吞掉其它 Ctrl 组合之前处理 `key.ctrl && input === "v"`：调用已有 `getClipboardImage()`。
+
+- 有图且 `data.length <=` 现有 `MAX_IMAGE_BYTES`（5MB）：插入图片码点，MIME 用剪贴板返回值
+- 有图但超过 5MB：提示 `图片超过 5MB，未附加`，不插入
+- 无图：静默返回（不提示），避免想贴字时误按 Ctrl+V 刷警告
+
+Mac 上 Cmd+V 仍由终端注入文字。README 与 `/help` 写明贴图用 Ctrl+V。
+
+---
+
+## 4. 编辑
+
+因为每个标记是一个码点，现有 `moveCaretHorizontal` / `backspaceAt` / `deleteAt` 已整块移动或删除。`Ctrl+W` / `Ctrl+K` / `Ctrl+U` 按现有「删一段字符串」处理，事后扫描丢掉孤儿附件。
+
+点击：先按展开后的显示列命中 cluster，再映射回 `value` 码点下标；点在标记上时 caret 落在该码点前（与现在点在某字前一致），再按右键一次跳过整块。
+
+Enter：`display` 去空白后非空，**或**旁路表非空，即可发送。发送后清空草稿与表。
+
+---
+
+## 5. 提交与展示
+
+`onSubmit` 改为接收一次提交的结构化结果：
+
+```ts
+type SubmittedPrompt = {
+  display: string
+  content: string | Array<{ type: "text"; text: string } | { type: "image"; image: Buffer; mimeType: string }>
+}
+```
+
+`display`：把 `value` 里的附件码点换成标记文案，用于对话区用户气泡和输入历史。
+
+`content` 按 `value` 从左到右展开：
+
+- 连续普通字合成一个 `text` part
+- 片段换成一个 `text` part，正文前后各单独一行分隔：`--- 粘贴 #${id} ---`
+- 图片一个 `image` part（`Buffer` + `mimeType`）
+
+若没有任何图片 part，`content` 收成单个字符串（与现在 `messages.push({ content: text })` 兼容）。有图片则为数组。
+
+`tui-chat`：`addMessage` 用 `display`；`messages.push({ role: "user", content })` 用 `content`。`lastUserMessage` 存 `display`。
+
+`display` 去空白后以 `/` 开头：原样交给现有 `handleSlashCommand`，旁路表丢弃、不写入 `messages`（避免 `/help` 误带一张图）。否则按上面的 `content` 入列。
+
+超限提示不进输入框正文：`InputBar` 增加 `onNotice(text: string)`，`tui-chat` 接到现有系统消息通道（与 `/paste` 失败提示同一处）。
+
+输入历史：`pushInput` 写入 `display`（短标记，无二进制、无片段全文）。从历史上召回的标记是普通字符，旁路表为空。
+
+---
+
+## 6. 文件与同步
+
+| 文件 | 改动 |
+|------|------|
+| `src/tui/paste-draft.ts`（新） | 规范化粘贴、单行/多行判定、码点分配、展开 `display`/`content`、孤儿回收；无 React |
+| `src/tui/bracketed-paste.ts`（新） | 从 stdin 块里扫描 bracketed paste 包 |
+| `src/tui/caret-pos.ts` / `text-width.ts` | cluster 宽度可注入「此码点显示宽」；`visualRows` / 点击换算认识附件宽 |
+| `src/tui/InputBar.tsx` | 打开/关闭 bracketed paste、粘贴包、Ctrl+V、旁路表、`onNotice`、按新规则提交 |
+| `src/tui/index.tsx` / `App.tsx` | `onSubmit` 改为 `SubmittedPrompt`；透传 `onNotice` |
+| `src/tui-chat.ts` | 按 `display`/`content` 入列；斜杠判定见上；`onNotice` 走系统消息 |
+| `src/tui/slash-handler.ts` | `/help` 快捷键增加 Ctrl+V 贴图、多行粘贴收成片段 |
+| `README.md` | 中英快捷键各补一句 |
+| `docs/API.md` | 不改（TUI 便利，协议不变） |
+
+`/paste`、`/attach`、CLI `-i` 行为不变。
+
+---
+
+## 7. 测试
+
+纯函数（`tests/paste-draft.test.ts`、`tests/bracketed-paste.test.ts`，必要时扩 `tests/caret-pos.test.ts`）：
+
+- 单行；`a\nb`；`a\nb\n` 去掉末尾换行后仍是两行片段；仅 `hello\n` → 单行插入
+- 片段展开顺序：字 + 图 + 片段不错位；无图时 `content` 为字符串
+- 删除码点后旁路表回收；清空后计数从 1 再起
+- 超 1_000_000 码元拒绝；标记过宽时点击仍落在该码点
+- bracketed paste 扫描：跨 chunk、内含 `\n`/`\r`、无结束符时保持缓冲
+
+`InputBar` 不测 Ink 渲染。stdin 夹具覆盖：粘贴多行不提交；粘贴中的 `useInput` 碎片不插入。
+
+## 错误文案
+
+| 情况 | 文案 |
+|------|------|
+| 图片 > 5MB | `图片超过 5MB，未附加` |
+| 片段 > 1_000_000 码元 | `粘贴内容过大，未附加` |
+| Ctrl+V 无图 | （无文案） |