min-agent 0.2.1 → 0.4.0

package/docs/superpowers/specs/2026-08-17-mouse-selection-design.md

@@ -0,0 +1,116 @@
+# 消息区鼠标拖拽选择与自动复制设计
+
+日期:2026-08-17
+状态:已批准(用户确认方案 A:应用内拖拽选择 + 自动复制)
+
+## 问题
+
+min-agent TUI 启用了 SGR 鼠标跟踪(1000 模式),终端原生拖拽选择被鼠标协议接管,
+消息区(内容区)文本无法用鼠标选取、复制。参考 opencode / claude code 的交互:
+在消息区按住左键拖拽高亮文本,松开自动复制到系统剪贴板。
+
+## 目标
+
+1. 消息区按住左键拖拽 → 选区实时高亮(反显)
+2. 松开 → 自动复制到系统剪贴板(不占用 Ctrl+C,它仍用于退出)
+3. 选区保持高亮直到下次点击/按键,状态栏短暂提示"已复制"
+4. 原有功能不回归:单击展开工具行、滚轮滚动、输入框点击定位光标、Ctrl+C 退出
+
+## 设计
+
+### 1. 鼠标协议升级(`src/tui/mouse.ts`)
+
+- `MOUSE_ENABLE` = `\x1b[?1000h\x1b[?1002h\x1b[?1006h`(1002 = 按住按钮时报告拖拽移动)
+- `MOUSE_DISABLE` 同步加 `?1002l`
+- 新增 `MOTION = 32` 常量:SGR 移动事件按钮码 = 基础按钮 + 32;修饰键(Shift=4 等)
+  与基础按钮同在一个字段,`button & 15 === 0` 判断为无修饰键的纯左键
+
+### 2. 剪贴板写入(`src/clipboard.ts`)
+
+新增 `writeClipboard(text: string): boolean`,平台分发与现有读剪贴板一致:
+- macOS:`pbcopy`(execSync input 管道,避免 shell 引号问题)
+- Linux:`xclip -selection clipboard`,失败回退 `xsel --clipboard --input`
+- Windows:PowerShell `Set-Clipboard -Value ([Console]::In.ReadToEnd())`
+
+失败静默返回 false,不弹错。
+
+### 3. 选区纯函数模块(`src/tui/selection.ts`,新)
+
+全部按 `charWidth` 处理 CJK 宽度,输入为 ANSI 行与 0-based 显示列:
+
+- `stripAnsi(line)`:去掉 `\x1b[...m` 颜色码
+- `applySelection(line, start, end)`:在选区边界注入 `\x1b[7m` / `\x1b[27m`(反显),
+  保留原有样式;选区内遇到 `\x1b[0m`(RESET)时在其后重注入 `\x1b[7m`,保证跨样式
+  重置时高亮不断裂。与选区有交叠的字符(含全角)整字符高亮,不动字符边界
+- `extractText(line, start, end)`:按显示列切出选区纯文本(剥 ANSI)
+- `selectionRanges(rows, anchor, current)`:把拖拽锚点/当前点(0-based 坐标:
+  行 = `areaRows` 索引,列 = 行内显示列,由 MessageList 从终端坐标换算)归一为
+  与 `rows` 对齐的逐行选区,流式语义:
+  - 同行:`[min(col), max(col))`
+  - 跨行(向下拖):首行 `[anchor.col, 行尾)`,中间行整行,末行 `[0, current.col)`
+  - 跨行(向上拖):对称反转
+  - `rows` 中 null(指示行/空白行)跳过;坐标夹在消息区范围内
+  - 返回 `(start,end | null)[]`,与 `rows` 对齐
+
+### 4. MessageList 集成(`src/tui/MessageList.tsx`)
+
+**状态**:`selection: { anchor: Cell; cur: Cell } | null`(终端 1-based 坐标);
+`pendingPress` ref 记录按下点,用于区分单击与拖拽——按下只记录,出现移动事件才
+激活选区,松开未移动才算点击(工具行展开,逻辑从"按下即触发"改为"松开且未移动")。
+
+**行映射**:渲染时用与 MessageRow 相同的逻辑(`sliceLines`)构建 `areaRows:
+(string | null)[]`,与终端行一一对应(1 行 = 1 项,指示行/用户消息空行 = null)。
+点击与选区换算共用该映射,选区随每次渲染实时重算(流式输出时选区跟随内容)。
+
+**坐标换算**:行号(1-based)→ `areaRows` 索引(减 1);列 = 终端列 - 2(全部行有
+`paddingLeft={1}`,第一字符在终端列 2),夹到行宽内。
+
+**高亮渲染**:每个消息 part 把选区范围换算为"shown 行空间",以新 prop
+`selection?: (CellRange | null)[]` 传入 `MessageRow`,按角色逐行注入反显
+(用户消息首行的 "> "、工具行首行的 "⚡ name ▸ " 前缀单独处理,选区可跨前缀)。
+memo 比较追加 `prev.selection === next.selection`;无选区时传 `undefined`,
+身份稳定,不影响流式渲染性能。
+
+**松手复制**:提取各选中行文本(剥 ANSI、按列切片)以 `\n` 拼接 →
+`writeClipboard` → 选区保持高亮,直到下次点击(按下即清)、按键或滚轮滚动时清除;
+复制成功且文本非空时调用 `onCopyNotice` 回调。
+
+**事件过滤**:仅处理无修饰键(`button & 15 === 0`)且落在消息区(`row ≤ areaRows.length`)
+的事件;带修饰键(Shift)的拖拽不接管,留给支持原生 Shift 选择的终端。
+
+### 5. 复制反馈
+
+- `TuiState` 增 `copyNotice?: string`;`TuiRenderer.showCopyNotice(text)` 设置并在
+  2.5s 后自动清除
+- App 增 `onCopyNotice` 回调 prop 传给 MessageList(实现为 TuiRenderer.showCopyNotice)
+- StatusBar:把提示渲染在分隔线行的右端(占用分隔线自身宽度,不增加行数,布局不跳动)
+
+### 6. 文件改动
+
+| 文件 | 改动 |
+|---|---|
+| `src/tui/mouse.ts` | 启用/禁用序列加 1002、`MOTION` 常量 |
+| `src/tui/selection.ts`(新) | 选区纯函数:stripAnsi/applySelection/extractText/selectionRanges |
+| `src/clipboard.ts` | `writeClipboard()` |
+| `src/tui/MessageList.tsx` | selection state、press/drag/release 事件流、areaRows 映射、MessageRow 高亮渲染、onCopyNotice |
+| `src/tui/types.ts` | `TuiState.copyNotice` |
+| `src/tui/index.tsx` | `TuiRenderer.showCopyNotice()`、App 增 onCopyNotice prop |
+| `src/tui/App.tsx` | 传 onCopyNotice 给 MessageList |
+| `src/tui/StatusBar.tsx` | 分隔线行右端渲染"✓ 已复制"提示 |
+| `src/tui-chat.ts` | `/help` 快捷键区加"鼠标拖拽 选择文本并自动复制" |
+
+### 7. 测试
+
+- `tests/selection.test.ts`(新):stripAnsi / extractText(含 CJK 边界)/
+  applySelection(注入、RESET 重注入、空选区不变)/ selectionRanges(同行、
+  向下、向上、null 行跳过、越界夹取)
+- `tests/mouse.test.ts`:补拖拽移动事件解析(button 32)、启用序列含 `?1002h`
+- 运行 `bun run typecheck`(仓库根)与 `bun test`(packages/min-agent)
+
+## 不做(YAGNI)
+
+- 双击选词、三击选段
+- 键盘选择模式(tmux 风格)
+- 跨行选区自动去除 "> " / "⚡ name ▸ " 前缀(复制所见即所得)
+- 复制保留 Markdown 格式/富文本
+- 选区随流式输出"追字"(选区锚定终端坐标,内容变化时重算)

