@fieldwangai/agentflow 0.1.165 → 0.1.167

package/bin/lib/workspace-routes.mjs

@@ -11,8 +11,21 @@
  *    是请求回调的闭包，解构之后路由体里的写法完全不变。
  */
 
-import { listFlowsJson, listNodesJson, readNodeDetailJson, readNodeFilePreview } from "./catalog-flows.mjs";
+import { listNodesJson, readNodeDetailJson, readNodeFilePreview } from "./catalog-flows.mjs";
 import { startComposerAgent } from "./composer-agent.mjs";
+import {
+  aiMaterializationPrompt,
+  aiPlanPrompt,
+  appendAiTraceEvents,
+  createAiExplorationSession,
+  classifyAiToolSideEffect,
+  listAiExplorationSessions,
+  materializableAiTraceEvents,
+  parseAiPlanResult,
+  readAiExplorationSession,
+  updateAiExplorationSession,
+  writeAiExplorationMaterialization,
+} from "./ai-exploration.mjs";
 import { buildSkillCompactInjectionBlock, loadResourcesForSkillKeys } from "./composer-skill-router.mjs";
 import { execFileBuffered } from "./exec-buffered.mjs";
 import { runGit } from "./git-worktree.mjs";
@@ -30,22 +43,30 @@ import {
 } from "./marketplace.mjs";
 import {
   appendMarketplaceUsageEvent,
-  marketplaceStatsFor,
-  marketplaceUsageStats,
   marketplaceResourcesForRun,
-  readMarketplaceFlowOrigin,
   writeMarketplaceFlowOrigin,
 } from "./marketplace-usage.mjs";
+import {
+  indexedProjectFlowPreview,
+  getRepositoryIndex,
+  indexedMarketplaceFlowCopies,
+  listIndexedNodes,
+  listIndexedProjectFlows,
+  markRepositoryIndexDirty,
+  updateIndexedProjectFlowVisibility,
+  updateIndexedNodeVisibility,
+  writeProjectFlowMarketplaceMetadata,
+} from "./repository-index.mjs";
 import { NODE_PACKAGE_ENTRY, nodePackageExportsRun, readNodePackageManifest } from "./node-package-manifest.mjs";
 import { inspectNodePackageDirectory } from "./node-package-archive.mjs";
 import { json, readBody } from "./http-util.mjs";
 import { log } from "./log.mjs";
-import { PACKAGE_ROOT, PIPELINES_DIR, getAgentflowUserDataRoot, getUserPipelinesRoot, listAgentflowUserIds } from "./paths.mjs";
+import { PACKAGE_ROOT, PIPELINES_DIR, getAgentflowUserDataRoot, getUserPipelinesRoot } from "./paths.mjs";
 import { validateUserPipelineId } from "./flow-write.mjs";
 import { runLedgerId } from "./run-ledger.mjs";
 import { getTeamById, getTeamForUser } from "./teams.mjs";
 import { readMergedEnvObject, runtimeEnvForUser } from "./user-env.mjs";
-import { acceptWorkspaceCollaborationInvite, addWorkspaceCollaborationMember, deleteWorkspaceCollaborationForFlow, ensureWorkspaceCollaboration, getWorkspaceCollaborationByFlow, getWorkspaceCollaborationForProject, listWorkspaceCollaborationsForUser, removeWorkspaceCollaborationMember, removeWorkspaceCollaborationTeamShare, setWorkspaceCollaborationTeamShare, workspaceCollaborationAccess } from "./workspace-collaboration.mjs";
+import { acceptWorkspaceCollaborationInvite, addWorkspaceCollaborationMember, deleteWorkspaceCollaborationForFlow, ensureWorkspaceCollaboration, getWorkspaceCollaborationForProject, listWorkspaceCollaborationsForUser, removeWorkspaceCollaborationMember, removeWorkspaceCollaborationTeamShare, setWorkspaceCollaborationTeamShare, workspaceCollaborationAccess } from "./workspace-collaboration.mjs";
 import { WorkspaceFlowParseError } from "./workspace-flow-store.mjs";
 import { mergeWorkspaceGraphs, workspaceDesignRevision, workspaceRuntimeRevision } from "./workspace-graph-merge.mjs";
 import { DEFAULT_WORKSPACE_PREVIEW_TTL_MS, createWorkspacePreviewId, normalizeWorkspacePreviewTtlMs, readWorkspacePreviewMetadata, workspaceSharedPreviewFlowDir, writeWorkspacePreviewMetadata } from "./workspace-preview.mjs";
@@ -248,6 +269,170 @@ function missingWorkspaceGraphNodePackages(workspaceRoot, scoped, graph, userCtx
   return [...missing].sort();
 }
 
