Files
Thing/doc/EDITOR_MODULE_PLAN.md
T
2026-10-23 17:25:17 +08:00

44 KiB
Raw Blame History

编辑器模块规划(Editor Module Plan)

状态:方案已确认,待开工(v1 已落地;v2 定位修订与本轮 10 项决策已定稿) 本轮决策(2026-09-30,用户已拍板):不引入工作区(Q2=a)· 目录树不纳入索引(Q3=a)· 标签页放 P4(Q4=a)· 模块显示名 = 编辑器(Q1=a) v1 现状(原「笔记模块」,已全部落地):CM6 内核 + Live Preview + 本地笔记库 + 独立窗口 + 检索/索引 + WebDAV + 导入导出 + 模板 + 双链 + 图片预览 + 全局快捷键 + 文件关联 v2 修订方向:模块核心从「笔记」改为「编辑器」——一个 notepad++ 式的通用文本/代码编辑器;笔记库与本地目录探查退化为它的两个并列导航能力,不再是模块的中心 已确认决策:所见即所得 = Live Preview(非块编辑);WebDAV = 备份 / 同步目标(不做远端直连读写);编码 = 可探测、可切换、原样写回 定位:Thing 工具集的第 13 个模块,id = editor(原 notes),category = 'tool' 作者:砚 | 日期:2026-09-30 关联文档:AI_DEV_GUIDE.md(模块注册 / IPC / 进程管理范式)、UI_DESIGN_SYSTEM.md(页面框架 / 组件规范)、TERMINAL_MODULE_PLAN.md(独立窗口 / 跨窗口设置同步范式)

阅读顺序:§11 开工清单(先读,它是执行入口) → §0 结论 → §1 定位修订 → §3 功能规格 → §5 编码 → §7 缺口 → §8 路线图。 §9 是 v1 的压缩实施记录,只保留「为什么这么做」的结论与踩过的坑;§10 是已拍板的决策表(不再是待定项)。


0. 结论先行

八个关键判断。

  1. 模块改名 notes → editor,但一次到位、不留双命名。 id / 窗口 label / 事件名 / Rust 命令前缀 / 目录名 / 存储键全部统一。半改不改(模块叫 editor、命令还叫 notes_*)比不改更糟:读代码的人要同时维护两套心智。改名是机械工作(约 400 处标识符),风险集中在「漏改一处」,用脚本核对(§9.6)。

  2. 「笔记」不是被删掉,而是被降级为一种能力。 编辑器的最小模型是「路径 + 字节 + 编码」,笔记库是加在它之上的一层(库根沙箱 + front-matter + 索引 + 双链)。因此文件是真相层,笔记库是视图层——这条和 v1 的「文件即真相」并不冲突,只是把「库」从中心挪到了并列位置。

  3. 左侧导航 = 两个并列的树 + 三块辅助能力。 两个树:笔记库(沙箱、有索引、有双链)与本地目录(任意路径、无索引、无 front-matter 语义)。三块辅助:文件名/内容搜索、最近打开(文件夹与文件分开记)、定位到资源管理器。

  4. 多编码是这一版的新增硬需求,且必须「可切换」。 探测链:BOM → 严格 UTF-8 → GB18030(中文存量主力)→ 用户手动指定。写回默认按读取时的编码。切换编码的语义是「换一种方式解释磁盘字节」而不是「重新解释缓冲区文本」——因此切换动作会从磁盘按新编码重新解码(有未保存改动时先让用户三选一,见 §5.3)。

  5. 系统集成走用户级注册表,不需要管理员权限。 文件关联(双击打开)走 Tauri fileAssociations;资源管理器右键菜单(文件/文件夹)走 HKCU\Software\Classes\*\shell\* 与 Directory\shell\*,用已在依赖树里的 winreg 写(项目已有 system_proxy.rs / glsmtc.rs 两处先例)。注册动作放在设置页按钮里、默认不自动写注册表——开发模式下的 exe 路径是 target\debug\thing.exe,自动注册会留下指向临时产物的僵尸菜单项。

  6. 默认全局快捷键 Alt+E 打开编辑器。 走既有 shortcut.rs(原子注册 + 冲突检测),设置页可改。

  7. 不引入「工作区」概念(已拍板)。 用户要的是「右键文件夹 → 在这里打开」,用当前目录根这一个状态就够了(可切换 + 有历史)。引入 workspace 会连带出「多根 / 会话恢复 / 每根独立状态」三个复杂度,而收益(同时开两个目录树)在 notepad++ 式用法里很低。因此侧栏只有一个「目录」面板,根是单值。

  8. 不做的事(明确划界,避免无限扩张):不做 IDE 能力(调试器、终端内嵌、LSP 补全、Git 集成);不做块编辑器;不做远端工作区(WebDAV 只做备份/同步目标)。


1. 定位修订(v1 → v2)

维度 v1(笔记模块) v2(编辑器模块)
一句话 一个 Markdown 笔记库,带所见即所得编辑 一个通用文本/代码编辑器,顺带能管一个笔记库
中心对象 笔记(库内 .md) 文件(任意路径的任意文本)
首要入口 库树 → 选一篇笔记 打开文件 / 最近文件 / 目录树 → 选一个文件
笔记库的角色 模块的全部 两个导航根之一 + 一层语义(front-matter / 双链 / 索引)
编码 「尽量别写坏」(读时记、写回原样) 一级功能:探测 + 状态栏显示 + 可切换
系统集成 无(P2 曾因依赖代价搁置) 文件关联 + 资源管理器右键 + Alt+E
索引 FTS5 全文检索(笔记的核心) 保留,但只服务笔记库;目录树只做文件名匹配
markdown Live Preview 默认视图 按文件类型自动选择:.md 用 Live Preview,其余用纯高亮

