dwf-ai-connector

v0.3.23

Published

22 days ago

DWF AI Connector - AI Agent console for DWF low-code platform

0High
0Medium
0Low

satenruiko

dwf ai-agent mcp low-code model-context-protocol agent cli

DWF AI Connector

DWF AI Connector 是一个面向 DWF（低代码平台）的 AI Agent 控制台，帮助用户通过自然语言与 DWF 环境交互，完成数据建模、应用建模、对象管理等操作。

它包含一个 React 前端、多个 Node.js 后端服务，以及 MCP（Model Context Protocol）工具服务，支持通过浏览器或第三方 MCP 客户端使用。

架构概览

Browser / 第三方 MCP 客户端
  │
  ├─▶ apps/web (React + Vite)          前端管理界面  :5174
  │
  ├─▶ agent-gateway (Express)          Agent 控制面  :5180
  │       ├─▶ SQLite / PostgreSQL 持久化
  │       ├─▶ DWF backend (:9088)      环境/MCP 实例管理
  │       └─▶ agent-runtime (:5190)    Agent 执行引擎
  │               ├─▶ pi-coding-agent
  │               ├─▶ MCP 工具 (dwf-mcp-server)
  │               └─▶ dwf-cli 命令行
  │
  └─▶ dwf-backend (Express)            DWF 平台接入  :9088
          ├─▶ SQLite / PostgreSQL 持久化
          └─▶ 动态启动/管理 MCP Server 实例

核心能力

DWF 环境管理：维护多个 DWF 实例连接、端口、账号。
MCP 实例管理：按需启动/停止 DWF MCP Server，选择暴露给 Agent 的工具和实体类白名单。
Agent 配置：绑定模型 Provider、MCP 服务、Skills。
对话式 Agent：通过自然语言调用 DWF 工具，自动完成建模、查询、应用搭建。
Skills 库：可插拔的 Agent 技能，支持内置与用户自定义。
工具进化：收集工具调用上下文，持续优化工具描述。

技术栈

| 层级 | 技术 | |------|------| | 语言 | TypeScript 5.9，ESM | | 运行时 | Node.js >= 20 | | 包管理 | npm workspaces | | 前端 | React 18，Vite 5，Tailwind CSS，lucide-react | | 后端 | Express 5，drizzle-orm，pino | | 数据库 | SQLite（默认）/ PostgreSQL（可选） | | Agent 框架 | @mariozechner/pi-coding-agent | | MCP SDK | @modelcontextprotocol/sdk |

目录结构

dwf-ai-connector/
├── apps/
│   └── web/                    # React 前端
├── packages/
│   └── shared/                 # 共享类型与契约
├── services/
│   ├── dwf-mcp-server/         # DWF MCP 工具服务
│   ├── dwf-backend/            # DWF 平台接入与管理 API
│   ├── agent-runtime/          # Agent 执行引擎
│   ├── agent-gateway/          # Agent 控制面（REST + SSE）
│   ├── dwf-cli/                # 命令行 MCP 客户端
├── .env                        # 本地开发环境变量
├── .env.example                # 环境变量模板
├── Dockerfile.backend          # dwf-backend 生产镜像
├── Dockerfile.gateway          # gateway + web + runtime 生产镜像
├── docker-compose.yml          # 三服务编排模板
├── AGENTS.md                   # 开发规范（给 Coding Agent 阅读）
└── docs/services-guide.md      # 服务使用文档

快速开始（Windows）

以下命令适用于 Windows PowerShell。Linux / macOS / Git Bash 用户可将 $env:XXX="..." 替换为 export XXX=...。

环境要求

Node.js >= 20
npm >= 10
PostgreSQL >= 14（仅在需要 PostgreSQL 模式时安装）

1. 克隆仓库并安装依赖

cd dwf-ai-connector
npm install

默认使用 SQLite，无需安装 PostgreSQL。

2. 配置环境变量

本项目各服务通过 dotenv 从各自工作目录加载 .env。首次下载后，需要分别为以下两个服务创建 .env：

# dwf-backend
Copy-Item services\dwf-backend\.env.example services\dwf-backend\.env

# agent-gateway
Copy-Item services\agent-gateway\.env.example services\agent-gateway\.env

默认内容已适配本地开发（使用 SQLite）。两个服务共享同一个数据库文件 data/connector.db，启动时自动创建。

services/dwf-backend/.env：

