min-agent 0.2.0 → 0.3.0

package/docs/superpowers/plans/2026-08-16-input-caret.md

@@ -0,0 +1,782 @@
+# 输入框光标编辑实现计划
+
+> **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:** 输入框支持左右键移动光标、点击定位光标、光标处插入/删除文本。
+
+**Architecture:** 编辑与坐标换算逻辑抽为纯函数模块(`src/tui/mouse.ts`、`src/tui/caret-pos.ts`),InputBar 只做状态与渲染集成。光标 `caretIndex` 基于 code point 数组索引(兼容 CJK/emoji),视觉行由 `visualRows()` 统一派生,渲染与点击换算共用同一份行映射,保证一致。
+
+**Tech Stack:** TypeScript, React 18 + Ink 5, bun:test, SGR 鼠标协议 (1006)
+
+**Spec:** `docs/superpowers/specs/2026-08-16-input-caret-design.md`
+
+---
+
+## 文件结构
+
+| 文件 | 职责 |
+|---|---|
+| `src/tui/mouse.ts`(新) | SGR 鼠标协议:启用/禁用序列常量、`parseSgrMouse()` 事件解析 |
+| `src/tui/caret-pos.ts`(新) | 光标纯函数:`visualRows()` 视觉行映射、`moveCaretHorizontal()`、`caretIndexFromClick()`、`insertAt()`/`backspaceAt()`/`deleteAt()` |
+| `src/tui/InputBar.tsx`(改) | 集成:`caretIndex` state、左右键/插入/退格、光标渲染、硬件光标位置、鼠标协议启用与事件处理 |
+| `src/tui/App.tsx`(改) | 给 InputBar 传 `terminalRows` prop |
+| `tests/mouse.test.ts`(新) | 鼠标序列解析 |
+| `tests/caret-pos.test.ts`(新) | 视觉行/移动/点击换算/编辑函数 |
+
+测试命令(在 `packages/min-agent` 下):`bun test tests/<file>`、全量 `bun test`、类型 `./node_modules/.bin/tsc --noEmit`。
+
+---
+
+## Task 1: mouse.ts — SGR 鼠标序列解析
+
+**Files:**
+- Create: `src/tui/mouse.ts`
+- Test: `tests/mouse.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+```ts
+import { expect, test } from "bun:test"
+import { parseSgrMouse, MOUSE_ENABLE, MOUSE_DISABLE } from "../src/tui/mouse.js"
+
+test("parseSgrMouse extracts row and col from a press event", () => {
+  expect(parseSgrMouse("\x1b[<0;10;5M")).toEqual({ row: 5, col: 10 })
+  expect(parseSgrMouse("\x1b[<2;3;1M")).toEqual({ row: 1, col: 3 })
+})
+
+test("parseSgrMouse finds the event inside a larger chunk", () => {
+  expect(parseSgrMouse("abc\x1b[<0;1;2Mxyz")).toEqual({ row: 2, col: 1 })
+})
+
+test("parseSgrMouse returns null for non-mouse input", () => {
+  expect(parseSgrMouse("hello")).toBeNull()
+  expect(parseSgrMouse("\x1b[13;2u")).toBeNull()
+  expect(parseSgrMouse("\x1b[<0;3;4m")).toBeNull()
+})
+
+test("mouse enable/disable sequences are well-formed", () => {
+  expect(MOUSE_ENABLE).toContain("?1000h")
+  expect(MOUSE_ENABLE).toContain("?1006h")
+  expect(MOUSE_DISABLE).toContain("?1000l")
+  expect(MOUSE_DISABLE).toContain("?1006l")
+})
+```
+
+- [ ] **Step 2: 运行确认失败**
+
+Run: `bun test tests/mouse.test.ts`
+Expected: FAIL(模块不存在)
+
+- [ ] **Step 3: 实现**
+
+```ts
+/** Enable button-event tracking (1000) with SGR coordinates (1006). */
+export const MOUSE_ENABLE = "\x1b[?1000h\x1b[?1006h"
+/** Disable button-event tracking. */
+export const MOUSE_DISABLE = "\x1b[?1000l\x1b[?1006l"
+
+/**
+ * Parse an SGR mouse press event from raw stdin bytes:
+ * CSI < b ; Px ; Py M — button; column; row (b is 0 for left, rows/cols 1-based).
+ * Only press events (uppercase M) are handled; release events (lowercase m)
+ * are ignored. Returns null if no event found.
+ */
+export function parseSgrMouse(input: string): { row: number; col: number } | null {
+  const match = input.match(/\x1b\[<(\d+);(\d+);(\d+)M/)
+  if (!match) return null
+  return { row: parseInt(match[3]!, 10), col: parseInt(match[2]!, 10) }
+}
+```
+
+注意:真实 xterm SGR 鼠标序列是三字段 `CSI < b ; Px ; Py M`(按钮;列;行),不是两字段——测试必须用真实终端会发出的格式。
+
+- [ ] **Step 4: 运行确认通过**
+
+Run: `bun test tests/mouse.test.ts`
+Expected: PASS(4 tests)
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/tui/mouse.ts tests/mouse.test.ts
+git commit -m "feat: SGR 鼠标序列解析"
+```
+
+---
+
+## Task 2: caret-pos.ts — 视觉行映射与光标移动
+
+**Files:**
+- Create: `src/tui/caret-pos.ts`
+- Test: `tests/caret-pos.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+```ts
+import { expect, test } from "bun:test"
+import { visualRows, moveCaretHorizontal } from "../src/tui/caret-pos.js"
+
+test("visualRows maps a single line", () => {
+  expect(visualRows("ab", 10)).toEqual([{ text: "ab", startIndex: 0 }])
+})
+
+test("visualRows counts newlines as one character", () => {
+  expect(visualRows("ab\ncd", 10)).toEqual([
+    { text: "ab", startIndex: 0 },
+    { text: "cd", startIndex: 3 },
+  ])
+})
+
+test("visualRows wraps wide lines and tracks fullwidth widths", () => {
+  const rows = visualRows("你好ab", 4)
+  expect(rows[0]!.text).toBe("你好")
+  expect(rows[0]!.startIndex).toBe(0)
+  expect(rows[1]!.text).toBe("ab")
+  expect(rows[1]!.startIndex).toBe(2)
+})
+
+test("visualRows handles an empty value", () => {
+  expect(visualRows("", 10)).toEqual([{ text: "", startIndex: 0 }])
+})
+
+test("moveCaretHorizontal clamps at both ends", () => {
+  expect(moveCaretHorizontal("ab", 0, -1)).toBe(0)
+  expect(moveCaretHorizontal("ab", 2, 1)).toBe(2)
+})
+
+test("moveCaretHorizontal steps by code point, not UTF-16 unit", () => {
+  expect(moveCaretHorizontal("a你b", 1, 1)).toBe(2)
+  expect(moveCaretHorizontal("a你b", 2, -1)).toBe(1)
+})
+
+test("moveCaretHorizontal crosses visual rows naturally", () => {
+  expect(moveCaretHorizontal("ab\ncd", 2, 1)).toBe(3)
+  expect(moveCaretHorizontal("ab\ncd", 3, -1)).toBe(2)
+})
+```
+
+- [ ] **Step 2: 运行确认失败**
+
+Run: `bun test tests/caret-pos.test.ts`
+Expected: FAIL(模块不存在)
+
+- [ ] **Step 3: 实现**
+
+```ts
+import { charWidth, wrapByWidth } from "./text-width.js"
+
+/** One visual row of the input value: the text and its first character's index in Array.from(value). */
+export interface VisualRow {
+  text: string
+  startIndex: number
+}
+
+/** Split the value into visual rows, tracking each row's character start index (newlines count as one). */
+export function visualRows(value: string, maxWidth: number): VisualRow[] {
+  const rows: VisualRow[] = []
+  let start = 0
+  const lines = value.split("\n")
+  for (let i = 0; i < lines.length; i++) {
+    for (const row of wrapByWidth(lines[i]!, maxWidth)) {
+      rows.push({ text: row, startIndex: start })
+      start += Array.from(row).length
+    }
+    if (i < lines.length - 1) start += 1
+  }
+  return rows
+}
+
+/** Move the caret by one code point; clamps at the start/end of the value. */
+export function moveCaretHorizontal(value: string, caretIndex: number, direction: 1 | -1): number {
+  const len = Array.from(value).length
+  return Math.min(Math.max(caretIndex + direction, 0), len)
+}
+```
+
+- [ ] **Step 4: 运行确认通过**
+
+Run: `bun test tests/caret-pos.test.ts`
+Expected: PASS(7 tests)
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/tui/caret-pos.ts tests/caret-pos.test.ts
+git commit -m "feat: 输入框视觉行映射与光标移动"
+```
+
+---
+
+## Task 3: caret-pos.ts — 点击换算与编辑函数
+
+**Files:**
+- Modify: `src/tui/caret-pos.ts`
+- Test: `tests/caret-pos.test.ts`
+
+- [ ] **Step 1: 写失败测试(追加)**
+
+```ts
+import { caretIndexFromClick, insertAt, backspaceAt, deleteAt } from "../src/tui/caret-pos.js"
+
+test("caretIndexFromClick maps column to character index", () => {
+  const rows = visualRows("abcd", 10)
+  expect(caretIndexFromClick(rows, 0, 5, 5)).toBe(0)
+  expect(caretIndexFromClick(rows, 0, 6, 5)).toBe(1)
+  expect(caretIndexFromClick(rows, 0, 9, 5)).toBe(4)
+  expect(caretIndexFromClick(rows, 0, 99, 5)).toBe(4)
+})
+
+test("caretIndexFromClick snaps fullwidth characters to the nearest boundary", () => {
+  const rows = visualRows("你ab", 10)
+  // "你" spans columns 5-6; clicking past it snaps to index 1
+  expect(caretIndexFromClick(rows, 0, 7, 5)).toBe(1)
+  // clicking just before it stays at index 0
+  expect(caretIndexFromClick(rows, 0, 5, 5)).toBe(0)
+})
+
+test("caretIndexFromClick picks the right visual row", () => {
+  const rows = visualRows("ab\ncd", 10)
+  // row 1 is "cd" starting at text column 4: 'c' occupies col 4, 'd' col 5;
+  // clicking 'd' snaps to the boundary before it (index 4)
+  expect(caretIndexFromClick(rows, 1, 5, 4)).toBe(4)
+})
+
+test("caretIndexFromClick with an out-of-range row returns 0", () => {
+  const rows = visualRows("ab", 10)
+  expect(caretIndexFromClick(rows, 5, 5, 4)).toBe(0)
+})
+
+test("insertAt inserts at the caret and advances it", () => {
+  expect(insertAt("ab", 1, "X")).toEqual({ value: "aXb", caretIndex: 2 })
+  expect(insertAt("ab", 0, "你")).toEqual({ value: "你ab", caretIndex: 1 })
+  expect(insertAt("", 0, "x")).toEqual({ value: "x", caretIndex: 1 })
+})
+
+test("backspaceAt removes the code point before the caret", () => {
+  expect(backspaceAt("ab", 2)).toEqual({ value: "a", caretIndex: 1 })
+  expect(backspaceAt("a你b", 2)).toEqual({ value: "ab", caretIndex: 1 })
+  expect(backspaceAt("ab", 0)).toEqual({ value: "ab", caretIndex: 0 })
+})
+
+test("deleteAt removes the code point at the caret", () => {
+  expect(deleteAt("ab", 0)).toEqual({ value: "b", caretIndex: 0 })
+  expect(deleteAt("a你b", 1)).toEqual({ value: "ab", caretIndex: 1 })
+  expect(deleteAt("ab", 2)).toEqual({ value: "ab", caretIndex: 2 })
+})
+```
+
+- [ ] **Step 2: 运行确认失败**
+
+Run: `bun test tests/caret-pos.test.ts`
+Expected: FAIL(caretIndexFromClick/insertAt 等未定义)
+
+- [ ] **Step 3: 实现(追加到 caret-pos.ts)**
+
+```ts
+/**
+ * Map a click column (1-based terminal column) on a visual row to a character
+ * index in the value. Fullwidth characters snap to the nearer boundary.
+ */
+export function caretIndexFromClick(
+  rows: VisualRow[],
+  rowIndex: number,
+  clickColumn: number,
+  textStartColumn: number,
+): number {
+  const row = rows[rowIndex]
+  if (!row) return 0
+  const target = clickColumn - textStartColumn
+  if (target <= 0) return row.startIndex
+  let width = 0
+  let idx = 0
+  for (const char of row.text) {
+    const w = charWidth(char)
+    if (width + w > target) {
+      return row.startIndex + idx + (target - width < w / 2 ? 0 : 1)
+    }
+    width += w
+    idx++
+  }
+  return row.startIndex + idx
+}
+
+/** Insert text at the caret; returns the new value and caret index. */
+export function insertAt(value: string, caretIndex: number, text: string): { value: string; caretIndex: number } {
+  const chars = Array.from(value)
+  chars.splice(caretIndex, 0, ...Array.from(text))
+  return { value: chars.join(""), caretIndex: caretIndex + Array.from(text).length }
+}
+
+/** Remove the code point before the caret. */
+export function backspaceAt(value: string, caretIndex: number): { value: string; caretIndex: number } {
+  if (caretIndex <= 0) return { value, caretIndex }
+  const chars = Array.from(value)
+  chars.splice(caretIndex - 1, 1)
+  return { value: chars.join(""), caretIndex: caretIndex - 1 }
+}
+
+/** Remove the code point at the caret. */
+export function deleteAt(value: string, caretIndex: number): { value: string; caretIndex: number } {
+  const chars = Array.from(value)
+  if (caretIndex >= chars.length) return { value, caretIndex }
+  chars.splice(caretIndex, 1)
+  return { value: chars.join(""), caretIndex }
+}
+```
+
+注意:`chars` 是 code point 数组,`splice` 索引即 code point 索引,与 `caretIndex` 语义一致,无需 UTF-16 换算。
+
+- [ ] **Step 4: 运行确认通过**
+
+Run: `bun test tests/caret-pos.test.ts`
+Expected: PASS(14 tests)
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/tui/caret-pos.ts tests/caret-pos.test.ts
+git commit -m "feat: 点击坐标换算与光标编辑函数"
+```
+
+---
+
+## Task 4: InputBar 集成 — 光标状态、左右键与编辑
+
+**Files:**
+- Modify: `src/tui/InputBar.tsx`
+
+先读取当前文件确认行号(`packages/min-agent/src/tui/InputBar.tsx`,以下基于 HEAD 版本)。
+
+- [ ] **Step 1: 替换 import 与光标状态**
+
+将:
+
+```tsx
+import { displayWidth, wrapByWidth } from "./text-width.js"
+```
+
+替换为:
+
+```tsx
+import { displayWidth } from "./text-width.js"
+import { visualRows, moveCaretHorizontal, insertAt, backspaceAt, deleteAt } from "./caret-pos.js"
+```
+
+在 `const [value, setValue] = useState("")` 后加:
+
+```tsx
+const [caretIndex, setCaretIndex] = useState(0)
+```
+
+更新 `acceptCommand`:
+
+```tsx
+  const acceptCommand = (cmd: SlashCommand) => {
+    if (cmd.argHint) {
+      setValue(`/${cmd.name} `)
+      setCaretIndex(cmd.name.length + 2)
+      setMenuDismissed(true)
+    } else {
+      onSubmit(`/${cmd.name}`)
+      setValue("")
+      setCaretIndex(0)
+    }
+  }
+```
+
+- [ ] **Step 2: 重写 useInput 回调**
+
+将 `useInput((input, key) => { ... })` 回调整体替换为:
+
+```tsx
+  useInput((input, key) => {
+    if (disabled) return
+
+    // Fast typing or paste can deliver "text\r" as a single chunk — treat a
+    // trailing Enter as Enter and strip it from the value.
+    const cleanInput = input.replace(/[\r\n]+$/, "")
+    const pressedEnter = key.return || /[\r\n]+$/.test(input)
+
+    // Esc closes the slash menu
+    if (key.escape) {
+      if (menuOpen) setMenuDismissed(true)
+      return
+    }
+
+    // Any other key re-opens the menu
+    setMenuDismissed(false)
+
+    // Slash menu navigation
+    if (menuOpen) {
+      if (key.downArrow) {
+        setMenuIndex((i) => (i + 1) % matches.length)
+        return
+      }
+      if (key.upArrow) {
+        setMenuIndex((i) => (i - 1 + matches.length) % matches.length)
+        return
+      }
+      if (pressedEnter || key.tab) {
+        if (selected) acceptCommand(selected)
+        return
+      }
+      // Left/right keep their normal caret behavior even with the menu open
+      if (key.leftArrow || key.rightArrow) return
+    }
+
+    // Ctrl+J: insert newline
+    if (key.ctrl && input === "j") {
+      const after = insertAt(value, caretIndex, "\n")
+      setValue(after.value)
+      setCaretIndex(after.caretIndex)
+      return
+    }
+
+    // Enter: submit or continue if ends with backslash
+    if (pressedEnter) {
+      if (value.endsWith("\\")) {
+        const after = insertAt(value.slice(0, -1), caretIndex, "\n")
+        setValue(after.value)
+        setCaretIndex(after.caretIndex)
+        return
+      }
+      const text = value.trim()
+      if (text) {
+        onSubmit(text)
+        setValue("")
+        setCaretIndex(0)
+      }
+      return
+    }
+
+    // Left / right move the caret through the text
+    if (key.leftArrow) {
+      setCaretIndex((i) => moveCaretHorizontal(value, i, -1))
+      return
+    }
+    if (key.rightArrow) {
+      setCaretIndex((i) => moveCaretHorizontal(value, i, 1))
+      return
+    }
+
+    // Backspace / Delete — remove a whole code point, not a UTF-16 unit,
+    // otherwise CJK and emoji leave broken surrogate halves behind.
+    if (key.backspace || key.delete) {
+      const after = key.delete ? deleteAt(value, caretIndex) : backspaceAt(value, caretIndex)
+      setValue(after.value)
+      setCaretIndex(after.caretIndex)
+      return
+    }
+
+    // Escape, up/down arrows, etc. — ignore (handled elsewhere)
+    if (key.escape || key.upArrow || key.downArrow || key.pageUp || key.pageDown) return
+    if (key.ctrl || key.meta) return
+
+    // Kitty Shift+Enter sequence (or a fragment of it) — handled by the raw
+    // stdin listener, never as text
+    if (isKittySequenceFragment(input)) return
+
+    // SGR mouse events are handled by the raw stdin listener (Task 5)
+    if (/^\[<.*M$/.test(input)) return
+
+    // Tab → 2 spaces
+    if (key.tab) {
+      const after = insertAt(value, caretIndex, "  ")
+      setValue(after.value)
+      setCaretIndex(after.caretIndex)
+      return
+    }
+
+    // Normal character input (including CJK)
+    if (input) {
+      const after = insertAt(value, caretIndex, cleanInput)
+      setValue(after.value)
+      setCaretIndex(after.caretIndex)
+    }
+  }, { isActive: !disabled })
+```
+
+同时将 Kitty 监听中的 `setValue((v) => v + "\n")` 改为:
+
+```tsx
+      if (shiftEnter) setValue((v) => v + "\n")
+```
+
+(保持原样——Shift+Enter 在行尾追加,与光标位置无关;若后续需要光标感知可再改,本次不涉及。)
+
+注意:原回调中的 `if (key.pageUp || key.pageDown) return` 与 `key.ctrl || key.meta` 已合并进新代码。
+
+- [ ] **Step 3: 更新渲染与硬件光标位置**
+
+将:
+
+```tsx
+  const isEmpty = value === ""
+  const logicalLines = value.split("\n")
+  const isMultiline = logicalLines.length > 1
+  const borderColor = disabled ? "gray" : "cyan"
+
+  // Available cells for text on a single visual row.
+  const textWidth = Math.max(8, width - BOX_CHROME - GUTTER_WIDTH)
+
+  // Visual rows of the value, plus the caret position inside them.
+  const rows: string[] = []
+  for (const line of logicalLines) rows.push(...wrapByWidth(line, textWidth))
+  let caretColumnOffset = displayWidth(rows[rows.length - 1]!)
+  // The caret block itself needs a cell; if the row is full it moves down.
+  if (caretColumnOffset + 1 > textWidth) {
+    rows.push("")
+    caretColumnOffset = 0
+  }
+  const caretRow = rows.length - 1
+```
+
+替换为:
+
+```tsx
+  const isEmpty = value === ""
+  const logicalLines = value.split("\n")
+  const isMultiline = logicalLines.length > 1
+  const borderColor = disabled ? "gray" : "cyan"
+
+  // Available cells for text on a single visual row.
+  const textWidth = Math.max(8, width - BOX_CHROME - GUTTER_WIDTH)
+
+  // Visual rows of the value, plus the caret position inside them.
+  const rows = visualRows(value, textWidth)
+  const clampedCaret = Math.min(caretIndex, Array.from(value).length)
+  // Locate the caret's visual row and its column offset inside that row.
+  let caretRowIndex = rows.length - 1
+  let caretColumnOffset = displayWidth(rows[caretRowIndex]!.text)
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i]!
+    const end = row.startIndex + Array.from(row.text).length
+    if (clampedCaret >= row.startIndex && clampedCaret <= end) {
+      caretRowIndex = i
+      caretColumnOffset = displayWidth(Array.from(row.text).slice(0, clampedCaret - row.startIndex).join(""))
+      break
+    }
+  }
+  // A caret at the end of a full row has no cell left — move it to the start
+  // of the next visual row (pushing an empty one when it is the last row).
+  if (caretColumnOffset >= textWidth) {
+    if (caretRowIndex === rows.length - 1) {
+      rows.push({
+        text: "",
+        startIndex: rows[caretRowIndex]!.startIndex + Array.from(rows[caretRowIndex]!.text).length,
+      })
+    }
+    caretRowIndex++
+    caretColumnOffset = 0
+  }
+```
+
+将 `setCaretPosition` 段:
+
+```tsx
+  setCaretPosition({
+    rowsAbove: 1 /* bottom border */ + hintRows + menuRows,
+    column: TEXT_START_COLUMN + caretColumnOffset,
+  })
+```
+
+替换为:
+
+```tsx
+  const rowsBelowCaret = rows.length - 1 - caretRowIndex
+  setCaretPosition({
+    rowsAbove: rowsBelowCaret + 1 /* bottom border */ + hintRows + menuRows,
+    column: TEXT_START_COLUMN + caretColumnOffset,
+  })
+```
+
+将 `rows.map((row, i) => ...)` 渲染段:
+
+```tsx
+        rows.map((row, i) => (
+          <Box key={i}>
+            <Text color={disabled ? "gray" : "cyan"}>{i === 0 ? GUTTER : "  "}</Text>
+            <Text wrap="truncate-end">{i === caretRow ? `${row}█` : row}</Text>
+          </Box>
+        ))
+```
+
+替换为:
+
+```tsx
+        rows.map((row, i) => {
+          const chars = Array.from(row.text)
+          const rowEnd = row.startIndex + chars.length
+          const caretHere = clampedCaret >= row.startIndex && clampedCaret <= rowEnd
+          const offset = caretHere ? clampedCaret - row.startIndex : chars.length
+          const before = chars.slice(0, offset).join("")
+          const after = chars.slice(offset).join("")
+          return (
+            <Box key={i}>
+              <Text color={disabled ? "gray" : "cyan"}>{i === 0 ? GUTTER : "  "}</Text>
+              <Text wrap="truncate-end">
+                {before}
+                {caretHere && <Text inverse> </Text>}
+                {after}
+              </Text>
+            </Box>
+          )
+        })
+```
+
+注意:光标用 `<Text inverse> </Text>`(反色空格,1 个单元格)替代原行尾 `█`,与硬件光标位置一致;空值时 placeholder 分支保持原样,硬件光标由 setCaretPosition 停在文本起始列。
+
+- [ ] **Step 4: 类型检查与测试**
+
+Run: `./node_modules/.bin/tsc --noEmit`
+Expected: 无错误
+
+Run: `bun test`
+Expected: 全部通过(现有 153 tests 不受影响)
+
+- [ ] **Step 5: 手动验证(可选)**
+
+Run: `bun run src/cli.ts`,输入文本后按 ← → 移动光标;把光标移到中间再输入/退格,观察插入位置正确;退格删除光标前字符。
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/tui/InputBar.tsx
+git commit -m "feat: 输入框光标移动与光标处编辑"
+```
+
+---
+
+## Task 5: 鼠标点击定位
+
+**Files:**
+- Modify: `src/tui/InputBar.tsx`
+- Modify: `src/tui/App.tsx`
+
+- [ ] **Step 1: App 传入 terminalRows**
+
+在 `App.tsx` 的 InputBar 调用处加 `terminalRows={terminalRows}`:
+
+```tsx
+        <InputBar
+          onSubmit={onSubmit}
+          disabled={initialState.isRunning}
+          placeholder={initialState.isRunning ? "按 Esc 取消运行..." : "输入消息... (Ctrl+J 换行)"}
+          columns={columns}
+          terminalRows={terminalRows}
+        />
+```
+
+在 `InputBarProps` 接口(InputBar.tsx)加:
+
+```tsx
+  /** Terminal height (rows), kept fresh by the App-level resize listener. */
+  terminalRows: number
+```
+
+并在组件解构处加 `terminalRows`。
+
+- [ ] **Step 2: InputBar 启用鼠标协议并解析点击**
+
+InputBar.tsx 顶部 import 改为:
+
+```tsx
+import { Box, Text, useInput, useStdin, useStdout } from "ink"
+import { setCaretPosition } from "./caret.js"
+import { displayWidth } from "./text-width.js"
+import { visualRows, moveCaretHorizontal, insertAt, backspaceAt, deleteAt, caretIndexFromClick } from "./caret-pos.js"
+import { MOUSE_ENABLE, MOUSE_DISABLE, parseSgrMouse } from "./mouse.js"
+```
+
+在 `const { stdin } = useStdin()` 后加 `const { stdout } = useStdout()`。
+
+在 `const width = columns || 80` 后加输入框几何计算(依赖渲染期值,放组件体内、`rows` 计算之后;下面的 effect 通过依赖数组拿到最新值):
+
+```tsx
+  // Input bar sits at the bottom of App's footer: its content area starts
+  // `terminalRows` rows up minus the bar's own height.
+  const inputTopRow = terminalRows - rows.length - 2 /* border */ - hintRows - menuRows + 1
+```
+
+将 Kitty 监听 effect 替换为(同时解析鼠标;依赖数组包含几何值,每次输入变化重建监听,成本可忽略):
+
+```tsx
+  useEffect(() => {
+    if (!stdin || disabled) return
+
+    const handleData = (data: Buffer) => {
+      const chunk = data.toString("utf-8")
+      const { buffer, shiftEnter } = accumulateKittyInput(kittyBuffer.current, chunk)
+      kittyBuffer.current = buffer
+      if (shiftEnter) setValue((v) => v + "\n")
+      const click = parseSgrMouse(chunk)
+      if (click) {
+        const contentRow = click.row - inputTopRow
+        if (contentRow >= 0 && contentRow < rows.length) {
+          setCaretIndex(caretIndexFromClick(rows, contentRow, click.col, TEXT_START_COLUMN))
+        }
+      }
+    }
+
+    stdin.on("data", handleData)
+    return () => { stdin.off("data", handleData) }
+  }, [stdin, disabled, rows, inputTopRow])
+```
+
+新增鼠标协议启用的 effect(放在 Kitty effect 之后):
+
+```tsx
+  // Enable the SGR mouse protocol so clicks on the input bar can position the
+  // caret. Events arrive on raw stdin; parseSgrMouse picks them out of the
+  // same chunk stream as the Kitty sequence. Terminals without mouse support
+  // simply never send events — keyboard navigation still works.
+  useEffect(() => {
+    stdout.write(MOUSE_ENABLE)
+    return () => { stdout.write(MOUSE_DISABLE) }
+  }, [stdout])
+```
+
+注意:依赖数组包含 `rows`(每次渲染新数组)→ Kitty effect 每次按键重建。`accumulateKittyInput` 的 `kittyBuffer` 是 ref,不受影响。若担心频繁重建,可将 `rows`/`inputTopRow` 改用 ref(见下方"替代实现"注释)——保持简单,直接依赖即可。
+
+- [ ] **Step 3: 类型检查与测试**
+
+Run: `./node_modules/.bin/tsc --noEmit`
+Expected: 无错误
+
+Run: `bun test`
+Expected: 全部通过
+
+- [ ] **Step 4: 手动验证**
+
+Run: `bun run src/cli.ts`:
+1. 输入多行文本(含中文),鼠标点击输入框任意位置,光标应跳到点击处
+2. 点击中间后输入/退格,在光标处生效
+3. 点击输入框上方区域不应移动光标
+4. 退出 TUI(Ctrl+C / /exit)后终端鼠标恢复默认(可正常选中文本)
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/tui/InputBar.tsx src/tui/App.tsx
+git commit -m "feat: 输入框鼠标点击定位光标"
+```
+
+---
+
+## Task 6: 收尾验证
+
+- [ ] **Step 1: 全量验证**
+
+Run: `bun test && ./node_modules/.bin/tsc --noEmit`
+Expected: 全部通过、无类型错误
+
+- [ ] **Step 2: 更新文档(如涉及)**
+
+检查 `packages/min-agent/README.md` 与交互模式 `/help` 是否描述输入框交互;若描述与现状不符,同步更新。
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add -A
+git commit -m "chore: 输入框光标编辑收尾"
+```