@arronqzy/vue-view 0.1.23 → 0.1.25

package/src/panel/hooks/useWorkspaceProjects.ts

@@ -11,16 +11,16 @@ import {
   createWorkspaceProjectId,
   getWorkspaceProject,
   listWorkspaceProjects,
-  putWorkspaceProject,
   type WorkspaceProjectListItem,
   type WorkspaceProjectRecord,
 } from "../library/workspace-project-db";
-import { deleteWorkspaceProject } from "../library/workspace-storage";
 import {
-  broadcastWorkspaceProjectUpdate,
-  subscribeWorkspaceProjectsChanged,
-} from "../library/workspace-project-sync";
+  deleteWorkspaceProject,
+  putWorkspaceProject,
+} from "../library/workspace-storage";
+import { subscribeWorkspaceProjectsChanged } from "../library/workspace-project-sync";
 import { writeWorkspacePreviewCache, readWorkspacePreviewCache } from "../library/workspace-project-cache";
+import { normalizeAppNameSpace } from "@arronqzy/blueprint-dsl";
 import {
   cloneWorkspaceSnapshot,
   workspaceSnapshotsEqual,
@@ -48,6 +48,11 @@ export type UseWorkspaceProjectsOptions = {
   onProjectApplied?: (record: WorkspaceProjectRecord) => void;
   /** 外部传入的初始工作区，挂载后自动加载（不触发 onProjectApplied） */
   initialWorkspace?: MaybeRefOrGetter<WorkspaceProjectRecord | null | undefined>;
+  /**
+   * 按 IndexedDB id 打开工作区。与 initialWorkspace 同时存在时：
+   * 首次优先 initialWorkspace；之后 workspaceId 变化会从 IndexedDB 打开。
+   */
+  workspaceId?: MaybeRefOrGetter<string | null | undefined>;
   nameSpace?: MaybeRefOrGetter<string | null | undefined>;
 };
 
@@ -94,9 +99,11 @@ function workspaceApplyKey(record: WorkspaceProjectRecord): string {
 export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
   const { t, locale } = useI18nOptional();
   const nameSpace = () => toValue(options.nameSpace) ?? null;
+  const eventNameSpace = () => normalizeAppNameSpace(nameSpace()) || null;
   const projects = ref<WorkspaceProjectListItem[]>([]);
   const activeProjectId = ref<string | null>(null);
   const activeProjectName = ref<string | null>(null);
+  let activeCreatedAt: number | null = null;
   const syncedSnapshotRef = shallowRef<WorkspaceSnapshot | null>(null);
   let syncedPanelRevision: unknown = null;
   let pendingRevisionSync = false;
@@ -150,7 +157,9 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
         const active = activeProjectId.value;
         const removedActive =
           message.type === "cleared" ||
-          (active !== null && message.projectIds.includes(active));
+          (message.type === "deleted" &&
+            active !== null &&
+            message.projectIds.includes(active));
         if (removedActive) {
           activeProjectId.value = null;
           activeProjectName.value = null;
@@ -187,9 +196,61 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     return !workspaceSnapshotsEqual(buildCurrentSnapshot(), syncedSnapshotRef.value);
   });
 
+  async function ensureWorkspaceInIndexedDb(record: WorkspaceProjectRecord) {
+    const id = typeof record.id === "string" ? record.id.trim() : "";
+    if (!id) return;
+    try {
+      const existing = await getWorkspaceProject(id, nameSpace());
+      const incomingUpdatedAt =
+        typeof record.updatedAt === "number" && Number.isFinite(record.updatedAt)
+          ? record.updatedAt
+          : 0;
+      if (existing && existing.updatedAt >= incomingUpdatedAt) {
+        return;
+      }
+      const now = Date.now();
+      const name =
+        (typeof record.name === "string" && record.name.trim()) ||
+        (typeof record.productName === "string" && record.productName.trim()) ||
+        t("panel.defaults.unnamedProduct");
+      const toStore: WorkspaceProjectRecord = {
+        ...record,
+        id,
+        name,
+        createdAt: existing?.createdAt ?? record.createdAt ?? now,
+        updatedAt: incomingUpdatedAt || now,
+        panelState:
+          normalizeImportedPanelState(record.panelState) ??
+          existing?.panelState ??
+          createEmptyPanelState(),
+        blueprintDocument:
+          parseBlueprintData(record.blueprintDocument).value ??
+          existing?.blueprintDocument ??
+          BlueprintGraph.empty().document,
+        blueprintMeta: {
+          name:
+            record.blueprintMeta?.name ??
+            existing?.blueprintMeta?.name ??
+            t("panel.defaults.unnamedBlueprint"),
+          remark:
+            record.blueprintMeta?.remark ?? existing?.blueprintMeta?.remark ?? "",
+        },
+        productName:
+          typeof record.productName === "string" && record.productName.trim()
+            ? record.productName
+            : existing?.productName ?? t("panel.defaults.unnamedProduct"),
+        titleIconDataUrl: record.titleIconDataUrl ?? existing?.titleIconDataUrl,
+      };
+      await putWorkspaceProject(toStore, nameSpace());
+      await refreshProjects();
+    } catch (error) {
+      console.warn("[abuilder] ensureWorkspaceInIndexedDb failed", error);
+    }
+  }
+
   function applyProjectRecord(
     record: WorkspaceProjectRecord,
-    applyOptions?: { notifyApplied?: boolean }
+    applyOptions?: { notifyApplied?: boolean; persistToIndexedDb?: boolean }
   ) {
     const parsedBlueprint = parseBlueprintData(record.blueprintDocument);
     const blueprintDocument =
@@ -213,6 +274,10 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     options.setTitleIconDataUrl(titleIconDataUrl);
     activeProjectId.value = record.id || null;
     activeProjectName.value = record.name ?? null;
+    activeCreatedAt =
+      typeof record.createdAt === "number" && Number.isFinite(record.createdAt)
+        ? record.createdAt
+        : Date.now();
     syncedSnapshotRef.value = cloneWorkspaceSnapshot({
       blueprintDocument,
       blueprintMeta,
@@ -221,15 +286,23 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     });
     syncedPanelRevision = toValue(options.panelRevision);
     pendingRevisionSync = true;
+    const normalized: WorkspaceProjectRecord = {
+      ...record,
+      id: record.id,
+      name: record.name ?? productName,
+      createdAt: activeCreatedAt,
+      updatedAt: record.updatedAt ?? Date.now(),
+      blueprintDocument,
+      blueprintMeta,
+      panelState,
+      productName,
+      titleIconDataUrl: titleIconDataUrl || undefined,
+    };
     if (applyOptions?.notifyApplied !== false) {
-      options.onProjectApplied?.({
-        ...record,
-        blueprintDocument,
-        blueprintMeta,
-        panelState,
-        productName,
-        titleIconDataUrl: titleIconDataUrl || undefined,
-      });
+      options.onProjectApplied?.(normalized);
+    }
+    if (applyOptions?.persistToIndexedDb) {
+      void ensureWorkspaceInIndexedDb(normalized);
     }
   }
 
@@ -244,46 +317,13 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     options.setTitleIconDataUrl("");
     activeProjectId.value = null;
     activeProjectName.value = null;
+    activeCreatedAt = null;
     syncedSnapshotRef.value = null;
   }
 
   let bootstrapped = false;
   let appliedWorkspaceKey: string | null = null;
