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