wechen-agent-editor-v1 1.0.8 → 1.1.1

package/README.md

@@ -4,6 +4,143 @@
 
 **包名**：以 `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。
+
+**节点类型映射**（画布 ↔ DTO）：
+
+| 画布 | DTO `nodes[].type` | 说明 |
+|------|-------------------|------|
+| `pill` | `start` | 入口 |
+| `mainAgent` | `agent` | 主 Agent |
+| `card`（默认） | `task` | 通用任务 |
+| `card` + `data.backendNodeType` | `condition` / `api` / `script` | 扩展类型；导入后写回 `backendNodeType` |
+
+自定义节点若需稳定 DTO 类型，请在 `node.data` 设置 **`backendNodeType`**（取值与 `WechenBackendWorkflowNodeType` 一致）。
+
+```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`）。
+
+### 编辑器与 Agent 运行时
+
+本包是 **编排 UI + 序列化 + ref API**，**不包含** Agent / LLM **执行引擎**。推荐分层：
+
+```
+WechenAgentEditor（编排） → onSave / exportBackendWorkflowJson → 宿主持久化 → 你们的运行时调度
+```
+
+- **`onTestRun` / `ref.testRun()`**：仅触发宿主回调，具体执行由宿主实现。
+- **`validateWechenAgentFlow(flow)`**：纯函数图校验（默认不阻断保存）；可在 `onBeforeSave` 内返回 `false` 拦截。
+- **ref 增删改查**：`getSnapshot` / `patchNodeData` / `removeNode` / `addNode` / `addNodeFromLibrary` / `addEdge` / `connect` / `replaceFlow`（见 `WechenAgentEditorRef`）。
+
+```tsx
+import { validateWechenAgentFlow } from "wechen-agent-editor-v1";
+
+<WechenAgentEditor
+  onBeforeSave={(snap) => {
+    const { valid, issues } = validateWechenAgentFlow(snap.flow);
+    if (!valid) {
+      console.warn(issues);
+      return false;
+    }
+  }}
+  onSave={(s) => { /* POST exportBackendWorkflowJson(s, meta) */ }}
+/>
+```
+
 ---
 
 ## 安装
@@ -32,7 +169,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"
   }
 }
 ```
@@ -55,54 +192,167 @@ import "wechen-agent-editor-v1/style.css";
 
 antd 5 为 CSS-in-JS，请用 **`ConfigProvider`** 包裹应用（与官方用法一致）。
 
-### 嵌入尺寸、`readOnly` 与 `readingMode`
+### 嵌入 flex 布局
 
-根组件默认 **`height` / `width` 为 `100%`**，可通过 **`className` / `style`** 透传；可选 **`minHeight`**。请保证父级链路上有**明确高度**（如 flex 子项 `flex:1` + `minHeight:0`、固定 `height` 等），否则中间画布可能无法撑满。
+在 **列方向 flex** 页面中，推荐与 playground 相同的外层结构：父级定高（或 `100vh`），编辑器所在子项使用 **`flex: 1`**、**`minHeight: 0`**，编辑器根节点会 **`flex: 1`** 并 **`height/width: 100%`** 填满该区域。
 
-- **`readOnly`**：禁止对图的增删改（拖入、连线、删除键、拖动节点等），仍可使用平移/缩放查看。**`readOnly`** 与 **`readingMode`** 会出现在 **`renderConfigPanel` / `renderNodeConfig`** 的入参中，便于对表单设 **`disabled`**。
-- **`readingMode`**：**仅展示中间流程画布**（隐藏顶栏与左右栏），并**禁用选中**与一切改图，适合文档内嵌、大屏预览等纯展示场景（隐含只读）。
+```tsx
+<div style={{ height: "100vh", display: "flex", flexDirection: "column", minHeight: 0 }}>
+  <YourToolbar />
+  <div style={{ flex: 1, minHeight: 0, display: "flex", flexDirection: "column" }}>
+    <WechenAgentEditor {...props} />
+  </div>
+</div>
+```
 
