wechen-agent-editor-v1 1.0.0 → 1.0.2

package/README.md

@@ -1,26 +1,24 @@
-# @li/wechen-agent
+# wechen-agent-editor-v1
 
-**@li/wechen-agent** 是一个可发布的 **Agent 流程编排编辑器** React 组件库：**画布上的图语义为可执行的 AI 流程**——**节点** 表示 **功能模块**，**连线** 表示 **执行顺序 / 控制流**（不是仅画关系图）；持久化的 `flow` 供宿主 **运行时或执行引擎** 消费。技术形态为左侧组件库（**可拖入画布**）、中间 **@xyflow/react** 画布、右侧 **节点 / 连线** 配置（antd + **Monaco Editor** 编辑 System Prompt 等）。适用于在宿主应用中嵌入「可执行 Agent / MCP 编排」类界面。
+**wechen-agent-editor-v1** 是一个可发布的 **Agent 流程编排编辑器** React 组件库：**画布上的图语义为可执行的 AI 流程**——**节点** 表示 **功能模块**，**连线** 表示 **执行顺序 / 控制流**（不是仅画关系图）；持久化的 `flow` 供宿主 **运行时或执行引擎** 消费。技术形态为左侧组件库（**可拖入画布**）、中间 **@xyflow/react** 画布、右侧 **节点 / 连线** 配置（antd + **Monaco Editor** 编辑 System Prompt 等）。适用于在宿主应用中嵌入「可执行 Agent / MCP 编排」类界面。
+
+> **npm 包名**：安装与 `import` 路径均以仓库根目录 **`package.json` 的 `name`** 为准（当前为 **`wechen-agent-editor-v1`**）。历史文档或内部示例若出现 **`@li/wechen-agent`**，请视为**曾用别名**，以 `package.json` 为准。
 
 > **BREAKING（包名）**：若你曾使用旧包名 `my-react-antd-widget`，请改为安装本包并更新 import。  
-> **BREAKING（peer）**：自 Monaco 集成起，宿主必须安装 **`monaco-editor`** 与 **`@monaco-editor/react`**，并配置 **Monaco worker**（见下文）。  
+> **BREAKING（Monaco）**：自 Monaco 集成起，需在宿主入口配置 **Monaco worker**（见下文）；运行时依赖会随本包 **`dependencies`** 一并安装，无需在命令行单独列出。  
 > **BREAKING（initialFlow）**：未传 `initialFlow` 时为 **空画布**（无内置示例节点）。若依赖旧版「零配置即出现示例图」，请显式传入 `initialFlow={cloneWechenAgentFlow(defaultInitialFlow)}`（需同时 import `cloneWechenAgentFlow` 与 `defaultInitialFlow`）。
 
 
-## 依赖（peer）
+## 依赖（安装）
 
-宿主应用 **必须** 自行安装：
+**最少一行**（`react`、`antd`、`@xyflow/react`、`monaco-editor` 等作为本包 **`dependencies`**，会随安装 **自动解析**）：
 
 ```bash
-npm install @li/wechen-agent react react-dom antd @xyflow/react monaco-editor @monaco-editor/react
+npm install wechen-agent-editor-v1
 ```
 
-若你发布为 **非 scoped** 包，将命令中的 `@li/wechen-agent` 换成 `package.json` 里的实际 `name`。
-
-- `react` / `react-dom`：建议 18+
-- `antd`：建议 5+
-- `@xyflow/react`：建议 12+（React Flow，拖拽编排核心）
-- `monaco-editor` + `@monaco-editor/react`：与根目录 `peerDependencies` 大版本对齐（用于 System Prompt 等代码编辑）
+- **`node_modules` 中仍会出现** `react`、`antd` 等传递依赖，属正常；无需在宿主 `package.json` 里逐个手写，除非你希望 **显式锁定版本** 或与业务线其他包 **对齐同一 React 大版本**（减少多份 `react` 的风险）。
+- 版本范围以本包 `package.json` 的 **`dependencies`** 为准；建议 **React 18+**、**antd 5+**、**@xyflow/react 12+**。
 
 ### 从包导入（ESM）
 
@@ -34,7 +32,7 @@ import {
   defaultInitialFlow,
   type WechenAgentEditorRef,
   type WechenAgentSnapshot,
-} from "@li/wechen-agent";
+} from "wechen-agent-editor-v1";
 ```
 
 **主要导出一览**（完整列表以 `src/index.ts` 为准）：
@@ -68,7 +66,7 @@ import { ConfigProvider } from "antd";
 import {
   WechenAgentEditor,
   type WechenAgentSnapshot,
-} from "@li/wechen-agent";
+} from "wechen-agent-editor-v1";
 
 export function AgentPage() {
   return (
@@ -116,7 +114,7 @@ export function AgentPage() {
 
 ```tsx
 import { Button, Space } from "antd";
