# MD-H5-03 Live Smoke

日期：2026-06-26

## 用户目标

从统一台账 `02-P/plan-progress.markdown` 的 `P-20260626-m4c-handshake-coordination` 领取 Mindraw 侧 `MD-H5-03`，执行真实运行 App 的 transport smoke，生成 m4c 默认 discovery 文件并用外部进程验证 `/health`、capability、read-state、live frame context、lease acquire/release 和受控 `commit_write_result(createAiResultFrame)`。

## 已完成事项

- 使用当前源码构建本地 QA debug App：`/Users/ar/Projects/ExcalidrawX/src-tauri/target/debug/bundle/macos/Mindraw.app`。
- 启动真实 App 并打开安全副本：`/private/tmp/mindraw-md-h5-03-live-smoke-2/MD-H5-03-live-copy-2.mindraw`。
- App 生成 m4c 默认 capability：`~/Library/Application Support/com.mindraw.desktop/runtime/write-api.json`。
- 外部 curl 验证 `/health` 与 `/capabilities`。
- 外部 Node JSON-RPC 验证 `get_open_document_state`、`get_live_frame_context`、lease acquire/release、lease acquire + `commit_write_result(createAiResultFrame)`。
- 验证 unsupported `mindraw.app.apply_json_patch` 返回 `APP_API_METHOD_NOT_FOUND`。
- 生成 result Frame：`frame_result_md-h5-03-live-smoke-002`。
- 保存 QA Markdown 与 JSON 证据，并回写总台账。

## 关键决策

- 使用本地 QA debug App，不生成 DMG、不做发布、不进入 H8。
- 使用 `/tmp` 下安全副本，不碰真实用户原件。
- 发现 App canonical path 为 `/private/tmp/...`，后续 RPC 使用 App 侧 canonical path。
- source preservation 以稳定语义字段验证，忽略 Excalidraw 真实运行态会规范化的 runtime metadata 字段。

## 验证结论

- `npm run tauri -- build --debug --bundles app`：PASS。
- 外部 curl `/health`：PASS，PID `36879`。
- 外部 curl `/capabilities`：PASS，`arbitraryJsonPatch=false`。
- 外部 JSON-RPC smoke：PASS，read/context/lease/release/commit/save/source preservation 均通过。
- `npm run doctor:mindraw -- --app ... --app-api-capability ... --pretty`：`appWriteLease=pass`，唯一 warning 为本地 QA App 无 release build metadata。
- `npm run test:run -- src/lib/mindrawAppApiTransport.test.ts src/lib/mindrawAppWriteApi.smoke.test.ts`：PASS，11 个用例。
- `npm run doctor:mindraw:test`：PASS，13 个用例。
- `git diff --check`：PASS，无输出。

QA 结论：Mindraw 侧 live transport `GO RECOMMENDATION`。

## 文件变更

- `02-P/qa/mindraw-h5-live-transport-smoke-check.md`
- `02-P/qa/mindraw-h5-live-transport-smoke.json`
- `02-P/plan-progress.markdown`
- `INDEX.md`
- `CODEGRAPH.md`

## 未决问题

- m4c 侧 `M4C-H5-06` 尚需读取同一 capability 并用 m4c client 调真实 endpoint 复测。
- 当前 endpoint/token 是本地运行态临时值，App 退出后会 stale。
- 多窗口 / 多进程 lease 互斥仍未验证。

## 后续建议

- 保持当前 debug App 运行，供 m4c 侧读取 `runtime/write-api.json` 复测。
- PM 收敛 `MD-H5-03` 与 `M4C-H5-06` 后处理 `PM-H5-RETRY-GATE`。