feat: 字体与高亮系统改进（CJK 对齐、ReDoS 防护、链接规则、崩溃类设置修复）
CI / typecheck + test + build (windows) (push) Canceled after 0s
CI / typecheck + test + build (windows) (push) Canceled after 0s
基于两轮专项调研（字体/高亮各两路，子代理实测探针交叉印证）实施的完整改进。
## 修复的真实 bug
**设置越界导致窗格永久死亡（用户报告）**
行高设 0.95 → xterm 构造/热更抛错 → 错误边界卸载整个 dockview 窗格；坏值已
落盘，每次重启都崩。根因是一整类缺陷：UI 允许值 / 配置能写值 与 xterm 硬约束
不一致，且主进程不校验。同类还有 scrollback<0（抛错）、cursorStyle 非法值
（更隐蔽：构造期被吞掉、只有热更期抛错，导致「重试」按钮永远无效、窗格死循环）。
修复：FONT_LIMITS/CURSOR_STYLES/RENDERER_MODES 收拢到 shared 层单一来源，
主进程加载时钳制 + 白名单化，healClampedFontSettings() 回写自愈；设置页
InputNumber、字体热键共用同一常量（照 LOCK_AUTO_DELAYS 先例，杜绝再次漂移）。
**perm 预设锚定失效**
^[-dlbcps]... 的 ^ 锚定的是「转义序列之间的 text run 起点」而非行首，ls -l
多行输出只有第一行权限位上色；带颜色的 ls（run 以转义切开）完全不触发。
改为 (?<=^|\s)[-dlbcps][rwxstST-]{9}(?![rwxstST-])——用负向前瞻而不是
(?=\s|$) 是因为后者会让带 ACL `+` / macOS `@` 后缀的真实 ls -l 输出不再染色。
旧 pattern 登记进 LEGACY_BUILTIN_PATTERNS，存量安装下次启动自动升级。
**高亮 span 吃掉应用自身 SGR**
wrap 固定追加 \x1b[0m，把应用设的颜色一并清掉。改为 SgrState 跟踪并重放。
四条护栏（每条都踩过坑，详见 AGENTS.md）：
- reset 判定解析参数：ESC[00m/ESC[0;0m/ESC[0;32m（Go/Java 日志库常写）原先
被追加进累积器，逐行增长直到撞上限，之后所有 span 恢复永久失效
- 回放闸门按序列条数而非字节数：同一个"单个前景色"长度差近 4 倍，按字节卡
会砍掉真彩色却放过索引色
- 恢复串只插在可见间隙和最后一个 span 后：每 span 都重放会让 Kimi 这类全彩
TUI（~19 span/行）把 9.5KB 输出膨胀到 40.8KB（4.30x），渲染线程实测卡
18.4 秒。现为 3.05x 且长间隙着色正常
- 基准测试守门（膨胀 < 3.2x），改参数必须重跑
**CSI 私有参数导致整行失去高亮**
ESCAPE_RE 漏了 <>= 前缀与中间字节，\x1b[>4;1m(modifyOtherKeys)、
\x1b[<0;1;2M(SGR 鼠标)、\x1b[=1;1$y(DECRQM) 让整行成含裸 ESC 的文本，该行
之后所有关键词失去高亮（vim/tmux 常发）。
**超长行拖垮整段高亮**：一条 >4KB 的行让整个 text run 失去高亮。改为逐行降级。
**统计「最后写入者赢」**：模块级 totals 被各 pane 覆盖，设置页数据在窗格间
跳动。改为按 pane 实例 UUID 聚合（不能用 sessionId——SSH 分屏同一 session 挂
两个 pane，正好复制该 bug）。
## 新增能力
- **CJK 对齐三件套**：@xterm/addon-unicode11@0.10.0-beta.301（peer 恰好接受
锁定的 6.1.0-beta.304，升 xterm 必须同步重配）、rescaleOverlappingGlyphs、
cjkFontFamily 回退槽位。默认字体栈没有任何 CJK 字体，中文靠 Chromium 回退
到比例字体导致列错位
- **字体名引号包裹**：quoteFontStack() 逐段判定（含反斜杠转义——只转义 " 会
让尾部反斜杠把闭合引号转义掉，CSS 字符串不终止）
- **等宽徽标**：canvas measureText 逐字符采样，等宽排前
- **规则按行匹配**（lineAnchor → m flag）
- **命中提醒**（notify + onMatch 事件出口，60s 冷却，只显示规则名不显示原文）
- **可点击链接规则**（WezTerm hyperlink_rules 式，安全闸门在生成 span 时就
丢弃非 http/https 目标）
## 其它
- 主题语义变量改为单一命名体系：semanticVars() 键就是最终 CSS 属性名，字面量
键联合让拼错成为编译错误；删除 cssVarName()/semanticCssVars() 中间层
（自定义属性名大小写敏感，转换被绕过会静默回落到深色兜底值）
- 删除死代码：automaticFontFallback 与顶层 overviewRuler 在 6.1.0-beta.304
中均不存在，且移除了让任何伪造键都能通过 tsc 的 as 断言
- ReDoS 防护（MAX_PATTERN_LEN + 编辑器 backtracksBadly 实时探测）——注意这
只是止血，(a+)+$ 配 30 字符实测仍卡 8.2 秒，根治需把正则执行挪进 Worker
测试 29 → 32（新增 font-stack、link-rules），全部通过；AGENTS.md 已同步。
This commit is contained in:
Bill committed
1 parent
619e4ac57f
commit
cee616a23a
29 files changed
+3071
-216
No files matched your search
@@ -7,10 +7,10 @@ Electron + electron-vite + React 终端工具（本地终端 / SSH / SFTP）。
|
||||
- 开发：`npm run dev`（主进程改动不热重建，需重启）
|
||||
- dev 实例使用独立用户数据目录 `%APPDATA%\OpenTerminal-dev` 与独立单实例锁（`src/main/index.ts` 顶部 `!app.isPackaged` 分支），窗口标题带 `(dev)`：**可与已安装的正式版同时运行，互不干扰**，也不会把测试设置/会话写进真实配置
|
||||
- 类型检查：`npm run typecheck`（tsconfig.node.json + tsconfig.web.json；只看渲染层可单跑 `npx tsc --noEmit -p tsconfig.web.json`）
|
||||
- 测试：`npm test`（**npm 生命周期先自动跑 `pretest` 做类型检查**，再 `node tests/build-bundles.cjs` 重建 esbuild bundle，然后依次跑可离线运行的 29 个测试：ssh-loopback、commands-store、connections-store、settings-store、local-path-grants、lock-store、lock-controller、lock-shortcuts、reserved-accelerators、terminal-title、ipc-guard、updater-fallback、log-sanitizer、app-log、sftp-timeout、hl-split-smoke、hl-rules、zmodem-e2e、ssh-session-e2e、sysinfo-e2e、terminal-cwd、terminal-links、broadcast-store、write-batcher、refit-throttle、semantic-theme、theme-contrast、css-theme-vars、ot-var-names；真实服务器测试需 JD_* 凭据，不在此列）。其中渲染层纯函数测试（semantic-theme、theme-contrast、ot-var-names、write-batcher、refit-throttle、broadcast-store、terminal-cwd、terminal-links、terminal-title、hl-split-smoke、hl-rules 等）用 Node 22.18+ 的原生 TS 类型剥离**直接 import `.ts` 源文件**（不经 esbuild bundle），Node 20/22.17 以下会 `ERR_UNKNOWN_FILE_EXTENSION`
|
||||
- 测试：`npm test`（**npm 生命周期先自动跑 `pretest` 做类型检查**，再 `node tests/build-bundles.cjs` 重建 esbuild bundle，然后依次跑可离线运行的 31 个测试：ssh-loopback、commands-store、connections-store、settings-store、local-path-grants、lock-store、lock-controller、lock-shortcuts、reserved-accelerators、terminal-title、ipc-guard、updater-fallback、log-sanitizer、app-log、sftp-timeout、hl-split-smoke、hl-rules、zmodem-e2e、ssh-session-e2e、sysinfo-e2e、terminal-cwd、terminal-links、broadcast-store、write-batcher、refit-throttle、semantic-theme、theme-contrast、css-theme-vars、ot-var-names、font-stack、link-rules；真实服务器测试需 JD_* 凭据，不在此列）。其中渲染层纯函数测试（semantic-theme、theme-contrast、ot-var-names、font-stack、write-batcher、refit-throttle、broadcast-store、terminal-cwd、terminal-links、terminal-title、hl-split-smoke、hl-rules、link-rules 等）用 Node 22.18+ 的原生 TS 类型剥离**直接 import `.ts` 源文件**（不经 esbuild bundle），Node 20/22.17 以下会 `ERR_UNKNOWN_FILE_EXTENSION`
|
||||
- 依赖分类规则：**只有 `src/main/`/`src/preload/` 实际 import 的包才能进 `dependencies`**（node-pty/ssh2/zmodem.js/font-list/electron-updater）；纯渲染层依赖一律 devDependencies（Vite 全量打包进 out/renderer，`externalizeDepsPlugin` 不作用渲染层）——这条让 asar 从 98MB 瘦到 8.1MB，加新依赖时别放错边
|
||||
- 下载量统计：`node scripts/download-stats.cjs`（Gitea + GitHub release 资产的 download_count 汇总；GitHub 优先直连、失败自动回退 `HTTPS_PROXY`/本地 7897；更新通道无计数接口不计入）
|
||||
- 打包：`npm run dist`（**生命周期先自动跑 `predist` → `npm test`，即类型检查 + 29 个离线测试全部通过后才 build/package**，typecheck 全程只跑一次；predist 末尾的 `npm install --package-lock-only` 会把 `package-lock.json` 根版本号对齐 `package.json`，**发布提交必须带上 package-lock.json**），产物在 `release/`（exe + latest.yml + blockmap）
|
||||
- 打包：`npm run dist`（**生命周期先自动跑 `predist` → `npm test`，即类型检查 + 31 个离线测试全部通过后才 build/package**，typecheck 全程只跑一次；predist 末尾的 `npm install --package-lock-only` 会把 `package-lock.json` 根版本号对齐 `package.json`，**发布提交必须带上 package-lock.json**），产物在 `release/`（exe + latest.yml + blockmap）
|
||||
- GitHub Actions：`.github/workflows/ci.yml` 在 windows-latest + Node 22 上跑 `npm ci` / `npm test`（含 pretest typecheck）/ `npm run build`，只做验证，不打包安装器、不发布
|
||||
- 国内网络需镜像：`ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/ npm run dist`
|
||||
- 依赖一致性闸门：`predist` 开头跑 `node scripts/verify-deps.cjs`（逐条比对 `node_modules` 与 `package-lock.json` 的版本，跨平台 optional 依赖缺失跳过；不一致就 exit 1）——`npm install --package-lock-only` **只重算 lockfile、不碰 node_modules**（本版 npm 还会把 `node_modules/.package-lock.json` 一并重写成理想树，制造「已经装好了」的假象），所以**改动依赖版本后必须真实 `npm install` 或 `npm ci` 再构建**，别指望 lockfile 对齐就等于树里换了包；v1.0.21 的中文输入法回归正是这个坑（`@xterm/xterm` 锁 6.1.0-beta.304，树里还是 6.0.0，打进去的是旧代码）
|
||||
@@ -71,11 +71,19 @@ Electron + electron-vite + React 终端工具（本地终端 / SSH / SFTP）。
|
||||
## 主题机制
|
||||
|
||||
- 终端主题由 xterm 主题派生 UI 配色：`src/renderer/src/theme/chrome.ts` 的 `applyChromeTheme` 写入 `--chrome-bg/-bg-deep/-border/-hover` CSS 变量，antd token 在 `main.tsx` ThemedConfigProvider 派生
|
||||
- **语义变量层（2026-10 主题改造）**：`src/renderer/src/theme/semantic.ts`（**零 import 纯模块**——`tests/semantic-theme.mjs` 经 Node 原生类型剥离直连它，加 import 前先想清楚）导出 `isLightTheme`/`mix`/`luminance`/`contrast`/`darkenToRatio`/`SEMANTIC` 锚点；`chrome.ts` 的 `applyChromeTheme` 随主题派生 `--ot-*` 变量并写 `color-scheme: dark|light`（原生滚动条/表单跟随）。**深色分支锁 SEMANTIC 锚点原值（零回归），浅色分支 `darkenToRatio` 按 WCAG 派生**（正文/-fg ≥4.5:1，语义基色 ≥3:1）。CSS 一律 `var(--ot-*, 锚点兜底)`，新代码禁止裸颜色字面量——`node tests/css-theme-vars.mjs` fail-closed 扫描（剥注释/color-mix/var 兜底走受控清单 FALLBACK_OK，跳过含 `${` 的模板串行，白名单按「文件+精确值」登记在测试内）；**canvas 绘制吃不到 CSS 变量**（`ctx.strokeStyle` 不解析 var()），图表类组件用 `useResolvedTheme()` + `semanticVars()` 取实色（MonitorPanel 的做法）。**变量名大小写敏感**：`semanticVars()` 的键是 camelCase 而 CSS 读的是 kebab-case，`chrome.ts` 必须经 `semanticCssVars()`（内部 `cssVarName()`）转换后再写——直接写 camelCase 名**不报错**，只是该变量永不生效、元素静默回落到 `:root` 的深色兜底值（浅色主题就这么坏过一轮：`--ot-text-muted` 等 9 个多词变量全部没生效）。`node tests/ot-var-names.mjs` 把「CSS 引用名 = JS 写入名 = global.css `:root` 声明名」三个集合锁在一起——**值测试（semantic-theme/theme-contrast）看不出这类问题**，改语义层时别只跑它们
|
||||
- **语义变量层（2026-10 主题改造）**：`src/renderer/src/theme/semantic.ts`（**零 import 纯模块**——`tests/semantic-theme.mjs` 经 Node 原生类型剥离直连它，加 import 前先想清楚）导出 `isLightTheme`/`mix`/`luminance`/`contrast`/`darkenToRatio`/`SEMANTIC` 锚点 + `OtVarName`/`SemanticVars` 类型；`chrome.ts` 的 `applyChromeTheme` 随主题派生 `--ot-*` 变量并写 `color-scheme: dark|light`（原生滚动条/表单跟随）。**深色分支锁 SEMANTIC 锚点原值（零回归），浅色分支 `darkenToRatio` 按 WCAG 派生**（正文/-fg ≥4.5:1，语义基色 ≥3:1）。CSS 一律 `var(--ot-*, 锚点兜底)`，新代码禁止裸颜色字面量——`node tests/css-theme-vars.mjs` fail-closed 扫描（剥注释/color-mix/var 兜底走受控清单 FALLBACK_OK，跳过含 `${` 的模板串行，白名单按「文件+精确值」登记在测试内）；**canvas 绘制吃不到 CSS 变量**（`ctx.strokeStyle` 不解析 var()），图表类组件用 `useResolvedTheme()` + `semanticVars()` 取实色（MonitorPanel 的做法）。**单一命名体系（v1.0.29 修复）**：`semanticVars()` 的键**就是最终 CSS 自定义属性名**（`'--ot-text-muted'`），返回类型 `SemanticVars = Record<OtVarName | 'color-scheme', string>` 是字面量键联合——**曾经是 camelCase 键 + `cssVarName()`/`semanticCssVars()` 转换桥，自定义属性名大小写敏感，转换一被绕过就静默回落到 `:root` 深色兜底值（浅色主题下 `--ot-text-muted` 等 9 个多词变量全部没生效过一轮）**；现在中间层已删除，键名拼错在读取处直接是 TS 类型错误，`node tests/ot-var-names.mjs` 另外断言每个键匹配 `/^--ot-[a-z0-9-]+$/`（camelCase 混回来即 FAIL）并把「CSS 引用名 = JS 写入名 = global.css `:root` 声明名」三个集合锁在一起——**值测试（semantic-theme/theme-contrast）看不出这类问题**，改语义层时别只跑它们。加变量时 `OtVarName` 联合与 `semanticVars()` 两个分支三处一起改
|
||||
- **浅色主题可读性**：内置浅色主题 ANSI 调色板已重做，16 色+fg 全部 ≥4.5:1（`node tests/theme-contrast.mjs` 守门，改浅色主题必须过它；改色用 `darkenToRatio` 统一加深算法，不许手挑色）；`minimumContrastRatio` 按「背景图 4.5｜浅色无图 4.5｜深色无图 1」矩阵（构造+热更两处都要改），`drawBoldTextInBrightColors` 浅色关闭；WebGL 渲染器同样执行 MCR（addon-webgl 自带 `_getMinimumContrastColor` 对比度路径，已核实）；antd 算法随 `isLightTheme` 切 `defaultAlgorithm`/`darkAlgorithm`（**antd 没有 lightAlgorithm，浅色就是默认算法**）；github-light 底色已柔化 `#f6f8fa`
|
||||
- 标签强调色：`settings.tabAccentColor`（默认 `#3fb950`），经 `--tab-accent` CSS 变量生效；`--tab-accent-fg` 是强调底上的文字色（明暗自适应，选中态按钮文字也用它）
|
||||
- 背景图（`settings.terminal.backgroundImage`）：图片层 `.term-bg-image` 在 xterm 画布之下（`terminal.css`），xterm 背景设 `#00000000` 透明。**图片模式下的三条铁律**：① `.terminal-view.has-bg-image .terminal-view-dock` 强制深色底衬 `#0d1117`，不能用 `--chrome-bg`——浅色主题下它是白色，调低透明度会把图洗白而不是压暗；② `minimumContrastRatio` 从 1 提到 4.5（WCAG AA，与 VS Code 终端默认值一致；TerminalView 构造与设置热更两处都要改；注意正确拼写是 `minimumContrastRatio`，`minContrastRatio` 会被静默忽略），xterm 的对比度计算把透明背景当黑色亮度，会把浅色主题的深色前景自动提亮到可读。无图时保持 1 不动主题配色。③ 压暗层（`settings.terminal.backgroundImageDim`，0–90，**默认 0**）：`.term-bg-dim` 纯黑 scrim 在 DOM 序上位于 `.term-bg-image` 之后、xterm（z-index:1）之下（同在 z-index:0 层，靠 DOM 序压图），与透明度的区别是透明度把图与深色底衬混合、压暗在图之上叠黑（保饱和但整体变暗）；**dim=0 时 TerminalView 不渲染该层，零成本**
|
||||
|
||||
## 终端字体
|
||||
|
||||
- **引号包裹在消费点做，settings 存原样**：`src/renderer/src/terminal/fontStack.ts` 的 `quoteFontStack`（零 import 纯模块，`tests/font-stack.mjs` 直连）把字体栈逐段判定——裸标识符合法且非 CSS 关键字则裸写，其余（含空格/括号/`+`/非 ASCII/数字开头）双引号包裹，幂等。**只在传给 xterm（构造+热更）与预览 inline style 时调用**，settings.json 里保持用户原文。枚举端 `font-list` 的 `disableQuoting: true` 不动
|
||||
- **CJK 回退槽位**：`settings.terminal.cjkFontFamily`（默认 `''`=不追加）。TerminalView 的 `appendCjk` 先拼栈再 `quoteFontStack`（追加在引号包裹**之前**，一次切分）。fontOpts 的 useShallow 选择器含该字段，改中文字体即时热更
|
||||
- **`@xterm/addon-unicode11@0.10.0-beta.301` 精确锁定**（devDependencies）：peer 恰好接受 `6.1.0-beta.304`，**升 xterm 必须同步重配 addon 版本**（beta.302+ 的 peer 已不接受 304）。`term.loadAddon` 后 `unicode.activeVersion = '11'`；addon 随 `term.dispose()` 连带清理（AddonManager 已注册），不用单独存 ref
|
||||
- `rescaleOverlappingGlyphs: true`（**仅 WebGL 渲染器有效**，DOM 渲染器按浏览器布局不受影响）——把超出 cell 步进的字形压回格内，box-drawing/CJK 宽字符不再压到邻格
|
||||
- 字体下拉等宽徽标：SettingsTabs 用离屏 canvas `measureText` 逐字符采样（`i1l.,:;|Wm0@`，容差 0.01，测失败判非等宽）——误判只会漏徽标不会错标；等宽排前面、「默认」永远第一；`filterOption` 只匹配 `searchText ?? value`，徽标文本不进搜索
|
||||
|
||||
## 终端尺寸同步
|
||||
|
||||
- `TerminalView.scheduleFit`：fit 后**去抖 100ms** 再把 cols/rows 发给 PTY，并跳过与上次相同的尺寸。每次 ResizeObserver 都戳 PTY 会让全屏 TUI（Claude Code 等）在最大化/还原的中间尺寸上反复重绘，留下重复帧
|
||||
@@ -133,6 +141,16 @@ Electron + electron-vite + React 终端工具（本地终端 / SSH / SFTP）。
|
||||
- 上下文敏感的规则用 **lookbehind/lookahead 只圈住关键词本身**，否则分级会读到错误的数字：`(?<=\bHTTP/\d(?:\.\d)?\s)[1-5]\d\d\b` 让 `HTTP/1.1 404` 只着色 `404`（若把 `HTTP/1.1` 一起匹配，bands 会读到版本号 `1`）。同理 `[1-5]\d\d(?=\s+OK|…)` 靠先行断言限定"后面跟原因短语"才算状态码，避免把 `123` 这类普通数字当成 404
|
||||
- 裸 3 位数（`[1-5]\d\d`）**不能单独成规则**，必须有上下文锚点；同理 MAC、短哈希这类高误伤模式不进预设
|
||||
- 导入 / 导出与实时预览：`src/shared/highlightIO.ts` 管 JSON 信封（`kind`/`version`，外来 JSON 直接拒绝）与 replace/append 合并；渲染层用剪贴板 + FileReader + Blob 下载完成，**不新增 IPC**。编辑器预览走引擎的 `previewSpans`（跑真实高亮再解析它自己的 SGR 输出），并且**带上当前其它规则**，这样 span 被别的规则抢走时能一眼看出来
|
||||
- **锚定语义（改预设 `^…` 前必读）**：规则只作用于「转义序列之间的 text run」，且默认**没有 `m` flag**——裸 `^` 锚定 run 起点而非行首（`perm` 预设曾因此整类失效）。行首锚定用 lookbehind `(?<=^|\s)`；规则可开 `lineAnchor: true`（schema 字段，编译成 `gm`/`gim`，编辑器有「按行匹配」开关，徽标 `^$`），让用户的 `^ERROR$` 按行生效
|
||||
- **span 结束恢复应用 SGR**：引擎给命中 span 收尾时不再是裸 `\x1b[0m`，而是 `\x1b[0m` + 重放进入 span 前活跃的 SGR 序列。状态由 `HighlightStream` 持有并跨 push 传递——`hl-split-smoke` 的逐切分点字节一致依赖这一点，动 `applyHighlights` 第 4 参（sgr 状态）签名前先想清楚。四条护栏（全部踩过坑，别拆）：
|
||||
- **reset 判定必须解析参数**，不能字符串全等。ECMA-48 里 `ESC[m`/`ESC[0m`/`ESC[00m`/`ESC[0;0m` 都是全量复位，`ESC[0;32m`（复位+设色，Go/Java 日志库常写）要先清空再记录新色。只认两种规范写法会让其它拼法被**追加**进累积器，每行涨几字节直到撞上上限，之后所有 span 的恢复永久失效
|
||||
- **回放闸门按序列条数**（`MAX_REPLAY_SEQUENCES=3`）而不是字节数。同一个「单个前景色」的写法长度差近 4 倍（`ESC[31m` 5B / `ESC[38;5;196m` 11B / 真彩色 13–19B），按字节卡会砍掉真彩色却放过索引色，语义不一致。`MAX_RESTORE_LEN=256` 只是累积器的内存上限
|
||||
- **恢复串只插在「可见间隙」前后**（`MIN_GAP_FOR_RESTORE=3` 个可见字符），不是每个 span 后。Kimi 这类全彩 TUI 一行 ~19 个 span，每 span 都重放会让 9.5KB 输出膨胀到 40.8KB（**4.30x**，无恢复时 2.78x），下游 xterm 解析 + WebGL 字形图集（背景图模式 MCR=4.5 逐字形算对比度，真彩色让缓存全 miss）被压垮，实测渲染线程卡 **18.4 秒**（日志 `[renderer] main thread stalled ~18384ms`）。现在的实现：最后一个 span 后必恢复，中间间隙够长才恢复，膨胀 3.05x 且长间隙着色正常
|
||||
- **改以上任何参数必须重跑 `[restore cost budget]` 基准段**（`tests/hl-rules.mjs`，断言密集真彩色 TUI 膨胀 < 3.2x）。功能性用例全绿不代表热路径没回归——`hl-split-smoke` 的样本每行以 reset 结尾，恰好绕过了这类膨胀
|
||||
- **CSI 参数类必须含私有前缀与中间字节**：`ESCAPE_RE` 的 CSI 分支是 `[0-9;:?<>=]*[ -/]*[A-Za-z]`。漏掉 `<`/`>`/`=` 和中间字节（`ESC[>4;1m` modifyOtherKeys、`ESC[<0;1;2M` SGR 鼠标、`ESC[=1;1$y` DECRQM）会让整行被当成含裸 ESC 的文本透传，**该行之后直到下一个换行的所有关键词全部失去高亮**——vim/tmux 在鼠标与按键上报时正好发这些序列
|
||||
- **用户正则没有真正的 ReDoS 防护**：`MAX_LINE_LEN=4KB` 限的是长度不是回溯成本——`(a+)+$` 配 30 个字符实测卡 **8.2 秒**（28 字符 2 秒，指数级）。现有防线是 `MAX_PATTERN_LEN=500` 限幅 + 编辑器 `backtracksBadly()` 探测（用 4 组诱发输入实跑，超 50ms 预算就提示），**都拦不住真正的灾难性回溯**。要正解需把预览/执行挪进 Worker 加超时，已列为待办
|
||||
- **超长行按行降级**：run 无 >4KB 行时走整段扫描（保留跨行匹配）；有则按 `\n` 逐行，>4KB 的行原样透传不上色（该 run 内跨行匹配放弃）。回溯防护不变式：**任何 >4KB 的行不进用户正则**
|
||||
- **统计按 pane 实例聚合**：`highlightStats.ts` 按 pane id（`crypto.randomUUID()`，**不是 sessionId**——SSH 分屏同一 session 挂两 pane）登记各自 sink，订阅方拿跨 pane 求和；卸载与关统计开关都要注销，重绑定（rebind）**不**注销（React 先跑完 cleanups 再 setups，在那里注销会让 pane 从汇总消失一拍）。重置清各 pane 的真实计数器
|
||||
- 分类（`category`，`safety|status|file|net|text|metric`）：预设的分类放在 `PRESET_CATEGORIES` 一张表里，`basic` 集合必须始终是 safety+status 的子集（有测试守）；`settings.terminal.highlightGroupByCategory` 只影响设置页（加分类列 + 按分类聚簇，组内仍按 priority），**热路径完全不涉及**
|
||||
- 跟随主题（`settings.terminal.highlightThemeColors`，默认关）：`src/renderer/src/theme/highlightColors.ts` 按**色相分桶**把规则颜色映射到当前主题的 ANSI 调色板（不用"最近色"，否则语义会漂移），亮度决定用普通色还是 bright 色（这样 percent 的两档绿仍能区分）；饱和度低于 0.15 的中性色保持原样；**背景色不映射**（它是文字底块，不是语义信号）。映射在编译期一次性完成，热路径零成本；编辑器预览走同一函数，否则预览会与终端不一致
|
||||
- 统计（`settings.terminal.highlightStats`，默认关）：引擎的 `applyHighlights`/`HighlightStream` 接受可选 `StatsSink`，**只在传了 sink 时才计数与计时**（默认路径不插桩）；`TerminalView` 只在开关打开时挂 sink，并**每秒发布一次快照**（不是每块），否则忙碌的终端会把设置页重渲染到卡死；设置页通过 `subscribeHighlightStats` 订阅，多出「命中/耗时」两列（耗时按 µs/ms 格式化）
|
||||
@@ -143,3 +161,15 @@ Electron + electron-vite + React 终端工具（本地终端 / SSH / SFTP）。
|
||||
- `caseInsensitive: true` 的规则编译成 `gi`（规则级开关，默认关闭）；预设里 `okstate` 带 `(?<!not\s)` 反向断言，把 `not ok` 让给 `badstate`
|
||||
- 词边界是这套预设的全部难点：新增关键词后请跑 `node tests/.hl-rules.cjs`（`invalid` 不能点亮 `valid`、`disabled` 不能点亮 `enabled` 等）
|
||||
- 升级旧安装：`settingsStore.refreshBuiltinRules` 只把**仍是出厂 pattern** 的内置规则升到新预设（保留用户的颜色/优先级/启停），且仅当规则集恰好等于旧预设集时才追加新增的内置规则——否则用户删掉的规则会每次加载都复活。改预设 pattern 时同步更新 `LEGACY_BUILTIN_PATTERNS` / `LEGACY_BUILTIN_IDS`
|
||||
|
||||
## 可点击链接规则
|
||||
|
||||
- 内置链接（`src/renderer/src/terminal/urlLinks.ts` 的 `findUrls`，4 条写死的正则：http(s) / ftp / `www.` / 裸 host:port）**不动**；用户自定义规则是叠加在其上的第二来源
|
||||
- 引擎在 `src/shared/linkRules.ts`（**零 import 纯模块**，`tests/link-rules.mjs` 直连）：`sanitizeLinkRules` 清洗（id/pattern/template 必填、非法正则丢弃、模板空串丢弃、`enabled` 缺省为 true、note 截断 60、上限 100 条）、`formatLinkTemplate` 展开模板（`$0` 整段 / `$1`–`$9` 分组 / `$$` 字面 `$`，**只吃一位数字**所以 `$10` = 分组 1 + 字面 `0`，未参与分组展开为空串而非 `undefined`）、`compileLinkRules`、`findRuleLinks`、`mergeLinkSpans`
|
||||
- **安全闸门 = `isSafeLinkTarget`（同文件）**：生成 span 时就把非 `http:`/`https:` 目标丢掉，`file://` / `javascript:` / `ms-settings:` / 相对路径连下划线都不会出现（不是等点开才拦）。主进程 `openExternal` 的协议白名单是第二道，两个都要在
|
||||
- 接线点在 `TerminalView.tsx` 的 link provider：`mergeLinkSpans(findRuleLinks(text, linkRulesRef.current), findUrls(text))`——**用户规则优先，重叠的内置链接让位**；hover 提示 `text: link.url` 显示的是展开后的真实目标
|
||||
- **热更走 `linkRulesRef`**（照 `streamRef.setRules` / `notifyRulesRef` 的模式）：provider 随终端注册一次，改规则只换 ref 指向，绝不重建终端。`EMPTY_LINK_RULES` 是共享的稳定空数组——选择器返回新建的 `[]` 会让 zustand 每次拿到新身份，任何无关设置写入都会重渲染所有 pane
|
||||
- 性能护栏：`LINK_TEXT_MAX` 4KB 以上的逻辑行整行跳过（内置正则是固定集合，用户正则可回溯爆炸）；每规则每行上限 200 个匹配；能匹配空串的 pattern 强制 `lastIndex` 前进，避免死循环
|
||||
- UI 在 `HighlightTab.tsx` 底部的 `ClickableLinkRules`（与高亮同属「终端输出的模式匹配」心智）：表格（启用/正则/模板/操作）+ 编辑弹窗（pattern 非法正则内联报错、template 非 http(s) 内联报错、note、启用）。导入导出与 profile 联动**尚未做**，属后续可加
|
||||
- 设置字段 `AppSettings.linkRules?: LinkRule[]`（可选，默认 `[]`）；三处接线照 `highlightProfiles`：`src/main/settingsStore.ts` 的 `deepMerge` 分支 + `sanitizeLinkRules` 调用 + `defaultSettings()`，渲染层 `settings/store.ts` 的 `setLinkRules` + persist 白名单
|
||||
- 测试：`node tests/link-rules.mjs`
|
||||
Reference in new issue
Block a user