zdata-cli

zdata-cli 是掌昆数据中台的命令行查询工具，用于在终端中查询报表数据和常用数据维度，并将结果输出为表格、JSON 或 HTML 文件。

功能概览

1. 综合报表查询：query 直接请求数据中台报表接口。
2. 远端维度查询：list ogames、list games 直接请求数据中台维度接口并输出。
3. 本地维度同步：cache sync 将原游戏、子游戏维度写入 SQLite。
4. 本地维度搜索：cache search 从 SQLite 查询名称和 ID，减少 AI 上下文占用。
5. 缓存管理：cache status 查看缓存状态，cache path 输出 SQLite 文件路径。

输出格式：

• query、list 支持 table、json、html。
• cache sync、cache search、cache status 支持 table、json。
• cache path 只输出数据库路径。

安装与构建

推荐通过 npm 一键安装命令和 AI skill：

npx @zktech/zdata-cli@latest install
zdata-cli --help

该安装方式会从 npm 包中选择当前系统对应的 zdata-cli Go 二进制文件，并把内置的 Agent skill 安装到 ~/.agents/skills/zdata。安装后请通过环境变量或配置文件提供 X-API-Key。

从源码本地构建：

go build -o zdata-cli ./cmd/zdata

如需给 AI 或脚本长期使用，建议将 zdata-cli 放入系统 PATH。

配置

X-API-Key 可通过以下方式提供，优先级从高到低：

1. 命令行参数 --api-key
2. 环境变量 ZDATA_X_API_KEY
3. 配置文件 ~/.zdata/config.json

配置文件示例：

{
  "x-api-key": "your-api-key",
  "base_url": "https://data-center.zkyouxi.com/"
}

base_url 可通过 --base-url、环境变量 ZDATA_BASE_URL 或配置文件设置。不设置时默认使用 https://data-center.zkyouxi.com/。

命令总览

zdata-cli query

zdata-cli list ogames
zdata-cli list games

zdata-cli cache sync ogames
zdata-cli cache sync games
zdata-cli cache sync all

zdata-cli cache search ogames
zdata-cli cache search games

zdata-cli cache status
zdata-cli cache path

报表查询

zdata-cli query --start 2026-05-01 --end 2026-05-31
zdata-cli query --start 2026-05-01 --end 2026-05-31 --game-group-id 5324
zdata-cli query --start 2026-05-01 --end 2026-05-31 --platform android
zdata-cli query --start 2026-05-01 --end 2026-05-31 --rebate-status aft --profit-status bef
zdata-cli query --start 2026-05-01 --end 2026-05-31 --group-by "stat_datetime,game_group_id,platform,media_id"
zdata-cli query --start 2026-05-01 --end 2026-05-31 --time-metrics paid-retention
zdata-cli query --start 2026-05-01 --end 2026-05-31 --data-type GROUP_DAY_HOURLY_TABLE --time-metrics reg-uv --time-dimensions 0,1,2,3
zdata-cli query --start 2026-05-01 --end 2026-05-31 --data-type GROUP_MONTH_DAILY_TABLE --time-dimensions 1,2,3,7,15
zdata-cli query --report material-click --start 2026-06-09 --end 2026-06-09 --material-type video --format html
zdata-cli query --start 2026-05-01 --end 2026-05-31 --format html --output report.html

query 的 --start 和 --end 为必填参数。可选筛选包括原游戏 ID、子游戏 ID、媒体 ID、平台、返点状态和分成状态。默认 --report 15d 查询市场 15D 归因综合报表；传 --report material-click 查询素材点击归因报表，该模式固定使用 USER_MATERIAL_CLICK、game_id,media_id,material_id,material_name,material_path 分组和素材点击指标，按 game_id desc, media_cost desc 排序，并在输出中显示 game_id/game_name、media_id/media_name 与素材预览列。HTML 输出会显示媒体名称，不显示独立媒体 ID 列；媒体 ID 会作为 data-media-id 挂在媒体名称单元格上。默认 --rebate-status bef、--profit-status aft；这两个状态参数每次只能传一个值。默认按 stat_datetime,game_group_id 分组，可通过 --group-by 改为 stat_datetime、game_group_id、platform、ad_convert_tag_name、ad_type_tag_name、ad_placement_tag_name、media_id、ad_creative_tag_name 中的一个或多个字段。为了兼容 macOS、Linux shell 和 Windows PowerShell，多个 --group-by 字段请使用双引号包起来，例如 --group-by "stat_datetime,game_group_id,platform,media_id"。

当 --group-by 包含 game_group_id 时，输出列会在其右侧自动补充 game_group_name；包含 media_id 时会自动补充 media_name。其他分组字段不会补充额外名称列。

