mnote/docs/superpowers/plans/2026-05-09-local-folder-page-aggregate-next-phase.md

本地文件夹收尾与 Page Aggregate 主线回归实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 先把当前 local_folder / local_markdown 的未收口点收成稳定 checkpoint，再把文档页读取真相继续推进到 Rust 原生 Page Aggregate，最后补齐 3000 主界面的 tree live stream 浏览器级闭环。

Architecture: 保持 WorkspaceSource -> Rust kernel / mnote-web -> projection / command -> UI 的单一路径。第一段只处理当前未提交工作已经暴露出的本地/云空间切换、Markdown 附件与 marks 回归问题；第二段让 Next 侧 /api/documents/page 优先消费 Rust 已存在的 mnote.page_aggregate.v1 快照，而不是继续本地拼装 meta + content；第三段以 snapshot + delta + resync 的 Rust Web tree stream 作为 3000 当前 sidebar / filetree / page subtree 的正式实时主链。

Tech Stack: Rust (mnote-web, core-protocol), TypeScript/React (wolai-frontend), existing browser smoke scripts, Rust unit tests, Vitest, Playwright smoke.

---

Task 1: 收口本地/云工作区切换入口与最近目录体验

Files:

• Modify: rust/crates/mnote-web/src/ssr/pages/layout.rs

• Modify: rust/crates/mnote-web/src/ssr/styles.rs

• Modify: scripts/task164-desktop-hot-local-folder-main-entry-smoke.js

• Step 1: 先把 smoke 断言补成失败用例

const recentLocalRoots = await page.evaluate(() => {
  const raw = window.localStorage.getItem("mnote.localFolder.recentRoots") || "[]";
  return JSON.parse(raw);
});
assert.equal(recentLocalRoots[0], fileUrl(root), "打开本地文件夹后应记录最近 rootUri");

await page.locator('[data-testid="mnote-workspace-source-trigger"]').click({ timeout: UI_TIMEOUT_MS });
await page.locator('[data-testid="mnote-workspace-source-menu"]').waitFor({ state: "visible", timeout: UI_TIMEOUT_MS });
await page.locator('[data-testid="mnote-switch-cloud-workspace"]').click({ timeout: UI_TIMEOUT_MS });
await page.waitForURL((url) => {
  return url.pathname === "/" &&
    url.searchParams.get("sourceKind") !== "local_folder" &&
    !url.searchParams.has("rootUri");
}, { timeout: UI_TIMEOUT_MS });

• Step 2: 运行 smoke，确认当前基线失败或缺断言

Run: MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3000 node scripts/task164-desktop-hot-local-folder-main-entry-smoke.js

Expected: 失败，或日志中尚未覆盖“最近目录 / 切回云空间”链路。

• Step 3: 在 Rust SSR 壳里补最小实现

function rememberCloudWorkspaceId(workspaceId) {
  var normalized = String(workspaceId || '').trim();
  if (!normalized || normalized === 'local-folder') return;
  try {
    if (window.localStorage) window.localStorage.setItem(MNOTE_LAST_CLOUD_WORKSPACE_KEY, normalized);
  } catch (_) {}
}

function switchToCloudWorkspace() {
  var targetUrl = new URL('/', window.location.origin);
  var workspaceId = readLastCloudWorkspaceId();
  if (workspaceId) targetUrl.searchParams.set('workspaceId', workspaceId);
  targetUrl.searchParams.set('sourceKind', 'convex_workspace');
  window.location.href = targetUrl.toString();
}

.mnote-workspace-source-menu {
  position: absolute;
  inset-inline-start: 0;
  top: calc(100% + 6px);
}

• Step 4: 重新运行 smoke，确认体验闭环

Run: MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3000 node scripts/task164-desktop-hot-local-folder-main-entry-smoke.js

Expected: PASS，并打印 task164 desktop hot local folder main entry smoke passed。

Task 2: 收口 local markdown 附件 media 与 marks 可见化漂移

Files:

• Modify: rust/crates/mnote-web/src/routes/web_shell.rs

• Modify: wolai-frontend/src/lib/documents/tiptap-content-converter.ts

• Modify: wolai-frontend/src/lib/documents/tiptap-content-converter.test.ts

• Step 1: 先写失败测试，钉死 Rust/前端两边都要可见且保留链接

#[tokio::test]
async fn document_shell_renders_local_markdown_attachment_name_in_html() {
    assert!(html.contains("Spec"));
    assert!(html.contains("assets/spec.pdf"));
}

expect(
  tiptapDocFromBlocks([
    {
      id: "m1",
      type: "media",
      props: { name: "Spec", sourcePath: "assets/spec.pdf" },
      content: [],
    },
  ] as never),
).toEqual({
  type: "doc",
  content: [
    {
      type: "paragraph",
      attrs: { blockId: "m1" },
      content: [
        {
          type: "text",
          text: "Spec",
          marks: [{ type: "link", attrs: { href: "assets/spec.pdf" } }],
        },
      ],
    },
  ],
});

