wechen-agent-editor-v1 1.0.8 → 1.1.0

package/README.md

@@ -4,6 +4,105 @@
 
 **包名**：以 `package.json` 的 `name` 为准（`wechen-agent-editor-v1`）。安装与 `import` 均使用该名称。
 
+## 快速开始
+
+### 60 秒最小集成（L0）
+
+只需 **`onSave`** 与 antd **`ConfigProvider`**，并保证父容器有高度（例如 `height: 100%` 链或 `100vh`）。未传 **`initialFlow`** 时为**空画布**（与编辑器默认一致）。
+
+```tsx
+import { ConfigProvider } from "antd";
+import { WechenAgentEditor } from "wechen-agent-editor-v1";
+// 若生产构建后缺少 Flow 全局样式，再增加：import "wechen-agent-editor-v1/style.css";
+
+export function AgentPage() {
+  return (
+    <ConfigProvider>
+      <div style={{ height: "100vh" }}>
+        <WechenAgentEditor onSave={(s) => console.log("flow", s.flow)} />
+      </div>
+    </ConfigProvider>
+  );
+}
+```
+
+### 常用配置一条对象（L1）
+
+标题、初始流、只读、以及在**默认组件库**上按条目打补丁，可用 **`buildWechenAgentEditorProps`** 一次展开为 `WechenAgentEditor` 的 props（类型见包内导出）。
+
+```tsx
+import { ConfigProvider } from "antd";
+import {
+  WechenAgentEditor,
+  buildWechenAgentEditorProps,
+  cloneWechenAgentFlow,
+  COMPONENT_LIBRARY_GROUP_APP,
+  defaultInitialFlow,
+} from "wechen-agent-editor-v1";
+
+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),
+});
+
+export function AgentPage() {
+  return (
+    <ConfigProvider>
+      <div style={{ height: "100vh" }}>
+        <WechenAgentEditor {...editorProps} />
+      </div>
+    </ConfigProvider>
+  );
+}
+```
+
+**高级扩展**（自定义画布节点、右侧配置面板、组件库列表映射、顶栏按钮等）仍使用完整 **`WechenAgentEditorProps`**；说明见下文「行为与扩展（摘要）」与 **`src/index.ts`** 导出。
+
+### 后端工作流 JSON（存库 / 执行 / 回显）
+
+编辑器内部持久化形态为 **`WechenAgentFlowJson`**（React Flow 的 `nodes` / `edges` + 业务 `data`）。若后端希望 **扁平 DTO**（`flowId`、`flowName`、`nodes[].type` + `config`、`edges[].source/target` 等），请使用：
+
+- **`exportBackendWorkflowJson(snapshot | flow, meta)`** → **`WechenBackendWorkflowJson`**（根字段 **`schemaVersion`** 当前为 **`"1"`**，与业务字段 **`version`** 区分）
+- **`importBackendWorkflowToFlow(dto)`** → **`WechenAgentFlowJson`**，再作为 **`initialFlow`** 或 **`ref.replaceFlow`** 回显
+
+**有损字段**：导出会去掉 RF 运行期字段与部分边样式；导入会按边 `id` 重新分配 `sourceHandle`/`targetHandle`。详见类型 **`WechenBackendWorkflowJson`** 的 JSDoc。
+
+```tsx
+import {
+  WechenAgentEditor,
+  exportBackendWorkflowJson,
+  importBackendWorkflowToFlow,
+} from "wechen-agent-editor-v1";
+
+<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} />
+```
+
+本仓库 **playground** 提供对照：`npm run dev:minimal` 为最小页；默认 `npm run dev` 为带场景 JSON 与工具栏的完整演示（见 `playground/README.md`）。
+
 ---
 
 ## 安装