一句话总结这次修订:把「库」从产品中心降为两个导航能力之一,把「文件 + 编码 + 系统集成」提到中心。


2. 需求解构

用户原话 解构为 落点
「核心改为 Editer,标题和其他都改」 模块改名 + 重定位 + 主页面/窗口标题/文案全面改口径 §1 / §7 / §9.6
「笔记作为编辑器模块的一个核心功能」 笔记库降为并列能力,但保留全部既有实现 §1 / §3.3
「左边导航栏有两个功能:笔记库 / 本地目录结构」 侧栏两个并列根:库根(沙箱 + 索引)与当前目录(任意) §3.3 / §6
「导航栏需要定位打开文件位置、搜索文件名(参考 idea)」 「在资源管理器中显示」+ 两级过滤(文件名 LIKE / 库内 FTS) §3.4
「核心只是普通编辑器,类似 notepad++」 不引入 IDE 能力;以「打开快、编码稳、快捷键全」为质量目标 §0.8 / §3.1
「快捷键直接打开编辑器,默认 alt+e」 全局快捷键,默认 Alt+E,设置页可改 §3.7
「文件管理器右键菜单,用 Thing Editer 打开」 HKCU 注册 *\shell\ThingEditor 与 Directory\shell\ThingEditor §3.6
「历史打开的文件夹/文件记录」 最近文件 + 最近文件夹两份列表(分组显示、可清空) §3.5
「多编码,识别 + 支持切换编码」 探测链 + 状态栏编码菜单 + 重解码 + 按新编码重写 §5
「优化结构和功能完整性」 补齐:编码切换、目录树、最近记录、右键菜单、大文件策略、只读打开 §3 / §4

3. 功能规格

3.1 编辑器核心

  • 打开方式:最近文件 / 目录树 / 笔记库树 / 系统对话框 / 命令行 / 文件关联 / 资源管理器右键。
  • 视图按类型自动选:.md/.markdown/.mdx 默认 Markdown(Live Preview,可在状态栏切到源码);其余按扩展名加载语言高亮(@codemirror/lang-* 按需 import())。
  • 基础编辑:行号、折叠、括号匹配、多光标、矩形选择、搜索替换(CM6 原生 searchKeymap)、转到行(Alt+G)、撤销栈、Tab 缩进。
  • 快捷键(窗口内,CM6 keymap 优先于全局):Ctrl+S 保存、Ctrl+Shift+S 另存为、Ctrl+O 打开、Ctrl+P 快速打开、Ctrl+W 关闭当前文档、Ctrl+Tab 文档间切换、Ctrl+E 切换编码、Ctrl+Shift+M 切换 Live Preview/源码。
  • 多文档:同一窗口内多标签(新增,见 §8-P1)。Ctrl+W 关闭标签,关闭前若有未保存改动则二次确认。
  • 大文件策略:超过阈值(默认 5MB,可配)时关闭 Live Preview / 折叠 / 补全 / 装饰,只保留高亮 + 行号;并在状态栏给出可点击的降级说明。
  • 只读打开:检测到文件不可写时以只读模式打开(替代「打开成功但保存失败」)。

3.2 笔记模式(.md 在库内)

保持 v1 全部能力:Live Preview(标题/强调/行内代码/列表/任务/引用/代码块/分隔线/表格/图片内联)、[[wikilink]] 点击跳转与一键新建、front-matter 属性面板、大纲、双链面板、字数/行数统计。

3.3 左侧导航(两个并列根)

面板 根 能力 数据来源
笔记库 库根(可切换,默认 {appData}/editor/library) 树 / 新建 / 重命名 / 删除 / 标签 / 双链 / FTS 全文检索 SQLite 索引(notes.db → editor.db)
本地目录 当前目录根(可切换,有历史) 树 / 文件名过滤 / 打开文件 / 新建文件/文件夹 / 重命名 / 删除 / 在资源管理器中显示 / 复制路径 直接 fs 读目录(不进索引)

两个面板都在同一个侧栏里用分段导航切换(v1 已有 4 段:文件/检索/大纲/双链;v2 扩为:库 / 目录 / 检索 / 最近,大纲与双链改为编辑区右侧的抽屉,因为它们跟「当前文档」绑定而不是跟「导航」绑定)。

为什么把大纲/双链挪到右侧抽屉:它们描述的是当前文档,而侧栏描述的是去哪找文件。混在一起会让侧栏在「导航」与「文档信息」两种语义之间摇摆(v1 已经能感到这个别扭)。

3.4 搜索与定位

  • 文件名过滤:侧栏顶部输入框,对当前树做不区分大小写的子串匹配,命中项的祖先自动展开(v1 已有)。
  • 快速打开 Ctrl+P:跨「库 + 最近 + 当前目录」的文件名跳转,本地模糊排序(连续匹配 > 前缀 > 词首 > 位置),零网络、零后端。
  • 库内全文检索 Ctrl+Shift+F:FTS5(trigram),标题权重高于正文,命中片段高亮(定界符方案,不注入 HTML)。目录树不做全文检索(不在索引里,也不该为此扫盘)。
  • 定位打开文件位置:revealItemInDir(opener 插件,能力已授权)。三处入口:标签右键、侧栏行右键、状态栏路径点击。
  • 搜索文件名作用域切换:输入框旁边一个「当前树 / 全库 / 当前目录」的小切换(idea 的 Ctrl+Shift+N 体验,但不引入独立对话框)。

