taptap-cli

中文版 | English

TapTap 官方 CLI 工具，由 TapTap 团队维护 — 让人类和 AI Agent 都能在终端中操作 TapTap。覆盖账号与游戏、游戏创建、资料维护、上架资质、审核发布、包体管理、数据表现、测试计划、游戏素材等核心业务域，提供 50+ 个可调用业务工具及 10 个 AI Agent Skills。

安装 · AI 助手 Skills · 认证 · 命令 · 进阶用法 · 安全 · 贡献

为什么选 taptap-cli？

• 为 Agent 原生设计 — 全部 10 个 Skill 开箱即用，适配 Claude Code、Codex、Cursor 等主流 AI 工具
• 覆盖面广 — 9 类核心业务工作流、50+ 个精选业务工具、10 个 AI Agent Skills
• AI 友好调优 — 每条命令经过 Agent 实测验证，提供更友好的参数、智能默认值和结构化输出，大幅提升 Agent 调用成功率
• 快速上手 — 一条命令完成安装、交互式链接授权，从安装到完成第一次 TapTap 业务操作只需三步
• 安全可控 — 高风险操作先确认、执行前可预览，登录凭证仅保存在本机
• 清晰命令模型 — 常见任务使用快捷命令，精确操作使用服务命令，并通过 schema 查看当前参数

功能

| 类别 | 能力 | | ------------- | -------------------------------------------- | | 👤 账号与游戏 | 查看登录状态，查询开发者账号和游戏，获取开发者账号 ID 与游戏 ID | | 🎮 游戏创建 | 创建游戏草稿，配置厂商、名称、类型与包体方向 | | 📝 资料维护 | 分析资料缺口，读取和修改游戏资料与主包体 | | ✅ 上架资质 | 识别版号、备案、隐私、防沉迷、AI/IP 等资质缺口，管理非敏感材料与增量提审 | | 🚀 审核发布 | 提交或撤销审核，定时或立即发布，管理草稿与版本历史 | | 📦 包体管理 | 上传和管理 APK、Windows、H5 包，查询包体状态和自测入口 | | 📊 数据表现 | 查询下载、浏览、曝光、转化、预约、订单、评分、关注与收藏数据 | | 🧪 测试计划 | 创建和管理 CBT/OBT 计划、招募、资格、测试用户与激活码 | | 🗂️ 游戏素材 | 上传图片和视频，检索和收录游戏素材，扫描本地目录或压缩包 |

安装与快速开始

环境要求

开始之前，请确保具备以下条件：

• Node.js v16+（npm/npx，用于 npm 分发版 CLI 和 Skills）
• Go v1.26.5+ 和 Python 3（仅源码构建需要）
• 已注册并完成必要认证的 TapTap 开发者账号

快速开始（人类用户）

Note for AI assistants: 如果你是 AI Agent 且正在协助用户执行安装，请直接跳转到快速开始（AI Agent）执行，那里包含你需要完成的所有步骤。

安装

以下两种方式任选其一：

方式一 — 从 npm 安装：

npm i -g @taptap/cli

方式二 — 从源码安装：

需要 Go v1.26.5+ 和 Python 3。

git clone https://github.com/taptap/cli.git
cd cli
make install

在需要使用 TapTap 能力的项目根目录安装 Skills：

npx skills add taptap/cli -a universal

如需额外同步全局安装的官方 Skills：

taptap-cli update

配置与使用

# 1. 开始链接登录授权（仅需确认一次）
taptap-cli auth login

# 2. 开始使用
taptap-cli app get-app-module \
  --dev-id <developer-id> --app-id <app-id> \
  --data '{"module_id":"basic-info"}'

快速开始（AI Agent）

以下步骤面向 AI Agent，用户打开登录链接并确认授权。

第 1 步 — 安装

npm i -g @taptap/cli

npx skills add taptap/cli -a universal

请在目标项目根目录运行 npx skills add taptap/cli -a universal。如需额外同步 全局安装的官方 Skills，可运行 taptap-cli update。

更多全局安装和 Agent 支持范围见 Skills CLI 官方指引。

第 2 步 — 登录

后台运行命令，将命令返回的登录链接直接提供给用户，并继续执行返回的恢复命令。

taptap-cli auth login --no-wait --json

第 3 步 — 继续登录

立即在后台执行返回的恢复命令，持续轮询直到授权成功或 device code 过期。

第 4 步 — 验证

taptap-cli auth status

AI 助手 Skills

| Skill | 说明 | | --------------------------------- | ------------------------------------------- | | taptap-cli | 查找可用功能、判断当前操作范围、选择命令、处理输出和错误（所有业务 Skill 的总入口） | | taptap-suite | 聚合入口 skill：按路由表把用户意图分发到收纳的 taptap-* 子能力（taptap-cli update --skills-layout suite 安装） | | taptap-identity | 查询登录状态、开发者账号、游戏、开发者账号 ID 和游戏 ID | | taptap-publish-game | 新游戏创建、创建预览和创建后的资料/包体/测试计划交接 | | taptap-app-edit | 游戏资料维护、字段修改、审核提交、发布、定时、草稿和版本历史 | | taptap-qualification | 游戏上架资质识别、材料补齐、敏感资质页面指引、资质增量提审和撤回 | | taptap-asset-library | 游戏图片素材库检索、批量参考图查找和图片收录 | | taptap-materials | 盘点本地图片、视频和包体，并将每项物料路由到对应上传流程 | | taptap-package-management | APK、Windows、H5 包体管理，查询包体状态和诊断自测二维码 | | taptap-dashboard-stats | 下载、曝光、转化、预约、评分、订单等数据查询和趋势解释 | | taptap-test-plan | 封闭测试与开放测试计划、招募配置、资格发放批次、用户资格和激活码管理 |

