8.7 KiB
Tauri / Rust 桌面客户端需求说明（第三阶段）
状态：需求基线；Rust Host、原生 Vault、无边框窗口控制和属性导入已进入 Alpha，Sidecar、Stronghold、多窗口及发布包仍未完成。本文不表示已有可发布安装包。
基线日期：2026-09-06。第三阶段完整范围与实施顺序见第三阶段实施规划。
1. 目标与边界
第三阶段在现有 Vue 编辑器和 FastAPI AI Core 上接入 Tauri 2 / Rust Host，提供原生窗口、菜单、多 Vault 文件管理、安全凭据存储和 Sidecar 生命周期管理。
- Vue 负责页面、编辑事务、主题和交互状态；通过既有 Service 边界调用能力，不在组件中散布平台判断。
- Rust Host 负责系统能力、路径权限、原生菜单事件及受控进程生命周期。
- FastAPI AI Core 保留笔记解析、索引、检索、模型和 Agent 业务职责；同一文件不得同时由 Host 和 AI Core 无协调地写入。
- Web 模式保留可运行能力；桌面专有功能通过能力检测显隐，不用无响应按钮假装已实现。
2. 顶部菜单与元数据格式一键导入
2.1 入口预留
桌面客户端顶部菜单栏的 段落 → 导入为笔记属性… 预留元数据格式导入功能，与标题、正文、列表等段落操作归组。它处理笔记内容中的元数据，不是主题包安装入口。
稳定的前端命令标识为 editor.import-note-properties。属性转换处理器、Tauri 原生菜单事件和无边框窗口内的可见“段落”菜单均分发同一命令，没有维护第二套转换逻辑。默认快捷键为 Windows/Linux 的 Ctrl+Alt+P、macOS 的 ⌘⌥P；Rust Host 使用 CmdOrCtrl+Alt+P 注册 accelerator，仍由活动编辑器能力检查决定是否可用。
无边框桌面窗口在标题栏下方固定显示“文件 / 编辑 / 段落 / 格式 / 视图 / 主题 / 帮助”菜单行。段落菜单提供正文、六级标题、列表、引用、代码块和属性导入；格式菜单复用编辑器已有的加粗、斜体、行内代码、代码块、公式及警告框命令；主题菜单列出当前已安装主题并可进入主题管理。保存使用 Ctrl+S；撤销和重做沿用编辑器已有的 Ctrl+Z 与 Ctrl+Shift+Z，菜单只调用相同编辑器命令，不额外注册按键监听，以免一次按键执行两次。
除编辑器原有的加粗、斜体、撤销和重做外，桌面键表还注册正文/标题 Ctrl+0…6、删除线 Alt+Shift+5、行内代码 Ctrl+反引号、链接 Ctrl+K、代码块 Ctrl+Shift+K、公式块 Ctrl+Shift+M、行内公式 Ctrl+Shift+L、表格 Ctrl+Alt+T、默认警告框 Ctrl+Alt+C、分割线 Ctrl+Shift+H、三类列表和引用。Ctrl+Alt+P 在源码模式执行属性导入，在写作模式创建或聚焦 YAML Front Matter。警告框菜单列出 note、abstract、info、todo、tip、important、success、question、warning、failure、danger、bug、example、quote 十四种样式。
Markdown 格式（含警告框）与元数据共用 editorCommandService 的能力查询和命令分发接口，详见 警告框与桌面编辑命令开发说明。Host 根据 supported / enabled 显隐或禁用菜单，不能把已预留的命令 ID 当作已可执行能力；原生快捷键不绕过活动文档、只读和冲突检查。
2.2 输入与转换规则
- 无选区时识别当前笔记开头的属性块；有选区时只处理完整的属性块。无活动笔记、加载中、只读或冲突状态下禁用操作，并提供原因。
- 支持标准 YAML frontmatter，以及历史编辑器产生的
***开头、title:/tags:字段、横线结尾的兼容形式。普通分隔线、代码块和包含冒号的正文不得被误判。 - 将识别成功的内容规范化到文件头唯一的
---frontmatter 中，正文中的旧属性块仅在转换成功后移除。 - 写作模式显示独立标题和可编辑标签；源码模式显示真实
title/tags字段。标签必须进入现有保存和索引链路，能被标签筛选使用，不能只创建装饰性标签元素。 - 保留未知属性及其类型，特别是
embedding_local_only等行为配置。复杂 YAML 不得用正则拆分后静默丢弃；无法无损处理时说明原因，并保留原文供源码编辑。 - 标签支持字符串、逗号分隔值和 YAML 列表，去重并保留顺序；中文、空格、转义字符须正确往返。空标签与删除标签有明确语义。
- 已存在 frontmatter 时合并到同一个属性块；字段值冲突时展示差异供用户选择，禁止静默覆盖。重复执行不重复添加标签或属性块。
2.3 编辑与保存行为
- 无歧义转换一次菜单操作完成，并构成一个可撤销的编辑事务；转换失败不得改变文档或保存状态。
- 转换作用于当前内存文档，不先从磁盘读取旧内容覆盖未保存编辑。操作绑定文件标识和文档版本，异步处理期间切换文件或继续编辑时，应取消或重新校验。
- 成功后进入现有脏状态和自动保存流程。磁盘保存失败显示可重试状态，撤销／重做同时恢复正文、属性及标签。
- 属性块不进入正文大纲；标题跳转、引用定位仍使用完整原文件的正确偏移。写作／源码切换、保存后重开不得改变属性语义。
- 当前 Alpha 已覆盖完整解析、合并冲突、单事务撤销和菜单分发的自动测试；写作模式属性面板、重开后的标签检索、缩放和真实 WebView 操作仍须按本节验收，不能仅凭单元测试视为全部通过。
3. 桌面基础需求
| 模块 | 第三阶段要求 | 验收要点 |
|---|---|---|
| 窗口与菜单 | 原生窗口控制、顶部菜单、焦点分发、关闭前未保存处理 | 菜单操作针对活动编辑器；多窗口不串文档；取消关闭保留编辑 |
| Vault 与文件系统 | 原生目录选择、多 Vault、最近打开、文件监听、路径规范化 | 未授权目录不可访问；重命名同步树和打开文件；外部修改不静默覆盖 |
| 写入与恢复 | 原子写入、版本／内容摘要校验、失败重试和异常退出恢复 | 不产生半写文件；并发保存不覆盖新版本；恢复流程可验证 |
| AI Core Sidecar | 启停、健康检查、日志、崩溃恢复、退出清理 | 不残留进程；不可用时显示原因；本地通信有访问控制 |
| 凭据 | 按既有架构接入 Stronghold／平台安全存储，制定开发凭据迁移方案 | 前端只持有凭据引用；不回显密钥；失败可恢复且不丢凭据 |
| MCP 与插件 | 按已冻结的 Host 沙箱契约落实文件、网络和子进程授权 | 沿用审批边界，不因桌面集成默认放开权限 |
| 主题 | 复用主题包校验；原生文件选择和下载适配共用检查流程 | 导入不自动启用；安装失败可恢复；ZIP 路径和资源限制继续有效 |
| 外观与导航 | 继承主题、代码配色、相对纸页宽度、文件／大纲切换 | 窗口缩放、高 DPI、深浅主题下无截断；键盘导航完整 |
| 发布 | Windows、macOS、Linux 构建与安装验证；签名、升级及回滚方案 | 未准备好签名和回滚前不启用自动更新；平台差异有说明 |
根据 2026-09-06 的范围确认，各扩展社区、独立 Sync Server 和桌面同步客户端正式纳入第三阶段，具体工作包与验收门禁见第三阶段实施规划。本文聚焦桌面客户端细则；移动端仍不属于本阶段首个稳定版本范围。
4. 开发顺序与验收
- 冻结 Host 能力与 Service 适配接口，明确每类数据的写入责任方及权限模型。
- 接入窗口、菜单与编辑命令路由，完成“段落 → 导入为笔记属性…”的编辑器事务。
- 接入 Vault、文件监听、冲突处理、Sidecar 和凭据迁移。
- 完成平台测试、安装包和升级恢复验收。
元数据导入专项测试至少覆盖：标准／历史格式、普通正文误判、代码围栏、未知字段、复杂 YAML、同名字段冲突、重复导入、中文标签、撤销重做、未保存文档、处理中切换文件、保存失败、重开后标签检索，以及写作／源码模式的大纲与引用偏移。
第三阶段实现 PR 必须补充实际 Command 名称、输入输出类型、错误码、平台差异和测试证据；在此之前本文所有 Host 能力均标为计划实现。