Metadata-Version: 2.4
Name: minglue-mec-cli
Version: 0.2.2
Summary: CLI tool for minglue-mec system, designed for AI integration
Author-email: Developer <dev@example.com>
License-Expression: MIT
Keywords: minglue,mec,cli,ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pydantic>=2.5.0

# minglue-mec-cli 命令说明

本文档对应 `minglue-mec-cli` 当前版本 `0.2.2`，说明所有 CLI 命令的用途、参数、示例和操作风险。

默认 API 地址为：

```bash
https://mec.miaozhen.com/taskmng
```

所有支持 `--url/-u` 的命令都可以切换环境：

```bash
minglue-mec client list --url https://your-host/taskmng
```

输出统一为 JSON，常见结构：

```json
{
  "success": true,
  "message": "操作说明",
  "data": {}
}
```

## 操作风险

- 只读：只查询数据，不修改后端。
- 本地写入：只修改本机 token 文件。
- 写入：会新增、修改、取消、回写或触发后端流程。
- 文件上传：会上传本地文件到后端。
- 执行任务：会创建工单或触发计算/执行流程。

## 全局命令

### `version`

只读。查看 CLI 版本。

```bash
minglue-mec version
```

### `help`

只读。显示 CLI 帮助。

```bash
minglue-mec help
minglue-mec task --help
minglue-mec task status --help
```

## 认证：`auth`

Token 保存在本机：

```text
~/.minglue/tokens.json
```

### `auth login`

本地写入。登录并保存 token。

参数：

- `--account, -a`：账号，必填。
- `--password, -p`：密码，必填。
- `--url, -u`：API 地址。
- `--debug`：打印请求调试信息。

示例：

```bash
minglue-mec auth login -a dailijia -p 123456
```

### `auth logout`

本地写入。删除本地 token。

```bash
minglue-mec auth logout
```

### `auth status`

只读。查看本地是否已有 token。

```bash
minglue-mec auth status
```

## 客户：`client`

### `client list`

只读。分页查询客户。

参数：

- `--page, -p`：页码，默认 `1`。
- `--page-size, -s`：每页数量，默认 `20`。
- `--client-name, -c`：客户名称筛选。
- `--url, -u`：API 地址。
- `--debug`：调试输出。

示例：

```bash
minglue-mec client list -p 1 -s 10
minglue-mec client list -c 宝洁
```

### `client detail`

只读。按客户 ID 查询客户详情。

参数：

- `--clientid`：客户 ID，必填。
- `--url, -u`：API 地址。
- `--debug`：调试输出。

示例：

```bash
minglue-mec client detail --clientid 52438ca58a9543f8a7e4f66250243ce4
```

### `client quota`

只读。查询客户配额使用记录。

参数：

- `--clientid`：客户 ID，必填。
- `--page, -p`：页码。
- `--page-size, -s`：每页数量。
- `--url, -u`：API 地址。
- `--debug`：调试输出。

示例：

```bash
minglue-mec client quota --clientid 52438ca58a9543f8a7e4f66250243ce4 -p 1 -s 20
```

### `client options`

只读。获取客户下拉选项，常用于创建任务前选择客户。

```bash
minglue-mec client options
```

## 品牌：`brand`

### `brand list`

只读。分页查询品牌。

参数：

- `--page, -p`：页码。
- `--page-size, -s`：每页数量。
- `--brand-name, -b`：品牌名称筛选。
- `--url, -u`：API 地址。

示例：

```bash
minglue-mec brand list -p 1 -s 10
minglue-mec brand list -b GILLETTE
```

### `brand detail`

只读。按品牌 ID 查询详情。

参数：

- `--brandid`：品牌 ID，必填。
- `--url, -u`：API 地址。
- `--debug`：调试输出。

示例：

```bash
minglue-mec brand detail --brandid 8fc7b8fe91804d1bb5faad5996542ebd
```

### `brand options`

只读。按客户获取品牌下拉选项。

参数：

- `--clientid`：客户 ID。
- `--clientname`：客户名称。
- `--url, -u`：API 地址。
- `--debug`：调试输出。

