OpenClaw Terminal 模块超深度专业级分析

---

一、模块定位

1.1 业务职责、功能定位、作用范围

Terminal 模块 是 OpenClaw CLI 系统的终端输出基础设施层，承担以下核心业务职责：

职责领域	说明
终端文本渲染	ANSI 转义序列处理、Unicode 字素宽度计算、全角/半角感知的文本对齐与换行
安全防护	日志注入防御（CWE-117）、管道断裂容错、不可信文本消毒
视觉主题系统	统一调色板（Lobster Palette）、富文本/纯文本双模式适配
表格渲染引擎	ANSI 感知的自动换行、flex 弹性列宽、Unicode/ASCII 边框自适应
交互提示组件	选项卡式选择器、通知卡片（Note）输出
终端状态管理	进度行注册/清理、终端状态恢复（raw mode、光标、鼠标追踪）
超链接支持	OSC-8 终端超链接生成与回退策略
文档链接	自动拼接文档站 URL 并格式化为可点击终端链接

作用范围：该模块为 CLI 层的所有输出场景提供底层能力，不涉及网络通信、数据持久化或业务逻辑。

1.2 在系统中的位置

┌─────────────────────────────────────────────────────────┐
│                   OpenClaw System                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │  CLI入口  │→│ 命令处理  │→│ 业务逻辑  │              │
│  └──────────┘  └────┬─────┘  └──────────┘              │
│                     │                                    │
│              ┌──────▼──────┐                             │
│              │  输出格式化  │ ←── 调用 terminal 模块      │
│              └──────┬──────┘                             │
│              ┌──────▼──────────────────────────┐         │
│              │     terminal 模块（本模块）       │         │
│              │  ┌─────┐ ┌──────┐ ┌─────┐       │         │
│              │  │ansi │ │theme │ │table│       │         │
│              │  └─────┘ └──────┘ └─────┘       │         │
│              │  ┌─────┐ ┌──────┐ ┌─────┐       │         │
│              │  │note │ │stream│ │restore│     │         │
│              │  └─────┘ └──────┘ └─────┘       │         │
│              └──────────────────────────────────┘         │
│              ┌──────▼──────┐                             │
│              │  终端/stdout  │                             │
│              └─────────────┘                             │
└─────────────────────────────────────────────────────────┘

层级定位：Terminal 模块处于 表示层（Presentation Layer） 的最底部，直接与终端 I/O 交互。它是 CLI 用户体验的基石——所有用户可见的输出均经过此模块处理或受其能力约束。

1.3 核心业务价值

