44 KiB
编辑器模块规划(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. 结论先行
八个关键判断。
-
模块改名
notes→editor,但一次到位、不留双命名。id/ 窗口 label / 事件名 / Rust 命令前缀 / 目录名 / 存储键全部统一。半改不改(模块叫 editor、命令还叫notes_*)比不改更糟:读代码的人要同时维护两套心智。改名是机械工作(约 400 处标识符),风险集中在「漏改一处」,用脚本核对(§9.6)。 -
「笔记」不是被删掉,而是被降级为一种能力。 编辑器的最小模型是「路径 + 字节 + 编码」,笔记库是加在它之上的一层(库根沙箱 + front-matter + 索引 + 双链)。因此文件是真相层,笔记库是视图层——这条和 v1 的「文件即真相」并不冲突,只是把「库」从中心挪到了并列位置。
-
左侧导航 = 两个并列的树 + 三块辅助能力。 两个树:笔记库(沙箱、有索引、有双链)与本地目录(任意路径、无索引、无 front-matter 语义)。三块辅助:文件名/内容搜索、最近打开(文件夹与文件分开记)、定位到资源管理器。
-
多编码是这一版的新增硬需求,且必须「可切换」。 探测链:BOM → 严格 UTF-8 → GB18030(中文存量主力)→ 用户手动指定。写回默认按读取时的编码。切换编码的语义是「换一种方式解释磁盘字节」而不是「重新解释缓冲区文本」——因此切换动作会从磁盘按新编码重新解码(有未保存改动时先让用户三选一,见 §5.3)。
-
系统集成走用户级注册表,不需要管理员权限。 文件关联(双击打开)走 Tauri
fileAssociations;资源管理器右键菜单(文件/文件夹)走HKCU\Software\Classes\*\shell\*与Directory\shell\*,用已在依赖树里的winreg写(项目已有system_proxy.rs/glsmtc.rs两处先例)。注册动作放在设置页按钮里、默认不自动写注册表——开发模式下的 exe 路径是target\debug\thing.exe,自动注册会留下指向临时产物的僵尸菜单项。 -
默认全局快捷键
Alt+E打开编辑器。 走既有shortcut.rs(原子注册 + 冲突检测),设置页可改。 -
不引入「工作区」概念(已拍板)。 用户要的是「右键文件夹 → 在这里打开」,用当前目录根这一个状态就够了(可切换 + 有历史)。引入 workspace 会连带出「多根 / 会话恢复 / 每根独立状态」三个复杂度,而收益(同时开两个目录树)在 notepad++ 式用法里很低。因此侧栏只有一个「目录」面板,根是单值。
-
不做的事(明确划界,避免无限扩张):不做 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 — 编辑器化改造(结构)
- 改名:
notes→editor(id / 窗口 label / 事件 / 命令前缀 / 目录 / 存储键 / Rust 模块名),脚本核对无残留(§9.6)。 - 库内目录改名:
<库根>/.notes/→<库根>/.editor/(含sync.json),首次打开时惰性迁移;索引可重建,丢了无损。 - 侧栏重构:
库 / 目录 / 检索 / 最近四段;大纲与双链移到编辑区右侧抽屉。 - 本地目录树:打开文件夹(对话框 / 右键菜单 / 最近文件夹)、树浏览、文件名过滤、打开文件、在资源管理器中显示、复制路径、手动刷新。
- 最近记录:最近文件 + 最近文件夹(落
settings.json,分组显示、可清空、失效项灰显)。 - 主模块页 Tab 调整:概览 / 库 / 编辑器 / 集成。
P4 — 编码与系统集成(这一版的核心价值)
- 编码探测链(§5.1)+ 状态栏显示编码/换行/只读。
- 切换编码(§5.3):重解码对话框三选项、保存时不可表示字符报错、换行独立切换。
- 系统集成:
Alt+E默认值;HKCU 右键菜单注册/卸载(文件 + 文件夹 + 目录背景),设置页按钮 + exe 路径显示 + dev 环境提示。 - 只读打开与大文件降级提示。
- 标签页(多文档):
Ctrl+W/Ctrl+Tab、每标签独立编码与视图模式、关闭确认。
P5 — 完善(本轮不做,按体感排后续优先级)
- 语言包补齐:
.sh/.ps1/.toml/.ini/.dockerfile走legacy-modes;.scss/.less引入@codemirror/lang-sass。 - 目录树上的文件操作完善:拖拽移动、在新窗口打开、批量重命名。
- Markdown 内嵌代码块高亮(
codeLanguages,需解决 language-data 异步 vsmarkdown()同步)。 - 双链图谱(数据已就绪:
editor_link_graph命令可用,仅缺可视化)。 - 会话恢复:关窗后重开恢复文档与光标位置。
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 坑记录(跨版本有效)
<SelectItem>不能用空串value:reka-ui 把空串保留给 placeholder,会直接抛异常。用显式哨兵值('__all__'/'__current__')在调用点翻译。报错栈指向SelectItem.vue而不是调用方 —— 先搜value: ''。cargo add <tauri 插件>会连带升级整个 tauri 依赖树(wry / tray-icon / window-vibrancy),而 dev 启动会校验 JS 包与 crate 的 minor 是否一致。改一边必须同时看另一边。- 不要把
package.json交给 PowerShell 的Set-Content -Encoding UTF8(PS 5.1 写入 BOM),带 BOM 会让 Vite 读 PostCSS 配置直接失败。用node -e或UTF8Encoding($false)。 - CRLF 下反推行首偏移一律偏 1:必须预先算
lineStarts表,不要在循环里「减回去」。 - front-matter 用状态机而不是布尔量:首行
---是开头,布尔量会在第 0 行就关掉状态,导致第 2 行的闭合---把上一行元数据提升成 Setext 标题。 let plan = plan(...)会遮蔽函数名,第二个测试起报E0618且位置离成因很远。函数名避开返回值名。enum不能出现在node --test直接跑的文件里(Node 的 TS 支持是 strip-only)。用const X = {...} as const+ 类型别名。- quick-xml 0.42 的
QName::as_ref()返回&str(旧版&[u8]),BytesText无decode();升级时只cargo update -p quick-xml,避免动到 wry 链。 - 冷启动的文件关联事件会丢:
setup里emit时 WebView 还没加载。改为存OnceLock<Mutex<Option<PathBuf>>>,前端注册完监听后主动取走。 - 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) |
| 二进制文件编辑 | 编码/换行模型只对文本成立;识别为二进制时明确拒绝并提示用外部工具 |