wechen-agent-editor-v1 1.0.7 → 1.1.0

package/README.md

@@ -1,298 +1,259 @@
 # wechen-agent-editor-v1
 
-**wechen-agent-editor-v1** 是一个可发布的 **Agent 流程编排编辑器** React 组件库：**画布上的图语义为可执行的 AI 流程**——**节点** 表示 **功能模块**，**连线** 表示 **执行顺序 / 控制流**（不是仅画关系图）；持久化的 `flow` 供宿主 **运行时或执行引擎** 消费。技术形态为左侧组件库（**可拖入画布**）、中间 **@xyflow/react** 画布、右侧 **节点 / 连线** 配置（antd + **Monaco Editor** 编辑 System Prompt 等）。适用于在宿主应用中嵌入「可执行 Agent / MCP 编排」类界面。
+面向宿主应用的 **Agent 流程编排编辑器** React 组件：左侧可拖入的组件库、中间 **@xyflow/react** 画布、右侧基于 **antd** 与 **Monaco** 的配置区。图上的 **节点** 表示功能模块，**边** 表示执行顺序；持久化的 `flow` 可由你的运行时或执行引擎消费。
 
-> **npm 包名**：安装与 `import` 路径均以仓库根目录 **`package.json` 的 `name`** 为准（当前为 **`wechen-agent-editor-v1`**）。历史文档或内部示例若出现 **`@li/wechen-agent`**，请视为**曾用别名**，以 `package.json` 为准。
+**包名**：以 `package.json` 的 `name` 为准（`wechen-agent-editor-v1`）。安装与 `import` 均使用该名称。
 
-> **BREAKING（包名）**：若你曾使用旧包名 `my-react-antd-widget`，请改为安装本包并更新 import。  
-> **BREAKING（peer 依赖）**：自 **1.0.3** 起，`react`、`react-dom`、`antd`、`monaco-editor`、`@monaco-editor/react` 为 **`peerDependencies`**（由宿主安装）。自 **1.0.7** 起，**`@xyflow/react` 为本包 `dependencies` 且列入 `bundledDependencies`**：发布 tarball 内会附带 **`node_modules/@xyflow/react`**，宿主 **根目录 `package.json` 可不写** `@xyflow/react` 也能解析 **`dist/index.js` 中的 import**（利于 Umi MFSU 等场景）。若宿主**另有**直接使用 **`@xyflow/react`** 的页面，请用 **`npm ls`** 与 **`resolve.alias`** 避免 **双份 xyflow 运行时**。请见下文「依赖（安装）」与「排查」。  
-> **BREAKING（Monaco）**：需在宿主入口配置 **Monaco worker**（见下文）。  
-> **BREAKING（initialFlow）**：未传 `initialFlow` 时为 **空画布**（无内置示例节点）。若依赖旧版「零配置即出现示例图」，请显式传入 `initialFlow={cloneWechenAgentFlow(defaultInitialFlow)}`（需同时 import `cloneWechenAgentFlow` 与 `defaultInitialFlow`）。
+## 快速开始
 
+### 60 秒最小集成（L0）
 
-## 依赖（安装）
+只需 **`onSave`** 与 antd **`ConfigProvider`**，并保证父容器有高度（例如 `height: 100%` 链或 `100vh`）。未传 **`initialFlow`** 时为**空画布**（与编辑器默认一致）。
 