1. 零乱码保证：通过字素级宽度计算和 ANSI 感知换行，确保 CJK 字符、Emoji、组合字符在终端中不会导致表格错位或文本截断
2. 安全合规：sanitizeForLog 和 sanitizeTerminalText 阻止日志伪造攻击，符合 CWE-117 规范
3. 健壮性：SafeStreamWriter 处理 EPIPE 信号，避免 CLI 工具在管道场景下崩溃
4. 一致的品牌体验：Lobster Palette (#FF5A2D 主色) 在所有终端输出中保持视觉一致性
5. 终端适配：Windows/macOS/Linux 边框自动选择、TTY 检测、NO_COLOR/FORCE_COLOR 标准支持

---

二、模块整体结构

2.1 类结构、接口定义、依赖注入关系

本模块采用函数式+类型定义的 TypeScript 设计，无 class 继承体系。所有核心逻辑通过纯函数和工厂函数实现。

类型定义体系

┌─────────────────────────────────────────────────────────┐
│                    类型定义层                            │
├─────────────────────────────────────────────────────────┤
│  Align = "left" | "right" | "center"                    │
│  TableColumn { key, header, align?, minWidth?,          │
│                maxWidth?, flex? }                        │
│  RenderTableOptions { columns, rows, width?,            │
│                       padding?, border? }                │
│  SafeStreamWriterOptions { beforeWrite?,                │
│                            onBrokenPipe? }              │
│  SafeStreamWriter { write, writeLine, reset,            │
│                     isClosed }                          │
│  RestoreTerminalStateOptions { resumeStdin?,            │
│                                resumeStdinIfPaused? }   │
└─────────────────────────────────────────────────────────┘

依赖注入关系

palette.ts ──→ theme.ts ──→ prompt-style.ts ──→ prompt-select-styled.ts
                                     │
                                     └──→ health-style.ts

ansi.ts ──→ table.ts
       ──→ note.ts
       ──→ safe-text.ts

terminal-link.ts ──→ links.ts

stream-writer.ts (独立, 无上游依赖)

restore.ts ──→ progress-line.ts (依赖)

progress-line.ts (独立, 被依赖)

note.ts ──→ ansi.ts
       ──→ prompt-style.ts
       ──→ ../shared/string-coerce.js
       ──→ @clack/prompts (外部)

2.2 核心方法清单与作用

文件	导出函数/常量	作用
ansi.ts	stripAnsi(input)	剥离所有 ANSI CSI 和 OSC-8 序列
	splitGraphemes(input)	将字符串拆分为 Unicode 字素段
	sanitizeForLog(v)	安全化日志文本（CWE-117）
	visibleWidth(input)	计算字符串的终端可见宽度
stream-writer.ts	createSafeStreamWriter(opts)	创建 EPIPE 安全的流写入器
restore.ts	restoreTerminalState(reason?, opts?)	恢复终端到正常状态
note.ts	note(message, title?)	输出格式化通知卡片
	wrapNoteMessage(message, opts?)	智能换行通知文本
table.ts	renderTable(opts)	渲染 ANSI 终端表格
	getTerminalTableWidth(min, fallback)	获取终端表格可用宽度
theme.ts	theme (对象)	导出颜色主题函数集
	isRich()	判断是否启用富文本模式
	colorize(rich, color, value)	条件性着色
palette.ts	LOBSTER_PALETTE	Lobster 调色板常量
prompt-style.ts	stylePromptMessage/Title/Hint	提示文本样式化
prompt-select-styled.ts	selectStyled<T>(params)	带样式的选项选择器
health-style.ts	styleHealthChannelLine(line, rich)	健康检查行着色
terminal-link.ts	formatTerminalLink(label, url, opts?)	生成 OSC-8 超链接
links.ts	formatDocsLink(path, label?, opts?)	生成文档站链接
safe-text.ts	sanitizeTerminalText(input)	单行终端文本消毒
progress-line.ts	registerActiveProgressLine(stream)	注册活动进度行
	clearActiveProgressLine()	清除活动进度行
	unregisterActiveProgressLine(stream?)	注销进度行

2.3 内部调用关系

调用链全景

外部调用者 (CLI 命令层)
  │
  ├──→ note(message, title)
  │      ├──→ isSuppressedByEnv(process.env.OPENCLAW_SUPPRESS_NOTES)
  │      ├──→ wrapNoteMessage(message, opts)
  │      │      ├──→ process.stdout.columns
  │      │      ├──→ wrapLine(line, maxWidth) × N
  │      │      │      ├──→ line.match(/^(\s*)([-*\u2022]\s+)?(.*)$/)
  │      │      │      ├──→ content.split(/\s+/)
  │      │      │      ├──→ visibleWidth(word) ←── ansi.ts
  │      │      │      │      ├──→ stripAnsi(input)
  │      │      │      │      ├──→ splitGraphemes(input)
  │      │      │      │      └──→ graphemeWidth(grapheme)
  │      │      │      └──→ isCopySensitiveToken(word)
  │      │      └──→ lines.join("\n")
  │      ├──→ stylePromptTitle(title) ←── prompt-style.ts ←── theme.ts
  │      └──→ clackNote(wrappedMessage, styledTitle) ←── @clack/prompts
  │
  ├──→ renderTable(opts)
  │      ├──→ displayString(value) ←── ../utils.js
  │      ├──→ resolveDefaultBorder(platform, env)
  │      ├──→ visibleWidth(text) ←── ansi.ts
  │      ├──→ 列宽计算 & flex 弹性分配
  │      ├──→ wrapLine(text, width)  ←── 内部 ANSI 感知换行器
  │      │      └──→ splitGraphemes(text) ←── ansi.ts
  │      ├──→ padCell(text, width, align)
  │      └──→ Unicode/ASCII 边框渲染
  │
  ├──→ createSafeStreamWriter(opts)
  │      └──→ 返回 { write, writeLine, reset, isClosed }
  │
  ├──→ restoreTerminalState(reason, opts)
  │      ├──→ clearActiveProgressLine() ←── progress-line.ts
  │      ├──→ stdin.setRawMode(false)
  │      ├──→ stdin.resume() (条件)
  │      └──→ process.stdout.write(RESET_SEQUENCE)
  │
  └──→ formatDocsLink(path, label, opts)
         ├──→ resolveDocsRoot() → "https://docs.openclaw.ai"
         └──→ formatTerminalLink(label, url, opts) ←── terminal-link.ts
                 └──→ process.stdout.isTTY (判断是否生成 OSC-8)

2.4 数据流入流出方式

函数	输入	输出	数据流特征
stripAnsi	任意字符串	纯文本字符串	同步纯函数
visibleWidth	任意字符串	数字	同步纯函数
renderTable	TableColumn[] + Row[]	渲染后的字符串	同步纯函数，副作用在调用方
createSafeStreamWriter	选项对象	StreamWriter 对象	工厂函数，有状态闭包
note	消息字符串 + 标题	void (副作用: stdout)	副作用函数
restoreTerminalState	原因字符串 + 选项	void (副作用: stdin/stdout)	副作用函数
formatTerminalLink	标签+URL+选项	字符串	同步纯函数

---

三、核心业务逻辑深度解析

3.1 ansi.ts

3.1 ansi.ts — ANSI 处理与字素宽度引擎

完整执行流程

输入字符串
  │
  ▼
┌─────────────────────┐
│  正则匹配池初始化     │
│  ANSI_CSI_PATTERN    │  ESC [ <params> <final>
│  OSC8_PATTERN        │  ESC ] 8 ; ; url ST
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  Intl.Segmenter      │  ← 浏览器/Node 14+ 特性
│  可用性检测          │  降级策略: Array.from()
└─────────┬───────────┘
          │
          ▼
┌─── stripAnsi(input) ───┐
│  1. OSC8_REGEX 替换 "" │  ← 先移除 OSC-8 超链接
│  2. CSI_REGEX 替换 ""  │  ← 再移除所有 CSI 序列
│  3. 返回纯文本          │
└─────────────────────────┘

┌─── splitGraphemes(input) ──┐
│  空 → []                    │
│  Segmenter 可用:            │
│    Array.from(segmenter,    │
│      s => s.segment)        │
│  降级: Array.from(input)   │
└─────────────────────────────┘

┌─── sanitizeForLog(v) ──────┐
│  1. stripAnsi(v)            │  ← 移除 ANSI 序列
│  2. for c in 0x00..0x1F:    │  ← 移除 C0 控制字符
│       replaceAll(CHR(c),"") │
│  3. replaceAll(0x7F, "")   │  ← 移除 DEL 字符
│  4. 返回安全字符串          │
└─────────────────────────────┘

┌─── visibleWidth(input) ────┐
│  1. stripAnsi(input)        │  ← 剥离 ANSI
│  2. splitGraphemes(result)  │  ← 字素拆分
│  3. reduce(sum, graphemeWidth)│
│       │                     │
│       ▼                     │
│  graphemeWidth(grapheme):  │
│    空 → 0                   │
│    Emoji → 2                │  ← Extended_Pictographic
│    遍历 chars:              │
│      ZeroWidth → skip      │  ← 组合用字符
│      FullWidth → 2         │  ← CJK/全角字符
│      可打印 → 1             │
│      不可打印 → 0           │
└─────────────────────────────┘

逐行解析

// 第1行：CSI 序列正则 — 匹配 ESC [ 后跟参数字节(0x20-0x3F)和终字节(0x40-0x7E)
// 覆盖范围：光标移动、擦除、SGR(颜色/样式)等所有 CSI 序列
const ANSI_CSI_PATTERN = "\\x1b\\[[\\x20-\\x3f]*[\\x40-\\x7e]";

// 第3行：OSC-8 超链接正则 — 匹配 ESC ] 8 ; ; URL ST 或空链接关闭
// 两种模式：带URL的 ESC]8;;url ESC\ 和关闭的 ESC]8;;ESC\
const OSC8_PATTERN = "\\x1b\\]8;;.*?\\x1b\\\\|\\x1b\\]8;;\\x1b\\\\";

// 第5-6行：编译正则对象，全局标志 "g" 用于 replace 全部替换
const ANSI_CSI_REGEX = new RegExp(ANSI_CSI_PATTERN, "g");
const OSC8_REGEX = new RegExp(OSC8_PATTERN, "g");

// 第8-10行：Intl.Segmenter 可用性检测
// 这是 ECMAScript Internationalization API 的字素分割器
// granularity: "grapheme" 表示按用户感知的字符单元分割
// 降级方案：不支持时设为 null，splitGraphemes 使用 Array.from
const graphemeSegmenter =
  typeof Intl !== "undefined" && "Segmenter" in Intl
    ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
    : null;

// 第12-14行：stripAnsi — 剥离 ANSI 序列
// 先替换 OSC-8（更复杂的结构），再替换 CSI
// 顺序重要：OSC-8 包含 ESC 字符，先处理避免 CSI 正则误匹配
export function stripAnsi(input: string): string {
  return input.replace(OSC8_REGEX, "").replace(ANSI_CSI_REGEX, "");
}

// 第16-27行：splitGraphemes — 字素级拆分
// 空输入直接返回空数组
// 有 Segmenter 时：segment() 返回迭代器，提取每个 segment
// 降级：Array.from() 按码点拆分（对 surrogate pair 正确，但对组合字符不正确）
export function splitGraphemes(input: string): string[] {
  if (!input) return [];
  if (!graphemeSegmenter) return Array.from(input);
  try {
    return Array.from(graphemeSegmenter.segment(input), (segment) => segment.segment);
  } catch {
    return Array.from(input);
  }
}

// 第29-37行：sanitizeForLog — CWE-117 日志安全化
// 设计意图：防止攻击者通过注入 ANSI 序列或控制字符伪造日志条目
// 步骤1: stripAnsi 移除所有终端控制序列
// 步骤2: 遍历 C0 控制字符区间(0x00-0x1F)，逐个移除
// 步骤3: 移除 DEL 字符(0x7F)
export function sanitizeForLog(v: string): string {
  let out = stripAnsi(v);
  for (let c = 0; c <= 0x1f; c++) {
    out = out.replaceAll(String.fromCharCode(c), "");
  }
  return out.replaceAll(String.fromCharCode(0x7f), "");
}

// 第39-49行：isZeroWidthCodePoint — 零宽字符判断
// 覆盖 Unicode 规范中的组合用标记区间：
// 0x0300-0x036F: 组合变音符 (Combining Diacritical Marks)
// 0x1AB0-0x1AFF: 组合变音符扩展
// 0x1DC0-0x1DFF: 组合变音符补充
// 0x20D0-0x20FF: 组合变音符符号
// 0xFE20-0xFE2F: 组合用半符号
// 0xFE00-0xFE0F: 变体选择符 (VS1-VS16)
// 0x200D: 零宽连接符 (ZWJ) — 用于 Emoji 组合（如 👨‍👩‍👧）
function isZeroWidthCodePoint(codePoint: number): boolean {
  return (
    (codePoint >= 0x0300 && codePoint <= 0x036f) ||
    (codePoint >= 0x1ab0 && codePoint <= 0x1aff) ||
    (codePoint >= 0x1dc0 && codePoint <= 0x1dff) ||
    (codePoint >= 0x20d0 && codePoint <= 0x20ff) ||
    (codePoint >= 0xfe20 && codePoint <= 0xfe2f) ||
    (codePoint >= 0xfe00 && codePoint <= 0xfe0f) ||
    codePoint === 0x200d
  );
}

// 第51-80行：isFullWidthCodePoint — 全角字符判断
// 基于 Unicode East Asian Width 标准
// 覆盖所有 CJK 区间、韩文、日文假名、全角拉丁等
// 0x1100-0x115F: 韩文 Jamo
// 0x2329/0x232A: 角括号
// 0x2E80-0x3247: CJK Radicals/Kanbun/Katakana
// 0x3250-0x4DBF: CJK 兼容
// 0x4E00-0xA4C6: CJK Unified Ideographs（汉字主区间）
// 0xAC00-0xD7A3: 韩文音节
// 0xFF01-0xFF60: 全角 ASCII
// 0x20000+: CJK Extension B 及以上
function isFullWidthCodePoint(codePoint: number): boolean {
  if (codePoint < 0x1100) return false;
  return (
    codePoint <= 0x115f ||
    codePoint === 0x2329 || codePoint === 0x232a ||
    (codePoint >= 0x2e80 && codePoint <= 0x3247 && codePoint !== 0x303f) ||
    (codePoint >= 0x3250 && codePoint <= 0x4dbf) ||
    (codePoint >= 0x4e00 && codePoint <= 0xa4c6) ||
    (codePoint >= 0xa960 && codePoint <= 0xa97c) ||
    (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
    (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
    (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
    (codePoint >= 0xfe30 && codePoint <= 0xfe6b) ||
    (codePoint >= 0xff01 && codePoint <= 0xff60) ||
    (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
    (codePoint >= 0x1aff0 && codePoint <= 0x1affe) ||
    (codePoint >= 0x1b000 && codePoint <= 0x1b2ff) ||
    (codePoint >= 0x1f200 && codePoint <= 0x1f251) ||
    (codePoint >= 0x20000 && codePoint <= 0x3fffd)
  );
}

// 第82行：Emoji 模式 — 使用 Unicode 属性转义
// Extended_Pictographic: 大多数 Emoji
// Regional_Indicator: 国旗 Emoji 的区域指示符
// \u20e3: 组合用封闭键帽 (keycap)
const emojiLikePattern = /[\p{Extended_Pictographic}\p{Regional_Indicator}\u20e3]/u;

// 第84-99行：graphemeWidth — 单个字素的终端宽度
// 设计意图：准确计算每个用户感知字符占用的终端列数
// Emoji 统一占2列（大多数终端的实际行为）
// 零宽字符跳过（组合用，不占列）
// 全角字符占2列
// 其他可打印字符占1列
// 完全不可见返回0
function graphemeWidth(grapheme: string): number {
  if (!grapheme) return 0;
  if (emojiLikePattern.test(grapheme)) return 2;
  let sawPrintable = false;
  for (const char of grapheme) {
    const codePoint = char.codePointAt(0);
    if (codePoint == null) continue;
    if (isZeroWidthCodePoint(codePoint)) continue;
    if (isFullWidthCodePoint(codePoint)) return 2;
    sawPrintable = true;
  }
  return sawPrintable ? 1 : 0;
}

// 第101-106行：visibleWidth — 字符串可见宽度计算
// 完整管线：剥离 ANSI → 字素拆分 → 逐个计算宽度 → 累加
export function visibleWidth(input: string): number {
  return splitGraphemes(stripAnsi(input)).reduce(
    (sum, grapheme) => sum + graphemeWidth(grapheme), 0
  );
}

3.2 stream-writer.ts

3.2 stream-writer.ts — 安全流写入器

完整执行流程

createSafeStreamWriter(options)
  │
  ├── 初始化闭包状态:
  │     closed = false   (管道是否已断开)
  │     notified = false  (是否已通知上层)
  │
  ├── 定义内部函数:
  │     noteBrokenPipe(err, stream)
  │       └── 首次调用 onBrokenPipe 回调, 之后静默
  │
  │     handleError(err, stream)
  │       ├── EPIPE/EIO → closed=true, noteBrokenPipe, return false
  │       └── 其他错误 → throw (不可恢复)
  │
  │     write(stream, text)
  │       ├── closed → return false
  │       ├── beforeWrite() → 捕获异常 → handleError
  │       └── stream.write(text) → 捕获异常 → handleError
  │
  │     writeLine(stream, text)
  │       └── write(stream, text + "\n")
  │
  └── 返回 { write, writeLine, reset, isClosed }
        reset(): closed=false, notified=false  (重置状态)
        isClosed(): 返回 closed  (查询状态)

逐行解析

// 第1-4行：选项类型定义
// beforeWrite: 每次写入前的钩子（用于进度行清理等）
// onBrokenPipe: 管道断裂时的回调通知
export type SafeStreamWriterOptions = {
  beforeWrite?: () => void;
  onBrokenPipe?: (err: NodeJS.ErrnoException, stream: NodeJS.WriteStream) => void;
};

// 第6-10行：写入器接口定义
// write/writeLine: 基本写入操作，返回是否成功
// reset: 重置关闭状态（用于重试场景）
// isClosed: 查询管道状态
export type SafeStreamWriter = {
  write: (stream: NodeJS.WriteStream, text: string) => boolean;
  writeLine: (stream: NodeJS.WriteStream, text: string) => boolean;
  reset: () => void;
  isClosed: () => boolean;
};

// 第12-15行：EPIPE 错误判断
// EPIPE: 管道读者已关闭（如 head/pipeline 场景）
// EIO: 某些平台在管道断裂时返回 I/O 错误
function isBrokenPipeError(err: unknown): err is NodeJS.ErrnoException {
  const code = (err as NodeJS.ErrnoException)?.code;
  return code === "EPIPE" || code === "EIO";
}

// 第17-63行：工厂函数 — 创建安全写入器
export function createSafeStreamWriter(options: SafeStreamWriterOptions = {}): SafeStreamWriter {
  // 闭包状态：closed 跟踪管道状态，notified 防止重复回调
  let closed = false;
  let notified = false;

  // 管道断裂通知：只通知一次（幂等性）
  const noteBrokenPipe = (err: NodeJS.ErrnoException, stream: NodeJS.WriteStream) => {
    if (notified) return;
    notified = true;
    options.onBrokenPipe?.(err, stream);
  };

  // 错误处理：EPIPE 优雅降级，其他错误向上抛出
  const handleError = (err: unknown, stream: NodeJS.WriteStream): boolean => {
    if (!isBrokenPipeError(err)) throw err;  // 不可恢复的错误
    closed = true;          // 标记管道已断开
    noteBrokenPipe(err, stream);  // 通知上层
    return false;           // 返回写入失败
  };

  // write: 核心写入方法
  const write = (stream: NodeJS.WriteStream, text: string): boolean => {
    if (closed) return false;  // 快速路径：已断开直接返回
    try {
      options.beforeWrite?.();  // 前置钩子（如清理进度行）
    } catch (err) {
      return handleError(err, process.stderr);  // 钩子异常按管道错误处理
    }
    try {
      stream.write(text);       // 实际写入
      return !closed;           // 写入成功但可能已被并发关闭
    } catch (err) {
      return handleError(err, stream);  // 写入异常处理
    }
  };

  // writeLine: 换行写入 — 在文本末尾追加 \n
  const writeLine = (stream: NodeJS.WriteStream, text: string): boolean =>
    write(stream, `${text}\n`);

  // 返回写入器对象
  return {
    write,
    writeLine,
    reset: () => { closed = false; notified = false; },  // 重置用于重试
    isClosed: () => closed,  // 状态查询
  };
}

3.3 restore.ts — 终端状态恢复

完整执行流程

![终端状态恢复流程图](diagrams/06-restore-flow.png)

restoreTerminalState(reason?, options?)
  │
  ├── 1. clearActiveProgressLine()
  │      └── 清除当前显示的进度行
  │
  ├── 2. stdin.setRawMode(false)
  │      └── 退出原始模式，恢复正常行缓冲
  │      └── 条件: stdin.isTTY && setRawMode 可用
  │
  ├── 3. stdin.resume() (可选)
  │      └── 恢复暂停的标准输入
  │      └── 条件: resumeStdin && stdin.isPaused()
  │
  └── 4. stdout.write(RESET_SEQUENCE)
         └── 发送完整终端重置序列:
             \x1b[0m     — SGR 重置（颜色/样式）
             \x1b[?25h   — 显示光标
             \x1b[?1000l — 禁用鼠标追踪(VT200)
             \x1b[?1002l — 禁用按钮事件追踪
             \x1b[?1003l — 禁用所有鼠标追踪
             \x1b[?1006l — 禁用 SGR 鼠标模式
             \x1b[?2004l — 禁用括号粘贴模式
             \x1b[<u     — 禁用焦点追踪(若支持)
             \x1b[>4;0m  — 禁用光标闪烁(若支持)

逐行解析

// 第1行：导入进度行清理函数
import { clearActiveProgressLine } from "./progress-line.js";

// 第3-4行：终端重置序列 — 一站式恢复所有可能的终端状态变更
// 这是最关键的常量：确保 CLI 异常退出后终端不会"乱掉"
const RESET_SEQUENCE =
  "\x1b[0m\x1b[?25h\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?2004l\x1b[<u\x1b[>4;0m";

// 第6-19行：选项类型 — 控制是否恢复 stdin
// resumeStdin 默认 false — 安全选择
// Docker TTY 场景下恢复 stdin 会导致容器进程不退出
type RestoreTerminalStateOptions = {
  resumeStdin?: boolean;
  resumeStdinIfPaused?: boolean;  // 更明确的别名
};

// 第21-30行：恢复失败报告函数
// 双重 try-catch：即使报告本身失败也不会崩溃
function reportRestoreFailure(scope: string, err: unknown, reason?: string): void {
  const suffix = reason ? ` (${reason})` : "";
  const message = `[terminal] restore ${scope} failed${suffix}: ${String(err)}`;
  try {
    process.stderr.write(`${message}\n`);  // 优先用 stderr
  } catch (writeErr) {
    console.error(`[terminal] restore reporting failed${suffix}: ${String(writeErr)}`);
  }
}

// 第32-66行：核心恢复函数
export function restoreTerminalState(reason?: string, options: RestoreTerminalStateOptions = {}): void {
  // 合并 resumeStdin 选项，默认 false
  const resumeStdin = options.resumeStdinIfPaused ?? options.resumeStdin ?? false;

  // 步骤1：清除活动进度行
  try {
    clearActiveProgressLine();
  } catch (err) {
    reportRestoreFailure("progress line", err, reason);
  }

  // 步骤2：退出 raw mode
  const stdin = process.stdin;
  if (stdin.isTTY && typeof stdin.setRawMode === "function") {
    try {
      stdin.setRawMode(false);  // 恢复正常行缓冲模式
    } catch (err) {
      reportRestoreFailure("raw mode", err, reason);
    }
    // 步骤3：恢复暂停的 stdin（可选）
    if (resumeStdin && typeof stdin.isPaused === "function" && stdin.isPaused()) {
      try {
        stdin.resume();  // 重新开始读取 stdin
      } catch (err) {
        reportRestoreFailure("stdin resume", err, reason);
      }
    }
  }

  // 步骤4：发送重置序列到 stdout
  if (process.stdout.isTTY) {
    try {
      process.stdout.write(RESET_SEQUENCE);  // 一次性恢复所有终端设置
    } catch (err) {
      reportRestoreFailure("stdout reset", err, reason);
    }
  }
}

3.4 note.ts — 通知卡片输出

完整执行流程

note(message, title?)
  │
  ├── 1. 环境变量检查
  │      └── OPENCLAW_SUPPRESS_NOTES 非0/false/off → 静默返回
  │
  ├── 2. 文本换行
  │      └── wrapNoteMessage(message, opts)
  │            ├── 计算 maxWidth:
  │            │     columns = process.stdout.columns ?? 80
  │            │     maxWidth = max(40, min(88, columns-10))
  │            ├── 按换行符拆分
  │            └── 每行调用 wrapLine(line, maxWidth)
  │                  ├── 解析缩进和项目符号
  │                  │     /^(\s*)([-*\u2022]\s+)?(.*)$/
  │                  ├── 按空格拆分单词
  │                  ├── 逐词累积，超宽则换行
  │                  ├── 特殊处理: isCopySensitiveToken
  │                  │     URL/路径/文件名 → 不拆分
  │                  └── 超长单词 → splitLongWord 强制拆分
  │
  ├── 3. 标题样式化
  │      └── stylePromptTitle(title) → theme.heading(title)
  │
  └── 4. 调用 clack Note 组件渲染
         └── clackNote(wrappedMessage, styledTitle)

逐行解析

// 第1-3行：外部依赖导入
import { note as clackNote } from "@clack/prompts";  // UI 组件库
import { normalizeLowercaseStringOrEmpty } from "../shared/string-coerce.js";  // 字符串规范化
import { visibleWidth } from "./ansi.js";  // 宽度计算
import { stylePromptTitle } from "./prompt-style.js";  // 标题样式

// 第5-8行：URL/路径匹配正则
const URL_PREFIX_RE = /^(https?:\/\/|file:\/\/)/i;  // URL 前缀
const WINDOWS_DRIVE_RE = /^[a-zA-Z]:[\\/]/;          // Windows 盘符路径
const FILE_LIKE_RE = /^[a-zA-Z0-9._-]+$/;            // 文件名模式

// 第10-17行：环境变量抑制检测
// OPENCLAW_SUPPRESS_NOTES: 控制是否显示通知
// 0/false/off → 不抑制（显示通知）
// 其他值 → 抑制（隐藏通知）
function isSuppressedByEnv(value: string | undefined): boolean {
  if (!value) return false;  // 未设置 → 不抑制
  const normalized = normalizeLowercaseStringOrEmpty(value);
  if (!normalized) return false;
  return normalized !== "0" && normalized !== "false" && normalized !== "off";
}

// 第19-26行：超长单词强制拆分
// maxLen <= 0 时原样返回（不拆分）
// 按字符数组切割，每 maxLen 个字符为一段
function splitLongWord(word: string, maxLen: number): string[] {
  if (maxLen <= 0) return [word];
  const chars = Array.from(word);
  const parts: string[] = [];
  for (let i = 0; i < chars.length; i += maxLen) {
    parts.push(chars.slice(i, i + maxLen).join(""));
  }
  return parts.length > 0 ? parts : [word];
}

// 第28-45行：复制敏感 Token 判断
// 这些 Token 在换行时不应被拆分（保持可复制性）
// URL → 不拆
// Unix/Windows 路径 → 不拆
// 包含斜杠的字符串 → 不拆
// 包含下划线的文件名模式 → 不拆
function isCopySensitiveToken(word: string): boolean {
  if (!word) return false;
  if (URL_PREFIX_RE.test(word)) return true;
  if (word.startsWith("/") || word.startsWith("~/") || word.startsWith("./") || word.startsWith("../")) return true;
  if (WINDOWS_DRIVE_RE.test(word) || word.startsWith("\\\\")) return true;
  if (word.includes("/") || word.includes("\\")) return true;
  return word.includes("_") && FILE_LIKE_RE.test(word);
}

// 第47-58行：推送换行后的单词段
// 第一段使用 firstPrefix（带缩进/项目符号）
// 后续段使用 continuationPrefix（纯缩进）
function pushWrappedWordSegments(params: {
  word: string; available: number;
  firstPrefix: string; continuationPrefix: string; lines: string[];
}) {
  const parts = splitLongWord(params.word, params.available);
  const first = parts.shift() ?? "";
  params.lines.push(params.firstPrefix + first);
  for (const part of parts) {
    params.lines.push(params.continuationPrefix + part);
  }
}

// 第60-117行：wrapLine — 单行换行算法
// 解析行的结构：缩进 + 可选项目符号 + 内容
// 逐词累积，超过 maxWidth 时换行
// 复制敏感 Token 不拆分，超长非敏感 Token 强制拆分
function wrapLine(line: string, maxWidth: number): string[] {
  if (line.trim().length === 0) return [line];  // 空行原样保留

  // 正则拆分：缩进 + 可选项目符号 + 内容
  const match = line.match(/^(\s*)([-*\u2022]\s+)?(.*)$/);
  const indent = match?.[1] ?? "";       // 前导空格
  const bullet = match?.[2] ?? "";       // 项目符号 (-, *, •)
  const content = match?.[3] ?? "";      // 实际内容
  const firstPrefix = `${indent}${bullet}`;  // 首行前缀
  const nextPrefix = `${indent}${bullet ? " ".repeat(bullet.length) : ""}`;  // 续行前缀

  // 计算首行和续行的可用宽度（减去前缀宽度）
  const firstWidth = Math.max(10, maxWidth - visibleWidth(firstPrefix));
  const nextWidth = Math.max(10, maxWidth - visibleWidth(nextPrefix));

  const words = content.split(/\s+/).filter(Boolean);
  const lines: string[] = [];
  let current = "";       // 当前行累积的文本
  let prefix = firstPrefix;  // 当前行前缀
  let available = firstWidth;  // 当前行可用宽度

  for (const word of words) {
    // 情况1：当前行为空，开始新行
    if (!current) {
      if (visibleWidth(word) > available) {
        // 单词超宽：敏感 Token 原样放入，非敏感 Token 强制拆分
        if (isCopySensitiveToken(word)) { current = word; continue; }
        pushWrappedWordSegments({ word, available, firstPrefix: prefix, continuationPrefix: nextPrefix, lines });
        prefix = nextPrefix; available = nextWidth;
        continue;
      }
      current = word;  // 单词适合，放入当前行
      continue;
    }

    // 情况2：当前行已有内容，尝试追加
    const candidate = `${current} ${word}`;
    if (visibleWidth(candidate) <= available) {
      current = candidate;  // 追加后不超宽，直接追加
      continue;
    }

    // 追加后超宽：提交当前行
    lines.push(prefix + current);
    prefix = nextPrefix;
    available = nextWidth;

    // 新词是否超宽？
    if (visibleWidth(word) > available) {
      if (isCopySensitiveToken(word)) { current = word; continue; }
      pushWrappedWordSegments({ word, available, firstPrefix: prefix, continuationPrefix: prefix, lines });
      current = "";
      continue;
    }
    current = word;  // 新词适合新行
  }

  // 提交最后一行
  if (current || words.length === 0) {
    lines.push(prefix + current);
  }

  return lines;
}

// 第119-128行：wrapNoteMessage — 整条消息换行
// 自动计算终端宽度，限制最大88字符（可读性最佳实践）
export function wrapNoteMessage(message: string, options: { maxWidth?: number; columns?: number } = {}): string {
  const columns = options.columns ?? process.stdout.columns ?? 80;
  const maxWidth = options.maxWidth ?? Math.max(40, Math.min(88, columns - 10));
  return message.split("\n").flatMap((line) => wrapLine(line, maxWidth)).join("\n");
}

// 第130-135行：note — 通知输出主函数
export function note(message: string, title?: string) {
  if (isSuppressedByEnv(process.env.OPENCLAW_SUPPRESS_NOTES)) return;  // 环境变量抑制
  clackNote(wrapNoteMessage(message), stylePromptTitle(title));  // 渲染通知卡片
}

3.5 table.ts — 终端表格渲染引擎

完整执行流程

renderTable(opts)
  │
  ├── 1. 预处理
  │      ├── rows.map(row => displayString(value))  ← 每个值转显示字符串
  │      └── border 默认值解析 ←── resolveDefaultBorder()
  │
  ├── 2. 无边框快速路径
  │      └── border === "none" → 简单的 " | " 分隔输出
  │
  ├── 3. 列宽计算
  │      ├── 计算 header/cell 最大宽度
  │      ├── 应用 padding × 2
  │      ├── 应用 minWidth/maxWidth 约束
  │      └── 初始宽度 → widths[]
  │
  ├── 4. 列宽调整（超宽压缩）
  │      ├── total > maxWidth 时触发
  │      ├── 优先压缩 flex 列（到 preferredMinWidths）
  │      ├── 再压缩 flex 列（到 absoluteMinWidths）
  │      ├── 再压缩非 flex 列（到 preferredMinWidths）
  │      └── 最后压缩非 flex 列（到 absoluteMinWidths）
  │
  ├── 5. 列宽调整（有余量扩展）
  │      ├── extra = maxWidth - currentTotal
  │      └── 均匀分配给 flex 列（受 maxWidth 上限）
  │
  ├── 6. 边框字符选择
  │      └── unicode: ┌─┐│├┼┤└┴┘  vs  ascii: +-+|
  │
  ├── 7. 渲染
  │      ├── 顶边框
  │      ├── 表头行（自动换行 + 对齐）
  │      ├── 分隔线
  │      ├── 数据行 × N（自动换行 + 对齐）
  │      └── 底边框
  │
  └── 返回完整表格字符串

table.ts 内部 wrapLine — ANSI 感知换行器

这是 table.ts 最复杂的部分，与 note.ts 的 wrapLine 独立实现，专为表格单元格设计：

wrapLine(text, width)
  │
  ├── 1. Token 化
  │      ├── 遍历 text 字符
  │      ├── ESC [ ... m → Token{ansi, value}  ← SGR 样式
  │      ├── ESC ] 8 ;; ... ST → Token{ansi, value}  ← OSC-8 链接
  │      ├── 其他文本 → splitGraphemes → Token{char, value}
  │      └── 不支持的 ESC → Token{char, value}  ← 防止死循环
  │
  ├── 2. 分离前后缀 ANSI
  │      ├── prefixAnsi: 文本前的所有 ANSI token
  │      ├── suffixAnsi: 文本后的所有 ANSI token
  │      └── coreTokens: 中间的核心内容 token
  │
  ├── 3. 逐 token 填充缓冲区
  │      ├── ANSI token → 直接推入（不占宽度）
  │      ├── 换行符 → flushAt(buf.length)
  │      ├── 超宽 → flushAt(lastBreakIndex) 在断点换行
  │      ├── 断点字符 → 更新 lastBreakIndex
  │      │     (空格/制表符/斜杠/连字符/下划线/点号)
  │      └── 行首空格 → 跳过
  │
  ├── 4. flushAt — 缓冲区刷出
  │      ├── left = buf[0..breakAt]  → pushLine
  │      ├── rest = buf[breakAt..]   → 新缓冲区
  │      └── trimLeadingSpaces(rest)
  │
  └── 5. ANSI 包装
         └── 每行前后追加 prefixAnsi/suffixAnsi

逐行解析（关键函数）

// 第1-2行：导入依赖
import { displayString } from "../utils.js";  // 值到显示字符串转换
import { splitGraphemes, visibleWidth } from "./ansi.js";  // ANSI 处理

// 第4行：对齐方式类型
type Align = "left" | "right" | "center";

// 第6-12行：列定义类型
// key: 行数据中的字段名
// header: 列标题
// align: 对齐方式
// minWidth/maxWidth: 列宽约束
// flex: 是否为弹性列（可伸缩）
export type TableColumn = {
  key: string;
  header: string;
  align?: Align;
  minWidth?: number;
  maxWidth?: number;
  flex?: boolean;
};

// 第14-20行：表格渲染选项
// columns: 列定义数组
// rows: 数据行数组
// width: 总宽度限制
// padding: 单元格内边距
// border: 边框风格
export type RenderTableOptions = {
  columns: TableColumn[];
  rows: Array<Record<string, string>>;
  width?: number;
  padding?: number;
  border?: "unicode" | "ascii" | "none";
};

// 第22-35行：默认边框解析
// 非 Windows → unicode（大多数终端支持 UTF-8）
// Windows → 检测现代终端（WT_SESSION/xterm/cygwin/vscode）
//   现代终端 → unicode
//   旧终端 → ascii（cmd.exe 默认不支持 Unicode 边框）
function resolveDefaultBorder(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): "unicode" | "ascii" {
  if (platform !== "win32") return "unicode";
  const term = env.TERM ?? "";
  const termProgram = env.TERM_PROGRAM ?? "";
  const isModernTerminal =
    Boolean(env.WT_SESSION) ||
    term.includes("xterm") || term.includes("cygwin") || term.includes("msys") ||
    termProgram === "vscode";
  return isModernTerminal ? "unicode" : "ascii";
}

// 第37-41行：字符重复工具
function repeat(ch: string, n: number): string {
  if (n <= 0) return "";
  return ch.repeat(n);
}

// 第43-55行：单元格对齐填充
// 计算文本可见宽度与目标宽度的差值
// right: 左侧填充空格
// center: 左右均匀分配空格
// left: 右侧填充空格（默认）
function padCell(text: string, width: number, align: Align): string {
  const w = visibleWidth(text);
  if (w >= width) return text;
  const pad = width - w;
  if (align === "right") return `${repeat(" ", pad)}${text}`;
  if (align === "center") {
    const left = Math.floor(pad / 2);
    const right = pad - left;
    return `${repeat(" ", left)}${text}${repeat(" ", right)}`;
  }
  return `${text}${repeat(" ", pad)}`;
}

// 第57-215行：wrapLine — ANSI 感知的单元格换行器（见上方流程图）
// [已在流程图中详述，此处省略重复]

// 第217-223行：宽度规范化
// 过滤无效值（NaN、负数、0、Infinity）
function normalizeWidth(n: number | undefined): number | undefined {
  if (n == null) return undefined;
  if (!Number.isFinite(n) || n <= 0) return undefined;
  return Math.floor(n);
}

// 第225-228行：获取终端表格宽度
// 最小60，fallback 120（非 TTY 场景）
export function getTerminalTableWidth(minWidth = 60, fallbackWidth = 120): number {
  return Math.max(minWidth, process.stdout.columns ?? fallbackWidth);
}

// 第230-361行：renderTable — 核心渲染函数
export function renderTable(opts: RenderTableOptions): string {
  // 步骤1：预处理所有值为显示字符串
  const rows = opts.rows.map((row) => {
    const next: Record<string, string> = {};
    for (const [key, value] of Object.entries(row)) {
      next[key] = displayString(value);
    }
    return next;
  });

  // 步骤2：边框默认值
  const border = opts.border ?? resolveDefaultBorder(process.platform, process.env);

  // 无边框快速路径
  if (border === "none") {
    const columns = opts.columns;
    const header = columns.map((c) => c.header).join(" | ");
    const lines = [header, ...rows.map((r) => columns.map((c) => r[c.key] ?? "").join(" | "))];
    return `${lines.join("\n")}\n`;
  }

  const padding = Math.max(0, opts.padding ?? 1);  // 默认1格内边距
  const columns = opts.columns;

  // 步骤3：计算每列的 header 和 cell 最大宽度
  const metrics = columns.map((c) => {
    const headerW = visibleWidth(c.header);
    const cellW = Math.max(0, ...rows.map((r) => visibleWidth(r[c.key] ?? "")));
    return { headerW, cellW };
  });

  // 初始宽度 = max(headerW, cellW) + padding×2，应用 maxWidth 上限和 minWidth 下限
  const widths = columns.map((c, i) => {
    const base = Math.max(metrics[i]?.headerW ?? 0, metrics[i]?.cellW ?? 0) + padding * 2;
    const capped = c.maxWidth ? Math.min(base, c.maxWidth) : base;
    return Math.max(c.minWidth ?? 3, capped);
  });

  // 步骤4：超宽压缩
  const maxWidth = normalizeWidth(opts.width);
  const sepCount = columns.length + 1;  // 分隔线数量
  const total = widths.reduce((a, b) => a + b, 0) + sepCount;

  // 计算两种最小宽度
  const preferredMinWidths = columns.map((c, i) =>
    Math.max(c.minWidth ?? 3, (metrics[i]?.headerW ?? 0) + padding * 2, 3)
  );
  const absoluteMinWidths = columns.map((_c, i) =>
    Math.max((metrics[i]?.headerW ?? 0) + padding * 2, 3)
  );

  if (maxWidth && total > maxWidth) {
    let over = total - maxWidth;
    // 分级压缩策略：flex优先 → 非flex
    // preferred → absolute（更激进的压缩）
    const flexOrder = columns
      .map((_c, i) => ({ i, w: widths[i] ?? 0 }))
      .filter(({ i }) => Boolean(columns[i]?.flex))
      .toSorted((a, b) => b.w - a.w)  // 宽列优先压缩
      .map((x) => x.i);
    const nonFlexOrder = columns
      .map((_c, i) => ({ i, w: widths[i] ?? 0 }))
      .filter(({ i }) => !columns[i]?.flex)
      .toSorted((a, b) => b.w - a.w)
      .map((x) => x.i);

    // 轮询式压缩：每列减1，循环直到 over=0 或无法继续
    const shrink = (order: number[], minWidths: number[]) => {
      while (over > 0) {
        let progressed = false;
        for (const i of order) {
          if ((widths[i] ?? 0) <= (minWidths[i] ?? 0)) continue;
          widths[i] = (widths[i] ?? 0) - 1;
          over -= 1;
          progressed = true;
          if (over <= 0) break;
        }
        if (!progressed) break;
      }
    };

    shrink(flexOrder, preferredMinWidths);      // 第一轮：flex列→preferred下限
    shrink(flexOrder, absoluteMinWidths);       // 第二轮：flex列→absolute下限
    shrink(nonFlexOrder, preferredMinWidths);   // 第三轮：非flex列→preferred下限
    shrink(nonFlexOrder, absoluteMinWidths);    // 第四轮：非flex列→absolute下限
  }

  // 步骤5：有余量扩展flex列
  if (maxWidth) {
    const currentTotal = widths.reduce((a, b) => a + b, 0) + sepCount;
    let extra = maxWidth - currentTotal;
    if (extra > 0) {
      const flexCols = columns.map((c, i) => ({ c, i }))
        .filter(({ c }) => Boolean(c.flex))
        .map(({ i }) => i);
      if (flexCols.length > 0) {
        const caps = columns.map((c) =>
          typeof c.maxWidth === "number" && c.maxWidth > 0
            ? Math.floor(c.maxWidth) : Number.POSITIVE_INFINITY
        );
        while (extra > 0) {
          let progressed = false;
          for (const i of flexCols) {
            if ((widths[i] ?? 0) >= (caps[i] ?? Number.POSITIVE_INFINITY)) continue;
            widths[i] = (widths[i] ?? 0) + 1;
            extra -= 1;
            progressed = true;
            if (extra <= 0) break;
          }
          if (!progressed) break;
        }
      }
    }
  }

  // 步骤6：边框字符映射
  const box = border === "ascii"
    ? { tl:"+", tr:"+", bl:"+", br:"+", h:"-", v:"|", t:"+", ml:"+", m:"+", mr:"+", b:"+" }
    : { tl:"┌", tr:"┐", bl:"└", br:"┘", h:"─", v:"│", t:"┬", ml:"├", m:"┼", mr:"┤", b:"┴" };

  // 步骤7：渲染
  const hLine = (left: string, mid: string, right: string) =>
    `${left}${widths.map((w) => repeat(box.h, w)).join(mid)}${right}`;

  const contentWidthFor = (i: number) => Math.max(1, widths[i] - padding * 2);
  const padStr = repeat(" ", padding);

  // renderRow — 渲染单行（含自动换行）
  const renderRow = (record: Record<string, string>, isHeader = false) => {
    const cells = columns.map((c) => (isHeader ? c.header : (record[c.key] ?? "")));
    const wrapped = cells.map((cell, i) => wrapLine(cell, contentWidthFor(i)));
    const height = Math.max(...wrapped.map((w) => w.length));  // 多行单元格取最高行数
    const out: string[] = [];
    for (let li = 0; li < height; li += 1) {
      const parts = wrapped.map((lines, i) => {
        const raw = lines[li] ?? "";  // 不够高的行补空
        const aligned = padCell(raw, contentWidthFor(i), columns[i]?.align ?? "left");
        return `${padStr}${aligned}${padStr}`;
      });
      out.push(`${box.v}${parts.join(box.v)}${box.v}`);
    }
    return out;
  };

  // 组装完整表格
  const lines: string[] = [];
  lines.push(hLine(box.tl, box.t, box.tr));      // ┌───┬───┐
  lines.push(...renderRow({}, true));              // │ H1 │ H2 │
  lines.push(hLine(box.ml, box.m, box.mr));       // ├───┼───┤
  for (const row of rows) {
    lines.push(...renderRow(row, false));          // │ v1 │ v2 │
  }
  lines.push(hLine(box.bl, box.b, box.br));       // └───┴───┘
  return `${lines.join("\n")}\n`;
}

3.6 theme.ts + palette.ts — 主题与调色板

Lobster Palette 色彩体系

Token	色值	用途	视觉语义
accent	#FF5A2D	主强调色	OpenClaw 品牌色，龙虾红
accentBright	#FF7A3D	亮强调色	高亮元素
accentDim	#D14A22	暗强调色	低对比度强调
info	#FF8A5B	信息色	提示性文本
success	#2FBF71	成功色	通过/完成状态
warn	#FFB020	警告色	需注意的状态
error	#E23D2D	错误色	失败/错误状态
muted	#8B7F77	弱化色	次要/禁用文本

theme 对象构建逻辑

// 1. 检测 NO_COLOR / FORCE_COLOR 环境变量
// NO_COLOR 标准：https://no-color.org/
// FORCE_COLOR：强制启用颜色（覆盖 NO_COLOR）
const hasForceColor = typeof process.env.FORCE_COLOR === "string" &&
  process.env.FORCE_COLOR.trim().length > 0 &&
  process.env.FORCE_COLOR.trim() !== "0";

// 2. 根据环境变量选择 chalk 实例
// NO_COLOR 且无 FORCE_COLOR → level=0（纯文本）
// 否则 → 默认 chalk（自动检测终端支持）
const baseChalk = process.env.NO_COLOR && !hasForceColor
  ? new Chalk({ level: 0 }) : chalk;

// 3. 创建 hex 颜色函数工厂
const hex = (value: string) => baseChalk.hex(value);

// 4. 构建主题对象 — 每个属性都是一个颜色函数
export const theme = {
  accent: hex("#FF5A2D"),        // (s) => chalk.hex("#FF5A2D")(s)
  accentBright: hex("#FF7A3D"),
  accentDim: hex("#D14A22"),
  info: hex("#FF8A5B"),
  success: hex("#2FBF71"),
  warn: hex("#FFB020"),
  error: hex("#E23D2D"),
  muted: hex("#8B7F77"),
  heading: baseChalk.bold.hex("#FF5A2D"),  // 粗体主色
  command: hex("#FF7A3D"),       // 命令名高亮
  option: hex("#FFB020"),        // 选项高亮
} as const;

// 5. isRich — 判断是否启用富文本
// level > 0 意味着 chalk 会生成 ANSI 颜色码
export const isRich = () => baseChalk.level > 0;

// 6. colorize — 条件性着色
// rich=false 时原样返回，避免在非 TTY 场景输出 ANSI 码
export const colorize = (rich: boolean, color: (value: string) => string, value: string) =>
  rich ? color(value) : value;

3.7 其他模块解析

terminal-link.ts — OSC-8 超链接

// 格式: ESC ] 8 ; ; URL ST LABEL ESC ] 8 ; ; ST
// \u001b]8;;URL\u0007LABEL\u001b]8;;\u0007
// 安全处理：移除 label 和 URL 中的 ESC 字符（防止注入）
// TTY 检测：非 TTY 环境回退为 "label (url)" 格式
// force 选项：强制生成/禁用超链接
export function formatTerminalLink(label, url, opts?): string {
  const esc = "\u001b";
  const safeLabel = label.replaceAll(esc, "");  // 防 ANSI 注入
  const safeUrl = url.replaceAll(esc, "");
  const allow = opts?.force === true ? true : opts?.force === false ? false : process.stdout.isTTY;
  if (!allow) return opts?.fallback ?? `${safeLabel} (${safeUrl})`;
  return `\u001b]8;;${safeUrl}\u0007${safeLabel}\u001b]8;;\u0007`;
}

links.ts — 文档链接生成

// 固定文档根: https://docs.openclaw.ai
// path 处理逻辑:
//   无 path → 链接到文档根
//   http 开头 → 原样使用
//   / 开头 → 拼接 docsRoot + path
//   其他 → 拼接 docsRoot + "/" + path
export function formatDocsLink(path, label?, opts?): string {
  const docsRoot = resolveDocsRoot();  // "https://docs.openclaw.ai"
  const trimmed = typeof path === "string" ? path.trim() : "";
  const url = trimmed
    ? trimmed.startsWith("http") ? trimmed
      : `${docsRoot}${trimmed.startsWith("/") ? trimmed : `/${trimmed}`}`
    : docsRoot;
  return formatTerminalLink(label ?? url, url, {
    fallback: opts?.fallback ?? url,
    force: opts?.force,
  });
}

safe-text.ts — 单行文本消毒

// 用途：将不可信文本安全地渲染到终端单行
// 步骤:
//   1. stripAnsi → 移除 ANSI 序列
//   2. \r → \\r, \n → \\n, \t → \\t  ← 将控制字符转义为可见形式
//   3. 移除 C0(0x00-0x1F) 和 C1(0x7F-0x9F) 控制字符
// 注意：与 sanitizeForLog 的区别 — safe-text 保留可见的转义表示
export function sanitizeTerminalText(input: string): string {
  const normalized = stripAnsi(input)
    .replace(/\r/g, "\\r").replace(/\n/g, "\\n").replace(/\t/g, "\\t");
  let sanitized = "";
  for (const char of normalized) {
    const code = char.charCodeAt(0);
    const isControl = (code >= 0x00 && code <= 0x1f) || (code >= 0x7f && code <= 0x9f);
    if (!isControl) sanitized += char;
  }
  return sanitized;
}

progress-line.ts — 进度行管理

// 全局单例模式：同一时刻只有一个活动进度行
// registerActiveProgressLine(stream): 注册 TTY 流为进度行载体
// clearActiveProgressLine(): 清除进度行（\r + ESC[2K = 回车+清除整行）
// unregisterActiveProgressLine(stream?): 注销进度行

let activeStream: NodeJS.WriteStream | null = null;

export function registerActiveProgressLine(stream: NodeJS.WriteStream): void {
  if (!stream.isTTY) return;  // 非 TTY 不需要进度行
  activeStream = stream;
}

export function clearActiveProgressLine(): void {
  if (!activeStream?.isTTY) return;
  activeStream.write("\r\x1b[2K");  // \r 回到行首 + \x1b[2K 清除整行
}

export function unregisterActiveProgressLine(stream?: NodeJS.WriteStream): void {
  if (!activeStream) return;
  if (stream && activeStream !== stream) return;  // 只注销自己的流
  activeStream = null;
}

health-style.ts — 健康检查行着色

// 根据健康检查结果的关键词自动着色
// "failed" → error 红
// "ok" → success 绿
// "linked" → success 绿
// "configured" → success 绿
// "not linked" → warn 黄
// "not configured" → muted 灰
// "unknown" → warn 黄
// 解析逻辑: 在冒号处分割 line，着色 detail 部分的关键词前缀
export function styleHealthChannelLine(line: string, rich: boolean): string {
  if (!rich) return line;
  const colon = line.indexOf(":");
  if (colon === -1) return line;
  const label = line.slice(0, colon + 1);
  const detail = line.slice(colon + 1).trimStart();
  const normalized = normalizeLowercaseStringOrEmpty(detail);
  const applyPrefix = (prefix, color) =>
    `${label} ${color(detail.slice(0, prefix.length))}${detail.slice(prefix.length)}`;
  // ... 模式匹配和着色
}

prompt-select-styled.ts — 样式化选择器

// 封装 @clack/prompts 的 select 组件
// 自动对 message 应用 accent 色
// 自动对 hint 应用 muted 色
export function selectStyled<T>(params) {
  return select({
    ...params,
    message: stylePromptMessage(params.message),  // accent 着色
    options: params.options.map((opt) =>
      opt.hint === undefined ? opt : { ...opt, hint: stylePromptHint(opt.hint) }  // muted 着色
    ),
  });
}

---

四、业务规则正确性审查

4.1 宽度计算正确性 ✅

visibleWidth 的字素宽度计算覆盖了：

• ASCII 字符（1列）✅
• CJK 字符（2列）✅
• Emoji（2列）✅
• 组合字符（0列）✅
• ZWJ 连接的 Emoji（通过 Segmenter 正确识别为单个字素）✅
• 全角拉丁/数字（2列）✅

4.2 日志安全合规 ✅

sanitizeForLog 实现了 CWE-117 防御：

• 移除所有 ANSI 转义序列 ✅
• 移除 C0 控制字符(0x00-0x1F) ✅
• 移除 DEL(0x7F) ✅

4.3 管道断裂容错 ✅

SafeStreamWriter 正确处理 EPIPE：

• 检测到 EPIPE 后标记 closed ✅
• 后续写入快速返回 false ✅
• onBrokenPipe 回调幂等 ✅
• 非 EPIPE 错误正常抛出 ✅

4.4 终端状态恢复完整性 ✅

RESET_SEQUENCE 覆盖了所有常见的终端模式变更：

• SGR 重置 ✅
• 光标可见性 ✅
• 鼠标追踪模式 × 4 ✅
• 括号粘贴模式 ✅
• 焦点追踪 ✅
• 光标闪烁 ✅

4.5 表格列宽分配合理性 ✅

四级压缩策略确保：

• flex 列优先承担压缩压力 ✅
• 非必要时不压缩到 header 无法显示 ✅
• 绝对必要时可以压缩到 header + padding ✅
• 有余量时 flex 列扩展填充 ✅

4.6 潜在风险点

1. table.ts wrapLine 的 ANSI 状态传递：换行后没有重新打开前缀 ANSI 样式。注释说明"终端保持 SGR 状态跨行"，但在某些边缘场景（如 SGR 组合样式）可能出现样式丢失。当前实现依赖终端的 SGR 状态机行为，在实际使用中基本可靠。

2. progress-line.ts 全局单例：多个进度行注册会互相覆盖。这是设计意图（同一时刻只有一个进度行），但在并发场景可能产生竞态。

3. note.ts isCopySensitiveToken：仅检测下划线+文件名模式的 token，不覆盖中文字符开头的路径或含有空格的文件名。

---

五、模块间协作全景

5.1 典型使用场景调用链

场景1：输出表格

CLI 命令 → renderTable(opts)
  ├── displayString() → 值格式化
  ├── visibleWidth() → 列宽计算
  ├── wrapLine() → 单元格换行
  │    └── splitGraphemes() → 字素拆分
  ├── padCell() → 对齐填充
  └── 返回表格字符串 → SafeStreamWriter.write(stdout, table)

场景2：输出通知

CLI 命令 → note(message, title)
  ├── isSuppressedByEnv() → 环境变量检查
  ├── wrapNoteMessage()
  │    ├── visibleWidth() → 宽度计算
  │    ├── wrapLine() → 逐行换行
  │    └── isCopySensitiveToken() → 路径保护
  ├── stylePromptTitle() → theme.heading() → chalk.bold.hex()
  └── clackNote() → 终端渲染

场景3：程序退出清理

进程信号 → restoreTerminalState(reason)
  ├── clearActiveProgressLine() → \r\x1b[2K
  ├── stdin.setRawMode(false) → 退出原始模式
  ├── stdin.resume() → 恢复输入
  └── stdout.write(RESET_SEQUENCE) → 完整重置

场景4：安全日志输出

业务代码 → sanitizeForLog(value)
  ├── stripAnsi() → 移除终端序列
  └── 移除控制字符 → 安全字符串 → 写入日志文件

---

六、设计模式总结

模式	应用位置	说明
工厂函数	createSafeStreamWriter	闭包封装有状态逻辑
策略模式	resolveDefaultBorder	根据平台选择边框策略
单例模式	progress-line.ts	全局唯一活动进度行
Null Object	Chalk({ level: 0 })	NO_COLOR 场景的空颜色实现
环境变量开关	NO_COLOR/FORCE_COLOR/OPENCLAW_SUPPRESS_NOTES	遵循社区标准
防御性编程	restoreTerminalState 双重 try-catch	清理路径永不抛异常
Token 流处理	table.ts wrapLine	ANSI/字符混合流式处理
弹性布局	table.ts flex 列宽	类似 CSS flex 的列宽分配

---

本报告由 OpenClaw AI 自动生成，基于 /root/.hermes/hermes-agent/project/openclaw/src/terminal 目录下全部源码的超深度分析。

---

---

七、测试套件深度解析

续主报告，本章节对全部 6 个测试文件进行逐条分析，揭示测试覆盖的边界条件与设计意图。

7.1 ansi.test.ts — ANSI 处理测试

框架：Vitest | 测试数量：4 | 覆盖函数：stripAnsi, sanitizeForLog, splitGraphemes, visibleWidth

测试用例逐条解析

用例 1：strips ANSI and OSC8 sequences

expect(stripAnsi("\u001B[31mred\u001B[0m")).toBe("red");
expect(stripAnsi("\u001B[2K\u001B[1Ared")).toBe("red");
expect(stripAnsi("\u001B]8;;https://openclaw.ai\u001B\\link\u001B]8;;\u001B\\")).toBe("link");

输入	ANSI 类型	验证点
\x1B[31mred\x1B[0m	SGR（颜色）	红色包裹的文本剥离后保留 “red”
\x1B[2K\x1B[1Ared	CSI（擦除+光标上移）	非SGR的CSI序列也被正确剥离
\x1B]8;;url\x1B\\link\x1B]8;;\x1B\\	OSC-8 超链接	完整的超链接结构（打开+关闭）剥离后保留 “link”

设计意图：覆盖 ANSI 两大类序列（CSI + OSC-8）的剥离正确性。特别注意了 CSI 不限于 SGR——擦除序列、光标移动序列也必须被正确处理。

---

用例 2：sanitizes control characters for log-safe interpolation

const input = "\u001B[31mwarn\u001B[0m\r\nnext\u0000line\u007f";
expect(sanitizeForLog(input)).toBe("warnnextline");

解析：

• 输入包含：SGR 颜色码 + \r(CR) + \n(LF) + NUL(\x00) + DEL(\x7f)
• 输出：纯文本 “warnnextline”
• 验证点：
  • SGR 序列被移除 ✅
  • C0 控制字符(0x00-0x1F)被移除 ✅（\r=0x0D, \n=0x0A, NUL=0x00）
  • DEL(0x7F)被移除 ✅
  • CWE-117 合规：日志注入攻击向量全部消除

---

用例 3：measures wide graphemes by terminal cell width

expect(visibleWidth("abc")).toBe(3);       // ASCII
expect(visibleWidth("📸 skill")).toBe(8);  // Emoji + 空格 + ASCII
expect(visibleWidth("表")).toBe(2);        // CJK 汉字
expect(visibleWidth("\u001B[31m📸\u001B[0m")).toBe(2);  // ANSI 包裹的 Emoji

输入	宽度计算	验证点
"abc"	1+1+1=3	ASCII 字符宽度=1
"📸 skill"	2+1+1+1+1+1+1=8	Emoji=2, 空格=1, ASCII=1
"表"	2	CJK 汉字=2（FullWidth）
"\x1B[31m📸\x1B[0m"	2	ANSI 剥离后仅计算 Emoji 宽度

设计意图：验证宽度计算的三种核心场景——纯 ASCII、混合 Emoji、CJK 字符，以及 ANSI 包裹不影响宽度计算。

---

用例 4：keeps emoji zwj sequences as single graphemes

expect(splitGraphemes("👨👩👧👦")).toEqual(["👨👩👧👦"]);
expect(visibleWidth("👨👩👧👦")).toBe(2);

解析：

• 👨👩👧👦 是 ZWJ（Zero Width Joiner）序列组成的家庭 Emoji
• splitGraphemes 必须将其作为单个字素返回（而非拆分为 4 个人物 Emoji + 3 个 ZWJ）
• 宽度计算：整个 ZWJ 序列 = 2 列（单 Emoji 宽度）
• 关键验证：Intl.Segmenter 正确识别 ZWJ 序列为单一用户感知字符

---

7.2 stream-writer.test.ts — 安全流写入器测试

框架：Vitest | 测试数量：2 | 覆盖函数：createSafeStreamWriter

测试用例逐条解析

用例 1：signals broken pipes and closes the writer

const onBrokenPipe = vi.fn();
const writer = createSafeStreamWriter({ onBrokenPipe });
const stream = {
  write: vi.fn(() => {
    const err = new Error("EPIPE") as NodeJS.ErrnoException;
    err.code = "EPIPE";
    throw err;
  }),
} as unknown as NodeJS.WriteStream;

expect(writer.writeLine(stream, "hello")).toBe(false);     // 第一次写入：EPIPE
expect(writer.isClosed()).toBe(true);                      // 状态：已关闭
expect(onBrokenPipe).toHaveBeenCalledTimes(1);             // 回调：调用1次

onBrokenPipe.mockClear();
expect(writer.writeLine(stream, "again")).toBe(false);     // 第二次写入：快速返回
expect(onBrokenPipe).toHaveBeenCalledTimes(0);            // 回调：不再调用（幂等）

状态流转验证：

初始状态 → writeLine("hello") → EPIPE → closed=true → onBrokenPipe(1次)
         → writeLine("again") → closed=true → 快速返回false → onBrokenPipe(0次)

验证点：

1. EPIPE 异常被捕获而非抛出 ✅
2. closed 状态正确设置 ✅
3. onBrokenPipe 回调幂等（只通知一次） ✅
4. 后续写入快速返回 false ✅

---

用例 2：treats broken pipes from beforeWrite as closed

const writer = createSafeStreamWriter({
  onBrokenPipe,
  beforeWrite: () => {
    const err = new Error("EIO") as NodeJS.ErrnoException;
    err.code = "EIO";
    throw err;
  },
});
const stream = { write: vi.fn(() => true) } as unknown as NodeJS.WriteStream;

expect(writer.write(stream, "hi")).toBe(false);
expect(writer.isClosed()).toBe(true);
expect(onBrokenPipe).toHaveBeenCalledTimes(1);

解析：

• beforeWrite 钩子抛出 EIO（另一种管道错误码）
• 即使 stream.write 本身没问题，beforeWrite 的异常也应触发关闭
• 验证点：beforeWrite 异常路径与 stream.write 异常路径行为一致
• 设计意图：beforeWrite 通常用于清理进度行，如果此步骤失败（如进度行所在流已断），整个写入应被视为失败

---

7.3 restore.test.ts — 终端状态恢复测试

框架：Vitest | 测试数量：4 | 覆盖函数：restoreTerminalState

测试基础设施

// 模拟 progress-line 模块
const clearActiveProgressLine = vi.hoisted(() => vi.fn());
vi.mock("./progress-line.js", () => ({ clearActiveProgressLine }));

// 可配置的终端 I/O 模拟
function configureTerminalIO(params: {
  stdinIsTTY: boolean;
  stdoutIsTTY: boolean;
  setRawMode?: (mode: boolean) => void;
  resume?: () => void;
  isPaused?: () => boolean;
}) { ... }

// 保存/恢复原始 process 属性
afterEach(() => { vi.restoreAllMocks(); ... });

设计模式：

• vi.hoisted：在模块导入前创建 mock，确保 vi.mock 工厂函数能引用
• configureTerminalIO：灵活配置 TTY 检测结果和 stdin 方法
• afterEach 还原：防止测试间状态泄漏

测试用例逐条解析

用例 1：does not resume paused stdin by default

const { setRawMode, resume } = setupPausedTTYStdin();
restoreTerminalState("test");
expect(setRawMode).toHaveBeenCalledWith(false);  // 退出 raw mode ✅
expect(resume).not.toHaveBeenCalled();            // 不恢复 stdin ✅

验证点：默认行为是安全的——只退出 raw mode，不恢复 stdin。这确保 “清理后退出” 的场景不会因为 stdin resume 而挂起。

---

用例 2：resumes paused stdin when resumeStdin is true

restoreTerminalState("test", { resumeStdinIfPaused: true });
expect(setRawMode).toHaveBeenCalledWith(false);
expect(resume).toHaveBeenCalledOnce();

验证点：显式启用 resumeStdinIfPaused 时，暂停的 stdin 会被恢复。

---

用例 3：does not touch stdin when stdin is not a TTY

configureTerminalIO({ stdinIsTTY: false, stdoutIsTTY: false, ... });
restoreTerminalState("test", { resumeStdinIfPaused: true });
expect(setRawMode).not.toHaveBeenCalled();
expect(resume).not.toHaveBeenCalled();

验证点：非 TTY 环境（如管道、CI）中不调用 setRawMode/resume，避免对非 TTY stdin 调用不存在的方法。

---

用例 4：writes kitty and modifyOtherKeys reset sequences to stdout

const writeSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
configureTerminalIO({ stdinIsTTY: false, stdoutIsTTY: true });
restoreTerminalState("test");

expect(writeSpy).toHaveBeenCalled();
const output = writeSpy.mock.calls.map(([chunk]) => String(chunk)).join("");
expect(output).toContain("\x1b[<u");      // Kitty 键盘协议重置
expect(output).toContain("\x1b[>4;0m");   // modifyOtherKeys 关闭

验证点：RESET_SEQUENCE 中包含两个现代终端扩展协议的重置序列。

• \x1b[<u：Kitty 键盘协议的 “unfocus” 通知关闭
• \x1b[>4;0m：xterm modifyOtherKeys 模式关闭

这两个是较新的终端协议，测试确保它们被包含在重置序列中。

---

7.4 safe-text.test.ts — 单行文本消毒测试

框架：Vitest | 测试数量：3 | 覆盖函数：sanitizeTerminalText

测试用例逐条解析

用例 1：removes C1 control characters

expect(sanitizeTerminalText("a\u009bb\u0085c")).toBe("abc");

• \u009b = CSI 引入符（C1 控制字符）
• \u0085 = NEL (Next Line，C1 控制字符)
• 验证点：C1 区间 (0x80-0x9F) 的控制字符被移除

与 sanitizeForLog 的区别：sanitizeForLog 只处理 C0 (0x00-0x1F) + DEL (0x7F)，不处理 C1。sanitizeTerminalText 覆盖更广的 C1 区间。

---

用例 2：strips cursor and erase ANSI sequences

expect(sanitizeTerminalText("\u001b[2K\u001b[1Arewritten")).toBe("rewritten");

• \x1b[2K = 擦除整行
• \x1b[1A = 光标上移1行
• 验证点：stripAnsi 作为第一步正确移除所有 CSI 序列

---

用例 3：escapes line controls while preserving printable text

expect(sanitizeTerminalText("a\tb\nc\rd")).toBe("a\\tb\\nc\\rd");

• Tab → \\t，LF → \\n，CR → \\r
• 验证点：行控制字符被转义为可见形式，而非直接移除
• 设计意图：单行显示场景（如日志、状态栏）需要保留控制字符的"存在证据"，但又不允许它们实际生效

---

7.5 links.test.ts — 文档链接测试

框架：Vitest | 测试数量：5 | 覆盖函数：formatDocsLink

测试用例逐条解析

#	用例名	输入	预期行为	验证点
1	prepends docs root for relative path	"/channels/telegram"	包含 https://docs.openclaw.ai/channels/telegram	相对路径拼接正确
2	preserves absolute http url	"https://example.com/page"	包含 https://example.com/page	绝对 URL 不被改写
3	whitespace-only → docs root	" "	包含 https://docs.openclaw.ai	空白路径视为空
4	undefined path → no crash	undefined	不抛异常，输出含 docs root	回归测试 #67076, #67074
5	null path → no crash	null	不抛异常	null 安全

关键洞察：用例 4 和 5 是回归测试，对应的 issue (#67076, #67074) 指向了实际生产 bug——某些 channel 插件的 meta.docsPath 在运行时为 undefined/null，但 formatDocsLink 的类型签名声明 path 为 string。这暴露了类型系统与运行时数据的不一致。

---

7.6 prompt-select-styled.test.ts — 样式化选择器测试

框架：Vitest | 测试数量：1 | 覆盖函数：selectStyled

Mock 架构

// 三层 mock：clack select + prompt-style 的两个函数
const { selectMock, stylePromptMessageMock, stylePromptHintMock } = vi.hoisted(() => ({
  selectMock: vi.fn(),
  stylePromptMessageMock: vi.fn((value: string) => `msg:${value}`),
  stylePromptHintMock: vi.fn((value: string) => `hint:${value}`),
}));

vi.mock("@clack/prompts", () => ({ select: selectMock }));
vi.mock("./prompt-style.js", () => ({
  stylePromptMessage: stylePromptMessageMock,
  stylePromptHint: stylePromptHintMock,
}));

设计意图：完全隔离 selectStyled 的两个依赖，验证它只是装饰器（Decorator）——对 select 的参数做样式变换后透传。

测试用例解析

selectMock.mockReturnValue(expected);  // select 返回 Symbol

const result = selectStyled({
  message: "Pick channel",
  options: [
    { value: "stable", label: "Stable", hint: "Tagged releases" },
    { value: "dev", label: "Dev" },                    // 无 hint
  ],
});

expect(result).toBe(expected);                                       // 返回值透传
expect(stylePromptMessageMock).toHaveBeenCalledWith("Pick channel"); // message 样式化
expect(stylePromptHintMock).toHaveBeenCalledWith("Tagged releases"); // hint 样式化
expect(selectMock).toHaveBeenCalledWith({
  message: "msg:Pick channel",                        // 样式化后的 message
  options: [
    { value: "stable", label: "Stable", hint: "hint:Tagged releases" },  // 样式化后的 hint
    { value: "dev", label: "Dev" },                    // 无 hint 的选项不受影响
  ],
});

验证点：

1. 返回值直接透传（装饰器模式） ✅
2. message 经过 stylePromptMessage 变换 ✅
3. 有 hint 的选项经过 stylePromptHint 变换 ✅
4. 无 hint 的选项不受影响 ✅
5. 变换后的值正确传入底层 select ✅

---

7.7 table.test.ts — 表格渲染测试（核心重头戏）

框架：Vitest | 测试数量：10（renderTable 8 + wrapNoteMessage 5 = 13 断言组） | 覆盖函数：renderTable, wrapNoteMessage

这是最复杂、最关键的测试文件，覆盖了终端表格渲染的几乎所有边界条件。

renderTable 测试

#	用例名	验证的边界条件
1	prefers shrinking flex columns	超宽时 flex 列优先压缩，非 flex 列（Item）保持完整显示
2	expands flex columns to fill width	有余量时 flex 列扩展填满，表格总宽 = 指定 width
3	wraps ANSI-colored cells without corrupting escape sequences	ANSI 换行不拆断 SGR 序列
4	resets ANSI styling on wrapped lines	换行后的 SGR 重置码位置正确（在边框 │ 之前）
5	trims leading spaces on wrapped ANSI continuation lines	ANSI 包裹的续行不出现多余前导空格
6	respects explicit newlines in cell values	单元格内的 \n 被保留为换行
7	keeps borders aligned with wide emoji graphemes	Emoji 占2列时边框仍然对齐
8	consumes unsupported escape sequences without hanging	未知的 ESC 序列不导致换行器死循环
9	falls back to ASCII borders on legacy Windows	旧版 Windows 控制台使用 ASCII 边框
10	keeps unicode borders on modern Windows	Windows Terminal 使用 Unicode 边框

关键用例深度解析

用例 3：ANSI 换行不拆断 SGR 序列

const out = renderTable({
  width: 36,
  columns: [
    { key: "K", header: "K", minWidth: 3 },
    { key: "V", header: "V", flex: true, minWidth: 10 },
  ],
  rows: [{ K: "X", V: `\x1b[33m${"a".repeat(120)}\x1b[0m` }],
});

// 验证：输出中每个 ESC 出现的位置都匹配完整的 ANSI token
const ansiToken = new RegExp(String.raw`\u001b\[[0-9;]*m|\u001b\]8;;.*?\u001b\\`, "gs");
let escapeIndex = out.indexOf("\u001b");
while (escapeIndex >= 0) {
  ansiToken.lastIndex = escapeIndex;
  const match = ansiToken.exec(out);
  expect(match?.index).toBe(escapeIndex);  // 每个 ESC 都是完整 token 的起始
  escapeIndex = out.indexOf("\u001b", escapeIndex + 1);
}

设计意图：120个字符的黄色文本在 width=36 的表格中必然换行多次。测试确保换行器永远不会在 SGR 序列的中间切割——每个 \x1b[ 后面必须跟完整的参数字节和 m 终止符。

---

用例 4：SGR 重置码在边框之前

const reset = "\x1b[0m";
// ... 80 个字符的红色文本在 width=24 的表格中
const lines = out.split("\n").filter((line) => line.includes("a"));
for (const line of lines) {
  const resetIndex = line.lastIndexOf(reset);
  const lastSep = line.lastIndexOf("│");
  expect(resetIndex).toBeGreaterThan(-1);          // 重置码存在
  expect(lastSep).toBeGreaterThan(resetIndex);      // 边框在重置码之后
}

设计意图：换行后每个单元格行的 ANSI 状态必须正确闭合。如果 \x1b[0m 在边框 │ 之后，意味着颜色会"泄漏"到边框和下一列。测试确保重置码在单元格内容末尾、边框之前。

---

用例 7：Emoji 不破坏边框对齐

const width = 72;
// 包含 📸 和 ✗ 的表格行
for (const line of out.trimEnd().split("\n")) {
  expect(visibleWidth(line)).toBe(width);  // 每行宽度严格等于 width
}

设计意图：这是最严格的对齐测试——不仅要求边框视觉对齐，还要求每行的可见宽度精确等于指定的 width。任何 Emoji 宽度计算错误都会导致此测试失败。

---

用例 8：不支持 ESC 序列不挂起

// \x1b[2J = 擦除屏幕（非 SGR 的 CSI 序列）
const out = renderTable({ ..., rows: [{ K: "row", V: "before \x1b[2J after" }] });
expect(out).toContain("before");
expect(out).toContain("after");

设计意图：wrapLine 的 Token 化器遇到不支持的 ESC 序列时，必须将其作为普通字符消费（而非跳过或死循环）。\x1b[2J 不是 SGR，不是 OSC-8，所以会进入"不支持的 ESC → Token{char}"分支。

---

wrapNoteMessage 测试

#	用例名	验证点
1	preserves long filesystem paths	Unix 路径不被拆分
2	preserves long urls	URL 不被拆分
3	preserves file-like underscore tokens	administrators_authorized_keys 不被拆分
4	chunks generic long opaque tokens	普通 70 字符字符串被强制换行
5	wraps bullet lines with indentation	项目符号续行保持缩进
6	preserves Windows paths	C:\\... 路径不被拆分
7	preserves UNC paths	\\\\server\\share\\... 不被拆分

用例 4 的关键性：与用例 1-3 形成对照——普通长单词必须被换行（防止行宽爆炸），而路径/URL 不被拆分（保持可复制性）。isCopySensitiveToken 的判断逻辑在此得到完整验证。

---

八、跨模块依赖深度分析

8.1 外部依赖图谱

terminal/
  ├── ansi.ts          ←── (无外部依赖, 纯计算)
  ├── palette.ts       ←── (无外部依赖, 纯常量)
  ├── stream-writer.ts ←── (无外部依赖, 仅用 Node.js 内置类型)
  ├── progress-line.ts ←── (无外部依赖, 仅用 Node.js WriteStream)
  ├── safe-text.ts     ←── ansi.ts (stripAnsi)
  ├── terminal-link.ts ←── (无外部依赖)
  ├── theme.ts         ←── palette.ts + chalk (npm)
  ├── prompt-style.ts  ←── theme.ts
  ├── health-style.ts  ←── theme.ts + shared/string-coerce.ts
  ├── prompt-select-styled.ts ←── prompt-style.ts + @clack/prompts (npm)
  ├── note.ts          ←── ansi.ts + prompt-style.ts + shared/string-coerce.ts + @clack/prompts
  ├── links.ts         ←── terminal-link.ts
  ├── restore.ts       ←── progress-line.ts
  └── table.ts         ←── ansi.ts + utils.ts (displayString)

8.2 关键外部模块解析

shared/string-coerce.ts

terminal 模块使用的唯一函数：normalizeLowercaseStringOrEmpty(value)

export function normalizeLowercaseStringOrEmpty(value: unknown): string {
  return normalizeOptionalString(value)?.toLowerCase() ?? "";
}

调用点：

1. note.ts → isSuppressedByEnv → 用于解析 OPENCLAW_SUPPRESS_NOTES 环境变量
2. health-style.ts → styleHealthChannelLine → 用于规范化健康检查状态关键词

设计意图：统一处理 unknown 类型到小写字符串的转换，避免在每个调用点重复 null/undefined 检查。对环境变量处理尤其重要——process.env.X 的类型是 string | undefined。

utils.ts → displayString()

export function displayString(input: string): string {
  return shortenHomeInString(input);
}

调用点：table.ts → renderTable → 对每个单元格值调用

设计意图：将用户主目录路径（如 /Users/alice/.openclaw）缩短为 ~/.openclaw，使表格更紧凑。这是 terminal 模块与 config 路径系统的唯一交互点。

npm 外部依赖

包名	版本约束	使用位置	作用
chalk	^5	theme.ts	终端颜色/样式
@clack/prompts	^0.x	note.ts, prompt-select-styled.ts	交互式 UI 组件

chalk 的架构角色：

• theme.ts 创建了 chalk 的 hex 颜色函数实例
• NO_COLOR 环境变量下降级为 Chalk({ level: 0 })（纯文本模式）
• FORCE_COLOR 可覆盖 NO_COLOR

@clack/prompts 的架构角色：

• 提供 note() 和 select() 两个 UI 原语
• terminal 模块通过 stylePrompt* 和 selectStyled 对其进行装饰
• 实现了装饰器模式：不修改 clack 内部，只变换输入参数

---

九、数据流序列图

9.1 CLI 输出表格完整序列

CLI Layer    Output Layer    terminal/table    terminal/ansi    terminal/theme    stdout
   │              │               │               │               │             │
   ├─renderTable()┤               │               │               │             │
   │              ├─displayString()┤               │               │             │
   │              │◄──shortened──┤               │               │             │
   │              ├─resolveBorder()│               │               │             │
   │              ├─visibleWidth()┤               │               │             │
   │              │               ├─stripAnsi()──┤               │             │
   │              │               │◄─pure text──┤               │             │
   │              │               ├─splitGraphemes()┤            │             │
   │              │               │◄─grapheme[]─┤               │             │
   │              │               ├─graphemeWidth()┤             │             │
   │              │◄──width──────┤               │               │             │
   │              ├─calc widths   │               │               │             │
   │              ├─shrink/expand │               │               │             │
   │              ├─wrapLine()────┤               │               │             │
   │              │               ├─splitGraphemes()┤             │             │
   │              │               ├─visibleWidth()┤               │             │
   │              ├─padCell()─────┤               │               │             │
   │              ├─assemble──────┤               │               │             │
   │◄──table str──┤               │               │               │             │
   ├─writer.write()─────────────────────────────────────────────────────────────┤
   │              │               │               │               │             │

9.2 程序退出终端恢复序列

Signal Handler    restore.ts    progress-line    stdin    stdout    Terminal
     │               │              │            │        │          │
     ├─restore()─────┤              │            │        │          │
     │               ├─clearLine()──┤            │        │          │
     │               │              ├─\r\x1b[2K──────────────────────┤
     │               │              │            │        │          │(进度行清除)
     │               ├─setRawMode(false)────────┤        │          │
     │               │              │            ├─exit──┤│          │(退出原始模式)
     │               ├─resume?()────────────────┤        │          │
     │               │              │            ├─read──┤│          │(恢复stdin)
     │               ├─RESET_SEQ─────────────────────────┤          │
     │               │              │            │        ├─\x1b[0m─┤(SGR重置)
     │               │              │            │        ├─\x1b[?25h┤(显示光标)
     │               │              │            │        ├─\x1b[?2004l┤(括号粘贴关)
     │               │              │            │        ├─...────┤│(其他重置)
     │◄──done────────┤              │            │        │          │
     │               │              │            │        │          │(终端正常)

---

十、安全模型深度审查

10.1 攻击面分析

攻击向量	入口函数	防御机制	CWE	状态
日志注入	sanitizeForLog	剥离 ANSI + C0 + DEL	CWE-117	✅ 已防御
终端逃逸	sanitizeTerminalText	剥离 ANSI + C0 + C1 + 可见化 \r\n\t	CWE-117	✅ 已防御
ANSI 注入（超链接）	formatTerminalLink	移除 label/URL 中的 ESC 字符	CWE-77	✅ 已防御
管道断裂崩溃	createSafeStreamWriter	EPIPE/EIO 捕获 + closed 状态	N/A	✅ 已防御
终端状态泄漏	restoreTerminalState	全面重置序列 + 双重 try-catch	N/A	✅ 已防御

10.2 sanitizeForLog vs sanitizeTerminalText 对比

特性	sanitizeForLog	sanitizeTerminalText
ANSI 剥离	✅	✅
C0 移除 (0x00-0x1F)	✅ 全部移除	✅ 移除（\r\n\t 除外）
C1 移除 (0x80-0x9F)	❌	✅
DEL 移除 (0x7F)	✅	✅ (在 C1 区间内)
\r\n\t 处理	直接移除	转义为 \\r \\n \\t
目标场景	日志文件（不可见）	终端单行显示（需可见证据）
宽度计算	无	无

10.3 formatTerminalLink 注入防御

const safeLabel = label.replaceAll(esc, "");  // 移除 ESC → 阻止嵌套超链接
const safeUrl = url.replaceAll(esc, "");      // 移除 ESC → 阻止 URL 中的控制序列

攻击场景：如果攻击者控制 label，可能尝试注入：

label = "click\x1b]8;;https://evil.com\x1b\\here\x1b]8;;\x1b\\"

防御：replaceAll(esc, "") 移除所有 ESC 字符，使得注入的 OSC-8 结构变为普通文本。

---

十一、性能特征分析

11.1 热路径与优化

函数	调用频率	算法复杂度	优化策略
visibleWidth	极高（每个表格单元格、每行换行计算）	O(n) n=字符串长度	无缓存（纯函数开销低）
stripAnsi	极高（visibleWidth 内部调用）	O(n) 正则替换	预编译正则（模块级常量）
splitGraphemes	高	O(n)	Intl.Segmenter 原生实现
renderTable	中	O(r×c×w) r=行数 c=列数 w=最大宽度	flex 弹性列宽减少换行
wrapLine (table)	高	O(n) n=token 数	Token 流式处理，单次遍历
note	低	O(n) n=消息长度	环境变量早期返回

11.2 内存特征

• 无堆分配热点：所有核心函数返回字符串/数字，不创建持久对象
• 闭包开销：createSafeStreamWriter 创建闭包（2个 boolean + 4个函数引用），开销极低
• 正则编译：ANSI_CSI_REGEX 和 OSC8_REGEX 在模块加载时编译一次，运行时无编译开销
• 字素分割：Intl.Segmenter 实例在模块加载时创建，全局复用

11.3 潜在性能风险

1. 超大表格：renderTable 对所有单元格调用 visibleWidth + wrapLine，千行表格可能产生延迟
2. 超长单词：splitLongWord 在极端情况下（兆级字符串）会创建大数组
3. graphemeWidth 的 Emoji 检测：emojiLikePattern.test() 使用 Unicode 属性转义，每次调用都执行完整匹配

---

十二、可维护性评估与改进建议

12.1 代码质量评分

维度	评分	说明
可读性	9/10	函数命名清晰，注释适度，逻辑流直观
可测试性	9/10	纯函数为主，mock 点清晰，边界条件覆盖全面
健壮性	9/10	EPIPE 容错、双重 try-catch、环境变量降级
一致性	8/10	note.ts 和 table.ts 各自独立的 wrapLine 实现（略冗余）
类型安全	7/10	links.ts 的 path 参数运行时可为 null/undefined（与类型声明矛盾）
文档	7/10	关键函数有 JSDoc，但部分内部函数缺少注释

12.2 改进建议

#	建议	优先级	影响
1	统一 wrapLine 实现：note.ts 和 table.ts 的换行逻辑高度相似但独立实现，建议抽取为共享的 ansi-aware-wrap.ts	P2	减少维护成本，确保换行行为一致
2	修复 links.ts 类型签名：path 参数应为 `string	undefined	null`，与运行时行为对齐
3	添加 graphemeWidth 缓存：对高频重复字符串（如表格列头）缓存宽度计算结果	P3	大表格性能优化
4	progress-line.ts 并发安全：添加原子操作或互斥机制，防止多个进度行注册的竞态	P2	多实例场景下的健壮性
5	isCopySensitiveToken 扩展：支持含空格的文件路径（如 "my file.txt"）和中文字符路径	P2	CJK 用户场景下的换行体验
6	table.ts wrapLine ANSI 状态恢复：换行时主动重新打开前缀 ANSI 样式，而非依赖终端的 SGR 状态机	P3	边缘场景的渲染正确性