chore: land tree view-state, vault, Pi module split, and repo hygiene

Persist PageTree expand state via control-plane view-state and align chevron/DOM with restored expansion; keep Sidex-style shallow page-tree scan and drop the unused recursive scanner that only added cargo noise. Add password vault workbench routes/runtime/skill/CLI, split page_ai_pi into a module package, and retire Hermes/ACP/OpenHub recycle + root harness evidence from the index while gitignoring recycle and local diag dumps. Archive superseded design/bugs docs under old/, point architecture at ARCHITECTURE.md, and refresh smokes for Pi S1–S7, vault, and editor regressions so the working tree can stay clean.
2026-07-21 05:13:05 +08:00
parent 6f9c7d3b58
commit b798f628ee
264 changed files with 17480 additions and 17314 deletions
@@ -1,5 +1,63 @@
 # mnote 测试参考

+## ⚡ 浏览器测试快速启动（AI agent 专用）
+
+> **执行浏览器验证前，先确认此节，避免浪费时间。**
+
+### 1. 检查服务是否已运行
+```bash
+ss -ltnp 'sport = :3000'
+# 有输出 = 服务已运行，跳到步骤 3
+# 无输出 = 服务未运行，继续步骤 2
+```
+
+### 2. 启动服务（后台模式）
+```bash
+nohup npm run dev:hot > /tmp/mnote-dev.log 2>&1 &
+echo $!
+# 等待 5-10 秒后检查日志
+sleep 8 && grep -E 'gateway 已启动|Running' /tmp/mnote-dev.log
+```
+**关键点：**
+- 启动命令是 `npm run dev:hot`（不是 desktop:hot）
+- `dev:hot` 默认启用 `MNOTE_WEB_ALLOW_DEV_FIXTURES=1`
+- 使用 cargo-watch 自动重编译
+- 端口固定为 3000
+
+### 3. 浏览器验证步骤（Paseo）
+```bash
+# 1. 新建标签页
+paseo_browser_new_tab url=http://localhost:3000/auth
+
+# 2. 等待页面加载
+paseo_browser_wait url=localhost:3000 timeoutMs=15000
+
+# 3. 截图（如果返回 "tab not painted"，等 3 秒重试）
+paseo_browser_screenshot
+
+# 4. 快速登录（snapshot 找到 @e5 即"测试账号快速登录"按钮）
+paseo_browser_click ref=@e5
+
+# 5. 等待进入工作区
+paseo_browser_wait url=localhost:3000 text=工作区
+
+# 6. 截图
+paseo_browser_screenshot
+```
+
+### 4. 测试账号
+- 邮箱：`mnote.e2e@example.com`
+- 密码：`MnoteE2E123!`
+- 用户名：`mnote-e2e`
+
+### 5. 常见问题
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| ERR_CONNECTION_REFUSED | 服务器未启动 | 先运行 `npm run dev:hot` |
+| tab not painted | 页面未渲染完成 | 等待 3 秒后重试截图 |
+| Paseo 终端无输出 | 前台进程阻塞 | 用 `nohup ... &` 后台启动 |
+| `desktop:hot` vs `dev:hot` | 启动命令不同 | 浏览器测试用 `dev:hot` |
+
 这份文档面向 `/mnt/Data1T/mnote/scripts` 目录下的现有测试脚本，目标不是重新设计测试体系，而是把当前已经在用的 smoke、回归脚本、截图取证和人工复核方式整理成一套可执行参考。

 当前结论先说在前面：
@@ -36,12 +94,12 @@ node scripts/task490-runtime-surfaces-smoke.js
 - 入口与认证：`task114-rust-web-gateway-entry-smoke.js`、`task159-auth-entry-smoke.js`、`task097-homepage-entry-smoke.js`
 - Rust SSR 文档页 / Page Aggregate：local-first 默认优先 `task167-local-markdown-title-body-options-no-convex-smoke.js`；Page Aggregate browser conversion / compat fallback 改动补跑 `task522-page-aggregate-compat-fallback-contract.js`；cloud/control-plane 文档可补跑 `task110-page-title-single-truth-smoke.js`、`task-page-aggregate-body-sync-smoke.js`、`task-page-aggregate-options-sync-smoke.js`、`task-page-aggregate-refresh-persistence-smoke.js`
 - leptos-tiptap runtime surface：`task490-runtime-surfaces-smoke.js`；需要验证保存回读可补跑 `task121-rust-web-editor-island-hydration-smoke.js`，但它仍使用 `/api/tree/commands create` 准备文档，不作为无 Convex 默认基线；需要验证浮层互斥和更多菜单状态时再跑 `task158-e30-menu-state-smoke.js`