3.5 历史记录

  • 最近文件:路径 + 显示名 + 时间 + 是否仍存在(失效项灰显、可一键清理)。
  • 最近文件夹:同理,用于「右键文件夹 → 在这里打开」与侧栏目录面板的快速切换。
  • 存储:editor/settings.json 的 recentFiles / recentFolders(与笔记库解耦 —— 库可以换/删,历史不该跟着丢)。各自上限 20 条,超出淘汰最旧。
  • 两份列表分开存:文件与文件夹的用途不同,混在一起会让「最近文件夹」被文件挤掉。

3.6 系统集成

集成 机制 权限
双击 .md/.markdown/.mdx 打开 bundle.fileAssociations(安装器写 OpenWithProgids) 安装器
「用 Thing 编辑器打开」(文件) HKCU\Software\Classes\*\shell\ThingEditor 用户级,免管理员
「用 Thing 编辑器打开」(文件夹) HKCU\Software\Classes\Directory\shell\ThingEditor 同上
「用 Thing 编辑器打开」(目录背景) HKCU\Software\Classes\Directory\Background\shell\ThingEditor 同上
菜单图标 菜单项 Icon 值指向 exe(用 exe 自带图标) —
已运行时的二次启动 tauri-plugin-single-instance 转交 argv 给已有实例 已落地
免注册表运行 设置页提供「注册 / 卸载右键菜单」按钮,并显示当前 exe 路径 —

关键约束:注册表条目里写的是绝对 exe 路径。

  • 打包安装后:指向安装目录的 exe,稳定;
  • tauri dev 下:指向 target\debug\thing.exe,一旦清理 target 就变成死链。 → 因此默认不注册,且注册时校验 exe 存在;设置页在 dev 环境下给出明确提示。

3.7 全局快捷键

快捷键 动作 默认
Alt+E 打开编辑器窗口(无参数 = 上次的文档/最近文件) 本版新增默认值
Ctrl+Shift+N 新建笔记(直接落库根) 空(v1 已有实现,改为可配)

两者都走 shortcut.rs,触发时只发事件、窗口由前端创建(v1 已确立的姿态)。


4. 存储、索引与目录树

{appData}/editor/                 # 模块自身(与库解耦)
├── settings.json                 # 设置 + 最近文件/文件夹
├── editor.db                     # 笔记库索引(可重建)
└── library/                      # 默认库根
    ├── notes/  assets/  templates/
    └── .editor/                  # 库内私有:同步基线 sync.json
  • 配置文件全量走 settings.json(v1 已如此),新增 recentFiles / recentFolders / defaultEncoding / largeFileMb / contextMenuEnabled。
  • 索引服务架构不变(单线程 worker 独占 rusqlite 连接 + 通道排队 + notify 监听),只改名。
  • 目录树不进索引:它是「看盘」而不是「管库」。目录树节点按需 read_dir(带缓存与手动刷新),深度上限与库树一致(24)。
  • 配置改动只在用户显式操作下发生:目录树上的新建/重命名/删除都是显式动作,且删除走系统回收站(复用 quickpanel 的回收站实现,terminal/local_fs.rs 已有先例)。目录树自身不做任何隐式写入(不生成索引、不生成元数据文件、不自动整理)。

5. 编码:探测、显示、切换

5.1 探测链(按优先级)

顺序 判据 结论 说明
1 EF BB BF / FF FE / FE FF utf-8-bom / utf-16le / utf-16be BOM 是无歧义事实,直接采信
2 std::str::from_utf8 通过 utf-8 结构性校验,不是统计猜测
3 以上失败 gb18030 中文存量主力(GBK 超集),比「猜 Big5/Shift_JIS」安全
4 用户手动指定 用户值 前三级都可能错,必须留人工兜底

刻意不做:字符频率统计 + 多编码自信度比较(chardet 式)。理由是它在短文本上比规则更不可靠,而本项目的主要场景(代码/配置/中文笔记)恰好都是「UTF-8 或 GB18030」二选一。真错了有第 4 级兜底,代价可控。

5.2 读取与状态

读文件时一次性回传:content(已解码 UTF-8 字符串 + 换行归一为 \n)、encoding(探测结果)、eol(lf/crlf)、size、large、readonly。

  • 状态栏显示:UTF-8 / GB18030 / UTF-8 BOM + CRLF / LF + 只读标记。
  • readonly:打开时用 OpenOptions::new().write(true).open() 探一次写权限(不实际写入),失败则置只读。这比「打开成功但保存时才报错」体验好得多。
  • 编码名一律用 terminal/encoding.rs 的 normalize() 规范形态(utf-8 / gbk / gb18030 / big5 / shift_jis / euc-kr / latin1),双端取值同源,避免「状态栏写 GBK、设置里叫 cp936」这种不一致。

5.3 切换编码(关键设计)

核心约束:切换编码不是「重新解释缓冲区文本」,而是「换一种方式去解释磁盘字节」。

  • 切换时:以磁盘当前字节(而非缓冲区文本)按新编码重新解码 → 替换缓冲区内容。
    • 若此时有未保存改动:弹确认框给出三个选项——①丢弃我的改动并按新编码重读(默认,语义最清晰);②先保存再重读(用旧编码落盘,再按新编码读回——用户能立刻看出旧编码是否选错);③取消。
  • 保存时:按当前 encoding 编码写回。若目标编码无法表示缓冲区里的某些字符(例如把含 emoji 的文本存成 GBK),保存前报错并列出无法表示的字符位置,而不是静默替换成 ?(静默替换 = 不可逆数据损坏)。
  • 状态栏编码下拉:UTF-8 / UTF-8 BOM / GB18030 / GBK / Big5 / Shift_JIS / EUC-KR / Latin-1 + 「重新载入为…」(不改变写回编码,仅重新解释)。
  • 换行切换:LF / CRLF 独立于编码(v1 已按读取值写回),状态栏可切换。