package/docs/superpowers/specs/2026-08-20-config-http-alignment-design.md

@@ -0,0 +1,47 @@
+# 配置与 HTTP 对齐（第 2 批）— 设计文档
+
+**日期:** 2026-08-20
+**状态:** 已批准（范围来自五批拆分；语义对齐现有 TUI）
+**范围:** 项目级 config/记忆、`exec` 写 history 与 `--resume`、HTTP 的 plan/budget/diff/redo 与确认/提问回调
+
+后续批次不在本文：MCP resources/prompts、沙箱、exec JSON 流、原生 Anthropic/Google、hooks、Browser/LSP、主题。
+
+---
+
+## 设计决策
+
+| 决策 | 结论 |
+|------|------|
+| 项目配置可覆盖字段 | `activeProvider`、`defaultModel`、`sampling`、`budget`、`permission`、`compaction`；**不**写 providers/apiKey |
+| 合并规则 | 项目字段有值则覆盖全局；sampling/budget/compaction 浅合并 |
+| 密钥 | 仍只存在 `~/.min-agent/config.json` |
+| 项目记忆 | `.min-agent/memory.json`；system prompt 先项目后全局 |
+| 记忆默认写入 | 存在 `.min-agent/` 则默认 project，否则 global；可显式 `scope` |
+| exec 会话 | 每次结束后 `saveSession`；`--resume <id>` 加载后追加本轮消息 |
+| HTTP plan | `POST /v1/chat` 增加 `plan_mode` |
+| HTTP budget/diff/redo | 独立端点，语义对齐 `/budget` `/diff` `/redo` |
+| 确认/提问 | serve 默认仍自动批准；请求 `auto_approve: false` 且必须 `stream: true`；SSE `confirm`/`question` + `POST /v1/approvals` `/v1/answers`；超时 5 分钟视为拒绝/跳过 |
+
+---
+
+## 1. 项目级配置
+
+`ProjectConfig` 增加上述字段。`mergeProjectOverGlobal` + `getEffectiveConfig()`。
+
+`getActiveProvider` / 采样 / 预算 / 权限 / compaction 读 effective config。`saveConfig` 仍写全局；`saveProjectConfig` 写项目。TUI `/budget [n] [--project]` 可写项目。
+
+## 2. 项目级记忆
+
+文件格式与全局相同。列表/删除按 scope 编索引。HTTP `GET /v1/memory` 增加 `project_memories`（原 `memories` 仍为全局）。
+
+## 3. exec
+
+`runAgent` 支持 `resumeSessionId`。结束后打印 `min-agent exec --resume <id>`。会话不存在则退出错误。
+
+## 4. HTTP
+
+- `plan_mode` → `RunOptions.planMode`
+- `GET/POST /v1/budget`（POST 可 `scope: project`）
+- `GET /v1/diff`
+- `POST /v1/chat/redo` `{ session_id }`：取出最后一条用户文本再跑一轮
+- 确认门闩：`AsyncLocalStorage`，不改变 process 级 `-y`；SSE 等待配套 POST

