minimal-agent 0.10.0 → 0.12.0

package/src/ui/liveViewport.ts

@@ -0,0 +1,189 @@
+/**
+ * ============================================================
+ *  src/ui/liveViewport.ts —— LiveArea 有界多行 live 区的宽度安全工具（纯函数）
+ * ------------------------------------------------------------
+ *  ★ 两条硬不变量（根治 Windows 终端"思维链刷屏"，缺一不可）：
+ *
+ *    Ink 默认 render 在主屏 scrollback 上用 log-update 维护**底部 live 区**：
+ *    每帧 `eraseLines(上一帧 \n 数)`（光标上移逐行清）再重写。两个坑都会让上移清除"漏擦"：
+ *
+ *    ┌─ INV-1 每行物理宽度 < 终端宽 ──────────────────────────────┐
+ *    │ stock ink `log-update.js` 用 `output.split('\n').length` 记账，    │
+ *    │ **完全不补偿满宽行被终端自动折行**。若某行物理宽触到终端最后一列，   │
+ *    │ 终端自己折一行 → 实际物理行 > ink 记的 \n 数 → eraseLines 擦少 →   │
+ *    │ 它上面的行每帧 strand 进 scrollback = 刷屏。                       │
+ *    │ ∴ live 区每一行都按**我们自己的** displayWidth（CJK/全角/emoji=2，  │
+ *    │   宁宽不窄）预钳到 ≤ cols - LIVE_RIGHT_MARGIN 再交给 ink。不依赖    │
+ *    │   ink 的字宽测量 → 终端永不折行 → \n 记账 == 物理行 → 精确擦除。     │
+ *    └────────────────────────────────────────────────────────┘
+ *    ┌─ INV-2 live 区总高度 < 终端行数 ──────────────────────────┐
+ *    │ `ink.js` onRender：一旦 outputHeight >= stdout.rows 会**全屏        │
+ *    │ clearTerminal 重写**（含整个 static），灾难性。∴ 流式内容预览必须   │
+ *    │ 有界（取尾部最近 N 行，N 自适应终端高度，见 LiveArea.contentMaxLines）。│
+ *    └────────────────────────────────────────────────────────┘
+ *
+ *    完整思维链 / 完整答案 / 完整工具结果一律走 `<Static>`（write-once，永不
+ *    参与 log-update → 天然 strand-proof、高度不受限）。live 区只放**有界**的过程预览。
+ *
+ *  ★ 中文/emoji 宽度（关键，别退化成按码点切）：
+ *    CJK / 全角 / emoji 1 码点 = 2 列。宽度必须按 charWidth 累加，不能按 length，
+ *    否则这些字符实际占 2× 列宽被算窄、钳不住 → 终端折行 → INV-1 失守、刷屏复发。
+ * ============================================================
+ */
+
+/** live 行右侧安全余量（列）：钳到 cols - 此值，吃掉光标在"恰好满宽"处的自动折行边界。 */
+export const LIVE_RIGHT_MARGIN = 2;
+
+/** 剥离 ANSI/CSI 控制序列（含 ESC 引导符）。流式文本理论上没有，做防御性清理。 */
+const ANSI_RE = new RegExp('\\u001b\\[[0-9;?]*[ -/]*[@-~]', 'g');
+
+/**
+ * 单个 Unicode 码点的终端显示宽度：CJK / 全角 / emoji = 2，其余 = 1。
+ *
+ * 设计目标是做终端实际宽度的**上界估计**（宁可算宽、不可算窄）：算宽只会让行
+ * 提前一两列截断（无害），算窄则会让钳制失效、终端折行（= 刷屏复发，INV-1 失守）。
+ *
+ * 覆盖：
+ *   - 常见 East Asian Ambiguous 标点（…—–·“”‘’ 等）：CJK 终端按全角(2)渲染，
+ *     这些是中文文本里最容易把行顶宽的"隐形 2 列"字符，统一按 2 计。
+ *   - Emoji / 符号 / dingbat（💭✶ 等）：终端普遍按全角(2)渲染。注意 charWidth 是
+ *     逐码点求和，ZWJ/变体序列会被算成各组件之和（偏大 = 安全方向）。
+ *   - Hangul Jamo / CJK 部首笔画符号标点 / 假名 / CJK 统一 / 谚文音节 /
+ *     兼容表意 / 竖排标点 / 全角 ASCII 与符号 / CJK 扩展 B+（星平面）。
+ */
+export function charWidth(cp: number): 1 | 2 {
+  // 常见 ambiguous-width 标点：CJK 终端按 2 列渲染，统一上界为 2 防折行
+  if (
+    cp === 0x00b7 || // ·
+    cp === 0x2013 || // –
+    cp === 0x2014 || // —
+    cp === 0x2018 || // ‘
+    cp === 0x2019 || // ’
+    cp === 0x201c || // “
+    cp === 0x201d || // ”
+    cp === 0x2026 || // …
+    cp === 0x203b // ※
+  ) {
+    return 2;
+  }
+  // Emoji / 符号 / dingbat：终端普遍全角渲染（含 💭 与 spinner ✶✷✸✹✺）。上界=2，算宽无害。
+  // 0x2300/0x2500 两段是蜂群树引入的 ⎿ ├ └ │ ─（figures.ts）——ambiguous-width，
+  // CJK 终端可能按全角渲染，按「宁宽不窄」哲学一并按 2 计（INV-1 记账依赖此上界）。
+  if (
+    (cp >= 0x2300 && cp <= 0x23ff) || // Misc Technical（含 ⎿ U+23BF）
+    (cp >= 0x2500 && cp <= 0x25ff) || // Box Drawing / Block Elements / Geometric（├ └ │ ─ ▾ ▶）
+    (cp >= 0x2600 && cp <= 0x27bf) || // Misc Symbols + Dingbats（含 ✶✷✸✹✺）
+    (cp >= 0x2b00 && cp <= 0x2bff) || // Misc Symbols and Arrows
+    (cp >= 0xfe00 && cp <= 0xfe0f) || // Variation Selectors（VS16 强制全角）
+    (cp >= 0x1f000 && cp <= 0x1faff) // Emoji 主区（含 💭）
+  ) {
+    return 2;
+  }
+  if (
+    cp >= 0x1100 &&
+    (cp <= 0x115f ||
+      (cp >= 0x2e80 && cp <= 0x303e) ||
+      (cp >= 0x3041 && cp <= 0xa4cf) ||
+      (cp >= 0xac00 && cp <= 0xd7a3) ||
+      (cp >= 0xf900 && cp <= 0xfaff) ||
+      (cp >= 0xfe10 && cp <= 0xfe6f) ||
+      (cp >= 0xff00 && cp <= 0xff60) ||
+      (cp >= 0xffe0 && cp <= 0xffe6) ||
+      (cp >= 0x20000 && cp <= 0x3fffd))
+  ) {
+    return 2;
+  }
+  return 1;
+}
+
+/** 一段文本的显示宽度（按 charWidth 累加；不破坏 surrogate pair）。 */
+export function displayWidth(text: string): number {
+  let w = 0;
+  for (const ch of text) {
+    w += charWidth(ch.codePointAt(0) ?? 0);
+  }
+  return w;
+}
+
+/**
+ * 标准化流式文本：CRLF/CR → LF、剥离 ANSI、收敛尾部多余空行。
+ */
+export function normalizeLiveText(text: string): string {
+  return text
+    .replace(/\r\n?/g, '\n')
+    .replace(ANSI_RE, '')
+    .replace(/\n+$/g, '');
+}
+
+/**
+ * 取**前缀**：保留从头开始、显示宽度 ≤ maxWidth 的最长前缀（不破坏 surrogate pair）。
+ * 用于状态行的单行宽度钳制（保住最重要的行首 glyph/阶段，多余的尾部丢弃）。
+ */
+export function clampWidthStart(text: string, maxWidth: number): string {
+  if (maxWidth <= 0) return '';
+  let w = 0;
+  let out = '';
+  for (const ch of text) {
+    const cw = charWidth(ch.codePointAt(0) ?? 0);
+    if (w + cw > maxWidth) break;
+    out += ch;
+    w += cw;
+  }
+  return out;
+}
+
+/**
+ * 把（可能多行的）流式文本硬换行成**显示行数组**，每行显示宽度 ≤ maxWidth（满足 INV-1）。
+ *
+ * 规则：
+ *   - 先按原始 `\n` 切段落（保留空行 → 输出空字符串行）。
+ *   - 段落内贪心累加：超过 maxWidth 时，优先在**最近一个空格**处断行（word-aware，
+ *     英文不切断单词）；没有空格（如中文）则按字符硬断。
+ *   - 全程按 charWidth（CJK/全角/emoji=2）计宽，绝不按 length。
+ *
+ * 这是"打字机多行"的核心：reasoning / 答案的长文本在这里被切成等宽窄行，
+ * 再由 LiveArea 取尾部最近 N 行（满足 INV-2）。
+ *
+ * 导出供单测断言。
+ */
+export function wrapToDisplayLines(text: string, maxWidth: number): string[] {
+  if (maxWidth <= 0) return [];
+  const normalized = normalizeLiveText(text);
+  const out: string[] = [];
+
+  for (const para of normalized.split('\n')) {
+    if (para.length === 0) {
+      out.push('');
+      continue;
+    }
+    let line = '';
+    let lineWidth = 0;
+    let lastSpace = -1; // line 内最近一个空格的下标（断行机会）
+
+    for (const ch of para) {
+      const cw = charWidth(ch.codePointAt(0) ?? 0);
+      // 超宽且当前行非空 → 先断行再放入 ch
+      if (lineWidth + cw > maxWidth && line.length > 0) {
+        if (lastSpace >= 0 && lastSpace < line.length - 1) {
+          // 在最近空格处断：head 不含该空格，余下部分（不含空格）顺延到下一行
+          const head = line.slice(0, lastSpace);
+          const rest = line.slice(lastSpace + 1);
+          out.push(head);
+          line = rest;
+          lineWidth = displayWidth(rest);
+        } else {
+          out.push(line);
+          line = '';
+          lineWidth = 0;
+        }
+        lastSpace = -1;
+      }
+      line += ch;
+      lineWidth += cw;
+      if (ch === ' ') lastSpace = line.length - 1;
+    }
+    out.push(line);
+  }
+
+  return out;
+}