-import type { WechenAgentHeaderActionsRenderContext } from "@li/wechen-agent";
+import type { WechenAgentHeaderActionsRenderContext } from "wechen-agent-editor-v1";
 
 <WechenAgentEditor
   renderHeaderActions={(ctx: WechenAgentHeaderActionsRenderContext) => (
@@ -144,53 +142,89 @@ npm run dev
 
 ## 构建与发布到 npm
 
-维护者或 CI 在发版前建议完成下列 **自检**：
+以下面向 **维护者** 与 **CI**。**npm 包名、版本号** 以仓库根目录 **`package.json` 的 `name` / `version`** 为唯一权威（当前包名为 **`wechen-agent-editor-v1`**），请勿依赖本文档中可能出现的示例数字。
 
-1. **依赖**：宿主侧 peer 与业务线 lockfile 可解析（见上文版本范围）。
+### 发布前自检
+
+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`**），无意外把 `playground` 或源码打进包。
-4. **测试**（可选）：`npm test`（Vitest，见 `src/**/*.test.ts`）。
-5. **版本号**：在 `package.json` 提升 `version`；若团队维护变更说明，可同步更新 **CHANGELOG**（本仓库未强制附带该文件，由发布流程决定）。
+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 run pack:check
 npm test
+npm run pack:check
+```
+
+### 宿主入口与构建产物
+
+**集成方**仅通过 **`package.json` `name`** 对应的 **根路径** 导入，例如：
+
+```ts
+import { WechenAgentEditor } from "wechen-agent-editor-v1";
+```
+
+**构建产物**为 **`dist/index.js`**（类型声明 **`dist/index.d.ts`**），由 **`src/index.ts`** 聚合导出；请勿依赖未文档化的深层路径。**公开 API** 概览见上文「主要导出一览」，完整符号以 `src/index.ts` 分组为准。
+
+### 发布流程与生命周期
+
+执行 **`npm publish`** 或 **`npm run release`** 时，npm 会先运行 **`prepublishOnly`**（已设为 `npm run build`），再上传。
+
+- **请勿**在 `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
 ```
 
-执行 `npm publish`（或 `npm run publish`）时，npm 会先运行 **`prepublishOnly`**（已设为 `npm run build`），再上传。**`files`** 显式包含 **`dist/`** 与 **`LICENSE`**；`README` 等会按 npm 默认规则一并打入包。不含 `monaco-editor` 源码树与 `playground`。
+若将来包名改为 **`@scope/pkg`**（scoped），需对该 **scope** 拥有发布权限，必要时使用 `npm login --scope=@scope`，且 **scoped 包首次**发布到公共注册表通常需要 `npm publish --access public`。
 
-### 首次发布到 npm（操作清单）
+**发布**：
 
-**版本号含义**：`package.json` 中 **`version`** 当前为 **1.0.0**，表示以 **语义化版本** 首次公开发布；之后 **`MAJOR`** 不兼容 API 变更、**`MINOR`** 向后兼容功能、**`PATCH`** 修订。若需先发预览版，可改用 **0.x** 并在文档中说明。
+```bash
+npm publish
+# 或（项目脚本；含 --access public，与公开注册表默认行为一致）
+npm run release
+```
 
-**发布入口（宿主应使用）**：仅通过包名根路径导入，例如 `import { WechenAgentEditor } from "@li/wechen-agent"`。**构建产物**为 **`dist/index.js`**（类型声明 **`dist/index.d.ts`**），由源码 **`src/index.ts`** 聚合导出；请勿依赖未文档化的深层路径。**公开 API** 概览见上文「主要导出一览」，完整符号以 `src/index.ts` 分组为准。
+**国内网络（可选）**：日常可使用 **npmmirror** 加速 `npm install`；**发布到 npm 官方** 必须使用 **`https://registry.npmjs.org/`**。根目录提供一键切换与「发版后恢复镜像」脚本（修改本机 `npm config registry`，发版前可先 `npm run registry:show` 查看当前值）：
 
-**发布前**：将 `package.json` 中 **`repository` / `bugs` / `homepage`** 里的占位地址（`your-org/wechen-agent`）替换为 **真实 Git 仓库** URL，便于 npm 页展示与问题反馈。
+```bash
+npm run registry:show          # 查看当前默认 registry
+npm run registry:npmjs         # 切到 npm 官方（发版前）
+npm run registry:npmmirror      # 切到 npmmirror（原淘宝镜像，装依赖常用）
+npm run release:cn             # 先切官方 → npm publish → 成功后再切回 npmmirror
+```
 
-**前置条件**：已安装 **Node.js（建议 LTS）** 与 **npm**；在 [npmjs.com](https://www.npmjs.com/) 拥有账号。发布 **`@li/...` scoped 包** 前，确认你对 **`@li` 组织** 具有 **publish** 权限（或由组织管理员授权）。
+**发后验证**（将包名换成与 `package.json` `name` 一致）：
 
-1. **本地校验**  
-   - `npm install`（或 CI 用 `npm ci`）  
-   - `npm run build`  
-   - `npm test`（可选，Vitest）  
-   - `npm run pack:check` 查看将要上传的 tarball 内容  
+```bash
+npm view wechen-agent-editor-v1 version
+```
 
-2. **登录 npm**  
-   - `npm login`（若仅用 scope：`npm login --scope=@li`）  
-   - `npm whoami` 确认当前用户  
+在空目录新建最小项目并烟测：
+
+```bash
+npm install wechen-agent-editor-v1
+```
 
-3. **发布**（scoped 包首次需公开作用域）  
-   - `npm publish --access public`  
-   - 或：`npm run publish`（脚本已等价包含上述参数）  
+### 元数据占位
 
-4. **发后验证**  
-   - `npm view @li/wechen-agent version`  
-   - 在空目录新建最小项目：`npm install @li/wechen-agent`，再 `import { WechenAgentEditor } from "@li/wechen-agent"` 做一次烟测  
+发版前建议将 `package.json` 中 **`repository` / `bugs` / `homepage`** 里的占位地址（如 `your-org/wechen-agent`）替换为 **真实 Git 仓库** URL，便于 npm 页面展示与问题反馈。**占位未替换时** npm 项目页上的「仓库」链接不可用，建议在 **对外公开发布前** 完成替换。
 
 ## 技术说明
 
-- 构建：Vite `build.lib`，`react`、`react-dom`、`antd`、`@xyflow/react`、`monaco-editor`、`@monaco-editor/react` 均为 **external**。
+- 构建：Vite `build.lib`，`react`、`react-dom`、`antd`、`@xyflow/react`、`monaco-editor`、`@monaco-editor/react` 均为 **external**（**不打进 `dist`**，由安装本包时带入的 **`dependencies`** 在运行时解析）。
 - 组件库条目拖入画布时，使用 MIME `application/reactflow` 与载荷前缀 `scope:"wechen-agent"`；宿主可 import `WECHEN_AGENT_FLOW_DRAG_MIME` 与编解码函数以对齐自定义侧栏。
 - 顶栏 **保存** / **测试运行** 通过 `onSave`、`onTestRun` 传出 `WechenAgentSnapshot`：`flow` 为与 `initialFlow` 同形的 **完整对象**（推荐）；`flowJson` 为兼容用字符串。
 - 画布 **Controls** 使用 `showInteractive={false}` 时隐藏「锁定交互」开关，**缩放 / 适应视图** 仍可用。

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * @packageDocumentation
- * @li/wechen-agent — 可执行 AI 流程编排编辑器（节点=模块，连线=顺序/控制流；非仅关系图）。
+ * wechen-agent-editor-v1 — 可执行 AI 流程编排编辑器（节点=模块，连线=顺序/控制流；非仅关系图）。
  *
  * **宿主必做**
  * - 安装下方 **peer** 依赖，并在入口引入 `@xyflow/react/dist/style.css`。
@@ -9,7 +9,7 @@
  * **最小示例**
  * ```tsx
  * import "@xyflow/react/dist/style.css";
- * import { WechenAgentEditor } from "@li/wechen-agent";
+ * import { WechenAgentEditor } from "wechen-agent-editor-v1";
  * <WechenAgentEditor onSave={(s) => api.save(s.flow)} />
  * ```
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wechen-agent-editor-v1",
-  "version": "1.0.0",
-  "description": "Wechen Agent — executable AI flow orchestration editor (React Flow): nodes as modules, edges as execution order; Monaco + Ant Design, for npm",
+  "version": "1.0.2",
+  "description": "Wechen Agent：可执行的 AI 流程编排编辑器（React Flow），节点即模块、边即执行顺序；Monaco + Ant Design，面向 npm",
   "license": "MIT",
   "keywords": [
     "react",
@@ -46,9 +46,13 @@
     "prepublishOnly": "npm run build",
     "dev": "npm --prefix playground run dev",
     "pack:check": "npm pack --dry-run",
-    "publish": "npm publish --access public"
+    "release": "npm publish --access public",
+    "release:cn": "npm run registry:npmjs && npm publish --access public && npm run registry:npmmirror",
+    "registry:show": "npm config get registry",
+    "registry:npmjs": "npm config set registry https://registry.npmjs.org/",
+    "registry:npmmirror": "npm config set registry https://registry.npmmirror.com/"
   },
-  "peerDependencies": {
+  "dependencies": {
     "@monaco-editor/react": "^4.6.0",
     "@xyflow/react": ">=12.0.0",
     "antd": ">=5.0.0",
@@ -57,16 +61,10 @@
     "react-dom": ">=18.0.0"
   },
   "devDependencies": {
-    "@monaco-editor/react": "^4.6.0",
     "@types/node": "^20.14.0",
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.1",
     "@vitejs/plugin-react": "^4.3.4",
-    "@xyflow/react": "^12.3.6",
-    "antd": "^5.22.1",
-    "monaco-editor": "^0.45.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
     "typescript": "~5.6.3",
     "vite": "^5.4.11",
     "vite-plugin-dts": "^4.3.0",