package/docs/superpowers/specs/2026-08-20-mcp-plugins-alignment-design.md

@@ -0,0 +1,37 @@
+# MCP 与插件对齐（第 3 批）— 设计文档
+
+**日期:** 2026-08-20
+**状态:** 已批准（范围来自五批拆分；语义对齐现有 TUI / 内置工具）
+**范围:** MCP resources / prompts、插件危险操作走确认；计划模式只保留只读 MCP/插件
+
+后续批次不在本文：沙箱、exec JSON 流、原生 Anthropic/Google、hooks、Browser/LSP/Notebook、主题。
+
+---
+
+## 设计决策
+
+| 决策 | 结论 |
+|------|------|
+| resources/prompts 暴露方式 | 四个只读 agent 工具（`mcp_list_resources` / `mcp_read_resource` / `mcp_list_prompts` / `mcp_get_prompt`），不把每条 resource 注册成独立工具 |
+| 连接失败面 | 服务器未声明或 list 失败时记空列表，**不**让整次 MCP 连接失败 |
+| 列表上限 | resources 200、templates 100、prompts 100；工具输出仍走 `truncateToolOutput` |
+| 插件确认 | 默认确认；`readOnly: true` 或 `dangerous: false` 跳过 |
+| 计划模式 | 去掉无 `readOnlyHint` 的 MCP 工具、非 `readOnly` 插件；catalog 工具保留 |
+| HTTP | `GET /v1/mcp` 增加计数；`GET .../resources`、`GET .../prompts`、`POST .../resources/read`、`POST .../prompts/get` |
+| serve 默认 | 仍自动批准（与第 2 批一致）；未设 `readOnly` 的插件在 TUI/`exec`（无 `-y`）会询问 |
+
+---
+
+## 1. MCP resources / prompts
+
+连接成功后根据 `getServerCapabilities()` 分页拉取。缓存供状态栏/HTTP 列表；`read` / `get` 走实时 RPC。
+
+多个已连接服务器时，`read`/`get` 若 URI/名称不唯一则必须带 `server`。二进制 resource 不把大段 base64 塞进上下文。
+
+## 2. 插件确认
+
+`PluginToolDef` 增加 `readOnly?: boolean`、`dangerous?: boolean`。确认文案面向用户：「运行自定义工具 {id}」加参数摘要。拒绝则工具返回说明，不抛错。
+
+## 3. 文档与测试
+
+README 插件示例标明 `readOnly`；`/mcp` 与 `mcp info` 显示资源/提示计数；API.md 同步新端点。测试覆盖：无 capability 的服务器仍能连；带 resources/prompts 的 stdio 服务器可 list/read；插件默认确认、`readOnly` 跳过。

