@arronqzy/react-view 1.0.38 → 1.0.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arronqzy/react-view",
-  "version": "1.0.38",
+  "version": "1.0.39",
   "files": [
     "src",
     "dist",
@@ -30,14 +30,14 @@
     "@codemirror/lang-json": "^6.0.1",
     "@codemirror/theme-one-dark": "^6.1.2",
     "@codemirror/view": "^6.36.2",
-    "@arronqzy/blueprint-dsl": "1.0.17",
-    "@arronqzy/ui": "1.0.10",
     "@arronqzy/i18n": "0.1.17",
-    "@arronqzy/react-blueprint": "1.0.23",
+    "@arronqzy/ui": "1.0.10",
+    "@arronqzy/blueprint-dsl": "1.0.17",
     "@arronqzy/rx-store": "1.0.8",
     "@arronqzy/view-scene3d": "0.1.5",
+    "@arronqzy/view-table": "0.1.8",
     "@arronqzy/webllm-assistant": "0.1.16",
-    "@arronqzy/view-table": "0.1.8"
+    "@arronqzy/react-blueprint": "1.0.24"
   },
   "devDependencies": {
     "@types/react": "^19.0.1",
@@ -46,8 +46,8 @@
     "eslint": "^8.57.0",
     "typescript": "^5.5.4",
     "@arronqzy/eslint-config": "0.0.0",
-    "@arronqzy/typescript-config": "1.0.0",
-    "@arronqzy/tailwind": "1.0.2"
+    "@arronqzy/tailwind": "1.0.2",
+    "@arronqzy/typescript-config": "1.0.0"
   },
   "scripts": {
     "lint": "eslint \"src/**/*.{ts,tsx}\"",

package/readme.md

@@ -57,7 +57,8 @@ export function Editor({ workspace }: { workspace?: WorkspaceProjectRecord | nul
 |------|------|------|
 | `className` | 根节点 class | — |
 | `initialZoom` | 初始缩放 | `1` |
-| `initialWorkspace` | 挂载后加载的完整工作区。空则空白画布 | — |
+| `initialWorkspace` | 挂载后加载的完整工作区。空则空白画布。带 `id` 时默认同步进 IndexedDB | — |
+| `workspaceId` | 按 IndexedDB id 打开（不 remount） | — |
 
 ## 在线预览
 
@@ -89,7 +90,7 @@ parseOnlinePreviewSearchParams("?preview=online&projectId=xxx");
 
 ## 工作区事件
 
-回调带完整工作区，用来写自己的后端。IndexedDB 的增删改查不导出。
+回调带完整工作区，用来写自己的后端。`initialWorkspace` 会默认同步进 IndexedDB；本地副本可用导出的 list / get / delete / clear 清理。
 
 ```ts
 import {
@@ -111,10 +112,12 @@ syncSub.unsubscribe();
 | 事件 | 常量 | 何时触发 |
 |------|------|----------|
 | `workspace:add` | `AbuilderEvents.workspaceAdd` | 创建成功 |
-| `workspace:sync` | `AbuilderEvents.workspaceSync` | 同步成功 |
+| `workspace:sync` | `AbuilderEvents.workspaceSync` | 同步成功（载荷含 `nameSpace`） |
 | `workspace:delete` | `AbuilderEvents.workspaceDelete` | 删除工作区，参数 `{ ids, nameSpace }` |
+| `blueprint-library:changed` | `AbuilderEvents.blueprintLibraryChanged` | 蓝图库变更 |
+| `api-collection:changed` | `AbuilderEvents.apiCollectionChanged` | 接口集合变更 |
 
-`workspace:add` / `workspace:sync` 的参数字段：`id`、`name`、`createdAt`、`updatedAt`、`panelState`、`blueprintDocument`、`blueprintMeta`、`productName`、`titleIconDataUrl`。
+`workspace:add` / `workspace:sync` 的参数字段：上述工作区字段 + `nameSpace`。可用 `addEventSubscription(event, cb, { nameSpace })` 过滤。
 
 校验：
 
@@ -155,14 +158,14 @@ const dataUrl = await getPreviewSnapshot({
 | `addEventSubscription` / `AbuilderEvents` | 工作区事件 |
 | `getPreviewSnapshot` | 预览截图 data URL |
 | `parseWorkspaceData` 等 | 校验 / 解析 / 空工作区 |
-| `listWorkspaceProjects` / `getWorkspaceProject` / `deleteWorkspaceProject` / `clearWorkspaceProjects` | 浏览器 IndexedDB 中保存的工作区 |
-| `listBlueprintLibrary` / `getBlueprintLibraryRecord` / `deleteBlueprintLibraryRecord` / `clearBlueprintLibrary` | 蓝图库；删除后已挂载的面板自动刷新 |
-| `listExecutionRunRecords` / `getExecutionRunRecord` / `deleteExecutionRunRecord` / `clearAllExecutionRunRecords` / `purgeExecutionRunsOlderThan` / `trimExecutionRunRecordsToMax` | 蓝图执行日志 |
-| `readExecutionLogSettings` / `writeExecutionLogSettings` | 执行日志保留策略 |
-| `listApiCollectionRecords` / `deleteApiCollection` / `clearApiCollections` | 接口集合 |
-| `clearAbuilderStorage` | 一次清空以上四类数据，返回各自删除数量；不动偏好设置 |
-
-本地数据函数的最后一个参数都是 `nameSpace`，要和面板的 `nameSpace` 一致。
+| `putWorkspaceProject` / `upsertWorkspaceProject` / `list` / `get` / `delete` / `clear` | 工作区完整 CRUD |
+| `putBlueprintLibraryRecord` / `list` / `get` / `delete` / `clear` | 蓝图库完整 CRUD |
+| `putExecutionRunRecord` / `list` / `get` / `delete` / `clear` / `purge*` / `trim*` | 执行日志 |
+| `putApiCollection` / `upsertApiCollectionFromJson` / `list` / `delete` / `clear` | 接口集合 |
+| `getCurrentWorkspace` / `openWorkspace` / `createWorkspace` / `saveWorkspace` / `syncWorkspace` | 命令式操作已挂载面板 |
+| `clearAbuilderStorage` | 一次清空四类数据 |
+
+本地数据函数的 `nameSpace` 要和面板一致。面板 `ref` 类型为 `AbuilderViewHandle`。
 | `createView` / `createAction` | 视图 DSL 扩展点（`src/core`） |
 
 ## 样式

package/src/index.ts

@@ -12,28 +12,38 @@ export {
 export type {
   AbuilderEventName,
   AbuilderEventPayloadMap,
+  AddEventSubscriptionOptions,
   WorkspaceAddEventPayload,
   WorkspaceSyncEventPayload,
   WorkspaceDeleteEventPayload,
+  BlueprintLibraryChangedEventPayload,
   ApiCollectionUploadStartEventPayload,
   ApiCollectionUploadSuccessEventPayload,
+  ApiCollectionChangedEventPayload,
   WorkspaceData,
 } from "./panel/library/event-subscription";
 export type { WorkspaceProjectRecord } from "./panel/library/workspace-project-db";
 export {
   listWorkspaceProjects,
   getWorkspaceProject,
+  putWorkspaceProject,
+  upsertWorkspaceProject,
   deleteWorkspaceProject,
   clearWorkspaceProjects,
 } from "./panel/library/workspace-storage";
-export type { WorkspaceProjectListItem } from "./panel/library/workspace-storage";
+export type {
+  WorkspaceProjectListItem,
+  PutWorkspaceProjectOptions,
+} from "./panel/library/workspace-storage";
 export {
   listBlueprintLibrary,
   getBlueprintLibraryRecord,
+  putBlueprintLibraryRecord,
   deleteBlueprintLibraryRecord,
   clearBlueprintLibrary,
   listExecutionRunRecords,
   getExecutionRunRecord,
+  putExecutionRunRecord,
   deleteExecutionRunRecord,
   clearAllExecutionRunRecords,
   purgeExecutionRunsOlderThan,
@@ -41,6 +51,8 @@ export {
   readExecutionLogSettings,
   writeExecutionLogSettings,
   listApiCollectionRecords,
+  putApiCollection,
+  upsertApiCollectionFromJson,
   deleteApiCollection,
   clearApiCollections,
   clearAbuilderStorage,
@@ -52,6 +64,16 @@ export type {
   ExecutionRunRecord,
   ExecutionLogSettings,
   ApiCollectionRecord,
+  UpsertApiCollectionInput,
+  UpsertApiCollectionResult,
 } from "./panel/library/abuilder-storage";
+export {
+  getCurrentWorkspace,
+  openWorkspace,
+  createWorkspace,
+  saveWorkspace,
+  syncWorkspace,
+} from "./panel/library/abuilder-view-handle";
+export type { AbuilderViewHandle } from "./panel/library/abuilder-view-handle";
 export { getPreviewSnapshot } from "./panel/library/preview-snapshot";
 export type { GetPreviewSnapshotOptions } from "./panel/library/preview-snapshot";

package/src/panel/ReactViewPanel.tsx

@@ -1,4 +1,16 @@
-import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import {
+  registerAbuilderViewHandle,
+  type AbuilderViewHandle,
+} from "./library/abuilder-view-handle";
 import { useI18n } from "@arronqzy/i18n/react";
 import { relocalizeMessage, type Locale } from "@arronqzy/i18n";
 import type { State } from "@arronqzy/rx-store";
@@ -141,6 +153,11 @@ export type ReactViewPanelProps = {
   className?: string;
   /** 外部传入的完整工作区数据，挂载后按这份数据完整渲染；空则显示空白，不自动打开 IndexedDB 记录 */
   initialWorkspace?: WorkspaceProjectRecord | null;
+  /**
+   * 按 IndexedDB id 打开工作区（不 remount）。
+   * 与 `initialWorkspace` 同时存在时：首次优先完整记录；之后 id 变化从 IndexedDB 打开。
+   */
+  workspaceId?: string | null;
   /** 界面语言；省略时按 localStorage / 浏览器语言解析 */
   locale?: Locale | null;
   onLocaleChange?: (locale: Locale) => void;
@@ -156,14 +173,18 @@ export type ReactViewPanelProps = {
   packageVersion?: string | null;
 };
 
-function ReactViewPanelInner({
+const ReactViewPanelInner = forwardRef<AbuilderViewHandle, ReactViewPanelProps>(function ReactViewPanelInner(
+  {
   initialZoom = 1,
   className,
   initialWorkspace = null,
+  workspaceId = null,
   nameSpace = null,
   packageName = null,
   packageVersion = null,
-}: ReactViewPanelProps) {
+}: ReactViewPanelProps,
+  ref
+) {
   const { t, locale, setLocale } = useI18n();
   const messages = useMemo(() => getPanelMessages(t), [t]);
   const THEME_STORAGE_KEY = appStorageKey("panel:theme", nameSpace);
@@ -1076,9 +1097,26 @@ function ReactViewPanelInner({
     panelRevision: `${historyCursor}|${allElements.length}`,
     onProjectApplied: handleWorkspaceProjectApplied,
     initialWorkspace,
+    workspaceId,
     nameSpace,
   });
 
+  const viewHandle = useMemo<AbuilderViewHandle>(
+    () => ({
+      getNameSpace: () => nameSpace ?? null,
+      getCurrentWorkspace: () => workspaceProjects.getCurrentWorkspaceRecord(),
+      openWorkspace: (idOrRecord) => workspaceProjects.handleOpenProject(idOrRecord),
+      createWorkspace: () => workspaceProjects.handleCreateProject(),
+      saveWorkspace: () => workspaceProjects.handleSaveProject(),
+      syncWorkspace: () => workspaceProjects.handleSyncProject(),
+    }),
+    [nameSpace, workspaceProjects]
+  );
+
+  useImperativeHandle(ref, () => viewHandle, [viewHandle]);
+
+  useEffect(() => registerAbuilderViewHandle(viewHandle), [viewHandle]);
+
   useEffect(() => {
     registerPreviewSnapshotProvider(async () => {
       return captureEditorPreviewSnapshot({
@@ -2798,10 +2836,16 @@ function ReactViewPanelInner({
         open={apiCollectionManagerOpen}
         onOpenChange={setApiCollectionManagerOpen}
         onUploadStart={(info) => {
-          emitAbuilderEvent(AbuilderEvents.apiCollectionUploadStart, info);
+          emitAbuilderEvent(AbuilderEvents.apiCollectionUploadStart, {
+            ...info,
+            nameSpace: nameSpace ?? null,
+          });
         }}
         onUploadSuccess={(info) => {
-          emitAbuilderEvent(AbuilderEvents.apiCollectionUploadSuccess, info);
+          emitAbuilderEvent(AbuilderEvents.apiCollectionUploadSuccess, {
+            ...info,
+            nameSpace: nameSpace ?? null,
+          });
         }}
         onSyncCollection={(record) => {
           const patches = buildApiCollectionSyncPatches({
@@ -2846,17 +2890,14 @@ function ReactViewPanelInner({
       <Toaster />
     </div>
   );
-}
-
-export function ReactViewPanel({
-  locale,
-  onLocaleChange,
-  nameSpace,
-  ...rest
-}: ReactViewPanelProps) {
-  return (
-    <I18nRoot locale={locale} onLocaleChange={onLocaleChange} nameSpace={nameSpace}>
-      <ReactViewPanelInner nameSpace={nameSpace} {...rest} />
-    </I18nRoot>
-  );
-}
+});
+
+export const ReactViewPanel = forwardRef<AbuilderViewHandle, ReactViewPanelProps>(
+  function ReactViewPanel({ locale, onLocaleChange, nameSpace, ...rest }, ref) {
+    return (
+      <I18nRoot locale={locale} onLocaleChange={onLocaleChange} nameSpace={nameSpace}>
+        <ReactViewPanelInner ref={ref} nameSpace={nameSpace} {...rest} />
+      </I18nRoot>
+    );
+  }
+);

package/src/panel/hooks/useWorkspaceProjects.ts

@@ -7,16 +7,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,
@@ -45,6 +45,11 @@ export type UseWorkspaceProjectsOptions = {
   onProjectApplied?: (record: WorkspaceProjectRecord) => void;
   /** 外部传入的初始工作区，挂载后自动加载（不触发 onProjectApplied） */
   initialWorkspace?: WorkspaceProjectRecord | null;
+  /**
+   * 按 IndexedDB id 打开工作区。与 `initialWorkspace` 同时存在时：
+   * 首次优先 `initialWorkspace`；之后 `workspaceId` 变化会从 IndexedDB 打开。
+   */
+  workspaceId?: string | null;
   /** 隔离 IndexedDB / 预览缓存 / 同步频道 */
   nameSpace?: string | null;
 };
@@ -103,17 +108,20 @@ export function useWorkspaceProjects({
   panelRevision,
   onProjectApplied,
   initialWorkspace,
+  workspaceId = null,
   nameSpace = null,
 }: UseWorkspaceProjectsOptions) {
   const { t } = useI18nOptional();
   const [projects, setProjects] = useState<WorkspaceProjectListItem[]>([]);
   const [activeProjectId, setActiveProjectId] = useState<string | null>(null);
   const [activeProjectName, setActiveProjectName] = useState<string | null>(null);
+  const activeCreatedAtRef = useRef<number | null>(null);
   const syncedSnapshotRef = useRef<WorkspaceSnapshot | null>(null);
   const syncedPanelRevisionRef = useRef<unknown>(null);
   const pendingRevisionSyncRef = useRef(false);
   const previewWindowsRef = useRef(new Map<string, Window>());
   const [previewingProjectIds, setPreviewingProjectIds] = useState<string[]>([]);
+  const eventNameSpace = normalizeAppNameSpace(nameSpace) || null;
 
   const refreshPreviewing = useCallback(() => {
     const ids: string[] = [];
@@ -166,7 +174,9 @@ export function useWorkspaceProjects({
     return subscribeWorkspaceProjectsChanged((message) => {
       const removedActive =
         message.type === "cleared" ||
-        (activeProjectId !== null && message.projectIds.includes(activeProjectId));
+        (message.type === "deleted" &&
+          activeProjectId !== null &&
+          message.projectIds.includes(activeProjectId));
       if (removedActive) {
         setActiveProjectId(null);
         setActiveProjectName(null);
@@ -197,8 +207,67 @@ export function useWorkspaceProjects({
     buildCurrentSnapshot,
   ]);
 
+  const ensureWorkspaceInIndexedDb = useCallback(
+    async (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);
+      }
+    },
+    [nameSpace, refreshProjects, t]
+  );
+
   const applyProjectRecord = useCallback(
-    (record: WorkspaceProjectRecord, options?: { notifyApplied?: boolean }) => {
+    (
+      record: WorkspaceProjectRecord,
+      options?: { notifyApplied?: boolean; persistToIndexedDb?: boolean }
+    ) => {
       const parsedBlueprint = parseBlueprintData(record.blueprintDocument);
       const blueprintDocument =
         parsedBlueprint.value ?? BlueprintGraph.empty().document;
@@ -221,6 +290,10 @@ export function useWorkspaceProjects({
       setTitleIconDataUrl(titleIconDataUrl);
       setActiveProjectId(record.id || null);
       setActiveProjectName(record.name ?? null);
+      activeCreatedAtRef.current =
+        typeof record.createdAt === "number" && Number.isFinite(record.createdAt)
+          ? record.createdAt
+          : Date.now();
       syncedSnapshotRef.current = cloneWorkspaceSnapshot({
         blueprintDocument,
         blueprintMeta,
@@ -229,18 +302,27 @@ export function useWorkspaceProjects({
       });
       syncedPanelRevisionRef.current = panelRevision;
       pendingRevisionSyncRef.current = true;
+      const normalized: WorkspaceProjectRecord = {
+        ...record,
+        id: record.id,
+        name: record.name ?? productName,
+        createdAt: activeCreatedAtRef.current,
+        updatedAt: record.updatedAt ?? Date.now(),
+        blueprintDocument,
+        blueprintMeta,
+        panelState,
+        productName,
+        titleIconDataUrl: titleIconDataUrl || undefined,
+      };
       if (options?.notifyApplied !== false) {
-        onProjectApplied?.({
-          ...record,
-          blueprintDocument,
-          blueprintMeta,
-          panelState,
-          productName,
-          titleIconDataUrl: titleIconDataUrl || undefined,
-        });
+        onProjectApplied?.(normalized);
+      }
+      if (options?.persistToIndexedDb) {
+        void ensureWorkspaceInIndexedDb(normalized);
       }
     },
     [
+      ensureWorkspaceInIndexedDb,
       importPanelData,
       onProjectApplied,
       setBlueprintGraph,
@@ -263,6 +345,7 @@ export function useWorkspaceProjects({
     setTitleIconDataUrl("");
     setActiveProjectId(null);
     setActiveProjectName(null);
+    activeCreatedAtRef.current = null;
     syncedSnapshotRef.current = null;
   }, [
     importPanelData,
@@ -275,23 +358,7 @@ export function useWorkspaceProjects({
 
   const initialWorkspaceAppliedKeyRef = useRef<string | null>(null);
   const bootstrappedRef = useRef(false);
-  useEffect(() => {
-    if (!bootstrappedRef.current) {
-      bootstrappedRef.current = true;
-      if (hasWorkspacePayload(initialWorkspace)) {
-        applyProjectRecord(initialWorkspace, { notifyApplied: false });
-        initialWorkspaceAppliedKeyRef.current = workspaceApplyKey(initialWorkspace);
-      } else {
-        applyEmptyWorkspace();
-      }
-      return;
-    }
-    if (!hasWorkspacePayload(initialWorkspace)) return;
-    const key = workspaceApplyKey(initialWorkspace);
-    if (initialWorkspaceAppliedKeyRef.current === key) return;
-    initialWorkspaceAppliedKeyRef.current = key;
-    applyProjectRecord(initialWorkspace, { notifyApplied: false });
-  }, [applyEmptyWorkspace, applyProjectRecord, initialWorkspace]);
+  const workspaceIdAppliedRef = useRef<string | null>(null);
 
   const persistProject = useCallback(
     async (options: { id?: string; name: string; createdAt?: number }) => {
@@ -299,7 +366,7 @@ export function useWorkspaceProjects({
         const snapshot = cloneWorkspaceSnapshot(buildCurrentSnapshot());
         const now = Date.now();
         const id = options.id ?? createWorkspaceProjectId();
-        const createdAt = options.createdAt ?? now;
+        const createdAt = options.createdAt ?? activeCreatedAtRef.current ?? now;
         const name = (options.name ?? "").trim() || resolveProjectName();
 
         let panelState: State;
@@ -325,10 +392,9 @@ export function useWorkspaceProjects({
         };
 
         await putWorkspaceProject(record, nameSpace);
-        writeWorkspacePreviewCache(record, nameSpace);
-        broadcastWorkspaceProjectUpdate(id, now, nameSpace);
         setActiveProjectId(id);
         setActiveProjectName(name);
+        activeCreatedAtRef.current = createdAt;
         syncedSnapshotRef.current = snapshot;
         syncedPanelRevisionRef.current = panelRevision;
         pendingRevisionSyncRef.current = false;
@@ -349,14 +415,49 @@ export function useWorkspaceProjects({
     ]
   );
 
+  const getCurrentWorkspaceRecord = useCallback((): WorkspaceProjectRecord | null => {
+    if (!activeProjectId) return null;
+    try {
+      const snapshot = buildCurrentSnapshot();
+      const panelState = exportPanelData();
+      const now = Date.now();
+      return {
+        id: activeProjectId,
+        name: activeProjectName || resolveProjectName(),
+        createdAt: activeCreatedAtRef.current ?? 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;
+    }
+  }, [
+    activeProjectId,
+    activeProjectName,
+    buildCurrentSnapshot,
+    exportPanelData,
+    resolveProjectName,
+  ]);
+
   const handleCreateProject = useCallback(async () => {
     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 };
     });
-  }, [persistProject, resolveProjectName, t]);
+  }, [eventNameSpace, persistProject, resolveProjectName, t]);
 
   const handleSaveProject = useCallback(async () => {
     if (!activeProjectId) {
@@ -368,17 +469,33 @@ export function useWorkspaceProjects({
       const record = await persistProject({
         id: activeProjectId,
         name,
-        createdAt: existing?.createdAt,
+        createdAt: existing?.createdAt ?? activeCreatedAtRef.current ?? undefined,
+      });
+      emitAbuilderEvent(AbuilderEvents.workspaceSync, {
+        ...record,
+        nameSpace: eventNameSpace,
       });
       return { name, id: record.id };
     });
-  }, [activeProjectId, handleCreateProject, nameSpace, persistProject, resolveProjectName, t]);
+  }, [
+    activeProjectId,
+    eventNameSpace,
+    handleCreateProject,
+    nameSpace,
+    persistProject,
+    resolveProjectName,
+    t,
+  ]);
 
   const handleOpenProject = useCallback(
-    async (id: string) => {
+    async (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"));
@@ -397,24 +514,29 @@ export function useWorkspaceProjects({
       if (!activeProjectId) {
         throw new Error(t("panel.messages.saveWorkspaceFirst"));
       }
+      // 本地无记录时 upsert，避免宿主 initialWorkspace 未落盘后同步报错
       const existing = await getWorkspaceProject(activeProjectId, nameSpace);
-      if (!existing) {
-        setActiveProjectId(null);
-        setActiveProjectName(null);
-        syncedSnapshotRef.current = null;
-        await refreshProjects();
-        throw new Error(t("panel.messages.workspaceNotFound"));
-      }
-      const name = resolveProjectName() || existing.name;
+      const name = resolveProjectName() || existing?.name || activeProjectName || "";
       const record = await persistProject({
         id: activeProjectId,
         name,
-        createdAt: existing.createdAt,
+        createdAt: existing?.createdAt ?? activeCreatedAtRef.current ?? undefined,
+      });
+      emitAbuilderEvent(AbuilderEvents.workspaceSync, {
+        ...record,
+        nameSpace: eventNameSpace,
       });
-      emitAbuilderEvent(AbuilderEvents.workspaceSync, record);
       return name;
     });
-  }, [activeProjectId, nameSpace, persistProject, refreshProjects, resolveProjectName, t]);
+  }, [
+    activeProjectId,
+    activeProjectName,
+    eventNameSpace,
+    nameSpace,
+    persistProject,
+    resolveProjectName,
+    t,
+  ]);
 
   const handleDeleteProject = useCallback(
     async (id: string) => {
@@ -424,6 +546,7 @@ export function useWorkspaceProjects({
           if (activeProjectId === id) {
             setActiveProjectId(null);
             setActiveProjectName(null);
+            activeCreatedAtRef.current = null;
             syncedSnapshotRef.current = null;
           }
           previewWindowsRef.current.delete(id);
@@ -478,6 +601,58 @@ export function useWorkspaceProjects({
     [activeProjectId, dirty, handleSyncProject, nameSpace, refreshPreviewing, t]
   );
 
+  useEffect(() => {
+    if (!bootstrappedRef.current) {
+      bootstrappedRef.current = true;
+      if (hasWorkspacePayload(initialWorkspace)) {
+        applyProjectRecord(initialWorkspace, {
+          notifyApplied: false,
+          persistToIndexedDb: true,
+        });
+        initialWorkspaceAppliedKeyRef.current = workspaceApplyKey(initialWorkspace);
+        if (initialWorkspace.id) {
+          workspaceIdAppliedRef.current = initialWorkspace.id;
+        }
+      } else if (typeof workspaceId === "string" && workspaceId.trim()) {
+        workspaceIdAppliedRef.current = workspaceId.trim();
+        void handleOpenProject(workspaceId.trim());
+      } else {
+        applyEmptyWorkspace();
+      }
+      return;
+    }
+    if (!hasWorkspacePayload(initialWorkspace)) return;
+    const key = workspaceApplyKey(initialWorkspace);
+    if (initialWorkspaceAppliedKeyRef.current === key) return;
+    initialWorkspaceAppliedKeyRef.current = key;
+    if (initialWorkspace.id) {
+      workspaceIdAppliedRef.current = initialWorkspace.id;
+    }
+    applyProjectRecord(initialWorkspace, {
+      notifyApplied: false,
+      persistToIndexedDb: true,
+    });
+  }, [
+    applyEmptyWorkspace,
+    applyProjectRecord,
+    handleOpenProject,
+    initialWorkspace,
+    workspaceId,
+  ]);
+
+  useEffect(() => {
+    if (!bootstrappedRef.current) return;
+    const id = typeof workspaceId === "string" ? workspaceId.trim() : "";
+    if (!id) return;
+    if (workspaceIdAppliedRef.current === id) return;
+    if (activeProjectId === id) {
+      workspaceIdAppliedRef.current = id;
+      return;
+    }
+    workspaceIdAppliedRef.current = id;
+    void handleOpenProject(id);
+  }, [activeProjectId, handleOpenProject, workspaceId]);
+
   return {
     projects,
     activeProjectId,
@@ -490,6 +665,7 @@ export function useWorkspaceProjects({
     handleSyncProject,
     handleDeleteProject,
     handlePreviewProject,
+    getCurrentWorkspaceRecord,
     refreshProjects,
   };
 }

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

@@ -1,10 +1,22 @@
+import { normalizeAppNameSpace } from "@arronqzy/blueprint-dsl";
 import {
   clearAllExecutionRunRecords,
-  clearApiCollections,
+  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/react-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 {
@@ -19,17 +31,36 @@ export {
   readExecutionLogSettings,
   writeExecutionLogSettings,
   listApiCollectionRecords,
-  deleteApiCollection,
-  clearApiCollections,
 } from "@arronqzy/react-blueprint";
 export type {
   BlueprintLibraryListItem,
   BlueprintLibraryRecord,
   ExecutionRunRecord,
   ExecutionLogSettings,
+  UpsertApiCollectionInput,
+  UpsertApiCollectionResult,
 } from "@arronqzy/react-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,
@@ -37,12 +68,79 @@ export async function deleteBlueprintLibraryRecord(
 ): 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;
 }
 

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();
+}

package/src/panel/library/event-subscription.ts

@@ -1,3 +1,4 @@
+import { normalizeAppNameSpace } from "@arronqzy/blueprint-dsl";
 import type { WorkspaceProjectRecord } from "./workspace-project-db";
 
 export const AbuilderEvents = {
@@ -7,10 +8,14 @@ export const AbuilderEvents = {
   workspaceSync: "workspace:sync",
   /** 删除工作区（界面删除，或调用 deleteWorkspaceProject / clearWorkspaceProjects） */
   workspaceDelete: "workspace:delete",
+  /** 蓝图库写入 / 删除 / 清空 */
+  blueprintLibraryChanged: "blueprint-library:changed",
   /** 开始上传接口集合 */
   apiCollectionUploadStart: "api-collection:upload-start",
   /** 上传接口集合成功 */
   apiCollectionUploadSuccess: "api-collection:upload-success",
+  /** 接口集合写入 / 删除 / 清空 */
+  apiCollectionChanged: "api-collection:changed",
 } as const;
 
 export type AbuilderEventName = (typeof AbuilderEvents)[keyof typeof AbuilderEvents];
@@ -18,8 +23,14 @@ export type AbuilderEventName = (typeof AbuilderEvents)[keyof typeof AbuilderEve
 /** 工作区完整数据（面板 + 蓝图），可用于外部持久化与再次加载 */
 export type WorkspaceData = WorkspaceProjectRecord;
 
-export type WorkspaceAddEventPayload = WorkspaceData;
-export type WorkspaceSyncEventPayload = WorkspaceData;
+export type WorkspaceAddEventPayload = WorkspaceData & {
+  /** 所属 nameSpace，默认库为 null */
+  nameSpace: string | null;
+};
+export type WorkspaceSyncEventPayload = WorkspaceData & {
+  /** 所属 nameSpace，默认库为 null */
+  nameSpace: string | null;
+};
 export type WorkspaceDeleteEventPayload = {
   /** 被删除的工作区 id */
   ids: string[];
@@ -27,9 +38,17 @@ export type WorkspaceDeleteEventPayload = {
   nameSpace: string | null;
 };
 
+export type BlueprintLibraryChangedEventPayload = {
+  nameSpace: string | null;
+  action: "put" | "delete" | "clear";
+  /** 涉及的蓝图 id；clear 时可能为空 */
+  ids?: string[];
+};
+
 export type ApiCollectionUploadStartEventPayload = {
   fileNames: string[];
   count: number;
+  nameSpace: string | null;
 };
 
 export type ApiCollectionUploadSuccessEventPayload = {
@@ -39,20 +58,57 @@ export type ApiCollectionUploadSuccessEventPayload = {
     apiCount: number;
     persistLocal: boolean;
   }>;
+  nameSpace: string | null;
+};
+
+export type ApiCollectionChangedEventPayload = {
+  nameSpace: string | null;
+  action: "put" | "delete" | "clear";
+  ids?: string[];
 };
 
 export type AbuilderEventPayloadMap = {
   [AbuilderEvents.workspaceAdd]: WorkspaceAddEventPayload;
   [AbuilderEvents.workspaceSync]: WorkspaceSyncEventPayload;
   [AbuilderEvents.workspaceDelete]: WorkspaceDeleteEventPayload;
+  [AbuilderEvents.blueprintLibraryChanged]: BlueprintLibraryChangedEventPayload;
   [AbuilderEvents.apiCollectionUploadStart]: ApiCollectionUploadStartEventPayload;
   [AbuilderEvents.apiCollectionUploadSuccess]: ApiCollectionUploadSuccessEventPayload;
+  [AbuilderEvents.apiCollectionChanged]: ApiCollectionChangedEventPayload;
+};
+
+export type AddEventSubscriptionOptions = {
+  /**
+   * 仅接收该 nameSpace 的事件。
+   * 省略则接收全部；传入空字符串 / null 表示默认库。
+   */
+  nameSpace?: string | null;
 };
 
 type EventCallback = (payload: unknown) => void;
 
 const listeners = new Map<string, Set<EventCallback>>();
 
+function resolvePayloadNameSpace(payload: unknown): string | null | undefined {
+  if (!payload || typeof payload !== "object") return undefined;
+  if (!("nameSpace" in payload)) return undefined;
+  const value = (payload as { nameSpace?: unknown }).nameSpace;
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string") return value;
+  return undefined;
+}
+
+function matchesNameSpaceFilter(
+  payload: unknown,
+  filter: string | null | undefined
+): boolean {
+  if (filter === undefined) return true;
+  const wanted = normalizeAppNameSpace(filter);
+  const actual = resolvePayloadNameSpace(payload);
+  if (actual === undefined) return true;
+  return normalizeAppNameSpace(actual) === wanted;
+}
+
 export function emitAbuilderEvent<T extends AbuilderEventName>(
   eventName: T,
   payload: AbuilderEventPayloadMap[T]
@@ -70,17 +126,26 @@ export function emitAbuilderEvent<T extends AbuilderEventName>(
 
 export function addEventSubscription<T extends AbuilderEventName>(
   eventName: T,
-  callback: (payload: AbuilderEventPayloadMap[T]) => void
+  callback: (payload: AbuilderEventPayloadMap[T]) => void,
+  options?: AddEventSubscriptionOptions
 ): { unsubscribe: () => void } {
   let set = listeners.get(eventName);
   if (!set) {
     set = new Set();
     listeners.set(eventName, set);
   }
-  set.add(callback as EventCallback);
+  const filter =
+    options && Object.prototype.hasOwnProperty.call(options, "nameSpace")
+      ? options.nameSpace
+      : undefined;
+  const wrapped: EventCallback = (payload) => {
+    if (!matchesNameSpaceFilter(payload, filter)) return;
+    callback(payload as AbuilderEventPayloadMap[T]);
+  };
+  set.add(wrapped);
   return {
     unsubscribe: () => {
-      set.delete(callback as EventCallback);
+      set.delete(wrapped);
       if (set.size === 0) {
         listeners.delete(eventName);
       }

package/src/panel/library/workspace-project-sync.ts

@@ -11,6 +11,7 @@ export type WorkspaceProjectSyncMessage = {
 
 export type WorkspaceProjectsChangedMessage =
   | { type: "deleted"; projectIds: string[] }
+  | { type: "upserted"; projectIds: string[] }
   | { type: "cleared" };
 
 export function broadcastWorkspaceProjectsChanged(
@@ -33,7 +34,12 @@ export function subscribeWorkspaceProjectsChanged(
   const channel = new BroadcastChannel(appStorageKey(LIST_CHANNEL, nameSpace));
   channel.onmessage = (event: MessageEvent<WorkspaceProjectsChangedMessage>) => {
     const data = event.data;
-    if (!data || (data.type !== "deleted" && data.type !== "cleared")) return;
+    if (
+      !data ||
+      (data.type !== "deleted" && data.type !== "cleared" && data.type !== "upserted")
+    ) {
+      return;
+    }
     onChange(data);
   };
   return () => channel.close();

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

@@ -4,16 +4,70 @@ import {
   deleteWorkspaceProject as deleteWorkspaceProjectRecord,
   getWorkspaceProject,
   listWorkspaceProjects,
+  putWorkspaceProject as putWorkspaceProjectRecord,
+  type WorkspaceProjectRecord,
 } from "./workspace-project-db";
 import {
   clearWorkspacePreviewCaches,
   removeWorkspacePreviewCache,
+  writeWorkspacePreviewCache,
 } from "./workspace-project-cache";
-import { broadcastWorkspaceProjectsChanged } from "./workspace-project-sync";
+import {
+  broadcastWorkspaceProjectUpdate,
+  broadcastWorkspaceProjectsChanged,
+} from "./workspace-project-sync";
 import { AbuilderEvents, emitAbuilderEvent } from "./event-subscription";
 
 export { listWorkspaceProjects, getWorkspaceProject };
-export type { WorkspaceProjectListItem } from "./workspace-project-db";
+export type { WorkspaceProjectListItem, WorkspaceProjectRecord } from "./workspace-project-db";
+
+export type PutWorkspaceProjectOptions = {
+  /**
+   * 写入后是否发出工作区事件。
+   * - `false` / 省略：只写 IndexedDB（宿主自己管后端时常用）
+   * - `"add"`：发出 `workspace:add`
+   * - `"sync"`：发出 `workspace:sync`
+   */
+  emitEvent?: false | "add" | "sync";
+};
+
+function resolvedNameSpace(nameSpace?: string | null): string | null {
+  return normalizeAppNameSpace(nameSpace) || null;
+}
+
+/**
+ * 写入 / 覆盖 IndexedDB 中的工作区（upsert），并更新预览缓存、通知其他标签页。
+ * `nameSpace` 需与面板的 `nameSpace` 一致。
+ */
+export async function putWorkspaceProject(
+  record: WorkspaceProjectRecord,
+  nameSpace?: string | null,
+  options?: PutWorkspaceProjectOptions
+): Promise<WorkspaceProjectRecord> {
+  const saved = await putWorkspaceProjectRecord(record, nameSpace);
+  writeWorkspacePreviewCache(saved, nameSpace);
+  broadcastWorkspaceProjectUpdate(saved.id, saved.updatedAt, nameSpace);
+  broadcastWorkspaceProjectsChanged(
+    { type: "upserted", projectIds: [saved.id] },
+    nameSpace
+  );
+  const ns = resolvedNameSpace(nameSpace);
+  if (options?.emitEvent === "add") {
+    emitAbuilderEvent(AbuilderEvents.workspaceAdd, { ...saved, nameSpace: ns });
+  } else if (options?.emitEvent === "sync") {
+    emitAbuilderEvent(AbuilderEvents.workspaceSync, { ...saved, nameSpace: ns });
+  }
+  return saved;
+}
+
+/** `putWorkspaceProject` 的别名 */
+export async function upsertWorkspaceProject(
+  record: WorkspaceProjectRecord,
+  nameSpace?: string | null,
+  options?: PutWorkspaceProjectOptions
+): Promise<WorkspaceProjectRecord> {
+  return putWorkspaceProject(record, nameSpace, options);
+}
 
 /**
  * 删除 IndexedDB 中保存的单个工作区（及其 localStorage 预览标记）。
@@ -28,7 +82,7 @@ export async function deleteWorkspaceProject(
   broadcastWorkspaceProjectsChanged({ type: "deleted", projectIds: [id] }, nameSpace);
   emitAbuilderEvent(AbuilderEvents.workspaceDelete, {
     ids: [id],
-    nameSpace: normalizeAppNameSpace(nameSpace) || null,
+    nameSpace: resolvedNameSpace(nameSpace),
   });
 }
 
@@ -44,7 +98,7 @@ export async function clearWorkspaceProjects(nameSpace?: string | null): Promise
   if (items.length > 0) {
     emitAbuilderEvent(AbuilderEvents.workspaceDelete, {
       ids: items.map((item) => item.id),
-      nameSpace: normalizeAppNameSpace(nameSpace) || null,
+      nameSpace: resolvedNameSpace(nameSpace),
     });
   }
   return items.length;