编辑调整、对比模块

This commit is contained in:
zhongluofeng committed 2026-10-16 13:18:32 +08:00
1 parent c9e61f38c5
commit 6cfa74c901
76 files changed
+9514 -626

No files matched your search

+349
View File
@@ -0,0 +1,349 @@
# 对比工具模块规划(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)会让对齐与渲染变慢 | 阈值降级 + 明确提示,不做静默失败 |
+4 -4
View File
@@ -137,10 +137,10 @@ shadcn 既有(值调整) → --background / --foreground / --primary / --c
--divider: #26262B;
--input: #2E2E34;
--foreground: #F5F5F7;
--fg-secondary: #A8A8B0;
--muted-foreground: #7A7A82;
--fg-disabled: #55555C;
--foreground: #FFFFFF; /* 深色下主文字用纯白 */
--fg-secondary: #ECECF2;
--muted-foreground: #D2D2DA;
--fg-disabled: #9A9AA4;
--primary: #2997FF;
--primary-hover: #4AA8FF;