package/docs/superpowers/specs/2026-08-20-sandbox-permissions-design.md

@@ -0,0 +1,68 @@
+# 沙箱与权限分级（第 4 批）— 设计文档
+
+**日期:** 2026-08-20
+**状态:** 已批准（范围来自五批拆分；语义对齐现有 TUI / `confirm` / `/plan`）
+**范围:** 权限档位、工作区文件隔离、命令级网络/写盘隔离；HTTP/CLI/TUI 同步
+
+后续批次不在本文：exec JSON 流、原生 Anthropic/Google、hooks、Browser/LSP/Notebook、主题。
+
+---
+
+## 设计决策
+
+| 决策 | 结论 |
+|------|------|
+| 两轴分开 | **确认**（`permission`）与 **隔离**（`sandbox`）正交。`--yes` / `allow-all` 只跳过确认，不自动关掉隔离 |
+| 确认档位 | `ask`（默认）/ `accept-edits` / `allow-all`。`accept-edits` 自动放行 write/edit/apply_patch，危险命令与自定义工具仍询问 |
+| 隔离档位 | `off`（默认）/ `workspace` / `strict`。`workspace`：文件工具可任意读（凭据除外）、只写入工作区+临时目录+包管理缓存；`strict`：读和写都限制在工作区（及 extra 根） |
+| 默认 | 未配置时 `sandbox.mode=off`、`network=allow`。`MIN_AGENT_SANDBOX` 覆盖当前进程；单独 `--sandbox` / `--network` 写入配置并退出；带消息时才作为本轮覆盖 |
+| 凭据 | 即使 `sandbox=off`，文件工具也禁止读写密钥类路径（`~/.ssh` 私钥、`~/.min-agent/config.json` 等） |
+| 命令隔离 | macOS 用 `sandbox-exec`，Linux 有 `bwrap` 时用 bubblewrap；没有则仍执行路径策略 + 网络命令启发式，不悄悄降级成无隔离执行 |
+| 网络 | `network=deny` 时：OS 配置禁止命令出网；无 OS 后端则拦截常见联网命令；`search_web` / `web_fetch` 一并拒绝。MCP 进程不受本批约束 |
+| `/plan` | 仍是去掉写入类工具；与 sandbox 叠加，不互相替代 |
+| HTTP | 请求可收紧、不可放宽。`serve` 默认仍自动批准，隔离默认仍为 off |
+| 自定义工具 | 进程内执行，文件隔离管不到；继续靠 `readOnly` / 确认。文案不提实现细节 |
+
+---
+
+## 1. 配置
+
+全局与项目 `.min-agent/config.json` 均可写（项目覆盖全局，字段级合并）：
+
+```json
+{
+  "permission": "ask",
+  "sandbox": {
+    "mode": "off",
+    "network": "allow",
+    "extraWriteRoots": [],
+    "extraReadRoots": []
+  }
+}
+```
+
+`sandbox` 也可写成字符串 `"workspace"`。未配置时默认 `off`。密钥仍只存在全局配置。
+
+生效顺序：环境变量 / CLI 覆盖 → 配置合并 → 每请求 ALS（只收紧）。
+
+---
+
+## 2. 工具行为
+
+- `read` / `write` / `edit` / `apply_patch` / `glob` / `grep`：解析 realpath（含符号链接逃逸），按档位拒绝并返回面向用户的说明。
+- `bash` / explore 只读 bash：工作目录必须落在允许的写根；按档位套 OS 配置。
+- `search_web` / `web_fetch`：`network=deny` 时直接拒绝。
+
+---
+
+## 3. 界面与 HTTP
+
+- TUI：`/permission`、`/sandbox`（可 `--project` / `--global` 写入配置）；`/help` 同步。
+- CLI：`sandbox` 子命令；单独 `--sandbox` / `--network` 写入配置并退出；带消息/`--resume`/`--model`/`--provider` 时才作为本轮覆盖；`--permission`；`--yes` 仍只表示自动批准。
+- HTTP：`GET/POST /v1/permission`、`GET/POST /v1/sandbox`；`/v1/chat` 增加 `sandbox`、`network`（只收紧）。`GET /v1/meta` 附带当前隔离摘要。
+
+---
+
+## 4. 文档与测试
+
+README / API.md / AGENTS.md / `/help` 同步。测试覆盖：路径策略、凭据拒绝、symlink 逃逸、档位收紧、`accept-edits`、无 OS 后端时的网络启发式、HTTP 只收紧。有系统隔离后端时加一条写盘拒绝的集成断言。

