edit | blame | history | raw

2026-06-25 Round01 文档建设

用户目标

用户确认 Round01 第一批开工建设，要求基于已评审的 .mindraw 格式规划开始推进。用户明确确认 7 项前置决策：

  • 第一批范围限定为文档契约收口、QA 用例化和 fixtures 规格，不进入生产代码实现。
  • MVP 包结构固定为 Board.mindraw/manifest.json、Board.mindraw/drawing.excalidraw、Board.mindraw/.assets/。
  • 第一版只按普通目录包处理，不注册 macOS package。
  • .assets 第一版只是镜像/资产池，drawing.excalidraw 中的 files.dataURL 仍是运行时和导出安全底座。
  • documentId MVP 必填，不包含用户名、路径等隐私信息；另存为新 .mindraw 包默认生成新的 documentId。
  • 默认不静默压缩图片资产；未来压缩必须在 manifest 中记录处理策略。
  • Obsidian 互通先按当前项目已有导出实现和当前稳定插件行为写验收口径，不锁死具体插件版本。
  • 全局链接不提前；Phase 3.5 不提前到 Phase 2 后面。本轮只写契约、failure matrix 和 QA 用例，不实现 mindraw:// runtime。

已完成事项

  • 按用户中途指令重新读取 /Users/ar/.codex/AGENTS.md 和 /Users/ar/Projects/ExcalidrawX/AGENTS.md。
  • 读取 INDEX.md、CODEGRAPH.md、02-P/plan-progress.markdown，确认新规则中 02-P/plan.markdown 已停用，后续统一更新 plan-progress.markdown。
  • 更新 Round01 README，记录第一批建设 TODO、已确认 MVP 决策、本轮不做范围和 Tauri 目录包 spike 边界。
  • 更新 ADR，明确 .mindraw MVP 普通目录包结构、MVP 契约表、Phase 3.5 不提前、进入生产实现前置门禁。
  • 更新 manifest schema，明确 MVP 必填字段、documentId 规则、校验与恢复语义、全局链接契约边界。
  • 更新兼容矩阵，补齐 .mindraw 打开失败态、Deep Link Failure Matrix、旧 .excalidraw 不回归定义。
  • 更新 QA 入口清单，把原则表升级为可执行 P0/P1 用例，包含 fixture、前置条件、操作、正检、逆检和证据要求。
  • 更新 fixtures 计划，冻结第一批 fixtures 规格，覆盖最小包、单图片、缺失资产、损坏 manifest、损坏 scene、非法路径、hash mismatch、旧 .excalidraw 回归和 Phase 3.5 链接契约入口。
  • 更新 02-P/plan-progress.markdown，记录用户确认、第一批文档建设进展、已确认决策和后置问题。

关键决策

  • Round01 当前仍是格式定义期，不做生产代码。
  • .mindraw MVP 先作为普通目录包，不做 zip、不注册 macOS package。
  • drawing.excalidraw 是主 scene 固定文件名。
  • .assets 是第一版镜像/资产池，不替代 Excalidraw files.dataURL。
  • documentId MVP 必填，另存新包默认换新。
  • 全局链接 runtime 保持 Phase 3.5，不提前；本轮只做格式和 QA 契约。
  • 旧 .excalidraw 工作流必须不回归。

文件变更

  • 修改 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
  • 修改 02-P/plan-progress.markdown
  • 新增本会话记录 .codex-sessionhistory/2026-06-25-Round01文档建设.md

未决问题

  • 尚未生成真实 fixture 文件；本轮只冻结规格。
  • 尚未执行 Tauri 目录包 spike；需在 Round01 文档复核后进入。
  • 尚未进入 DocumentKind / DocumentRef / DocumentFormatService 生产实现。
  • 尚未实现 .mindraw 读写、导出互通或 mindraw:// runtime。

后续建议

  • 下一步先对第一批 Round01 文档做架构 / QA 复核。
  • 复核通过后按 fixtures 计划生成第一批最小 fixture。
  • 再进入 Tauri 目录包 spike，验证选择、打开、保存、watch、拖放、路径校验和原子写入。
  • Spike 通过后，再进入 Phase 1 文档容器抽象生产实现方案。