- local-first 本地工作区：`task164-desktop-hot-local-folder-main-entry-smoke.js`、`task166-local-first-managed-workspace-no-convex-smoke.js`、`task167-local-markdown-title-body-options-no-convex-smoke.js`、`task436-local-markdown-open-document-external-change-smoke.js`、`task443-local-markdown-asset-upload-smoke.js`、`task451-local-markdown-conflict-resolution-ui-smoke.js`、`task452-local-search-index-browser-smoke.js`、`task453-local-folder-page-ai-changed-files-smoke.js`；WorkspacePath / ObjectIdentity runtime 消费统一改动补跑 `task524-workspace-object-identity-matrix-smoke.js`。`task452` 只覆盖普通本地搜索、settings API、tag/backlink API 和旧 local-index UI 不复活；资料库问答、PDF/Office/image source ingestion 与引用回跳改跑 WeKnora / provider-neutral knowledge-rag 脚本。
- LightRAG / Knowledge RAG 资料库：`task781-knowledge-bases-registry-smoke.js`、`task785-weknora-create-kb-folder-ingest-search-smoke.js`、`task787-weknora-default-lightrag-legacy-smoke.js` 覆盖默认 provider、知识库列表、摄取、搜索、引用桥接与 legacy LightRAG guard。旧 `task529/530/531/534` LightRAG 脚本只作为 legacy fallback / 历史对照，不进入默认回归。旧 OpenHub 专项资料库 smoke 已软归档到 `recycle/20260712-pi-ts-openhub-retirement/`；旧 `task526-local-folder-ocr-api-smoke.js` / OCR sidecar 链路已退役并软归档；`/api/search/documents` 不作为 WeKnora、LightRAG legacy、LiteParse、OCR sidecar 或 evidence.sqlite 的资料库问答 fallback。
+- local-first 本地工作区：`task164-desktop-hot-local-folder-main-entry-smoke.js`、`task166-local-first-managed-workspace-no-convex-smoke.js`、`task167-local-markdown-title-body-options-no-convex-smoke.js`、`task436-local-markdown-open-document-external-change-smoke.js`、`task443-local-markdown-asset-upload-smoke.js`、`task451-local-markdown-conflict-resolution-ui-smoke.js`、`task452-local-search-index-browser-smoke.js`、`task453-local-folder-page-ai-changed-files-smoke.js`；WorkspacePath / ObjectIdentity runtime 消费统一改动补跑 `task524-workspace-object-identity-matrix-smoke.js`。`task452` 只覆盖普通本地搜索、settings API、tag/backlink API 和旧 local-index UI 不复活；资料库问答、PDF/Office/image source ingestion 与引用回跳改跑 LightRAG / provider-neutral knowledge-rag 脚本。
+- LightRAG / Knowledge RAG 资料库：LightRAG 是默认 provider。资料源、摄取、source scope 与 watcher 改动优先跑 `task532-knowledge-rag-docx-ingestion-smoke.js`、`task533-knowledge-rag-source-watcher-sync-smoke.js`、`task534-knowledge-rag-source-management-scope-smoke.js`、`task538-knowledge-rag-source-scope-api-smoke.js`；引用和 Page AI final answer 改动补跑 `task529-knowledge-rag-citation-resource-tab-smoke.js`、`task530-knowledge-rag-page-ai-final-answer-smoke.js`；真实 Pi + LightRAG 服务可用时补跑 `task-pi-lab-real-lightrag-smoke.js`。WeKnora 仅是历史/备用 provider，不进入默认回归。旧 OpenHub 专项资料库 smoke 已软归档到 `recycle/20260712-pi-ts-openhub-retirement/`；旧 `task526-local-folder-ocr-api-smoke.js` / OCR sidecar 链路已退役并软归档；`/api/search/documents` 不作为 LightRAG、LiteParse、OCR sidecar 或 evidence.sqlite 的资料库问答 fallback。
 - local Markdown conflict regression：`task510-local-markdown-conflict-regression-group.js` 串联真实冲突、连续上传、新建页面、外部恢复、多 tab CAS 与上传 409 孤儿策略；可用 `MNOTE_CONFLICT_REGRESSION_TASKS=a.js,b.js` 做定点子集。
 - tree realtime / live cache：`task446-tree-rename-dual-browser-live-smoke.js`、`task447-tree-move-order-dual-browser-live-smoke.js`、`task448-tree-resync-recovery-dual-browser-smoke.js`、`task449-tree-sse-reconnect-snapshot-recovery-smoke.js`
 - 资源对象与 mindmap：`task455-local-folder-mindmap-clean-smoke.js`、`task456-resource-object-shell-sync-smoke.js`、`task166-mindmap-phase6-block-smoke.js`、`task167-mindmap-kmind-parity-smoke.js`、`task168-mindmap-put-validator-smoke.js`；Page AI mindmap skill / 资源生成改动补跑 `task503-mindmap-skill-capability-smoke.js`，真实 mindmap resource tab / Page AI target 改动补跑 `task525-page-ai-mindmap-resource-target-smoke.js`