DATABASE_URL=file:../../data/connector.db
DWF_BACKEND_BASE_URL=http://127.0.0.1:9088/api/v1
AGENT_SECRET_KEY=dwf-agent-dev-secret

services/agent-gateway/.env：

DATABASE_URL=file:../../data/connector.db
DWF_BACKEND_BASE_URL=http://127.0.0.1:9088/api/v1
AGENT_GATEWAY_PORT=5180
AGENT_RUNTIME_PORT=5190
AGENT_SECRET_KEY=dwf-agent-dev-secret

项目根目录的 .env.example 仅作为总览参考，不会被服务直接读取。

3. 创建 DWF 环境

启动后，在前端 http://localhost:5174/environments 创建 DWF 环境：

| 字段 | 说明 | 示例 | |------|------|------|
| 实例名称 | 环境标识 | 测试环境 | | 实例地址 | DWF 基础地址（含端口） | http://172.21.11.113:6060 | | 用户名 / 密码 | DWF 登录账号 | - |

填写实例地址后点击"探测"，系统会自动从 DWF config.js 获取 Modeler API Base URL 和 App API Base URL。

4. 启动开发环境

npm run dev

启动完成后访问：

前端：http://localhost:5174
Gateway API：http://localhost:5180/agent-api
DWF Backend API：http://localhost:9088/api/v1

可选：使用 PostgreSQL

如果需要使用 PostgreSQL（例如多实例部署或已有 PG 基础设施）：

安装 PostgreSQL 并创建数据库 dwf_ai。
在两个服务的 .env 中配置：

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/dwf_ai

安装 pg 依赖：

npm install pg -w @dwf/dwf-backend
npm install pg -w @dwf/agent-gateway

重新启动服务即可。

生产部署

Docker Compose（推荐）

cd dwf-ai-connector
# 准备 .env
cp .env.example .env
# 启动全部服务
docker-compose up -d

默认暴露端口：

5180：前端 + gateway
9088：dwf-backend

Docker 默认使用 SQLite，两个容器通过共享卷持久化 data/connector.db。

离线环境部署

如果目标服务器无法访问 Docker Hub，可在本地构建镜像后导出上传：

# 本地构建
docker build -f Dockerfile.backend -t dwf-ai-connector-backend:latest .
docker build -f Dockerfile.gateway -t dwf-ai-connector-gateway:latest .

# 导出
docker save dwf-ai-connector-backend:latest -o dwf-backend.tar
docker save dwf-ai-connector-gateway:latest -o dwf-gateway.tar

# 上传到服务器后加载
docker load -i dwf-backend.tar
docker load -i dwf-gateway.tar

全局安装与 CLI 使用

从 npm registry 安装

npm install -g dwf-ai-connector
dwf-ai-connector

从本地源码安装（开发测试）

# 必须先构建
npm run build

# 全局安装（指向本地源码目录）
npm install -g .

# 运行
dwf-ai-connector

注意：Windows 下 npm install -g . 会创建指向源码目录的 symlink，因此修改代码后只需重新 npm run build 即可生效。但如果修改了 package.json 的 bin / files / dependencies 字段，需要重新 npm install -g .。

开发与测试全局安装

如果你正在修改 CLI 代码并想通过全局安装验证：

# 修改代码后
npm run build

# 重新全局安装（因为 package.json 可能变了）
npm install -g .

# 运行测试
dwf-ai-connector

CLI 参数

| 参数 | 默认值 | 说明 | |------|--------|------| | --data-dir <path> | ~/.dwf-ai-connector/data | SQLite 数据目录，数据库文件为 connector.db | | --open | false | 启动成功后自动用系统默认浏览器打开前端页面 |

# 使用自定义数据目录
dwf-ai-connector --data-dir /path/to/data

# 使用项目目录下的 data/（适合本地开发测试）
dwf-ai-connector --data-dir ./data

# 启动后自动打开浏览器
dwf-ai-connector --open

终端输出的 URL 已使用 OSC 8 超链接协议 包装。在 Windows Terminal、VS Code 终端、iTerm2 等现代终端中，URL 会显示为蓝色可点击链接；在不支持的终端（如传统 cmd.exe、PowerShell 5.1 控制台）中会回退为普通文本，可复制后访问。

推荐终端：Windows Terminal