@@ -32,7 +131,7 @@ npm 7+ 会校验整棵依赖树的 peer。冲突常来自宿主已有包，未
 {
   "dependencies": {
     "@monaco-editor/react": "^4.6.0",
-    "wechen-agent-editor-v1": "^1.0.8"
+    "wechen-agent-editor-v1": "^1.1.0"
   }
 }
 ```
@@ -62,38 +161,45 @@ antd 5 为 CSS-in-JS，请用 **`ConfigProvider`** 包裹应用（与官方用
 - **`readOnly`**：禁止对图的增删改（拖入、连线、删除键、拖动节点等），仍可使用平移/缩放查看。**`readOnly`** 与 **`readingMode`** 会出现在 **`renderConfigPanel` / `renderNodeConfig`** 的入参中，便于对表单设 **`disabled`**。
 - **`readingMode`**：**仅展示中间流程画布**（隐藏顶栏与左右栏），并**禁用选中**与一切改图，适合文档内嵌、大屏预览等纯展示场景（隐含只读）。
 
-### 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。
+### 删除守卫（`onBeforeRemoveNode` / `onBeforeRemoveEdge`）
 
-### 最小页面
+在可编辑模式下，可通过回调 **按节点/边粒度** 决定是否允许删除。同步返回 **`false`** 时取消该次删除（**Backspace** 与 **`ref.removeNode` / `ref.removeEdge`** 均生效）。**`readOnly` / `readingMode`** 下不调用回调。删除节点时 **级联移除** 的关联边 **不会** 逐条触发 `onBeforeRemoveEdge`。
 
 ```tsx
-import { ConfigProvider } from "antd";
-import { WechenAgentEditor, type WechenAgentSnapshot } from "wechen-agent-editor-v1";
-
-export function AgentPage() {
-  return (
-    <ConfigProvider>
-      <WechenAgentEditor
-        title="Agent 编辑"
-        onSave={(s: WechenAgentSnapshot) => {
-          /* 持久化 s.flow / s.nodes / s.edges */
-        }}
-        onTestRun={(s) => {
-          /* 试运行 */
-        }}
-      />
-    </ConfigProvider>
-  );
-}
+<WechenAgentEditor
+  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}
+/>
 ```
 
-未传 **`initialFlow`** 时为**空画布**。需要内置示例图时，从本包导入 **`defaultInitialFlow`**、**`cloneWechenAgentFlow`** 并传入 `initialFlow={cloneWechenAgentFlow(defaultInitialFlow)}`。
+L1 工厂同样支持：`buildWechenAgentEditorProps({ onBeforeRemoveNode: ... })`。
+
+### 四边感应区连线（默认）
+
+内置 **`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** 端）。
+
+周界四向感应的 **完整方案说明（交互、角区、数据字段、代码映射）** 见仓库 **`openspec/changes/node-perimeter-sensing-scheme/design.md`**。
+
+### 组件库 legacy 接线桩（`flowHandles`，可选）
+
+**已弃用优先**：编排默认以 **四边感应区** 为准。**`libraryGroups`** 中每项仍可设置 **`flowHandles`** 以兼容旧版「声明桩位」：`FlowHandleSpec[]` 或 **`mode: 'even'`** 自动均分。拖入后写入 **`data.flowHandles`**；**`card` / `mainAgent`** 在 **`flowHandles` 展开非空** 时仍走声明桩渲染。**`renderFlowNode`** 自定义整节点时由宿主自行决定接线方式。类型见 **`expandFlowHandlesConfig`**、**`findComponentLibraryItem`** 等导出。
+
+### 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。
+
+### 与快速开始一致的最小页（可选 `title`）
+
+与上文 **L0** 相同；若需要顶栏文案可传 **`title`**。未传 **`initialFlow`** 时为**空画布**。需要内置示例图时，从本包导入 **`defaultInitialFlow`**、**`cloneWechenAgentFlow`** 并传入 `initialFlow={cloneWechenAgentFlow(defaultInitialFlow)}`。
 
 ### 行为与扩展（摘要）
 
-- **连线**：从节点的 source Handle 拖到 target Handle；选中边可在右侧调整动画与方向等。
+- **连线**：从节点的 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`**。
@@ -102,7 +208,15 @@ export function AgentPage() {
 
 ### 集成自检
 
-在宿主项目根目录执行 **`npm ls react`**、**`npm ls @xyflow/react`**，确认无意外多版本；完成 **`npm run build`**（或 Umi `max build`）与画布拖放、连线、右侧配置的简单烟测。
+在宿主项目根目录建议逐项确认：
+
+| 检查项 | 说明 |
+|--------|------|
+| 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` 取流 |
 
 ---
 
