edit | blame | history | raw

MD-H5-02 Transport

日期：2026-06-26

用户目标

从统一台账 02-P/plan-progress.markdown 的 P-20260626-m4c-handshake-coordination 领取 Mindraw 侧 MD-H5-02，实现 H5 解阻用最小外部 App API transport / capability 暴露，让运行中的 Mindraw 可被本机 m4c 安全发现并调用 read / lease / controlled commit 最小闭环。

已完成事项

  • 新增 Rust 本机 App API transport：src-tauri/src/app_api_transport.rs。
  • App 启动时绑定 127.0.0.1 随机端口，写入 m4c 默认 discovery 文件 ~/Library/Application Support/com.mindraw.desktop/runtime/write-api.json，并保留 app-api-capability.json 兼容副本。
  • /rpc 支持 JSON-RPC 调用 get_open_document_state、get_live_frame_context、acquire_write_lease、release_write_lease、commit_write_result(createAiResultFrame) 和 capabilities。
  • 通过 bearer token / X-Mindraw-Api-Token 做本机调用 guard。
  • 新增前端 dispatcher：src/lib/mindrawAppApiTransport.ts，复用既有 MD-H1-02/03/04/05 read / lease / mutation / save path。
  • 更新 doctor：默认读取 runtime/write-api.json，校验 required methods、token、arbitraryJsonPatch=false 和 /health。
  • 新增 QA 证据：02-P/qa/mindraw-h5-app-api-transport-check.md。
  • 更新 CODEGRAPH.md、INDEX.md 和总台账 Progress Log，标记 MD-H5-02 完成。

关键决策

  • transport 只做本机 HTTP JSON-RPC + capability discovery，不重写业务写入链路。
  • write path 仍由前端 facade 执行，避免 Rust 直接改场景 JSON。
  • 不开放任意 JSON patch，只允许 createAiResultFrame。
  • capability primary 路径对齐 m4c 已准备的默认路径 runtime/write-api.json。

验证结论

  • npm run test:run -- src/lib/mindrawAppApiTransport.test.ts src/lib/mindrawAppWriteApi.smoke.test.ts：PASS，11 个用例。
  • npm run doctor:mindraw:test：PASS，13 个 Node test。
  • cargo test --manifest-path src-tauri/Cargo.toml app_api_transport：PASS，3 个 Rust test。
  • npm run build：PASS，仅既有字体和 chunk size 警告。
  • git diff --check：PASS，无输出。

QA 结论：PASS FOR MD-H5-02 TRANSPORT POC。

文件变更

  • src-tauri/src/app_api_transport.rs
  • src-tauri/src/lib.rs
  • src/lib/mindrawAppApiTransport.ts
  • src/lib/mindrawAppApiTransport.test.ts
  • src/App.tsx
  • scripts/mindraw-doctor.mjs
  • scripts/mindraw-doctor.test.mjs
  • CODEGRAPH.md
  • INDEX.md
  • 02-P/qa/mindraw-h5-app-api-transport-check.md
  • 02-P/plan-progress.markdown

未决问题

  • 尚未启动真实 Tauri App 后由 m4c 进程外 curl 完整联测。
  • capability stale 依赖 doctor health 识别。
  • token 当前存于本机 capability 文件；后续是否升级为更强 handshake 由 PM 决定。
  • 多窗口 / 多进程 lease 互斥仍未验证。
  • 真实 Tauri command ACL / event bridge 需 H5 retry smoke 覆盖。

后续建议

  • PM 收敛 MD-H5-02 与 M4C-H5-05 后，决定是否重开 H5 retry smoke。
  • m4c 下一步应读取 runtime/write-api.json 调真实 endpoint，不得用 direct package write 替代。