-### Monaco Worker
+**行为说明**：自 **1.1.x** 起，画布区域 **不再** 默认施加 `min-height: 400px`；若需要最小可视高度，请对编辑器传入 **`minHeight`** prop，或在页面级容器设置 `min-height`。
+
+### 骨架 CSS 类名（自定义样式）
+
+加载 **`wechen-agent-editor-v1/style.css`** 后，可用下列稳定类名覆盖布局分区样式（与根 **`className`** 合并，不会替换默认类）：
+
+| 类名 | 区域 |
+| --- | --- |
+| `wechen-agent-editor` | 根布局 |
+| `wechen-agent-editor--reading` | 阅读模式根修饰 |
+| `wechen-agent-editor__workspace` | 工作区（顶栏 + 主体） |
+| `wechen-agent-editor__header` | 顶栏 |
+| `wechen-agent-editor__body` | 主体行（左栏 + 画布 + 右栏） |
+| `wechen-agent-editor__library-sider` | 左侧组件库 Sider |
+| `wechen-agent-editor__library-panel` | 组件库面板内容 |
+| `wechen-agent-editor__main` | 中间主内容 |
+| `wechen-agent-editor__canvas` / `wechen-agent-canvas` | 画布壳（二者同元素，后者为兼容别名） |
+| `wechen-agent-editor__config-sider` | 右侧配置 Sider |
+| `wechen-agent-editor__config-panel` | 配置面板内容 |
+
+```css
+/* 例：自定义顶栏背景 */
+.wechen-agent-editor__header {
+  background: #fafafa !important;
+}
+```
 
-必须在**首次渲染编辑器之前**完成 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。
+### 国际化（壳层 vs 宿主自定义）
+
+编辑器是 **编排基座**：画布节点由 **`renderFlowNode`**、右侧内容区由 **`renderConfigPanel` / `renderNodeConfig`** 自定义时，**业务文案由宿主自行 i18n**。包内 **`localeMessages`** 仅覆盖 **壳层**（顶栏按钮、左右栏分区标题、组件库搜索/空状态、画布缩放控件等；经 React Flow **`ariaLabelConfig`** 注入）。
+
+#### 语言契约（`localeMessages` 大 JSON）
 
-### 最小页面
+| 条件 | 编辑器显示语言 |
+| --- | --- |
+| **未传** `localeMessages` | **始终内置中文**（`DEFAULT_ZH_CN`），与 antd `ConfigProvider`、浏览器语言 **无关** |
+| **已传** `localeMessages` | **仅以该 JSON 为准**；缺失 key **不回退中文**，显示 key 字符串 |
+| 存在 `localeTranslate` | **最高优先级**（便于对接 i18next） |
+
+语言包 **key 为默认中文**（与界面中文一致），便于对照扩展，例如 `{ "保存": "Save", "配置": "Settings" }`。代码中可用 **`LOCALE_KEYS`** / **`FALLBACK_LOCALE_KEYS`** 常量（值为中文 key，如 `LOCALE_KEYS.HEADER_SAVE === "保存"`）。
+
+生产推荐：从 **`exportWechenAgentEditorLocaleBundle()`** 复制整表，将 value 译为目标语言后传入；或用 **`mergeWechenAgentEditorLocaleMessages(译文)`** 在宿主侧生成完整大 JSON。
 
 ```tsx
-import { ConfigProvider } from "antd";
-import { WechenAgentEditor, type WechenAgentSnapshot } from "wechen-agent-editor-v1";
+import {
+  WechenAgentEditor,
+  LOCALE_KEYS,
+  mergeWechenAgentEditorLocaleMessages,
+  validateLocaleMessagesCompleteness,
+} from "wechen-agent-editor-v1";
+
+// 中文（默认）：不传 localeMessages
+<WechenAgentEditor renderConfigPanel={(ctx) => <MyPanel {...ctx} />} />;
+
+// 英文：key 为中文，value 为目标语言
+const enPack = mergeWechenAgentEditorLocaleMessages({
+  保存: "Save",
+  配置: "Settings",
+  组件库: "Component library",
+  // 或使用常量： [LOCALE_KEYS.HEADER_SAVE]: "Save",
+});
+validateLocaleMessagesCompleteness(enPack);
+
+<WechenAgentEditor localeMessages={enPack} />;
+```
 
