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 set server http://your-dwf-server:6060

# 登录（输入原始密码，CLI 自动加密）
dwf-cli auth login

# 查看登录状态
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       # 命令注册 + 上下文初始化
│   ├── _common.py        # 共享工具（ContextObj、get_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}
└── core/                 # 基础设施
    ├── config.py         # 配置管理（JSON 持久化）
    ├── 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 — 终端美化输出
• pycryptodome — AES 密码加密
• uv — 包管理器
• pytest — 测试框架
• Ruff — 代码检查与格式化

AI Agent 集成

DWF-CLI 可被 AI 编程工具（opencode、Claude Code 等）通过内置 bash 工具直接调用。

在你的项目 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 set server <url>` then `dwf-cli auth login -u <user> -p <pass>`

License

Apache-2.0