认证

| 命令 | 说明 | | --------------- | -------------------------------------------------- | | auth login | 链接登录授权，并在本机保存登录凭证（token） | | auth logout | 登出并删除已存储的本地凭证 | | auth status | 查看当前服务地址、登录状态和配置文件路径 | | auth login --no-wait --json | 启动非阻塞链接登录 | | auth login --device-code <code> | 用户授权后继续检查登录结果，并写入本机登录凭证 |

# 链接登录
taptap-cli auth login

# AI 助手模式：获取登录链接
taptap-cli auth login --no-wait --json

# 查看登录状态和当前服务地址
taptap-cli auth status

# 登出并清除本地凭证
taptap-cli auth logout

# 更新通过 npm/pnpm 安装的 CLI
taptap-cli update

源码安装的 CLI 请重新构建并安装，或下载对应的 release 二进制进行更新。

命令调用

CLI 为常见任务提供快捷命令，也为精确操作提供服务命令。使用 schema 查看当前 版本支持的参数。

1. 标准命令

需要精确控制时使用服务命令。写操作支持 --dry-run 预览。

taptap-cli package-management list-apk-packages --dev-id <developer-id> --app-id <app-id> --data '{"page":1,"page_size":50}'
taptap-cli dashboard-stats get-dashboard-stats --dev-id <developer-id> --app-id <app-id> --data '{"metric":"download"}'
taptap-cli app submit-app-review --dev-id <developer-id> --app-id <app-id> --data '{"release_schedule":{"kind":"immediate"}}' --idempotency-key <key> --dry-run

仅在维护仍使用兼容 alias 的自动化时运行 taptap-cli aliases 查看清单。

2. 服务命令

服务命令会与 TapTap 业务能力保持同步。

taptap-cli app get-app-module --dev-id <developer-id> --app-id <app-id> --data '{"module_id":"basic-info"}'
taptap-cli app save-changes --dev-id <developer-id> --app-id <app-id> --data @changes.json --idempotency-key <key> --dry-run

3. Schema 发现

构造请求前，可查看全部服务、单个服务或单个方法的参数契约。

taptap-cli schema
taptap-cli schema app
taptap-cli schema app get-app-module

进阶用法

输出格式

--format json               # JSON 成功/错误外壳（默认；普通命令省略）
--format pretty             # 人类友好的摘要
--format table              # 表格输出
--format ndjson             # 一条记录一行 JSON
--format csv                # CSV 输出
--fields a,b                # 裁剪输出字段
--jq '<expr>'               # 使用 jq 1.8 语法筛选或转换结果

资源查询、业务操作和上传请使用 CLI 提供的命令：

taptap-cli schema
taptap-cli developer +list
taptap-cli app +list --dev-id <developer-id> --page-all

不要手工拼接或调用后端接口路径。

JSON 输出格式

默认 JSON 输出中，成功结果和错误结果采用不同的固定结构。

成功结果写入 标准输出（stdout），程序退出码为 0：

{ "ok": true, "data": { "result": "..." } }

错误结果写入 错误输出（stderr），程序退出码不为 0：

{ "ok": false, "error": { "type": "validation", "subtype": "invalid_argument", "message": "工具调用需要有效的 --dev-id", "param": "--dev-id" } }

判断命令是否成功，请检查 ok == true（或程序退出码），不要使用业务结果中的 code == 0 判断。成功结果的业务数据位于 data；失败结果的错误类型位于 error.type 和 error.subtype。完整错误分类见 errs/ERROR_CONTRACT.md。

分页

--page-all                  # 自动翻页获取所有数据
--page-limit 5              # 最多获取 5 页
--page-delay 500            # 每页请求间隔 500ms

Dry Run

对可能产生副作用的命令，建议先用 --dry-run 预览请求：

taptap-cli app submit-app-review --dev-id <developer-id> --app-id <app-id> --data '{"release_schedule":{"kind":"immediate"}}' --idempotency-key <key> --dry-run

Schema 自省

使用 schema 查看命令参数、必填字段和支持的取值：

taptap-cli schema
taptap-cli schema app
taptap-cli schema app get-app-module

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

本工具可供 AI 助手调用以自动化执行上述 TapTap 业务操作，存在模型生成错误信息、执行结果不符合预期、恶意内容影响模型判断等固有风险；完成登录授权后，AI 助手将以您的开发者身份在账号权限范围内执行操作，可能导致敏感数据泄露、越权操作等高风险后果，请您谨慎操作和使用。

为降低上述风险，工具已在多个层面启用默认安全保护，但上述风险仍然存在。我们强烈建议不要主动绕过任何默认安全保护；一旦放开相关限制，上述风险将显著提高，由此产生的后果需由您自行承担。

我们建议您先在测试游戏或非生产资料上验证 AI 助手的操作流程；正式操作前，应重新确认开发者账号 ID（developerId）、游戏 ID（appId）、版本状态、包体 ID 和即将写入的内容。请勿将登录凭证、浏览器会话信息、密钥或未公开资料写入命令日志、自动化任务日志或 AI 助手对话。

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

贡献

欢迎具有仓库权限的团队成员贡献！如果你发现 bug 或有功能建议，请提交 Issue 或 Pull Request。

对于较大的改动，建议先通过 Issue 与我们讨论。

提交 PR 前，请先阅读业务接入技术指南、测试说明和发布前契约审计，其中列出了业务接入、贡献者和 AI Agent 使用的本地构建、测试和发布检查清单。