Metadata-Version: 2.4
Name: dwf-cli
Version: 0.1.1
Summary: DWF platform command-line tool for AI agents
Project-URL: Repository, https://gitee.com/tsinghua-nercbds/dwf-cli
Project-URL: Documentation, https://gitee.com/tsinghua-nercbds/dwf-cli#readme
Project-URL: Issues, https://gitee.com/tsinghua-nercbds/dwf-cli/issues
Author-email: nercbds dwf group <csliuyb@qq.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agent,cli,dwf
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.0
Requires-Dist: pycryptodome>=3.23.0
Requires-Dist: pypinyin>=0.52.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.25.1
Description-Content-Type: text/markdown

# 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](https://docs.astral.sh/uv/) 包管理器

### 安装

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

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

### 配置与登录

```bash
# 配置 DWF 服务器地址
dwf-cli config set server http://your-dwf-server:6060

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

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

### 使用示例

```bash
# 查询实体类列表
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 主题构建：

```bash
# 本地预览（默认不含 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](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()`

### 开发命令

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

安装后直接使用：

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

### 文档命令

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

## 技术栈

- [Typer](https://typer.tiangolo.com/) — CLI 框架
- [httpx](https://www.python-httpx.org/) — HTTP 客户端
- [Rich](https://rich.readthedocs.io/) — 终端美化输出
- [pycryptodome](https://www.pycryptodome.org/) — AES 密码加密
- [uv](https://docs.astral.sh/uv/) — 包管理器
- [pytest](https://docs.pytest.org/) — 测试框架
- [Ruff](https://docs.astral.sh/ruff/) — 代码检查与格式化

## AI Agent 集成

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

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

```markdown
## 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