5.4 与终端模块的编码复用

terminal/encoding.rs 提供 decode / encode / normalize / SUPPORTED / is_supported(v1 已直接复用,未提取为公共模块 —— 它们是纯函数,无业务耦合;若将来第三个模块要用再提取)。


6. 界面结构

6.1 主模块页(设置与管理,不编辑)

Tab 收敛为 概览 / 库 / 编辑器 / 集成(把 v1 的「同步」并入「库」,因为同步是库的属性):

Tab 内容
概览 库状态横幅(路径/笔记数/索引)、最近文件与文件夹、快捷入口(打开编辑器 / 打开文件 / 打开文件夹 / 今日日记)
库 库根切换、重建索引、导入导出、WebDAV(连接/方向/冲突/快照)
编辑器 主题(含 JetBrains 三套)、字体字号行高连字、Live Preview 开关、默认编码、大文件阈值、自动保存、快捷键
集成 文件关联状态、右键菜单注册/卸载、exe 路径、单实例说明

6.2 编辑器窗口

┌─ 标题栏(自绘:文档名 + 未保存点 + 窗口按钮)────────────────────────┐
├─ 工具栏:保存 另存 打开 快速打开 | 格式化(.md 时) | 编码 换行 主题 ─┤
├────────────┬──────────────────────────────────────────┬─────────────┤
│ 侧栏        │ 标签栏:doc1 × | doc2 × | …               │ 抽屉(可选) │
│ [库|目录|   ├──────────────────────────────────────────┤ 大纲 / 双链  │
│  检索|最近] │           编辑器(CM6)                   │             │
│            │                                          │             │
│ 树 / 结果   │                                          │             │
├────────────┴──────────────────────────────────────────┴─────────────┤
│ 状态栏:保存态 · 字数/行数 · 行列 · 语言 · 编码 · 换行 · 路径          │
└─────────────────────────────────────────────────────────────────────┘

并排分屏(标签右键 → 并排分屏)把编辑页平分为左右两列,各占一半宽:

├─ 工具栏(整行,不参与分屏)──────────────────────────────────────────┤
│ 标签栏:doc1 × | doc2 ×      │ 副文档名 ×                            │
├──────────────────────────────┼──────────────────────────────────────┤
│  编辑器(CM6)· 主文档        │  编辑器(CM6)· 副文档                 │
└──────────────────────────────┴──────────────────────────────────────┘
  • 「标签栏 + 编辑栏」整体是左半列,副文档是右半列(自带 8px 标题行与关闭按钮), 两列等宽、各自独立滚动 —— 副文档是并排的一列,不是嵌在编辑栏内部的一块。 从前的做法把副面板塞在编辑栏(标签栏下方)内部,看起来像"同一栏里又开了个窗口"。
  • 不分屏时标签栏回到顶部、横跨整列宽度(即左半列占满),行为与基础形态一致。
  • 侧栏可整体折叠(腾出宽度给长行代码)。
  • 抽屉默认关闭,Ctrl+Shift+O 切大纲、Ctrl+Shift+B 切双链。这两个键位在实现时由 keymap.ts 统一声明并做冲突检测:若与 CM6 默认键位冲突,以 CM6 默认键位优先,本功能改用 Alt+O / Alt+B(冲突检测方式沿用 v1 的 shortcut.rs 思路,编辑器内用 CM6 的 keymap 优先级)。

6.3 目录面板的命令面(P3-5 实现依据)

命令 入参 说明
editor_read_dir path: String(空 = 用户主目录) 返回 cwd / parent / entries(名字/路径/是否目录/大小/mtime)
editor_create_file dir: String, name: String 重名报错(不自动加序号:目录树是用户的真实文件系统,静默改名会让人找不到刚建的文件)
editor_create_folder dir: String, name: String 同上
editor_rename_path path: String, newName: String 同目录改名;目标存在则报错
editor_delete_path paths: Vec<String> 走系统回收站(复用 quickpanel::commands::delete_file_impl),返回 (成功数, 失败明细);拒绝盘符根
editor_reveal_path path: String 在资源管理器中选中(opener 的 reveal_item_in_dir)

安全边界:目录树操作的是用户真实文件系统(不是沙箱),因此

  • 不设「必须在本目录根下」的限制(那是本地文件管理器,限制根目录只会挡住用户自己);
  • 但拒绝删除盘符根(Path::new(p).parent().is_none())—— 这是唯一不可恢复的事故;
  • 删除一律走回收站,不用 remove_file;
  • 路径来自用户自己的浏览/输入,与 terminal/local_fs.rs 同一姿态(该模块已有 list_dir / delete 的成熟实现,优先复用而不是重写)。

7. 缺口清单(v1 已有 → v2 要做)

