@douyin-minigame/cli

抖音小游戏 CLI，用于登录开发者平台、查询游戏数据，并将查询结果写入本地结构化文件。

基本信息

| 项目 | 说明 | | ---------- | -------------------------------------------------------------------- | | CLI 命令名 | dymg | | npm 包名 | @douyin-minigame/cli | | 运行时 | Node.js 24.x | | 产物入口 | dist/cli.js | | 随包 Skill | skills/douyin-minigame | | 输出方式 | 业务查询结果默认写入 data.csv、raw_response.json、summary.json |

能力范围

• 登录、查看登录态、退出登录
• 查询开发者名下的小游戏列表
• 查询榜单、热点等资讯数据
• 查询用户分析、增长分析数据
• 将每次数据查询结果写入独立目录，便于 Agent、脚本或人工继续处理
• 随 npm 包发布 douyin-minigame Agent Skill，并支持通过 CLI 同步到本机 Skill 目录

安装与使用

全局安装后，会暴露 dymg 命令。

npm：

npm install -g @douyin-minigame/cli

pnpm：

pnpm add -g @douyin-minigame/cli

yarn：

yarn global add @douyin-minigame/cli

bun：

bun add -g @douyin-minigame/cli

查看帮助：

dymg --help

查看某个命令的完整参数：

dymg <command-group> <command> --help
dymg growth metric-query --help

也可以通过 npx 按需执行：

npx -y @douyin-minigame/cli --help

安装或同步随包发布的 Agent Skill：

dymg skills install

快速开始

1. 登录开发者平台。

dymg auth login

2. 查看当前登录状态。

dymg auth status

3. 查询开发者名下的游戏列表。

dymg game game-list

4. 查询业务数据，并指定输出根目录。

dymg analytics behavior-query \
  --app-id <app-id> \
  --start-date 2026-06-01 \
  --end-date 2026-06-07 \
  --output-dir ./dymg-output

登录流程

| 命令 | 说明 | | ------------------------- | ------------------------------------------------------------------- | | auth login | 发起登录授权，默认等待用户在浏览器完成授权并自动完成登录 | | auth login --no-wait | 打印授权链接后结束进程，适合 Agent 发起登录流程 | | auth login --resume | 继续完成上一次 --no-wait 发起的登录流程 | | auth status | 查看当前登录状态 | | auth logout | 退出登录并清理本机状态 | | auth check-dir-writable | 用于 Agent 测试执行环境中的当前登录态目录是否可写，并输出结构化结果 |

Agent 分段式登录示例：

dymg auth login --no-wait
dymg auth login --resume

命令总览

| 命令组 | 命令 | 用途 | | ----------- | ---------------------------------------------------- | -------------------------------------- | | auth | login / status / logout / check-dir-writable | 登录与登录态管理、登录态目录写权限自检 | | game | game-list | 查询开发者名下的游戏列表 | | insight | ranking-list | 查询游戏榜单数据 | | insight | hotspot-list | 查询热点内容与热度信息 | | insight | element-list | 查询热门元素、标签、热度和关联信息 | | insight | theme-list | 查询热门题材、市场机会和趋势信息 | | analytics | behavior-query | 查询活跃、留存、时长、付费等行为指标 | | analytics | realtime-query | 查询实时在线、实时活跃等数据 | | analytics | retention-query | 查询留存分析数据 | | analytics | source-query | 查询来源渠道与场景分布 | | analytics | profile-query | 查询地域、年龄、性别等画像分布 | | analytics | device-query | 查询机型、品牌、宿主版本等设备分布 | | growth | metric-query | 查询新增、转化、收入等增长指标 | | 根命令 | check-update | 检查 CLI 是否有可用更新 | | 根命令 | update | 更新当前 CLI 到最新版或指定版本 | | skills | install | 安装或同步随包发布的 Agent Skill |

常用示例

更新 CLI

dymg check-update
dymg update
dymg update --target-version 1.2.3
dymg update --skip-skills

update 默认会更新 CLI 并同步随包发布的 Skill；传入 --skip-skills 时只更新 CLI。未显式传入 --package-manager 时，CLI 会尝试自动识别当前环境；识别失败时，需要显式传入 --package-manager npm|pnpm|yarn|bun。

skills install 把随包发布的 Agent Skill 同步到本机全局 Skill 目录。该命令兼容全局安装和 npx 临时调用场景。

check-update 用于手动检查更新；发现新版本时，可按提示执行 dymg update 更新 CLI 并同步 Skill。

CLI 会在业务命令结束后低频检查更新

查询游戏列表

dymg game game-list
dymg game game-list --page-index 1 --page-size 20

查询榜单与热点

dymg insight ranking-list --rank-type 1
dymg insight hotspot-list --top-n 10
dymg insight element-list --keyword 经营 --page 1 --page-size 20
dymg insight theme-list --include-top-videos --page 1 --page-size 20

查询用户分析

dymg analytics behavior-query \
  --app-id <app-id> \
  --start-date 2026-06-01 \
  --end-date 2026-06-07