打开方式：按 Win 键搜索 Windows Terminal / 终端，或按 Win + R 输入 wt 回车。
点击链接：启动后输出的 URL 会显示为带下划线的蓝色文字，按住 Ctrl 点击即可在浏览器中打开。
设为默认（Win11）：设置 → 隐私和安全性 → 开发者选项 → 终端 → 选择 Windows Terminal。之后从运行框启动的 cmd/powershell 都会用它打开。

dwf-cli 命令行工具

dwf-cli 是 DWF MCP 的命令行客户端，安装 dwf-ai-connector 后即可直接使用。它会自动发现运行中的 MCP 实例并连接，无需手动查找 URL。

前置条件

dwf-ai-connector 已启动（后端在 :9088）
在 Web UI 中至少启动了一个 MCP 实例

基本用法

# 自动发现并连接到运行中的 MCP 实例
dwf-cli datamodel list-classes

如果只有一个 MCP 实例在运行，dwf-cli 会自动连接。如果有多个，会弹出交互式选择列表。

查看可用 MCP 实例

dwf-cli instances

输出示例：

  MCP instances (backend: http://127.0.0.1:9088/api/v1)

    * [running]   测试环境
                  http://192.168.34.35:9088/api/v1/mcp-instance/proxy/abc123
      [stopped]   生产环境

  * = auto-selected when running dwf-cli without --instance

指定实例

# 按名称选择
dwf-cli datamodel list-classes --instance 测试环境

多个实例运行时的交互选择

dwf-cli datamodel list-classes

输出：

  Multiple MCP instances running:

    [1] 测试环境
    [2] 开发环境

  Select [1-2]: 1

  Connecting to: 测试环境

直连模式（跳过自动发现）

# 直接指定 MCP 端点 URL
dwf-cli datamodel list-classes --server-url http://localhost:30000/mcp

wrapper 专属参数

| 参数 | 说明 | |------|------| | --instance <name> | 按名称选择 MCP 实例 | | --backend-url <url> | 后端 API 地址（默认 http://127.0.0.1:9088/api/v1） | | --server-url <url> | 直连 MCP 端点，跳过自动发现 |

常用命令示例

# 数据模型管理
dwf-cli datamodel list-classes
dwf-cli datamodel create-entity-class --class_name Student --display_name 学生
dwf-cli datamodel list-objects --className Student

# 认证
dwf-cli auth login --host http://192.168.1.100:6060 --username admin
dwf-cli auth status

# Schema 查询
dwf-cli schema tools
dwf-cli schema classes

环境变量

| 变量 | 说明 | |------|------| | DWF_CLI_SERVER_URL | MCP 端点 URL（设置后跳过自动发现） | | DWF_BACKEND_BASE_URL | 后端 API 地址（用于自动发现，默认 http://127.0.0.1:9088/api/v1） | | DWF_CLI_TOOL_REGISTRY | 工具注册表路径（默认自动查找） |

启动后访问

| 服务 | 地址 | |------|------| | 前端 | http://localhost:5180 | | Gateway API | http://localhost:5180/agent-api | | DWF Backend API | http://localhost:9088/api/v1 |

CLI 会依次启动 dwf-backend → agent-gateway（内部自动启动 agent-runtime），并通过健康检查确认就绪后输出访问地址。

环境变量

CLI 默认使用以下端口和环境变量，可通过标准环境变量覆盖：

| 变量 | 默认值 | 说明 | |------|--------|------| | PORT | 9088 | dwf-backend 端口 | | AGENT_GATEWAY_PORT | 5180 | agent-gateway 端口 | | AGENT_RUNTIME_PORT | 5190 | agent-runtime 端口 | | AGENT_SECRET_KEY | dwf-agent-dev-secret | Provider API Key 加密密钥 | | DWF_BACKEND_BASE_URL | http://127.0.0.1:9088/api/v1 | dwf-backend API 基地址 |

发布到 npm

# 1. 确保已登录到官方 registry（不要指向 cnpm 等镜像）
npm whoami --registry https://registry.npmjs.org/

# 2. 发布（prepack 自动执行 npm run build）
npm publish --registry https://registry.npmjs.org/ --access public

发布注意事项

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 + dwf-cli.js + postinstall.js）
apps/web/dist/ — 前端构建产物
packages/shared/package.json + dist/ — 共享类型包
services/*/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/ 下，供运行时解析。

开发命令

# 全量构建
npm run build

# 启动生产服务（gateway 提供前端静态资源）
npm start

# 单独构建某个包
npm run build -w @dwf/dwf-mcp-server
npm run build -w @dwf/agent-runtime
npm run build -w @dwf/agent-gateway
npm run build -w @dwf/web

# 单独开发某个服务
npm run dev -w @dwf/web
npm run dev -w @dwf/agent-gateway
npm run dev -w @dwf/agent-runtime
npm run dev -w @dwf/dwf-backend

常见问题

全局安装后启动报错 `Cannot find package 'xxx'`

原因：npm 全局安装时，@dwf/shared 和 @dwf/dwf-mcp-server 这两个内部 workspace 包没有自动进入 node_modules/@dwf/，postinstall 脚本没有正确执行。

解决：

确认安装时 postinstall 已执行（重新安装）：

npm uninstall -g dwf-ai-connector
npm install dwf-ai-connector -g

检查目录是否存在：

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"

如果确实缺失，可能是 npm install 加了 --ignore-scripts。手动执行：
```
cd "$(npm root -g)/dwf-ai-connector"
node bin/postinstall.js
```

全局安装后启动报错 `EACCES` / `EPERM`

Windows 下可能是旧安装残留导致。关闭所有 node 进程后删除残留目录：

# 结束所有 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：

# 查找占用端口的进程
Get-NetTCPConnection -LocalPort 9088,5180,5190 | Select-Object LocalPort, OwningProcess

# 结束对应进程
Stop-Process -Id <PID> -Force

npm login 跳转到 cnpm 或返回 401/404

原因：本地 registry 配置成了镜像。

解决：所有 npm 发布命令都显式指定官方 registry：

npm login --registry https://registry.npmjs.org/
npm publish --registry https://registry.npmjs.org/ --access public

启动时报错 `PostgreSQL dependencies not available`

原因：当前 DATABASE_URL 以 postgresql:// 开头，但工作区没有安装 pg 包。

解决：如果需要使用 PostgreSQL，安装 pg 依赖：

npm install pg -w @dwf/dwf-backend
npm install pg -w @dwf/agent-gateway

或者将 .env 中的 DATABASE_URL 改回 SQLite 默认值：file:../../data/connector.db。

启动时报错 `client password must be a string`

原因：服务使用 PostgreSQL 连接字符串，但密码为空或格式不正确。

解决：确保以下两个 .env 文件中已正确设置 DATABASE_URL：

services/dwf-backend/.env
services/agent-gateway/.env

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/dwf_ai

并将 postgres:postgres 替换为你本地 PostgreSQL 的实际用户名和密码。

与第三方 MCP 客户端集成

DWF MCP Server 支持 stdio、streamable-http、sse 三种传输模式。当前前端默认使用 streamable-http。

对于 OpenCode 等支持 Remote MCP 的客户端，可通过 dwf-backend 的代理端点访问：

{
  "mcp": {
    "dwf-dev": {
      "type": "remote",
      "url": "http://YOUR_HOST:9088/api/v1/mcp-instance/proxy/YOUR_MCP_INSTANCE_ID"
    }
  }
}

注：OpenCode 直连 MCP 目前处于调研阶段，相关路由与网络配置后续会进一步优化。

开发规范

详见 AGENTS.md。

许可证

LICENSE

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

DWF AI Connector

架构概览

核心能力

技术栈

目录结构

快速开始（Windows）

环境要求

1. 克隆仓库并安装依赖

2. 配置环境变量

3. 创建 DWF 环境

4. 启动开发环境

可选：使用 PostgreSQL

生产部署

Docker Compose（推荐）

离线环境部署

全局安装与 CLI 使用

从 npm registry 安装

从本地源码安装（开发测试）

开发与测试全局安装

CLI 参数

推荐终端：Windows Terminal

dwf-cli 命令行工具

前置条件

基本用法

查看可用 MCP 实例

指定实例

多个实例运行时的交互选择

直连模式（跳过自动发现）

wrapper 专属参数

常用命令示例

环境变量

启动后访问

环境变量

发布到 npm

发布注意事项

开发命令

常见问题

全局安装后启动报错 Cannot find package 'xxx'

全局安装后启动报错 EACCES / EPERM

端口被占用

npm login 跳转到 cnpm 或返回 401/404

启动时报错 PostgreSQL dependencies not available

启动时报错 client password must be a string

与第三方 MCP 客户端集成

开发规范

许可证

全局安装后启动报错 `Cannot find package 'xxx'`

全局安装后启动报错 `EACCES` / `EPERM`

启动时报错 `PostgreSQL dependencies not available`

启动时报错 `client password must be a string`