-export function AgentPage() {
-  return (
-    <ConfigProvider>
-      <WechenAgentEditor
-        title="Agent 编辑"
-        onSave={(s: WechenAgentSnapshot) => {
-          /* 持久化 s.flow / s.nodes / s.edges */
-        }}
-        onTestRun={(s) => {
-          /* 试运行 */
-        }}
-      />
-    </ConfigProvider>
-  );
-}
+```tsx
+// antd 与编辑器语言独立配置
+<ConfigProvider locale={antdLocale}>
+  <WechenAgentEditor localeMessages={wechenEditorLocalePack} />
+</ConfigProvider>
 ```
 
-未传 **`initialFlow`** 时为**空画布**。需要内置示例图时，从本包导入 **`defaultInitialFlow`**、**`cloneWechenAgentFlow`** 并传入 `initialFlow={cloneWechenAgentFlow(defaultInitialFlow)}`。
+- **`exportWechenAgentEditorShellLocaleBundle('zh-CN')`**：仅壳层 key（生产常用子集）。
+- **`exportWechenAgentEditorFallbackLocaleBundle`**：内置回退面板 key（未传 `renderConfigPanel` 时）。
+- **`exportWechenAgentEditorLocaleBundle`**：壳层 + 回退 **完整** key 表（推荐作翻译模板）。
+- **`configSiderTitle`**：可完全覆盖右侧栏外框标题。
+- **`validateLocaleMessagesCompleteness`**：检查大 JSON 是否缺 key（开发期 `console.warn`）。
+
+完整契约演示见 `playground/src/App.tsx`（中文不传包；English 传 `playgroundLocaleEnFull.ts`）。
+
+### 嵌入尺寸、`readOnly` 与 `readingMode`
+
+根组件默认 **`height` / `width` 为 `100%`**，**`flex: 1`**、**`minHeight: 0`**（便于 flex 父级）；可通过 **`className` / `style`** 透传；可选 **`minHeight`**。请保证父级链路上有**明确高度**（见上文 flex 示例），否则中间画布可能无法撑满。
+
+- **`readOnly`**：禁止对图的增删改（拖入、连线、删除键、拖动节点等），仍可使用平移/缩放查看。**`readOnly`** 与 **`readingMode`** 会出现在 **`renderConfigPanel` / `renderNodeConfig`** 的入参中，便于对表单设 **`disabled`**。
+- **`readingMode`**：**仅展示中间流程画布**（隐藏顶栏与左右栏），并**禁用选中**与一切改图，适合文档内嵌、大屏预览等纯展示场景（隐含只读）。根节点会附加 **`wechen-agent-editor--reading`**。
+
+### 删除守卫（`onBeforeRemoveNode` / `onBeforeRemoveEdge`）
+
+在可编辑模式下，可通过回调 **按节点/边粒度** 决定是否允许删除。同步返回 **`false`** 时取消该次删除（**Backspace** 与 **`ref.removeNode` / `ref.removeEdge`** 均生效）。**`readOnly` / `readingMode`** 下不调用回调。删除节点时 **级联移除** 的关联边 **不会** 逐条触发 `onBeforeRemoveEdge`。
+
+```tsx
+<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}
+/>
+```
+
+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`** 仅自定义节点 **内容区**（字段与样式）；内置外壳与接线桩（感应区或 **`flowHandles`**）**始终保留**，**勿** 在 `renderFlowNode` 内放置 `Handle`。类型见 **`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`**。
+- **顶栏左侧**：可选 **`renderHeaderLeading`**，入参含当前解析标题 **`title`**（与 **`ref.getTitle()`** 一致）及 **`editorRef`**；未传时显示默认 `Title`。改标题数据仍用 **`title` prop** 或 **`replaceFlow`**。
+- **顶栏右侧**：可选 **`renderHeaderActions`**，入参含与默认行为一致的 **`save`** / **`testRun`** 及 **`editorRef`**。左右可 **同时** 自定义。Playground：`?tab=header-leading`、`?tab=header-actions`。
 
 完整类型与符号列表以 **`src/index.ts`** 的导出为准。
 
 ### 集成自检
 
-在宿主项目根目录执行 **`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` 取流 |
+| ref 增图 | `ref.addNodeFromLibrary` / `ref.connect` 与拖放、连线行为一致 |
+| DTO 往返 | `exportBackendWorkflowJson` → `importBackendWorkflowToFlow` → `replaceFlow`；`condition`/`api`/`script` 经 `data.backendNodeType` |
+| 图校验 | `validateWechenAgentFlow`；可选 `onBeforeSave` 拦截 |
 
 ---
 
@@ -111,7 +361,8 @@ export function AgentPage() {
 ```bash
 npm install
 npm install --prefix playground
