min-agent 0.2.0 → 0.3.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "min-agent",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Minimal AI coding agent with tool use, MCP, and skills support",
   "license": "MIT",
@@ -46,15 +46,14 @@
     "http-api"
   ],
   "dependencies": {
-    "@ai-sdk/openai": "3.0.53",
-    "@ai-sdk/provider": "3.0.8",
-    "@modelcontextprotocol/sdk": "1.27.1",
-    "ai": "6.0.168",
-    "glob": "13.0.5",
+    "@ai-sdk/openai": "~3.0.53",
+    "@ai-sdk/provider": "~3.0.8",
+    "@modelcontextprotocol/sdk": "~1.27.1",
+    "ai": "~6.0.168",
+    "glob": "~13.0.5",
     "ink": "5",
     "ink-spinner": "5",
-    "react": "18",
-    "zod": "^3.25.76"
+    "react": "18"
   },
   "devDependencies": {
     "@types/node": "22.13.9",