package/src/ui/markdown.ts

@@ -0,0 +1,230 @@
+/**
+ * ============================================================
+ *  src/ui/markdown.ts —— assistant 最终答案的 markdown → 终端展示行
+ * ------------------------------------------------------------
+ *  借鉴 Claude Code 的管线（marked lexer 分词 + 自研 token→ANSI 格式化），
+ *  按 minimal-agent 减法原则收敛。核心裁决：
+ *
+ *  ★ 代码块「零装饰」（复制即用的全部保障）：
+ *    `code` token 的每一行 = 原文逐字节输出——无边框、无背景、无缩进、无前缀、
+ *    不按宽度重排；渲染层配 wrap='end'（Ink 原样输出，不注入换行），超宽交给
+ *    终端软换行（现代终端复制时还原为整行）。任何"美化"都会污染复制。
+ *
+ *  ★ 删除线主动禁用：模型常用 ~xxx~ 表示"约等于"，渲染成删除线是灾难
+ *    （捐赠方同款裁决），del token 原样输出 raw。
+ *
+ *  ★ 只在 <Static> commit 时调用（write-once，每条消息一生解析一次，
+ *    <1ms 无重解析压力）；live 流式区不跑 markdown。
+ *
+ *  已知取舍：
+ *    - dim 与 bold 的 SGR 关闭码同为 22，嵌套会提前关闭外层——本文件不在
+ *      bold 内嵌 dim（捐赠方同样接受此约束）。
+ *    - 超过终端宽度的 code 行交终端软换行显示（视觉上折行、复制仍是整行）；
+ *      TODO：后续可为超宽 code 提供 /show 式展开。
+ *    - 表格第一期不做 flexbox 对齐，token.raw 原样透传（终端裸文本可读）；
+ *      TODO：需要时参照捐赠方 MarkdownTable 组件。
+ * ============================================================
+ */
+
+import { lexer, type Token, type Tokens } from 'marked';
+import { figures } from './figures.js';
+
+// ---------------- ANSI 内联样式（手写 SGR，不引 chalk） ----------------
+// Ink 的 Text 渲染管线（wrap-ansi / cli-truncate）是 ANSI-aware 的，
+// 字符串内嵌 SGR 与 wrap='end' 兼容（捐赠方同款做法）。
+const sgr = (open: number, close: number) => (s: string) => `\x1b[${open}m${s}\x1b[${close}m`;
+const bold = sgr(1, 22);
+const italic = sgr(3, 23);
+const underline = sgr(4, 24);
+const dim = sgr(2, 22);
+const cyan = sgr(36, 39);
+
+export type MdLineKind =
+  /** 普通文字行（可含 ANSI 内联样式；渲染层加 ⏺/缩进前缀） */
+  | 'prose'
+  /** 代码行 = 原文逐字节（渲染层零前缀零染色，复制安全断言点） */
+  | 'code'
+  /** ``` 围栏行（渲染层染 dim，与代码本体区分） */
+  | 'fence';
+
+export interface MdLine {
+  text: string;
+  kind: MdLineKind;
+}
+
+/**
+ * 快判：文本里没有任何 markdown 语法特征 → 跳过 lexer，直接按 \n 切 prose
+ * （旧行为快路径；也避免纯中文叙述被 lexer 意外重排）。
+ */
+export function looksLikeMarkdown(text: string): boolean {
+  return (
+    /(^|\n)\s{0,3}(#{1,6}\s|```|>\s|[-*+]\s|\d+\.\s|(-{3,}|\*{3,})\s*(\n|$))/.test(text) || // 块级：标题/围栏/引用/列表/hr
+    /`[^`\n]+`|\*\*[^*\n]+\*\*|\[[^\]\n]+\]\([^)\n]+\)/.test(text) // 行内：codespan/加粗/链接
+  );
+}
+
+/**
+ * marked tokenizer 对 codespan/escape/text 做 HTML 实体转义
+ * （`a && b` → 'a &amp;&amp; b'）——终端不是 HTML，必须还原。
+ * 注意 &amp; 最后替换（否则 &amp;lt; 会被二次解码）。
+ */
+export function unescapeEntities(text: string): string {
+  return text
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
+/** 行内 tokens → 单条含 ANSI 的字符串。 */
+export function formatInlineTokens(tokens: Token[]): string {
+  let out = '';
+  for (const token of tokens) {
+    switch (token.type) {
+      case 'strong':
+        out += bold(formatInlineTokens((token as Tokens.Strong).tokens));
+        break;
+      case 'em':
+        out += italic(formatInlineTokens((token as Tokens.Em).tokens));
+        break;
+      case 'codespan':
+        out += cyan(unescapeEntities((token as Tokens.Codespan).text));
+        break;
+      case 'del':
+        // 删除线禁用：~xxx~ 常是"约等于"，原样输出
+        out += (token as Tokens.Del).raw;
+        break;
+      case 'link': {
+        const link = token as Tokens.Link;
+        const label = link.tokens ? formatInlineTokens(link.tokens) : link.text;
+        out += label === link.href ? label : `${label} ${dim(`(${link.href})`)}`;
+        break;
+      }
+      case 'image':
+        out += `[图: ${(token as Tokens.Image).text}]`;
+        break;
+      case 'br':
+        out += '\n';
+        break;
+      case 'escape':
+        out += unescapeEntities((token as Tokens.Escape).text);
+        break;
+      case 'text': {
+        const t = token as Tokens.Text;
+        out += t.tokens ? formatInlineTokens(t.tokens) : unescapeEntities(t.text);
+        break;
+      }
+      default:
+        out += 'raw' in token ? (token as { raw: string }).raw : '';
+        break;
+    }
+  }
+  return out;
+}
+
+/** 把（可能含 ANSI 的）多行字符串切成 prose 行。 */
+function proseLines(text: string): MdLine[] {
+  return text.split('\n').map((line) => ({ text: line, kind: 'prose' as const }));
+}
+
+/** 单个块级 token → 展示行（导出供单测逐 token 断言）。 */
+export function formatBlockToken(token: Token): MdLine[] {
+  switch (token.type) {
+    case 'code': {
+      // ★ 复制安全核心路径：代码行 = token.text 逐字节，围栏行单独标 kind
+      const code = token as Tokens.Code;
+      return [
+        { text: `\`\`\`${code.lang ?? ''}`, kind: 'fence' },
+        ...code.text.split('\n').map((line) => ({ text: line, kind: 'code' as const })),
+        { text: '```', kind: 'fence' },
+      ];
+    }
+    case 'heading': {
+      const heading = token as Tokens.Heading;
+      const inner = formatInlineTokens(heading.tokens);
+      return [{ text: heading.depth === 1 ? bold(underline(inner)) : bold(inner), kind: 'prose' }];
+    }
+    case 'paragraph':
+      return proseLines(formatInlineTokens((token as Tokens.Paragraph).tokens));
+    case 'list': {
+      const list = token as Tokens.List;
+      const lines: MdLine[] = [];
+      const start = typeof list.start === 'number' ? list.start : 1;
+      list.items.forEach((item, i) => {
+        const bullet = list.ordered ? `${start + i}. ` : '- ';
+        const pad = ' '.repeat(bullet.length);
+        let firstLineDone = false;
+        for (const sub of item.tokens) {
+          if (sub.type === 'code') {
+            // 列表内代码块：零装饰优先于列表对齐（不缩进，保住复制安全）
+            lines.push(...formatBlockToken(sub));
+            continue;
+          }
+          if (sub.type === 'list') {
+            // 嵌套列表：整体缩进对齐父 bullet（不走 firstLine 逻辑，避免双重缩进）
+            lines.push(
+              ...formatBlockToken(sub).map((l) =>
+                l.kind === 'prose' ? { ...l, text: `${pad}${l.text}` } : l,
+              ),
+            );
+            continue;
+          }
+          const subLines = proseLines(
+            sub.type === 'text' || sub.type === 'paragraph'
+              ? formatInlineTokens((sub as Tokens.Text).tokens ?? [sub])
+              : 'raw' in sub
+                ? (sub as { raw: string }).raw
+                : '',
+          );
+          for (const l of subLines) {
+            if (l.kind !== 'prose') {
+              lines.push(l);
+            } else if (!firstLineDone) {
+              lines.push({ text: `${bullet}${l.text}`, kind: 'prose' });
+              firstLineDone = true;
+            } else {
+              lines.push({ text: `${pad}${l.text}`, kind: 'prose' });
+            }
+          }
+        }
+        if (!firstLineDone) lines.push({ text: bullet.trimEnd(), kind: 'prose' });
+      });
+      return lines;
+    }
+    case 'blockquote': {
+      const quote = token as Tokens.Blockquote;
+      const inner = quote.tokens.flatMap(formatBlockToken);
+      // 引用竖条只加在 prose 行；引用内代码块保持零装饰
+      return inner.map((l) =>
+        l.kind === 'prose' ? { ...l, text: `${dim(`${figures.quote} `)}${l.text}` } : l,
+      );
+    }
+    case 'space':
+      return [{ text: '', kind: 'prose' }];
+    case 'hr':
+      return [{ text: dim(figures.hr.repeat(20)), kind: 'prose' }];
+    case 'table':
+      // TODO：flexbox 对齐表格（捐赠方 MarkdownTable 模式）；第一期原样透传
+      return proseLines((token as Tokens.Table).raw.trimEnd());
+    default:
+      return 'raw' in token
+        ? proseLines((token as { raw: string }).raw.replace(/\n+$/, ''))
+        : [];
+  }
+}
+
+/**
+ * 主入口：assistant 正文 → 展示行。
+ * 纯文本走快路径（与旧渲染逐行一致）；lexer 意外抛错时兜底回退原文
+ * （模型输出任意性防御——格式化是锦上添花，绝不能让渲染崩掉消息）。
+ */
+export function renderMarkdownLines(src: string): MdLine[] {
+  if (src.length === 0) return [];
+  if (!looksLikeMarkdown(src)) return proseLines(src);
+  try {
+    return lexer(src).flatMap(formatBlockToken);
+  } catch {
+    return proseLines(src);
+  }
+}