示例：

```bash
minglue-mec brand options --clientid 52438ca58a9543f8a7e4f66250243ce4
```

### `brand sales`

只读。查询品牌历史销售机会 ID。

参数：

- `--brandid`：品牌 ID，必填。
- `--wherecreate`：后端筛选参数，可选。

示例：

```bash
minglue-mec brand sales --brandid 8fc7b8fe91804d1bb5faad5996542ebd
```

### `brand po`

只读。查询品牌历史 PO ID。

参数：

- `--brandid`：品牌 ID，必填。
- `--wherecreate`：后端筛选参数，可选。

示例：

```bash
minglue-mec brand po --brandid 8fc7b8fe91804d1bb5faad5996542ebd
```

### `brand tree`

只读。获取品牌授权树。

```bash
minglue-mec brand tree
```

## 任务：`task`

任务 ID 通常指业务字段 `taskid`，不是数据库自增/雪花 `id`。少数命令同时支持 `--id`。

### `task list`

只读。分页查询任务。

参数：

- `--page, -p`：页码。
- `--page-size, -s`：每页数量。
- `--taskname, -t`：任务名称筛选。
- `--clientname, -c`：客户名称筛选。
- `--url, -u`：API 地址。

示例：

```bash
minglue-mec task list -p 1 -s 10
minglue-mec task list -t AutoCIA
minglue-mec task list -c 宝洁
```

### `task create`

写入。通过 OpenApi 创建 MEC 任务。

参数：

- `--taskname, -t`：任务名称，必填。
- `--clientname, -c`：客户名称，必填。
- `--brandname, -b`：品牌名称，必填。
- `--platform, -p`：平台，必填。常用值：`TM`、`JD`、`ALI`、`DY`、`YT`。
- `--dtsaccount`：DTS 账号，必填。
- `--dtspassword`：DTS 密码，必填。
- `--crowdbagpath`：人群包路径，必填。
- `--salesid`：销售机会 ID。
- `--poid`：PO ID。
- `--taskenddate`：任务结束日期。
- `--datasource`：数据源。
- `--taskremarks`：任务备注。
- `--imagesreports`：`0` 表示画像，`1` 表示报告。
- `--url, -u`：API 地址。

示例：

```bash
minglue-mec task create \
  -t AutoCIA_Test_JD \
  -c 宝洁 \
  -b GILLETTE \
  -p JD \
  --dtsaccount pgdmp \
  --dtspassword password \
  --crowdbagpath /autocia/test
```

### `task detail`

只读。查询任务详情。

参数：

- `--id`：数据库行 ID。
- `--taskid`：业务任务 ID。
- `--url, -u`：API 地址。
- `--debug`：调试输出。

示例：

```bash
minglue-mec task detail --taskid 80893a8f301e4bf2bce3a98eca9f3f2a
minglue-mec task detail --id 829553056092230
```

### `task entity`

只读。查询任务工单实体详情。该接口可能依赖当前用户云工单 SecretId 配置；没有配置时后端会返回业务失败。

参数：

- `--taskid`：业务任务 ID，必填。

示例：

```bash
minglue-mec task entity --taskid 80893a8f301e4bf2bce3a98eca9f3f2a
```

### `task status`

只读。查询任务执行/计算状态。

参数：

- `--taskid`：业务任务 ID，必填。

示例：

```bash
minglue-mec task status --taskid 80893a8f301e4bf2bce3a98eca9f3f2a
```

### `task result`

只读。查询任务计算结果。

参数：

- `--taskid`：业务任务 ID，必填。
- `--platform, -p`：平台，必填。常用值：`JD`、`TM`、`ALI`、`DY`、`YT`。

示例：

```bash
minglue-mec task result --taskid 80893a8f301e4bf2bce3a98eca9f3f2a --platform JD
```

### `task bg-result`

只读。查询任务相关报告/背景结果。

参数：

- `--taskids`：任务 ID，多个用逗号分隔。

示例：

```bash
minglue-mec task bg-result --taskids 80893a8f301e4bf2bce3a98eca9f3f2a
```