@@ -111,7 +225,8 @@ export function AgentPage() {
 ```bash
 npm install
 npm install --prefix playground
-npm run dev
+npm run dev              # 完整 playground（场景 JSON + 工具栏）
+npm run dev:minimal      # 仅最小宿主集成（对照 README「快速开始」）
 ```
 
 浏览器地址以终端输出为准（默认 `http://localhost:5173`）。
@@ -120,8 +235,25 @@ npm run dev
 
 ## 维护者：发版
 
-1. 更新 `package.json` 的 **`version`**（语义化版本）。
-2. 执行 **`npm install`** → **`npm run build`** → **`npm test`**（建议）→ **`npm run pack:check`**。
-3. 登录 npm 官方 registry 后执行 **`npm run release`**（脚本已固定 `--registry https://registry.npmjs.org/`），或等价的手动 `npm publish`。
+### 1.1.0（相对 npm 线上 **1.0.8**）
+
+**新增（向后兼容）**
+
+- **`onBeforeRemoveNode` / `onBeforeRemoveEdge`**：删除前宿主守卫，按节点/边粒度允许或拒绝删除（键盘与 `ref.removeNode` / `ref.removeEdge` 均生效）
+- **`buildWechenAgentEditorProps`**（L1 宿主聚合配置）及 **`exportBackendWorkflowJson` / `importBackendWorkflowToFlow`**（后端 DTO 转换）等已在仓库合入、文档化的能力
+
+### 发版清单
+
+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 view wechen-agent-editor-v1 version
+npm pack --dry-run   # 确认 tarball 仅含 dist、LICENSE
+```
+
+5. 在空目录烟测：`npm install wechen-agent-editor-v1@1.1.0`，`import { WechenAgentEditor } from "wechen-agent-editor-v1"`。
 
 发版前可将 `repository` / `bugs` / `homepage` 中的占位 URL 换成真实仓库地址。

package/dist/WechenAgentEditor.d.ts

@@ -1,6 +1,6 @@
 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,17 @@ 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` 便于禁用表单。

package/dist/WechenAgentEditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WechenAgentEditor.d.ts","sourceRoot":"","sources":["../src/WechenAgentEditor.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,aAAa,EAAa,SAAS,EAAa,MAAM,OAAO,CAAC;AAc5E,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;IACpD;;;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;AAsgBD,eAAO,MAAM,iBAAiB,yHAqE7B,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"}

package/dist/config/componentLibraryConfig.d.ts

@@ -1,4 +1,5 @@
 import { ReactNode } from 'react';
+import { FlowHandlesConfig } from './flowHandleTypes';
 import { ComponentLibraryIconSlot } from './componentLibraryIconTypes';
 export type { ComponentLibraryIconSlot } from './componentLibraryIconTypes';
 export { isLibraryIconSet, isLibraryIconString } from './componentLibraryIconTypes';
@@ -28,6 +29,11 @@ export interface ComponentLibraryItem {
      * 传入节点时可完全自定义（如下拉、多个按钮）。此时忽略 `showAddButton` / `addButtonIcon`。
      */
     addButtonSlot?: ReactNode | null;
+    /**
+     * @deprecated 默认节点优先使用 **左右感应区** 动态接线（见 README）；仅当需兼容旧版声明桩时保留。
+     * 拖入画布后写入 `data.flowHandles`；使用 `renderFlowNode` 覆盖整节点时由宿主自行决定。
+     */
+    flowHandles?: FlowHandlesConfig;
 }
 export interface ComponentLibraryGroup {
     key: string;
@@ -55,6 +61,7 @@ export interface WechenAgentComponentLibraryItemPayload {
     showAddButton?: boolean;
     addButtonIcon?: ComponentLibraryIconSlot;
     addButtonSlot?: ReactNode | null;
+    flowHandles?: FlowHandlesConfig;
 }
 /**
  * 回调里「分组」：`name` 为分组标题（如主 Agent / 应用 Agent），`children` 为该组组件列表；
@@ -74,4 +81,6 @@ export type WechenAgentComponentLibraryList = WechenAgentComponentLibraryGroupPa
 export declare function toWechenAgentComponentLibraryList(groups: ComponentLibraryGroup[]): WechenAgentComponentLibraryList;
 /** 将 `{ name, children, groupKey? }[]` 转回编辑器内部分组（用于 `mapComponentLibraryList` 返回值） */
 export declare function fromWechenAgentComponentLibraryList(list: WechenAgentComponentLibraryList): ComponentLibraryGroup[];
+/** 按分组 key 与库项 key 查找组件库项（用于拖放落盘 `flowHandles` 等）。 */
+export declare function findComponentLibraryItem(groups: ComponentLibraryGroup[], groupKey: string, itemKey: string): ComponentLibraryItem | undefined;
 //# sourceMappingURL=componentLibraryConfig.d.ts.map

package/dist/config/componentLibraryConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"componentLibraryConfig.d.ts","sourceRoot":"","sources":["../../src/config/componentLibraryConfig.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAG5E,YAAY,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEpF,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC;;OAEG;IACH,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC;;;OAGG;IACH,aAAa,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,oBAAoB,EAAE,CAAC;CAC/B;AAED,sCAAsC;AACtC,eAAO,MAAM,4BAA4B,QAAkB,CAAC;AAC5D,kCAAkC;AAClC,eAAO,MAAM,2BAA2B,OAAiB,CAAC;AAE1D,2BAA2B;AAC3B,eAAO,MAAM,8BAA8B,EAAE,oBAAoB,EAIhE,CAAC;AAEF,4BAA4B;AAC5B,eAAO,MAAM,6BAA6B,EAAE,oBAAoB,EAM/D,CAAC;AAKF,8CAA8C;AAC9C,wBAAgB,gCAAgC,IAAI,qBAAqB,EAAE,CAa1E;AAED,iDAAiD;AACjD,MAAM,WAAW,sCAAsC;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,aAAa,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,uCAAuC;IACtD,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,sCAAsC,EAAE,CAAC;CACpD;AAED,MAAM,MAAM,+BAA+B,GAAG,uCAAuC,EAAE,CAAC;AAExF,2CAA2C;AAC3C,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,qBAAqB,EAAE,GAC9B,+BAA+B,CAmBjC;AAED,sFAAsF;AACtF,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,+BAA+B,GACpC,qBAAqB,EAAE,CA0BzB"}
+{"version":3,"file":"componentLibraryConfig.d.ts","sourceRoot":"","sources":["../../src/config/componentLibraryConfig.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAG5E,YAAY,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEpF,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC;;OAEG;IACH,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC;;;OAGG;IACH,aAAa,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,oBAAoB,EAAE,CAAC;CAC/B;AAED,sCAAsC;AACtC,eAAO,MAAM,4BAA4B,QAAkB,CAAC;AAC5D,kCAAkC;AAClC,eAAO,MAAM,2BAA2B,OAAiB,CAAC;AAE1D,2BAA2B;AAC3B,eAAO,MAAM,8BAA8B,EAAE,oBAAoB,EAIhE,CAAC;AAEF,4BAA4B;AAC5B,eAAO,MAAM,6BAA6B,EAAE,oBAAoB,EAM/D,CAAC;AAKF,8CAA8C;AAC9C,wBAAgB,gCAAgC,IAAI,qBAAqB,EAAE,CAa1E;AAED,iDAAiD;AACjD,MAAM,WAAW,sCAAsC;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACrC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,aAAa,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACjC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,uCAAuC;IACtD,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,sCAAsC,EAAE,CAAC;CACpD;AAED,MAAM,MAAM,+BAA+B,GAAG,uCAAuC,EAAE,CAAC;AAExF,2CAA2C;AAC3C,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,qBAAqB,EAAE,GAC9B,+BAA+B,CAoBjC;AAED,sFAAsF;AACtF,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,+BAA+B,GACpC,qBAAqB,EAAE,CA2BzB;AAED,sDAAsD;AACtD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,qBAAqB,EAAE,EAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,oBAAoB,GAAG,SAAS,CAGlC"}

package/dist/config/flowHandleTypes.d.ts

@@ -0,0 +1,27 @@
+import { CSSProperties } from 'react';
+/** Edge side for a React Flow `Handle` (`Position` maps in node components). */
+export type FlowHandleSide = "top" | "right" | "bottom" | "left";
+/** Declarative handle matching `@xyflow/react` `Handle` props subset. */
+export interface FlowHandleSpec {
+    type: "source" | "target";
+    position: FlowHandleSide;
+    id?: string;
+    style?: CSSProperties;
+}
+export interface FlowHandleSlotEven {
+    count: number;
+    side: FlowHandleSide;
+}
+/** Evenly spaced handles on one or two sides (`mode` reserved for future). */
+export interface FlowHandleAutoLayout {
+    mode: "even";
+    sources?: FlowHandleSlotEven;
+    targets?: FlowHandleSlotEven;
+}
+export type FlowHandlesConfig = FlowHandleSpec[] | FlowHandleAutoLayout;
+/**
+ * Normalizes `FlowHandlesConfig` to concrete specs for rendering.
+ * Auto layout on the **same** side for both sources and targets uses one shared spacing strip.
+ */
+export declare function expandFlowHandlesConfig(config: FlowHandlesConfig): FlowHandleSpec[];
+//# sourceMappingURL=flowHandleTypes.d.ts.map

package/dist/config/flowHandleTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowHandleTypes.d.ts","sourceRoot":"","sources":["../../src/config/flowHandleTypes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjE,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,QAAQ,EAAE,cAAc,CAAC;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,cAAc,CAAC;CACtB;AAED,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,OAAO,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED,MAAM,MAAM,iBAAiB,GAAG,cAAc,EAAE,GAAG,oBAAoB,CAAC;AAcxE;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAqDnF"}

package/dist/flow/deleteGuard.d.ts

@@ -0,0 +1,11 @@
+import { Edge, EdgeChange, Node, NodeChange } from '@xyflow/react';
+import { WechenBeforeRemoveEdgeFn, WechenBeforeRemoveNodeFn } from '../flowTypes';
+/** 是否允许删除指定节点（无回调或节点不存在时按 allow / deny 语义处理）。 */
+export declare function canRemoveNode(nodeId: string, nodes: ReadonlyArray<Node>, onBeforeRemoveNode?: WechenBeforeRemoveNodeFn): boolean;
+/** 是否允许删除指定边。 */
+export declare function canRemoveEdge(edgeId: string, edges: ReadonlyArray<Edge>, onBeforeRemoveEdge?: WechenBeforeRemoveEdgeFn): boolean;
+/** 过滤 `onNodesChange` 中被守卫拒绝的 `remove` 项；无回调时原样返回。 */
+export declare function filterRemoveNodeChanges(changes: NodeChange[], nodes: ReadonlyArray<Node>, onBeforeRemoveNode?: WechenBeforeRemoveNodeFn): NodeChange[];
+/** 过滤 `onEdgesChange` 中被守卫拒绝的 `remove` 项；无回调时原样返回。 */
+export declare function filterRemoveEdgeChanges(changes: EdgeChange[], edges: ReadonlyArray<Edge>, onBeforeRemoveEdge?: WechenBeforeRemoveEdgeFn): EdgeChange[];
+//# sourceMappingURL=deleteGuard.d.ts.map

package/dist/flow/deleteGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deleteGuard.d.ts","sourceRoot":"","sources":["../../src/flow/deleteGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,KAAK,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAMvF,iDAAiD;AACjD,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,EAC1B,kBAAkB,CAAC,EAAE,wBAAwB,GAC5C,OAAO,CAST;AAED,iBAAiB;AACjB,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,EAC1B,kBAAkB,CAAC,EAAE,wBAAwB,GAC5C,OAAO,CAST;AAED,sDAAsD;AACtD,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,UAAU,EAAE,EACrB,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,EAC1B,kBAAkB,CAAC,EAAE,wBAAwB,GAC5C,UAAU,EAAE,CAUd;AAED,sDAAsD;AACtD,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,UAAU,EAAE,EACrB,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,EAC1B,kBAAkB,CAAC,EAAE,wBAAwB,GAC5C,UAAU,EAAE,CAUd"}

package/dist/flow/dropNodes.d.ts

@@ -1,12 +1,13 @@
 import { Node } from '@xyflow/react';
+import { FlowHandlesConfig } from '../config/flowHandleTypes';
 import { MainAgentNodeData, SimpleNodeData } from '../flowTypes';
 export declare function newDroppedNodeId(): string;
 export declare function createDroppedCardNode(id: string, position: {
     x: number;
     y: number;
-}, label: string): Node<SimpleNodeData>;
+}, label: string, flowHandles?: FlowHandlesConfig): Node<SimpleNodeData>;
 export declare function createDroppedMainAgentNode(id: string, position: {
     x: number;
     y: number;
-}, label: string): Node<MainAgentNodeData>;
+}, label: string, flowHandles?: FlowHandlesConfig): Node<MainAgentNodeData>;
 //# sourceMappingURL=dropNodes.d.ts.map

