# 千牛取数模板导出 CLI（qianniu-exporter）

这是一个按 CLI-Anything 思路搭建的 agent-native CLI harness，用于把千牛路径：

> 数据 → 自助分析 → 取数报表 → 取数模板

下面的 Excel 取数模板逐个导出。

## 当前状态

- 已完成本地 CLI 骨架和可运行命令。
- 已验证 `qn-export --help`、`qn-export doctor`、HAR 扫描与 mock 导出测试。
- 已用真实 HAR 验证生意参谋异步导出流程：`download.json` 提交任务，`queryDownloadUrl.json` 轮询 OSS 签名地址，再下载 Excel。
- 还不能直接在 IT profile 里点击千牛页面；本机 GUI/浏览器点击必须交给 `visual-operator`。
- 千牛/生意参谋取数模板未发现 CLI-Hub 现成 harness；需要本项目自定义。

## 为什么采用 HAR/接口重放方式

千牛和生意参谋登录态、验证码、风控较强；官方公开 API 也不等于能直接读取“取数报表/取数模板”这个 UI 页面里的所有 Excel。更稳妥的 CLI 化方式是：

1. 由 `visual-operator` 在已登录页面中做一次受控操作，采集 HAR。
2. 本 CLI 从 HAR 中识别“模板列表/导出下载”候选接口。
3. 用 cookie 文件或后续接入的安全凭据，在命令行逐个导出 Excel。

## 安装/运行

在项目目录执行：

```bash
python3 -m pip install -e .
qn-export --help
qn-export doctor
```

## 命令

```bash
# 运行环境检查
qn-export doctor

# 生成给 visual-operator 的 HAR 采集简报
qn-export operator-brief --out docs/visual_operator_brief.md

# 扫描 HAR，生成候选接口 manifest：包含列表接口、下载接口
qn-export scan-har samples/qianniu_templates.har --out deliverables/qianniu_manifest.json

# 方案 A：如果 HAR 已经包含每个下载请求，直接预览/导出
qn-export export-all deliverables/qianniu_manifest.json --cookie-file secrets/cookie.json --out-dir deliverables/excels --dry-run
qn-export export-all deliverables/qianniu_manifest.json --cookie-file secrets/cookie.json --out-dir deliverables/excels --limit 1

# 方案 B：CLI 化“先取模板列表，再按列表逐个下载”
# 1) 重放列表接口，保存真实模板列表 JSON
qn-export fetch-list deliverables/qianniu_manifest.json --cookie-file secrets/cookie.json --out deliverables/template_list.json

# 2) 从模板列表 JSON 构建下载 manifest：可用一次真实下载请求作为 URL 模板
qn-export build-downloads deliverables/template_list.json --download-example-manifest deliverables/qianniu_manifest.json --out deliverables/download_manifest.json

# 3) 预览后小批量验证，再全量导出；支持 download.json → queryDownloadUrl.json → OSS Excel 的异步轮询
qn-export export-all deliverables/download_manifest.json --cookie-file secrets/cookie.json --out-dir deliverables/excels --dry-run
qn-export export-all deliverables/download_manifest.json --cookie-file secrets/cookie.json --out-dir deliverables/excels --limit 1 --poll-attempts 18 --poll-seconds 3
qn-export export-all deliverables/download_manifest.json --cookie-file secrets/cookie.json --out-dir deliverables/excels --poll-attempts 18 --poll-seconds 3

# 收集千牛默认下载目录里的 Excel 到项目目录（适合 visual-operator 点击下载后）
qn-export collect-downloads --source-dir "/Users/bot1/Downloads/My WangWang" --out-dir deliverables/operator_downloads --since-minutes 120
```

## Cookie 文件格式

不要把 Cookie 贴到聊天里。只在本地受控文件中保存。支持：

```json
{"Cookie": "a=b; c=d"}
```

或浏览器导出的 cookie 数组：

```json
[
  {"name": "a", "value": "b"},
  {"name": "c", "value": "d"}
]
```

## 下一步

1. 让 `visual-operator` 登录千牛并采集 HAR：至少包含一次页面列表加载/刷新，以及一次点击下载。
2. 用 `qn-export scan-har` 生成候选接口 manifest。
3. 走纯 CLI 流程：`fetch-list` 获取模板列表 JSON → `build-downloads` 生成全量下载 manifest → `export-all --dry-run` → `export-all --limit 1` → 全量导出。
4. 对生意参谋真实接口，`export-all` 支持异步流程：先请求 `download.json`，再轮询 `queryDownloadUrl.json` 获得 OSS 签名 Excel 地址。
5. 如果真实接口返回结构字段不同，用 `build-downloads --id-field/--name-field/--download-url-field/--download-id-param` 显式指定。