### `task attachments`

只读。查询任务附件。

参数：

- `--taskid`：业务任务 ID，必填。

示例：

```bash
minglue-mec task attachments --taskid 80893a8f301e4bf2bce3a98eca9f3f2a
```

### `task ring-upload-form`

只读。查询圈包上传所需的平台/表单信息。

参数：

- `--ringid`：圈包 ID，必填。

示例：

```bash
minglue-mec task ring-upload-form --ringid 2447033
```

### `task logs`

只读。查询任务执行状态日志。

参数：

- `--taskid`：业务任务 ID，可选。
- `--page, -p`：页码。
- `--page-size, -s`：每页数量。

示例：

```bash
minglue-mec task logs -p 1 -s 20
minglue-mec task logs --taskid 2262da5eba1e432eaa14ed89fcd254a3
```

### `task upload`

文件上传。上传任务计算文件。

参数：

- `--taskid`：业务任务 ID，必填。
- `--platform, -p`：平台，必填。`TM/ALI` 使用天猫/阿里上传接口，`JD` 使用京东接口，`DY/YT` 使用云图/抖音接口。
- `--file, -f`：本地文件路径，必填。

示例：

```bash
minglue-mec task upload --taskid xxx --platform JD --file ./result.xlsx
```

### `task cancel`

写入。取消任务。

参数：

- `--taskid`：业务任务 ID，必填。

示例：

```bash
minglue-mec task cancel --taskid 80893a8f301e4bf2bce3a98eca9f3f2a
```

### `task report-error`

写入。向后端回写任务错误信息。

参数：

- `--taskid`：业务任务 ID，必填。
- `--errmsg`：错误信息，必填。

示例：

```bash
minglue-mec task report-error --taskid xxx --errmsg "计算失败：文件格式错误"
```

## 圈包：`ring`

### `ring list`

只读。分页查询圈包头信息。

参数：

- `--page, -p`：页码。
- `--page-size, -s`：每页数量。
- `--client-name, -c`：客户名称筛选。
- `--brand-name, -b`：品牌名称筛选。

示例：

```bash
minglue-mec ring list -p 1 -s 10
```

### `ring packages`

只读。查询圈包明细。注意：当前后端该接口可能忽略分页并返回大量明细。

参数：

- `--page, -p`：页码。
- `--page-size, -s`：每页数量。
- `--task-name`：任务名筛选。
- `--client-name, -c`：客户名筛选。
- `--brand-name, -b`：品牌名筛选。

示例：

```bash
minglue-mec ring packages -p 1 -s 10
minglue-mec ring packages --task-name AutoCIA
```

### `ring detail`

只读。查询圈包明细详情。

参数：

- `--id`：圈包明细行 ID，必填。

示例：

```bash
minglue-mec ring detail --id 374520925560901
```

### `ring import-list`

只读。读取已上传 Excel 的圈包导入解析结果。

参数：

- `--excelid`：上传文件 ID，必填。

示例：

```bash
minglue-mec ring import-list --excelid 123456
```

### `ring options`

只读。按品牌 ID 获取可选圈包。

参数：

- `--brandid`：品牌 ID，必填。

示例：

```bash
minglue-mec ring options --brandid d86edde05c714d04b840b7930bdce388
```

### `ring city-data`

只读。获取城市维度数据。

参数：

- `--typestr`：数据源/类型，如 `ADM`。

示例：

```bash
minglue-mec ring city-data --typestr ADM
```

### `ring dw-data`

只读。获取点位数据。

参数：

- `--camid`：活动/计划 ID。
- `--dwid`：点位 ID。

示例：

```bash
minglue-mec ring dw-data --camid 2348080 --dwid 8OAdR
```

### `ring upload`

文件上传。上传圈包 Excel/CSV 文件，并创建圈包信息。

参数：

- `--file, -f`：本地文件路径，必填。
- `--ringname, -r`：圈包名称，必填。
- `--clientname, -c`：客户名称，必填。
- `--brandname, -b`：品牌名称，必填。