• Step 2: 运行最小测试，确认当前基线暴露漂移

Run: cd rust && cargo test -p mnote-web document_shell_renders_local_markdown_attachment_name_in_html -- --nocapture && cd /mnt/Data1T/mnote/wolai-frontend && pnpm vitest run src/lib/documents/tiptap-content-converter.test.ts

Expected: 前端测试失败，原因是 media 当前仍会丢掉 link mark；Rust 测试要么已过，要么暴露 HTML 可见化问题。

• Step 3: 做最小实现，统一 Rust adapter 与前端 converter 的 media 语义

case "media": {
  const sourcePath = toText(props.sourcePath ?? props.url ?? props.src).trim();
  const name = toText(props.name ?? props.fileName ?? props.title).trim() || sourcePath;
  return {
    blockId,
    blockType: "paragraph",
    props: {},
    contentNodes: name
      ? [{
          type: "text",
          text: name,
          marks: sourcePath ? [{ type: "link", attrs: { href: sourcePath } }] : [],
        }]
      : contentNodes,
    childBlockIds: [],
  };
}

• Step 4: 跑回归，确认 local markdown 不再出现 Rust/前端双轨

Run: cd rust && cargo test -p mnote-web local_markdown -- --nocapture && cd /mnt/Data1T/mnote/wolai-frontend && pnpm vitest run src/lib/documents/tiptap-content-converter.test.ts

Expected: PASS。

Task 3: 补齐 3-13 的浏览器回归矩阵，再同步设计稿状态

Files:

• Modify: scripts/task163-local-folder-unified-tree-browser-smoke.js

• Modify: rust/crates/mnote-web/src/routes/local_markdown_parser.rs

• Modify: rust/crates/mnote-web/src/routes/web_shell.rs

• Modify: design/03-rust-web/process/3-13-rust-web-local-markdown-gfm-ast-parser-migration-v1.md

• Step 1: 给本地 Markdown smoke 补齐缺的可见语义断言

await expect(page.locator(".ProseMirror input[type='checkbox']")).toHaveCount(2);
await expect(page.locator(".ProseMirror code")).toContainText(["inline code"]);
await expect(page.locator(".ProseMirror strong")).toContainText(["bold"]);
await expect(page.locator(".ProseMirror em")).toContainText(["italic"]);
await expect(page.locator(".ProseMirror s")).toContainText(["strike"]);
await expect(page.locator(".ProseMirror a")).toContainText(["Link", "Spec"]);
await expect(page.locator(".ProseMirror table td code")).toContainText(["cell"]);

• Step 2: 运行浏览器 smoke，确认 3-13 里剩余未勾项真实失败点

Run: MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3000 node scripts/task163-local-folder-unified-tree-browser-smoke.js

Expected: 至少暴露以下之一：checked/unchecked 断言不稳定、table cell marks 丢失、link/strike 渲染不完整。

• Step 3: 最小修复 parser / shell 映射

// 在 local_markdown_parser.rs 里固定空段落 / 空单元格 / 空引用块的降级节点；
// 在 web_shell.rs 里保证 legacy <-> Tiptap 映射不把 inline marks 吞成纯文本。

• Step 4: 复跑 smoke，并回写设计稿勾选状态

Run: MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3000 node scripts/task163-local-folder-unified-tree-browser-smoke.js && rg -n "\\- \\[ \\]" design/03-rust-web/process/3-13-rust-web-local-markdown-gfm-ast-parser-migration-v1.md

Expected: smoke PASS；3-13 只保留真正还没完成的收尾项，不再误把已验证项留成未完成。

Task 4: 让 Next /api/documents/page 优先消费 Rust Page Aggregate 快照

Files:

• Modify: wolai-frontend/src/lib/documents/page-aggregate-loader.ts

• Modify: wolai-frontend/src/app/api/documents/page/route.ts

• Modify: wolai-frontend/src/app/api/documents/page/route.test.ts

• Modify: wolai-frontend/src/lib/documents/page-aggregate-builder.ts

• Modify: rust/crates/mnote-web/src/routes/web_shell.rs (only if Rust snapshot contract 缺字段)

• Step 1: 先写失败测试，要求 happy path 直接吃 Rust 的 mnote.page_aggregate.v1

it("documents/page 路由优先返回 Rust page aggregate snapshot，而不是重新组装 meta + content", async () => {
  const response = await GET(
    new Request("http://localhost/api/documents/page?documentId=doc_1&workspaceId=ws_1"),
  );
  const payload = await response.json();
  expect(payload.page.schema).toBe("mnote.page_aggregate.v1");
  expect(payload.meta.queryName).toBe("documents.page.get");
});

• Step 2: 运行路由测试，确认当前实现仍停留在 Next 本地组装

Run: cd /mnt/Data1T/mnote/wolai-frontend && pnpm vitest run src/app/api/documents/page/route.test.ts

Expected: 失败，原因是 loader 仍依赖 api.documents.getMeta + documents.content.get + buildPageAggregateFromDocumentPayloads()。