-
-  function bootstrapInitialWorkspace() {
-    const initialWorkspace = toValue(options.initialWorkspace) ?? null;
-    if (!bootstrapped) {
-      bootstrapped = true;
-      if (hasWorkspacePayload(initialWorkspace)) {
-        applyProjectRecord(initialWorkspace, { notifyApplied: false });
-        appliedWorkspaceKey = workspaceApplyKey(initialWorkspace);
-      } else {
-        applyEmptyWorkspace();
-      }
-      return;
-    }
-    if (!hasWorkspacePayload(initialWorkspace)) return;
-    const key = workspaceApplyKey(initialWorkspace);
-    if (appliedWorkspaceKey === key) return;
-    appliedWorkspaceKey = key;
-    applyProjectRecord(initialWorkspace, { notifyApplied: false });
-  }
-
-  onMounted(() => {
-    bootstrapInitialWorkspace();
-    void refreshProjects();
-    previewPollTimer = window.setInterval(refreshPreviewing, 2000);
-  });
-
-  watch(
-    () => {
-      const record = toValue(options.initialWorkspace);
-      return record ? workspaceApplyKey(record) : "";
-    },
-    () => {
-      bootstrapInitialWorkspace();
-    }
-  );
+  let workspaceIdApplied: string | null = null;
 
   async function persistProject(persistOptions: {
     id?: string;
@@ -294,7 +334,7 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
       const snapshot = cloneWorkspaceSnapshot(buildCurrentSnapshot());
       const now = Date.now();
       const id = persistOptions.id ?? createWorkspaceProjectId();
-      const createdAt = persistOptions.createdAt ?? now;
+      const createdAt = persistOptions.createdAt ?? activeCreatedAt ?? now;
       const name = (persistOptions.name ?? "").trim() || resolveProjectName();
 
       let panelState: State;
@@ -320,10 +360,9 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
       };
 
       await putWorkspaceProject(record, nameSpace());
-      writeWorkspacePreviewCache(record, nameSpace());
-      broadcastWorkspaceProjectUpdate(id, now, nameSpace());
       activeProjectId.value = id;
       activeProjectName.value = name;
+      activeCreatedAt = createdAt;
       syncedSnapshotRef.value = snapshot;
       syncedPanelRevision = toValue(options.panelRevision);
       pendingRevisionSync = false;
@@ -334,11 +373,40 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     }
   }
 
