edit | blame | history | raw

2026-06-25 Mindraw 深链基础链路

用户目标

继续推进 .mindraw 基本可用，进入 Phase 3.5：验证本机 mindraw:// Global Link / Deep Link，让从任意位置点击链接打开 Mindraw 文件成为可实现路径。

已完成事项

  • 接入 Tauri 2 deep-link 插件：
  • @tauri-apps/plugin-deep-link
  • tauri-plugin-deep-link
  • src-tauri/capabilities/default.json 增加 deep-link:default
  • src-tauri/tauri.conf.json 增加 plugins.deep-link.desktop.schemes = ["mindraw"]
  • 新增链接格式：mindraw://open?documentId=<documentId>&element=<elementId>。
  • 新增兼容解析：mindraw://localhost?documentId=<documentId>&elementId=<elementId>。
  • 新增本机私有 registry：打开、保存、另存 .mindraw 包时登记 documentId -> packagePath 到 mindraw-documents.json。
  • 新增后端 resolve_mindraw_link：解析 URL，查 registry，复核包内 manifest 的 documentId，返回 package path 和 element id。
  • 补齐 registry 陈旧记录清理：registry 指向的路径已不是 .mindraw 目录包时，或包内 manifest documentId 与 registry key 不匹配时，删除对应 entry 并提示重新打开包刷新 registry。
  • 新增前端 openMindrawDeepLinkUrls()，并在 App.tsx 接入 getCurrent() 和 onOpenUrl()。
  • 修复 deep link 对象定位时机问题：mindraw-focus-element 事件可能早于新 active file 的 editor 监听器注册；现在由 ExcalidrawEditor 缓存目标，等 active .mindraw 和 Excalidraw API 就绪后选中并滚动。
  • 接入 Excalidraw generateLinkForSelection：当前 active 文件是 .mindraw 且存在 documentId 时，Copy link to object 复制 mindraw://open?documentId=...&element=...，不再复制 tauri://localhost?element=...。
  • 新增 QA 文档 02-P/qa/mindraw-phase35-deeplink-check.md。
  • 新增 QA 截图 02-P/qa/mindraw-phase35-deeplink-smoke.png。
  • 新增复制对象链接 smoke 截图 02-P/qa/mindraw-phase35-copy-link-smoke.png。
  • 更新 02-P/plan-progress.markdown、CODEGRAPH.md、INDEX.md。

关键决策

  • Global Link 第一版不把本机路径写进链接，避免泄露用户名和目录结构。
  • documentId 负责跨对话/跨文档引用，实际本机定位由私有 registry 完成。
  • registry 陈旧 entry 清理只处理明确不可用的记录；包移动后的自动搜索/迁移不在本轮做，仍要求用户重新打开 .mindraw 包刷新本机索引。
  • 本轮不覆盖 /Applications/Mindraw.app；改用临时唯一 bundle id QA app 验证系统级 URL 触发，避免影响用户当前安装版。
  • element 参数进入第一版可用链路：打开包后定位并选中目标对象。
  • 用户最早观察到的 tauri://localhost?element=... 只保留为普通非 .mindraw 文件的回退；.mindraw 包里的对象链接第一版使用 documentId + element。

文件变更

  • package.json
  • package-lock.json
  • src-tauri/Cargo.toml
  • src-tauri/Cargo.lock
  • src-tauri/capabilities/default.json
  • src-tauri/tauri.conf.json
  • src-tauri/src/lib.rs
  • src/App.tsx
  • src/components/ExcalidrawEditor.tsx
  • src/lib/mindrawDeepLink.ts
  • src/lib/mindrawDeepLink.test.ts
  • src/types/index.ts
  • src/store/useStore.ts
  • src/store/useStore.test.ts
  • 02-P/qa/mindraw-phase35-deeplink-check.md
  • 02-P/qa/mindraw-phase35-deeplink-smoke.png
  • 02-P/qa/mindraw-phase35-copy-link-smoke.png
  • 02-P/plan-progress.markdown
  • CODEGRAPH.md
  • INDEX.md

验证结果

  • npm run test:run -- src/lib/mindrawDeepLink.test.ts src/hooks/useMenuHandler.test.ts src/lib/obsidianExcalidraw.test.ts：PASS，3 个测试文件，33 个测试通过。
  • npm run test:run -- src/lib/imageDrop.test.ts src/hooks/useMenuHandler.test.ts src/hooks/useKeyboardShortcuts.test.tsx src/lib/documentFormat.test.ts src/lib/obsidianExcalidraw.test.ts src/lib/mindrawDeepLink.test.ts src/store/useStore.test.ts：PASS，7 个测试文件，84 个测试通过。
  • cargo test --locked --manifest-path src-tauri/Cargo.toml mindraw_deep_link_tests：PASS，5 个测试通过。
  • cargo test --locked --manifest-path src-tauri/Cargo.toml：PASS，31 个测试通过。
  • cargo check --manifest-path src-tauri/Cargo.toml：PASS。
  • npm run build：PASS，仍有既有字体、Tauri dialog import 和 chunk size warning。
  • npm run tauri -- build --debug --bundles app：PASS，生成本地 QA debug .app。
  • git diff --check：PASS。
  • Info.plist 检查：debug .app 已生成 CFBundleURLSchemes = ["mindraw"]。
  • 临时唯一 QA bundle 系统级 smoke：热启动 open -b com.mindraw.desktop.codexqa "mindraw://open?documentId=mdoc_smoke_deeplink_20260625&element=deep_link_target_red" PASS，打开 TargetBoard.mindraw 并选中/滚动到红色目标对象。
  • 临时唯一 QA bundle 系统级 smoke：冷启动同一条 URL PASS，启动应用、打开 TargetBoard.mindraw 并选中/滚动到红色目标对象。
  • 临时唯一 QA bundle 复制对象链接 smoke：右键红色目标对象，点击 Copy link to object，剪贴板为 mindraw://open?documentId=mdoc_smoke_deeplink_20260625&element=deep_link_target_red，不是 tauri://localhost?element=...。
  • cargo fmt --manifest-path src-tauri/Cargo.toml：失败，当前 stable toolchain 未安装 cargo-fmt / rustfmt。

未决问题

  • 未覆盖正式 /Applications/Mindraw.app 的替换安装验证；本轮只用临时唯一 QA bundle 验证系统级冷/热启动，避免影响用户当前安装版。
  • registry 陈旧 entry 清理已覆盖缺失/无效路径与 documentId 不匹配；包移动后的自动搜索/迁移策略仍未实现，仍需要重新打开包刷新 documentId -> packagePath。

后续建议

  • 后续若进入可分发/安装包流程，再用正式安装版替换验证 mindraw:// 默认 handler。
  • 后续设计包移动自动重定位/迁移策略：重复 documentId、registry 陈旧后的用户提示和恢复路径。