# 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_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 调用原生命令；AI Core 未接通时明确返回 CORE_UNAVAILABLE。桌面窗口关闭系统装饰，统一由应用标题栏提供拖动、最小化、最大化/还原及关闭；窗口命令只授予本地 `main` WebView。关闭请求先尝试保存，冲突或保存失败时保持窗口。原生“导入为笔记属性”菜单仅在源码模式和已打开笔记时启用，转换作为单次编辑器历史事务执行。

`bundle.active=false`，无自动更新、无签名安装包。开发命令为前端 `pnpm dev` 与 `cargo run --features desktop`；前端生产构建后可 `cargo build --features desktop --release`，仍只构建预览程序。需要对应平台 C++ 工具链和 WebView；本次 Windows 已使用系统 `x86_64-pc-windows-gnu` 工具链构建，仍不替代 MSVC 或其他平台验证。