edit | blame | history | raw

Phase 3.8 Lease Spike

日期：2026-06-26

用户目标

用户要求进入 Phase 3.8：document lease / App write API spike。

已完成事项

  • 新增 Phase 3.8 spike 目录：02-P/Round01-mindraw-defstart/spikes/002-document-lease-app-write-api/。
  • 新增可运行脚本：validate-document-lease.mjs，在临时目录生成测试 .mindraw 包，验证 document lease / App write API 状态机。
  • 新增 spike README，记录 Given / When / Then、覆盖项、发现和 verdict。
  • 新增主项目契约文档：02-P/功能任务/document-lease-app-write-api-spike.md。
  • 新增 QA 记录：02-P/qa/mindraw-phase38-document-lease-spike-check.md。
  • 同步更新 02-P/plan-progress.markdown 和 INDEX.md。

关键决策

  • App 打开同一 .mindraw 包时，外部工具直接写 package 必须继续返回 APP_LEASE_REQUIRED。
  • Phase 3.8 的正确方向是 App-mediated write：App 作为唯一写入方，外部工具只能基于 App live context / workingRevision 提交受控 mutation。
  • 必须区分 diskRevision 和 workingRevision；dirty 文档不能用磁盘 revision 作为写入凭证。
  • dirty 文档不是天然 No-Go；如果外部工具读取的是 App live working snapshot，并且 commit 时 workingRevision 未变化，App 可以合并 result Frame 并保存。
  • lease 必须短 TTL、独占、绑定 writePlanId / expectedWorkingRevision，并在 commit 时重新校验。

文件变更

  • 02-P/Round01-mindraw-defstart/spikes/002-document-lease-app-write-api/README.md
  • 02-P/Round01-mindraw-defstart/spikes/002-document-lease-app-write-api/validate-document-lease.mjs
  • 02-P/功能任务/document-lease-app-write-api-spike.md
  • 02-P/qa/mindraw-phase38-document-lease-spike-check.md
  • 02-P/plan-progress.markdown
  • INDEX.md
  • .codex-sessionhistory/2026-06-26-Phase38LeaseSpike.md

验证

  • node 02-P/Round01-mindraw-defstart/spikes/002-document-lease-app-write-api/validate-document-lease.mjs：PASS。
  • node --check 02-P/Round01-mindraw-defstart/spikes/002-document-lease-app-write-api/validate-document-lease.mjs：PASS。
  • git diff --check 覆盖本轮相关文件：PASS。

覆盖项：

  • direct-file-write-open-package-rejected：PASS / APP_LEASE_REQUIRED
  • app-api-dirty-live-context-commit：PASS
  • disk-revision-cannot-write-dirty-working-copy：PASS / WORKING_REVISION_MISMATCH
  • user-edit-after-lease-rejected：PASS / WORKING_REVISION_MISMATCH
  • concurrent-lease-rejected：PASS / LEASE_ALREADY_HELD
  • expired-lease-rejected：PASS / LEASE_EXPIRED
  • closed-document-app-api-rejected：PASS / APP_DOCUMENT_NOT_OPEN

未决问题

  • 未实现生产 Tauri command。
  • 未接真实 Excalidraw editor API。
  • 未验证多窗口、多 tab、App 后台启动、焦点切换和 UI 错误反馈。
  • 未实现正式 MCP server 或真实用户 .mindraw 写回。
  • Phase 4 .assets 权威资产治理仍未完成。

后续建议

下一步如果继续主项目实现，应进入 Phase 3.8 production design：

  1. 只读 App state / live frame context API。
  2. Lease manager：acquire / release / expiry / concurrency。
  3. 受控 createAiResultFrame mutation，并复用现有保存路径。
  4. 真实 App QA：dirty、revision mismatch、expired lease、concurrent lease、save failed。