dymg analytics retention-query \
  --app-id <app-id> \
  --start-date 2026-06-01 \
  --end-date 2026-06-07 \
  --retention-scene 1

dymg analytics device-query \
  --app-id <app-id> \
  --dimension 1 \
  --top-n 20

查询增长分析

growth metric-query 需要显式传入数据时效、维度、指标和一级渠道。列表参数使用英文逗号分隔，不加空格。

dymg growth metric-query \
  --app-id <app-id> \
  --activate-start-date 2026-06-01 \
  --activate-end-date 2026-06-02 \
  --dimension 1,2 \
  --metric 1,24 \
  --life-time 24:1,2 \
  --first-channel 1 \
  --freshness-type 1

dymg growth metric-query \
  --app-id <app-id> \
  --activate-start-date 2026-06-01 \
  --activate-end-date 2026-06-07 \
  --dimension 1 \
  --metric 11,21 \
  --life-time 11:7,14,30 \
  --life-time 21:7,14,30 \
  --first-channel 1,2,3,4 \
  --freshness-type 2

通用参数

| 参数 | 适用范围 | 说明 | | -------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | --caller <agent> | 全局参数 | 标识调用来源；合法值包括 coze、cursor、claude_code、github_copilot、gemini_cli、trae、manus、devin、codex、hermes、openclaw、unknown | | --output-dir <dir> | 业务查询命令 | 指定输出根目录；CLI 会继续创建 command-timestamp 子目录 | | --app-id <appId> | 需要指定小游戏的业务查询命令 | 小游戏 appId；insight 命令不需要 |

常见边界

| 场景 | 规则 | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | 用户分析 | analytics realtime-query 仅支持当天；其他 analytics 查询支持最近 90 天 | | 增长分析 | --freshness-type 1 为实时数据，支持最近 2 天；--freshness-type 2 为离线数据，支持最近 180 天 | | 榜单分页 | insight ranking-list --page-size 最大为 200，且 page * pageSize 不能超过 200 | | 游戏类型筛选 | insight ranking-list --game-type-list 和 insight hotspot-list --game-type-ids 使用游戏类型/分类标签 ID，完整枚举见随包 Skill reference | | 热点筛选 | insight hotspot-list 使用关键词、游戏类型或题材筛选时，--top-n 最大为 50 | | 热门元素/题材 | insight element-list --page-size 和 insight theme-list --page-size 最大为 50 | | 输出目录 | --output-dir 是输出根目录，CLI 会继续创建 command-timestamp 子目录 |

输出说明

业务查询命令默认写出三类数据查询结果：

| 文件 | 内容 | | ------------------- | ------------------------------------------------------------------------------------------------------- | | data.csv | 扁平化后的业务数据，适合表格查看或脚本处理 | | raw_response.json | 接口原始响应 | | summary.json | 本次执行摘要，包括命令、数据查询结果路径、行数等信息；分页类命令会额外包含结构化结果元信息 resultMeta |

标准输出只展示执行结果和 summary.json 路径，不直接打印业务明细。

分页类命令的 summary.json 读取口径：

• rowCount 仅表示 data.csv 实际写入的行数
• resultMeta.total 表示服务端可提供的总量；若 resultMeta.unit 存在，则按该单位解释
• resultMeta.returnedCount 表示本次接口返回的记录数；若 resultMeta.unit 存在，则按该单位解释
• resultMeta.page、pageSize、hasMore、nextCursor 仅在接口提供分页信息时出现；hasMore 优先使用服务端显式返回值，缺失时按 page * pageSize < total 推导
• resultMeta.unit 仅在返回数量单位与 rowCount 不一致时出现

仅在需要判断分页总量、是否还有下一页或是否已取全时，优先读取 summary.json 的 resultMeta，缺失时再回退到 raw_response.json

如需指定输出位置，使用 --output-dir <dir> 设置输出根目录；CLI 会在该目录下创建本次查询子目录，避免覆盖前一次结果。

输出目录示例：

./dymg-output/
  analytics-behavior-query-20260710-153012/
    data.csv
    raw_response.json
    summary.json

安全与风险提示（使用前必读）

本工具可操作抖音小游戏开发者平台，完成 CLI 登录授权后，将以您的开发者账号身份在授权范围内执行数据查询与导出操作，可能导致敏感数据泄露、越权查询、导出结果外泄等高风险后果，请您谨慎操作和使用。

为降低上述风险，工具已在多个层面启用默认安全保护（例如以当前 CLI 登录态鉴定账号身份、按名下游戏权限校验查询范围、业务明细默认不直接打印到终端，而是落地到数据查询结果目录），但上述风险仍然存在。我们强烈建议不要主动修改任何默认安全配置；一旦放开相关限制，上述风险将显著提高，由此产生的后果需由您自行承担。

我们建议您将本工具作为私人使用，谨慎将其多用户共享环境或允许其他用户与其交互，以避免开发者账号权限被滥用或数据泄露。

请您充分知悉全部使用风险，使用本工具即视为您自愿承担相关所有责任。

发布说明

当前 npm 包发布编译后的 CLI 产物、随包 Agent Skill 和必要元数据。