package/src/ui/textBuffer.ts

@@ -0,0 +1,239 @@
+/**
+ * ============================================================
+ *  src/ui/textBuffer.ts —— 输入框文本缓冲（纯逻辑，无 React）
+ * ------------------------------------------------------------
+ *  把"光标 + 文本"建模成一对值 { text, cursor }：
+ *    - text 是 user-perceived 字符串（可含 \n，多行也行）
+ *    - cursor 是 **code-point 偏移**（非 UTF-16），保证不会切坏 emoji / 中日韩
+ *
+ *  所有 op 都是纯函数：返回新的 { text, cursor }，不改入参。
+ *  这样 React 端用 useState 包一下就行；测试也直接对纯函数断言、零依赖。
+ *
+ *  支持的操作：
+ *    - 插入：insert / setText / clear
+ *    - 删除：deleteBefore（Backspace）/ deleteAt（Delete）
+ *           / killToLineStart（Ctrl+U）/ killToLineEnd（Ctrl+K）
+ *           / deleteWordBefore（Ctrl+W）
+ *    - 移动：moveLeft / moveRight / moveWordLeft / moveWordRight
+ *           / moveLineStart / moveLineEnd
+ *           / moveBufferStart / moveBufferEnd
+ *           / moveUp / moveDown（按逻辑行，跨 \n，保持列位）
+ *
+ *  词边界定义（够用即可，不学完整 vim/emacs）：
+ *    [A-Za-z0-9_] 视为 word char；其他（空格、标点、CJK、emoji）都是 non-word。
+ *    word-jump 的语义对齐多数 emacs：先吃当前侧的 non-word，再吃 word。
+ * ============================================================
+ */
+
+export interface BufferState {
+  /** 用户可见文本（可含 \n） */
+  text: string;
+  /** 光标位置：code-point 偏移，范围 [0, codePointLength] */
+  cursor: number;
+}
+
+export const EMPTY_BUFFER: BufferState = { text: '', cursor: 0 };
+
+// ---------- 工具：code-point 视角操作字符串 ----------
+
+/** 把字符串拆成 code-point 数组（Array.from 自动处理 surrogate pair） */
+function toCps(s: string): string[] {
+  return Array.from(s);
+}
+
+function fromCps(cps: string[]): string {
+  return cps.join('');
+}
+
+function isWordChar(c: string | undefined): boolean {
+  if (!c) return false;
+  return /[A-Za-z0-9_]/.test(c);
+}
+
+/** 给定 code-point 数组与一个偏移，返回所在逻辑行的起点（指向 \n 之后或 0） */
+function findLineStart(cps: string[], idx: number): number {
+  let i = idx;
+  while (i > 0 && cps[i - 1] !== '\n') i--;
+  return i;
+}
+
+/** 给定 code-point 数组与一个偏移，返回所在逻辑行的终点（指向 \n 或末尾） */
+function findLineEnd(cps: string[], idx: number): number {
+  let i = idx;
+  while (i < cps.length && cps[i] !== '\n') i++;
+  return i;
+}
+
+/** 把 cursor 钳制到合法范围 */
+function clamp(cps: string[], idx: number): number {
+  return Math.max(0, Math.min(cps.length, idx));
+}
+
+// ---------- 插入 ----------
+
+export function bufInsert(s: BufferState, content: string): BufferState {
+  if (content.length === 0) return s;
+  const cps = toCps(s.text);
+  const ins = toCps(content);
+  cps.splice(s.cursor, 0, ...ins);
+  return { text: fromCps(cps), cursor: s.cursor + ins.length };
+}
+
+export function bufSetText(text: string): BufferState {
+  return { text, cursor: toCps(text).length };
+}
+
+export function bufClear(): BufferState {
+  return EMPTY_BUFFER;
+}
+
+// ---------- 删除 ----------
+
+export function bufDeleteBefore(s: BufferState): BufferState {
+  if (s.cursor === 0) return s;
+  const cps = toCps(s.text);
+  cps.splice(s.cursor - 1, 1);
+  return { text: fromCps(cps), cursor: s.cursor - 1 };
+}
+
+/**
+ * Ctrl+W / M-DEL：先吃光标左侧的非词字符（空格 / 标点），再吃前一个词。
+ * 例：光标贴在 "world" 后 → 删 'world'，留 "hello   "。
+ *     光标在 "hello   " 之后 → 先吃 3 空格再吃 "hello"，留空。
+ */
+export function bufDeleteWordBefore(s: BufferState): BufferState {
+  if (s.cursor === 0) return s;
+  const cps = toCps(s.text);
+  let i = s.cursor;
+  while (i > 0 && !isWordChar(cps[i - 1])) i--;
+  while (i > 0 && isWordChar(cps[i - 1])) i--;
+  cps.splice(i, s.cursor - i);
+  return { text: fromCps(cps), cursor: i };
+}
+
+/** Ctrl+U：从光标删到当前逻辑行行首 */
+export function bufKillToLineStart(s: BufferState): BufferState {
+  const cps = toCps(s.text);
+  const lineStart = findLineStart(cps, s.cursor);
+  if (lineStart === s.cursor) return s;
+  cps.splice(lineStart, s.cursor - lineStart);
+  return { text: fromCps(cps), cursor: lineStart };
+}
+
+/** Ctrl+K：从光标删到当前逻辑行行末（不删 \n 自身） */
+export function bufKillToLineEnd(s: BufferState): BufferState {
+  const cps = toCps(s.text);
+  const lineEnd = findLineEnd(cps, s.cursor);
+  if (lineEnd === s.cursor) return s;
+  cps.splice(s.cursor, lineEnd - s.cursor);
+  return { text: fromCps(cps), cursor: s.cursor };
+}
+
+// ---------- 移动 ----------
+
+export function bufMoveLeft(s: BufferState): BufferState {
+  return { text: s.text, cursor: Math.max(0, s.cursor - 1) };
+}
+
+export function bufMoveRight(s: BufferState): BufferState {
+  const len = toCps(s.text).length;
+  return { text: s.text, cursor: Math.min(len, s.cursor + 1) };
+}
+
+export function bufMoveWordLeft(s: BufferState): BufferState {
+  const cps = toCps(s.text);
+  let i = s.cursor;
+  while (i > 0 && !isWordChar(cps[i - 1])) i--;
+  while (i > 0 && isWordChar(cps[i - 1])) i--;
+  return { text: s.text, cursor: i };
+}
+
+export function bufMoveWordRight(s: BufferState): BufferState {
+  const cps = toCps(s.text);
+  let i = s.cursor;
+  while (i < cps.length && !isWordChar(cps[i])) i++;
+  while (i < cps.length && isWordChar(cps[i])) i++;
+  return { text: s.text, cursor: i };
+}
+
+export function bufMoveLineStart(s: BufferState): BufferState {
+  const cps = toCps(s.text);
+  return { text: s.text, cursor: findLineStart(cps, s.cursor) };
+}
+
+export function bufMoveLineEnd(s: BufferState): BufferState {
+  const cps = toCps(s.text);
+  return { text: s.text, cursor: findLineEnd(cps, s.cursor) };
+}
+
+export function bufMoveBufferStart(s: BufferState): BufferState {
+  return { text: s.text, cursor: 0 };
+}
+
+export function bufMoveBufferEnd(s: BufferState): BufferState {
+  return { text: s.text, cursor: toCps(s.text).length };
+}
+
+/** ↑：上移一个逻辑行，保留列位（目标行短就贴行末） */
+export function bufMoveUp(s: BufferState): BufferState {
+  const cps = toCps(s.text);
+  const lineStart = findLineStart(cps, s.cursor);
+  if (lineStart === 0) return s; // 已在首行
+  const prevLineEnd = lineStart - 1; // 指向上一行末尾的 \n
+  const prevLineStart = findLineStart(cps, prevLineEnd);
+  const col = s.cursor - lineStart;
+  const prevLineLen = prevLineEnd - prevLineStart;
+  return { text: s.text, cursor: prevLineStart + Math.min(col, prevLineLen) };
+}
+
+/** ↓：下移一个逻辑行，保留列位 */
+export function bufMoveDown(s: BufferState): BufferState {
+  const cps = toCps(s.text);
+  const lineStart = findLineStart(cps, s.cursor);
+  const lineEnd = findLineEnd(cps, s.cursor);
+  if (lineEnd === cps.length) return s; // 已在末行
+  const nextLineStart = lineEnd + 1;
+  const nextLineEnd = findLineEnd(cps, nextLineStart);
+  const col = s.cursor - lineStart;
+  const nextLineLen = nextLineEnd - nextLineStart;
+  return { text: s.text, cursor: nextLineStart + Math.min(col, nextLineLen) };
+}
+
+// ---------- 渲染辅助：把 text 切成 lines + 算光标行列 ----------
+
+export interface BufferLayout {
+  /** 逻辑行（按 \n 分割），不含 \n 自身 */
+  lines: string[];
+  /** 光标所在的行号（0-based） */
+  cursorRow: number;
+  /** 光标在所在行的列号（code-point 偏移，0-based） */
+  cursorCol: number;
+}
+
+/**
+ * 给定一个 BufferState，算出它的可视布局。
+ * 渲染端拿到 lines + cursorRow/Col 就能把光标绘制在正确位置。
+ */
+export function layoutBuffer(s: BufferState): BufferLayout {
+  const cps = toCps(s.text);
+  const cursor = clamp(cps, s.cursor);
+  const lineStart = findLineStart(cps, cursor);
+  // 把 cps 按 \n 分行（保持 code-point 视角，避免 surrogate pair 撕裂）
+  const lines: string[] = [];
+  let buf: string[] = [];
+  let cursorRow = 0;
+  let charCount = 0;
+  for (const ch of cps) {
+    if (ch === '\n') {
+      lines.push(fromCps(buf));
+      buf = [];
+      if (charCount < lineStart) cursorRow++;
+    } else {
+      buf.push(ch);
+    }
+    charCount++;
+  }
+  lines.push(fromCps(buf));
+  const cursorCol = cursor - lineStart;
+  return { lines, cursorRow, cursorCol };
+}