- Page AI / agent history / ChatOnly：`task502-page-ai-agent-selector-context-smoke.js` 覆盖 Page AI agent/context/target picker、skills source 和 run payload；opencode WebUI embed 改动补跑 `task763-page-ai-opencode-embed-smoke.js`，只验证真实登录、Page AI 抽屉、opencode iframe/host chrome 和 changed file/open/refresh DOM hook，不 mock 聊天成功；raw local resource target 改动补跑 `task520-page-ai-raw-resource-target-smoke.js`；`task504-page-ai-history-agent-filter-smoke.js` 覆盖 Page AI 历史按 agent 过滤；ChatOnly / provider session 绑定改动优先跑 `task512-chatonly-doubao-sync-smoke.js`，跨 provider 同步补跑 `task513-chatonly-provider-sync-smoke.js`
+- Page AI / agent history / ChatOnly：`task502-page-ai-agent-selector-context-smoke.js` 覆盖 Page AI agent/context/target picker、skills source 和 run payload；raw local resource target 改动补跑 `task520-page-ai-raw-resource-target-smoke.js`；`task504-page-ai-history-agent-filter-smoke.js` 覆盖 Page AI 历史按 agent 过滤；ChatOnly / provider session 绑定改动优先跑 `task512-chatonly-doubao-sync-smoke.js`，跨 provider 同步补跑 `task513-chatonly-provider-sync-smoke.js`。`task763` / `task765` 是 OpenCode debug fallback 专项脚本，不属于默认回归，待 debug route 彻底移除时一并退役。
 - Dev hot / OnlyOffice live bridge：Sidebar dev hot reload 入口改动补跑 `task514-sidebar-dev-hot-reload-gating-smoke.js`；OnlyOffice live bridge session / scope / HTTP 工具边界改动补跑 `task515-onlyoffice-live-scope-http-smoke.js`；bridge session/token/queue/current/close 和 `docKey/pageOrigin` 元数据改动补跑 `task516-onlyoffice-bridge-multisession-browser-smoke.js`；bridge plugin index / `Asc.plugin` direct loop / plugin 元数据透传改动补跑 `task517-onlyoffice-bridge-plugin-direct-smoke.js`；真实 ONLYOFFICE iframe / DocumentServer session、同文档双 tab、resource scope 和非 dry-run 写入落点改动补跑 `task518-onlyoffice-real-iframe-session-scope-smoke.js`；Page AI 真实 UI 选择 Office target 并冻结 live bridge session 改动补跑 `task523-page-ai-onlyoffice-real-target-session-smoke.js`
 - local resource lifecycle API：`task437-local-folder-asset-trash-lifecycle-smoke.js`，现在只验证 `local-file:*` delete / restore / purge，不再依赖普通 `.txt` 是否出现在 UI 文件树。

@@ -52,6 +110,8 @@ node scripts/task490-runtime-surfaces-smoke.js
 - 旧 Convex 兼容 smoke 已软删除到 `recycle/20260527-legacy-cleanup/convex/scripts/`，包括 `task163`、`task174`、`task175`、`task427`、`task428`、`task429`、`task430`、`task431`、`task432`、`task433`、`task434`。
 - `task179-tree-create-delete-no-reload-smoke.js`：覆盖 `/tree` debug shell。`/tree` 已是显式 debug/internal 边界，脚本默认阻断；只有设置 `MNOTE_ALLOW_DEBUG_TREE_SMOKE=1` 时才可执行。
 - `task123-rust-web-tree-live-stream-consumer-smoke.js`：只证明 `/api/tree/events` SSE fallback 仍可用。当前 realtime 主链是 WebSocket push + SSE fallback；验证主链时优先使用 446 / 447 / 448，只有排查 fallback 时再跑 123。
+- WeKnora 默认 provider 脚本（`task544`、`task769`、`task772`、`task777`、`task781`、`task783`、`task784`、`task785`、`task787`、`task788`、`task789`、`task790`、`task79x`）已退役；它们与 LightRAG 默认 provider 主线相反。
+- Hermes/ACP/Reasonix 页面 AI 主流程 smoke 已退役；只保留 `task-hermes-page-ai-retirement-guard.js` 防止旧 runtime 复活。`task762-page-ai-board-first-smoke.js` 也已退役。
 - 旧 `task019`、`task021`、`task022` 这类早期 UI regression 脚本已软删除到 `recycle/scripts/retired-ui-regressions/`，只作为历史对照；后续默认不要用于当前 Rust SSR / local-first 主路径验收。

 ### 0.3 其他 current 候选脚本
