DWF-CLI

DWF（Digital Workflow）平台命令行工具，通过 REST API 与 DWF 后端交互，为 AI 智能体和开发人员提供数据模型查询、数据操作、认证管理等功能。

功能

• 用户认证 — 登录/登出/状态查询（AES 加密密码传输）
• 数据模型管理 — 查询/创建/更新/删除实体类、关联类、外部实体类及其属性
• 数据操作 — 对象数据的增删改查（CRUD），支持 --if-not-exists 幂等创建
• 高级查询 — 对象列表支持 refs（关联字段拉平）和 options（嵌套子查询）
• Excel 快速建表 — 上传 Excel 一键完成建表和数据导入
• 功能模型 — 应用管理、全局操作列表
• 表单模型 — 视图的查询/创建/更新/删除
• Schema 自省 — dwf-cli schema 查看命令参数定义，--validate 校验输入
• 配置管理 — 服务器地址、AES 密钥等配置项管理

快速开始

环境要求

• Python 3.12+
• uv 包管理器

安装

# 安装（推荐 uv tool）
uv tool install dwf-cli

# 或从源码安装
git clone https://gitee.com/tsinghua-nercbds/dwf-cli.git
cd dwf-cli
uv tool install .

配置与登录

# 方式一：自动检测（推荐，从 DWF 服务获取配置）
dwf-cli config detect http://your-dwf-server:6060 --save

# 方式二：手动配置
dwf-cli config set server http://your-dwf-server:6060
dwf-cli config set app_server http://your-dwf-server:9090

# 登录（TTY 模式交互输入密码）
dwf-cli auth login --username admin

# 非 TTY 模式（CI / AI agent）
echo 'password' > /tmp/pw && dwf-cli auth login --username admin --password-file /tmp/pw

# 查看登录状态
dwf-cli auth status

使用示例

# 查询实体类列表
dwf-cli datamodel list
dwf-cli datamodel list -p 1 -s 10

# 查询关联类 / 外部实体类
dwf-cli datamodel list -t r
dwf-cli datamodel list -t x

# 包含系统类
dwf-cli datamodel list --system

# 查看某个类的属性
dwf-cli datamodel show User
dwf-cli datamodel show Animate -f json

# 创建实体类（支持 --type entity|relation|external）
dwf-cli datamodel create --data '[{"className":"TestClass","displayName":"测试类"}]'
dwf-cli datamodel create -t relation --data '[{"className":"UserAsset","leftClass":"User","rightClass":"Asset"}]'
dwf-cli datamodel create -t external --external-mode sql --file ext.json

# 更新类信息
dwf-cli datamodel update --data '{"id":"ABC123","displayName":"新名称"}'
dwf-cli datamodel update -t external --data '{"id":"EXT123","displayName":"新名称"}'

# 属性管理
dwf-cli datamodel attribute list --keyword name
dwf-cli datamodel attribute create --data '[{"attributeName":"phone","valueType":"String"}]'
dwf-cli datamodel attribute bind -c User --data '[{"attributeName":"phone"}]'

# 对象数据操作
dwf-cli datamodel object list -c User -p 0
dwf-cli datamodel object get <oid> -c User
dwf-cli datamodel object create -c User --data '{"name":"test"}'
dwf-cli datamodel object create -c User --data '{"name":"test"}' --if-not-exists

# 对象高级查询（refs 关联字段拉平）
dwf-cli datamodel object list -c Animate --file query.json

# Excel 一键建表
dwf-cli datamodel excel-quickstart template.xlsx

# Schema 自省
dwf-cli schema --all
dwf-cli schema datamodel create

# 功能模型
dwf-cli funcmodel app list
dwf-cli funcmodel operations list

# 表单模型
dwf-cli formmodel view list -c User
dwf-cli formmodel view create -c User --name myView

# 配置管理
dwf-cli config list
dwf-cli config get server
dwf-cli config set aes_key "your-key"

文档

完整文档使用 MkDocs + Material 主题构建：

# 本地预览（默认不含 API 参考文档，构建更快）
uv run mkdocs serve

# 包含 API 参考文档
DWF_INCLUDE_API_DOCS=1 uv run mkdocs serve

# 重新生成 API 文档（从 OpenAPI JSON）
uv run python scripts/openapi_to_md.py

文档站点自动部署至 Tomcat（通过 Jenkinsfile CI）。

架构

项目采用三层分离架构：

cli/  →  api/  →  core/

• cli/ — CLI 层：Typer 命令定义、参数解析、Rich 表格输出
• api/ — API 层：DWF 后端 REST API 的 Python SDK（httpx）
• core/ — 基础设施层：配置管理、AES 加密、错误定义、输出格式化

依赖方向严格单向：cli → api → core，禁止反向依赖。

详细架构设计见 ARCHITECTURE.md。

项目结构

