远程 Vault（SSH/SFTP）¶
文件权威在服务器；本机 UI + 可选远端 BYOA。
能力¶
| 层 | 说明 |
|---|---|
| 连接 | remote_connect / disconnect；密钥或 SSH agent；remote_ssh_config_hosts 解析 ~/.ssh/config 供对话框联想 |
| 文件 | SFTP list/read/write/mkdir/remove/bytes |
| Catalog | work mirror（本机查询，写回远端） |
blob 缓存（remote_cache_*） |
|
| Agent | ACP over SSH：remote_agent_probe / scan / 与 agent_run_once 集成（命令实现属 agent 域 features/agent/commands/remote.rs，经反转 trait agent::remote_host::{RemoteAgentHosts, RemoteAgentLaunch} 复用 remote 域的 SSH session/exec） |
| 入库 / 回收站 | 远端写路径与 trash bridge；features 命令经反转 trait import::RemoteImportOps / trash::remote_ops::RemoteTrashOps 调用（integration::remote 实现并在 app 启动时注册为 State） |
| Connector | 可绑定 remote:<sessionId> |
前端伪路径 remote:<sessionId>（解析在 core/remote.rs，纯字符串工具，features/integration 共用）。客户端：macOS / Linux（Windows 客户端暂不支持打开远程 Vault）。
Catalog 发布¶
连接与 remote_paper_list 通过 SSH 调用服务器的 python3 标准库 sqlite3，只读执行 VACUUM INTO，读取包含已提交 WAL 内容的一致快照。服务器需提供 python3 及 sqlite3 模块；失败时不回退到裸读主文件。
重新加载论文列表（含手动刷新）通过 SQLite backup API 更新 work mirror，与现有 Catalog 操作共用连接锁；单篇查询继续读取本机镜像。未发布的本机修改不会被刷新覆盖，只读断开不发布。远端非空 WAL 尚在时拒绝替换主库，需关闭远端数据库连接后重新打开 Vault；仍按单写者使用。
本机 work mirror 开启 WAL。初始化远端 Catalog 与每次 push 都通过 SQLite VACUUM INTO 导出独立一致快照，读取已提交的主库与 WAL 内容；其他写连接保持打开或存在未提交事务时也不依赖连接关闭/checkpoint。临时快照在成功或失败后自动清理，导出失败不上传。
发布仍先检查远端 size/mtime 是否与上次一致，再上传临时文件并 rename（不支持时回退覆盖）；该检查保留现有乐观冲突语义，不是远端原子 CAS。快照只包含开始读取时可见的已提交数据，之后的修改由后续 push 发布。sidecar 投影及远端会话清退仍见架构计划 B1/B2。
论文命令的实现共享（本地/远端）¶
remote_paper_get / remote_paper_set_tags / remote_paper_set_is_read 与本地 paper_get / paper_set_tags / paper_set_is_read 共用同一实现入口 src-tauri/src/features/paper/catalog/service.rs：命令先解析目标（本地 resolve_vault → PathBuf，远端 try_session! → session.work_root），再调用同一用例（同一校验、错误文案与 catalog 写入）；远端壳额外在写入成功后经 RemoteSession::push_catalog 发布 catalog（PaperCommitOptions.push_catalog 与断开 flush 复用同一方法）。remote_paper_rescan 的 SFTP 回填扫描（marker 探测 + NOTES.md 标题回填 + remote_rescan 兜底行）是远端独有实现，本地 rescan 走 papers::rebuild_from_disk，两者只在参数/包络与 push 时机上一致。
已知差异（wire 契约保留，待后续单独评估）：paper_list 返回按 id 去重的 PaperListRow（含本地 has_pdf 探测）；remote_paper_list 刷新远端镜像后返回裸 PaperRecord[]，不去重、无 has_pdf（前端视为"未探测"，见 api.md 的 paper_list 一节）。两端命令名、参数、返回类型（specta bindings）保持现状，不因去重实现而变化。
超时¶
建连与校验约 15s；SFTP 操作约 30s；SSH ServerAlive；不自动重连、不重放写。
代码¶
src-tauri/src/integration/remote/（handle 解析：crates/agentero-core/src/remote.rs）
教程：../usage/remote-vault.md