package/dist/flow/dropNodes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dropNodes.d.ts","sourceRoot":"","sources":["../../src/flow/dropNodes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEtE,wBAAgB,gBAAgB,IAAI,MAAM,CAKzC;AAED,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAClC,KAAK,EAAE,MAAM,GACZ,IAAI,CAAC,cAAc,CAAC,CAOtB;AAED,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAClC,KAAK,EAAE,MAAM,GACZ,IAAI,CAAC,iBAAiB,CAAC,CAgBzB"}
+{"version":3,"file":"dropNodes.d.ts","sourceRoot":"","sources":["../../src/flow/dropNodes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEtE,wBAAgB,gBAAgB,IAAI,MAAM,CAKzC;AAED,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAClC,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,iBAAiB,GAC9B,IAAI,CAAC,cAAc,CAAC,CAUtB;AAED,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAClC,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,iBAAiB,GAC9B,IAAI,CAAC,iBAAiB,CAAC,CAiBzB"}

package/dist/flow/flowJsonUtils.d.ts

@@ -3,6 +3,7 @@ import { WechenAgentFlowJson } from '../flowTypes';
  * 去掉 React Flow 运行期字段，使 **`flow` 与 `defaultInitialFlow` / 传入的 `initialFlow` 同形**
  *（仅保留 id、type、position、data、edges 上业务相关字段等）。
  * 保存、`JSON.stringify`、回灌 `initialFlow` 前均应使用（`cloneWechenAgentFlow` / `parseWechenAgentFlowJson` 已内置）。
+ * 含对旧数据 **`edge.data.wechenFlowDirection === 'reverse'`** 的 **幂等归一化**（交换 `source`/`target` 并清除该标志，见 `swapWechenFlowEdgeEndpoints`）。
  */
 export declare function normalizeWechenAgentFlowJson(flow: WechenAgentFlowJson): WechenAgentFlowJson;
 /**

package/dist/flow/flowJsonUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flowJsonUtils.d.ts","sourceRoot":"","sources":["../../src/flow/flowJsonUtils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AA8BxD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,mBAAmB,GAAG,mBAAmB,CAM3F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,mBAAmB,GAAG,mBAAmB,CAGnF;AAED,8DAA8D;AAC9D,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAG1E"}
+{"version":3,"file":"flowJsonUtils.d.ts","sourceRoot":"","sources":["../../src/flow/flowJsonUtils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AA0DxD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,mBAAmB,GAAG,mBAAmB,CAQ3F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,mBAAmB,GAAG,mBAAmB,CAGnF;AAED,8DAA8D;AAC9D,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAG1E"}

package/dist/flow/initialFlow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initialFlow.d.ts","sourceRoot":"","sources":["../../src/flow/initialFlow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACpB,MAAM,cAAc,CAAC;AAEtB,eAAO,MAAM,mBAAmB,EAAE,IAAI,CAAC,iBAAiB,GAAG,cAAc,CAAC,EA6CzE,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,IAAI,EAkBrC,CAAC;AAEF,mCAAmC;AACnC,eAAO,MAAM,kBAAkB,EAAE,mBAIhC,CAAC;AAEF,yCAAyC;AACzC,eAAO,MAAM,gBAAgB,EAAE,mBAG9B,CAAC"}
+{"version":3,"file":"initialFlow.d.ts","sourceRoot":"","sources":["../../src/flow/initialFlow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACpB,MAAM,cAAc,CAAC;AAEtB,eAAO,MAAM,mBAAmB,EAAE,IAAI,CAAC,iBAAiB,GAAG,cAAc,CAAC,EA6CzE,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,IAAI,EA2BrC,CAAC;AAEF,mCAAmC;AACnC,eAAO,MAAM,kBAAkB,EAAE,mBAIhC,CAAC;AAEF,yCAAyC;AACzC,eAAO,MAAM,gBAAgB,EAAE,mBAG9B,CAAC"}

package/dist/flow/nodeChangeSyncAttachSides.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 节点变更 → 是否需按几何同步 `edge.data` 锚边（与 `ZoneHandles` 分区一致）。
+ * 见 `WechenAgentEditor` 中 `guardedOnNodesChange` → `patchEdgesAttachSidesFromGeometry`。
+ */
+/** 与 `@xyflow/react` `onNodesChange` 单次数组项兼容的最小形状 */
+export type NodeChangeLike = {
+    type: string;
+    dragging?: boolean;
+};
+/**
+ * 尺寸变化或拖动结束（`position` 且 `dragging === false`）时，应重算边上的
+ * `wechenSourceAttachSide` / `wechenTargetAttachSide`。
+ */
+export declare function shouldSyncEdgeAttachSidesAfterNodeChanges(changes: ReadonlyArray<NodeChangeLike>): boolean;
+//# sourceMappingURL=nodeChangeSyncAttachSides.d.ts.map

package/dist/flow/nodeChangeSyncAttachSides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeChangeSyncAttachSides.d.ts","sourceRoot":"","sources":["../../src/flow/nodeChangeSyncAttachSides.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,yCAAyC,CACvD,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,GACrC,OAAO,CAUT"}

package/dist/flow/nodes/CardNode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CardNode.d.ts","sourceRoot":"","sources":["../../../src/flow/nodes/CardNode.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAIjE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,2CAuBxC"}
+{"version":3,"file":"CardNode.d.ts","sourceRoot":"","sources":["../../../src/flow/nodes/CardNode.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAO/C,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,2CA+CxC"}

package/dist/flow/nodes/DeclaredHandles.d.ts

@@ -0,0 +1,5 @@
+import { FlowHandleSpec } from '../../config/flowHandleTypes';
+export declare function DeclaredHandles({ specs }: {
+    specs: FlowHandleSpec[];
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=DeclaredHandles.d.ts.map

package/dist/flow/nodes/DeclaredHandles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeclaredHandles.d.ts","sourceRoot":"","sources":["../../../src/flow/nodes/DeclaredHandles.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AASnE,wBAAgB,eAAe,CAAC,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,cAAc,EAAE,CAAA;CAAE,2CAcrE"}

package/dist/flow/nodes/MainAgentNode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MainAgentNode.d.ts","sourceRoot":"","sources":["../../../src/flow/nodes/MainAgentNode.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAIjE,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,2CAyC7C"}
+{"version":3,"file":"MainAgentNode.d.ts","sourceRoot":"","sources":["../../../src/flow/nodes/MainAgentNode.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAO/C,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,2CA2D7C"}

package/dist/flow/nodes/PillNode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PillNode.d.ts","sourceRoot":"","sources":["../../../src/flow/nodes/PillNode.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAIjE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,2CAsBxC"}
+{"version":3,"file":"PillNode.d.ts","sourceRoot":"","sources":["../../../src/flow/nodes/PillNode.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAK/C,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,2CAuBxC"}

package/dist/flow/nodes/ZoneHandles.d.ts

@@ -0,0 +1,10 @@
+/** 感应带宽度；与左右 / 上下Inset 一致用于切角 */
+export declare const ZONE_STRIP_PX = 11;
+/**
+ * 四边感应区：左/上为输入池（target），右/下为输出池（source）。
+ * 角区留白（左带不占左上角/左下角矩形），避免与上/下带重叠命中。
+ */
+export declare function ZoneHandles({ nodeId }: {
+    nodeId: string;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ZoneHandles.d.ts.map

package/dist/flow/nodes/ZoneHandles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZoneHandles.d.ts","sourceRoot":"","sources":["../../../src/flow/nodes/ZoneHandles.tsx"],"names":[],"mappings":"AAwBA,iCAAiC;AACjC,eAAO,MAAM,aAAa,KAAK,CAAC;AAchC;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,2CA+OzD"}

package/dist/flow/swapFlowEdgeEndpoints.d.ts

@@ -0,0 +1,11 @@
+import { Edge } from '@xyflow/react';
+/**
+ * 交换边的 `source`/`target` 与 handle，并清除 **`wechenFlowDirection`** 与四边锚点偏好（由布局重新推导）。
+ * 用于「执行方向 = 几何 source→target」：箭头始终在 target 端（`markerEnd`）。
+ *
+ * `patchEdge` 合并 **`data`** 时，对值为 **`undefined`** 的键 **删除** 原 `edge.data` 中对应键（见 `WechenAgentEditor` 内 `onPatchEdge`）。
+ *
+ * @returns 供 `patchEdge` 浅合并的字段；**自环** 时仅清除 `data.wechenFlowDirection`（若有），不交换端点。
+ */
+export declare function swapWechenFlowEdgeEndpoints(edge: Edge): Partial<Edge>;
+//# sourceMappingURL=swapFlowEdgeEndpoints.d.ts.map

package/dist/flow/swapFlowEdgeEndpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swapFlowEdgeEndpoints.d.ts","sourceRoot":"","sources":["../../src/flow/swapFlowEdgeEndpoints.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAG1C;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCrE"}

package/dist/flow/wechenAgentEdgeTypes.d.ts

@@ -1,8 +1,22 @@
 import { EdgeProps } from '@xyflow/react';
-/** 持久化在 `edge.data.wechenFlowDirection`，与源→目标几何方向相对 */
+/**
+ * 历史字段：曾用于「仅反转 dash 动画」。新语义下 **不应再持久化为 `reverse`**；
+ * `normalizeWechenAgentFlowJson` 会将遗留 `reverse` 归一为交换端点并清除该键。
+ */
 export type WechenAgentEdgeFlowDirection = "forward" | "reverse";
+/** 四边感应：目标端落在输入池的哪一侧（左 / 上） */
+export type WechenAttachSideIn = "left" | "top";
+/** 四边感应：源端落在输出池的哪一侧（右 / 下） */
+export type WechenAttachSideOut = "right" | "bottom";
+/** 连线在边对象 `data` 上的可选字段（感应边偏好等） */
+export interface WechenAgentEdgeData {
+    /** @deprecated 新图请通过交换 `source`/`target` 表达执行反向；遗留值由 normalize 迁移 */
+    wechenFlowDirection?: WechenAgentEdgeFlowDirection;
+    wechenTargetAttachSide?: WechenAttachSideIn;
+    wechenSourceAttachSide?: WechenAttachSideOut;
+}
 /**
- * 默认边：Bezier + 可选反向流动（`data.wechenFlowDirection === 'reverse'` 时 CSS 反转 dash 动画）。
+ * 默认边：平滑阶梯线；箭头在 **几何 target 端**（执行进入下游节点）。
  */
 export declare function WechenAgentDefaultEdge(props: EdgeProps): import("react/jsx-runtime").JSX.Element;
 export declare const wechenAgentEdgeTypes: {

package/dist/flow/wechenAgentEdgeTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wechenAgentEdgeTypes.d.ts","sourceRoot":"","sources":["../../src/flow/wechenAgentEdgeTypes.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAE3D,uDAAuD;AACvD,MAAM,MAAM,4BAA4B,GAAG,SAAS,GAAG,SAAS,CAAC;AAEjE;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,2CAStD;AAED,eAAO,MAAM,oBAAoB;;CAEhC,CAAC"}
+{"version":3,"file":"wechenAgentEdgeTypes.d.ts","sourceRoot":"","sources":["../../src/flow/wechenAgentEdgeTypes.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/D;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,SAAS,GAAG,SAAS,CAAC;AAEjE,+BAA+B;AAC/B,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,KAAK,CAAC;AAEhD,8BAA8B;AAC9B,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErD,mCAAmC;AACnC,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,mBAAmB,CAAC,EAAE,4BAA4B,CAAC;IACnD,sBAAsB,CAAC,EAAE,kBAAkB,CAAC;IAC5C,sBAAsB,CAAC,EAAE,mBAAmB,CAAC;CAC9C;AAkBD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,2CAStD;AAED,eAAO,MAAM,oBAAoB;;CAEhC,CAAC"}