# 缺口 严重度 落点
G1 模块仍叫 notes(id / 命令 / 事件 / 目录 / 存储键) 高(结构性) §9.6
G2 没有「本地目录」导航根(只有笔记库) 高 §3.3
G3 编码只能探测不能切换;无状态栏显示 高 §5
G4 没有最近文件夹记录(只有最近笔记,且存在 localStorage) 中 §3.5
G5 没有资源管理器右键菜单 中 §3.6
G6 默认全局快捷键为空(Alt+E 未设) 低 §3.7
G7 单窗口单文档(无标签页) 中 §3.1
G8 大纲/双链挤在导航侧栏里,语义混杂 中 §3.3
G9 大文件降级没有「只读打开」与显式提示 低 §3.1 / §5.2
G10 主模块页 Tab 结构未随定位调整(同步应并入库) 低 §6.1
G11 语言包缺 .sh/.ps1/.toml/.ini/.scss(legacy-modes 未接) 低 §8-P5.1
G12 Markdown 内嵌代码块高亮未做(codeLanguages 异步问题) 低 §8-P5.3
G13 FileDoc 无 readonly 字段(只读文件要等保存时才报错) 中 §5.2 / P4-1

8. 分期路线图

v1 的 P0/P1/P2 已全部落地(见 §9)。以下是从 P3 起的新路线图。

P3 — 编辑器化改造(结构)

  1. 改名:notes → editor(id / 窗口 label / 事件 / 命令前缀 / 目录 / 存储键 / Rust 模块名),脚本核对无残留(§9.6)。
  2. 库内目录改名:<库根>/.notes/ → <库根>/.editor/(含 sync.json),首次打开时惰性迁移;索引可重建,丢了无损。
  3. 侧栏重构:库 / 目录 / 检索 / 最近 四段;大纲与双链移到编辑区右侧抽屉。
  4. 本地目录树:打开文件夹(对话框 / 右键菜单 / 最近文件夹)、树浏览、文件名过滤、打开文件、在资源管理器中显示、复制路径、手动刷新。
  5. 最近记录:最近文件 + 最近文件夹(落 settings.json,分组显示、可清空、失效项灰显)。
  6. 主模块页 Tab 调整:概览 / 库 / 编辑器 / 集成。

P4 — 编码与系统集成(这一版的核心价值)

  1. 编码探测链(§5.1)+ 状态栏显示编码/换行/只读。
  2. 切换编码(§5.3):重解码对话框三选项、保存时不可表示字符报错、换行独立切换。
  3. 系统集成:Alt+E 默认值;HKCU 右键菜单注册/卸载(文件 + 文件夹 + 目录背景),设置页按钮 + exe 路径显示 + dev 环境提示。
  4. 只读打开与大文件降级提示。
  5. 标签页(多文档):Ctrl+W / Ctrl+Tab、每标签独立编码与视图模式、关闭确认。

P5 — 完善(本轮不做,按体感排后续优先级)

  1. 语言包补齐:.sh / .ps1 / .toml / .ini / .dockerfile 走 legacy-modes;.scss / .less 引入 @codemirror/lang-sass。
  2. 目录树上的文件操作完善:拖拽移动、在新窗口打开、批量重命名。
  3. Markdown 内嵌代码块高亮(codeLanguages,需解决 language-data 异步 vs markdown() 同步)。
  4. 双链图谱(数据已就绪:editor_link_graph 命令可用,仅缺可视化)。
  5. 会话恢复:关窗后重开恢复文档与光标位置。

9. v1 实施记录(压缩归档)

完整细节已在 v1 文档中,此处只留结论与坑——它们对 v2 仍然成立。

