2026-06-25 Round01 开工评审

用户目标

用户要求组织两位架构师和两位 QA，对 Round01-mindraw-defstart 当前状态进行小会评审，判断 Round01 是否具备开工条件。

评审范围

只读评审以下文档：

• 02-P/plan.markdown
• 02-P/Round01-mindraw-defstart/README.md
• 02-P/Round01-mindraw-defstart/ADR-001-mindraw-format-contract.md
• 02-P/Round01-mindraw-defstart/manifest-schema-draft.md
• 02-P/Round01-mindraw-defstart/compatibility-matrix.md
• 02-P/Round01-mindraw-defstart/qa-entry-checklist.md
• 02-P/Round01-mindraw-defstart/fixtures-plan.md

参与角色

• 架构师 A
• 架构师 B
• QA A
• QA B

统一结论

结论：CONDITIONAL GO

Round01 可以继续推进，但开工范围必须限定为：

• 格式契约收口
• ADR 定稿
• manifest schema 定稿
• QA 用例化
• fixtures 准备
• 小范围 Tauri 目录包 spike

当前不具备直接进入生产代码实现的条件。

如果“开工”指进入 DocumentKind / DocumentRef / DocumentFormatService / AssetStore 的生产实现 PR，则当前结论是 NO-GO。

主要依据

• .mindraw 作为 Mindraw 自有容器格式的方向成立。
• .mindraw 不是 .excalidraw 分叉的边界已经清楚。
• 第一版显式另存/导出、不自动迁移旧 .excalidraw、不做 zip、不做 runtime embed、不自动执行脚本，这些原则已经清楚。
• 但当前多个关键文档仍是草案，且待确认项会直接影响后续代码实现。

必须补齐项

1. 定稿 MVP 包结构：

• 主 scene 文件名固定为 drawing.excalidraw。
• 资产目录固定为 .assets。
• 第一版只支持普通目录包，不注册 macOS package。

1. 定稿 manifest.json 最小字段和校验语义：

• schemaVersion
• createdBy.appVersion
• scene.sha256
• requiredFeatures / optionalFeatures
• manifest 损坏、缺失、字段类型错误时的恢复策略。

1. 明确 .assets 第一版权威关系：

• 第一版 .assets 是镜像/资产池，不是唯一权威源。
• Excalidraw files.dataURL 仍是运行时和导出安全底座。
• 如果 drawing.excalidraw、manifest、.assets 不一致，需要明确报错和恢复策略。

1. 补齐路径与写入安全契约：

• 包内相对路径。
• 禁止 ..。
• 禁止绝对路径。
• 禁止 symlink escape。
• 大小写/Unicode 冲突。
• 原子写入。
• 半写入恢复。

1. 锁定 Obsidian .excalidraw.md 目标插件版本和验收样例。

2. 补齐 feature gate：

• 第一版如果遇到未来 embeds/、automation/，只识别 feature gate。
• 不解析、不执行、不承诺兼容。

1. 将 QA 入口清单从原则表升级为可执行测试用例：

• 用例 ID。
• fixture。
• 前置条件。
• 操作步骤。
• 预期结果。
• 断言方式。
• 证据要求。

1. 准备最小 fixtures：

• minimal-empty
• single-image
• missing-asset
• damaged-manifest
• damaged-scene
• illegal-path
• hash-mismatch
• 旧 .excalidraw 回归样本。

可后置项

• .assets 成为唯一权威资产源。
• 复杂资产去重、GC、压缩自动化。
• 完整 mindraw.json embed schema。
• HTML/XML runtime。
• terminal runtime。
• browser/WebView runtime。
• Automation Runtime / ExcalidrawAutomate 兼容层。
• macOS package 注册和 Finder 展示。
• .excalidraw.md 反向打开为 .mindraw。

推荐下一步

1. 把 ADR 从草案推进到“已采纳/已确认”。
2. 增加一张 MVP contract 表。
3. 增加一张 failure matrix。
4. 将 QA P0/P1 转成测试用例表。
5. 准备最小 fixtures 或冻结 fixture 规格。
6. 做 Tauri 目录包 spike，验证选择、打开、保存、覆盖、watch、拖放和原子写入。

文件变更

本轮只新增本会话记录，没有修改产品代码或 Round01 正式文档。

2026-06-25 全局链接补充复评

用户要求在全局链接 / deep link / documentId / linking / Phase 3.5 已补入文档后，重新组织两位架构师和两位 QA 复评 Round01 是否具备开工条件。

复评结论：上一轮 CONDITIONAL GO 不变。

具体含义：

• 可以继续推进：格式契约收口、ADR 定稿、manifest schema 定稿、QA 用例化、fixtures 规格或最小样例准备、Tauri 目录包 spike、Phase 3.5 deep link addressing spike 的调研/验证。
• 不可以直接进入：DocumentKind / DocumentRef / DocumentFormatService / AssetStore / DeepLinkService 生产实现 PR、.mindraw 正式读写、系统 scheme 注册、single-instance、真实定位交互、.assets 权威化、Obsidian 导出改造、HTML/terminal/browser runtime、Automation Runtime。

复评变化点：

• 全局链接不是推翻性变化，不会把 Round01 降为整体 NO-GO。
• 全局链接也不会把 Round01 升级为无条件 GO。
• 全局链接新增了“全局链接契约门禁”，这些门禁阻塞生产实现，但不阻塞 Round01 继续收口。

新增必须收口项：

1. documentId 是否 MVP 必填、生成规则、稳定性、复制/另存为是否换新、隐私边界、重复/缺失/非法值处理。
2. linking 字段语义：它是能力声明还是索引入口；addressing: ["file", "documentId", "elementId"] 的顺序、兼容含义和未来扩展规则。
3. 第一版链接格式：建议 mindraw://open?file=...&element=...，doc=... 作为未来 fallback。
4. DeepLinkService 边界：只解析、校验、路由、定位；不得触发脚本、不得自动执行 automation、不得直接依赖 Excalidraw 内部 API。
5. deep link failure matrix：无效路径、权限不足、包移动、manifest 损坏、scene hash mismatch、element/frame 不存在、文档已打开且 dirty、App 未启动/已启动、URL 参数非法、scheme 未注册、single instance 未接收。
6. 全局链接真实用户路径用例：复制对象或 frame 链接，放到 AI、Markdown、Finder / Terminal open 等本机位置，未启动或已启动 Mindraw，打开或切换目标文件，定位并高亮对象。
7. fixtures 增补：global-link-target、missing-object、moved-package、unsaved-open-doc-conflict，并继续保留上一轮要求的 damaged-manifest、damaged-scene、illegal-path、hash-mismatch、旧 .excalidraw 回归样本。

更新后的推荐下一步：

1. 增加 MVP contract 表，把 documentId、linking.defaultScheme、elementId/frameId 来源写成必定或后置。
2. 增加 failure matrix，覆盖 .mindraw 包损坏、资产损坏、路径安全和 deep link 失败态。
3. 把 QA checklist 改成用例表：fixture、前置条件、操作、预期、逆检、断言、证据。
4. 冻结最小 fixtures 清单，再进入 Tauri 目录包 spike。
5. deep link spike 放在 Tauri 目录包 spike 之后，不进入当前生产实现。