示例：

```bash
minglue-mec ring upload \
  --file ./ring.xlsx \
  --ringname "测试圈包" \
  --clientname "宝洁" \
  --brandname "GILLETTE"
```

### `ring create`

写入。旧版 JSON 方式创建圈包包。当前后端 OpenApi 更推荐使用 `ring upload`。

该命令参数较多，适合脚本化传入单个圈包明细。必填参数包括客户、品牌、活动、规则、平台、任务名、数据源、城市、媒体、物料等。

示例：

```bash
minglue-mec ring create \
  --client-name 宝洁 \
  --client-id CLIENT_ID \
  --brand-id BRAND_ID \
  --brand-name GILLETTE \
  --activity-id ACT001 \
  --name-group group1 \
  --rule-loop 媒体 \
  --value-coil 腾讯视频 \
  --log-type 曝光 \
  --upload-platform JD \
  --task-name task1 \
  --analysis-platform MEC \
  --data-source ADM \
  --id-output IDFA,IMEI,OAID \
  --city 全国 \
  --media 腾讯视频 \
  --material 素材
```

## 执行状态日志：`statuslog`

### `statuslog list`

只读。分页查询任务执行状态日志。

参数：

- `--taskid`：业务任务 ID。
- `--page, -p`：页码。
- `--page-size, -s`：每页数量。

示例：

```bash
minglue-mec statuslog list -p 1 -s 20
minglue-mec statuslog list --taskid 2262da5eba1e432eaa14ed89fcd254a3
```

### `statuslog detail`

只读。查询执行状态日志详情。

参数：

- `--id`：日志行 ID，必填。

示例：

```bash
minglue-mec statuslog detail --id 829587952746565
```

### `statuslog over-task`

写入。调用后端 `Ml_Statuslog/overtask` 修改状态日志/任务状态。

参数：

- `--id`：日志行 ID。
- `--taskid`：业务任务 ID。
- `--data, -d`：JSON 请求体。

示例：

```bash
minglue-mec statuslog over-task --data "{\"id\":829587952746565}"
```

## AI SQL：`aisql`

### `aisql models`

只读。获取可用 AI 模型。

```bash
minglue-mec aisql models
```

### `aisql check-agreement`

只读。检查当前用户是否签署 AI SQL 协议。

```bash
minglue-mec aisql check-agreement
```

### `aisql agree`

写入。签署 AI SQL 协议。

```bash
minglue-mec aisql agree
```

### `aisql gen`

写入/调用 AI 服务。根据自然语言生成 SQL。

参数：

- `--comment, -c`：需求描述，必填。
- `--model, -m`：模型，默认 `mlamp/deepseek-v4-flash`。
- `--client`：客户名称。
- `--brand`：品牌名称。
- `--datafrom`：数据来源，如 `ADM`、`OTT-OM`、`OTT-PMO`、`TVM`、`BDID-MZID`、`BDID-IPV6`。
- `--contype`：分析类型。
- `--datetimefw`：时间范围。
- `--debug`：调试输出。

示例：

```bash
minglue-mec aisql gen \
  -c "查询曝光人数" \
  --client 宝洁 \
  --brand GILLETTE \
  --datafrom ADM \
  --datetimefw 20260701-20260722
```

### `aisql translate`

只读/调用 AI 服务。将 SQL 翻译成自然语言说明。

参数：

- `--sql, -s`：SQL 语句，必填。

示例：

```bash
minglue-mec aisql translate -s "select count(1) from table_name"
```

### `aisql create`

写入。创建 AI SQL 任务。

必填参数：

- `--task-name, -t`：任务名。
- `--clientid`：客户 ID。
- `--client`：客户名称。
- `--brandid`：品牌 ID。
- `--brand`：品牌名称。
- `--datafrom`：数据来源。
- `--contype`：分析类型。
- `--datetimefw`：时间范围。
- `--comment`：需求描述。
- `--sql`：SQL 语句。

可选参数：