本节的文件名一律是 v2 目标名。v1 代码里对应的真实路径是: src-tauri/src/notes/*.rs、src/modules/notes/**、src/stores/notesStore.ts、 src/types/notes.ts,命令为 notes_*。

9.1 交付总览(v1,均已落地)

层 关键文件
Rust 文件 IO editor/files.rs(编码/换行探测、授权白名单、附件落盘)
Rust 库 editor/library.rs(safe_join 路径沙箱、扫描、增删改移)
Rust 模板 editor/templates.rs(4 个内置模板 + 库内覆盖 + {{title}}/{{date}})
Rust 导入导出 editor/import.rs(文件/目录/zip,重名加序号、绝不覆盖)、editor/export.rs(整库/单目录 zip)
Rust 索引 editor/index.rs(SQLite + FTS5 trigram:front-matter、标签、双链、检索、片段)、editor/index_service.rs(单线程 worker + notify)
Rust WebDAV editor/webdav/{client,sync}.rs(PROPFIND/MKCOL/PUT/GET/DELETE/MOVE + 三方比对 + 冲突策略 + 改名识别)、editor/backup.rs(zip 快照 + 轮转 + 恢复)
Rust 参数 editor/args.rs(文件关联/命令行参数解析 + 待打开文件缓存)
前端内核 editor/core.ts(Compartment 热重配置)、markdownLivePreview.ts、languages.ts、themes.ts、keymap.ts、outline.ts、wikilink.ts、images.ts、markdownExport.ts
前端组件 LibrarySidebar.vue、SearchPanel.vue、QuickOpen.vue、MarkdownOutline.vue、BacklinksPanel.vue、WebdavPanel.vue、ImportExportPanel.vue、NewNoteDialog.vue、EditorHost.vue、EditorToolbar.vue
前端状态 stores/editorStore.ts、modules/editor/editorClient.ts、types/editor.ts
命令 40 条(notes_* → 将统一改名为 editor_*)

9.2 关键决策(v2 继续沿用)

  • 真相是文件,索引可丢:删掉 editor.db 的唯一后果是下次搜索前做一次全量扫描。
  • 索引由单线程 worker 独占:rusqlite::Connection 非共享对象,而搜索命令(Tauri 线程池)、保存后的增量更新、notify 回调会并发进来;通道排队 + 专职线程换来「慢操作只排队不堵搜索」。
  • FTS5 用 trigram:默认 unicode61 把连续汉字切成一个词元,「会议」搜不到「周会议纪要」。代价是查询词 <3 字符静默返回空 → 回退 LIKE + Rust 侧自建片段。
  • WebDAV 同步基线存两侧指纹,不比 mtime(跨机时钟偏差会让「本地比远端新」两边都成立)。删除传播保守优先;同步有失败不推进基线。
  • 冲突「两侧都留」用远端 MOVE 保留历史,而不是覆盖。
  • 同步/网络类命令一律 async + spawn_blocking:reqwest::blocking 在 tokio 运行时线程上会 panic。
  • HTML 导出零外链、失败关闭:样式内联;DOMPurify 不可用时返回空串而不是原文。
  • 渲染链路按需 import():markdownExport(markdown-it + DOMPurify + highlight.js)约 1.1MB,静态引入会让模块 chunk 从 40kB 涨到 1.2MB。
  • 库外文件的路径授权白名单:库内走 safe_join(根目录沙箱),库外走「用户显式打开过的绝对路径集合」。读宽松(读时登记),写严格。
  • from(大纲)一律是行首偏移:指向正文起点会让空标题没有合法取值。
  • Live Preview 是装饰不是渲染:只对 view.visibleRanges 计算(性能红线);光标行「显形」为可编辑源码。

9.3 验证状态(v1 收尾时)

cargo check        0 warning
cargo build        整包通过
cargo test --lib   58 passed / 0 failed
node --test        74 passed / 0 failed / 1 skipped(Node 无 DOM 的 XSS 断言)
vue-tsc / eslint   通过
vite build         NotesModule 41kB(gzip 12.5) / NotesWindow 98kB(gzip 32.6)
                   / markdownExport 1.12MB(gzip 371) 按需加载
接线核对            命令 定义=导出=注册 40/40/40,无差集
                   事件 Rust 8 = TS 8,无差集
                   类型 18 个结构字段名双端一一对应

9.4 坑记录(跨版本有效)

  1. <SelectItem> 不能用空串 value:reka-ui 把空串保留给 placeholder,会直接抛异常。用显式哨兵值('__all__' / '__current__')在调用点翻译。报错栈指向 SelectItem.vue 而不是调用方 —— 先搜 value: ''。
  2. cargo add <tauri 插件> 会连带升级整个 tauri 依赖树(wry / tray-icon / window-vibrancy),而 dev 启动会校验 JS 包与 crate 的 minor 是否一致。改一边必须同时看另一边。
  3. 不要把 package.json 交给 PowerShell 的 Set-Content -Encoding UTF8(PS 5.1 写入 BOM),带 BOM 会让 Vite 读 PostCSS 配置直接失败。用 node -e 或 UTF8Encoding($false)。
  4. CRLF 下反推行首偏移一律偏 1:必须预先算 lineStarts 表,不要在循环里「减回去」。
  5. front-matter 用状态机而不是布尔量:首行 --- 是开头,布尔量会在第 0 行就关掉状态,导致第 2 行的闭合 --- 把上一行元数据提升成 Setext 标题。
  6. let plan = plan(...) 会遮蔽函数名,第二个测试起报 E0618 且位置离成因很远。函数名避开返回值名。
  7. enum 不能出现在 node --test 直接跑的文件里(Node 的 TS 支持是 strip-only)。用 const X = {...} as const + 类型别名。
  8. quick-xml 0.42 的 QName::as_ref() 返回 &str(旧版 &[u8]),BytesText 无 decode();升级时只 cargo update -p quick-xml,避免动到 wry 链。
  9. 冷启动的文件关联事件会丢:setup 里 emit 时 WebView 还没加载。改为存 OnceLock<Mutex<Option<PathBuf>>>,前端注册完监听后主动取走。
  10. FTS5 的 snippet() 对「走 LIKE 回退的短词」什么都不产出;列索引用 -1(让 FTS 挑最佳列)。

9.5 与 v1 规划不一致之处(保留结论)

规划 实际 原因
语言支持走 language-data 一处入口 手写扩展名映射表 + 逐语言 import() matchFilename 覆盖不到 .vue/.toml/.ps1;手写表行为可预期
Markdown 内嵌代码块高亮 未做 language-data 清单异步 vs markdown() 同步(见 G12)
.scss / .less 未做 @codemirror/lang-css 只导出 css()
表格渲染 / 图片内联 已做(图片走 data URL,非 asset 协议) asset 协议要求把用户自选库根加进白名单,等于给 WebView 开任意读文件的口子
提取 terminal/encoding.rs 为公共模块 未提取,直接复用 纯函数无耦合;第三个模块要用时再提取
系统关联 已做文件关联;右键菜单本轮补 §3.6
双链图谱 / 托盘入口 / Mermaid 未做 §8-P5 / §0.8

9.6 改名清单(P3 的执行依据)

面 v1 v2 规模
模块 id / 目录 notes / src/modules/notes/ editor / src/modules/editor/ 10 处
窗口 hash / label 前缀 #notes-window / notes-window-* #editor-window / editor-window-* 16 处 + capability 文件名
事件名 notes-settings 等 8 个 editor-* 4 处(双端一致)
Rust 命令前缀 notes_*(40 条) editor_* 246 行
Rust 模块目录 src-tauri/src/notes/ src-tauri/src/editor/ 18 处
store / client / types notesStore / notesClient / types/notes.ts editorStore / editorClient / types/editor.ts 77 处
localStorage 键 thing_notes_recent 改为落 settings.json(不再用 localStorage) 1 处
capability 文件 notes-window.json editor-window.json 1 文件
默认库目录 {appData}/notes/library {appData}/editor/library 需迁移逻辑(见下)

迁移策略:{appData}/notes/ 若存在且 {appData}/editor/ 不存在 → 启动时整目录重命名并记日志;否则各自独立。库内 .notes/(索引 + 同步基线)同理改 .editor/,并在首次打开时惰性迁移(索引可重建,丢了也无损)。


10. 决策表(已拍板,开工时按此执行)

Q1–Q4 由用户于 2026-09-30 明确拍板;Q5–Q10 由本规划给出建议并一并视为生效(若要改,改这一行即可,不影响其它章节)。

# 决策点 结论 影响面
Q1 模块显示名与英文 id id = editor,显示名「编辑器」(一词式,与「终端」「下载」一致) 模块注册、窗口标题、搜索项、改名清单 §9.6
Q2 是否引入「工作区」 不引入。只有「笔记库根」与「当前目录根」两个单值 + 各自历史 §3.3 侧栏只有一个目录面板;ST-4 无需 workspace 状态
Q3 目录树是否纳入索引 不纳入。目录树只做文件名过滤;全文检索仅对笔记库可用(FTS5) §3.4 / §4;editor_index_* 只处理库内 .md
Q4 标签页放哪一期 P4(与编码、系统集成同期) §8-P4.5;EditorHost 需支持多 view 实例
Q5 右键菜单注册时机 设置页手动按钮,默认不写注册表 §3.6;dev 环境 exe 路径不稳定
Q6 目录树删除语义 走系统回收站(复用 quickpanel 实现) §4;与 terminal/local_fs.rs 同口径
Q7 默认编码兜底 GB18030(探测链第 3 级) §5.1;第 4 级人工指定兜底
Q8 「笔记库」这一叫法 保留(库内文件仍是笔记,用户已理解该词) §3.3 面板名「笔记库」
Q9 主模块页是否给「打开文件夹」入口 给 §6.1 概览页行动区
Q10 大文件阈值 5MB 默认,可配,且状态栏显式提示降级 §3.1;largeFileMb 进设置

11. 开工清单(执行入口)

本节是「照做即可」的清单。P3 与 P4 之间没有依赖倒置:P3 是结构改造(改名 + 侧栏 + 目录树 + 最近记录),P4 是能力新增(编码 + 系统集成 + 标签页)。建议严格 P3 → P4:改名会碰到 P4 要改的每一个文件,同时做会让 diff 无法 review。

11.1 定稿参数(实现时直接用这些值,不要再另起炉灶)

项 值
模块 id / 显示名 / 图标 key editor / 编辑器 / editor(icons.ts 映射到 FileCode2 或 NotebookPen,见下)
模块排序 order 45(沿用,排在终端 40 之后)
窗口 hash / label 前缀 #editor-window / editor-window-
窗口查询参数 ?file=<绝对路径> / ?note=<库内相对路径> / ?folder=<绝对路径>
Tauri 命令前缀 editor_(40 条现有命令全部平移,P4 新增约 12 条)
事件名(8 个) editor-settings / editor-library-changed / editor-file-changed / editor-sync-progress / editor-new-note / editor-open-editor / editor-open-file / editor-open-folder(最后一个是 P4 新增)
Rust 模块目录 src-tauri/src/editor/
前端目录 src/modules/editor/
store / client / types useEditorStore / src/modules/editor/editorClient.ts / src/types/editor.ts
模块自身目录 {appData}/editor/(settings.json / editor.db / library/)
库内私有目录 <库根>/.editor/(sync.json)
keyring 键 editor.webdav.password
默认全局快捷键 打开编辑器 = Alt+E;新建笔记 = 空(可配)
默认库根 {appData}/editor/library
默认编码 / 大文件阈值 UTF-8 优先探测,兜底 GB18030;5MB
右键菜单键名 HKCU\Software\Classes\{*,Directory,Directory\Background}\shell\ThingEditor,显示名 「用 Thing 编辑器打开」
图标 key / 组件 key = editor;组件 FileCode2(已确认 @lucide/vue 有该图标;备选 SquarePen / FileCode)。侧栏新面板建议:目录 = FolderTree、最近 = History、抽屉 = PanelRight

11.2 P3 执行顺序(每步都可独立验证 + 可提交)

步 内容 验证
P3-1 改名:Rust 侧(模块目录 notes/ → editor/、40 条命令 notes_* → editor_*、NoteSettings → EditorSettings 等类型名、事件常量) cargo check 0 warning;cargo test --lib editor:: 58 passed
P3-2 改名:前端侧(src/modules/notes/ → editor/、notesStore → editorStore、notesClient → editorClient、types/notes.ts → editor.ts、STORAGE_KEYS、main.ts 路由、capability 文件名与 windows glob、模块注册与图标) vue-tsc / eslint / vite build 通过;模块列表里显示「编辑器」
P3-3 迁移:{appData}/notes/ → {appData}/editor/(启动时整目录 rename,幂等);<库根>/.notes/ → .editor/(惰性,ensure_schema 时探测并 rename) 手工验证:改名前留下的库仍能被打开、索引被重建
P3-4 侧栏重构为 库 / 目录 / 检索 / 最近 四段;大纲与双链移到右侧抽屉 四段可切换;抽屉快捷键生效
P3-5 本地目录树:Rust editor_read_dir / editor_create_file / editor_create_folder / editor_rename_path / editor_delete_path(回收站)+ 前端 DirectoryPanel.vue 能浏览、新建、重命名、删除(进回收站)、在资源管理器中显示
P3-6 最近记录:recentFiles / recentFolders 落 settings.json,RecentPanel.vue,失效项灰显 + 清空 打开文件/文件夹后出现在「最近」,重启后仍在
P3-7 主模块页 Tab → 概览 / 库 / 编辑器 / 集成(同步并入库页) 四页可切换,入口按钮就位

P3 完成判据:模块叫「编辑器」、侧栏有库与目录两个根、最近记录可用、cargo test 与 node --test 全绿、vite build 通过且模块 chunk 无异常膨胀。

11.3 P4 执行顺序

步 内容 验证
P4-1 FileDoc 增 readonly;files.rs 增写权限探测(OpenOptions::new().write(true).open() 不写入) 只读文件打开后状态栏显示「只读」,保存被拦并给出原因
P4-2 编码探测链按 §5.1 收紧(BOM → 严格 UTF-8 → GB18030);新增 editor_redecode_file(path, encoding) Rust 单测覆盖 BOM/UTF-8/GBK/UTF-16
P4-3 状态栏编码与本行下拉 + 切换编码三选项对话框(§5.3)+ 保存时不可表示字符报错 手工:GBK 文件切 UTF-8 看到乱码→切回正常;含 emoji 存 GBK 被拦
P4-4 系统集成:Alt+E 默认值;右键菜单注册/卸载(winreg,HKCU)+ 设置页「集成」Tab 注册后资源管理器右键出现菜单项,点击能打开文件/文件夹
P4-5 标签页(多文档):Ctrl+W / Ctrl+Tab、每标签独立 encoding/eol/视图模式、关闭确认 同时开 3 个不同编码的文件,互不串味

P4 完成判据:编码可探测可切换、右键菜单可用、Alt+E 生效、多标签可用;§9.3 的全部检查项重新跑一遍通过。

11.4 每个阶段都要跑的验证命令

# Rust
& "C:\Users\<user>\.cargo\bin\cargo.exe" check --message-format short   # 必须 0 warning
& "C:\Users\<user>\.cargo\bin\cargo.exe" test --lib editor::            # 单测(P3-1 后模块名变了)
# 前端
& "C:\Program Files\nodejs\node.exe" node_modules/vue-tsc/bin/vue-tsc.js --noEmit
& "C:\Program Files\nodejs\node.exe" node_modules/eslint/bin/eslint.js src
& "C:\Program Files\nodejs\node.exe" node_modules/vite/bin/vite.js build
& "C:\Program Files\nodejs\node.exe" --test src/modules/quickpanel/engine.test.ts src/lib/calc.test.ts src/lib/theme.test.ts src/modules/editor/editor/outline.test.ts

注意:本机沙箱禁止直接 spawn 工作区外的可执行文件,必须用绝对路径调用 cargo.exe / node.exe(node 在 C:\Program Files\nodejs\)。 新增依赖用 bun add,且 $env:TEMP 必须指向可写目录(详见 §9.4 的坑记录)。

11.5 改名核对脚本(P3-1/P3-2 完成后跑)

# 应无输出(除文档与 §9 的历史记录外)
Select-String -Path (Get-ChildItem src,src-tauri/src,src-tauri/capabilities -Recurse -Include *.ts,*.vue,*.rs,*.json |
  ForEach-Object { $_.FullName }) -Pattern "notes_" | ForEach-Object { "$($_.Path):$($_.LineNumber)" }
Select-String -Path (Get-ChildItem src -Recurse -Include *.ts,*.vue |
  ForEach-Object { $_.FullName }) -Pattern "notesStore|notesClient" | ForEach-Object { "$($_.Path):$($_.LineNumber)" }
# 命令三方一致性(应 定义 = 导出 = 注册)
# 见 §9.3 的接线核对做法:比对 commands.rs / mod.rs / lib.rs 两处

附录 A:命名规范(v2)

  • 模块 id:editor;显示名:编辑器;图标 key:editor。
  • 窗口 hash:#editor-window(可带 ?file=<abs path> 或 ?note=<rel path>);label 前缀:editor-window。
  • 事件名(8 个,与 v1 一一对应,最后一个为 P4 新增):editor-settings / editor-library-changed / editor-file-changed / editor-sync-progress / editor-new-note / editor-open-editor / editor-open-file / editor-open-folder。
  • 窗口 label 前缀:editor-window-(不是事件,列在此处避免与上表混淆)。
  • 前端组件:DirectoryPanel.vue / RecentPanel.vue / EditorTabs.vue(P4)/ DrawerPanel.vue(大纲与双链的容器)为 P3/P4 新增。
  • Rust 命令前缀:editor_;Rust 模块目录:src-tauri/src/editor/。
  • 前端 store:useEditorStore;类型文件:src/types/editor.ts;IPC 客户端:src/modules/editor/editorClient.ts。
  • 存储:{appData}/editor/settings.json;库内私有目录:<库根>/.editor/。
  • keyring 键:editor.webdav.password。

附录 B:能力边界(明确不做)

不做 理由
调试器 / 内嵌终端 / LSP 补全 / Git 集成 那是 IDE,与「notepad++ 式编辑器」的定位冲突;本项目终端模块已覆盖终端场景
块编辑器(拖拽块、/ 菜单) 与「.md 文本是唯一真相」的模型不匹配(v1 已确认)
远端直连读写(把 WebDAV 当工作区) 离线不可用、限流敏感、冲突面大(v1 已确认)
目录树全文索引 与「打开快」冲突(Q3)
字符频率统计式编码探测 短文本上比规则更不可靠(§5.1)
二进制文件编辑 编码/换行模型只对文本成立;识别为二进制时明确拒绝并提示用外部工具