推进本地优先迁移与资源闭环

- 补齐共享只读页面 AI 浏览器 smoke，并回填当前优先级 checklist 的 P4/P5/P6 证据。

- 为 OnlyOffice 资源增加 /office/{documentId}/{assetId} 对象壳，固定 resource identity 与侧边栏打开路径。

- 扩展 Convex 导出脚本，支持 dry-run、manifest、冲突报告、索引刷新与 rollback，并补充 smoke。

- 补充资源 AI 工具合同与 Convex 导出 Web 入口设计。

scripts/export-convex-workspace-to-local.js

@@ -5,7 +5,14 @@ const fs = require("node:fs");
 const path = require("node:path");
 
 function parseArgs(argv) {
-  const args = { fixture: "", out: "" };
+  const args = {
+    fixture: "",
+    out: "",
+    dryRun: false,
+    manifest: "",
+    conflictReport: "",
+    rollback: "",
+  };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     if (arg === "--fixture") {
@@ -16,12 +23,34 @@ function parseArgs(argv) {
       args.out = argv[++index] || "";
       continue;
     }
+    if (arg === "--dry-run") {
+      args.dryRun = true;
+      continue;
+    }
+    if (arg === "--manifest") {
+      args.manifest = argv[++index] || "";
+      continue;
+    }
+    if (arg === "--conflict-report") {
+      args.conflictReport = argv[++index] || "";
+      continue;
+    }
+    if (arg === "--rollback") {
+      args.rollback = argv[++index] || "";
+      continue;
+    }
     if (arg === "--help" || arg === "-h") {
-      console.log("用法：node scripts/export-convex-workspace-to-local.js --fixture <fixture.json> --out <dir>");
+      console.log(
+        [
+          "用法：node scripts/export-convex-workspace-to-local.js --fixture <fixture.json> --out <dir> [--dry-run] [--manifest <file>] [--conflict-report <file>]",
+          "回滚：node scripts/export-convex-workspace-to-local.js --rollback <manifest.json>",
+        ].join("\n"),
+      );
       process.exit(0);
     }
     throw new Error(`未知参数：${arg}`);
   }
+  if (args.rollback) return args;
   if (!args.fixture) throw new Error("缺少 --fixture");
   if (!args.out) throw new Error("缺少 --out");
   return args;
@@ -36,6 +65,10 @@ function writeUtf8(filePath, content) {
   fs.writeFileSync(filePath, content, "utf8");
 }
 
+function writeJson(filePath, value) {
+  writeUtf8(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
 function sanitizeName(name) {
   return String(name || "untitled")
     .trim()
@@ -45,10 +78,6 @@ function sanitizeName(name) {
     .trim() || "untitled";
 }
 
-function toMarkdownFilename(title) {
-  return `${sanitizeName(title)}.md`;
-}
-
 function loadFixture(filePath) {
   return JSON.parse(fs.readFileSync(filePath, "utf8"));
 }
@@ -126,16 +155,36 @@ function serializePageOptions(doc) {
   };
 }
 
-function main() {
-  const { fixture: fixturePath, out } = parseArgs(process.argv.slice(2));
-  const fixture = loadFixture(fixturePath);
+function fileUriForPath(localPath) {
+  return `file://${path.resolve(localPath)}`;
+}
+
+function nowId() {
+  return new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
+}
+
+function normalizeRelativePath(relativePath) {
+  const normalized = String(relativePath || "").replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!normalized || normalized.split("/").some((part) => part === "..")) {
+    throw new Error(`非法迁移相对路径：${relativePath}`);
+  }
+  return normalized;
+}
+
+function pushFileOperation(operations, relativePath, content, contentEncoding = "utf8") {
+  operations.push({
+    action: "create",
+    relativePath: normalizeRelativePath(relativePath),
+    content,
+    contentEncoding,
+  });
+}
+
+function buildMigrationPlan(fixture, out) {
   const documents = Array.isArray(fixture.documents) ? fixture.documents : [];
   const mediaAssets = Array.isArray(fixture.mediaAssets) ? fixture.mediaAssets : [];
   const aiSessions = Array.isArray(fixture.aiSessions) ? fixture.aiSessions : [];
 
-  fs.rmSync(out, { recursive: true, force: true });
-  ensureDir(out);
-
   const docsById = buildDocumentIndex(documents);
   const markdownPathByDocId = new Map();
   const assetPathById = new Map();
@@ -162,6 +211,10 @@ function main() {
     };
   });
 
+  const operations = [];
+  const indexedDocuments = [];
+  const indexedResources = [];
+
   documents.forEach((doc) => {
     const markdownPath = markdownPathByDocId.get(String(doc.id));
     const assetRoot = markdownPath.replace(/\.md$/i, ".assets");
@@ -182,49 +235,217 @@ function main() {
       "---",
       "",
     ].join("\n");
-    writeUtf8(path.join(out, markdownPath), `${frontmatter}${markdownBody}`);
-    ensureDir(path.join(out, assetRoot));
+    pushFileOperation(operations, markdownPath, `${frontmatter}${markdownBody}`);
+    indexedDocuments.push({
+      documentId: `local-mdid:${doc.id}`,
+      title: String(doc.title || doc.id || "untitled"),
+      path: markdownPath,
+      rawText: markdownBody,
+      tags: [],
+      backlinks: [],
+      resourceRefs: [],
+      updatedAt: Date.now(),
+    });
+    operations.push({
+      action: "ensureDir",
+      relativePath: normalizeRelativePath(assetRoot),
+    });
   });
 
   mediaAssets.forEach((asset) => {
     const relativePath = assetPathById.get(String(asset.id));
     if (!relativePath) return;
-    const target = path.join(out, relativePath);
-    writeUtf8(target, decodeAssetContent(asset));
+    const content = decodeAssetContent(asset).toString("base64");
+    pushFileOperation(operations, relativePath, content, "base64");
+    indexedResources.push({
+      resourceId: String(asset.id),
+      resourceType: "media",
+      title: sanitizeName(asset.fileName || asset.name || asset.id),
+      path: relativePath,
+      updatedAt: Date.now(),
+    });
   });
 
   aiSessions.forEach((session) => {
     const sessionId = sanitizeName(session.sessionId || session.id || "session");
     const shareId = String(session.shareId || session.share_id || "").trim();
     const visibility = String(session.visibility || "").trim();
-    const dir = shareId || visibility === "shared"
-      ? path.join(out, "ai-sessions", "shared", sanitizeName(shareId || "share"))
-      : path.join(out, "ai-sessions", "private");
-    ensureDir(dir);
-    const filePath = path.join(dir, `${sessionId}.jsonl`);
+    const relativePath = shareId || visibility === "shared"
+      ? path.posix.join("ai-sessions", "shared", sanitizeName(shareId || "share"), `${sessionId}.jsonl`)
+      : path.posix.join("ai-sessions", "private", `${sessionId}.jsonl`);
     const events = Array.isArray(session.events) ? session.events : [];
     const lines = events.map((event) => JSON.stringify(event)).join("\n");
-    writeUtf8(filePath, lines ? `${lines}\n` : "");
+    pushFileOperation(operations, relativePath, lines ? `${lines}\n` : "");
   });
 
-  writeUtf8(path.join(out, ".mnote", "page-ids.json"), JSON.stringify({ version: 1, pages: pageIds }, null, 2));
-  writeUtf8(path.join(out, ".mnote", "page-options.json"), JSON.stringify({ version: 1, pages: pageOptions }, null, 2));
-  writeUtf8(path.join(out, ".mnote", "resource-index.json"), JSON.stringify(resourceIndex, null, 2));
-  writeUtf8(
-    path.join(out, ".mnote", "workspace.json"),
-    JSON.stringify(
+  const workspaceId = fixture.workspace?.id || "exported-workspace";
+  pushFileOperation(operations, ".mnote/page-ids.json", `${JSON.stringify({ version: 1, pages: pageIds }, null, 2)}\n`);
+  pushFileOperation(operations, ".mnote/page-options.json", `${JSON.stringify({ version: 1, pages: pageOptions }, null, 2)}\n`);
+  pushFileOperation(operations, ".mnote/resource-index.json", `${JSON.stringify(resourceIndex, null, 2)}\n`);
+  pushFileOperation(
+    operations,
+    ".mnote/workspace.json",
+    `${JSON.stringify(
       {
-        workspaceId: fixture.workspace?.id || "exported-workspace",
+        workspaceId,
         ownerId: fixture.workspace?.ownerId || fixture.workspace?.owner_id || "unknown",
         createdAt: new Date().toISOString(),
         capabilities: ["local_files", "ai_sessions", "exported_from_convex"],
       },
       null,
       2,
-    ),
+    )}\n`,
+  );
+  pushFileOperation(
+    operations,
+    ".mnote/index/search-index.json",
+    `${JSON.stringify(
+      {
+        version: 1,
+        builtAt: Date.now(),
+        rootUri: fileUriForPath(out),
+        workspaceId,
+        documents: indexedDocuments,
+        resources: indexedResources,
+      },
+      null,
+      2,
+    )}\n`,
   );
 
-  console.log(JSON.stringify({ ok: true, out }, null, 2));
+  return {
+    workspaceId,
+    operations,
+    documentCount: documents.length,
+    resourceCount: mediaAssets.length,
+    aiSessionCount: aiSessions.length,
+  };
+}
+
+function detectConflicts(out, operations) {
+  return operations
+    .filter((operation) => operation.action === "create")
+    .filter((operation) => fs.existsSync(path.join(out, operation.relativePath)))
+    .map((operation) => ({
+      code: "target_exists",
+      relativePath: operation.relativePath,
+      targetPath: path.join(out, operation.relativePath),
+      message: "目标文件已存在，迁移不会覆盖",
+    }));
+}
+
+function manifestForPlan(out, plan, dryRun, conflicts = []) {
+  const migrationId = `convex-export-${nowId()}`;
+  return {
+    version: 1,
+    migrationId,
+    source: "convex_fixture",
+    dryRun,
+    out: path.resolve(out),
+    createdAt: new Date().toISOString(),
+    backupDir: path.join(path.resolve(out), ".mnote", "migration-backups", migrationId),
+    workspaceId: plan.workspaceId,
+    documentCount: plan.documentCount,
+    resourceCount: plan.resourceCount,
+    aiSessionCount: plan.aiSessionCount,
+    operations: plan.operations.map((operation) => ({
+      action: operation.action,
+      relativePath: operation.relativePath,
+      contentEncoding: operation.contentEncoding || null,
+    })),
+    createdFiles: [],
+    backupFiles: [],
+    conflicts,
+    indexRefresh: {
+      status: dryRun ? "planned" : "pending",
+      path: ".mnote/index/search-index.json",
+    },
+  };
+}
+
+function writeConflictReport(filePath, out, conflicts) {
+  if (!filePath) return;
+  writeJson(filePath, {
+    version: 1,
+    code: conflicts.length ? "migration_conflict" : "ok",
+    out: path.resolve(out),
+    generatedAt: new Date().toISOString(),
+    conflicts,
+  });
+}
+
+function applyPlan(out, plan, manifest) {
+  ensureDir(out);
+  ensureDir(manifest.backupDir);
+  for (const operation of plan.operations) {
+    const target = path.join(out, operation.relativePath);
+    if (operation.action === "ensureDir") {
+      ensureDir(target);
+      continue;
+    }
+    if (operation.action !== "create") continue;
+    ensureDir(path.dirname(target));
+    const content = operation.contentEncoding === "base64"
+      ? Buffer.from(operation.content, "base64")
+      : operation.content;
+    fs.writeFileSync(target, content, operation.contentEncoding === "base64" ? undefined : "utf8");
+    manifest.createdFiles.push(operation.relativePath);
+  }
+  manifest.indexRefresh.status = "written";
+}
+
+function rollbackManifest(manifestPath) {
+  const manifest = loadFixture(manifestPath);
+  const out = manifest.out;
+  if (!out) throw new Error("rollback manifest 缺少 out");
+  const createdFiles = Array.isArray(manifest.createdFiles) ? manifest.createdFiles : [];
+  createdFiles
+    .slice()
+    .reverse()
+    .forEach((relativePath) => {
+      const target = path.join(out, normalizeRelativePath(relativePath));
+      if (fs.existsSync(target)) fs.rmSync(target, { force: true });
+    });
+  const backupFiles = Array.isArray(manifest.backupFiles) ? manifest.backupFiles : [];
+  backupFiles.forEach((backup) => {
+    if (!backup || !backup.relativePath || !backup.backupPath) return;
+    const target = path.join(out, normalizeRelativePath(backup.relativePath));
+    ensureDir(path.dirname(target));
+    fs.copyFileSync(backup.backupPath, target);
+  });
+  console.log(JSON.stringify({ ok: true, rollback: manifestPath, removed: createdFiles.length }, null, 2));
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.rollback) {
+    rollbackManifest(args.rollback);
+    return;
+  }
+  const fixture = loadFixture(args.fixture);
+  const plan = buildMigrationPlan(fixture, args.out);
+  const conflicts = detectConflicts(args.out, plan.operations);
+  const manifest = manifestForPlan(args.out, plan, args.dryRun, conflicts);
+  const manifestPath = args.manifest || path.join(args.out, ".mnote", "migration-manifest.json");
+  writeConflictReport(args.conflictReport, args.out, conflicts);
+  if (args.dryRun) {
+    manifest.indexRefresh.status = "planned";
+    writeJson(manifestPath, manifest);
+    console.log(JSON.stringify({ ok: true, dryRun: true, out: args.out, conflicts: conflicts.length }, null, 2));
+    return;
+  }
+  if (conflicts.length) {
+    writeJson(manifestPath, manifest);
+    console.error(JSON.stringify({ ok: false, code: "migration_conflict", conflicts }, null, 2));
+    process.exit(2);
+  }
+  applyPlan(args.out, plan, manifest);
+  writeJson(manifestPath, manifest);
+  if (path.resolve(manifestPath) !== path.resolve(path.join(args.out, ".mnote", "migration-manifest.json"))) {
+    writeJson(path.join(args.out, ".mnote", "migration-manifest.json"), manifest);
+  }
+
+  console.log(JSON.stringify({ ok: true, out: args.out, manifest: manifestPath }, null, 2));
 }
 
 if (require.main === module) {