-本包将 **`react`、`react-dom`、`antd`、`monaco-editor`、`@monaco-editor/react`** 声明为 **`peerDependencies`**（须由宿主安装）。**`@xyflow/react`** 在 **`dependencies`** 且 **`bundledDependencies`**：安装 **`wechen-agent-editor-v1`** 时 npm 会把 **`@xyflow/react`** 放进 **`node_modules/wechen-agent-editor-v1/node_modules/`**（与 **`dist/index.js` 中的 import** 配套）。**仅使用本编辑器** 时宿主 **可不**在根 `package.json` 写 **`@xyflow/react`**。**请保证宿主只解析到一份 `react` / `react-dom` / `antd` / `monaco-editor` 链**；若宿主**另有**自行引用 **`@xyflow/react`** 的代码，注意 **不要形成两套 Flow 运行时**。
-
-```bash
-npm install wechen-agent-editor-v1
-```
-
-- **npm 7+** 安装本包时，一般会 **自动安装缺失的 peer**；仍建议在宿主 `package.json` 中 **显式列出** 上述依赖及版本，便于与业务线对齐并避免重复副本。
-- 版本范围以 **`peerDependencies`** 为准；建议 **React 18+**、**`antd` 5+**；**`@xyflow/react`** 版本随本包 **`dependencies` / `bundledDependencies`** 锁定（与 **`npm pack` 内容**一致）。
-
-### 宿主 `npm install wechen-agent-editor-v1` 报 `ERESOLVE`
-
-npm 7+ 会对 **整棵依赖树**做严格 peer 校验；安装 **`wechen-agent-editor-v1`** 往往只是 **触发一次完整解析**，冲突可能来自 **宿主里早已存在的包**，**不一定与本包 `peerDependencies` 声明矛盾**。
-
-**与本 issue 一致的两类典型冲突**（看 `npm install` 日志里 **While resolving …** 指向谁）：
-
-| 类型 | 常见表现 | 建议先做的排查 |
-|------|----------|----------------|
-| **`@ant-design/pro-chat` ↔ `antd-style`** | 例如 pro-chat 声明 **`antd-style@^3`**，宿主已用 **`antd-style@^4`** | 在 [npm @ant-design/pro-chat](https://www.npmjs.com/package/@ant-design/pro-chat?activeTab=versions) 查各版本 **peerDependencies**；宿主执行 **`npm ls @ant-design/pro-chat antd-style`** |
-| **`@ahooksjs/use-request`（经 `ahooks` / `@umijs/plugins`）↔ React 18** | peer 仍写 **`react@^16 \|\| ^17`** 等 | **`npm why @ahooksjs/use-request`**；**`npm ls ahooks react`**；按 Umi / ahooks 官方说明 **升级 ahooks 或相关插件** |
-
-**「临时 unblock」与「根治」**（勿与下文「多份 React」混淆——那是 **安装成功后运行时** 的问题）：
-
-| 阶段 | 做法 | 说明 |
-|------|------|------|
-| **临时** | `npm install wechen-agent-editor-v1@<version> --legacy-peer-deps`，或宿主根目录 **`.npmrc`**：`legacy-peer-deps=true` | 仅放宽 **peer 解析**，**不替代**你在 `package.json` 里对本包要求的 **`react` / `antd` / `monaco-editor` / …** 的显式声明；上线前请在宿主跑 **`npm run build`**（或 `max build`）并记录技术债 |
-| **根治** | **升级** `@ant-design/pro-chat` 等到与 **`antd-style@4`** 兼容的组合；或 **升级 ahooks / Umi 链** 与 React 18 一致；必要时再用 **`overrides`**（见下折叠示例） | 对齐后应 **去掉** `legacy-peer-deps`，避免长期掩盖不兼容 |
-
-**与「排查：第一次从组件库拖入正常…」的区别**：本节解决 **`npm install` 失败（ERESOLVE）**；该小节解决 **装得上但画布异常**（多为 **多份 `react`**、**样式未进包**，或 **宿主另引 `@xyflow/react` 与本包内置副本冲突**）。
-
-<details>
-<summary><strong>可选：<code>package.json</code> <code>overrides</code> 示例（npm）</strong> — 仅作参考，须按宿主实际包名与版本调整；优先升级上游</summary>
-
-`overrides` 会 **强制子依赖解析版本**，可能掩盖真实不兼容；合并前请在 **关键页面 + CI build** 验证。
+```tsx
+import { ConfigProvider } from "antd";
+import { WechenAgentEditor } from "wechen-agent-editor-v1";
+// 若生产构建后缺少 Flow 全局样式，再增加：import "wechen-agent-editor-v1/style.css";
 
-```json
-{
-  "overrides": {
-    "@ahooksjs/use-request": "^2.0.0"
-  }
+export function AgentPage() {
+  return (
+    <ConfigProvider>
+      <div style={{ height: "100vh" }}>
+        <WechenAgentEditor onSave={(s) => console.log("flow", s.flow)} />
+      </div>
+    </ConfigProvider>
+  );
 }
 ```
 
-上例中的版本号 **仅为占位**——请替换为你们团队已在 **React 18 + 当前 Umi** 下验证过的版本。涉及 **`@ant-design/pro-chat` 与 `antd-style`** 时，更稳妥的路径通常是 **升级 pro-chat** 或按官方矩阵统一 `antd-style` 大版本，而不是长期用 overrides「硬拧」peer。
+### 常用配置一条对象（L1）
 
-</details>
+标题、初始流、只读、以及在**默认组件库**上按条目打补丁，可用 **`buildWechenAgentEditorProps`** 一次展开为 `WechenAgentEditor` 的 props（类型见包内导出）。
 
-### Umi Max（`@umijs/max`）/ Ant Design Pro 类宿主适配清单
-
-以下在本仓库 **无法替你改宿主 `package.json`**，但按此清单在 **业务前端仓库**（如 `iccp-frontend`）操作，可稳定接入 **`wechen-agent-editor-v1`**。
+```tsx
+import { ConfigProvider } from "antd";
+import {
+  WechenAgentEditor,
+  buildWechenAgentEditorProps,
+  cloneWechenAgentFlow,
+  COMPONENT_LIBRARY_GROUP_APP,
+  defaultInitialFlow,
+} from "wechen-agent-editor-v1";
 
-1. **在宿主 `dependencies` 中显式加入**（版本可按团队锁定微调，须满足本包 `peerDependencies`）：
+const editorProps = buildWechenAgentEditorProps({
+  title: "我的流程",
+  initialFlow: cloneWechenAgentFlow(defaultInitialFlow),
+  readOnly: false,
+  library: {
+    preset: "default",
+    itemPatches: [
+      { groupKey: COMPONENT_LIBRARY_GROUP_APP, itemKey: "alert", patch: { subtitle: "自定义副标题" } },
+    ],
+  },
+  onSave: (s) => console.log("flow", s.flow),
+});
 
-```json
-{
-  "@monaco-editor/react": "^4.6.0",
-  "wechen-agent-editor-v1": "^1.0.7"
+export function AgentPage() {
+  return (
+    <ConfigProvider>
+      <div style={{ height: "100vh" }}>
+        <WechenAgentEditor {...editorProps} />
+      </div>
+    </ConfigProvider>
+  );
 }
 ```
 
-若宿主 **另有**页面直接使用 **`@xyflow/react`**，可再显式加入 **`@xyflow/react`**，并与本包 **`dependencies` 中版本** 对齐，避免 **双实例**。宿主已声明的 **`react`、`react-dom`、`antd`、`monaco-editor`** 请保持 **单版本**；**`@monaco-editor/react` 与 `monaco-editor` 主版本** 请对照 [@monaco-editor/react 说明](https://github.com/suren-atoyan/monaco-react) 与当前 `monaco-editor` 一致。
+**高级扩展**（自定义画布节点、右侧配置面板、组件库列表映射、顶栏按钮等）仍使用完整 **`WechenAgentEditorProps`**；说明见下文「行为与扩展（摘要）」与 **`src/index.ts`** 导出。
 
-2. **`npm install` 仍 `ERESOLVE`**：与上文 **「宿主 `npm install wechen-agent-editor-v1` 报 `ERESOLVE`」** 同源；典型顺序仍是 **升级 `@ant-design/pro-chat`（或统一 `antd-style` 大版本）** → **升级 / 调整 `ahooks` 与 Umi 插件链** → 最后再 **`.npmrc`**：`legacy-peer-deps=true`（并记录技术债）。
+### 后端工作流 JSON（存库 / 执行 / 回显）
 
-3. **Umi / MFSU**：自 **1.0.7** 起 **`@xyflow/react` 随本包 `bundledDependencies` 一并安装到 `wechen-agent-editor-v1/node_modules`**，一般 **不再**出现 **`Cannot find module '@xyflow/react'`**（旧版见排查第 4 条）。若仍异常，可在 **`mfsu.exclude`** 中加入 **`wechen-agent-editor-v1`**、**`monaco-editor`**、**`@monaco-editor/react`**（以 [Umi MFSU](https://umijs.org/docs/api/config#mfsu) 为准）；改配置后删除项目根目录 **`.umi`** 并重启 **`max dev`**。
-   - **对照**：暂时 **`mfsu: false`** 做问题隔离。
+编辑器内部持久化形态为 **`WechenAgentFlowJson`**（React Flow 的 `nodes` / `edges` + 业务 `data`）。若后端希望 **扁平 DTO**（`flowId`、`flowName`、`nodes[].type` + `config`、`edges[].source/target` 等），请使用：
 
-4. **Monaco worker**：在 Umi 入口最早处完成 **worker 引导**（参考本仓库 `playground/src/monacoBootstrap.ts`），与是否使用 MFSU 无关。
+- **`exportBackendWorkflowJson(snapshot | flow, meta)`** → **`WechenBackendWorkflowJson`**（根字段 **`schemaVersion`** 当前为 **`"1"`**，与业务字段 **`version`** 区分）
+- **`importBackendWorkflowToFlow(dto)`** → **`WechenAgentFlowJson`**，再作为 **`initialFlow`** 或 **`ref.replaceFlow`** 回显
 
-5. **验证**：`npm ls react`、`npm ls @xyflow/react` 无双副本；`max dev` / `max build` 通过；页面内 **拖入 → 连线 → 右侧配置** 烟测。
+**有损字段**：导出会去掉 RF 运行期字段与部分边样式；导入会按边 `id` 重新分配 `sourceHandle`/`targetHandle`。详见类型 **`WechenBackendWorkflowJson`** 的 JSDoc。
 
-### 排查：第一次从组件库拖入正常，之后无法连线 / 无法再拖 / 样式怪
+```tsx
+import {
+  WechenAgentEditor,
+  exportBackendWorkflowJson,
+  importBackendWorkflowToFlow,
+} from "wechen-agent-editor-v1";
 
-1. **多份 React / 多份 @xyflow**（最常见）：在宿主项目根目录执行 **`npm ls react`**、**`npm ls @xyflow/react`**，若出现 **多个版本** 或嵌套在 **`wechen-agent-editor-v1/node_modules` 下又一份**，请删除锁文件后重装，或在 **Vite** 中配置 **`resolve.dedupe: ['react', 'react-dom', '@xyflow/react']`**，或调整 **pnpm overrides / npm overrides** 强制单版本。
-2. **样式未进生产包**：若打包后 **完全无 Flow 样式**，可兜底增加一行：  
-   `import "wechen-agent-editor-v1/style.css"`（本包 **`exports`** 已导出 **`./style.css` → `dist/style.css`**）。
-3. **Monaco**：未配 worker 时编辑区异常，一般 **不影响** 画布连线；请先排除 1、2。
-4. **Umi 运行时报 `Cannot find module '@xyflow/react'`**（**1.0.7 之前版本**）：本包曾将 **`@xyflow/react`** 仅作 **peer**，MFSU 预编译 **`wechen-agent-editor-v1`** 时易触发；请 **升级到 `wechen-agent-editor-v1@^1.0.7`**（含 **`bundledDependencies`**），或按旧版文档在宿主声明 **`@xyflow/react`** 并配置 **`mfsu.exclude`**。
+<WechenAgentEditor
+  onSave={(s) => {
+    const dto = exportBackendWorkflowJson(s, {
+      flowId: "agent_flow_001",
+      workflowVersion: "1.0",
+    });
+    void fetch("/api/flows", {
+      method: "POST",
+      body: JSON.stringify(dto),
+      headers: { "Content-Type": "application/json" },
+    });
+  }}
+/>;
+
+// 回显：从接口取 dto 后
+const flow = importBackendWorkflowToFlow(dtoFromApi);
+// <WechenAgentEditor initialFlow={flow} />
+```
 
-### 从包导入（ESM）
+本仓库 **playground** 提供对照：`npm run dev:minimal` 为最小页；默认 `npm run dev` 为带场景 JSON 与工具栏的完整演示（见 `playground/README.md`）。
 
-本包以 **ESM** 发布（`package.json` 的 `exports["."].import`）。构建会把 **React Flow 全局样式**打进 **`dist/style.css`**；自 **1.0.6** 起，**`npm run build`** 产出的 **`dist/index.js`** 会在文件首行包含 **`import './style.css'`**（由 `vite.config.ts` 在构建收尾写入），以便宿主打包器随主入口拉取 Flow 全局样式。自 **1.0.7** 起，**`@xyflow/react` 通过 `bundledDependencies` 随 tarball 提供**（**`dist/index.js` 仍 `import` 该包名**，由解析落到 **`wechen-agent-editor-v1/node_modules/@xyflow/react`**）。若你的打包链 **不处理** 依赖包内的该 `import`，请仍使用兜底：**`import "wechen-agent-editor-v1/style.css"`**。宿主 **无需**再写 `@xyflow/react/dist/style.css`。典型写法：
+---
 
-```ts
-import {
-  WechenAgentEditor,
-  cloneWechenAgentFlow,
-  defaultInitialFlow,
-  type WechenAgentEditorRef,
-  type WechenAgentSnapshot,
-} from "wechen-agent-editor-v1";
+## 安装
+
+```bash
+npm install wechen-agent-editor-v1
 ```
 
-**主要导出一览**（完整列表以 `src/index.ts` 为准）：
+### Peer 依赖（须由宿主安装）
 
-| 类别 | 示例符号 |
-|------|-----------|
-| 组件 | `WechenAgentEditor` |
-| Ref / 快照 / Flow | `WechenAgentEditorRef`, `WechenAgentSnapshot`, `WechenAgentFlowJson` |
-| 顶栏自定义 | `WechenAgentHeaderActionsRenderContext`（与 `renderHeaderActions` 搭配） |
-| 右侧配置扩展 | `WechenAgentRenderConfigPanelFn`、`WechenAgentConfigPanelContext` 等 |
-| 组件库 | `getDefaultComponentLibraryGroups`、`COMPONENT_LIBRARY_GROUP_MAIN`、动态 `appendComponentToLibrary` … |
-| Flow 工具 | `cloneWechenAgentFlow`、`parseWechenAgentFlowJson`、`mergeNodeData`、`emptyInitialFlow` … |
-| 拖放协议 | `WECHEN_AGENT_FLOW_DRAG_MIME`、`encodePaletteDragPayload` … |
+`react`、`react-dom`、`antd`（建议 5+）、`monaco-editor`、`@monaco-editor/react`。请在 `package.json` 中显式声明并与业务栈版本对齐。
 
-### 样式
+**`@xyflow/react`** 已作为本包的 **`dependencies`** 且列入 **`bundledDependencies`**，会安装到 `node_modules/wechen-agent-editor-v1/node_modules/@xyflow/react`，与 `dist/index.js` 中的引用配套。仅嵌入本编辑器时，宿主根目录 **不必**再单独安装 `@xyflow/react`。若项目中 **另有**直接使用 `@xyflow/react` 的代码，请用 `npm ls @xyflow/react` 与打包器的 `resolve`/别名保证 **单实例**，避免两套 Flow 运行时。
 
-- **React Flow**：样式在 **`dist/style.css`**，随 **`import "…/wechen-agent-editor-v1"`**（或包名根路径）一并生效。若生产环境仍无样式，请确认宿主打包器 **会处理依赖包里的 `import "./style.css"`**；仍不行时使用兜底：**`import "wechen-agent-editor-v1/style.css"`**。
-- **Ant Design**：antd 5 为 **CSS-in-JS**，随组件在运行时注入；请使用 **`ConfigProvider`** 包裹（与官方用法一致），并避免 **重复多份 `antd`** 导致样式异常。
+### 安装失败（`ERESOLVE`）
 
-Monaco 由 `@monaco-editor/react` 加载；**worker 需在宿主侧配置**，否则编辑器无法初始化。可选方式：
+npm 7+ 会校验整棵依赖树的 peer。冲突常来自宿主已有包，未必与本包声明矛盾。优先：**升级**冲突链上的上游（如 Pro 组件、ahooks、Umi 插件）使 peer 与 React 18 一致。临时可 **`npm install wechen-agent-editor-v1 --legacy-peer-deps`** 或在宿主 `.npmrc` 使用 `legacy-peer-deps=true`（上线前务必用 `npm run build` 验证，并计划去掉该放宽）。
 
-1. **Vite**：在入口最早执行处设置 `MonacoEnvironment` 并使用 `monaco-editor/.../editor.worker?worker` 等（参考本仓库 `playground/src/monacoBootstrap.ts`）。  
-2. **官方文档**：[Monaco Editor](https://github.com/microsoft/monaco-editor) 与 [@monaco-editor/react](https://github.com/suren-atoyan/monaco-react) 中的 Vite / Webpack 说明。
+### Umi / MFSU
 
-## 使用示例
+一般可直接使用。若遇预编译或模块解析异常，可在配置里将 **`wechen-agent-editor-v1`**、**`monaco-editor`**、**`@monaco-editor/react`** 加入 **`mfsu.exclude`**（见 [Umi MFSU](https://umijs.org/docs/api/config#mfsu)），删除 `.umi` 后重启；或用 **`mfsu: false`** 做对比排查。
 
-```tsx
-import { ConfigProvider } from "antd";
-import {
-  WechenAgentEditor,
-  type WechenAgentSnapshot,
-} from "wechen-agent-editor-v1";
+**依赖示例**（版本请按团队锁定，须满足本包 `peerDependencies`）：
 
-export function AgentPage() {
-  return (
-    <ConfigProvider>
-      <WechenAgentEditor
-        title="Agent 编辑"
-        onSave={(s: WechenAgentSnapshot) => {
-          /* 持久化 s.nodes / s.edges */
-        }}
-        onTestRun={(s) => {
-          /* 触发试运行 */
-        }}
-      />
-    </ConfigProvider>
-  );
+```json
+{
+  "dependencies": {
+    "@monaco-editor/react": "^4.6.0",
+    "wechen-agent-editor-v1": "^1.1.0"
+  }
 }
 ```
 
-未传 `initialFlow` 时画布为空；需要旧版内置示例图见上文 **BREAKING（initialFlow）** 一行。
+---
 
-**画布连线**：在节点上从 **source** Handle 拖到 **target** Handle 可新建边；**新建边默认带流动动画**（`defaultEdgeOptions`）。选中 **节点** 时右侧为「节点配置」；选中 **连线** 时右侧为「连线配置」，可开关 **动画**、选择 **正向/反向** 流动（`edge.data.wechenFlowDirection`）、编辑可选 **文字标签**，并有 **重连 / Delete 删除** 说明。
+## 使用
 
-**节点 data 合并**：表单与 `renderNodeConfig` 回写使用 **`mergeNodeData`**（亦导出）：嵌套 **对象** 深度合并；**数组** 字段在补丁中出现时 **整段替换**（`Form.List` 常见行为）。自定义 `data` 请保持可 JSON 化。
+### 入口与样式
 
-**`patchNode` / `patchNodeData` 形状**（与 `mergeNodeData` 的 `patch` 一致）：
+```ts
+import { WechenAgentEditor, type WechenAgentSnapshot } from "wechen-agent-editor-v1";
+```
+
+发布产物中 **`dist/index.js`** 会包含对 **`./style.css`** 的引用，正常情况下图样式会随主入口进入打包结果。若生产环境仍看不到 Flow 全局样式，可增加：
 
-- **`patch` 表示 `node.data` 上的部分字段**，不是整颗 `Node`；**一次调用可传多个顶层键**（统一保存多字段），例如：  
-  `patchNode({ label: "x", config: { a: 1 } })` → 同时更新 `data.label` 并对 `data.config` 做深度合并。
-- **嵌套对象**：`patchNode({ config: { a: 1 } })` 与已有 `data.config` 按 `mergeNodeData` 规则合并，未出现在补丁里的兄弟键保留（除非被空值覆盖）。
-- **何时才用 `patch` 里的 `data` 键**：仅当你的业务模型里 **`node.data` 下确有名 `data` 的嵌套对象** 时，才使用 `patchNode({ data: { ... } })`；否则该写法更新的是 **`node.data.data.*`**，容易与「把整个业务 payload 放进 `data` 键」的误解混淆。
+```ts
+import "wechen-agent-editor-v1/style.css";
+```
 
-**`patchNode` / `patchNodeData` 与 `patchEdge` 作用层级**：
+antd 5 为 CSS-in-JS，请用 **`ConfigProvider`** 包裹应用（与官方用法一致）。
 
-- **节点**：`patchNode`（右侧统一配置）与 ref 的 **`patchNodeData(nodeId, patch)`** 都是把 `patch` **合并进 `node.data`**。`patch` 的**顶层键就是 `data` 上的键**，例如 `patchNode({ label: "标题" })` 只改 `node.data.label`，不会替换整颗节点，也不会动 `id` / `type` / `position`。可一次传入多键：`patchNode({ label, foo: 1 })`。嵌套用 `patchNode({ config: { a: 1 } })`（与 `mergeNodeData` 深度合并规则一致）。**不要**误以为需要写成 `patchNode({ data: { label } })` 才能写进 data——那种写法表示更新的是 **`node.data.data.label`**（仅当你的业务字段里真的有一层名叫 `data` 的对象时才对）。
-- **边**：`patchEdge` 将 **`Partial<Edge>` 浅合并到边对象顶层**（如 `animated`、`label`），与节点 `data` 不是同一套模型。
+### 嵌入尺寸、`readOnly` 与 `readingMode`
 
-**统一右侧配置 `renderConfigPanel`**（可选）：单一函数同时覆盖 **节点** 与 **连线** 右侧栏。入参为判别联合 `kind: "node" | "edge"`，并提供 **`patchNode`** / **`patchEdge`**，由宿主决定何时调用（不必依赖 Form 即时合并）。对某一选中态返回 **`undefined`** 时回退内置「节点配置」或「连线配置」。与 `renderNodeConfig` 同时传入时，**`renderConfigPanel` 优先**（仅当其对当前选中返回 `undefined` 时再走内置）。类型见导出的 `WechenAgentRenderConfigPanelFn`、`WechenAgentConfigPanelContext`。
+根组件默认 **`height` / `width` 为 `100%`**，可通过 **`className` / `style`** 透传；可选 **`minHeight`**。请保证父级链路上有**明确高度**（如 flex 子项 `flex:1` + `minHeight:0`、固定 `height` 等），否则中间画布可能无法撑满。
 
-**顶栏右侧自定义 `renderHeaderActions`**（可选）：替换顶栏 **右侧** 的「保存」「测试运行」按钮区（左侧 CRAFT 标签与标题不变）。入参为 **`WechenAgentHeaderActionsRenderContext`**：
+- **`readOnly`**：禁止对图的增删改（拖入、连线、删除键、拖动节点等），仍可使用平移/缩放查看。**`readOnly`** 与 **`readingMode`** 会出现在 **`renderConfigPanel` / `renderNodeConfig`** 的入参中，便于对表单设 **`disabled`**。
+- **`readingMode`**：**仅展示中间流程画布**（隐藏顶栏与左右栏），并**禁用选中**与一切改图，适合文档内嵌、大屏预览等纯展示场景（隐含只读）。
 
-- **`save`** / **`testRun`**：与默认按钮、`ref.save()` / `ref.testRun()` 相同，会触发 **`onSave` / `onTestRun`**（若已传入）。
-- **`editorRef`**：与 `<WechenAgentEditor ref={...} />` 为 **同一 ref 对象**（推荐使用对象 `useRef`），可在自定义工具条中调用 **`getSnapshot`**、`patchNodeData`、`fitView` 等任意 ref API。挂载完成前 **`current` 可能为 `null`**，请在点击回调或 `useEffect` 内使用。
+### 删除守卫（`onBeforeRemoveNode` / `onBeforeRemoveEdge`）
 
-未传 `renderHeaderActions` 时保持默认两个按钮。传入后若返回 **`null` / `undefined`**，右侧 **不显示任何内容**（也不显示默认按钮）；若需要默认 UI，请勿传该 prop。
+在可编辑模式下，可通过回调 **按节点/边粒度** 决定是否允许删除。同步返回 **`false`** 时取消该次删除（**Backspace** 与 **`ref.removeNode` / `ref.removeEdge`** 均生效）。**`readOnly` / `readingMode`** 下不调用回调。删除节点时 **级联移除** 的关联边 **不会** 逐条触发 `onBeforeRemoveEdge`。
 
 ```tsx
-import { Button, Space } from "antd";
-import type { WechenAgentHeaderActionsRenderContext } from "wechen-agent-editor-v1";
-
 <WechenAgentEditor
-  renderHeaderActions={(ctx: WechenAgentHeaderActionsRenderContext) => (
-    <Space>
-      <Button onClick={ctx.save}>Save</Button>
-      <Button type="primary" onClick={ctx.testRun}>
-        Test run
-      </Button>
-    </Space>
-  )}
+  onBeforeRemoveNode={(node) => {
+    // 例：禁止删除入口节点，或 data.deletable === false 的节点
+    if (node.id === "start_node") return false;
+    if (node.data?.deletable === false) return false;
+    return true;
+  }}
+  onBeforeRemoveEdge={(edge) => edge.data?.locked !== true}
 />
 ```
 
-宿主入口需在渲染编辑器 **之前** 完成 Monaco worker 引导（见 `playground/src/main.tsx` 与 `monacoBootstrap.ts`）。
+L1 工厂同样支持：`buildWechenAgentEditorProps({ onBeforeRemoveNode: ... })`。
 
-## 本地开发（维护本仓库）
+### 四边感应区连线（默认）
 
-```bash
-npm install
-npm install --prefix playground
-npm run dev
-```
-
-浏览器打开终端提示的地址（默认 `http://localhost:5173`）。
+内置 **`pill` / `card` / `mainAgent`** 在未使用 **`renderFlowNode`**、且未启用下文 **legacy `flowHandles`** 时，采用 **上 / 右 / 下 / 左** 周界窄条（**四条始终挂载**，无上/下连线锚点时仍保留空条带便于发现）：**输入池 = 左 ∪ 上**（`target`）、**输出池 = 右 ∪ 下**（`source`）；边稳定排序后 **前半入左、后半入上**，出边 **前半出右、后半出下**；**`in-new-{nodeId}`** 默认在 **左侧**，**`out-new-{nodeId}`** 在 **右侧**；角区留白避免相邻带重叠命中。透明 **`Handle`**、无固定圆点桩 UI。新边 **`sourceHandle` / `targetHandle`** 仍为 **`out-${edgeId}`** / **`in-${edgeId}`**；**`normalizeWechenAgentFlowJson`** 归一化旧桩 id，并将遗留 **`data.wechenFlowDirection: 'reverse'`** 归一为 **交换 `source`/`target`** 后清除该键。新建连线会写入 **`edge.data.wechenSourceAttachSide` / `wechenTargetAttachSide`**（默认 **右→左**），用于稳定落回感应带；亦可手写 **`top`/`bottom`** 等偏好。**`ConnectionMode.Strict`**、**`isValidConnection`**（禁自环）。默认边 **平滑阶梯 + 终点箭头**（箭头在 **target** 端）。
 
-## 构建与发布到 npm
+周界四向感应的 **完整方案说明（交互、角区、数据字段、代码映射）** 见仓库 **`openspec/changes/node-perimeter-sensing-scheme/design.md`**。
 
-以下面向 **维护者** 与 **CI**。**npm 包名、版本号** 以仓库根目录 **`package.json` 的 `name` / `version`** 为唯一权威（当前包名为 **`wechen-agent-editor-v1`**），请勿依赖本文档中可能出现的示例数字。
+### 组件库 legacy 接线桩（`flowHandles`，可选）
 
-### 发布前自检
+**已弃用优先**：编排默认以 **四边感应区** 为准。**`libraryGroups`** 中每项仍可设置 **`flowHandles`** 以兼容旧版「声明桩位」：`FlowHandleSpec[]` 或 **`mode: 'even'`** 自动均分。拖入后写入 **`data.flowHandles`**；**`card` / `mainAgent`** 在 **`flowHandles` 展开非空** 时仍走声明桩渲染。**`renderFlowNode`** 自定义整节点时由宿主自行决定接线方式。类型见 **`expandFlowHandlesConfig`**、**`findComponentLibraryItem`** 等导出。
 
-1. **依赖**：在仓库根目录执行 `npm install`（或 CI 使用 `npm ci`），确认 `dependencies` 可解析；宿主若额外安装 React 等，注意与上文版本范围兼容（见「依赖（安装）」）。
-2. **构建**：`npm run build` 成功，生成 `dist/index.js` 与 `dist/index.d.ts`。
-3. **打包内容**：`npm run pack:check`（即 `npm pack --dry-run`）确认仅包含 `package.json` **`files`** 声明的内容（当前为 **`dist`** 与 **`LICENSE`**），无意外把 `playground` 或源码打进包。
-4. **测试**（建议）：`npm test`（Vitest，见 `src/**/*.test.ts`）。
-5. **版本号**：在 `package.json` 提升 **`version`**（语义化：**`MAJOR`** 不兼容 API、**`MINOR`** 向后兼容功能、**`PATCH`** 修订）。若需预览版可使用 **0.x** 或预发布标签（如 `-beta`），并在变更说明中写明。若团队维护变更说明，可同步更新 **CHANGELOG**（本仓库未强制附带该文件）。
+### Monaco Worker
 
-**根目录一键执行（建议顺序）**：
+必须在**首次渲染编辑器之前**完成 Monaco worker 引导，否则代码编辑区无法初始化。可参考本仓库 **`playground/src/monacoBootstrap.ts`** 与 **`playground/src/main.tsx`**，并按 [Monaco](https://github.com/microsoft/monaco-editor) / [@monaco-editor/react](https://github.com/suren-atoyan/monaco-react) 文档适配 Vite 或 Webpack。
 
-```bash
-npm install
-npm run build
-npm test
-npm run pack:check
-```
+### 与快速开始一致的最小页（可选 `title`）
 
-### 宿主入口与构建产物
+与上文 **L0** 相同；若需要顶栏文案可传 **`title`**。未传 **`initialFlow`** 时为**空画布**。需要内置示例图时，从本包导入 **`defaultInitialFlow`**、**`cloneWechenAgentFlow`** 并传入 `initialFlow={cloneWechenAgentFlow(defaultInitialFlow)}`。
 
-**集成方**仅通过 **`package.json` `name`** 对应的 **根路径** 导入，例如：
+### 行为与扩展（摘要）
 
-```ts
-import { WechenAgentEditor } from "wechen-agent-editor-v1";
-```
+- **连线**：从节点的 source Handle 拖到 target Handle；选中边可在右侧调整动画与**执行方向**等。**执行方向**与 **`source` → `target`** 一致：箭头在 **目标** 端；选「反向」会 **交换源与目标**（及 handle），不再依赖仅反转 dash 的持久化字段。历史 **`edge.data.wechenFlowDirection: 'reverse'`** 在 **`normalizeWechenAgentFlowJson` / `cloneWechenAgentFlow` / `parseWechenAgentFlowJson`** 中 **幂等归一** 为交换端点并清除该键。宿主也可调用 **`swapWechenFlowEdgeEndpoints(edge)`** 得到与内置面板一致的 **`patchEdge`** 补丁。
+- **数据合并**：节点 `data` 的更新遵循导出的 **`mergeNodeData`**（对象深度合并，数组在补丁中出现时整段替换）。`patchNode` / ref 的 **`patchNodeData`** 将补丁合并进 `node.data`；**`patchEdge`** 为边的顶层浅合并。
+- **自定义右侧面板**：可选 **`renderConfigPanel`**（节点与连线统一入口）或 **`renderNodeConfig`**；同时存在时以 `renderConfigPanel` 为准（返回 `undefined` 时回退内置）。
+- **顶栏按钮**：可选 **`renderHeaderActions`**，入参含与默认行为一致的 **`save`** / **`testRun`** 及 **`editorRef`**。
 
-**构建产物**为 **`dist/index.js`**、**`dist/style.css`**（React Flow 全局样式，由入口 JS 自动引用）与类型 **`dist/index.d.ts`**，由 **`src/index.ts`** 聚合导出；请勿依赖未文档化的深层路径。**公开 API** 概览见上文「主要导出一览」，完整符号以 `src/index.ts` 分组为准。
+完整类型与符号列表以 **`src/index.ts`** 的导出为准。
 
-### 发布流程与生命周期
+### 集成自检
 
-执行 **`npm publish`** 或 **`npm run release`** 时，npm 会先运行 **`prepublishOnly`**（已设为 `npm run build`），再上传。项目脚本 **`release` / `release:cn` 已对 `npm publish` 固定加上 `--registry https://registry.npmjs.org/`**，避免本机默认 registry 仍是 **npmmirror** 时发布误连镜像站并报 **ENEEDAUTH**。
+在宿主项目根目录建议逐项确认：
 
-- **请勿**在 `package.json` 中新增名为 **`publish`** 的脚本并在其中调用 `npm publish`：发版完成后 npm 会再次执行同名生命周期脚本，可能导致**同一版本被发布两次**并报 **E403**。
-- **`README`** 等会按 npm 默认规则一并打入包； tarball 不含 `monaco-editor` 源码树与 `playground`。
+| 检查项 | 说明 |
+|--------|------|
+| Peer 依赖 | **`npm ls react`**、**`npm ls @xyflow/react`**（若宿主另有 Flow 代码）无意外多版本 |
+| 构建 | **`npm run build`**（或 Umi `max build`）通过 |
+| Monaco | 已在首屏前完成 **worker 引导**（见上文「Monaco Worker」） |
+| 空画布 | **未传 `initialFlow`** 时中间画布无预置节点；业务示例需 **`cloneWechenAgentFlow(defaultInitialFlow)`** 或 `ref.replaceFlow(...)` 显式注入 |
+| 烟测 | 拖入节点、四向连线、`readOnly` / `readingMode`、保存或 `getSnapshot` 取流 |
 
-**前置条件**：已安装 **Node.js（建议 LTS）** 与 **npm**；在 [npmjs.com](https://www.npmjs.com/) 拥有账号。
+---
 
-**登录**（本包当前为 **unscoped** 名，一般使用全局登录即可）：
+## 本地开发（本仓库）
 
 ```bash
-npm login
-npm whoami
+npm install
+npm install --prefix playground
+npm run dev              # 完整 playground（场景 JSON + 工具栏）
+npm run dev:minimal      # 仅最小宿主集成（对照 README「快速开始」）
 ```
 
-若将来包名改为 **`@scope/pkg`**（scoped），需对该 **scope** 拥有发布权限，必要时使用 `npm login --scope=@scope`，且 **scoped 包首次**发布到公共注册表通常需要 `npm publish --access public`。
+浏览器地址以终端输出为准（默认 `http://localhost:5173`）。
 
-**发布**（请先在 **npm 官方** 完成登录：`npm login --registry https://registry.npmjs.org/`）：
+---
 
-```bash
-npm publish --access public --registry https://registry.npmjs.org/
-# 或（项目脚本，已含上述 registry）
-npm run release
-```
+## 维护者：发版
 
-**国内网络（可选）**：日常可使用 **npmmirror** 加速 `npm install`；**发版**请用上面的 **`--registry`** 或脚本（勿依赖「先 npm config set registry」——用户级 `.npmrc` 里若仍指向镜像，`npm publish` 可能仍连镜像并报错）。发版成功后若希望把 **默认 registry** 切回镜像，可执行：
+### 1.1.0（相对 npm 线上 **1.0.8**）
 
-```bash
-npm run registry:show          # 查看当前默认 registry
-npm run registry:npmjs         # 手动切到 npm 官方（仅改默认 registry，可选）
-npm run registry:npmmirror     # 切回 npmmirror（装依赖常用）
-npm run release:cn             # 发布到官方（脚本内已固定 registry）→ 成功后再切回 npmmirror
-```
+**新增（向后兼容）**
 
-**发后验证**（将包名换成与 `package.json` `name` 一致）：
+- **`onBeforeRemoveNode` / `onBeforeRemoveEdge`**：删除前宿主守卫，按节点/边粒度允许或拒绝删除（键盘与 `ref.removeNode` / `ref.removeEdge` 均生效）
+- **`buildWechenAgentEditorProps`**（L1 宿主聚合配置）及 **`exportBackendWorkflowJson` / `importBackendWorkflowToFlow`**（后端 DTO 转换）等已在仓库合入、文档化的能力
 
-```bash
-npm view wechen-agent-editor-v1 version
-```
+### 发版清单
 
-在空目录新建最小项目并烟测：
+1. 确认 `package.json` **`version`** 已 bump（当前 **1.1.0**）。
+2. 执行 **`npm install`**（同步 lock）→ **`npm run release:prep`**（`test` + `build` + `pack:check` + playground build），或分步执行。
+3. **`npm whoami`** 确认已登录 **registry.npmjs.org**；scoped 包首次发布需 **`--access public`**（`publishConfig` 已配置）。
+4. 执行 **`npm run release`**（或 `npm publish`），发后验证：
 
 ```bash
-npm install wechen-agent-editor-v1
+npm view wechen-agent-editor-v1 version
+npm pack --dry-run   # 确认 tarball 仅含 dist、LICENSE
 ```
 
-### 元数据占位
-
-发版前建议将 `package.json` 中 **`repository` / `bugs` / `homepage`** 里的占位地址（如 `your-org/wechen-agent`）替换为 **真实 Git 仓库** URL，便于 npm 页面展示与问题反馈。**占位未替换时** npm 项目页上的「仓库」链接不可用，建议在 **对外公开发布前** 完成替换。
-
-## 技术说明
+5. 在空目录烟测：`npm install wechen-agent-editor-v1@1.1.0`，`import { WechenAgentEditor } from "wechen-agent-editor-v1"`。
 
-- 构建：Vite `build.lib`，**`react`、`react-dom`、`antd`、`monaco-editor`、`@monaco-editor/react`** 为 **external**（**不打进 `dist`**），由宿主 **`peerDependencies`** 解析；**`@xyflow/react` 自 1.0.7 起由 `bundledDependencies` 随 npm 包分发**（**不打进单文件 `dist/index.js`**）。**请勿**让本包与宿主各装一份 **React**。
-- **`sideEffects`**：`package.json` 声明 **`./dist/index.js`** 与 **`./dist/style.css`**，避免宿主误摇树掉 **入口 JS 对同目录 CSS 的 `import`**，导致 **生产包样式丢失**。
-- 组件库条目拖入画布时，使用 MIME `application/reactflow` 与载荷前缀 `scope:"wechen-agent"`；宿主可 import `WECHEN_AGENT_FLOW_DRAG_MIME` 与编解码函数以对齐自定义侧栏。
-- 顶栏 **保存** / **测试运行** 通过 `onSave`、`onTestRun` 传出 `WechenAgentSnapshot`：`flow` 为与 `initialFlow` 同形的 **完整对象**（推荐）；`flowJson` 为兼容用字符串。
-- 画布 **Controls** 使用 `showInteractive={false}` 时隐藏「锁定交互」开关，**缩放 / 适应视图** 仍可用。
+发版前可将 `repository` / `bugs` / `homepage` 中的占位 URL 换成真实仓库地址。

package/dist/WechenAgentEditor.d.ts

@@ -1,6 +1,6 @@
-import { ReactNode } from 'react';
+import { CSSProperties, ReactNode } from 'react';
 import { ComponentLibraryGroup, WechenAgentComponentLibraryList } from './config/componentLibraryConfig';
-import { WechenAgentEditorRef, WechenAgentFlowJson, WechenAgentHeaderActionsRenderContext, WechenAgentSnapshot } from './flowTypes';
+import { WechenAgentEditorRef, WechenAgentFlowJson, WechenAgentHeaderActionsRenderContext, WechenAgentSnapshot, WechenBeforeRemoveEdgeFn, WechenBeforeRemoveNodeFn } from './flowTypes';
 import { WechenAgentRenderFlowNodeFn } from './WechenAgentEditorContext';
 import { WechenAgentRenderNodeConfigFn } from './panels/NodeConfigPanel';
 import { WechenAgentRenderConfigPanelFn } from './wechenAgentConfigPanel';
@@ -46,6 +46,33 @@ export interface WechenAgentEditorProps {
     onSave?: (snapshot: WechenAgentSnapshot) => void;
     /** 测试运行：收到与 `onSave` 同形的 `WechenAgentSnapshot`；具体执行由宿主实现（可为试运行 / 调试） */
     onTestRun?: (snapshot: WechenAgentSnapshot) => void;
+    /**
+     * 删除节点前回调；同步返回 **`false`** 时取消该次删除（键盘 Backspace 与 `ref.removeNode` 均生效）。
+     * 删除节点时 **级联移除** 的关联边 **不会** 逐条触发 `onBeforeRemoveEdge`。
+     * `readOnly` / `readingMode` 下 **不调用** 本回调。
+     */
+    onBeforeRemoveNode?: WechenBeforeRemoveNodeFn;
+    /**
+     * 删除边前回调；同步返回 **`false`** 时取消该次删除（键盘与 `ref.removeEdge` 均生效）。
+     * `readOnly` / `readingMode` 下 **不调用** 本回调。
+     */
+    onBeforeRemoveEdge?: WechenBeforeRemoveEdgeFn;
+    /**
+     * 为真时禁止对图的增删改（拖入、连线、删除键、拖动节点等）；仍允许平移/缩放。
+     * 标志会传入 `renderConfigPanel` / `renderNodeConfig` 便于禁用表单。
+     */
+    readOnly?: boolean;
+    /**
+     * 为真时仅渲染中间画布（隐藏顶栏与左右栏），并禁用选中与一切改图；用于纯流程展示。
+     * 隐含只读语义，且 `readOnly`/`readingMode` 会一并传入回调 context。
+     */
+    readingMode?: boolean;
+    /** 根布局可选最小高度；不传则不设置，便于由父容器 `height:100%` 填满 */
+    minHeight?: number | string;
+    /** 透传根 `Layout` 的 `className` */
+    className?: string;
+    /** 透传根 `Layout` 的 `style`（在默认宽高之后合并，便于覆盖） */
+    style?: CSSProperties;
 }
 export declare const WechenAgentEditor: import('react').ForwardRefExoticComponent<WechenAgentEditorProps & import('react').RefAttributes<WechenAgentEditorRef>>;
 //# sourceMappingURL=WechenAgentEditor.d.ts.map

package/dist/WechenAgentEditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WechenAgentEditor.d.ts","sourceRoot":"","sources":["../src/WechenAgentEditor.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAa,SAAS,EAAa,MAAM,OAAO,CAAC;AAc7D,OAAO,KAAK,EACV,qBAAqB,EACrB,+BAA+B,EAChC,MAAM,iCAAiC,CAAC;AAazC,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,qCAAqC,EACrC,mBAAmB,EACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,4BAA4B,CAAC;AAGpC,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AAU/E,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,yDAAyD;IACzD,aAAa,CAAC,EAAE,qBAAqB,EAAE,CAAC;IACxC;;;OAGG;IACH,uBAAuB,CAAC,EAAE,CACxB,IAAI,EAAE,+BAA+B,KAClC,+BAA+B,CAAC;IACrC;;;OAGG;IACH,cAAc,CAAC,EAAE,2BAA2B,CAAC;IAC7C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,6BAA6B,CAAC;IACjD;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,8BAA8B,CAAC;IACnD;;;OAGG;IACH,mBAAmB,CAAC,EAAE,CAAC,GAAG,EAAE,qCAAqC,KAAK,SAAS,CAAC;IAChF,iEAAiE;IACjE,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACjD,wEAAwE;IACxE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,CAAC;CACrD;AAybD,eAAO,MAAM,iBAAiB,yHA2D7B,CAAC"}
+{"version":3,"file":"WechenAgentEditor.d.ts","sourceRoot":"","sources":["../src/WechenAgentEditor.tsx"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,aAAa,EAAa,SAAS,EAAa,MAAM,OAAO,CAAC;AAe5E,OAAO,KAAK,EACV,qBAAqB,EACrB,+BAA+B,EAChC,MAAM,iCAAiC,CAAC;AA0BzC,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,qCAAqC,EACrC,mBAAmB,EACnB,wBAAwB,EACxB,wBAAwB,EACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,4BAA4B,CAAC;AAGpC,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AAU/E,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,yDAAyD;IACzD,aAAa,CAAC,EAAE,qBAAqB,EAAE,CAAC;IACxC;;;OAGG;IACH,uBAAuB,CAAC,EAAE,CACxB,IAAI,EAAE,+BAA+B,KAClC,+BAA+B,CAAC;IACrC;;;OAGG;IACH,cAAc,CAAC,EAAE,2BAA2B,CAAC;IAC7C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,6BAA6B,CAAC;IACjD;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,8BAA8B,CAAC;IACnD;;;OAGG;IACH,mBAAmB,CAAC,EAAE,CAAC,GAAG,EAAE,qCAAqC,KAAK,SAAS,CAAC;IAChF,iEAAiE;IACjE,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACjD,wEAAwE;IACxE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACpD;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,wBAAwB,CAAC;IAC9C;;;OAGG;IACH,kBAAkB,CAAC,EAAE,wBAAwB,CAAC;IAC9C;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAmkBD,eAAO,MAAM,iBAAiB,yHAyE7B,CAAC"}

package/dist/backendWorkflowJson.d.ts

@@ -0,0 +1,57 @@
+import { WechenAgentFlowJson, WechenAgentSnapshot } from './flowTypes';
+/**
+ * 本包定义的「后端工作流 DTO」schema 版本；导入时 **必须** 一致，否则抛错（便于后端演进分支）。
+ */
+export declare const WECHEN_BACKEND_WORKFLOW_SCHEMA_VERSION = "1";
+/** 后端节点类型（与常见低代码「节点 + config」形态对齐；可扩展）。 */
+export type WechenBackendWorkflowNodeType = "start" | "agent" | "task" | "condition" | "api" | "script";
+export interface WechenBackendWorkflowNode {
+    id: string;
+    name: string;
+    type: WechenBackendWorkflowNodeType;
+    x: number;
+    y: number;
+    /** 执行侧参数；由导出映射写入，导入时再映射回 `node.data` */
+    config: Record<string, unknown>;
+}
+export interface WechenBackendWorkflowEdge {
+    source: string;
+    target: string;
+    /** 未给出时导出为 `"default"` */
+    condition?: string;
+}
+/**
+ * 建议持久化 / POST 给后端的 JSON 形状（与内部 `WechenAgentFlowJson` 解耦）。
+ *
+ * **有损说明（导出）**：不携带 React Flow 运行期字段（`measured` 等）、不携带完整 `style` / 自定义 `node.style`；
+ * `edge` 上除 `source`/`target`/`id`/`animated`/`label` 外的部分字段可能丢失，详见 README。
+ *
+ * **有损说明（导入）**：新建边的 `sourceHandle`/`targetHandle` 按边 `id` 规范化；`animated`/`style` 等默认简化。
+ */
+export interface WechenBackendWorkflowJson {
+    schemaVersion: string;
+    flowId: string;
+    flowName: string;
+    /** 业务上的流程定义版本（如 `"1.0"`），与 `schemaVersion` 不同 */
+    version?: string;
+    createTime?: string;
+    nodes: WechenBackendWorkflowNode[];
+    edges: WechenBackendWorkflowEdge[];
+}
+export interface BackendWorkflowExportMeta {
+    flowId: string;
+    flowName?: string;
+    workflowVersion?: string;
+    createTime?: string;
+}
+/**
+ * 将编辑器当前快照（或 `WechenAgentFlowJson`）导出为后端 DTO。
+ */
+export declare function exportBackendWorkflowJson(input: WechenAgentSnapshot | WechenAgentFlowJson, meta: BackendWorkflowExportMeta): WechenBackendWorkflowJson;
+/**
+ * 将后端 DTO 还原为 `WechenAgentFlowJson`，用于 `initialFlow` / `replaceFlow`。
+ */
+export declare function importBackendWorkflowToFlow(dto: WechenBackendWorkflowJson): WechenAgentFlowJson;
+/** 运行时轻量校验（不替代 JSON Schema 服务端校验）。 */
+export declare function isWechenBackendWorkflowJson(value: unknown): value is WechenBackendWorkflowJson;
+//# sourceMappingURL=backendWorkflowJson.d.ts.map

package/dist/backendWorkflowJson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backendWorkflowJson.d.ts","sourceRoot":"","sources":["../src/backendWorkflowJson.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAqC,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAI/G;;GAEG;AACH,eAAO,MAAM,sCAAsC,MAAM,CAAC;AAE1D,2CAA2C;AAC3C,MAAM,MAAM,6BAA6B,GACrC,OAAO,GACP,OAAO,GACP,MAAM,GACN,WAAW,GACX,KAAK,GACL,QAAQ,CAAC;AAEb,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,6BAA6B,CAAC;IACpC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,yBAAyB,EAAE,CAAC;IACnC,KAAK,EAAE,yBAAyB,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA4HD;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,mBAAmB,GAAG,mBAAmB,EAChD,IAAI,EAAE,yBAAyB,GAC9B,yBAAyB,CAY3B;AAiDD;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,yBAAyB,GAAG,mBAAmB,CAgB/F;AAED,sCAAsC;AACtC,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,yBAAyB,CAyC9F"}