@@ -120,9 +180,8 @@ node scripts/task490-runtime-surfaces-smoke.js
 代表脚本：

 - `task119-rust-web-wolai-visual-regression-smoke.js`
- `task129-wolai-aline-baseline-smoke.js`
- `task130` 到 `task137` 一系列 `wolai-aline-*`
- `task160-wolai-page-settings-shell-smoke.js`
+- 已跟踪的对标基线：`task118-rust-web-wolai-ui-parity-smoke.js`、`task119-rust-web-wolai-visual-regression-smoke.js`
+- `task128`、`task129` 到 `task137`、`task160`、`task162` 是 gitignored 的本地历史取证脚本，不属于默认回归。
 - 页面 AI 旧 `/api/ai-agent/run` 视觉 smoke 已移入本机 gitignored `recycle/scripts/retired-ai-agent-run-smokes/`；当前页面 AI 验证优先使用 Pi Lab / opencode / Page AI smoke 与 `task-page-block-ai-tools-smoke.js`。Hermes 相关 smoke 只作为 legacy guard / 历史对照。

 这一层最重要的原则不是“文案命中”，而是：
@@ -191,9 +250,9 @@ node scripts/task097-homepage-entry-smoke.js
 - tree / sidebar 改动：`task112`、`task120`、`task122`
 - document shell / island：`task110`、`task121`
 - local-first：优先使用 `task164-desktop-hot-local-folder-main-entry-smoke.js`、`task166-local-first-managed-workspace-no-convex-smoke.js`、`task167-local-markdown-title-body-options-no-convex-smoke.js`、`task455-local-folder-mindmap-clean-smoke.js`
- 页面设置：`task160`、`task164-page-options-visible-effect-smoke.js`
+- 页面设置：`task164-page-options-visible-effect-smoke.js`
 - 双栏：`task165`
- AI：优先使用 Pi Lab / opencode / Page AI 当前主线 smoke、`task-page-block-ai-tools-smoke.js` 和 `task-hermes-page-ai-retirement-guard.js` 这类 legacy guard；Hermes 页面 AI smoke 只作为历史对照。Page AI history / skills / ChatOnly 相关改动补跑 `task503-mindmap-skill-capability-smoke.js`、`task504-page-ai-history-agent-filter-smoke.js`、`task512-chatonly-doubao-sync-smoke.js`、`task513-chatonly-provider-sync-smoke.js`；OnlyOffice live bridge 改动补跑 `task515-onlyoffice-live-scope-http-smoke.js`、`task516-onlyoffice-bridge-multisession-browser-smoke.js`、`task517-onlyoffice-bridge-plugin-direct-smoke.js`、`task518-onlyoffice-real-iframe-session-scope-smoke.js`，其中 `task516/517` 覆盖 bridge session lifecycle 与 `docKey/pageOrigin` 元数据；Page AI 真实 target picker / Office live session 改动补跑 `task523-page-ai-onlyoffice-real-target-session-smoke.js`；`task155`、`task156`、`task161` 等旧 `/api/ai-agent/run` smoke 只保留在本机 gitignored `recycle/scripts/retired-ai-agent-run-smokes/` 做历史对照
+- AI：优先使用 Pi Lab / Page AI 当前主线 smoke、`task-page-block-ai-tools-smoke.js` 和 `task-hermes-page-ai-retirement-guard.js` 这类 legacy guard；其余 Hermes 页面 AI 主流程 smoke 已退役。Page AI history / skills / ChatOnly 相关改动补跑 `task503-mindmap-skill-capability-smoke.js`、`task504-page-ai-history-agent-filter-smoke.js`、`task512-chatonly-doubao-sync-smoke.js`、`task513-chatonly-provider-sync-smoke.js`；OnlyOffice live bridge 改动补跑 `task515-onlyoffice-live-scope-http-smoke.js`、`task516-onlyoffice-bridge-multisession-browser-smoke.js`、`task517-onlyoffice-bridge-plugin-direct-smoke.js`、`task518-onlyoffice-real-iframe-session-scope-smoke.js`，其中 `task516/517` 覆盖 bridge session lifecycle 与 `docKey/pageOrigin` 元数据；Page AI 真实 target picker / Office live session 改动补跑 `task523-page-ai-onlyoffice-real-target-session-smoke.js`；`task155`、`task156`、`task161` 等旧 `/api/ai-agent/run` smoke 只保留在本机 gitignored `recycle/scripts/retired-ai-agent-run-smokes/` 做历史对照

 原则：