29 KiB
对比工具模块规划(Diff Module Plan)
状态:P4 已落地(选项卡 / 左右双树 / 下钻 / 快捷键 / 中间列快速替换) 本轮决策(2026-10-13,用户已拍板):移除 devtools 的文本对比工具(并入本模块)· 目录对比暂不做写回(只读浏览)· 需要拖入支持 P4 决策(用户提出,2026-10-13):选项卡式会话(标题
左 ↔ 右)· 目录对比改为左右两棵结构树(两侧路径可自由输入 + 图标按钮)· 点树里的文件新开文件选项卡 · 全局快捷键 Alt+C · 中间列差异 + 快速替换(参考 Beyond Compare) 定位:Thing 工具集的第 14 个模块,id = diff,category = 'tool'作者:砚 | 日期:2026-10-13 关联文档:AI_DEV_GUIDE.md(模块注册 / IPC / 独立窗口范式)、UI_DESIGN_SYSTEM.md(页面框架 / 组件规范)、EDITOR_MODULE_PLAN.md(CM6 装配 / 编码探测 / 独立窗口 / 任务栏身份范式)、TERMINAL_MODULE_PLAN.md(拖放补注入范式)
阅读顺序:§9 开工清单(执行入口)→ §0 结论 → §4 技术选型 → §6 文件清单 → §8 分期。
0. 结论先行
六个关键判断。
-
可行,且仓库里已有大半基础设施。 编辑器模块已经把「CM6 + 主题系统 + 多语言高亮」「带编码探测的文件读取」「递归遍历(
walkdir已在依赖树)」「独立窗口 + 任务栏身份 + 拖放补注入」四块能力做完了。本模块的主要工作是组装,而不是造轮子。 -
做成独立模块 + 独立窗口,不塞进编辑器。 编辑器模块的中心对象是「一篇文档的生命周期」(标签、自动保存、光标、会话恢复);对比工具是「两个只读视图 + 一棵目录树」,没有自动保存、没有文档标签。混进去会让本已很大的
EditorWindow.vue(1500 行)与editorStore.ts继续膨胀,也会让editor-window-*这个 capability 的语义变模糊。模块体系是现成的(moduleConfig+ 一行注册 + 图标表 + 搜索索引 + 启用开关),独立成模块成本很低。 -
渲染层用
@codemirror/merge(CM6 官方 MergeView),计算层留在 Rust。 MergeView 天然给出并排 / 统一视图、块级高亮、chunk 跳转、接受/拒绝,并且直接吃项目现有的 CM6 主题(编辑器那九套配色自动跟随,无需为对比工具再维护一套配色)。Rust 只负责目录级扫描与分类:walkdir递归 + size/mtime 快速路径 + 按需内容比对。这样目录对比的每一项都能「点一下」下钻到 MergeView 的文件级对比 —— 正是 Beyond Compare 的交互主线。 -
三层能力按「易 → 难」分期,P1 只做文本对比。 文本对比(粘贴两段)→ 文件对比(两个路径,含编码探测)→ 文件夹对比(递归树 + 三态分类 + 下钻)。P1 的价值不只是功能,更是验证
@codemirror/merge与项目现有 CM6 版本的兼容性(见 §10),风险最低、最快闭环。 -
目录对比这一期只读,不做写回。 「浏览差异」与「同步目录」是两个量级的工程:后者要处理冲突策略、部分失败回滚、覆盖确认、二进制文件、只读属性与长路径。这一期给出只读的三态树 + 下钻即可,写回(复制 / 镜像 / 双向同步)留待单独评估。
-
拖入支持从 P2 起生效。 文本对比没有文件路径,用不上拖放;P2 起需要把「拖文件进窗口」纳入。既有实现是编辑器专用的
editor/drag_drop.rs(不通用:它按 editor 窗口的 label 前缀做注入),因此本模块另建一份同构实现或把它泛化成按 label 前缀参数化(见 §7.1,倾向后者)。
1. 定位与边界
| 维度 | 说明 |
|---|---|
| 一句话 | 一个 Beyond Compare 式的对比工具:文本 / 文件 / 文件夹三层,左右双栏 |
| 中心对象 | 两个被比较的目标(一段文本、一个文件、一棵目录树),而不是某篇文档 |
| 首要入口 | 模块页「新建对比」+ 独立窗口(可拖入文件/文件夹) |
| 与编辑器模块的关系 | 复用它的 CM6 装配、主题与语言包、Rust 文件读取;但不共享窗口、不共享 store |
| 明确不做 | 不做三路合并(3-way merge)· 不做 Git 集成 · 本期不做目录写回/同步 · 不做二进制语义对比(只报「二进制不同」) |
2. 需求解构
| 用户原话 | 解构为 | 落点 |
|---|---|---|
| 「能够进行文本,文件,文件夹对比」 | 三种对比目标,同一条渲染管线 | §3.1 / §3.2 / §3.3 |
| 「左右两个窗口对比,参考 beyond compare」 | 并排双栏 + 块级高亮 + 差异导航 + 三态目录树 | §3.1 / §3.3 |
| 「调整…对比工具…做到编辑器里面还是单独做模块」 | 架构决策 → 独立模块 | §5 |
| 「去除 devtools 里的 diff」 | 删除 DiffTools.vue 及其注册项,能力并入本模块 |
§8 开工清单 |
| 「目录对比暂时不用写回」 | P3 只读三态树,不做复制/同步 | §3.3 / §9 |
| 「需要拖入支持」 | 拖文件/文件夹进窗口即作为某一侧目标 | §7.1 |
3. 能力规格
3.1 文本对比(P1)
- 左右两个可编辑的 CM6 视图,构成一个 MergeView;任一侧输入即重算差异。
- 差异呈现:行内块级高亮(左边「被删/被改」、右边「新增/被改」),行号槽标注变化。
- 差异导航:上一个 / 下一个差异(工具栏按钮;到两端即停,不做循环跳转)。
- 顶部工具栏:粘贴到某一侧(从剪贴板)、交换左右、差异导航、清空两侧。并排是唯一的视图形态(统一视图需要另一套渲染路径,留待后续评估)。
- 状态栏:
差异 N 处 · +A 行 · -R 行 · 左侧 X 行 / 右侧 Y 行。 - 大文本保护:不做「超过 N 行就不算」的硬阈值,改用 MergeView 内置的
diffConfig.scanLimit(默认 500)—— 它在差异过大时放弃精确比对、退回快速(不精确)算法,从而避开二次方耗时,同时仍然给出结果(比「停算并提示」更可用)。已知代价:极端输入下差异块可能不够精确(Chunk.precise为 false)。
3.2 文件对比(P2)
- 两个路径(任意磁盘文件,不限于笔记库),来源:文件对话框 / 拖入 / 命令行 / 编辑器「与…对比」。
- 编码感知:复用
editor::files::read_file(BOM → 严格 UTF-8 → chardetng 探测 → GB18030 兜底),状态栏显示两侧各自探测到的编码,不一致时给出提示(「左边 GBK / 右边 UTF-8」这类差异往往就是用户要找的问题)。 - 二进制文件:不渲染 diff,只报「二进制文件,大小 X vs Y,内容不同/相同」。
- 只读打开 + 可切换为可编辑;保存回写仅作用于被显式编辑的一侧(这一条属于 P2,不等同于 P3 的目录同步)。
- 拖入:拖文件到左半区 = 设为左侧目标,右半区 = 右侧目标。
3.3 文件夹对比(P3,只读)
- 递归遍历两侧,按相对路径对齐(根目录不同名也要对齐)。
- 每个条目三态 + 细分:
状态 判据 仅左侧有 右侧无同相对路径 仅右侧有 左侧无同相对路径 两侧都有 · 相同 size 相同 → mtime 相同 →(必要时)内容一致 两侧都有 · 不同 size 不同,或 size 相同但内容不同 目标类型不同 一侧是文件、另一侧是同名目录 - 树形展开 + 过滤(只看有差异 / 只看某一侧有)+ 「展开到下一个差异」。
- 目录级汇总:
N 项不同 · M 项仅左 · K 项仅右,可折叠跳过相同项。 - 点击「不同」的文件行 → 在同一个窗口下钻到 §3.2 的文件对比视图(带返回上一级)。
- 忽略规则(可选,P3 后期):
node_modules/.git等常见目录的默认忽略清单。
3.4 不做(本期明确划界)
- 目录写回 / 镜像 / 双向同步(用户已拍板暂不做)。
- 三路合并与冲突解决。
- 二进制内容级对比(只判「相同/不同」与大小)。
- 大文件(> 阈值)的完整 diff —— 降级为只报状态,不做行级对齐。
4. 技术选型
4.1 渲染层:@codemirror/merge(已安装 6.12.2)
| 方案 | 结论 | 理由 |
|---|---|---|
@codemirror/merge |
采用 | CM6 官方 MergeView:并排/统一、块级高亮、chunk 导航、接受/拒绝、行号 gutter 全部现成;与已装的 @codemirror/state 6.7.6 / view 6.43.x 同源;主题直接复用 editor/editor/themes.ts 的九套配色 |
Rust similar crate |
暂不引入 | 计算快、可单测,但并排对齐 UI 要自己写;P1/P2 用不到,等 P3 目录级需要「批量算文件差异摘要」时再评估 |
| 手写 LCS(原 devtools 实现) | 弃用 | O(n·m) DP 会卡死 UI,且没有对齐/高亮,已随 DiffTools.vue 一并移除 |
4.2 计算层:Rust 只做目录级
walkdir已在依赖树(Cargo.toml),递归扫描零新增成本。- 文件内容比对优先用 size → mtime → 内容 三级快速路径,避免几万文件目录下全量读盘。
- 需要内容级判定时可选
similar或 SHA-256(sha2已在依赖树)。
4.3 主题:复用编辑器配色,不新建一套
对比窗口必须与编辑器窗口「同深同浅、同配色」,否则用户从编辑器跳到对比会感到割裂。做法:直接调用 resolveEditorTheme / editorTypography / editorBackground,并沿用编辑器窗口那套「跟随主应用主题 / 配色方案」的深浅推导(EditorWindow.windowIsDark 的逻辑)。不需要在本模块重复维护配色表。
5. 模块化决策(编辑器内 vs 独立模块)
| 维度 | 放进编辑器 | 独立 diff 模块(采纳) |
|---|---|---|
| 中心对象 | 一篇文档的生命周期 | 两个被比较的目标 |
| 窗口形态 | 编辑器标签栏 + 编辑区 | 双栏 + 目录树(布局不兼容) |
| 状态 | 自动保存 / 脏标记 / 会话恢复 / 光标 | 无自动保存;目标是只读或被显式编辑 |
| capability 语义 | 「编辑笔记」 | 「对比」(授权范围各自清晰) |
| 代码影响面 | 继续膨胀 EditorWindow.vue / editorStore.ts |
新增独立目录,互不干扰 |
| 复用方式 | —— | 复用 CM6 装配 / 主题 / 语言包 / Rust 文件读取,不共享窗口与 store |
补充两条:
- 不做成 devtools 里的小工具:devtools 是「主窗口内的单页聚合」,双栏 + 目录树装不进那个壳,也没有空间与拖拽入口。
- 交叉入口(可选,P2 之后再评估):编辑器窗口加「与…对比」,把当前文档发给 diff 窗口。它只是锦上添花,不影响主体结构。
6. 架构与文件清单
主模块页(入口 / 进度) 独立窗口(双栏差异视图 / 目录三态树)
↓ Tauri IPC ↓
src-tauri/src/diff/ 命令层
↓
commands.rs 单文件读取 / 写回 / 路径类型探测 / 目录对比入口
scan.rs 目录对比:递归遍历 + 三态分类(三层判据,见 §7.3)
types.rs 回传前端的 DTO(与前端 types.ts 对齐)
↓
editor::files 文件读取与编码探测(**复用**,提升为 pub(crate))
src-tauri/src/drag_drop.rs 拖放补注入(**通用**,编辑器与对比窗口共用)
前端:
src/modules/diff/
index.ts moduleConfig(icon: 'diff',order 50)
DiffModule.vue 主模块页:入口 + 三层能力进度
DiffWindow.vue 独立窗口外壳:模式切换(文件 / 文本 ↔ 文件夹)+ 文件对比界面
openWindow.ts diff-window 创建入口(单例,隐藏创建 + 拖放补注入)
diffClient.ts 命令名唯一落点(照抄 editorClient.ts 范式)
types.ts 与 Rust DTO 对齐的类型(DiffStats / DiffFileDoc / DirDiffEntry / DirDiffReport / DiffSide)
components/
TextMergeView.vue MergeView 封装(P1;P2 增补 setTexts / getText / doc-changed)
DirDiffView.vue 目录对比视图(P3:工具行 / 根路径 / 过滤 / 三态树 / 汇总)
登记点:
src/modules/index.ts 注册 moduleConfig
src/modules/icons.ts 图标映射(diff → Diff)
src/main.ts 独立窗口路由表加一行 '#diff-window'(按前缀匹配,支持 ?path=)
src/lib/constants.ts WINDOWS.diffWindow
src-tauri/src/taskbar_identity.rs 新增 'diff' 窗口类型(AUMID + 组合图标)
src-tauri/capabilities/diff-window.json windows: ["diff-window"]
7. 关键实现细节
7.1 拖入支持(用户点名需要)
既有实现原先在 src-tauri/src/editor/drag_drop.rs,已泛化为 src-tauri/src/drag_drop.rs 的 window_attach_drag_drop(按传入 label 生效,日志标记为 drag-drop),编辑器窗口与对比窗口共用同一份实现 —— 泛化而非复制,避免第二份同构实现各自腐坏。
要点(两条实现路径的取舍已定:泛化):
| 事项 | 结论 |
|---|---|
| 命令 | window_attach_drag_drop(label),模块位于 crate 根部(不再属于 editor) |
| 调用时机 | 窗口创建后立即 fire-and-forget 调用(不能等 tauri://created:窗口创建过快时该事件可能早于监听注册而永远等不到)。Rust 侧自行重试等待子窗口就位 |
| 窗口配置 | dragDropEnabled: true |
| 落点分侧 | 前端按 drop 坐标分左右半边。坐标是物理像素,需除以 devicePixelRatio 再与 CSS 宽度比较 |
| 目录 | diff_read_file 会拒绝目录并提示「目录对比尚未开放」——不让用户拖了没反应 |
7.2 编码与二进制(P2)
- 读取复用
editor::files::read_file(path, max_mb):BOM → 严格 UTF-8 → chardetng 探测 → GB18030 兜底,并把「读到的编码 + 换行」成对记下来供写回原样还原。为此把editor::files提升为pub(crate)(跨模块复用,范式同terminal::local_fs)。 - 二进制由对比模块自己判定(
editor::files只负责解码,没有二进制概念):按头部 8KB 含 NUL 判定,与editor::grep的跳过判据完全一致 —— 否则会出现「搜索跳过了、对比工具却显示一堆乱码」这种自相矛盾的行为。判定为二进制后不读内容,只回元信息(避免把无意义字节解码成一大段乱码再走 IPC)。 - 两侧编码分别在各自头部以 chip 显示;编码不一致要在状态栏显式提示(这是真实场景里最常见的「看起来全是乱码差异」根因)。
- 尺寸两级:软阈值 5MB(置
large,供前端降级)、硬上限 16MB(直接拒绝)。硬上限比编辑器的每篇上限更严,因为对比窗口同时持有两侧内容。 - 大文件降级:
large已回传,前端目前只在TextMergeView里靠 MergeView 的scanLimit兜底(见 §7.4),更细的降级(关折叠 / 不做行级对齐)留待后续。
7.3 目录扫描性能与判据(P3)
三层判据(代价递增,能不打盘就不打盘):
- size 不同 → 直接判「不同」(大小都不同,内容不可能相同);
- size 相同且 mtime 相同 → 判「相同」;
- size 相同但 mtime 不同 → 才读内容逐字节比对。
第 3 步有预算:[MAX_CONTENT_COMPARES] = 2000 条、单文件 ≤ 4MB。超出后不再读盘,按
时间戳归入「不同」并把 content_compared 置 false —— 结论仍是「不同」,但界面会显式
标注「未比对内容」,不与已确认的差异用同一种语气呈现(不能把「按元数据的推测」包装成
「读过的结论」)。
其余边界:
- 条目上限 8000(
truncated标记 + 界面提示):再大就让用户缩小范围, 而不是把几十 MB 的 JSON 塞过 IPC。 - 不跟随符号链接(
walkdir默认):跟随会让「链接成的环」把遍历变成死循环。 - 跳过清单由前端给出(目录名、大小写不敏感、命中即整棵子树不遍历),默认清单与
editor模块的默认跳过清单一致,另有开关可关。后端只按清单执行 —— 同editor::grep把默认清单留在前端的取舍。 - 扫描是同步命令 + 前端异步等待(一次返回整棵树),不做进度事件:实测量级下 (几万条目)耗时在百毫秒到数秒,做进度事件的复杂度不值当。若将来真的出现分钟级扫描, 再改成分批回传。
- 返回扁平列表(不是树):递归类型在 specta 下会生成无穷展开的 TS 类型(同
editor::types::LibraryEntry的坑);树的组装、剪枝、排序都在前端。
7.4 大文本保护(P1)
旧的 devtools 实现是 3000 行、LCS O(n·m)、超限直接停算。P1 不设硬阈值:MergeView 的 diffConfig.scanLimit(默认 500)会在差异过大时放弃精确比对、退回快速但不精确的算法,避开二次方耗时且仍然给出结果。真要做「超大文件不做行级对齐」的降级,留到 P2/P3 与文件读取的 large 标记一并处理 —— 那时才有「一个真实的大文件」这个输入,而不是用户粘贴的文本。
7.5 窗口与任务栏身份
沿用编辑器窗口的范式:隐藏创建(避免深色主题下闪白)→ 应用主题与窗口效果 → window_set_taskbar_identity(独立任务栏按钮 + 组合图标)→ show()。任务栏身份必须在 show() 之前设置。
8. 分期路线图
P1 · 文本对比(已落地)
目标:双栏 MergeView 跑通,验证 @codemirror/merge 与项目 CM6 版本的兼容性。
已交付:
src/modules/diff/:index.ts(moduleConfig)+DiffModule.vue(主模块页)+DiffWindow.vue(独立窗口)+openWindow.ts+components/TextMergeView.vue+types.ts。src/modules/icons.ts加diff图标映射;src/modules/index.ts注册模块;src/main.ts加#diff-window路由。src-tauri/capabilities/diff-window.json(globdiff-window-*同源权限集)。src-tauri/src/taskbar_identity.rs新增diff类型(独立 AUMID + 双栏图形组合图标)。src/lib/constants.ts加WINDOWS.diffWindow。- 删除 devtools 的文本对比工具:
DiffTools.vue已删,tools/index.ts去掉元数据 / 图标 / 组件映射,devtools/index.ts计数 20 → 19。 - 依赖:
@codemirror/merge ^6.12.2(@codemirror/state 6.7.6未变,view 6.43.x补丁级同步)。 - 校验:
vue-tsc --noEmit、eslint、vite build、cargo check全部通过。
尚未验证:窗口在真实 Tauri 运行时的观感(滚动联动、mica 底色下的对比度、任务栏图标)需要跑一次 tauri dev 目视确认。
P2 · 文件对比(已落地)
已交付:
- Rust
src-tauri/src/diff/:mod.rs/types.rs(DiffFileDoc)/commands.rs(diff_read_file、diff_write_file)。读取复用editor::files::read_file(编码探测 / 换行归一 / 只读探测),读取即登记授权(于是「打开过就能保存」成立)。为此把editor::files提升为pub(crate)。 - 尺寸与二进制策略:软阈值 5MB(置
large)、硬上限 16MB(直接拒绝,对比窗口天生要同时持有两侧)、二进制按「头部 8KB 含 NUL」判定(与editor::grep同一判据),二进制不读内容只回元信息。 - 拖放泛化:
editor/drag_drop.rs→src-tauri/src/drag_drop.rs,命令改名window_attach_drag_drop,编辑器与对比窗口共用;diff/openWindow.ts创建后立即补注入。 diffClient.ts(命令名唯一落点)+types.ts扩展(DiffFileDoc/DiffSide)。TextMergeView增补setTexts/getText与doc-changed事件(程序化装载期间抑制,避免把装载记成用户编辑)。DiffWindow.vue:两侧头部(打开文件 / 保存 / 编码 chip / 只读 chip / 脏标记)、拖入分侧高亮、编码不一致提示、二进制概览面板(只比大小,不断言「内容相同」)、Ctrl+S单侧写回、关闭前三选一确认。DiffModule.vue主模块页把「文件对比」标为可用。- 校验:
cargo check、vue-tsc --noEmit、eslint、vite build全部通过。
已知取舍:
bindings.ts是run()里export_bindings()在 debug 构建时生成的,本次未跑tauri dev,因此其中仍留着旧的editorAttachDragDrop声明(无任何调用点);下次 debug 运行会自动重建。- 脏标记是布尔(改过即脏),「改了又撤销回原样」仍显示为脏 —— 方向安全(至多多一次关闭确认),换来的是每次按键不必把整篇文档
toString()出来比对。 - 单侧写回不检查另一侧是否也改了同一个文件(两侧选中同一路径时后保存的覆盖先保存的)。仍是未解决的边界 —— P3 的目录模式是只读的,不会走到这条路径。
P3 · 文件夹对比(已落地,只读)
已交付:
- Rust
diff/scan.rs:递归遍历(walkdir,不跟随符号链接)+ 三态分类 + 三层判据(见 §7.3)+ 跳过清单 + 条目上限。 diff/commands.rs增补diff_compare_dirs与diff_path_kind(后者用于「拖入 /?path=传进来的路径是文件还是目录」)。- 前端
diffClient.compareDirs/pathKind,types.ts增补DirDiffEntry/DirDiffReport/DirDiffStatus。 components/DirDiffView.vue:选两侧文件夹、跳过构建目录 / 比对内容两个开关、过滤(仅差异 / 全部 / 仅左侧 / 仅右侧)、树(目录在前、同名排序、可折叠、展开/折叠全部)、按子树剪枝、汇总栏(不同 / 仅左 / 仅右 / 相同 / 类型不一致 / 跳过目录数 / 耗时 / 截断提示)。DiffWindow.vue增加模式切换(文件 / 文本 ↔ 文件夹,各自记住自己的目标)、拖入按模式分派(目录模式取该侧根;拖文件取父目录)、点差异行下钻到文件对比 + 「返回目录对比」。- 校验:
cargo check、vue-tsc --noEmit、eslint、vite build全部通过(并核对h-6.5这类分数间距类确实被 Tailwind v4 生成)。
关键取舍(都在实现里写了理由):
- 切模式不能丢改动:目录模式下
TextMergeView被卸载,用户刚敲的内容只存在于 CM6 实例里。离开文件模式前先snapshotEdits()把脏侧的内容取进contentA/B,切回来时再灌回去(setTexts抑制doc-changed,脏标记原样保留)。 - 保存必须先确保文件模式已挂载:
saveSide在取不到内容时直接返回 false 而不是写空串;Ctrl+S/ 「保存并关闭」走saveAllDirtyEnsuringFiles,会先切回文件模式再保存 —— 否则目录模式下保存会把文件写空。 - 目录的「相同 / 不同」由子树决定:Rust 一律给目录标
identical,前端按子树是否含差异决定目录行的颜色与是否显示。 - 只读:本期不做任何写回 / 同步(用户已拍板)。
尚未验证:与 P1/P2 一样,真实 Tauri 运行时下的观感与拖放行为需要跑一次 tauri dev 目视确认。
P4 · 交互层补全(已落地,参考 Beyond Compare)
用户提出的五项调整,逐项落地情况:
| # | 需求 | 实现 |
|---|---|---|
| 1 | 选项卡,标题 xxx ↔ xxx |
DiffWindow 改为**会话(session)**架构:一个选项卡 = 一对目标。标题取两侧显示名(文件用文件名、目录用末段目录名)。窗口标题同步为 对比 — 左 ↔ 右,任务栏悬停可见 |
| 2 | 目录对比改左右两个界面,都用结构树;两侧可自由输入与选择,选择改图标按钮 | DirDiffView 重写为左右两棵结构树:同一份并集行渲染两遍(行数/顺序一致、共用折叠状态),每侧只显示该侧真实存在的文件(缺失侧显示「—」并压暗名字);每侧顶部是可编辑路径输入框 + 文件夹图标按钮;列头对齐 Beyond Compare 的「名称 / 大小 / 已修改」 |
| 3 | 点一侧文件 → 新开文件对比选项卡 | 行点击 → open-file → 新开文件选项卡(记录 fromDirTabId,工具栏出现「返回目录对比」)。只在一侧存在的文件也能开(另一侧留空,整篇为新增/删除) |
| 4 | 快捷键唤出对比窗口,默认 Alt+C,参考编辑器机制 | Rust 侧新增 DiffSettings + DiffManager({app_data_dir}/diff/settings.json),init_on_launch 用 shortcut.rs 注册(原子注册 + 应用内冲突检测),触发只发 diff-open-window 事件;App.vue 应用级监听后调 openDiffWindow()。模块页可改快捷键(保存后就地重注册) |
| 5 | 中间列显示差异、快速替换等 BC 细节 | 文件对比启用 MergeView 的 revertControls:中间列按差异块渲染 ⇜ / ⇝ 按钮,点一下即把该块替换到另一侧(替换后该侧变脏)。MergeView 一次只能渲染一个方向,因此工具栏给出「右 → 左 / 左 → 右」方向切换(reconfigure 热切换,不重建视图) |
P4 关键取舍:
- 切选项卡不能丢改动:
TextMergeView只有一个实例,内容只在 CM6 里是最新的。切走前snapshotEdits()把脏侧内容取回会话,切回来再灌进去(setTexts抑制doc-changed,脏标记保留)。 - 关闭选项卡的判据是「脏」而不是「编辑器是否挂载」:非激活选项卡的编辑内容已快照在会话里,静默丢弃同样是丢改动 —— 因此脏就弹确认,确认后先激活它再保存(激活那一刻才能拿到最新内容)。
- 会话状态里的大对象要
markRaw:扫描报告可达数千条目,进响应式系统会逐条生成 Proxy。内容字符串是原始值,不进 Proxy,可以放心放会话里。 v-model:session而不是普通 prop:DirDiffView要直接改会话字段(8 个字段几乎都双向改),而vue/no-mutating-props禁止改 prop;defineModel是 Vue 为这种场景给的正解。
9. 已拍板决策表
| # | 问题 | 决策 | 影响 |
|---|---|---|---|
| 1 | devtools 里的文本对比工具 | 移除,能力并入本模块 | 避免仓库里存在两套 diff 引擎;顺带解决它的 3000 行上限 |
| 2 | 目录对比是否写回 | 暂不做(P3 只读) | P3 工程量显著下降;写回留待单独评估 |
| 3 | 是否需要拖入 | 需要 | 已落地:P2 起拖入文件按落点装入左 / 右半区 |
| 4 | 做进编辑器还是独立模块 | 独立模块 + 独立窗口 | 复用编辑器能力但不共享窗口/store |
| 5 | 渲染层选型 | @codemirror/merge |
已有 6.12.2 安装;主题复用编辑器配色 |
| 6 | 本期是否引入 Rust similar |
不引入(P1/P2 不需要) | P3 目录级若需批量摘要再评估 |
| 7 | 拖放补注入的实现路径 | 泛化既有实现(不复制第二份) | drag_drop.rs 移到 crate 根部、命令改名 window_attach_drag_drop;编辑器调用点随之一并更新 |
| 8 | 单文件读取的尺寸策略 | 软阈值 5MB / 硬上限 16MB | 硬上限比编辑器更严:对比窗口同时持有两侧内容 |
| 9 | 目录对比的判据 | size → mtime → 内容(三层) | 内容比对有预算(2000 条 / 4MB):超出按时间戳判定,并在界面标注「未比对内容」 |
| 10 | 目录树结构 | Rust 返回扁平列表,前端组装 | 避开 specta 递归类型的坑(同 LibraryEntry);剪枝 / 排序 / 过滤都在前端 |
| 11 | 本期是否做目录写回 | 不做(只读) | 用户已拍板;冲突策略等留待单独评估 |
| 12 | 窗口内是否有选项卡 | 有(P4):一选项卡 = 一对目标 | 状态按会话组织;目录下钻新开选项卡而不是替换 |
| 13 | 目录对比的界面形态 | 左右两棵结构树(P4,原为一棵并集树) | 同一份并集行渲染两遍,共用折叠状态保证不错行 |
| 14 | 打开对比窗口的快捷键 | Alt+C(P4,可在模块页改) | 走 shortcut.rs;触发只发事件,窗口由前端创建 |
| 15 | 中间列快速替换 | 启用(P4):⇜/⇝ 单方向 + 工具栏切换 | MergeView 一次只能一个方向;双方向要自绘中间列,暂不做 |
10. 风险与待验证
| 风险 / 未知 | 说明 | 应对 |
|---|---|---|
@codemirror/merge 与项目版本兼容 |
已确认安装 6.12.2,@codemirror/state 6.7.6 未变,view 由 6.43.13 升到 6.43.14(补丁级) |
已通过安装验证;P1 构建与运行再复核一次 |
| MergeView 的块级高亮配色与自建主题的融合 | MergeView 提供的是结构类名/默认色,需按项目语义色覆盖(新增/删除/修改) | P1 里显式覆盖 .cm-changedLine 等规则,对齐 --success-soft / --danger-soft |
| 目录扫描在大目录上的耗时 | 几十万文件递归 + 内容比对可能秒级到十几秒 | §7.3 快速路径 + 忽略清单 +(必要时)进度事件分批 |
| 拖放注入射程 | 现实现是编辑器专用的,泛化会触及编辑器路径 | §7.1 二选一;若选泛化,回归编辑器窗口的拖入 |
| 二进制与超长行文本在 MergeView 下的表现 | 极长单行(如压缩后的 JSON)会让对齐与渲染变慢 | 阈值降级 + 明确提示,不做静默失败 |