wechen-agent-editor-v1 1.0.7 → 1.0.8

package/README.md

@@ -1,139 +1,76 @@
 # 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`）。
+---
 
-
-## 依赖（安装）
-
-本包将 **`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`
+### Peer 依赖（须由宿主安装）
 
-npm 7+ 会对 **整棵依赖树**做严格 peer 校验；安装 **`wechen-agent-editor-v1`** 往往只是 **触发一次完整解析**，冲突可能来自 **宿主里早已存在的包**，**不一定与本包 `peerDependencies` 声明矛盾**。
+`react`、`react-dom`、`antd`（建议 5+）、`monaco-editor`、`@monaco-editor/react`。请在 `package.json` 中显式声明并与业务栈版本对齐。
 
-**与本 issue 一致的两类典型冲突**（看 `npm install` 日志里 **While resolving …** 指向谁）：
+**`@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 运行时。
 
-| 类型 | 常见表现 | 建议先做的排查 |
-|------|----------|----------------|
-| **`@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 或相关插件** |
+### 安装失败（`ERESOLVE`）
 
-**「临时 unblock」与「根治」**（勿与下文「多份 React」混淆——那是 **安装成功后运行时** 的问题）：
+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` 验证，并计划去掉该放宽）。
 
-| 阶段 | 做法 | 说明 |
-|------|------|------|
-| **临时** | `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`，避免长期掩盖不兼容 |
+### Umi / MFSU
 
-**与「排查：第一次从组件库拖入正常…」的区别**：本节解决 **`npm install` 失败（ERESOLVE）**；该小节解决 **装得上但画布异常**（多为 **多份 `react`**、**样式未进包**，或 **宿主另引 `@xyflow/react` 与本包内置副本冲突**）。
+一般可直接使用。若遇预编译或模块解析异常，可在配置里将 **`wechen-agent-editor-v1`**、**`monaco-editor`**、**`@monaco-editor/react`** 加入 **`mfsu.exclude`**（见 [Umi MFSU](https://umijs.org/docs/api/config#mfsu)），删除 `.umi` 后重启；或用 **`mfsu: false`** 做对比排查。
 
-<details>
-<summary><strong>可选：<code>package.json</code> <code>overrides</code> 示例（npm）</strong> — 仅作参考，须按宿主实际包名与版本调整；优先升级上游</summary>
-
-`overrides` 会 **强制子依赖解析版本**，可能掩盖真实不兼容；合并前请在 **关键页面 + CI build** 验证。
+**依赖示例**（版本请按团队锁定，须满足本包 `peerDependencies`）：
 
 ```json
 {
-  "overrides": {
-    "@ahooksjs/use-request": "^2.0.0"
+  "dependencies": {
+    "@monaco-editor/react": "^4.6.0",
+    "wechen-agent-editor-v1": "^1.0.8"
   }
 }
 ```
 
-上例中的版本号 **仅为占位**——请替换为你们团队已在 **React 18 + 当前 Umi** 下验证过的版本。涉及 **`@ant-design/pro-chat` 与 `antd-style`** 时，更稳妥的路径通常是 **升级 pro-chat** 或按官方矩阵统一 `antd-style` 大版本，而不是长期用 overrides「硬拧」peer。
-
-</details>
+---
 
-### Umi Max（`@umijs/max`）/ Ant Design Pro 类宿主适配清单
+## 使用
 
-以下在本仓库 **无法替你改宿主 `package.json`**，但按此清单在 **业务前端仓库**（如 `iccp-frontend`）操作，可稳定接入 **`wechen-agent-editor-v1`**。
+### 入口与样式
 
-1. **在宿主 `dependencies` 中显式加入**（版本可按团队锁定微调，须满足本包 `peerDependencies`）：
-
-```json
-{
-  "@monaco-editor/react": "^4.6.0",
-  "wechen-agent-editor-v1": "^1.0.7"
-}
+```ts
+import { WechenAgentEditor, type WechenAgentSnapshot } from "wechen-agent-editor-v1";
 ```
 
-若宿主 **另有**页面直接使用 **`@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` 一致。
-
-2. **`npm install` 仍 `ERESOLVE`**：与上文 **「宿主 `npm install wechen-agent-editor-v1` 报 `ERESOLVE`」** 同源；典型顺序仍是 **升级 `@ant-design/pro-chat`（或统一 `antd-style` 大版本）** → **升级 / 调整 `ahooks` 与 Umi 插件链** → 最后再 **`.npmrc`**：`legacy-peer-deps=true`（并记录技术债）。
-
-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`** 做问题隔离。
-
-4. **Monaco worker**：在 Umi 入口最早处完成 **worker 引导**（参考本仓库 `playground/src/monacoBootstrap.ts`），与是否使用 MFSU 无关。
-
-5. **验证**：`npm ls react`、`npm ls @xyflow/react` 无双副本；`max dev` / `max build` 通过；页面内 **拖入 → 连线 → 右侧配置** 烟测。
-
-### 排查：第一次从组件库拖入正常，之后无法连线 / 无法再拖 / 样式怪
-
-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`**。
-
-### 从包导入（ESM）
-
-本包以 **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`。典型写法：
+发布产物中 **`dist/index.js`** 会包含对 **`./style.css`** 的引用，正常情况下图样式会随主入口进入打包结果。若生产环境仍看不到 Flow 全局样式，可增加：
 
 ```ts
-import {
-  WechenAgentEditor,
-  cloneWechenAgentFlow,
-  defaultInitialFlow,
-  type WechenAgentEditorRef,
-  type WechenAgentSnapshot,
-} from "wechen-agent-editor-v1";
+import "wechen-agent-editor-v1/style.css";
 ```
 
-**主要导出一览**（完整列表以 `src/index.ts` 为准）：
+antd 5 为 CSS-in-JS，请用 **`ConfigProvider`** 包裹应用（与官方用法一致）。
 
-| 类别 | 示例符号 |
-|------|-----------|
-| 组件 | `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` … |
+### 嵌入尺寸、`readOnly` 与 `readingMode`
 
-### 样式
+根组件默认 **`height` / `width` 为 `100%`**，可通过 **`className` / `style`** 透传；可选 **`minHeight`**。请保证父级链路上有**明确高度**（如 flex 子项 `flex:1` + `minHeight:0`、固定 `height` 等），否则中间画布可能无法撑满。
 
-- **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`** 导致样式异常。
+- **`readOnly`**：禁止对图的增删改（拖入、连线、删除键、拖动节点等），仍可使用平移/缩放查看。**`readOnly`** 与 **`readingMode`** 会出现在 **`renderConfigPanel` / `renderNodeConfig`** 的入参中，便于对表单设 **`disabled`**。
+- **`readingMode`**：**仅展示中间流程画布**（隐藏顶栏与左右栏），并**禁用选中**与一切改图，适合文档内嵌、大屏预览等纯展示场景（隐含只读）。
 
-Monaco 由 `@monaco-editor/react` 加载；**worker 需在宿主侧配置**，否则编辑器无法初始化。可选方式：
+### Monaco Worker
 
-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 说明。
+必须在**首次渲染编辑器之前**完成 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。
 
-## 使用示例
+### 最小页面
 
 ```tsx
 import { ConfigProvider } from "antd";
-import {
-  WechenAgentEditor,
-  type WechenAgentSnapshot,
-} from "wechen-agent-editor-v1";
+import { WechenAgentEditor, type WechenAgentSnapshot } from "wechen-agent-editor-v1";
 
 export function AgentPage() {
   return (
@@ -141,10 +78,10 @@ export function AgentPage() {
       <WechenAgentEditor
         title="Agent 编辑"
         onSave={(s: WechenAgentSnapshot) => {
-          /* 持久化 s.nodes / s.edges */
+          /* 持久化 s.flow / s.nodes / s.edges */
         }}
         onTestRun={(s) => {
-          /* 触发试运行 */
+          /* 试运行 */
         }}
       />
     </ConfigProvider>
@@ -152,52 +89,24 @@ export function AgentPage() {
 }
 ```
 
-未传 `initialFlow` 时画布为空；需要旧版内置示例图见上文 **BREAKING（initialFlow）** 一行。
-
-**画布连线**：在节点上从 **source** Handle 拖到 **target** Handle 可新建边；**新建边默认带流动动画**（`defaultEdgeOptions`）。选中 **节点** 时右侧为「节点配置」；选中 **连线** 时右侧为「连线配置」，可开关 **动画**、选择 **正向/反向** 流动（`edge.data.wechenFlowDirection`）、编辑可选 **文字标签**，并有 **重连 / Delete 删除** 说明。
-
-**节点 data 合并**：表单与 `renderNodeConfig` 回写使用 **`mergeNodeData`**（亦导出）：嵌套 **对象** 深度合并；**数组** 字段在补丁中出现时 **整段替换**（`Form.List` 常见行为）。自定义 `data` 请保持可 JSON 化。
-
-**`patchNode` / `patchNodeData` 形状**（与 `mergeNodeData` 的 `patch` 一致）：
-
-- **`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` 键」的误解混淆。
+未传 **`initialFlow`** 时为**空画布**。需要内置示例图时，从本包导入 **`defaultInitialFlow`**、**`cloneWechenAgentFlow`** 并传入 `initialFlow={cloneWechenAgentFlow(defaultInitialFlow)}`。
 
-**`patchNode` / `patchNodeData` 与 `patchEdge` 作用层级**：
+### 行为与扩展（摘要）
 
-- **节点**：`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` 不是同一套模型。
+- **连线**：从节点的 source Handle 拖到 target Handle；选中边可在右侧调整动画与方向等。
+- **数据合并**：节点 `data` 的更新遵循导出的 **`mergeNodeData`**（对象深度合并，数组在补丁中出现时整段替换）。`patchNode` / ref 的 **`patchNodeData`** 将补丁合并进 `node.data`；**`patchEdge`** 为边的顶层浅合并。
+- **自定义右侧面板**：可选 **`renderConfigPanel`**（节点与连线统一入口）或 **`renderNodeConfig`**；同时存在时以 `renderConfigPanel` 为准（返回 `undefined` 时回退内置）。
+- **顶栏按钮**：可选 **`renderHeaderActions`**，入参含与默认行为一致的 **`save`** / **`testRun`** 及 **`editorRef`**。
 
-**统一右侧配置 `renderConfigPanel`**（可选）：单一函数同时覆盖 **节点** 与 **连线** 右侧栏。入参为判别联合 `kind: "node" | "edge"`，并提供 **`patchNode`** / **`patchEdge`**，由宿主决定何时调用（不必依赖 Form 即时合并）。对某一选中态返回 **`undefined`** 时回退内置「节点配置」或「连线配置」。与 `renderNodeConfig` 同时传入时，**`renderConfigPanel` 优先**（仅当其对当前选中返回 `undefined` 时再走内置）。类型见导出的 `WechenAgentRenderConfigPanelFn`、`WechenAgentConfigPanelContext`。
+完整类型与符号列表以 **`src/index.ts`** 的导出为准。
 
-**顶栏右侧自定义 `renderHeaderActions`**（可选）：替换顶栏 **右侧** 的「保存」「测试运行」按钮区（左侧 CRAFT 标签与标题不变）。入参为 **`WechenAgentHeaderActionsRenderContext`**：
+### 集成自检
 
-- **`save`** / **`testRun`**：与默认按钮、`ref.save()` / `ref.testRun()` 相同，会触发 **`onSave` / `onTestRun`**（若已传入）。
-- **`editorRef`**：与 `<WechenAgentEditor ref={...} />` 为 **同一 ref 对象**（推荐使用对象 `useRef`），可在自定义工具条中调用 **`getSnapshot`**、`patchNodeData`、`fitView` 等任意 ref API。挂载完成前 **`current` 可能为 `null`**，请在点击回调或 `useEffect` 内使用。
-
-未传 `renderHeaderActions` 时保持默认两个按钮。传入后若返回 **`null` / `undefined`**，右侧 **不显示任何内容**（也不显示默认按钮）；若需要默认 UI，请勿传该 prop。
-
-```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>
-  )}
-/>
-```
+在宿主项目根目录执行 **`npm ls react`**、**`npm ls @xyflow/react`**，确认无意外多版本；完成 **`npm run build`**（或 Umi `max build`）与画布拖放、连线、右侧配置的简单烟测。
 
-宿主入口需在渲染编辑器 **之前** 完成 Monaco worker 引导（见 `playground/src/main.tsx` 与 `monacoBootstrap.ts`）。
+---
 
-## 本地开发（维护本仓库）
+## 本地开发（本仓库）
 
 ```bash
 npm install
@@ -205,94 +114,14 @@ npm install --prefix playground
 npm run dev
 ```
 
-浏览器打开终端提示的地址（默认 `http://localhost:5173`）。
-
-## 构建与发布到 npm
-
-以下面向 **维护者** 与 **CI**。**npm 包名、版本号** 以仓库根目录 **`package.json` 的 `name` / `version`** 为唯一权威（当前包名为 **`wechen-agent-editor-v1`**），请勿依赖本文档中可能出现的示例数字。
-
-### 发布前自检
-
-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**（本仓库未强制附带该文件）。
-
-**根目录一键执行（建议顺序）**：
-
-```bash
-npm install
-npm run build
-npm test
-npm run pack:check
-```
-
-### 宿主入口与构建产物
-
-**集成方**仅通过 **`package.json` `name`** 对应的 **根路径** 导入，例如：
-
-```ts
-import { WechenAgentEditor } from "wechen-agent-editor-v1";
-```
-
-**构建产物**为 **`dist/index.js`**、**`dist/style.css`**（React Flow 全局样式，由入口 JS 自动引用）与类型 **`dist/index.d.ts`**，由 **`src/index.ts`** 聚合导出；请勿依赖未文档化的深层路径。**公开 API** 概览见上文「主要导出一览」，完整符号以 `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`。
-
-**前置条件**：已安装 **Node.js（建议 LTS）** 与 **npm**；在 [npmjs.com](https://www.npmjs.com/) 拥有账号。
-
-**登录**（本包当前为 **unscoped** 名，一般使用全局登录即可）：
-
-```bash
-npm login
-npm whoami
-```
-
-若将来包名改为 **`@scope/pkg`**（scoped），需对该 **scope** 拥有发布权限，必要时使用 `npm login --scope=@scope`，且 **scoped 包首次**发布到公共注册表通常需要 `npm publish --access public`。
-
-**发布**（请先在 **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** 切回镜像，可执行：
-
-```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` 一致）：
-
-```bash
-npm view wechen-agent-editor-v1 version
-```
-
-在空目录新建最小项目并烟测：
-
-```bash
-npm install wechen-agent-editor-v1
-```
+浏览器地址以终端输出为准（默认 `http://localhost:5173`）。
 
-### 元数据占位
+---
 
-发版前建议将 `package.json` 中 **`repository` / `bugs` / `homepage`** 里的占位地址（如 `your-org/wechen-agent`）替换为 **真实 Git 仓库** URL，便于 npm 页面展示与问题反馈。**占位未替换时** npm 项目页上的「仓库」链接不可用，建议在 **对外公开发布前** 完成替换。
+## 维护者：发版
 
-## 技术说明
+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`。
 
-- 构建：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,4 +1,4 @@
-import { ReactNode } from 'react';
+import { CSSProperties, ReactNode } from 'react';
 import { ComponentLibraryGroup, WechenAgentComponentLibraryList } from './config/componentLibraryConfig';
 import { WechenAgentEditorRef, WechenAgentFlowJson, WechenAgentHeaderActionsRenderContext, WechenAgentSnapshot } from './flowTypes';
 import { WechenAgentRenderFlowNodeFn } from './WechenAgentEditorContext';
@@ -46,6 +46,22 @@ export interface WechenAgentEditorProps {
     onSave?: (snapshot: WechenAgentSnapshot) => void;
     /** 测试运行：收到与 `onSave` 同形的 `WechenAgentSnapshot`；具体执行由宿主实现（可为试运行 / 调试） */
     onTestRun?: (snapshot: WechenAgentSnapshot) => void;
+    /**
+     * 为真时禁止对图的增删改（拖入、连线、删除键、拖动节点等）；仍允许平移/缩放。
+     * 标志会传入 `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":"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"}

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { WechenAgentEditorProps } from './WechenAgentEditor';
 export { WechenAgentEditorRenderContext, useWechenAgentEditorRender, } from './WechenAgentEditorContext';
 export type { WechenAgentRenderFlowNodeFn } from './WechenAgentEditorContext';
 export type { WechenAgentRenderNodeConfigFn } from './panels/NodeConfigPanel';
-export type { WechenAgentConfigPanelContext, WechenAgentConfigPanelEdgeContext, WechenAgentConfigPanelNodeContext, WechenAgentRenderConfigPanelFn, } from './wechenAgentConfigPanel';
+export type { WechenAgentConfigPanelContext, WechenAgentConfigPanelEdgeContext, WechenAgentConfigPanelNodeContext, WechenAgentEditorPanelFlags, WechenAgentRenderConfigPanelFn, } from './wechenAgentConfigPanel';
 export type { ComponentLibraryGroup, ComponentLibraryIconSlot, ComponentLibraryItem, WechenAgentComponentLibraryGroupPayload, WechenAgentComponentLibraryItemPayload, WechenAgentComponentLibraryList, } from './config/componentLibraryConfig';
 export { COMPONENT_LIBRARY_GROUP_APP, COMPONENT_LIBRARY_GROUP_MAIN, defaultAppAgentComponentItems, defaultMainAgentComponentItems, fromWechenAgentComponentLibraryList, getDefaultComponentLibraryGroups, isLibraryIconSet, isLibraryIconString, toWechenAgentComponentLibraryList, } from './config/componentLibraryConfig';
 export { appendComponentToLibrary, removeComponentFromLibrary, } from './config/componentLibraryDynamic';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,8BAA8B,CAAC;AAGtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAGlE,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,GAC3B,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAG9E,YAAY,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AAC9E,YAAY,EACV,6BAA6B,EAC7B,iCAAiC,EACjC,iCAAiC,EACjC,8BAA8B,GAC/B,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EACV,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,uCAAuC,EACvC,sCAAsC,EACtC,+BAA+B,GAChC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,6BAA6B,EAC7B,8BAA8B,EAC9B,mCAAmC,EACnC,gCAAgC,EAChC,gBAAgB,EAChB,mBAAmB,EACnB,iCAAiC,GAClC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,kCAAkC,CAAC;AAG1C,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,qCAAqC,EACrC,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrD,YAAY,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,8BAA8B,CAAC;AAGtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAGlE,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,GAC3B,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAG9E,YAAY,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AAC9E,YAAY,EACV,6BAA6B,EAC7B,iCAAiC,EACjC,iCAAiC,EACjC,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EACV,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,uCAAuC,EACvC,sCAAsC,EACtC,+BAA+B,GAChC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,6BAA6B,EAC7B,8BAA8B,EAC9B,mCAAmC,EACnC,gCAAgC,EAChC,gBAAgB,EAChB,mBAAmB,EACnB,iCAAiC,GAClC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,kCAAkC,CAAC;AAG1C,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,qCAAqC,EACrC,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrD,YAAY,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}