checkpoint before gfm ast parser design

2026-05-08 00:41:03 +08:00
parent e8ba12e461
commit c620b9e40c
41 changed files with 12270 additions and 263 deletions
@@ -0,0 +1,117 @@
+# 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。