- `--sccontent`：自然语言描述。
- `--model`：模型。
- `--dtsaccount`：DTS 账号。
- `--dtspassword`：DTS 密码。
- `--crow-data-path`：人群包路径。
- `--dts-path`：DTS 路径。
- `--sale-id`：销售机会 ID。
- `--excuter`：执行人。

示例：

```bash
minglue-mec aisql create \
  -t "AI SQL 测试任务" \
  --clientid CLIENT_ID \
  --client 宝洁 \
  --brandid BRAND_ID \
  --brand GILLETTE \
  --datafrom ADM \
  --contype 曝光分析 \
  --datetimefw 20260701-20260722 \
  --comment "查询曝光人数" \
  --sql "select count(1) from table_name"
```

### `aisql perform`

执行任务。为 AI SQL 任务创建/触发工单。

参数：

- `--id`：AI SQL 任务行 ID，必填。
- `--task-id`：工单模板 ID，默认 `1078`。

示例：

```bash
minglue-mec aisql perform --id 807313466699845
```

### `aisql status`

只读。查询 AI SQL 任务状态。

参数：

- `--id`：AI SQL 任务行 ID，必填。

示例：

```bash
minglue-mec aisql status --id 807313466699845
```

## MARS 计算任务：`mars`

### `mars create`

写入/执行任务。创建 MARS 计算任务，并由后端创建工单。

参数：

- `--task-name, -t`：MARS 任务名，必填。
- `--clientname, -c`：客户名称，必填。
- `--brandname, -b`：品牌名称，必填。
- `--crowname`：人群名称，必填。
- `--description`：描述 JSON 字符串。
- `--description-file`：描述 JSON 文件路径。
- `--days`：天数，不传则后端默认。
- `--taskcount`：任务数量，默认 `0`。

示例：

```bash
minglue-mec mars create \
  -t "MARS测试任务" \
  -c 宝洁 \
  -b GILLETTE \
  --crowname "测试人群" \
  --description-file ./mars-description.json \
  --taskcount 100000
```

### `mars status`

只读。查询 MARS 任务状态。

参数：

- `--marstaskid`：MARS 任务 ID，必填。

示例：

```bash
minglue-mec mars status --marstaskid 3f379bfc055042e69e31e2a19bf56c1f
```

### `mars download-url`

只读。查询 MARS 结果下载地址。

参数：

- `--marstaskid`：MARS 任务 ID，必填。

示例：

```bash
minglue-mec mars download-url --marstaskid 3f379bfc055042e69e31e2a19bf56c1f
```

### `mars download-file-url`

只读。本地拼接 MARS 文件下载 URL。

参数：

- `--fileid`：系统文件 ID，必填。

示例：

```bash
minglue-mec mars download-file-url --fileid 800302374490182
```

## USP/画像：`usp`

### `usp create`

写入。创建平台画像任务。

参数：

- `--platform, -p`：平台，必填。`TM/ALI` 走天猫/阿里画像，`JD` 走京东画像，`DY/YT` 走抖音/云图画像。
- `--taskid`：MEC 任务 ID，必填。
- `--crowds`：人群名称，多个用逗号分隔。不传时后端尝试从任务人群包推导。
- `--labeltype`：标签类型编码，多个用逗号分隔。不传时使用后端默认标签。

示例：

```bash
minglue-mec usp create --platform JD --taskid 80893a8f301e4bf2bce3a98eca9f3f2a
minglue-mec usp create --platform JD --taskid xxx --crowds crowdA,crowdB --labeltype 01,02,03
```

### `usp result`

只读。查询画像结果。

参数：

- `--taskid`：MEC 任务 ID，必填。

示例：

```bash
minglue-mec usp result --taskid 80893a8f301e4bf2bce3a98eca9f3f2a
```

## 通用资源：`resource`

`resource` 用于访问前端后台模块中大量统一 REST 资源，例如：

- `Ml_Client`
- `Ml_Brand`
- `Ml_task`
- `Ml_Crowdpack`
- `Ml_RingPackage`
- `Ml_Statuslog`
- `Ml_MarsTask`
- `Ml_AiHiveSql`

资源名会被转换为后端动态 API 路径，例如：