+  function getCurrentWorkspaceRecord(): WorkspaceProjectRecord | null {
+    if (!activeProjectId.value) return null;
+    try {
+      const snapshot = buildCurrentSnapshot();
+      const panelState = options.exportPanelData();
+      const now = Date.now();
+      return {
+        id: activeProjectId.value,
+        name: activeProjectName.value || resolveProjectName(),
+        createdAt: activeCreatedAt ?? now,
+        updatedAt: now,
+        panelState,
+        blueprintDocument: snapshot.blueprintDocument,
+        blueprintMeta: snapshot.blueprintMeta,
+        productName:
+          typeof snapshot.productName === "string"
+            ? snapshot.productName
+            : resolveProjectName(),
+        titleIconDataUrl: snapshot.titleIconDataUrl || undefined,
+      };
+    } catch (error) {
+      console.warn("[abuilder] getCurrentWorkspace failed", error);
+      return null;
+    }
+  }
+
   async function handleCreateProject() {
     return runBusyTask(t("common.savingWorkspace"), async () => {
       const name = resolveProjectName();
       const record = await persistProject({ name });
-      emitAbuilderEvent(AbuilderEvents.workspaceAdd, record);
+      emitAbuilderEvent(AbuilderEvents.workspaceAdd, {
+        ...record,
+        nameSpace: eventNameSpace(),
+      });
       return { name, id: record.id };
     });
   }
@@ -354,16 +422,24 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
       const record = await persistProject({
         id: projectId,
         name,
-        createdAt: existing?.createdAt,
+        createdAt: existing?.createdAt ?? activeCreatedAt ?? undefined,
+      });
+      emitAbuilderEvent(AbuilderEvents.workspaceSync, {
+        ...record,
+        nameSpace: eventNameSpace(),
       });
       return { name, id: record.id };
     });
   }
 