--time-metrics 使用短 key 决定请求中的 time_metrics 值，默认是 roi，映射到 agg_ROI。当传 roi 时，附表 ROI 指标会显示为 1日ROI、2周ROI、3月ROI、24时ROI 这类完整名称；当传 paid-retention 时，会映射到 付费留存率，并将付费留存率指标显示为 1日付留、2周付留 这类短名称，避免表头过宽。

素材点击归因报表同样使用上述 --time-metrics 规则，默认请求 agg_ROI，可传 --time-metrics paid-retention 请求 付费留存率。

素材点击归因报表的 --profit-status 固定只支持 bef，ROI 附表只支持 dN_agg_pay_amount / media_cost，不会按 profit_status 切换到 aft 或 real_profit 字段。

--data-type 默认是 GROUP_DAY_DAILY_TABLE。当 --start 到 --end 的日期范围超过 60 天时，必须使用 --data-type GROUP_MONTH_DAILY_TABLE；这是文档和 AI 使用规则，CLI 不做硬校验。CLI 会根据 --data-type 推导请求中的 stat_time_type：GROUP_DAY_* 为 day，GROUP_MONTH_* 为 month。--time-dimensions 只传时间片数值，CLI 会根据 --data-type 推导附表维度：GROUP_DAY_HOURLY_TABLE 使用小时维度，默认 0..23；其他当前支持的表类型使用日维度，默认 1,2,3,4,5,6,7,10,15。GROUP_DAY_HOURLY_TABLE 只支持 --time-metrics cost 和 --time-metrics reg-uv，分别读取接口返回的 dhN_agg_cost 和 dhN_agg_reg_uv 字段，并显示为 N时消耗、N时注册。GROUP_DAY_DAILY_TABLE 和 GROUP_MONTH_DAILY_TABLE 支持 roi 与 paid-retention；使用 GROUP_MONTH_DAILY_TABLE 时，--start 必须是开始月份第一天，--end 必须是结束月份最后一天，可跨多个月。

素材点击归因报表可用 --material-type 筛选素材类型，取值为 image,img_group、img_grid、video、audio；也可用 --game-category-id、--tag-id 和 --is-origin 0|1 筛选游戏题材、素材标签和是否原创。

时间范围口径：今N日 表示从今天开始往前回溯 N 天，近N日 表示从昨天开始往前回溯 N 天。

平台值说明：

| 值 | 说明 | | --- | --- | | android | 安卓 | | ios | iOS | | harmony | 鸿蒙 | | douyin | 抖音小游戏、抖小 | | wechat | 微信小游戏、微小 | | other | 其他小游戏 |

返点状态：

| 值 | 说明 | | --- | --- | | bef | 返点前 | | aft | 返点后 | | c_return | 框返 |

分成状态：

| 值 | 说明 | | --- | --- | | bef | 分成前 | | aft | 分成后 | | real_profit | 实收 |

远端维度查询

zdata-cli list ogames
zdata-cli list games
zdata-cli list games --os-type 1
zdata-cli list games --format json
zdata-cli list games --format html --output games.html

list games 会将接口返回的树形数据整理为子游戏明细字段：

子游戏ID, 子游戏名称, 原游戏ID, 原游戏名称, 专区ID, 专区名称

SQLite 缓存

默认数据库路径：

~/.zdata/zdata.db

可通过 --db 覆盖。数据库文件会在首次打开缓存库时创建，例如执行 cache sync、cache search 或 cache status。cache path 只打印路径，不会创建数据库文件。

同步缓存：

zdata-cli cache sync ogames
zdata-cli cache sync games
zdata-cli cache sync all

查询缓存：

zdata-cli cache search ogames --name 球球 --format json
zdata-cli cache search ogames --id 5324
zdata-cli cache search games --name 奇遇西行 --format json
zdata-cli cache search games --ogame-id 5324
zdata-cli cache search games --ogame-name 球球三国2

缓存状态和路径：

zdata-cli cache status
zdata-cli cache status --format json
zdata-cli cache path

缓存库会创建普通索引和 FTS5 全文索引：

• ID 类过滤使用普通索引，例如 game_id、ogame_id、area_id。
• 名称类搜索优先使用 FTS5 trigram 索引，适合较大的子游戏列表。
• 2 个字符以内的短关键词会自动回退到 LIKE 查询，保证中文短词也能命中。

AI 推荐流程

当用户给出原游戏名称但报表查询需要 ID 时，推荐先查本地缓存：

zdata-cli cache search ogames --name 球球三国2 --format json
zdata-cli query --start 2026-05-01 --end 2026-05-31 --game-group-id 5324

如果缓存未命中，先同步再查询：

zdata-cli cache sync ogames
zdata-cli cache search ogames --name 球球三国2 --format json

命令文档

• 综合报表查询
• 维度列表查询

快速示例

zdata-cli query --start 2026-05-01 --end 2026-05-31
zdata-cli cache sync all
zdata-cli cache search ogames --name 球球 --format json
zdata-cli cache search games --ogame-id 5324 --format json