```text
Ml_Crowdpack page -> /api/ml_crowdpack/page
Ml_RingPackage getcitydata -> /api/ml_ringpackage/getcitydata
```

### `resource available`

只读。列出已整理的常用资源名。

```bash
minglue-mec resource available
```

### `resource page`

只读。分页查询资源。

参数：

- `resource`：资源名，必填。
- `--page, -p`：页码。
- `--page-size, -s`：每页数量。
- `--params`：额外 JSON 参数，支持 `@file.json`。

示例：

```bash
minglue-mec resource page Ml_Crowdpack -p 1 -s 10
minglue-mec resource page Ml_task --params "{\"taskname\":\"AutoCIA\"}"
minglue-mec resource page Ml_task --params @query.json
```

### `resource list`

只读。查询资源列表。

参数：

- `resource`：资源名，必填。
- `--params`：JSON 参数，支持 `@file.json`。

示例：

```bash
minglue-mec resource list Ml_Client --params "{}"
```

### `resource detail`

只读。查询资源详情。

参数：

- `resource`：资源名，必填。
- `--id`：行 ID。
- `--params`：JSON 参数，支持 `@file.json`。

示例：

```bash
minglue-mec resource detail Ml_Crowdpack --id 829553055612997
```

### `resource add`

写入。新增资源。

参数：

- `resource`：资源名，必填。
- `--data, -d`：JSON 请求体，支持 `@file.json`。

示例：

```bash
minglue-mec resource add Ml_Statuslog --data @statuslog.json
```

### `resource edit`

写入。编辑资源。

参数：

- `resource`：资源名，必填。
- `--data, -d`：JSON 请求体，支持 `@file.json`。

示例：

```bash
minglue-mec resource edit Ml_Statuslog --data @statuslog.json
```

### `resource delete`

写入/删除。删除资源。

参数：

- `resource`：资源名，必填。
- `--id`：行 ID。
- `--data, -d`：JSON 请求体，支持 `@file.json`。

示例：

```bash
minglue-mec resource delete Ml_Statuslog --id 123
```

### `resource call`

视接口而定。调用资源的特殊动作。

参数：

- `resource`：资源名，必填。
- `action`：动作名，必填。
- `--method, -X`：HTTP 方法，默认 `GET`。
- `--params`：JSON 参数或请求体，支持 `@file.json`。

示例：

```bash
minglue-mec resource call Ml_RingPackage getcitydata --params "{\"typestr\":\"ADM\"}"
minglue-mec resource call Ml_Statuslog overtask -X POST --params @body.json
```

## 常用工作流

### 查询客户、品牌、任务状态

```bash
minglue-mec auth login -a your_account -p your_password
minglue-mec client options
minglue-mec brand options --clientid CLIENT_ID
minglue-mec task list -c 客户名 -p 1 -s 10
minglue-mec task status --taskid TASK_ID
minglue-mec task result --taskid TASK_ID --platform JD
```

### 查询圈包信息

```bash
minglue-mec ring list -p 1 -s 10
minglue-mec ring packages --task-name 任务名
minglue-mec ring detail --id RING_PACKAGE_ROW_ID
minglue-mec ring options --brandid BRAND_ID
```

### 查询执行日志和计算结果

```bash
minglue-mec statuslog list --taskid TASK_ID
minglue-mec task logs --taskid TASK_ID
minglue-mec task result --taskid TASK_ID --platform JD
minglue-mec task bg-result --taskids TASK_ID
```

### 查询 MARS 任务

```bash
minglue-mec resource page Ml_MarsTask -p 1 -s 10
minglue-mec mars status --marstaskid MARS_TASK_ID
minglue-mec mars download-url --marstaskid MARS_TASK_ID
```

## 调试建议

大多数业务命令支持 `--debug`。遇到后端返回不符合预期时，先加 `--debug` 查看实际 URL、参数和响应片段：

```bash
minglue-mec task status --taskid TASK_ID --debug
```

如果只想验证命令是否存在和参数是否正确：

```bash
minglue-mec task status --help
```