-  async function handleOpenProject(id: string) {
+  async function handleOpenProject(idOrRecord: string | WorkspaceProjectRecord) {
     try {
       await runBusyTask(t("common.loadingWorkspace"), async () => {
-        const record = await getWorkspaceProject(id, nameSpace());
+        if (typeof idOrRecord !== "string") {
+          applyProjectRecord(idOrRecord, { persistToIndexedDb: true });
+          return;
+        }
+        const record = await getWorkspaceProject(idOrRecord, nameSpace());
         if (!record) {
           await refreshProjects();
           throw new Error(t("panel.messages.workspaceNotFound"));
@@ -381,20 +457,17 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
         throw new Error(t("panel.messages.saveWorkspaceFirst"));
       }
       const existing = await getWorkspaceProject(activeProjectId.value, nameSpace());
-      if (!existing) {
-        activeProjectId.value = null;
-        activeProjectName.value = null;
-        syncedSnapshotRef.value = null;
-        await refreshProjects();
-        throw new Error(t("panel.messages.workspaceNotFound"));
-      }
-      const name = resolveProjectName() || existing.name;
+      const name =
+        resolveProjectName() || existing?.name || activeProjectName.value || "";
       const record = await persistProject({
         id: activeProjectId.value,
         name,
-        createdAt: existing.createdAt,
+        createdAt: existing?.createdAt ?? activeCreatedAt ?? undefined,
+      });
+      emitAbuilderEvent(AbuilderEvents.workspaceSync, {
+        ...record,
+        nameSpace: eventNameSpace(),
       });
-      emitAbuilderEvent(AbuilderEvents.workspaceSync, record);
       return name;
     });
   }
@@ -406,6 +479,7 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
         if (activeProjectId.value === id) {
           activeProjectId.value = null;
           activeProjectName.value = null;
+          activeCreatedAt = null;
           syncedSnapshotRef.value = null;
         }
         previewWindows.delete(id);
@@ -456,6 +530,73 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     });
   }
 
+  function bootstrapInitialWorkspace() {
+    const initialWorkspace = toValue(options.initialWorkspace) ?? null;
+    const workspaceIdRaw = toValue(options.workspaceId);
+    const workspaceId =
+      typeof workspaceIdRaw === "string" ? workspaceIdRaw.trim() : "";
+    if (!bootstrapped) {
+      bootstrapped = true;
+      if (hasWorkspacePayload(initialWorkspace)) {
+        applyProjectRecord(initialWorkspace, {
+          notifyApplied: false,
+          persistToIndexedDb: true,
+        });
+        appliedWorkspaceKey = workspaceApplyKey(initialWorkspace);
+        if (initialWorkspace.id) workspaceIdApplied = initialWorkspace.id;
+      } else if (workspaceId) {
+        workspaceIdApplied = workspaceId;
+        void handleOpenProject(workspaceId);
+      } else {
+        applyEmptyWorkspace();
+      }
+      return;
+    }
+    if (!hasWorkspacePayload(initialWorkspace)) return;
+    const key = workspaceApplyKey(initialWorkspace);
+    if (appliedWorkspaceKey === key) return;
+    appliedWorkspaceKey = key;
+    if (initialWorkspace.id) workspaceIdApplied = initialWorkspace.id;
+    applyProjectRecord(initialWorkspace, {
+      notifyApplied: false,
+      persistToIndexedDb: true,
+    });
+  }
+
+  onMounted(() => {
+    bootstrapInitialWorkspace();
+    void refreshProjects();
+    previewPollTimer = window.setInterval(refreshPreviewing, 2000);
+  });
+
+  watch(
+    () => {
+      const record = toValue(options.initialWorkspace);
+      return record ? workspaceApplyKey(record) : "";
+    },
+    () => {
+      bootstrapInitialWorkspace();
+    }
+  );
+
+  watch(
+    () => {
+      const raw = toValue(options.workspaceId);
+      return typeof raw === "string" ? raw.trim() : "";
+    },
+    (id) => {
+      if (!bootstrapped) return;
+      if (!id) return;
+      if (workspaceIdApplied === id) return;
+      if (activeProjectId.value === id) {
+        workspaceIdApplied = id;
+        return;
+      }
+      workspaceIdApplied = id;
+      void handleOpenProject(id);
+    }
+  );
+
   return {
     projects,
     activeProjectId,
@@ -468,6 +609,7 @@ export function useWorkspaceProjects(options: UseWorkspaceProjectsOptions) {
     handleSyncProject,
     handleDeleteProject,
     handlePreviewProject,
+    getCurrentWorkspaceRecord,
     refreshProjects,
   };
 }

