wechen-agent-editor-v1 1.0.4 → 1.0.6

package/README.md

@@ -21,6 +21,67 @@ npm install wechen-agent-editor-v1
 - **npm 7+** 安装本包时，一般会 **自动安装缺失的 peer**；仍建议在宿主 `package.json` 中 **显式列出** 上述依赖及版本，便于与业务线对齐并避免重复副本。
 - 版本范围以 **`peerDependencies`** 为准；建议 **React 18+**、**antd 5+**、**@xyflow/react 12+**。
 
+### 宿主 `npm install wechen-agent-editor-v1` 报 `ERESOLVE`
+
+npm 7+ 会对 **整棵依赖树**做严格 peer 校验；安装 **`wechen-agent-editor-v1`** 往往只是 **触发一次完整解析**，冲突可能来自 **宿主里早已存在的包**，**不一定与本包 `peerDependencies` 声明矛盾**。
+
+**与本 issue 一致的两类典型冲突**（看 `npm install` 日志里 **While resolving …** 指向谁）：
+
+| 类型 | 常见表现 | 建议先做的排查 |
+|------|----------|----------------|
+| **`@ant-design/pro-chat` ↔ `antd-style`** | 例如 pro-chat 声明 **`antd-style@^3`**，宿主已用 **`antd-style@^4`** | 在 [npm @ant-design/pro-chat](https://www.npmjs.com/package/@ant-design/pro-chat?activeTab=versions) 查各版本 **peerDependencies**；宿主执行 **`npm ls @ant-design/pro-chat antd-style`** |
+| **`@ahooksjs/use-request`（经 `ahooks` / `@umijs/plugins`）↔ React 18** | peer 仍写 **`react@^16 \|\| ^17`** 等 | **`npm why @ahooksjs/use-request`**；**`npm ls ahooks react`**；按 Umi / ahooks 官方说明 **升级 ahooks 或相关插件** |
+
+**「临时 unblock」与「根治」**（勿与下文「多份 React」混淆——那是 **安装成功后运行时** 的问题）：
+
+| 阶段 | 做法 | 说明 |
+|------|------|------|
+| **临时** | `npm install wechen-agent-editor-v1@<version> --legacy-peer-deps`，或宿主根目录 **`.npmrc`**：`legacy-peer-deps=true` | 仅放宽 **peer 解析**，**不替代**你在 `package.json` 里对本包要求的 **`react` / `@xyflow/react` / …** 的显式声明；上线前请在宿主跑 **`npm run build`**（或 `max build`）并记录技术债 |
+| **根治** | **升级** `@ant-design/pro-chat` 等到与 **`antd-style@4`** 兼容的组合；或 **升级 ahooks / Umi 链** 与 React 18 一致；必要时再用 **`overrides`**（见下折叠示例） | 对齐后应 **去掉** `legacy-peer-deps`，避免长期掩盖不兼容 |
+
+**与「排查：第一次从组件库拖入正常…」的区别**：本节解决 **`npm install` 失败（ERESOLVE）**；该小节解决 **装得上但画布异常**（多为 **多份 `react` / `@xyflow/react`** 或样式未进包）。
+
+<details>
+<summary><strong>可选：<code>package.json</code> <code>overrides</code> 示例（npm）</strong> — 仅作参考，须按宿主实际包名与版本调整；优先升级上游</summary>
+
+`overrides` 会 **强制子依赖解析版本**，可能掩盖真实不兼容；合并前请在 **关键页面 + CI build** 验证。
+
+```json
+{
+  "overrides": {
+    "@ahooksjs/use-request": "^2.0.0"
+  }
+}
+```
+
+上例中的版本号 **仅为占位**——请替换为你们团队已在 **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
+{
+  "@xyflow/react": "^12.3.6",
+  "@monaco-editor/react": "^4.6.0",
+  "wechen-agent-editor-v1": "^1.0.6"
+}
+```
+
+宿主已声明的 **`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**：若开发态 **Monaco 或 xyflow** 白屏、热更新异常，可在 **`.umirc.ts` / `config/config.ts`** 中尝试将 **`monaco-editor`、`@monaco-editor/react`** 加入 **`mfsu.exclude`**（以你项目 Umi 4 文档为准），或暂时关闭 MFSU 做对照。
+
+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** 强制单版本。
@@ -30,7 +91,7 @@ npm install wechen-agent-editor-v1
 
 ### 从包导入（ESM）
 
-本包以 **ESM** 发布（`package.json` 的 `exports["."].import`）。构建会把 **React Flow 全局样式**打进 **`dist/style.css`**，并由 **`dist/index.js`** 自动 `import`；宿主 **只 import 本包即可**，无需再写 `@xyflow/react/dist/style.css`。典型写法：
+本包以 **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 全局样式。若你的打包链 **不处理** 依赖包内的该 `import`，请仍使用兜底：**`import "wechen-agent-editor-v1/style.css"`**。宿主 **无需**再写 `@xyflow/react/dist/style.css`。典型写法：
 
 ```ts
 import {

package/dist/index.js

@@ -1,3 +1,4 @@
+import './style.css';
 import { jsx as s, Fragment as u1, jsxs as M } from "react/jsx-runtime";
 import { BezierEdge as fi, Handle as s1, Position as v1, ReactFlowProvider as ui, useReactFlow as hi, useNodesState as mi, useEdgesState as pi, addEdge as gi, reconnectEdge as zi, ReactFlow as Oi, Background as wi, Controls as Ei } from "@xyflow/react";
 import { Input as E4, Empty as X, Typography as M1, List as S1, Space as h1, Button as O1, Switch as Vi, Segmented as Ni, Form as G, Select as D1, InputNumber as Mi, Card as Hi, Layout as w1 } from "antd";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wechen-agent-editor-v1",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Wechen Agent：可执行的 AI 流程编排编辑器（React Flow），节点即模块、边即执行顺序；Monaco + Ant Design，面向 npm",
   "license": "MIT",
   "keywords": [
@@ -14,7 +14,9 @@
     "antd",
     "ai",
     "flow-editor",
-    "low-code"
+    "low-code",
+    "umijs",
+    "umi"
   ],
   "repository": {
     "type": "git",
@@ -57,7 +59,7 @@
     "registry:npmmirror": "npm config set registry https://registry.npmmirror.com/"
   },
   "peerDependencies": {
-    "@monaco-editor/react": "^4.6.0",
+    "@monaco-editor/react": ">=4.6.0",
     "@xyflow/react": ">=12.0.0",
     "antd": ">=5.0.0",
     "monaco-editor": ">=0.45.0",