package/docs/superpowers/specs/2026-08-20-tui-completeness-design.md

@@ -0,0 +1,273 @@
+# TUI 补齐（第 1 批）— 设计文档
+
+**日期:** 2026-08-20
+**状态:** 已批准
+**范围:** 会话内恢复、`/reload`、输入历史持久化、编辑键、消息区选择增强、子 agent 工具行
+**实现路径:** 在现有 TUI 上按模块补；新文件只放纯函数，界面仍走 `slash-handler` / `InputBar` / `MessageList` / `task`
+
+后续批次不在本文：项目级 config、HTTP plan/budget、MCP resources、沙箱、exec JSON、原生 Anthropic/Google、hooks、Browser/LSP、主题可配。
+
+---
+
+## 背景
+
+TUI 已能拖拽复制、`/model` 选择器、内存输入历史、`task` 子 agent。缺口是：
+
+- `/sessions` 只能列表，恢复必须退出再 `--resume`
+- `--resume` 只把 `ModelMessage[]` 灌进 agent，消息区仍是空的
+- 没有 `/reload` 重读规则
+- 输入历史上次退出即丢
+- Home/End、折行上下、点击斜杠菜单未接
+- 双击选词、三击选段、复制去装饰前缀、键盘选择模式未做
+- 子 agent 进度打在 stderr，TUI 里只看到一条 `task` 结果
+
+## 设计决策（已与用户确认）
+
+| 决策 | 结论 |
+|------|------|
+| 会话恢复 UX | `/sessions` 与 `/resume` 无参打开选择器（像 `/model`），带 id 直接切换 |
+| 切换当前会话 | 有消息则自动保存，再加载目标 |
+| 输入历史 | 全局 `~/.min-agent/input-history.json`，上限 1000 |
+| 子 agent | 普通工具行，点开看子工具调用和结果 |
+| 键盘选择 | 消息区模式，**Ctrl+B** 进入；不在输入框做 Shift 选区 |
+| 双击/三击 | 选中后立刻复制（与拖拽松手一致） |
+
+## 目标与非目标
+
+**目标:**
+
+- 会话内切换并画出历史；`--resume` 启动同样画出历史
+- `/reload` 重读规则并更新 runner 的 system prompt
+- 输入历史上限 1000、原子落盘
+- Home/End、折行 ↑↓（到顶/底再翻历史）、点击斜杠/参数菜单
+- 双击选词、三击选段、复制去掉 `> ` / `⚡ name ▸ ` / 结果缩进
+- Ctrl+B 消息区选择模式：方向键扩选，Enter 复制退出，Esc 取消
+- TUI 中 `task` 可展开子工具列表；非 TUI 仍用 stderr
+
+**非目标:**
+
+- 输入框 Shift 选区、主题可配、项目级记忆/config、HTTP 新端点
+- 恢复思考过程、子 agent 思考文本、子 agent 再调 `task`/`explore`
+- 改会话文件格式
+
+---
+
+## 1. 会话切换与 `/reload`
+
+### 1.1 选择器
+
+新增 `SessionPicker.tsx`，交互对齐 `ModelPicker`（替换输入框、输入过滤、↑↓/PgUpDn、Enter、Esc）。列表来自 `listSessions()`，展示 `id`、日期、标题、消息数；当前会话标 `←`。过滤匹配 id 或标题。无会话时不打开选择器，系统提示「无已保存的会话」。
+
+`TuiState` 增加 `sessionPicker?: boolean`。`TuiRenderer.showSessionPicker()` / `hideSessionPicker()`。`TuiCallbacks` 增加 `onSessionPick(id)` / `onSessionCancel()`。`App` footer 与 `modelPicker` 互斥：同一时刻只出现一种 picker / confirm / question / input。
+
+### 1.2 命令
+
+| 输入 | 行为 |
+|------|------|
+| `/sessions` 或 `/resume` | 打开选择器 |
+| `/sessions <id>` 或 `/resume <id>` | 立即切换 |
+| `/resume` | `/sessions` 的别名（`slash-commands.ts` 的 `aliases`） |
+
+为 `sessions` / `resume` 注册 Tab 补全：`listSessions()` 的 id，description 用标题。
+
+`/help` 与菜单文案改为「列出/切换已保存会话」。
+
+### 1.3 `switchSession(id)`
+
+抽到 `src/tui/session-switch.ts`（协调逻辑）+ `src/tui/hydrate.ts`（纯函数）。步骤：
+
+1. agent 正在跑（`runner.getController()` 非空）→ 拒绝：「请先等待当前回合结束或按 Esc 取消」
+2. `id === sessionId` → 「已是当前会话」
+3. `loadSession(id)` 为空 → 「会话不存在」
+4. `messages.length > 0` → `sessionId = saveSession(messages, sessionId)`
+5. 就地替换：`messages.length = 0`；`messages.push(...session.messages)`（runner 持有同一引用）
+6. `setSessionId(id)`；`clearStack(undo)`；`tracker.resetContext()`
+7. `lastUserMessage` = 最后一条 user 文本（无则 `null`）
+8. `tui.update({ messages: hydrateMessages(session.messages) })`
+9. 系统提示 `✓ 已切换到: {title}`
+
+`planMode` 不随会话重置。不重建 system prompt。
+
+### 1.4 hydrate
+
+`hydrateMessages(messages: ModelMessage[]): TuiMessage[]` 有损映射：
+
+- `user`：文本拼接；仅图片 parts 时内容为 `[📎 图片]`
+- `assistant`：只保留 text parts；tool-call parts 忽略（工具结果走 `tool` 角色）
+- `tool`：一条工具行，`toolName` + 结果摘要（复用 `summarizeToolResult` / `toolResultText`）；无 name 则跳过
+- 其它 / 无法解析：跳过，不抛
+
+不恢复 `thinking`。用于 `--resume` 启动（`tui.start()` 之后立刻 `tui.update({ messages: hydrate(...) })`）和会话内切换。
+
+### 1.5 `/reload`
+
+- `loadInstructions()` + `scanProject()` + `buildCodeSystemPrompt()`
+- `AgentRunnerDeps.codeSystemPrompt: string` 改为 `getSystemPrompt: () => string`；`tui-chat` 用可变闭包持有最新 prompt
+- 系统提示 `✓ 已重载规则（N 字符）`
+- 不重连 MCP、不重扫 skills
+
+---
+
+## 2. 输入历史与编辑键
+
+### 2.1 持久化
+
+文件：`~/.min-agent/input-history.json`
+
+```json
+{ "entries": ["...", "..."] }
+```
+
+最新在末尾。`HISTORY_LIMIT = 1000`（现为 500）。连续重复仍去重。斜杠命令也记录。
+
+- 读：`InputBar` 挂载时 `loadInputHistory()` → `createHistory()` 填 `entries`
+- 写：`pushInput` 之后 `saveInputHistory(entries)`，原子写（tmp + rename），与 `memory.ts` 相同
+- 坏 JSON / 非数组：备份为 `input-history.json.corrupt-{ts}`，当空历史
+- 写失败：静默，不挡输入
+- 不写 logger（避免把用户输入打进运行日志）
+
+纯函数放在现有 `input-history.ts`：`parseHistoryFile` / `serializeHistoryFile`。
+
+### 2.2 Home / End
+
+与现有 Ctrl+A / Ctrl+E 相同：`moveToLineStart` / `moveToLineEnd`（逻辑行，按 `\n`）。Ink 若提供 `key.home` / `key.end` 则用；否则在 raw stdin 里解析 CSI `H` / `F` / `1~` / `4~`（与 Delete 扫描同一通道）。
+
+### 2.3 折行 ↑↓
+
+菜单或参数菜单打开时：↑↓ 仍只移动菜单（现状）。
+
+否则：
+
+- 先按视觉行移动光标（`visualRows` + 保持显示列，换算用现有 `caretIndexFromClick` 同类逻辑）
+- 已在第一视觉行再 ↑ → 翻更早历史
+- 已在最后视觉行再 ↓ → 翻更新历史
+
+新增 `moveCaretVertical(value, caretIndex, direction, maxWidth): number`（`caret-pos.ts`）。
+
+### 2.4 点击菜单
+
+SGR 点击落在斜杠菜单或参数菜单的某一选项行 → 与键盘选中后 Enter（命令菜单）或 Tab（参数菜单）相同：`acceptCommand` / `acceptArg`。点击菜单框外仍按现有逻辑（点输入区定位光标）。用 footer 行数反推菜单绝对行，与输入框点击定位同一套坐标。
+
+---
+
+## 3. 消息区选择
+
+拖拽选择状态机保留。复制路径统一走 `copySelection(text)`：去前缀 → `writeClipboard` → 成功且非空才 `showCopyNotice`。
+
+### 3.1 去前缀（只影响剪贴板）
+
+对 `areaRows` 里被选中的每一行，剥 ANSI 后：
+
+- 用户消息首行：去掉开头 `> `
+- 工具消息首行：去掉从 `⚡ ` 起到第一个 `▸ ` 或 `▾ `（含其后一个空格）
+- 工具展开结果行：去掉开头两个空格
+- 其它行不变
+
+高亮仍按屏幕所见（含前缀）。函数：`stripCopyDecorations(line: string, kind: "user-head" | "tool-head" | "tool-body" | "plain"): string`。`kind` 由该行对应的 `TuiMessage.role` 与是否为首行/结果行决定。
+
+### 3.2 双击 / 三击
+
+SGR 不带 click count。在 `click` outcome 上记 `{ row, col, at, count }`：
+
+- 400ms 内、同一行、列差 ≤ 2 → `count++`，否则重置为 1
+- `count === 2`：该行（剥 ANSI）按空白界选词，高亮并复制
+- `count === 3`：该行所属那条消息当前可见的全部行，高亮并复制
+- `count === 1`：保持现有单击（工具行展开）
+
+词界：连续非空白为一个词；行首/行尾夹紧。CJK 与拉丁一样按空白切，不按字素再切。
+
+### 3.3 Ctrl+B 选择模式
+
+`TuiState.selectionMode?: boolean`。`App` 在处理 Ctrl+C 旁监听 Ctrl+B：
+
+- 确认框 / 提问 / picker 打开时忽略
+- agent 正在跑时拒绝进入（避免与 Esc 取消抢键），不提示或仅短提示「请先结束或取消当前回合」
+- 进入后：`InputBar` 视为 disabled（不接收编辑键）；状态栏分隔线提示 `选择模式  ↑↓←→扩选  Enter复制  Esc退出`
+
+起点：上次成功的消息区点击坐标；若无，则可见区第一条非空文本行、列 0。`anchor` 固定，方向键只动 `cur`（与拖拽扩选同一套 `selectionRanges`）。Home/End 在模式内：行首 / 行尾显示列。
+
+- Enter：复制（去前缀）并退出模式，选区保持到下次点击/按键（与拖拽相同）
+- Esc：退出模式，清除选区，不复制
+- Ctrl+C：仍中断/退出进程，顺带退出选择模式
+- 滚轮：与现有一样清选区；选择模式保持，光标行随滚动夹紧
+
+Ctrl+B 在 `InputBar` 里目前被 `key.ctrl` 总拦截吞掉；改为由 `App` 先处理，或 `InputBar` 在 Ctrl+B 时 `onSelectionMode()`。
+
+---
+
+## 4. 子 agent 工具行
+
+`src/tools/task.ts` 的 `runSubAgent` 增加可选：
+
+```ts
+onSubToolCall?: (name: string, input: unknown) => void
+onSubToolResult?: (name: string, output: unknown, isError: boolean) => void
+```
+
+有回调时不写 stderr 进度；无回调时保持现有 `console.error`（`exec` / 测试）。
+
+`TuiMessage` 增加：
+
+```ts
+toolChildren?: { name: string; summary: string; result?: string; isError?: boolean }[]
+```
+
+`createTaskTool` 在 TUI 路径由 `agent-runner` 传入回调：按父级 `toolCallId` 调用 `tui.appendToolChild(...)`。未展开：仍只显示 `description` 与最终 `→ 摘要`（不在摘要行刷当前子工具名）。展开：在结果之上列出子工具名、参数摘要、结果（截断规则同普通工具行）。
+
+子 agent 仍删除 `task` / `explore`。最终回复仍是父级 `task` 的 `toolResult`。思考文本不展示。
+
+---
+
+## 5. 错误处理
+
+| 场景 | 行为 |
+|------|------|
+| 切换 id 不存在 | 提示，留在当前会话 |
+| 切换时 agent 在跑 | 拒绝 |
+| `--resume` 指向不存在的 id | 维持现状（当新会话） |
+| 历史文件损坏 | 备份后空历史 |
+| 历史写入失败 | 静默 |
+| 复制失败 | 不高亮「已复制」 |
+| hydrate 未知形状 | 跳过该条 |
+| Ctrl+B 时 picker/confirm 开着 | 忽略 |
+| Ctrl+B 时 agent 在跑 | 不进入选择模式 |
+
+## 6. 测试
+
+| 文件 | 覆盖 |
+|------|------|
+| `tests/hydrate.test.ts` | user 文本/图片、assistant 去掉 tool-call、tool 行、未知跳过 |
+| `tests/input-history.test.ts`（改） | 解析/序列化、上限 1000、坏文件 |
+| `tests/caret-pos.test.ts`（改） | `moveCaretVertical` 折行、顶/底夹紧；Home/End 已有则补物理键映射若抽出 |
+| `tests/selection.test.ts`（改） | 去前缀、选词范围、三击=整条可见行 |
+| `tests/drag-state.test.ts`（改）或新文件 | 400ms 双击计数（若把点击计数抽成纯函数） |
+| `tests/session-switch` 或 hydrate+save 组合 | 拒绝运行中切换的守卫可测则测；picker 不测 Ink |
+
+仓库根 `bun run typecheck`；`packages/min-agent` 下 `bun test`。
+
+## 7. 文档同步
+
+- `README.md` 交互命令表：`/sessions`、`/resume`、`/reload`；快捷键补 Ctrl+B、Home/End、鼠标双击/三击
+- `/help` 与 `slash-commands.ts`
+- Configuration 或日志旁注明输入历史路径 `~/.min-agent/input-history.json`
+- `AGENTS.md`：用户配置目录补一条 input-history（若该文件已列 `~/.min-agent/` 内容）
+
+无新 HTTP 端点，不改 `docs/API.md`。
+
+## 影响范围
+
+- `src/tui-chat.ts`、`src/tui/agent-runner.ts`、`src/tui/slash-handler.ts`、`src/tui/slash-commands.ts`
+- `src/tui/App.tsx`、`src/tui/index.tsx`、`src/tui/types.ts`、`src/tui/InputBar.tsx`、`src/tui/MessageList.tsx`、`src/tui/StatusBar.tsx`
+- 新：`src/tui/SessionPicker.tsx`、`src/tui/hydrate.ts`、`src/tui/session-switch.ts`（若逻辑超过 slash-handler 可读范围）
+- `src/tui/input-history.ts`、`src/tui/caret-pos.ts`、`src/tui/selection.ts`、`src/tui/drag-state.ts`
+- `src/tools/task.ts`、`src/tool-display.ts`（子工具摘要复用）
+- `README.md`、`/help`、`packages/min-agent/AGENTS.md`
+
+---
+
+## 自审
+
+- 无 TBD：选择模式起点、双击时限、历史路径与上限、hydrate 规则、`/reload` 不含 MCP/skills 已写死
+- 与「增量补模块」一致：新 UI 只加 SessionPicker；选择模式复用 `selectionRanges`
+- 单批可落地：不包含后四批
+- `--resume` 画历史与会话内切换共用 hydrate，避免两套映射