package/src/panel/library/abuilder-storage.ts

@@ -0,0 +1,168 @@
+import { normalizeAppNameSpace } from "@arronqzy/blueprint-dsl";
+import {
+  clearAllExecutionRunRecords,
+  clearApiCollections as clearApiCollectionsRaw,
+  clearBlueprintLibrary as clearBlueprintLibraryRecords,
+  deleteApiCollection as deleteApiCollectionRaw,
+  deleteBlueprintLibraryRecord as deleteBlueprintLibraryRecordRaw,
+  putApiCollection as putApiCollectionRaw,
+  putBlueprintLibraryRecord as putBlueprintLibraryRecordRaw,
+  putExecutionRunRecord as putExecutionRunRecordRaw,
+  upsertApiCollectionFromJson as upsertApiCollectionFromJsonRaw,
+  type BlueprintLibraryRecord,
+  type ExecutionRunRecord,
+  type UpsertApiCollectionInput,
+  type UpsertApiCollectionResult,
+} from "@arronqzy/vue-blueprint";
+import type { ApiCollectionRecord } from "@arronqzy/blueprint-dsl";
+import { broadcastBlueprintLibraryChanged } from "./blueprint-library-sync";
+import { AbuilderEvents, emitAbuilderEvent } from "./event-subscription";
+import { clearWorkspaceProjects } from "./workspace-storage";
+
+export {
+  listBlueprintLibrary,
+  getBlueprintLibraryRecord,
+  listExecutionRunRecords,
+  getExecutionRunRecord,
+  deleteExecutionRunRecord,
+  clearAllExecutionRunRecords,
+  purgeExecutionRunsOlderThan,
+  trimExecutionRunRecordsToMax,
+  readExecutionLogSettings,
+  writeExecutionLogSettings,
+  listApiCollectionRecords,
+} from "@arronqzy/vue-blueprint";
+export type {
+  BlueprintLibraryListItem,
+  BlueprintLibraryRecord,
+  ExecutionRunRecord,
+  ExecutionLogSettings,
+  UpsertApiCollectionInput,
+  UpsertApiCollectionResult,
+} from "@arronqzy/vue-blueprint";
+export type { ApiCollectionRecord } from "@arronqzy/blueprint-dsl";
+
+function resolvedNameSpace(nameSpace?: string | null): string | null {
+  return normalizeAppNameSpace(nameSpace) || null;
+}
+
+/** 写入 / 覆盖蓝图库记录；已挂载的编辑器会刷新蓝图库列表 */
+export async function putBlueprintLibraryRecord(
+  record: BlueprintLibraryRecord,
+  nameSpace?: string | null
+): Promise<BlueprintLibraryRecord> {
+  const saved = await putBlueprintLibraryRecordRaw(record, nameSpace);
+  broadcastBlueprintLibraryChanged(nameSpace);
+  emitAbuilderEvent(AbuilderEvents.blueprintLibraryChanged, {
+    nameSpace: resolvedNameSpace(nameSpace),
+    action: "put",
+    ids: [saved.id],
+  });
+  return saved;
+}
+
+/** 删除蓝图库中的一条蓝图；已挂载的编辑器会刷新蓝图库列表 */
+export async function deleteBlueprintLibraryRecord(
+  id: string,
+  nameSpace?: string | null
+): Promise<void> {
+  await deleteBlueprintLibraryRecordRaw(id, nameSpace);
+  broadcastBlueprintLibraryChanged(nameSpace);
+  emitAbuilderEvent(AbuilderEvents.blueprintLibraryChanged, {
+    nameSpace: resolvedNameSpace(nameSpace),
+    action: "delete",
+    ids: [id],
+  });
+}
+
+/** 清空该 nameSpace 下的蓝图库，返回删除数量；已挂载的编辑器会刷新蓝图库列表 */
+export async function clearBlueprintLibrary(nameSpace?: string | null): Promise<number> {
+  const count = await clearBlueprintLibraryRecords(nameSpace);
+  broadcastBlueprintLibraryChanged(nameSpace);
+  emitAbuilderEvent(AbuilderEvents.blueprintLibraryChanged, {
+    nameSpace: resolvedNameSpace(nameSpace),
+    action: "clear",
+  });
+  return count;
+}
+
+/** 写入一条蓝图执行日志 */
+export async function putExecutionRunRecord(
+  record: ExecutionRunRecord,
+  nameSpace?: string | null
+): Promise<ExecutionRunRecord> {
+  return putExecutionRunRecordRaw(record, nameSpace);
+}
+
+/** 写入接口集合；persistLocal 时落 IndexedDB，并同步已挂载编辑器的内存列表 */
+export async function putApiCollection(
+  record: ApiCollectionRecord,
+  nameSpace?: string | null
+): Promise<ApiCollectionRecord> {
+  const saved = await putApiCollectionRaw(record, nameSpace);
+  emitAbuilderEvent(AbuilderEvents.apiCollectionChanged, {
+    nameSpace: resolvedNameSpace(nameSpace),
+    action: "put",
+    ids: [saved.id],
+  });
+  return saved;
+}
+
+/** 从 JSON 文本 upsert 接口集合；可传 nameSpace */
+export async function upsertApiCollectionFromJson(
+  input: UpsertApiCollectionInput
+): Promise<UpsertApiCollectionResult> {
+  const result = await upsertApiCollectionFromJsonRaw(input);
+  if (result.ok) {
+    emitAbuilderEvent(AbuilderEvents.apiCollectionChanged, {
+      nameSpace: resolvedNameSpace(input.nameSpace),
+      action: "put",
+      ids: [result.record.id],
+    });
+  }
+  return result;
+}
+
+export async function deleteApiCollection(
+  id: string,
+  nameSpace?: string | null
+): Promise<void> {
+  await deleteApiCollectionRaw(id, nameSpace);
+  emitAbuilderEvent(AbuilderEvents.apiCollectionChanged, {
+    nameSpace: resolvedNameSpace(nameSpace),
+    action: "delete",
+    ids: [id],
+  });
+}
+
+export async function clearApiCollections(nameSpace?: string | null): Promise<number> {
+  const count = await clearApiCollectionsRaw(nameSpace);
+  emitAbuilderEvent(AbuilderEvents.apiCollectionChanged, {
+    nameSpace: resolvedNameSpace(nameSpace),
+    action: "clear",
+  });
+  return count;
+}
+
+export type AbuilderStorageClearResult = {
+  workspaces: number;
+  blueprints: number;
+  executionRuns: number;
+  apiCollections: number;
+};
+
+/**
+ * 清空该 nameSpace 下编辑器写入浏览器的全部数据：工作区、蓝图库、执行日志、接口集合。
+ * 主题、字号、日志保留设置等偏好不受影响。
+ */
+export async function clearAbuilderStorage(
+  nameSpace?: string | null
+): Promise<AbuilderStorageClearResult> {
+  const [workspaces, blueprints, executionRuns, apiCollections] = await Promise.all([
+    clearWorkspaceProjects(nameSpace),
+    clearBlueprintLibrary(nameSpace),
+    clearAllExecutionRunRecords(nameSpace),
+    clearApiCollections(nameSpace),
+  ]);
+  return { workspaces, blueprints, executionRuns, apiCollections };
+}

