Files
Thing/doc/DIFF_MODULE_PLAN.md

29 KiB
Raw Permalink Blame History

对比工具模块规划(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. 结论先行

六个关键判断。

  1. 可行,且仓库里已有大半基础设施。 编辑器模块已经把「CM6 + 主题系统 + 多语言高亮」「带编码探测的文件读取」「递归遍历(walkdir 已在依赖树)」「独立窗口 + 任务栏身份 + 拖放补注入」四块能力做完了。本模块的主要工作是组装,而不是造轮子。

  2. 做成独立模块 + 独立窗口,不塞进编辑器。 编辑器模块的中心对象是「一篇文档的生命周期」(标签、自动保存、光标、会话恢复);对比工具是「两个只读视图 + 一棵目录树」,没有自动保存、没有文档标签。混进去会让本已很大的 EditorWindow.vue(1500 行)与 editorStore.ts 继续膨胀,也会让 editor-window-* 这个 capability 的语义变模糊。模块体系是现成的(moduleConfig + 一行注册 + 图标表 + 搜索索引 + 启用开关),独立成模块成本很低。

  3. 渲染层用 @codemirror/merge(CM6 官方 MergeView),计算层留在 Rust。 MergeView 天然给出并排 / 统一视图、块级高亮、chunk 跳转、接受/拒绝,并且直接吃项目现有的 CM6 主题(编辑器那九套配色自动跟随,无需为对比工具再维护一套配色)。Rust 只负责目录级扫描与分类:walkdir 递归 + size/mtime 快速路径 + 按需内容比对。这样目录对比的每一项都能「点一下」下钻到 MergeView 的文件级对比 —— 正是 Beyond Compare 的交互主线。

  4. 三层能力按「易 → 难」分期,P1 只做文本对比。 文本对比(粘贴两段)→ 文件对比(两个路径,含编码探测)→ 文件夹对比(递归树 + 三态分类 + 下钻)。P1 的价值不只是功能,更是验证 @codemirror/merge 与项目现有 CM6 版本的兼容性(见 §10),风险最低、最快闭环。

  5. 目录对比这一期只读,不做写回。 「浏览差异」与「同步目录」是两个量级的工程:后者要处理冲突策略、部分失败回滚、覆盖确认、二进制文件、只读属性与长路径。这一期给出只读的三态树 + 下钻即可,写回(复制 / 镜像 / 双向同步)留待单独评估。

  6. 拖入支持从 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)

三层判据(代价递增,能不打盘就不打盘):

  1. size 不同 → 直接判「不同」(大小都不同,内容不可能相同);
  2. size 相同且 mtime 相同 → 判「相同」;
  3. 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 版本的兼容性。

已交付:

  1. src/modules/diff/:index.ts(moduleConfig)+ DiffModule.vue(主模块页)+ DiffWindow.vue(独立窗口)+ openWindow.ts + components/TextMergeView.vue + types.ts。
  2. src/modules/icons.ts 加 diff 图标映射;src/modules/index.ts 注册模块;src/main.ts 加 #diff-window 路由。
  3. src-tauri/capabilities/diff-window.json(glob diff-window-* 同源权限集)。
  4. src-tauri/src/taskbar_identity.rs 新增 diff 类型(独立 AUMID + 双栏图形组合图标)。
  5. src/lib/constants.ts 加 WINDOWS.diffWindow。
  6. 删除 devtools 的文本对比工具:DiffTools.vue 已删,tools/index.ts 去掉元数据 / 图标 / 组件映射,devtools/index.ts 计数 20 → 19。
  7. 依赖:@codemirror/merge ^6.12.2(@codemirror/state 6.7.6 未变,view 6.43.x 补丁级同步)。
  8. 校验:vue-tsc --noEmit、eslint、vite build、cargo check 全部通过。

尚未验证:窗口在真实 Tauri 运行时的观感(滚动联动、mica 底色下的对比度、任务栏图标)需要跑一次 tauri dev 目视确认。

P2 · 文件对比(已落地)

已交付:

  1. 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)。
  2. 尺寸与二进制策略:软阈值 5MB(置 large)、硬上限 16MB(直接拒绝,对比窗口天生要同时持有两侧)、二进制按「头部 8KB 含 NUL」判定(与 editor::grep 同一判据),二进制不读内容只回元信息。
  3. 拖放泛化:editor/drag_drop.rs → src-tauri/src/drag_drop.rs,命令改名 window_attach_drag_drop,编辑器与对比窗口共用;diff/openWindow.ts 创建后立即补注入。
  4. diffClient.ts(命令名唯一落点)+ types.ts 扩展(DiffFileDoc / DiffSide)。
  5. TextMergeView 增补 setTexts / getText 与 doc-changed 事件(程序化装载期间抑制,避免把装载记成用户编辑)。
  6. DiffWindow.vue:两侧头部(打开文件 / 保存 / 编码 chip / 只读 chip / 脏标记)、拖入分侧高亮、编码不一致提示、二进制概览面板(只比大小,不断言「内容相同」)、Ctrl+S 单侧写回、关闭前三选一确认。
  7. DiffModule.vue 主模块页把「文件对比」标为可用。
  8. 校验:cargo check、vue-tsc --noEmit、eslint、vite build 全部通过。

已知取舍:

  • bindings.ts 是 run() 里 export_bindings() 在 debug 构建时生成的,本次未跑 tauri dev,因此其中仍留着旧的 editorAttachDragDrop 声明(无任何调用点);下次 debug 运行会自动重建。
  • 脏标记是布尔(改过即脏),「改了又撤销回原样」仍显示为脏 —— 方向安全(至多多一次关闭确认),换来的是每次按键不必把整篇文档 toString() 出来比对。
  • 单侧写回不检查另一侧是否也改了同一个文件(两侧选中同一路径时后保存的覆盖先保存的)。仍是未解决的边界 —— P3 的目录模式是只读的,不会走到这条路径。

P3 · 文件夹对比(已落地,只读)

已交付:

  1. Rust diff/scan.rs:递归遍历(walkdir,不跟随符号链接)+ 三态分类 + 三层判据(见 §7.3)+ 跳过清单 + 条目上限。
  2. diff/commands.rs 增补 diff_compare_dirs 与 diff_path_kind(后者用于「拖入 / ?path= 传进来的路径是文件还是目录」)。
  3. 前端 diffClient.compareDirs / pathKind,types.ts 增补 DirDiffEntry / DirDiffReport / DirDiffStatus。
  4. components/DirDiffView.vue:选两侧文件夹、跳过构建目录 / 比对内容两个开关、过滤(仅差异 / 全部 / 仅左侧 / 仅右侧)、树(目录在前、同名排序、可折叠、展开/折叠全部)、按子树剪枝、汇总栏(不同 / 仅左 / 仅右 / 相同 / 类型不一致 / 跳过目录数 / 耗时 / 截断提示)。
  5. DiffWindow.vue 增加模式切换(文件 / 文本 ↔ 文件夹,各自记住自己的目标)、拖入按模式分派(目录模式取该侧根;拖文件取父目录)、点差异行下钻到文件对比 + 「返回目录对比」。
  6. 校验: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)会让对齐与渲染变慢 阈值降级 + 明确提示,不做静默失败