41 lines
4.5 KiB
Markdown
41 lines
4.5 KiB
Markdown
# Rust Host v1 预览契约
|
||
|
||
状态：Rust 核心测试、clippy、Tauri 工程编译及 Windows GNU 开发可执行文件构建通过。**尚无可发布安装包，新标题栏仍待原生界面实测**。不将开发构建等同 D01–D08 全部通过。
|
||
|
||
## 命令
|
||
|
||
只允许本地 `main` WebView 使用 capability。不存在通用 shell、任意路径打开、任意 HTTP 转发或明文凭据读取命令。目录授权由原生目录选择器完成。
|
||
|
||
| 命令 | 参数 / 返回 |
|
||
| --- | --- |
|
||
| `host_capabilities` | protocol=1，workspace/core=true；sync/credentials/extensions=false |
|
||
| `core_request` | 仅代理固定的 `http://127.0.0.1:8000/health` 与 `/api/*` JSON 请求；路径、方法和超时由 Host 限制 |
|
||
| `workspace_choose` | 原生选择，取消返回 null；成功返回 vault_id/path/name |
|
||
| `workspace_open` | 只允许重开应用数据目录中已持久化授权的规范化路径 |
|
||
| `workspace_recent` | 最近 20 个用户主动选择的 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）、越界路径、保留目录和设备名被拒绝。最近 Vault 授权保存在应用数据目录的独立 SQLite 中，使用事务更新且不包含正文；任意路径不能绕过目录选择直接加入。大小写重命名暂报 PATH_CONFLICT，UNC 不支持；附件树、多窗口共享、目录移动/删除、稳定外部重命名识别、监听去重及完整恢复 UI 尚未实现。
|
||
|
||
本地恶意进程仍可能在路径校验与系统调用间改变文件系统；该预览不是 OS 沙箱。发布前须补句柄级路径固定及突破测试、磁盘满/掉电故障注入、真实 WebView 交互、性能门禁。
|
||
|
||
## 前端与发布
|
||
|
||
Web 模式沿用现有服务。Tauri Workspace Service 调用原生命令；当前预览版通过 Host 连接已在 `127.0.0.1:8000` 启动的 AI Core，连接失败时返回 CORE_UNAVAILABLE。随机端口、临时令牌和自动管理进程仍属于后续 Sidecar 交付。桌面窗口关闭系统装饰，统一由应用标题栏提供拖动、最小化、最大化/还原及关闭；窗口命令只授予本地 `main` WebView。关闭请求先尝试保存，冲突或保存失败时保持窗口。原生菜单事件和标题栏可见的“段落”菜单复用 `editor.import-note-properties`；仅在源码模式、已打开笔记且无冲突时启用，转换作为单次编辑器历史事务执行。
|
||
|
||
`bundle.active=false`，无自动更新、无签名安装包。开发命令为前端 `pnpm dev` 与 `cargo run --features desktop`；生产 EXE 必须在 `frontend` 目录执行 `pnpm desktop:build`，由 Tauri CLI 先构建并嵌入前端资源。不要用普通 `cargo build --release` 代替该命令，否则 Rust Host 会更新但 WebView 仍可能携带旧资源。需要对应平台 C++ 工具链和 WebView；本次 Windows 已使用系统 `x86_64-pc-windows-gnu` 工具链构建，仍不替代 MSVC 或其他平台验证。
|