dwf-ai-connector 0.1.1 → 0.1.3

package/README.md

@@ -3,7 +3,7 @@
 DWF AI Connector 是一个面向 DWF（低代码平台）的 AI Agent 控制台，帮助用户通过自然语言与 DWF 环境交互，完成数据建模、应用建模、对象管理等操作。
 
 它包含一个 React 前端、多个 Node.js 后端服务，以及 MCP（Model Context Protocol）工具服务，支持通过浏览器或第三方 MCP 客户端使用。
-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
+
 ---
 
 ## 架构概览
@@ -227,7 +227,22 @@ npm install -g .
 dwf-ai-connector
 ```
 
-> **注意**：Windows 下 `npm install -g .` 会创建指向源码目录的 symlink，因此修改代码后只需重新 `npm run build` 即可生效。但如果修改了 `package.json` 的 `bin` / `files` 字段，需要重新 `npm install -g .`。
+> **注意**：Windows 下 `npm install -g .` 会创建指向源码目录的 symlink，因此修改代码后只需重新 `npm run build` 即可生效。但如果修改了 `package.json` 的 `bin` / `files` / `dependencies` 字段，需要重新 `npm install -g .`。
+
+### 开发与测试全局安装
+
+如果你正在修改 CLI 代码并想通过全局安装验证：
+
+```powershell
+# 修改代码后
+npm run build
+
+# 重新全局安装（因为 package.json 可能变了）
+npm install -g .
+
+# 运行测试
+dwf-ai-connector
+```
 
 ### CLI 参数
 
@@ -268,18 +283,32 @@ CLI 默认使用以下端口和环境变量，可通过标准环境变量覆盖
 ## 发布到 npm
 
 ```bash
-# 1. 确保已登录
-npm whoami
+# 1. 确保已登录到官方 registry（不要指向 cnpm 等镜像）
+npm whoami --registry https://registry.npmjs.org/
 
 # 2. 发布（prepack 自动执行 npm run build）
-npm publish
+npm publish --registry https://registry.npmjs.org/ --access public
 ```
 
-`package.json` 的 `files` 字段控制发布内容，仅包含：
-- `bin/` — CLI 入口
+### 发布注意事项
+
+- **Registry**：如果本地 `npm config get registry` 返回的是 `https://registry.npmmirror.com/` 等镜像，必须显式加 `--registry https://registry.npmjs.org/`，否则 `npm login` 和 `npm publish` 都会指向镜像而失败。
+- **2FA**：如果账号开启双因素认证，普通密码登录无法 publish。请使用 **Classic Token - Automation** 类型或 **Granular Access Token（启用 Bypass 2FA）**，并通过 `npm config set //registry.npmjs.org/:_authToken=你的token` 设置。
+- **版本号**：每次发布必须提升 `package.json` 的 `version` 字段。`prepack` 会自动重新 build，确保 `dist/` 是最新的。
+- **测试发布**：正式发布前可用 `npm pack --dry-run` 预览 tarball 内容。
+
+`package.json` 的 `files` 字段控制发布内容，包含：
+
+- `bin/` — CLI 入口（`dwf-ai-connector.js` + `postinstall.js`）
 - `apps/web/dist/` — 前端构建产物
+- `packages/shared/package.json` + `dist/` — 共享类型包
 - `services/*/dist/` — 各服务构建产物
-- `packages/*/dist/` — 共享包构建产物
+- `services/agent-runtime/skills/builtin/` — 内置 Skills
+- `services/dwf-cli/config/` — CLI 工具注册表
+- `services/dwf-mcp-server/package.json` + `dist/` + `config/` — MCP 服务
+- `README.md`
+
+内部 workspace 包（`@dwf/shared`、`@dwf/dwf-mcp-server`）不会作为独立包发布。安装时 `postinstall` 脚本会自动把它们复制到 `node_modules/@dwf/` 下，供运行时解析。
 
 ## 开发命令
 
@@ -305,6 +334,68 @@ npm run dev -w @dwf/dwf-backend
 
 ## 常见问题
 
+### 全局安装后启动报错 `Cannot find package 'xxx'`
+
+原因：npm 全局安装时，`@dwf/shared` 和 `@dwf/dwf-mcp-server` 这两个内部 workspace 包没有自动进入 `node_modules/@dwf/`，postinstall 脚本没有正确执行。
+
+解决：
+
+1. 确认安装时 postinstall 已执行（重新安装）：
+   ```bash
+   npm uninstall -g dwf-ai-connector
+   npm install dwf-ai-connector -g
+   ```
+
+2. 检查目录是否存在：
+   ```bash
+   ls "$(npm root -g)/dwf-ai-connector/node_modules/@dwf/shared/dist/index.js"
+   ls "$(npm root -g)/dwf-ai-connector/node_modules/@dwf/dwf-mcp-server/dist/index.js"
+   ```
+
+3. 如果确实缺失，可能是 `npm install` 加了 `--ignore-scripts`。手动执行：
+   ```bash
+   cd "$(npm root -g)/dwf-ai-connector"
+   node bin/postinstall.js
+   ```
+
+### 全局安装后启动报错 `EACCES` / `EPERM`
+
+Windows 下可能是旧安装残留导致。关闭所有 node 进程后删除残留目录：
+
+```powershell
+# 结束所有 node 进程
+Get-Process node | Stop-Process -Force
+
+# 删除残留安装目录
+Remove-Item -Recurse -Force "$env:APPDATA\nvm\v22.17.0\node_modules\dwf-ai-connector"
+
+# 重新安装
+npm install dwf-ai-connector -g
+```
+
+### 端口被占用
+
+CLI 默认使用 9088 / 5180 / 5190。如果启动失败提示 `EADDRINUSE`：
+
+```powershell
+# 查找占用端口的进程
+Get-NetTCPConnection -LocalPort 9088,5180,5190 | Select-Object LocalPort, OwningProcess
+
+# 结束对应进程
+Stop-Process -Id <PID> -Force
+```
+
+### npm login 跳转到 cnpm 或返回 401/404
+
+原因：本地 registry 配置成了镜像。
+
+解决：所有 npm 发布命令都显式指定官方 registry：
+
+```bash
+npm login --registry https://registry.npmjs.org/
+npm publish --registry https://registry.npmjs.org/ --access public
+```
+
 ### 启动时报错 `PostgreSQL dependencies not available`
 
 原因：当前 `DATABASE_URL` 以 `postgresql://` 开头，但工作区没有安装 `pg` 包。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dwf-ai-connector",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "DWF AI Connector - AI Agent console for DWF low-code platform",
   "license": "MIT",
   "author": "DWF Team",
@@ -36,13 +36,16 @@
   "files": [
     "bin/",
     "apps/web/dist/",
+    "packages/shared/package.json",
     "packages/shared/dist/",
     "services/agent-gateway/dist/",
     "services/agent-runtime/dist/",
     "services/agent-runtime/skills/builtin/",
     "services/dwf-backend/dist/",
+    "services/dwf-backend/config/",
     "services/dwf-cli/dist/",
     "services/dwf-cli/config/",
+    "services/dwf-mcp-server/package.json",
     "services/dwf-mcp-server/dist/",
     "services/dwf-mcp-server/config/",
     "README.md"

package/packages/shared/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@dwf/shared",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}