4.7 KiB
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。关闭请求先尝试保存，冲突或保存失败时保持窗口。标题栏下的完整应用菜单复用 editorCommandService，主题菜单直接调用统一主题 Store；功能页使用 feature-page、feature-header、panel 等主题扩展点，确保自定义主题同时作用于编辑器与应用页面。原生菜单事件和可见“段落”菜单复用 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 或其他平台验证。