docs: separate design reference queue

- 将不直接执行的 process-reference 文档迁入各域 reference 目录

- 更新 design/README、AGENTS 和总序文档,固定 process/draft/reference/done 目录语义

- 修正活跃文档中指向旧 process 位置的参考链接

验证:git diff --check;codegraph sync .
This commit is contained in:
lix-2026
2026-05-21 10:19:02 +08:00
parent 1956a8a21a
commit 1569699fbb
30 changed files with 103 additions and 90 deletions
@@ -1,119 +0,0 @@
# 4-23 [process] Local / Cloud 显式桥接 P3 候选合同 v1
> 更新时间:2026-05-07
>
> 当前状态:`process-reference / P3 candidate`。本文只冻结 Local / Cloud 显式桥接候选合同,未进入当前实施;不得把它当作 local-first 默认读写路径。
>
> 关联:
> - `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。