-npm run dev
+npm run dev              # Playground 文档站（分 Tab 演示；ref 全表见 ?tab=ref-api，见 playground/README.md）
+npm run dev:minimal      # 仅最小宿主集成（对照 README「快速开始」）
 ```
 
 浏览器地址以终端输出为准（默认 `http://localhost:5173`）。
@@ -120,8 +371,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,11 +1,17 @@
 import { CSSProperties, ReactNode } from 'react';
 import { ComponentLibraryGroup, WechenAgentComponentLibraryList } from './config/componentLibraryConfig';
-import { WechenAgentEditorRef, WechenAgentFlowJson, WechenAgentHeaderActionsRenderContext, WechenAgentSnapshot } from './flowTypes';
+import { WechenAgentEditorRef, WechenAgentFlowJson, WechenAgentHeaderActionsRenderContext, WechenAgentHeaderLeadingRenderContext, WechenAgentSnapshot, WechenBeforeRemoveEdgeFn, WechenBeforeRemoveNodeFn, WechenBeforeSaveFn } from './flowTypes';
 import { WechenAgentRenderFlowNodeFn } from './WechenAgentEditorContext';
 import { WechenAgentRenderNodeConfigFn } from './panels/NodeConfigPanel';
 import { WechenAgentRenderConfigPanelFn } from './wechenAgentConfigPanel';
