# 4-23 [process] Local / Cloud 显式桥接 P3 候选合同 v1

> 更新时间：2026-05-07
>
> 关联：
> - `4-21-local-folder-convex-unified-tree-source-v1.md`
> - `4-22-local-folder-convex-unified-tree-execution-checklist-v1.md`

## 1. 结论

Local / Cloud 桥接只允许作为显式动作出现，不进入 Local Folder 打开、读取、watcher、保存、拖拽或普通树操作主链。

固定候选动作：

- `tree.bridge.import.preview`
- `tree.bridge.import.execute`
- `tree.bridge.export.preview`
- `tree.bridge.export.execute`
- `tree.bridge.publish.preview`
- `tree.bridge.publish.execute`
- `tree.bridge.sync.preview`

`sync.execute` 不进入 P3 默认范围；P3 只冻结候选 preview 和手动执行边界。

## 2. Import Local Folder To Cloud

输入：

- `sourceKind=local_folder`
- `rootUri=file://...`
- `targetWorkspaceId=ws_...`
- `selection=rowIds | all`

preview 必须输出：

- 将创建的 cloud documents。
- 将上传的附件。
- 本地 `mnote_id` / `.mnote/page-ids.json` 到 Convex document id 的映射策略。
- 冲突列表：同名页面、重复 `mnote_id`、不可读文件、超限附件。
- 回滚计划：已创建 document id、已上传 storage id、可删除顺序。

execute 规则：

- 必须引用 preview id。
- 必须幂等。
- 失败时返回可重试 cursor 和 rollback plan。
- 不允许修改 local root，除非用户显式要求写入 cloud id mapping。

## 3. Cloud Workspace Export To Local Folder

输入：

- `sourceKind=convex_workspace`
- `workspaceId=ws_...`
- `targetRootUri=file://...`
- `selection=rowIds | all`

preview 必须输出：

- 将写入的 `.md` 文件路径。
- 将下载的附件路径。
- Convex document id / asset id 到本地路径的映射。
- 冲突策略：默认 incremental naming，不静默覆盖。
- 回滚计划：本次新建文件、覆盖前备份、下载失败项。

execute 规则：

- 必须引用 preview id。
- Markdown frontmatter 必须保留 `mnote_id` 或 `cloud_document_id`。
- 附件路径和对象存储 id 写入 `.mnote/cloud-export-map.json`。
- 失败时不删除已存在用户文件；只删除本次创建且仍未被用户修改的文件。

## 4. Publish Local Page To Cloud

输入：

- `sourceKind=local_folder`
- `rootUri=file://...`
- `documentId=local-md...`
- `targetWorkspaceId=ws_...`
- `visibility=private | workspace | public`

preview 必须输出：

- 将创建或更新的 cloud page。
- 页面正文、frontmatter、附件引用的转换计划。
- 权限差异说明：local OS 权限不等于 Convex ACL。

execute 规则：

- 只发布选中的单页或显式选择的子树。
- 不启动双向同步。
- 发布结果写入 `.mnote/publish-map.json` 时必须经用户确认。

## 5. Manual Sync Candidate

sync 只能作为候选 preview：

- 比较 local revision、cloud domain event cursor 和 mapping。
- 输出三方差异：local-only、cloud-only、conflict。
- 不自动执行。

禁止项：

- 打开 local folder 时自动 import。
- 保存 local `.md` 时自动上传 Convex。
- Convex stream 事件自动改写本地文件。
- 把 OS 文件权限解释为 Convex ACL。

## 6. Done Gate

P3 进入实现前必须先满足：

- P0/P1/P2 的 local 和 convex 树操作 smoke 全绿。
- preview UI 已复用统一 preflight/result 组件。
- import/export/publish 均有 rollback plan。
- 至少一个真实浏览器 smoke 覆盖 preview，不允许直接跳 execute。