+const NODE_REVIEW_MAX_FILES = 100;
+const NODE_REVIEW_MAX_FILE_BYTES = 256 * 1024;
+const NODE_REVIEW_MAX_TOTAL_BYTES = 2 * 1024 * 1024;
+const NODE_REVIEW_TEXT_EXTENSIONS = new Set([
+  ".cjs", ".css", ".env", ".go", ".html", ".ini", ".java", ".js", ".json", ".jsx", ".kt",
+  ".md", ".mdx", ".mjs", ".py", ".rs", ".scss", ".sh", ".sql", ".toml", ".ts", ".tsx",
+  ".txt", ".xml", ".yaml", ".yml",
+]);
+
+function workspaceNodeReviewLanguage(filePath = "") {
+  const extension = path.extname(String(filePath || "")).toLowerCase().replace(/^\./, "");
+  const aliases = { cjs: "javascript", js: "javascript", jsx: "javascript", mjs: "javascript", py: "python", sh: "shell", ts: "typescript", tsx: "typescript", yml: "yaml" };
+  return aliases[extension] || extension || "text";
+}
+
+function workspaceNodeReviewSource({ sourcePath = "", title = "", kind = "file", content = "" } = {}) {
+  const text = String(content || "").replace(/\r\n/g, "\n");
+  const reviewPath = String(sourcePath || title || "source.txt").replace(/\\/g, "/");
+  return {
+    path: reviewPath,
+    title: String(title || path.basename(reviewPath) || reviewPath),
+    kind,
+    language: workspaceNodeReviewLanguage(reviewPath),
+    size: Buffer.byteLength(text),
+    sha256: crypto.createHash("sha256").update(text).digest("hex"),
+    content: text,
+  };
+}
+
+function workspaceNodeReviewFlowFile(flowRoot, fileRef, kind) {
+  const ref = String(fileRef || "").trim();
+  if (!ref) return null;
+  try {
+    const { abs, rel } = resolveWorkspaceFilePath(flowRoot, ref);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+      return { error: `找不到 ${ref}` };
+    }
+    const stat = fs.statSync(abs);
+    if (stat.size > NODE_REVIEW_MAX_FILE_BYTES) {
+      return { error: `${ref} 超过可预览大小限制` };
+    }
+    return workspaceNodeReviewSource({ sourcePath: rel, title: rel, kind, content: fs.readFileSync(abs, "utf-8") });
+  } catch (error) {
+    return { error: `${ref}: ${(error && error.message) || String(error)}` };
+  }
+}
+
+function workspaceNodeReviewPackageFiles(packageDir) {
+  const root = path.resolve(packageDir);
+  const candidates = [];
+  const walk = (dir) => {
+    if (candidates.length >= NODE_REVIEW_MAX_FILES) return;
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (candidates.length >= NODE_REVIEW_MAX_FILES) break;
+      if ([".git", "node_modules"].includes(entry.name)) continue;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(abs);
+      else if (entry.isFile() && NODE_REVIEW_TEXT_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) candidates.push(abs);
+    }
+  };
+  walk(root);
+  candidates.sort((left, right) => {
+    const leftRel = path.relative(root, left).replace(/\\/g, "/");
+    const rightRel = path.relative(root, right).replace(/\\/g, "/");
+    if (leftRel === NODE_PACKAGE_ENTRY) return -1;
+    if (rightRel === NODE_PACKAGE_ENTRY) return 1;
+    return leftRel.localeCompare(rightRel);
+  });
+  const sources = [];
+  let totalBytes = 0;
+  for (const abs of candidates) {
+    let stat;
+    try { stat = fs.statSync(abs); } catch { continue; }
+    if (!stat.isFile() || stat.size > NODE_REVIEW_MAX_FILE_BYTES || totalBytes + stat.size > NODE_REVIEW_MAX_TOTAL_BYTES) continue;
+    const rel = path.relative(root, abs).replace(/\\/g, "/");
+    sources.push(workspaceNodeReviewSource({ sourcePath: rel, title: rel, kind: "package", content: fs.readFileSync(abs, "utf-8") }));
+    totalBytes += stat.size;
+  }
+  return sources;
+}
+
+function workspaceNodeReviewSnapshot(workspaceRoot, flowRoot, graph, nodeId, userCtx = {}, label = "Draft") {
+  const instance = graph?.instances?.[nodeId];
+  if (!instance) return null;
+  const definitionId = String(instance.definitionId || nodeId);
+  const marketplaceRef = String(instance.marketplaceRef || definitionId).trim();
+  const sources = [];
+  const errors = [];
+  let packageInfo = null;
+
+  if (marketplaceRef.startsWith("marketplace:")) {
+    const resolved = resolveMarketplaceNodePackage(
+      workspaceRoot,
+      flowRoot,
+      marketplaceRef,
+      graph,
+      { ...userCtx, marketplaceScope: "all" },
+    );
+    if (!resolved) {
+      errors.push(`无法解析节点包 ${marketplaceRef}`);
+    } else {
+      const inspected = inspectNodePackageDirectory(resolved.packageDir, { allowLegacyManifest: true });
+      sources.push(...workspaceNodeReviewPackageFiles(resolved.packageDir));
+      packageInfo = {
+        id: resolved.id,
+        version: resolved.version,
+        definitionId: resolved.resolvedDefinitionId || marketplaceRef,
+        source: resolved.source || "marketplace",
+        contentSha256: inspected.ok ? inspected.contentSha256 : String(resolved.contentSha256 || ""),
+      };
+      if (!sources.length) errors.push(`节点包 ${marketplaceRef} 没有可预览的文本文件`);
+    }
+  } else if (String(instance.script || "").trim()) {
+    sources.push(workspaceNodeReviewSource({
+      sourcePath: `nodes/${nodeId}/inline-script.mjs`,
+      title: "内联脚本",
+      kind: "inline",
+      content: instance.script,
+    }));
+  }
+
+  for (const [ref, kind] of [[instance.scriptRef, "script"], [instance.implementationRef, "implementation"]]) {
+    const source = workspaceNodeReviewFlowFile(flowRoot, ref, kind);
+    if (source?.error) errors.push(source.error);
+    else if (source) sources.push(source);
+  }
+
+  const body = String(instance.body || "");
+  if (body.trim()) {
+    const looksJson = /^[\[{]/.test(body.trim());
+    sources.push(workspaceNodeReviewSource({
+      sourcePath: `nodes/${nodeId}/${looksJson ? "configuration.json" : "prompt.md"}`,
+      title: looksJson ? "节点配置" : "Prompt / 指令",
+      kind: looksJson ? "configuration" : "prompt",
+      content: body,
+    }));
+  }
+
+  const uniqueSources = [];
+  const seen = new Set();
+  for (const source of sources) {
+    const key = `${source.kind}\u0000${source.path}\u0000${source.sha256}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    uniqueSources.push(source);
+  }
+  return {
+    label,
+    nodeId,
+    definitionId,
+    model: String(instance.model || ""),
+    role: String(instance.role || "normal"),
+    implementationMode: String(instance.implementationMode || ""),
+    marketplaceRef: marketplaceRef.startsWith("marketplace:") ? marketplaceRef : "",
+    package: packageInfo,
+    sources: uniqueSources,
+    errors,
+    reviewable: uniqueSources.length > 0,
+  };
+}
+
 const NODE_STUDIO_DRAFTS_DIRNAME = "node-studio/drafts";
 
 function writeUserWorkspaces(userCtx = {}, entries = []) {
@@ -912,133 +1097,8 @@ function workspaceBufferLooksLikeZip(buf) {
   );
 }
 
-function installedMarketplaceFlowCopies(userId) {
-  const copies = new Map();
-  const pipelinesRoot = getUserPipelinesRoot(userId);
-  if (!fs.existsSync(pipelinesRoot)) return copies;
-  for (const entry of fs.readdirSync(pipelinesRoot, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const origin = readMarketplaceFlowOrigin(path.join(pipelinesRoot, entry.name));
-    if (!origin) continue;
-    const key = `${origin.id}@${origin.version}`;
-    const flowIds = copies.get(key) || [];
-    flowIds.push(entry.name);
-    copies.set(key, flowIds);
-  }
-  return copies;
-}
-
-const PROJECT_FLOW_MARKETPLACE_FILENAME = path.join(".workspace", "agentflow", "marketplace.json");
-
-function projectFlowMarketplaceId(ownerUserId, flowSource, flowId) {
-  return `project-flow:${String(ownerUserId || "").trim()}:${String(flowSource || "user").trim()}:${String(flowId || "").trim()}`;
-}
-
-function projectFlowMarketplaceMetadataPath(flowRoot) {
-  return path.join(path.resolve(flowRoot), PROJECT_FLOW_MARKETPLACE_FILENAME);
-}
-
-function readProjectFlowMarketplaceMetadata(flowRoot) {
-  try {
-    const parsed = JSON.parse(fs.readFileSync(projectFlowMarketplaceMetadataPath(flowRoot), "utf-8"));
-    return {
-      visibility: String(parsed?.visibility || "").trim() === "private" ? "private" : "public",
-      updatedAt: String(parsed?.updatedAt || "").trim(),
-    };
-  } catch {
-    return { visibility: "public", updatedAt: "" };
-  }
-}
-
-function writeProjectFlowMarketplaceMetadata(flowRoot, visibility) {
-  const filePath = projectFlowMarketplaceMetadataPath(flowRoot);
-  const value = {
-    version: 1,
-    visibility: String(visibility || "").trim() === "private" ? "private" : "public",
-    updatedAt: new Date().toISOString(),
-  };
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  const tempPath = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
-  fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
-  fs.renameSync(tempPath, filePath);
-  return value;
-}
-
-function graphHasRunnableEntry(graph) {
-  return Object.values(graph?.instances || {}).some((instance) => (
-    instance?.definitionId === "workspace_run"
-    || instance?.definitionId === "workspace_scheduled_run"
-  ));
-}
-
-function projectFlowUpdatedAt(flowRoot, metadata = {}) {
-  if (metadata.updatedAt) return metadata.updatedAt;
-  try {
-    return fs.statSync(path.resolve(flowRoot)).mtime.toISOString();
-  } catch {
-    return "";
-  }
-}
-
 function listRunnableProjectMarketplaceFlows(workspaceRoot, userCtx = {}, scope = "all") {
-  const requestedUserId = String(userCtx.userId || "").trim();
-  const stats = marketplaceUsageStats(workspaceRoot);
-  const resources = [];
-  const appendFlow = (ownerId, flow, flowSource = "user", workspaceId = "") => {
-    if (!ownerId || (scope === "owned" && ownerId !== requestedUserId)) return;
-    if (flow.archived || !flow.path) return;
-    let stable;
-    let graph;
-    try {
-      stable = readWorkspaceStableRelease(flow.path, workspaceRoot);
-      graph = stable?.graph || readWorkspaceGraph(flow.path, workspaceRoot).graph;
-    } catch {
-      return;
-    }
-    if (!graphHasRunnableEntry(graph)) return;
-    const metadata = readProjectFlowMarketplaceMetadata(flow.path);
-    const owned = ownerId === requestedUserId;
-    if (scope !== "owned" && metadata.visibility === "private" && !owned && userCtx.isAdmin !== true) return;
-    const id = projectFlowMarketplaceId(ownerId, flowSource, flow.id);
-    const version = stable?.release?.id || `current-${workspaceDesignRevision(graph).slice(0, 12)}`;
-    resources.push({
-      resourceType: "flow",
-      projectFlow: true,
-      id,
-      definitionId: flow.id,
-      displayName: flow.id,
-      description: flow.description || "",
-      version,
-      versionLabel: stable?.release?.id ? `Stable ${stable.release.id}` : "当前版本",
-      ownerUserId: ownerId,
-      liveOwnerUserId: ownerId,
-      liveFlowId: flow.id,
-      liveFlowSource: flowSource,
-      liveWorkspaceId: workspaceId,
-      visibility: metadata.visibility,
-      nodeCount: Object.keys(graph?.instances || {}).length,
-      edgeCount: Array.isArray(graph?.edges) ? graph.edges.length : 0,
-      updatedAt: projectFlowUpdatedAt(flow.path, metadata),
-      ...marketplaceStatsFor(stats, "project-flow", id, version, ownerId),
-      _graph: graph,
-      _flowRoot: flow.path,
-    });
-  };
-  for (const ownerUserId of listAgentflowUserIds()) {
-    const ownerId = String(ownerUserId || "").trim();
-    for (const flow of listFlowsJson(workspaceRoot, { userId: ownerId })) {
-      if ((flow.source || "user") !== "user" || flow.archived || !flow.path) continue;
-      appendFlow(ownerId, flow, "user");
-    }
-  }
-  for (const flow of listFlowsJson(workspaceRoot, { userId: "", includeWorkspaceFlows: true })) {
-    if ((flow.source || "") !== "workspace" || flow.archived || !flow.path) continue;
-    const collaboration = getWorkspaceCollaborationByFlow(flow.id, false);
-    const ownerId = String(collaboration?.ownerId || "").trim();
-    if (!ownerId) continue;
-    appendFlow(ownerId, flow, "workspace", collaboration.id);
-  }
-  return resources;
+  return listIndexedProjectFlows(workspaceRoot, userCtx, scope);
 }
 
 function publicProjectFlowMarketplaceResource(resource) {
@@ -1062,13 +1122,26 @@ function marketplaceResourceMatches(item, queryText) {
 function sortMarketplaceResources(items) {
   return items.sort((a, b) => (
     Number(b.useCount || 0) - Number(a.useCount || 0)
-    || Number(b.installCount || 0) - Number(a.installCount || 0)
     || String(b.updatedAt || b.createdAt || "").localeCompare(String(a.updatedAt || a.createdAt || ""))
     || String(a.displayName || a.id).localeCompare(String(b.displayName || b.id))
     || String(b.version || "").localeCompare(String(a.version || ""), undefined, { numeric: true, sensitivity: "base" })
   ));
 }
 
+function paginateMarketplaceResources(items, url, defaultLimit = 24) {
+  const requestedLimit = Number(url.searchParams.get("limit") || defaultLimit);
+  const limit = Math.min(100, Math.max(1, Number.isFinite(requestedLimit) ? Math.floor(requestedLimit) : defaultLimit));
+  const requestedCursor = Number(url.searchParams.get("cursor") || 0);
+  const offset = Math.max(0, Number.isFinite(requestedCursor) ? Math.floor(requestedCursor) : 0);
+  const pageItems = items.slice(offset, offset + limit);
+  const nextOffset = offset + pageItems.length;
+  return {
+    items: pageItems,
+    total: items.length,
+    nextCursor: nextOffset < items.length ? String(nextOffset) : "",
+  };
+}
+
 /**
  * @param {import('http').IncomingMessage} req
  * @param {import('http').ServerResponse} res
@@ -1131,6 +1204,7 @@ async function workspaceRoutes(req, res, ctx) {
       }
       try {
         const result = publishNodePackageArchive(root, parsed.file, { ownerUserId: userCtx.userId });
+        if (result.ok) markRepositoryIndexDirty(root);
         json(res, result.ok ? (result.alreadyExists ? 200 : 201) : (result.conflict ? 409 : 400), result);
       } catch (e) {
         json(res, 500, { ok: false, error: (e && e.message) || String(e) });
@@ -1163,6 +1237,7 @@ async function workspaceRoutes(req, res, ctx) {
           actorUserId: userCtx.userId || "",
           eventId: `install:node:${id}@${version}:${userCtx.userId || "anonymous"}`,
         });
+        markRepositoryIndexDirty(root);
         res.writeHead(200, {
           "Content-Type": "application/zip",
           "Content-Length": result.archive.length,
@@ -1186,7 +1261,7 @@ async function workspaceRoutes(req, res, ctx) {
         const marketplaceScope = scope === "owned" ? "owned" : "all";
         const queryText = String(url.searchParams.get("q") || "").trim().toLowerCase();
         if (kind === "node") {
-          const marketplaceNodes = listMarketplacePackages(root, { ...userCtx, marketplaceScope }).nodes
+          const marketplaceNodes = listIndexedNodes(root, userCtx, marketplaceScope)
             .map((node) => ({ ...node, resourceType: "node", installed: true }));
           let nodes = marketplaceNodes;
           if (scope === "installed") {
@@ -1217,23 +1292,23 @@ async function workspaceRoutes(req, res, ctx) {
             });
           }
           nodes = sortMarketplaceResources(nodes.filter((item) => marketplaceResourceMatches(item, queryText)));
-          json(res, 200, { kind, scope, sort: "useCount", order: "desc", items: nodes });
+          const page = paginateMarketplaceResources(nodes, url);
+          const index = getRepositoryIndex(root);
+          json(res, 200, {
+            kind,
+            scope,
+            sort: "useCount",
+            order: "desc",
+            ...page,
+            index: { status: "ready", generatedAt: index.generatedAt },
+          });
           return;
         }
         if (kind !== "flow") {
           json(res, 400, { error: "kind must be flow or node" });
           return;
         }
-        const installedCopies = installedMarketplaceFlowCopies(userCtx.userId);
-        const flows = listMarketplaceFlows(root, { ...userCtx, marketplaceScope }).flows.map((flow) => {
-          const installedFlowIds = installedCopies.get(`${flow.id}@${flow.version}`) || [];
-          return {
-            ...flow,
-            resourceType: "flow",
-            installed: installedFlowIds.length > 0,
-            installedFlowIds,
-          };
-        });
+        const installedCopies = indexedMarketplaceFlowCopies(root, userCtx.userId);
         const projectFlows = listRunnableProjectMarketplaceFlows(root, userCtx, scope).map((flow) => {
           const installedFlowIds = installedCopies.get(`${flow.id}@${flow.version}`) || [];
           return publicProjectFlowMarketplaceResource({
@@ -1242,14 +1317,21 @@ async function workspaceRoutes(req, res, ctx) {
             installedFlowIds,
           });
         });
-        const snippets = scope === "installed" ? [] : listMarketplaceFlowSnippets(root, { ...userCtx, marketplaceScope }).snippets
-          .map((snippet) => ({ ...snippet, resourceType: "flow-snippet", installed: false }));
         const items = sortMarketplaceResources(
-          [...projectFlows, ...flows, ...snippets]
+          projectFlows
             .filter((item) => scope !== "installed" || item.installed)
             .filter((item) => marketplaceResourceMatches(item, queryText)),
         );
-        json(res, 200, { kind, scope, sort: "useCount", order: "desc", items });
+        const page = paginateMarketplaceResources(items, url);
+        const index = getRepositoryIndex(root);
+        json(res, 200, {
+          kind,
+          scope,
+          sort: "useCount",
+          order: "desc",
+          ...page,
+          index: { status: "ready", generatedAt: index.generatedAt },
+        });
       } catch (e) {
         json(res, 500, { error: (e && e.message) || String(e) });
       }
@@ -1293,6 +1375,220 @@ async function workspaceRoutes(req, res, ctx) {
       return;
     }
 
+    if (req.method === "GET" && url.pathname === "/api/marketplace/flows/preview") {
+      const id = String(url.searchParams.get("id") || "").trim();
+      const version = String(url.searchParams.get("version") || "").trim();
+      const projectFlow = url.searchParams.get("projectFlow") === "1";
+      if (!id || !version) {
+        json(res, 400, { error: "Missing marketplace flow id or version" });
+        return;
+      }
+      try {
+        const installedCopies = indexedMarketplaceFlowCopies(root, userCtx.userId);
+        if (projectFlow) {
+          const source = listRunnableProjectMarketplaceFlows(root, userCtx, "all")
+            .find((flow) => flow.id === id);
+          if (!source) {
+            json(res, 404, { error: "Project flow not found or is private" });
+            return;
+          }
+          if (source.version !== version) {
+            json(res, 409, { error: "该流程已有新版本，请刷新流程仓库后重试" });
+            return;
+          }
+          const preview = indexedProjectFlowPreview(root, source);
+          if (!preview || preview.stale) {
+            markRepositoryIndexDirty(root);
+            json(res, preview?.stale ? 409 : 404, { error: preview?.stale ? "该流程已有新版本，请刷新流程仓库后重试" : "Project flow preview is unavailable" });
+            return;
+          }
+          json(res, 200, {
+            flow: {
+              ...publicProjectFlowMarketplaceResource(source),
+              owned: source.ownerUserId === userCtx.userId,
+              installedFlowIds: installedCopies.get(`${id}@${version}`) || [],
+            },
+            graph: preview.graph,
+          });
+          return;
+        }
+        const source = readMarketplaceFlow(root, id, version, { ...userCtx, marketplaceScope: "all" });
+        if (!source.ok) {
+          json(res, 404, { error: source.error || "Marketplace flow not found" });
+          return;
+        }
+        const metadata = listMarketplaceFlows(root, { ...userCtx, marketplaceScope: "all" }).flows
+          .find((flow) => flow.id === id && flow.version === version) || {};
+        json(res, 200, {
+          flow: {
+            ...metadata,
+            id,
+            version,
+            resourceType: "flow",
+            owned: metadata.ownerUserId === userCtx.userId,
+            installedFlowIds: installedCopies.get(`${id}@${version}`) || [],
+          },
+          graph: source.graph,
+        });
+      } catch (e) {
+        json(res, 500, { error: (e && e.message) || String(e) });
+      }
+      return;
+    }
+
+    if (req.method === "POST" && url.pathname === "/api/marketplace/flows/workspace-preview") {
+      let payload;
+      try {
+        payload = JSON.parse(await readBody(req));
+      } catch {
+        json(res, 400, { error: "Invalid JSON body" });
+        return;
+      }
+      const id = String(payload?.id || "").trim();
+      const version = String(payload?.version || "").trim();
+      const previewKind = ["snippet", "node"].includes(payload?.kind) ? payload.kind : "flow";
+      const projectFlow = payload?.projectFlow === true;
+      if (!id || !version) {
+        json(res, 400, { error: "Missing marketplace flow id or version" });
+        return;
+      }
+      try {
+        const installedCopies = indexedMarketplaceFlowCopies(root, userCtx.userId);
+        let graph;
+        let resource;
+        if (previewKind === "node") {
+          const node = listIndexedNodes(root, userCtx, "all")
+            .find((item) => item.id === id && item.version === version);
+          if (!node) {
+            json(res, 404, { error: "Node package not found or is private" });
+            return;
+          }
+          graph = {
+            version: 1,
+            instances: {
+              node_preview: {
+                definitionId: node.definitionId,
+                marketplaceRef: node.definitionId,
+                marketplacePackageId: node.id,
+                marketplaceVersion: node.version,
+                label: node.displayName || node.id,
+                role: "normal",
+                body: "",
+                input: Array.isArray(node.inputs) ? node.inputs : [],
+                output: Array.isArray(node.outputs) ? node.outputs : [],
+              },
+            },
+            edges: [],
+            ui: { nodePositions: { node_preview: { x: 320, y: 220 } } },
+          };
+          resource = { ...node, resourceType: "node", owned: node.ownerUserId === userCtx.userId };
+        } else if (previewKind === "snippet") {
+          const snippet = listMarketplaceFlowSnippets(root, { ...userCtx, marketplaceScope: "all" }).snippets
+            .find((item) => item.id === id && item.version === version);
+          if (!snippet) {
+            json(res, 404, { error: "Flow snippet not found or is private" });
+            return;
+          }
+          graph = snippet.snippet;
+          resource = { ...snippet, resourceType: "flow-snippet" };
+        } else if (projectFlow) {
+          const source = listRunnableProjectMarketplaceFlows(root, userCtx, "all")
+            .find((flow) => flow.id === id);
+          if (!source) {
+            json(res, 404, { error: "Project flow not found or is private" });
+            return;
+          }
+          if (source.version !== version) {
+            json(res, 409, { error: "该流程已有新版本，请刷新流程仓库后重试" });
+            return;
+          }
+          const preview = indexedProjectFlowPreview(root, source);
+          if (!preview || preview.stale) {
+            markRepositoryIndexDirty(root);
+            json(res, preview?.stale ? 409 : 404, { error: preview?.stale ? "该流程已有新版本，请刷新流程仓库后重试" : "Project flow preview is unavailable" });
+            return;
+          }
+          graph = preview.graph;
+          resource = {
+            ...publicProjectFlowMarketplaceResource(source),
+            owned: source.ownerUserId === userCtx.userId,
+            installedFlowIds: installedCopies.get(`${id}@${version}`) || [],
+          };
+        } else {
+          const source = readMarketplaceFlow(root, id, version, { ...userCtx, marketplaceScope: "all" });
+          if (!source.ok) {
+            json(res, 404, { error: source.error || "Marketplace flow not found" });
+            return;
+          }
+          const metadata = listMarketplaceFlows(root, { ...userCtx, marketplaceScope: "all" }).flows
+            .find((flow) => flow.id === id && flow.version === version) || {};
+          graph = source.graph;
+          resource = {
+            ...metadata,
+            id,
+            version,
+            resourceType: "flow",
+            owned: metadata.ownerUserId === userCtx.userId,
+            installedFlowIds: installedCopies.get(`${id}@${version}`) || [],
+          };
+        }
+        const flowId = createWorkspacePreviewId();
+        const flowDir = workspaceSharedPreviewFlowDir(root, flowId);
+        const now = Date.now();
+        const metadata = {
+          version: 1,
+          flowId,
+          ownerId: authUser.userId,
+          title: String(resource.displayName || resource.definitionId || id).trim().slice(0, 200),
+          createdAt: new Date(now).toISOString(),
+          updatedAt: new Date(now).toISOString(),
+          expiresAt: new Date(now + DEFAULT_WORKSPACE_PREVIEW_TTL_MS).toISOString(),
+          marketplace: { id, version, projectFlow },
+        };
+        fs.mkdirSync(flowDir, { recursive: true });
+        writeWorkspaceGraph(flowDir, graph, root);
+        writeWorkspacePreviewMetadata(flowDir, metadata);
+        const installedFlowId = resource.installedFlowIds?.[0] || "";
+        const action = previewKind === "node"
+          ? "add-node"
+          : previewKind === "snippet" ? "add-snippet"
+          : resource.projectFlow && resource.owned
+            ? "open-source"
+            : installedFlowId ? "open-installed" : "install";
+        const previewParams = new URLSearchParams({
+          flowId,
+          flowSource: "workspace",
+          archived: "1",
+          marketplacePreview: "1",
+          marketplaceKind: previewKind,
+          marketplaceResourceId: id,
+          marketplaceVersion: version,
+          marketplaceProjectFlow: projectFlow ? "1" : "0",
+          marketplaceTitle: resource.displayName || resource.definitionId || id,
+          marketplaceAction: action,
+          marketplaceInstallFlowId: resource.installFlowId || resource.liveFlowId || resource.definitionId || id,
+        });
+        if (previewKind === "node") previewParams.set("focusNodeId", "node_preview");
+        if (action === "open-source") {
+          previewParams.set("marketplaceTargetFlowId", resource.liveFlowId || resource.definitionId || "");
+          previewParams.set("marketplaceTargetFlowSource", resource.liveFlowSource || "user");
+          if (resource.liveWorkspaceId) previewParams.set("marketplaceTargetWorkspaceId", resource.liveWorkspaceId);
+        } else if (action === "open-installed") {
+          previewParams.set("marketplaceTargetFlowId", installedFlowId);
+          previewParams.set("marketplaceTargetFlowSource", "user");
+        }
+        json(res, 200, {
+          ok: true,
+          preview: true,
+          expiresAt: metadata.expiresAt,
+          url: `/workspace?${previewParams}`,
+        });
+      } catch (e) {
+        json(res, 500, { error: (e && e.message) || String(e) });
+      }
+      return;
+    }
+
     if (req.method === "POST" && url.pathname === "/api/marketplace/flows/publish") {
       let payload;
       try {
@@ -1329,6 +1625,7 @@ async function workspaceRoutes(req, res, ctx) {
           visibility: payload?.visibility || "public",
           graph,
         }, userCtx);
+        if (result.ok) markRepositoryIndexDirty(root);
         json(res, result.ok ? (result.alreadyExists ? 200 : 201) : (result.conflict ? 409 : 400), result);
       } catch (e) {
         json(res, 500, { error: (e && e.message) || String(e) });
@@ -1372,7 +1669,13 @@ async function workspaceRoutes(req, res, ctx) {
             json(res, 409, { error: "该流程已有新版本，请刷新流程仓库后重试" });
             return;
           }
-          sourceGraph = source._graph;
+          const preview = indexedProjectFlowPreview(root, source);
+          if (!preview || preview.stale) {
+            markRepositoryIndexDirty(root);
+            json(res, preview?.stale ? 409 : 404, { error: preview?.stale ? "该流程已有新版本，请刷新流程仓库后重试" : "Project flow preview is unavailable" });
+            return;
+          }
+          sourceGraph = preview.graph;
           originKind = "project-flow";
         } else {
           const source = readMarketplaceFlow(root, id, version, { ...userCtx, marketplaceScope: "all" });
@@ -1394,6 +1697,7 @@ async function workspaceRoutes(req, res, ctx) {
           actorUserId: userCtx.userId || "",
           eventId: `install:${originKind}:${id}@${version}:${userCtx.userId || "anonymous"}`,
         });
+        markRepositoryIndexDirty(root);
         json(res, 201, {
           ok: true,
           id,
@@ -1429,17 +1733,27 @@ async function workspaceRoutes(req, res, ctx) {
             return;
           }
           const metadata = writeProjectFlowMarketplaceMetadata(source._flowRoot, payload?.visibility);
+          updateIndexedProjectFlowVisibility(root, id, metadata.visibility, metadata.updatedAt);
           json(res, 200, { ok: true, kind: "project-flow", id, version: source.version, ...metadata });
           return;
         }
+        const resourceKind = String(payload?.kind || "");
+        const resourceId = String(payload?.id || "");
+        const resourceVersion = String(payload?.version || "");
+        const resourceVisibility = String(payload?.visibility || "public");
         const result = setMarketplaceVisibility(
           root,
-          String(payload?.kind || ""),
-          String(payload?.id || ""),
-          String(payload?.version || ""),
-          String(payload?.visibility || "public"),
+          resourceKind,
+          resourceId,
+          resourceVersion,
+          resourceVisibility,
           userCtx,
         );
+        if (result.ok && resourceKind === "node") {
+          updateIndexedNodeVisibility(root, resourceId, resourceVersion, resourceVisibility);
+        } else if (result.ok) {
+          markRepositoryIndexDirty(root);
+        }
         json(res, result.ok ? 200 : 400, result);
       } catch (e) {
         json(res, 500, { error: (e && e.message) || String(e) });
@@ -1729,6 +2043,49 @@ async function workspaceRoutes(req, res, ctx) {
       return;
     }
 
+    if (req.method === "GET" && url.pathname === "/api/workspace/node-review") {
+      try {
+        const nodeId = String(url.searchParams.get("nodeId") || "").trim();
+        if (!nodeId) {
+          json(res, 400, { error: "Missing nodeId" });
+          return;
+        }
+        const scoped = resolveWorkspaceScopeRoot(root, {
+          flowId: url.searchParams.get("flowId") || "",
+          flowSource: url.searchParams.get("flowSource") || "user",
+          workspaceId: url.searchParams.get("workspaceId") || "",
+          adminOwnerId: url.searchParams.get("adminOwnerId") || "",
+          archived: url.searchParams.get("archived") === "1",
+        }, userCtx);
+        if (scoped.error) {
+          json(res, scoped.status || 400, { error: scoped.error });
+          return;
+        }
+        const scopedUserCtx = workspaceScopedUserContext(scoped, userCtx);
+        const draftGraph = readWorkspaceGraph(scoped.root, root).graph;
+        const stableRelease = readWorkspaceStableRelease(scoped.root, root);
+        const draft = workspaceNodeReviewSnapshot(root, scoped.root, draftGraph, nodeId, scopedUserCtx, "Draft");
+        const stable = stableRelease
+          ? workspaceNodeReviewSnapshot(root, stableRelease.root, stableRelease.graph, nodeId, scopedUserCtx, `Stable ${stableRelease.release.id}`)
+          : null;
+        if (!draft && !stable) {
+          json(res, 404, { error: "Node not found" });
+          return;
+        }
+        json(res, 200, {
+          nodeId,
+          draft,
+          stable,
+          stableReleaseId: stableRelease?.release?.id || "",
+          stableRevision: stableRelease?.release?.designRevision || "",
+          draftRevision: workspaceDesignRevision(draftGraph),
+        });
+      } catch (e) {
+        json(res, 500, { error: (e && e.message) || String(e) });
+      }
+      return;
+    }
+
     if (req.method === "GET" && url.pathname === "/api/workspaces") {
       try {
         const scoped = resolveWorkspaceScopeRoot(root, {
@@ -1931,6 +2288,7 @@ async function workspaceRoutes(req, res, ctx) {
         const graph = workspaceGraphWithScheduleMode(draftGraph, payload.scheduleMode || "disabled");
         fs.mkdirSync(targetDir, { recursive: true });
         writeWorkspaceGraph(targetDir, graph, root);
+        markRepositoryIndexDirty(root);
         let collaborationCreated = false;
         if (flowSource === "workspace") {
           ensureWorkspaceCollaboration({ flowId, userId: authUser.userId });
@@ -2214,6 +2572,7 @@ async function workspaceRoutes(req, res, ctx) {
           json(res, result.conflict ? 409 : 400, result);
           return;
         }
+        markRepositoryIndexDirty(root);
         const graph = readWorkspaceGraph(scoped.root, root).graph;
         const workspaceSchedules = syncWorkspaceSchedulesForGraph(root, scoped, graph, authUser, userCtx);
         broadcastWorkspaceCollaborationEvent(userCtx, scoped.flowSource, scoped.flowId, scoped.archived, {
@@ -2262,6 +2621,7 @@ async function workspaceRoutes(req, res, ctx) {
           json(res, 404, result);
           return;
         }
+        markRepositoryIndexDirty(root);
         const graph = readWorkspaceGraph(scoped.root, root).graph;
         const workspaceSchedules = syncWorkspaceSchedulesForGraph(root, scoped, graph, authUser, userCtx);
         broadcastWorkspaceCollaborationEvent(userCtx, scoped.flowSource, scoped.flowId, scoped.archived, {
@@ -2389,6 +2749,7 @@ async function workspaceRoutes(req, res, ctx) {
           }
           throw new Error(`Workspace graph save rolled back: ${(scheduleError && scheduleError.message) || String(scheduleError)}`);
         }
+        markRepositoryIndexDirty(root);
         broadcastWorkspaceCollaborationEvent(
           userCtx,
           scoped.flowSource,
@@ -2500,6 +2861,7 @@ async function workspaceRoutes(req, res, ctx) {
         graph.instances[scheduleNodeId] = { ...instance, body: JSON.stringify(config) };
         const committed = commitWorkspaceGraph(root, scoped, graph, userCtx);
         const workspaceSchedules = syncWorkspaceSchedulesForGraph(root, scoped, committed.graph, authUser, userCtx);
+        markRepositoryIndexDirty(root);
         const schedule = workspaceSchedules.find((item) => item.scheduleNodeId === scheduleNodeId) || {
           flowId,
           flowSource,
@@ -3572,6 +3934,436 @@ async function workspaceRoutes(req, res, ctx) {
       return;
     }
 
+    if (req.method === "GET" && url.pathname === "/api/workspace/explorations") {
+      try {
+        const scoped = resolveWorkspaceScopeRoot(root, {
+          flowId: url.searchParams.get("flowId") || "",
+          flowSource: url.searchParams.get("flowSource") || "user",
+          adminOwnerId: url.searchParams.get("adminOwnerId") || "",
+          archived: url.searchParams.get("archived") === "1" || url.searchParams.get("flowArchived") === "1",
+        }, userCtx);
+        if (scoped.error) {
+          json(res, 400, { error: scoped.error });
+          return;
+        }
+        json(res, 200, { ok: true, explorations: listAiExplorationSessions(scoped.root) });
+      } catch (e) {
+        json(res, 500, { error: (e && e.message) || String(e) });
+      }
+      return;
+    }
+
+    if (req.method === "GET" && url.pathname === "/api/workspace/exploration") {
+      try {
+        const scoped = resolveWorkspaceScopeRoot(root, {
+          flowId: url.searchParams.get("flowId") || "",
+          flowSource: url.searchParams.get("flowSource") || "user",
+          adminOwnerId: url.searchParams.get("adminOwnerId") || "",
+          archived: url.searchParams.get("archived") === "1" || url.searchParams.get("flowArchived") === "1",
+        }, userCtx);
+        if (scoped.error) {
+          json(res, 400, { error: scoped.error });
+          return;
+        }
+        json(res, 200, { ok: true, exploration: readAiExplorationSession(scoped.root, url.searchParams.get("id") || "") });
+      } catch (e) {
+        json(res, /Invalid exploration|ENOENT/.test(String(e?.message || e)) ? 404 : 500, { error: (e && e.message) || String(e) });
+      }
+      return;
+    }
+
+    if (req.method === "POST" && url.pathname === "/api/workspace/exploration") {
+      let payload;
+      try { payload = JSON.parse(await readBody(req)); } catch {
+        json(res, 400, { error: "Invalid JSON body" });
+        return;
+      }
+      try {
+        const scoped = resolveWorkspaceScopeRoot(root, {
+          flowId: payload.flowId || "",
+          flowSource: payload.flowSource || "user",
+          adminOwnerId: payload.adminOwnerId || "",
+          archived: payload.archived === true || payload.flowArchived === true,
+        }, userCtx);
+        if (scoped.error) {
+          json(res, 400, { error: scoped.error });
+          return;
+        }
+        if (scoped.archived || isReadonlyBuiltinFlowSource(scoped.flowSource) || scoped.collaborationAccess?.writable === false) {
+          json(res, 403, { error: "Exploration write permission denied" });
+          return;
+        }
+        const exploration = createAiExplorationSession(scoped.root, {
+          title: payload.title,
+          goal: payload.goal,
+          mode: payload.mode || "observed",
+          status: payload.status || "running",
+          source: payload.source || { provider: "external", agent: "custom" },
+        });
+        json(res, 201, {
+          ok: true,
+          exploration,
+          ingest: {
+            method: "POST",
+            path: "/api/workspace/exploration/events",
+            body: {
+              flowId: payload.flowId || "",
+              flowSource: payload.flowSource || "user",
+              id: exploration.id,
+              events: [],
+            },
+          },
+        });
+      } catch (e) {
+        json(res, 500, { error: (e && e.message) || String(e) });
+      }
+      return;
+    }
+
+    if (req.method === "POST" && url.pathname === "/api/workspace/exploration/events") {
+      let payload;
+      try { payload = JSON.parse(await readBody(req)); } catch {
+        json(res, 400, { error: "Invalid JSON body" });
+        return;
+      }
+      try {
+        const scoped = resolveWorkspaceScopeRoot(root, {
+          flowId: payload.flowId || "",
+          flowSource: payload.flowSource || "user",
+          adminOwnerId: payload.adminOwnerId || "",
+          archived: payload.archived === true || payload.flowArchived === true,
+        }, userCtx);
+        if (scoped.error) {
+          json(res, 400, { error: scoped.error });
+          return;
+        }
+        if (scoped.archived || isReadonlyBuiltinFlowSource(scoped.flowSource) || scoped.collaborationAccess?.writable === false) {
+          json(res, 403, { error: "Exploration write permission denied" });
+          return;
+        }
+        const appended = appendAiTraceEvents(scoped.root, payload.id, payload.events || [], {
+          phase: payload.phase || "observed",
+        });
+        if (payload.status || payload.summary) {
+          appended.session = updateAiExplorationSession(scoped.root, payload.id, {
+            ...(payload.status ? { status: payload.status } : {}),
+            ...(payload.summary ? { summary: payload.summary } : {}),
+          });
+        }
+        json(res, 200, { ok: true, ...appended });
+      } catch (e) {
+        json(res, /Invalid exploration|ENOENT/.test(String(e?.message || e)) ? 404 : 400, { error: (e && e.message) || String(e) });
+      }
+      return;
+    }
+
+    if (req.method === "POST" && url.pathname === "/api/workspace/exploration/plan") {
+      let payload;
+      try { payload = JSON.parse(await readBody(req)); } catch {
+        json(res, 400, { error: "Invalid JSON body" });
+        return;
+      }
+      const goal = String(payload?.goal || "").trim();
+      if (!goal) {
+        json(res, 400, { error: "Missing exploration goal" });
+        return;
+      }
+      let scoped;
+      let exploration;
+      try {
+        scoped = resolveWorkspaceScopeRoot(root, {
+          flowId: payload.flowId || "",
+          flowSource: payload.flowSource || "user",
+          adminOwnerId: payload.adminOwnerId || "",
+          archived: payload.archived === true || payload.flowArchived === true,
+        }, userCtx);
+        if (scoped.error) {
+          json(res, 400, { error: scoped.error });
+          return;
+        }
+        if (scoped.archived || isReadonlyBuiltinFlowSource(scoped.flowSource) || scoped.collaborationAccess?.writable === false) {
+          json(res, 403, { error: "Exploration write permission denied" });
+          return;
+        }
+        const graphRead = readWorkspaceGraph(scoped.root);
+        const graph = graphRead?.graph || graphRead;
+        const workspaceSource = workspaceGraphAsSource(graph);
+        exploration = createAiExplorationSession(scoped.root, {
+          title: payload.title || goal.slice(0, 80),
+          goal,
+          mode: "planned",
+          status: "planning",
+          source: { provider: "agentflow", agent: String(payload.model || "default") },
+        });
+        const chunks = [];
+        let result = "";
+        const handle = startComposerAgent({
+          uiWorkspaceRoot: scoped.root,
+          cliWorkspace: scoped.root,
+          prompt: aiPlanPrompt({ goal, workspaceSource }),
+          modelKey: typeof payload.model === "string" ? payload.model.trim() : "",
+          agentflowUserId: userCtx.userId || "",
+          mode: "plan",
+          force: false,
+          sandboxDisabled: false,
+          approveMcps: false,
+          sandboxMode: "read-only",
+          allowDanger: false,
+          includeJsonResult: true,
+          onStreamEvent(ev) {
+            if (ev?.type !== "natural" || typeof ev.text !== "string") return;
+            if (ev.kind === "result") result = ev.text.trim();
+            else if (ev.kind === "assistant" && ev.text.trim()) chunks.push(ev.text.trim());
+          },
+        });
+        await handle.finished;
+        const plan = parseAiPlanResult(result || chunks.at(-1) || chunks.join("\n"), exploration.id);
+        const appended = appendAiTraceEvents(scoped.root, exploration.id, plan.events, { phase: "planned" });
+        const ready = updateAiExplorationSession(scoped.root, exploration.id, {
+          title: plan.title,
+          summary: plan.summary,
+          status: "ready",
+          eventCount: appended.session.eventCount,
+        });
+        json(res, 201, { ok: true, exploration: { ...ready, events: appended.events } });
+      } catch (e) {
+        if (scoped?.root && exploration?.id) {
+          try { updateAiExplorationSession(scoped.root, exploration.id, { status: "failed", summary: String(e?.message || e) }); } catch {}
+        }
+        json(res, 500, { error: (e && e.message) || String(e), ...(exploration?.id ? { explorationId: exploration.id } : {}) });
+      }
+      return;
+    }
+
+    if (req.method === "POST" && url.pathname === "/api/workspace/exploration/dry-run") {
+      let payload;
+      try { payload = JSON.parse(await readBody(req)); } catch {
+        json(res, 400, { error: "Invalid JSON body" });
+        return;
+      }
+      try {
+        const scoped = resolveWorkspaceScopeRoot(root, {
+          flowId: payload.flowId || "",
+          flowSource: payload.flowSource || "user",
+          adminOwnerId: payload.adminOwnerId || "",
+          archived: payload.archived === true || payload.flowArchived === true,
+        }, userCtx);
+        if (scoped.error) {
+          json(res, 400, { error: scoped.error });
+          return;
+        }
+        if (scoped.archived || isReadonlyBuiltinFlowSource(scoped.flowSource) || scoped.collaborationAccess?.writable === false) {
+          json(res, 403, { error: "Exploration dry-run permission denied" });
+          return;
+        }
+        const exploration = readAiExplorationSession(scoped.root, payload.id);
+        const planned = exploration.events.filter((event) => event.phase === "planned");
+        if (!planned.length) {
+          json(res, 400, { error: "Exploration has no planned spans" });
+          return;
+        }
+        const runToken = Date.now().toString(36);
+        const simulated = planned.map((event, index) => {
+          const blocked = event.requiresApproval === true || ["write", "external"].includes(event.sideEffect);
+          return {
+            id: `dry_${runToken}_${index + 1}`,
+            spanId: `dry_${runToken}_${event.spanId}`,
+            parentSpanId: event.parentSpanId ? `dry_${runToken}_${event.parentSpanId}` : "",
+            phase: "simulated",
+            type: event.type,
+            name: event.name,
+            summary: blocked
+              ? `策略预检已阻断：${event.summary || event.name}。真实执行前需要明确授权。`
+              : `策略预检通过：${event.summary || event.name}。本次未执行真实工具。`,
+            sideEffect: event.sideEffect,
+            requiresApproval: blocked,
+            status: blocked ? "blocked" : "success",
+            inputPreview: event.inputPreview || "",
+            outputPreview: blocked ? "副作用未执行" : "约束检查通过，未执行真实工具",
+          };
+        });
+        const appended = appendAiTraceEvents(scoped.root, exploration.id, simulated, { phase: "simulated" });
+        const blockedCount = appended.events.filter((event) => event.status === "blocked").length;
+        const updated = updateAiExplorationSession(scoped.root, exploration.id, {
+          mode: "simulated",
+          status: "ready",
+          summary: `Dry-run 策略预检完成：${appended.events.length - blockedCount} 项通过，${blockedCount} 项等待授权。`,
+          eventCount: appended.session.eventCount,
+        });
+        json(res, 200, {
+          ok: true,
+          exploration: { ...updated, events: [...exploration.events, ...appended.events] },
+          dryRun: { kind: "policy-check", executedTools: false, blockedCount },
+        });
+      } catch (e) {
+        json(res, 500, { error: (e && e.message) || String(e) });
+      }
+      return;
+    }
+
+    if (req.method === "POST" && url.pathname === "/api/workspace/exploration/materialize") {
+      let payload;
+      try { payload = JSON.parse(await readBody(req)); } catch {
+        json(res, 400, { error: "Invalid JSON body" });
+        return;
+      }
+      let scoped;
+      let exploration;
+      let materializeRunId = "";
+      try {
+        scoped = resolveWorkspaceScopeRoot(root, {
+          flowId: payload.flowId || "",
+          flowSource: payload.flowSource || "user",
+          adminOwnerId: payload.adminOwnerId || "",
+          archived: payload.archived === true || payload.flowArchived === true,
+        }, userCtx);
+        if (scoped.error) {
+          json(res, 400, { error: scoped.error });
+          return;
+        }
+        if (scoped.archived || isReadonlyBuiltinFlowSource(scoped.flowSource) || scoped.collaborationAccess?.writable === false) {
+          json(res, 403, { error: "Exploration materialization permission denied" });
+          return;
+        }
+        exploration = readAiExplorationSession(scoped.root, payload.id);
+        if (!exploration.events.length) {
+          json(res, 400, { error: "Exploration has no trace events" });
+          return;
+        }
+        const materializableEvents = materializableAiTraceEvents(exploration);
+        if (!materializableEvents.length) {
+          json(res, 400, { error: "Exploration has no planned or observed spans to materialize" });
+          return;
+        }
+        const dangerousEvents = materializableEvents.filter((event) => event.requiresApproval || ["write", "external"].includes(event.sideEffect));
+        if (dangerousEvents.length && payload.approveSideEffects !== true) {
+          json(res, 409, {
+            error: "Side-effect review is required before materialization",
+            sideEffects: dangerousEvents.map((event) => ({ spanId: event.spanId, name: event.name, sideEffect: event.sideEffect })),
+          });
+          return;
+        }
+        const beforeGraphRead = readWorkspaceGraph(scoped.root);
+        const beforeGraph = beforeGraphRead?.graph || beforeGraphRead;
+        const beforeIds = new Set([
+          ...(beforeGraph.nodes || []).map((node) => String(node.id || "")),
+          ...Object.keys(beforeGraph.instances || {}),
+        ].filter(Boolean));
+        materializeRunId = `materialize_${Date.now().toString(36)}`;
+        appendAiTraceEvents(scoped.root, exploration.id, [{
+          id: `${materializeRunId}_start`,
+          spanId: materializeRunId,
+          type: "agent",
+          name: "固化 Agent",
+          summary: "开始把已审核 Trace 转换为 Workspace DSL 调整态",
+          status: "running",
+          phase: "observed",
+          sideEffect: "write",
+        }], { phase: "observed" });
+        updateAiExplorationSession(scoped.root, exploration.id, { mode: "observed", status: "running" });
+        let reply = "";
+        let toolIndex = 0;
+        const handle = startComposerAgent({
+          uiWorkspaceRoot: scoped.root,
+          cliWorkspace: scoped.root,
+          prompt: aiMaterializationPrompt(exploration, workspaceGraphAsSource(beforeGraph)),
+          modelKey: typeof payload.model === "string" ? payload.model.trim() : "",
+          agentflowUserId: userCtx.userId || "",
+          force: true,
+          sandboxDisabled: false,
+          approveMcps: false,
+          sandboxMode: "workspace-write",
+          allowDanger: false,
+          onToolCall(subtype, toolName) {
+            toolIndex += 1;
+            try {
+              const toolStatus = /(?:complete|success|done)/i.test(String(subtype || ""))
+                ? "success"
+                : /(?:error|fail)/i.test(String(subtype || "")) ? "error" : "running";
+              const sideEffect = classifyAiToolSideEffect(toolName, subtype);
+              appendAiTraceEvents(scoped.root, exploration.id, [{
+                id: `${materializeRunId}_tool_${toolIndex}`,
+                spanId: `${materializeRunId}_tool_${toolIndex}`,
+                parentSpanId: materializeRunId,
+                type: String(subtype || "").toLowerCase() === "thinking" ? "decision" : "tool",
+                name: String(toolName || subtype || "Agent tool"),
+                summary: subtype ? `Agent 工具事件：${subtype}` : "Agent 工具调用",
+                status: toolStatus,
+                phase: "observed",
+                sideEffect,
+              }], { phase: "observed" });
+            } catch {
+              // Trace persistence must not interrupt an in-flight materialization.
+            }
+          },
+          onStreamEvent(ev) {
+            if (ev?.type === "natural" && ["assistant", "result"].includes(ev.kind) && typeof ev.text === "string" && ev.text.trim()) {
+              reply = ev.text.trim();
+            }
+          },
+        });
+        await handle.finished;
+        appendAiTraceEvents(scoped.root, exploration.id, [{
+          id: `${materializeRunId}_finish`,
+          spanId: materializeRunId,
+          type: "agent",
+          name: "固化 Agent",
+          summary: reply || "Workspace DSL 调整态生成完成",
+          status: "success",
+          phase: "observed",
+          sideEffect: "write",
+          endedAt: new Date().toISOString(),
+        }], { phase: "observed" });
+        const graphRead = readWorkspaceGraph(scoped.root);
+        const graph = graphRead?.graph || graphRead;
+        const graphIds = [
+          ...(graph.nodes || []).map((node) => String(node.id || "")),
+          ...Object.keys(graph.instances || {}),
+        ].filter(Boolean);
+        const nodeIds = [...new Set(graphIds)].filter((id) => !beforeIds.has(id));
+        const materialization = writeAiExplorationMaterialization(scoped.root, exploration.id, {
+          nodeIds,
+          designRevision: workspaceDesignRevision(graph),
+        });
+        appendAiTraceEvents(scoped.root, exploration.id, [{
+          type: "status",
+          name: "固化为 Workspace DSL",
+          summary: reply || `新增 ${nodeIds.length} 个节点`,
+          status: "success",
+          phase: "materialized",
+          sideEffect: "write",
+          artifacts: [{ kind: "dsl", path: "workspace.flow.js", label: "Workspace DSL" }],
+        }], { phase: "materialized" });
+        const updated = updateAiExplorationSession(scoped.root, exploration.id, {
+          mode: "materialized",
+          status: "completed",
+          materializedAt: materialization.materializedAt,
+        });
+        json(res, 200, { ok: true, exploration: updated, materialization, graph, reply });
+      } catch (e) {
+        if (scoped?.root && exploration?.id) {
+          try {
+            if (materializeRunId) {
+              appendAiTraceEvents(scoped.root, exploration.id, [{
+                id: `${materializeRunId}_error`,
+                spanId: materializeRunId,
+                type: "agent",
+                name: "固化 Agent",
+                summary: String(e?.message || e),
+                status: "error",
+                phase: "observed",
+                sideEffect: "write",
+                endedAt: new Date().toISOString(),
+              }], { phase: "observed" });
+            }
+            updateAiExplorationSession(scoped.root, exploration.id, { mode: "observed", status: "failed" });
+          } catch {}
+        }
+        json(res, 500, { error: (e && e.message) || String(e) });
+      }
+      return;
+    }
+
     if (url.pathname === "/api/workspace/conversations") {
       let payload = {};
       if (req.method === "POST") {
@@ -4018,6 +4810,7 @@ async function workspaceRoutes(req, res, ctx) {
           json(res, result.conflict ? 409 : 400, { error: result.error || "发布失败" });
           return;
         }
+        markRepositoryIndexDirty(root);
         json(res, 200, { ok: true, ...result });
       } catch (e) {
         json(res, 500, { error: (e && e.message) || String(e) });