+import { WechenAgentEditorLocaleMessages, WechenAgentEditorLocaleTranslateFn } from './i18n/defaultLocaleMessages';
+/** 编排语义：图为可执行 AI 流程结构；节点为功能模块，连线为执行顺序/控制流（持久化 `flow` 供运行时消费）。 */
+export type WechenConfigSiderTitleContext = {
+    kind: "node" | "edge" | null;
+};
+export type WechenConfigSiderTitleFn = (ctx: WechenConfigSiderTitleContext) => string;
 export interface WechenAgentEditorProps {
-    /** 顶栏标题；不传则使用 `initialFlow.title`，再没有则使用内置 `DEFAULT_TITLE` */
+    /** 顶栏标题；不传则使用 `initialFlow.title`，再没有则使用 `LOCALE_KEYS.HEADER_DEFAULT_TITLE`（默认「Agent 编辑」） */
     title?: string;
     /**
      * 初始画布，结构与保存时 **`WechenAgentSnapshot.flow`** 完全一致（`WechenAgentFlowJson`：`title?` + `nodes` + `edges`）。
@@ -22,8 +28,8 @@ export interface WechenAgentEditorProps {
      */
     mapComponentLibraryList?: (list: WechenAgentComponentLibraryList) => WechenAgentComponentLibraryList;
     /**
-     * 自定义画布节点渲染；参数为 React Flow `NodeProps`（含 `id`、`data`、`type`、`selected` 等）。
-     * 若使用自定义节点，请自行放置 `Handle` 以保留连线能力。
+     * 自定义画布节点 **内容区**（字段与样式）；参数为 React Flow `NodeProps`。
+     * 内置外壳与接线桩（四边感应或 `data.flowHandles`）始终保留；**勿** 在返回值内放置 `Handle`。
      */
     renderFlowNode?: WechenAgentRenderFlowNodeFn;
     /**
@@ -38,7 +44,13 @@ export interface WechenAgentEditorProps {
      */
     renderConfigPanel?: WechenAgentRenderConfigPanelFn;
     /**
-     * 自定义顶栏 **右侧** 操作区（左侧 CRAFT + 标题不变）。未传时显示默认「保存」「测试运行」。
+     * 自定义顶栏 **左侧** leading 区（默认 `Title` + 解析后的 `headerTitle`）。
+     * 返回 `null` / `undefined` 时左侧为空白（不显示默认标题）。
+     * 改标题数据仍用 `title` prop / `replaceFlow`；本回调仅负责呈现。
+     */
+    renderHeaderLeading?: (ctx: WechenAgentHeaderLeadingRenderContext) => ReactNode;
+    /**
+     * 自定义顶栏 **右侧** 操作区。未传时显示默认「保存」「测试运行」。
      * 返回 `null` / `undefined` 时右侧为空白（不显示默认按钮）。
      */
     renderHeaderActions?: (ctx: WechenAgentHeaderActionsRenderContext) => ReactNode;
@@ -46,6 +58,22 @@ 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;
+    /**
+     * 保存前回调；同步返回 **`false`** 时取消该次保存（顶栏与 `ref.save()`）。
+     * `readOnly` / `readingMode` 下 **不调用**。
+     */
+    onBeforeSave?: WechenBeforeSaveFn;
     /**
      * 为真时禁止对图的增删改（拖入、连线、删除键、拖动节点等）；仍允许平移/缩放。
      * 标志会传入 `renderConfigPanel` / `renderNodeConfig` 便于禁用表单。
@@ -62,6 +90,22 @@ export interface WechenAgentEditorProps {
     className?: string;
     /** 透传根 `Layout` 的 `style`（在默认宽高之后合并，便于覆盖） */
     style?: CSSProperties;
+    /**
+     * 编辑器壳层 + 内置回退路径的 **语言包大 JSON**（**key 为默认中文**，如 `"保存"`、`"配置"`）。
+     *
+     * - **未传**：始终显示内置中文（`DEFAULT_ZH_CN`），与 antd `ConfigProvider`、浏览器语言无关。
+     * - **已传**：仅以本对象为准；缺失 key 显示 key 字符串，**不回退**中文。
+     *   生产请传入与 `exportWechenAgentEditorLocaleBundle()` 同 key 集合的完整译文，
+     *   或先用 `mergeWechenAgentEditorLocaleMessages` 在宿主侧合并成整包。
+     *
+     * 自定义 `renderConfigPanel` / `renderFlowNode` 内业务文案由宿主自行 i18n。
+     */
+    localeMessages?: WechenAgentEditorLocaleMessages;
+    /** 优先于 `localeMessages`；`defaultText` 来自 `DEFAULT_ZH_CN[key]`。 */
+    localeTranslate?: WechenAgentEditorLocaleTranslateFn;
+    /** 覆盖右侧栏外框标题；未传时使用 `LOCALE_KEYS.SIDER_CONFIG_TITLE`（默认「配置」）。 */
+    configSiderTitle?: string | WechenConfigSiderTitleFn;
 }
