Files
Thing/doc/DIFF_MODULE_PLAN.md
T

350 lines
29 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 对比工具模块规划(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](../src-tauri/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)会让对齐与渲染变慢 | 阈值降级 + 明确提示,不做静默失败 |