src/dwf_cli/
├── __init__.py           # 入口点 (dwf-cli = "dwf_cli:app")
├── __main__.py           # python -m dwf_cli
├── api/                  # DWF 后端 REST SDK
│   ├── client.py         # HTTP 客户端（baseURL、token 注入、错误映射）
│   ├── auth.py           # 认证接口
│   ├── datamodel.py      # 数据模型 + 对象 CRUD 接口
│   ├── funcmodel.py      # 功能模型接口
│   └── formmodel.py      # 表单模型接口
├── cli/                  # Typer 命令
│   ├── __init__.py       # 命令注册 + 上下文初始化（双 client：modeler + app）
│   ├── _common.py        # 共享工具（ContextObj、get_client、get_app_client）
│   ├── auth.py           # dwf-cli auth {login, logout, status}
│   ├── datamodel.py      # dwf-cli datamodel {list, show, object CRUD}
│   ├── funcmodel.py      # dwf-cli funcmodel {app, operations}
│   ├── formmodel.py      # dwf-cli formmodel {view}
│   └── config.py         # dwf-cli config {get, set, list, detect}
├── mcp/                  # MCP Server（供 AI 工具直接集成）
│   ├── __init__.py
│   └── server.py         # FastMCP server，入口点 dwf-cli-mcp
└── core/                 # 基础设施
    ├── config.py         # 配置管理（JSON 持久化）+ config.js 解析
    ├── crypto.py         # AES 密码加密
    ├── errors.py         # 异常层级 + 退出码
    └── output.py         # Rich 表格/JSON 输出

开发

添加新命令

只需 3 步：

1. 新建 src/dwf_cli/api/xxx.py — 定义 API 调用函数
2. 新建 src/dwf_cli/cli/xxx.py — 定义 Typer 命令
3. 编辑 src/dwf_cli/cli/__init__.py — 添加 app.add_typer()

开发命令

uv run dwf-cli --help              # 开发时运行 CLI
uv run pytest -v                   # 运行测试
uv run ruff check .                # 代码检查
uv run ruff format .               # 代码格式化
uv add <package>                   # 添加依赖

安装后直接使用：

dwf-cli --help                     # 已安装环境直接调用

文档命令

uv run mkdocs serve                # 本地预览文档
DWF_INCLUDE_API_DOCS=1 uv run mkdocs serve  # 含 API 参考
uv run python scripts/openapi_to_md.py       # 重新生成 API 文档

技术栈

• Typer — CLI 框架
• httpx — HTTP 客户端
• Rich — 终端美化输出
• MCP Python SDK — MCP Server 实现
• pycryptodome — AES 密码加密
• uv — 包管理器
• pytest — 测试框架
• Ruff — 代码检查与格式化

AI Agent 集成

DWF-CLI 提供两种方式供 AI 编程工具使用：

方式一：CLI 命令（所有 AI 工具通用）

AI 编程工具（Claude Code、OpenCode、Codex 等）可通过 bash 直接调用 dwf-cli 命令。

在你的项目 AGENTS.md（opencode）或 CLAUDE.md（Claude Code）中添加以下内容：

## DWF CLI
Use `dwf-cli` to interact with the DWF platform.
- Run `dwf-cli schema --all` to get full command + parameter reference as JSON
- Run `dwf-cli <command> --help` for specific command usage
- Always use `--format json` for output parsing
- Use `--data` for inline JSON, `--file` for file input
- Use `--dry-run` to preview before executing
- Setup: `dwf-cli config detect <url> --save` then `dwf-cli auth login --username <user>` (TTY) or `--password-file` (non-interactive)

方式二：MCP Server（深度集成，推荐）

MCP (Model Context Protocol) 让 AI 工具直接调用 DWF 功能，无需拼 shell 命令。

安装后配置：

Claude Code (~/.claude/settings.json)：

{
  "mcpServers": {
    "dwf": {
      "command": "uvx",
      "args": ["dwf-cli-mcp"]
    }
  }
}

Cursor / Windsurf (.cursor/mcp.json)：

{
  "mcpServers": {
    "dwf": {
      "command": "uvx",
      "args": ["dwf-cli-mcp"]
    }
  }
}

从源码运行：

{
  "mcpServers": {
    "dwf": {
      "command": "uv",
      "args": ["--directory", "/path/to/dwf-cli", "run", "dwf-cli-mcp"]
    }
  }
}

提供的 MCP 工具：

工具	说明
dwf_auth_status	检查认证状态
dwf_config_list	查看配置
dwf_datamodel_list	列出数据模型
dwf_datamodel_show	查看模型详情
dwf_datamodel_create	创建数据模型
dwf_datamodel_delete	删除数据模型
dwf_attribute_list	列出属性
dwf_attribute_create	创建属性
dwf_attribute_bind	绑定属性到模型
dwf_object_list	列出对象
dwf_object_get	获取单个对象
dwf_object_create	创建对象
dwf_object_update	更新对象
dwf_object_delete	删除对象
dwf_object_count	统计对象数量
dwf_funcmodel_app_list	列出应用
dwf_funcmodel_operation_list	列出功能操作
dwf_formmodel_view_list	列出表单视图

License

Apache-2.0