72 lines
7.3 KiB
Markdown
72 lines
7.3 KiB
Markdown
# Tauri / Rust 桌面客户端需求说明（第三阶段）
|
|
|
|
状态：需求预留，尚未实现桌面客户端。本文不表示已有可调用的 Tauri Command 或可发布安装包。
|
|
|
|
基线日期：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`，已进入前端 v1 命令目录，但属性转换处理器与 Tauri IPC 尚未实现。原生菜单和编辑器命令面板应分发同一命令，避免两套转换逻辑。快捷键待第三阶段统一分配，不抢占现有编辑快捷键。
|
|
|
|
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 编辑与保存行为
|
|
|
|
- 无歧义转换一次菜单操作完成，并构成一个可撤销的编辑事务；转换失败不得改变文档或保存状态。
|
|
- 转换作用于当前内存文档，不先从磁盘读取旧内容覆盖未保存编辑。操作绑定文件标识和文档版本，异步处理期间切换文件或继续编辑时，应取消或重新校验。
|
|
- 成功后进入现有脏状态和自动保存流程。磁盘保存失败显示可重试状态，撤销／重做同时恢复正文、属性及标签。
|
|
- 属性块不进入正文大纲；标题跳转、引用定位仍使用完整原文件的正确偏移。写作／源码切换、保存后重开不得改变属性语义。
|
|
- 当前分支的 `frontend/src/features/editor/noteMetadata.ts` 仅是简单属性块展示与标签编辑基础；桌面阶段需补齐完整解析、合并冲突、单事务撤销和原生菜单分发，不能直接视为本节已经验收。
|
|
|
|
## 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 能力均标为计划实现。
|