package/src/ui/theme.ts

@@ -0,0 +1,35 @@
+/**
+ * ============================================================
+ *  src/ui/theme.ts —— TUI 语义色板（单一出处）
+ * ------------------------------------------------------------
+ *  借鉴 Claude Code 的语义化主题键思想（utils/theme.ts），按 minimal-agent
+ *  减法原则收敛为 7 个键：组件里写"这段文字是什么角色"（theme.subtle），
+ *  不写"这段文字是什么颜色"（'gray'）——改配色只动这一个文件。
+ *
+ *  值是 Ink <Text color=...> 的合法取值；undefined = 终端默认前景色。
+ *  事实调色板（与重构前完全一致，机械替换零行为变化）：
+ *    - 层次靠三级区分：subtle+dimColor（次要：思维链/工具/进度）
+ *      ↔ answer 默认亮色（主角：最终答案）↔ user/plugin bold（状态行）。
+ * ============================================================
+ */
+
+export const theme = {
+  /** 用户输入 / banner / 状态行 spinner / 输入框边框 */
+  user: 'cyan',
+  /** 最终答案正文 —— undefined = 终端默认亮色（答案是主角，不染色） */
+  answer: undefined,
+  /** ⏺ 答案锚点（配 bold） */
+  anchor: 'green',
+  /** 次要信息：思维链 / 工具结果 / turn 横线 / live 过程区（配 dimColor） */
+  subtle: 'gray',
+  /** 暂态提示 / tool_calls 摘要 / 中断提示 */
+  warning: 'yellow',
+  /** 永久错误 */
+  error: 'red',
+  /** 健康/正常状态（StatusLine 用量比率等） */
+  ok: 'green',
+  /** compacting 状态 / 插件进度 / reverse-search */
+  plugin: 'magenta',
+} as const;
+
+export type ThemeColor = (typeof theme)[keyof typeof theme];