• Step 3: 做最小 cutover，实现“Rust first，TS builder fallback only”

const rustPage = await loadPageAggregateFromRustSnapshot({
  request: input.request,
  documentId: input.documentId,
  workspaceId: input.workspaceId,
});
if (rustPage) {
  return {
    page: rustPage,
    bridge: { requestId, traceId, queryName: "documents.page.get" },
  };
}
return buildPageAggregateFromDocumentPayloads({ meta, contentPayload });

• Step 4: 跑 route + builder 回归，确认 Page Aggregate 读取真相继续向 Rust 收口

Run: cd /mnt/Data1T/mnote/wolai-frontend && pnpm vitest run src/app/api/documents/page/route.test.ts src/lib/documents/page-aggregate-builder.test.ts

Expected: PASS，并且 page-aggregate-builder.ts 退为 fallback / adapter 角色，而不是主 happy path。

Task 5: 补齐 3000 当前主界面的 tree live stream 浏览器级闭环

Files:

• Modify: rust/crates/mnote-web/src/ssr/pages/layout.rs

• Modify: rust/crates/mnote-web/src/routes/stream_support.rs

• Modify: scripts/task120-rust-web-tree-integration-smoke.js

• Modify: scripts/task123-rust-web-tree-live-stream-consumer-smoke.js

• Modify: scripts/task165-rust-web-dual-pane-smoke.js

• Step 1: 先把浏览器 smoke 补成“当前壳必须真的应用 delta / resync”

const applied = await page.locator("html").getAttribute("data-mnote-tree-live-applied");
assert(["delta", "resync"].includes(applied || ""), `tree live 应应用 delta/resync，实际: ${applied}`);

assert.equal(countRequests(requests, openIndex, isTreeEventRequest), 1, "双 pane fixture 页面不应建立第二条 tree EventSource");

• Step 2: 运行 tree live smoke，确认当前 3000 主壳的缺口

Run: MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3000 node scripts/task120-rust-web-tree-integration-smoke.js && MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3000 node scripts/task123-rust-web-tree-live-stream-consumer-smoke.js && MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3000 node scripts/task165-rust-web-dual-pane-smoke.js

Expected: 至少暴露以下之一：delta 只存在接口层、主壳未真正打到 DOM；resync fallback 未反映到属性或树快照；双 pane 重复建流。

• Step 3: 确认现有 layout.rs controller 与 delta/resync 选择逻辑已满足，本轮只补 smoke 断言

source.addEventListener('delta', function(event) {
  var payload = parseTreeEventPayload(event);
  dispatchTreeEvent('tree:delta', { payload: payload, revision: readPayloadRevision(payload), bootstrap: bootstrap });
});

source.addEventListener('resync', function(event) {
  var payload = parseTreeEventPayload(event);
  dispatchTreeEvent('tree:resync', { payload: payload, revision: readPayloadRevision(payload), bootstrap: bootstrap });
});

if let Some(delta) = change.delta {
    return Some((Ok(stream_event("delta", &payload)), Some(state)));
}
return Some((Ok(stream_event("resync", &with_stream_kind(&snapshot_payload, "resync"))), Some(state)));

• Step 4: 复跑 smoke，确认 3-3 可以继续向 done 靠拢

Run: MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3000 node scripts/task120-rust-web-tree-integration-smoke.js && MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3000 node scripts/task123-rust-web-tree-live-stream-consumer-smoke.js && MNOTE_WEB_SMOKE_BASE_URL=http://127.0.0.1:3000 node scripts/task165-rust-web-dual-pane-smoke.js

Expected: PASS。

Task 6: 做设计状态复核，清掉 done/ 与 [process] 漂移

Files:

• Modify: design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md

• Modify: design/03-rust-web/process/3-13-rust-web-local-markdown-gfm-ast-parser-migration-v1.md

• Modify: design/04-tree-domain/done/4-21-local-folder-convex-unified-tree-source-v1.md

• Modify: design/04-tree-domain/done/4-22-local-folder-convex-unified-tree-execution-checklist-v1.md

• Step 1: 先跑状态检查，找出 done/ 下仍写 [process] 的文档

Run: rg -n "^# .*\\[process\\]" design/03-rust-web/done design/04-tree-domain/done design/05-editor-mainline/done

Expected: 能直接列出当前状态漂移文件。

• Step 2: 按真实验证结果更新头部与完成描述

# 4-21 [done] Local Folder / Convex 统一树源架构 v1

补充：当前 `3000` 主入口、本地文件夹打开、统一 `file_tree / page_tree / page_aggregate` 消费链已完成；
仍在推进的工作移交给 `3-13`、`3-14`、`3-3`，不再继续混写在本稿里。

• Step 3: 复跑一致性检查

Run: rg -n "^# .*\\[(process|done)\\]" design/03-rust-web/done design/04-tree-domain/done design/05-editor-mainline/done

Expected: done/ 目录下不再残留明显错误的 [process] 头部。