+export type { WechenAgentEditorLocaleMessages, WechenAgentEditorLocaleTranslateFn, } from './i18n/defaultLocaleMessages';
 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,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;AAc5E,OAAO,KAAK,EACV,qBAAqB,EACrB,+BAA+B,EAChC,MAAM,iCAAiC,CAAC;AAuBzC,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,qCAAqC,EACrC,qCAAqC,EACrC,mBAAmB,EAEnB,wBAAwB,EACxB,wBAAwB,EACxB,kBAAkB,EAEnB,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;AAI/E,OAAO,KAAK,EACV,+BAA+B,EAC/B,kCAAkC,EACnC,MAAM,8BAA8B,CAAC;AAMtC,iEAAiE;AAEjE,MAAM,MAAM,6BAA6B,GAAG;IAC1C,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,CAAC,GAAG,EAAE,6BAA6B,KAAK,MAAM,CAAC;AAEtF,MAAM,WAAW,sBAAsB;IACrC,6FAA6F;IAC7F,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;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,CAAC,GAAG,EAAE,qCAAqC,KAAK,SAAS,CAAC;IAChF;;;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,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC;;;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;IACtB;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,+BAA+B,CAAC;IACjD,kEAAkE;IAClE,eAAe,CAAC,EAAE,kCAAkC,CAAC;IACrD,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,GAAG,wBAAwB,CAAC;CACtD;AAED,YAAY,EACV,+BAA+B,EAC/B,kCAAkC,GACnC,MAAM,8BAA8B,CAAC;AAyqBtC,eAAO,MAAM,iBAAiB,yHA4F7B,CAAC"}

package/dist/WechenAgentEditorContext.d.ts

@@ -1,8 +1,13 @@
 import { NodeProps } from '@xyflow/react';
 import { ReactNode } from 'react';
+/**
+ * 自定义画布节点 **内容区**（字段展示与样式）。
+ * 内置节点外壳、选中态与接线桩（`ZoneHandles` / `DeclaredHandles`）由包保留；
+ * **勿** 在返回值内放置 `@xyflow/react` `Handle`。
+ */
 export type WechenAgentRenderFlowNodeFn = (props: NodeProps) => ReactNode;
 export interface WechenAgentEditorRenderContextValue {
-    /** 自定义画布节点外观；未设置时使用内置 MainAgent / Card / Pill 节点 UI */
+    /** 自定义节点内容区；未设置时使用内置默认字段块 */
     renderFlowNode?: WechenAgentRenderFlowNodeFn;
 }
 export declare const WechenAgentEditorRenderContext: import('react').Context<WechenAgentEditorRenderContextValue | null>;

package/dist/WechenAgentEditorContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WechenAgentEditorContext.d.ts","sourceRoot":"","sources":["../src/WechenAgentEditorContext.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,MAAM,MAAM,2BAA2B,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,SAAS,CAAC;AAE1E,MAAM,WAAW,mCAAmC;IAClD,uDAAuD;IACvD,cAAc,CAAC,EAAE,2BAA2B,CAAC;CAC9C;AAED,eAAO,MAAM,8BAA8B,qEACsB,CAAC;AAElE,wBAAgB,0BAA0B,IAAI,mCAAmC,CAEhF"}
+{"version":3,"file":"WechenAgentEditorContext.d.ts","sourceRoot":"","sources":["../src/WechenAgentEditorContext.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,SAAS,CAAC;AAE1E,MAAM,WAAW,mCAAmC;IAClD,6BAA6B;IAC7B,cAAc,CAAC,EAAE,2BAA2B,CAAC;CAC9C;AAED,eAAO,MAAM,8BAA8B,qEACsB,CAAC;AAElE,wBAAgB,0BAA0B,IAAI,mCAAmC,CAEhF"}

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;AAgCb,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;AA+HD;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,mBAAmB,GAAG,mBAAmB,EAChD,IAAI,EAAE,yBAAyB,GAC9B,yBAAyB,CAY3B;AA2DD;;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"}