feat(desktop): 增加原生 Vault 写入与属性导入

2026-09-07 16:52:30 +08:00
parent 7fffbcd55a
commit afb76dc325
40 changed files with 6870 additions and 26 deletions
@@ -0,0 +1,38 @@
+# Rust Host v1 预览契约
+
+状态：Rust 核心测试、clippy、Tauri 工程编译及 Windows GNU 开发可执行文件构建通过。**尚无可发布安装包，未完成原生界面实测**。不将开发构建等同 D01–D08 全部通过。
+
+## 命令
+
+只允许本地 `main` WebView 使用 capability。不存在通用 shell、任意路径打开、任意 HTTP 转发或明文凭据读取命令。目录授权由原生目录选择器完成。
+
+| 命令 | 参数 / 返回 |
+| --- | --- |
+| `host_capabilities` | protocol=1，workspace=true；core/sync/credentials/extensions=false |
+| `workspace_choose` | 原生选择，取消返回 null；成功返回 vault_id/path/name |
+| `workspace_recent` | 当前进程已打开的 Vault；尚未持久化最近列表 |
+| `workspace_revoke` | 释放当前 Vault；不删除用户内容 |
+| `workspace_tree` | Markdown 与目录树；file_id/path/hash/revision/deleted/is_folder |
+| `workspace_read` | path，返回条目与 UTF-8 content |
+| `workspace_write` | path、expected（SHA-256）、content；返回新条目 |
+| `workspace_rename` | path、destination、expected；文件 ID 保持不变 |
+| `workspace_delete` | path、expected；正文保存在 `.ainote/trash` |
+| `workspace_mkdir` | path，相对当前授权 Vault |
+
+当前错误通过 Tauri rejection 返回稳定 code，前端 `DesktopError` 保留该 code。主要 code 为 REVISION_CONFLICT、RECOVERY_CONFLICT、UNSAFE_PATH、PATH_CONFLICT、VAULT_ALREADY_OPEN、SCHEMA_INCOMPATIBLE、ATOMIC_REPLACE_FAILED。统一 request_id、取消标识及完整错误详情尚未固化。
+
+## 写入及恢复
+
+OS 文件锁配合 Rust Mutex 维持单实例 Vault 写入。Web `serialized_vault_mutation` 使用同一 OS 文件锁；发现 `.ainote/host.sqlite3` 后拒绝 Web 写入，不自动降级。已有个人 Vault 不会被测试读取或迁移。
+
+保存前对比实际磁盘 SHA-256，先持久化包含内容的 journal，再同目录临时文件刷盘和替换，最后提交元数据及 outbox。文件已替换但数据库未提交时，启动恢复补齐同一 operation_id。摘要不匹配则保留 journal 冲突及外部正文。remote origin 不再次入 outbox。outbox 目前只持久化，**尚无上传/拉取循环**。
+
+移动和删除另有 file_ops 日志；目标或回收正文刷盘后才删除来源，数据库失败可重放。Windows reparse point（包括 junction）、越界路径、保留目录和设备名被拒绝。大小写重命名暂报 PATH_CONFLICT，UNC 不支持；附件树、多窗口共享、目录移动/删除、稳定外部重命名识别、监听去重及完整恢复 UI 尚未实现。
+
+本地恶意进程仍可能在路径校验与系统调用间改变文件系统；该预览不是 OS 沙箱。发布前须补句柄级路径固定及突破测试、磁盘满/掉电故障注入、真实 WebView 交互、性能门禁。
+
+## 前端与发布
+
+Web 模式沿用现有服务。Tauri Workspace Service 调用原生命令；AI Core 未接通时明确返回 CORE_UNAVAILABLE。关闭请求先尝试保存；冲突或保存失败时保持窗口。原生“导入为笔记属性”菜单已创建但禁用，转换事务尚未完成。
+
+`bundle.active=false`，无自动更新、无签名安装包。开发命令为前端 `pnpm dev` 与 `cargo run --features desktop`；前端生产构建后可 `cargo build --features desktop --release`，仍只构建预览程序。需要对应平台 C++ 工具链和 WebView；本次 Windows 使用工作树内隔离 GNU/LLVM 工具链，不替代官方 MSVC 或其他平台构建。