package/src/panel/library/abuilder-view-handle.ts

@@ -0,0 +1,100 @@
+import { normalizeAppNameSpace } from "@arronqzy/blueprint-dsl";
+import type { WorkspaceProjectRecord } from "./workspace-project-db";
+
+/** 已挂载编辑面板的命令式句柄（也可通过 `ref` 拿到） */
+export type AbuilderViewHandle = {
+  /** 当前 nameSpace */
+  getNameSpace: () => string | null;
+  /** 导出当前编辑器中的完整工作区；尚无关联 id 时返回 null */
+  getCurrentWorkspace: () => WorkspaceProjectRecord | null;
+  /** 按 id 从 IndexedDB 打开，或直接应用完整记录 */
+  openWorkspace: (idOrRecord: string | WorkspaceProjectRecord) => Promise<void>;
+  /** 创建新工作区并写入 IndexedDB，发出 workspace:add */
+  createWorkspace: () => Promise<{ name: string; id: string }>;
+  /** 保存当前工作区到 IndexedDB，发出 workspace:sync；无 active 时等同创建 */
+  saveWorkspace: () => Promise<{ name: string; id: string }>;
+  /** 同步当前工作区到 IndexedDB，发出 workspace:sync */
+  syncWorkspace: () => Promise<string>;
+};
+
+const handles = new Set<AbuilderViewHandle>();
+
+export function registerAbuilderViewHandle(handle: AbuilderViewHandle): () => void {
+  handles.add(handle);
+  return () => {
+    handles.delete(handle);
+  };
+}
+
+function findHandle(nameSpace?: string | null): AbuilderViewHandle | null {
+  if (handles.size === 0) return null;
+  if (nameSpace === undefined) {
+    return handles.values().next().value ?? null;
+  }
+  const wanted = normalizeAppNameSpace(nameSpace);
+  for (const handle of handles) {
+    if (normalizeAppNameSpace(handle.getNameSpace()) === wanted) return handle;
+  }
+  return null;
+}
+
+/**
+ * 读取当前已挂载编辑器中的工作区快照。
+ * 同页多个实例时请传入 `nameSpace`；未挂载或尚无 active 工作区时返回 null。
+ */
+export function getCurrentWorkspace(
+  nameSpace?: string | null
+): WorkspaceProjectRecord | null {
+  return findHandle(nameSpace)?.getCurrentWorkspace() ?? null;
+}
+
+/**
+ * 命令式打开工作区（不 remount）。
+ * 同页多个实例时请传入 `nameSpace`。
+ */
+export async function openWorkspace(
+  idOrRecord: string | WorkspaceProjectRecord,
+  nameSpace?: string | null
+): Promise<void> {
+  const handle = findHandle(nameSpace);
+  if (!handle) {
+    throw new Error(
+      "No mounted Abuilder panel. Pass initialWorkspace or mount <App> first."
+    );
+  }
+  await handle.openWorkspace(idOrRecord);
+}
+
+export async function createWorkspace(
+  nameSpace?: string | null
+): Promise<{ name: string; id: string }> {
+  const handle = findHandle(nameSpace);
+  if (!handle) {
+    throw new Error(
+      "No mounted Abuilder panel. Pass initialWorkspace or mount <App> first."
+    );
+  }
+  return handle.createWorkspace();
+}
+
+export async function saveWorkspace(
+  nameSpace?: string | null
+): Promise<{ name: string; id: string }> {
+  const handle = findHandle(nameSpace);
+  if (!handle) {
+    throw new Error(
+      "No mounted Abuilder panel. Pass initialWorkspace or mount <App> first."
+    );
+  }
+  return handle.saveWorkspace();
+}
+
+export async function syncWorkspace(nameSpace?: string | null): Promise<string> {
+  const handle = findHandle(nameSpace);
+  if (!handle) {
+    throw new Error(
+      "No mounted Abuilder panel. Pass initialWorkspace or mount <App> first."
+    );
+  }
+  return handle.syncWorkspace();
+}