TradPlus CLI 使用说明

修订历史

发布时间	修订说明
2026-05-22	新增 §5.1/§8 命令参数速查、写操作参数表、典型工作流；明确 flags/--args 传参规范
（更早）	安装、鉴权、输出格式与功能列表

1. 简介

TradPlus CLI 是面向 TradPlus OpenAPI 的命令行工具，命令名为 tp。它适合在终端、脚本、CI 或服务器环境中完成配置查询、报表导出、巡检和少量配置修改。

CLI 的特点：

• 可在 Shell 脚本、定时任务、CI 中使用。
• 支持 json、jsonl、csv、table 等输出格式。
• 写操作默认不会直接执行，需要显式添加 --yes。
• 复杂参数可通过 --args 传入 JSON 对象。

2. 安装

推荐使用安装脚本。脚本会自动识别操作系统和 CPU 架构，下载对应的 tp 二进制包并安装。

系统	CPU 架构	安装命令
macOS / Linux	amd64 / arm64	install-tp.sh
Windows	amd64 / arm64	install-tp.ps1

2.1 macOS / Linux

复制并执行：

curl -fsSL "https://mcp.tradplusad.com/cli/tp/install-tp.sh?version=latest" | bash

如果只想确认会下载哪个版本，不实际安装：

curl -fsSL "https://mcp.tradplusad.com/cli/tp/install-tp.sh?version=latest" | bash -s -- --dry-run

2.2 Windows PowerShell

复制并执行：

iwr "https://mcp.tradplusad.com/cli/tp/install-tp.ps1?version=latest" -UseB | iex

如遇执行策略限制，可先下载安装脚本，再用下面方式执行：

powershell -ExecutionPolicy Bypass -File .\install-tp.ps1

2.3 安装后验证

tp version
tp --help

如果提示 tp: command not found，说明安装目录不在 PATH 中。请根据安装脚本输出，把安装目录加入当前 shell 或系统环境变量。

3. 配置凭证

CLI 调用 OpenAPI 时需要 API Key 和密钥。可在 TradPlus 后台“我的账号”中获取。

名称	CLI 字段	说明
API Key	bear	标识用户身份
密钥	secret	用于请求签名
API 地址	base_url	推荐 https://api-developer.tradplusad.com

3.1 写入本地配置

推荐把凭证写入本地配置，后续命令就不需要重复输入。将 <your bear> 和 <your secret> 替换为自己的 API Key 和密钥：

tp config set --bear "<your bear>" --secret "<your secret>" --base-url "https://api-developer.tradplusad.com"

查看本地配置：

tp config get

配置文件默认保存到：

~/.tradplus/config.yaml

3.2 使用环境变量

适合脚本、CI、容器等不希望写入本地配置文件的场景。

export TRADPLUS_BEAR="<your bear>"
export TRADPLUS_SECRET="<your secret>"
export TRADPLUS_BASE_URL="https://api-developer.tradplusad.com"

其中 TRADPLUS_BASE_URL 建议使用 https://api-developer.tradplusad.com。环境变量只在当前终端会话中生效，新的终端窗口需要重新设置，或写入自己的 shell 配置文件。

3.3 使用命令行参数

也可以在单次命令中直接传入：

tp app list --bear "<your bear>" --secret "<your secret>"

通常无需在单次命令中设置 API 地址。如需显式指定，建议值为 https://api-developer.tradplusad.com：

tp app list --bear "<your bear>" --secret "<your secret>" --base-url "https://api-developer.tradplusad.com"

鉴权优先级从高到低为：

1. 命令行参数：--bear、--secret、--base-url
2. 环境变量：TRADPLUS_BEAR、TRADPLUS_SECRET、TRADPLUS_BASE_URL
3. 本地配置文件：~/.tradplus/config.yaml

4. 快速开始

安装并配置完成后，建议先执行：

tp version
tp auth summarize
tp app list --format table

确认某个应用或广告位是否在当前账号权限范围内：

tp auth scope --app-uuid "<app_uuid>"
tp auth scope --adseat-uuid "<adseat_uuid>"

查看某个命令的参数：

tp app list --help
tp placement upsert --help
tp report v4 --help

5. 输出格式与通用参数

常用全局参数：

参数	说明
--format compact	简洁文本，适合人工查看
--format table	表格输出，适合终端查看
--format json	JSON 输出，适合脚本处理
--format jsonl	一行一个 JSON，适合流式处理
--format csv	CSV 输出，适合导入 Excel 或数据工具
--fields	逗号分隔字段名，用于控制列表输出字段
--args	JSON 对象字符串，用于传入复杂参数
--yes	确认执行写操作
--print-request	写操作执行前打印最终请求参数，便于核对

示例：

tp app list --format table
tp app list --format json
tp app list --format csv --fields app_uuid,app_name,platform
tp adseat list --app-uuid "<app_uuid>" --format table --fields adseat_uuid,seat_name,ad_type

部分参数需要数字类型，例如 ad_type、os、adsource_id、api_token_id 等。使用 --args 传 JSON 时，应传数字而不是字符串：

tp platform list --args '{"ad_type":4,"os":1}'

不要写成：

tp platform list --args '{"ad_type":"4","os":"1"}'

5.1 参数传递规范（必读）

tp 不支持 在命令末尾用 参数名 参数值 的 positional 方式传参。下列写法均无效：

# ❌ 错误：currency 不会被识别
tp placement list currency USD

# ❌ 错误：key value 顺序写法无效
tp adseat list app_uuid abc123

应使用 --flag 或 --args JSON：

# ✅ 使用子命令 flags
tp placement list --currency USD
tp adseat list --app-uuid "abc123"

# ✅ 使用 --args（字段名与 OpenAPI / MCP 工具一致，snake_case）
tp placement list --args '{"currency":"USD","adseat_uuids":"<uuid>","is_on":-1}'

传递方式	字段命名	适用场景
子命令 flags	kebab-case，如 --adseat-uuid、--app-uuids	常用筛选；见各命令 --help
--args JSON	snake_case，如 adseat_uuids、start_date	子命令未暴露的字段、写操作复杂 body
全局 flags	--format、--fields、--yes 等	输出格式与写确认

合并规则：子命令先把 flags 写入参数 map，再合并 --args；同名字段以 --args 为准。

发现参数的三条路径（人工与 AI 均适用）：

1. tp <子命令> --help — 该子命令已注册的 flags 与示例
2. 本文 §8 命令参数速查 — 子命令 ↔ OpenAPI 字段对照表
3. tp debug tools / tp debug invoke <MCP工具名> --args '...' — 与 MCP 工具名及字段完全一致

参数校验失败时，CLI 会输出与 MCP 相同的参数说明（含必填项表格）；其中 currency: USD 表示 JSON 字段，不是 shell positional 写法。

5.2 flag 与 OpenAPI 字段对照（常见）

CLI flag	--args / OpenAPI 字段	说明
--app-uuid	app_uuid 或 app_uuids	单值查详情时常映射为 app_uuids
--adseat-uuid	adseat_uuids	列表接口多为复数字段
--currency	currency	取值 USD 或 CNY（大写）
--start / --end	start_date / end_date	报表日期，格式 YYYY-MM-DD
--placement-id	placement_ids	单 ID 查询

5.3 Shell 与 --args 引号

--args 的值必须是 单个 JSON 对象字符串。不同 Shell 引号规则如下：

Shell	推荐写法	说明
bash / zsh	--args '{"currency":"USD"}'	外层单引号，JSON 内双引号
bash / zsh	--args "{\"currency\":\"USD\"}"	外层双引号时需转义内部 "
PowerShell	--args '{\"currency\":\"USD\"}' 或 --args "{"currency":"USD"}"	避免 PowerShell 解析 {}
cmd.exe	使用 --args "{\"currency\":\"USD\"}"	或改用 @file.json 思路：先写文件再 type file

数字字段在 JSON 中不要加引号："is_on":-1、"ad_type":4。
布尔 OpenAPI 多用 0/1 整数，而非 JSON true/false。

合并 flags 与 --args 示例：

# flags 提供 currency，--args 补充 is_on（二者合并后发送）
tp placement list --currency USD --args '{"is_on":-1}' --format json

# 同名字段时 --args 覆盖 flags（不推荐混用，易混淆）
tp placement list --currency CNY --args '{"currency":"USD"}'   # 最终 currency=USD

6. 写操作确认机制

为了避免误改线上数据，写操作默认只做 dry-run，不会真正提交。需要确认执行时添加 --yes。

示例：

# 仅 dry-run，不真正删除
tp app delete --args '{"app_uuid":"<app_uuid>"}'

# 打印最终请求参数，核对后再决定是否执行
tp app delete --print-request --args '{"app_uuid":"<app_uuid>"}'

# 确认后真正执行
tp app delete --args '{"app_uuid":"<app_uuid>"}' --yes

建议生产环境写操作都按 “dry-run → 核对参数 → --yes” 的顺序执行。

7. 功能列表

以下为当前 CLI 已提供的主要命令。具体参数以 tp <命令> --help 为准。

7.1 配置、鉴权与巡检

命令	说明
tp config set	写入本地配置
tp config get	查看本地配置，敏感字段会脱敏
tp version / tp --version	查看 CLI 版本
tp auth summarize	查看当前凭证摘要
tp auth scope	校验当前凭证对应用、广告位的访问权限
tp summarize app	查看单应用配置总览
tp summarize adseat	查看单广告位总览
tp summarize platform	查看平台侧健康或使用摘要

7.2 应用、广告位与广告场景

命令	说明
tp app list	查询应用列表
tp app get	查询单个应用详情
tp app probe	根据应用商店链接探测应用信息
tp app create / update / delete	创建、更新、删除应用
tp adseat list	查询应用下广告位
tp adseat get	查询广告位详情
tp adseat create / update	创建、更新广告位
tp adscene list	查询广告场景
tp adscene upsert	创建或更新广告场景

7.3 广告源、平台与授权

命令	说明
tp placement list	查询广告源列表
tp placement get	查询广告源详情
tp placement list-by-app	按应用查询广告源，便于复用配置
tp placement upsert	创建或更新广告源
tp placement toggle	启用或停用广告源
tp platform legacy	查询广告平台 ID 列表
tp platform list	按广告类型和系统查询可用广告平台目录
tp token list / get / update	查询或更新 API Token
tp account-template get	查询广告平台授权字段模板
tp account-template save	保存广告平台授权信息

查询广告平台 ID 示例：

tp platform legacy --format table --fields adsource_id,name
tp platform list --ad-type 4 --os 1 --format table

其中 tp platform legacy 适合查通用广告平台 ID；tp platform list 适合在创建广告源前，按广告位类型与 Android / iOS 过滤可用平台。

7.4 中介组与 A/B 测试

命令	说明
tp intermediary list	查询广告位下中介组
tp intermediary upsert	创建或更新中介组
tp group-placement list	查询中介组内广告源项
tp group-placement update	更新中介组内广告源项属性
tp group-placement toggle	启用或停用中介组内广告源项
tp abtest list	查询 A/B 测试列表
tp abtest create / modify / start / close	创建、修改、启动或关闭 A/B 测试

7.5 报表

命令	说明
tp report v4	查询通用 V4 报表
tp report api	查询三方 API 维度报表
tp report tp	查询 TradPlus 平台报表
tp report abtest	查询 A/B 测试报表
tp report forecast	查询应用预估数据
tp report confidence	查询 A/B 置信度
tp report active-users	查询活跃用户数据

示例：

tp report v4 --start 2026-05-01 --end 2026-05-07 --format json
tp report active-users --app-uuid "<app_uuid>" --start 2026-05-01 --end 2026-05-07 --format csv

7.6 字典数据

命令	说明
tp meta categories	查询应用分类
tp geo regions	查询国家或地区
tp geo cities	查询城市，可按地区过滤

8. 命令参数速查

本节按 ssp_api 同款表格 列出各子命令的请求参数及 CLI 传参方式。
MCP 工具名 与 tp debug invoke <工具名> 一致；写操作另需 --yes。

表列说明：

列	含义
字段	OpenAPI / MCP 请求参数字段名（--args JSON 键）
类型	字符串 / 整数 / JSON 对象等
必传	Y=必填，N=可选
CLI flags	可直接使用的 --xxx；- 表示仅能通过 --args
说明	取值约束与备注

8.0 命令索引（CLI ↔ MCP ↔ OpenAPI）

便于检索：左列为终端命令，中间为 MCP 工具名（tp debug invoke 用），右列为 ssp_api 章节锚点（HTTP 直调时参考）。

CLI 命令	MCP 工具	ssp_api 章节（概览）
tp app list / get	list_apps	应用管理
tp app probe	get_app_info	应用管理
tp app create / update / delete	create_app / update_app / delete_app	应用管理
tp adseat list / get	list_adseats	广告位
tp adseat create / update	create_adseat / update_adseat	广告位
tp adscene list	list_adscenes	广告场景
tp adscene upsert	upsert_adscene	广告场景
tp placement list / get	list_placements	广告源
tp placement list-by-app	get_placement_list_by_app	广告源
tp placement upsert / toggle	upsert_placement / toggle_placement	广告源
tp platform legacy	list_adsources	附录广告平台 ID
tp platform list	new_get_adsource_list	广告平台目录
tp token list / get / update	list_api_tokens / get_api_token_list_detail / update_api_token	授权管理
tp account-template get / save	get_account_template / save_authorization_info	授权管理
tp intermediary list / upsert	list_intermediary_groups / upsert_intermediary_group	中介组
tp group-placement list / update / toggle	list_group_placements / update_group_placement / toggle_group_placement	中介组广告源
tp abtest list / create / …	list_abtests / create_abtest / …	A/B 测试
tp report v4 / api / tp	query_v4_report / query_v4_api_report / query_v4_tp_report	§3 报表
tp report abtest	query_v4_abtest_report	§3 报表
tp report active-users	query_active_user_report	§3 报表
tp meta categories	list_app_categories	附录分类
tp geo regions / cities	list_regions / list_cities	附录地区
tp auth scope	validate_access_scope	—
tp auth summarize	summarize_current_access	—
tp summarize app / adseat / platform	summarize_app_configuration 等	—

8.1 配置与鉴权

tp config set

字段	类型	必传	CLI flags	说明
bear	String	N	--bear	API Key
secret	String	N	--secret	密钥
base_url	String	N	--base-url	API 根地址

tp auth scope（MCP: validate_access_scope）

字段	类型	必传	CLI flags	说明
app_uuid	String	N*	--app-uuid	与 adseat_uuid 至少传一个
adseat_uuid	String	N*	--adseat-uuid	与 app_uuid 至少传一个
currency	String	N	-	默认 USD

tp auth summarize（MCP: summarize_current_access）

无业务参数。

tp summarize app（MCP: summarize_app_configuration）

字段	类型	必传	CLI flags	说明
app_uuid	String	Y	--app-uuid	应用 UUID
currency	String	N	-	USD 或 CNY，默认 USD

tp summarize adseat（MCP: summarize_adseat_overview）

字段	类型	必传	CLI flags	说明
adseat_uuid	String	Y	--adseat-uuid	广告位 UUID
currency	String	Y	-	USD 或 CNY

tp summarize platform（MCP: summarize_platform_auth_health / summarize_platform_usage）

字段	类型	必传	CLI flags	说明
kind	String	N	--kind	health（默认）或 usage
currency	String	Y*	-	usage 统计必填
adsource_id	String	N	-	按平台 ID 过滤
adsource_name	String	N	-	按平台名称过滤

8.2 应用与广告位

tp app list（MCP: list_apps）

字段	类型	必传	CLI flags	说明
app_uuids	String	N	--app-uuids	逗号分隔，最多 100；传入时忽略分页
page	Int	N	--page	默认 1
limit	Int	N	--limit	每页条数
—	—	N	--all	无 app_uuids 时自动翻页（CLI 扩展）

tp app list --format table
tp app list --app-uuids "uuid1,uuid2" --format json
tp app list --all --format json

tp app get（MCP: list_apps）

字段	类型	必传	CLI flags	说明
app_uuids	String	Y	--app-uuid	单个 UUID

tp app probe（MCP: get_app_info）

字段	类型	必传	CLI flags	说明
app_url	String	Y	--url	商店链接；--args 中可用 store_url 别名

tp app create / update / delete（写操作）

参数通过 --args JSON 传入，字段与 ssp_api 应用管理接口 一致；须 --yes。
缺参时执行不带 --yes 的命令可查看参数说明表。

tp adseat list（MCP: list_adseats）

字段	类型	必传	CLI flags	说明
app_uuid	String	N*	--app-uuid	与 adseat_uuids 二选一
adseat_uuids	String	N*	--adseat-uuids	逗号分隔
page	Int	N	--page	默认 1

tp adseat list --app-uuid "<app_uuid>" --format table

tp adseat get（MCP: list_adseats）

字段	类型	必传	CLI flags	说明
adseat_uuids	String	Y	--adseat-uuid	单个或多个（逗号分隔）

tp adseat create / update（写操作）

见 ssp_api 广告位接口；--args + --yes。

tp adscene list（MCP: list_adscenes）

字段	类型	必传	CLI flags	说明
app_uuid	String	N	--app-uuid	按应用过滤
adseat_uuid	String	N	-	按广告位过滤
page	Int	N	-	默认 1

8.3 广告源、平台与授权

tp placement list（MCP: list_placements）

字段	类型	必传	CLI flags	说明
currency	String	Y	--currency	USD 或 CNY；漏传报 1001
placement_ids	String	N	-	逗号分隔，最多 100
adsource_ids	String	N	-	逗号分隔
app_uuids	String	N	-	逗号分隔
adseat_uuids	String	N	--adseat-uuid	逗号分隔；flag 写入 adseat_uuids
page	Int	N	--page	默认 1，每页 100
is_on	Int	N	-	1=仅开启(默认), 0=仅关闭, -1=全部

tp placement list --currency USD
tp placement list --currency USD --adseat-uuid "<adseat_uuid>"
tp placement list --args '{"currency":"USD","is_on":-1}' --format json

tp placement get（MCP: list_placements）

字段	类型	必传	CLI flags	说明
placement_ids	String	Y	--placement-id	广告源 ID

tp placement list-by-app（MCP: get_placement_list_by_app）

字段	类型	必传	CLI flags	说明
app_uuid	String	Y	--app-uuid	应用 UUID
platform	String	N	--platform	如 pangle

tp placement upsert / toggle（写操作）

--args + --yes；字段见 ssp_api 广告源接口与 MCP upsert_placement / toggle_placement。

tp platform legacy（MCP: list_adsources）

无参数。

tp platform list（MCP: new_get_adsource_list）

字段	类型	必传	CLI flags	说明
ad_type	Int	Y	--ad-type	1 原生 2 插屏 3 开屏 4 横幅 5 激励
os	Int	Y	--os	1=Android, 2=iOS

tp platform list --ad-type 4 --os 1 --format table

tp token list（MCP: list_api_tokens）

无专用 flags；可用 --args 传筛选字段。

tp token get（MCP: get_api_token_list_detail）

字段	类型	必传	CLI flags	说明
api_token_id	String	Y	--token-id	授权 ID

tp token update / tp account-template save（写操作）

--args + --yes。

tp account-template get（MCP: get_account_template）

字段	类型	必传	CLI flags	说明
adsource_id	String	Y	--adsource-id	广告平台 ID

8.4 中介组与 A/B 测试

tp intermediary list（MCP: list_intermediary_groups）

字段	类型	必传	CLI flags	说明
adseat_uuid	String	Y	--adseat-uuid	广告位 UUID
currency	String	Y	-	USD 或 CNY
page	Int	N	--page	默认 1

tp intermediary list --adseat-uuid "<uuid>" --args '{"currency":"USD"}'

tp group-placement list（MCP: list_group_placements）

字段	类型	必传	CLI flags	说明
adseat_uuid	String	Y	-	广告位 UUID
currency	String	Y	-	USD 或 CNY
group_id	Int	N	--group-id	中介组 ID
bucket_id	Int	N	-	AB 分组 ID
page	Int	N	--page	默认 1

tp abtest list（MCP: list_abtests）

字段	类型	必传	CLI flags	说明
adseat_uuid	String	N	--adseat-uuid	按广告位过滤
abtest_id	Int	N	-	精确查询
page	Int	N	--page	默认 1

中介组 / AB 写操作：--args + --yes。

8.5 报表

报表 CLI flags 映射为 start_date / end_date（非 start/end 作为 API 字段）。

tp report v4 / api / tp（MCP: query_v4_report 等）

字段	类型	必传	CLI flags	说明
start_date	String	Y	--start	YYYY-MM-DD
end_date	String	Y	--end	YYYY-MM-DD
app_uuid	String	N	--app-uuid	单应用
adseat_uuid	String	N	--adseat-uuid	单广告位
metrics	String	N	-	逗号分隔指标
group_by	String	N	-	聚合维度
currency	String	N	-	USD 或 CNY
timezone	String	N	-	UTC+8 等

tp report v4 --start 2026-05-01 --end 2026-05-07 --format json
tp report v4 --args '{"start_date":"2026-05-01","end_date":"2026-05-07","metrics":"revenue,impression"}' --format json

tp report abtest（MCP: query_v4_abtest_report）

字段	类型	必传	CLI flags	说明
start_date	String	Y	--start	YYYY-MM-DD
end_date	String	Y	--end	YYYY-MM-DD
abtest_id	String	Y	--abtest-id	AB 测试 ID

tp report forecast（MCP: query_v4_app_forecast_report）

字段	类型	必传	CLI flags	说明
app_uuid	String	Y	--app-uuid	应用 UUID

tp report confidence（MCP: query_v4_ab_confidence_report）

字段	类型	必传	CLI flags	说明
abtest_id	String	Y	--abtest-id	AB 测试 ID

tp report active-users（MCP: query_active_user_report）

字段	类型	必传	CLI flags	说明
start_date	String	Y	--start	YYYY-MM-DD
end_date	String	Y	--end	YYYY-MM-DD
app_uuid	String	N	--app-uuid	应用 UUID
metrics	String	N	-	如 dau,deu
group_by	String	N	-	如 date,appId

8.6 字典与调试

tp meta categories（MCP: list_app_categories）

无参数。

tp geo regions（MCP: list_regions）

无参数。

tp geo cities（MCP: list_cities）

字段	类型	必传	CLI flags	说明
region	String	N	--region	国家/地区代码

tp debug invoke <tool> / tp debug tools

用法	说明
tp debug tools	列出全部 MCP 工具名
tp debug invoke list_placements --args '{"currency":"USD"}'	按 MCP 工具名调用；参数规则与上表 MCP 列一致

写类 MCP 工具经 debug invoke 调用时不经过 CLI 的 --yes 确认，生产环境慎用。

8.7 写操作参数

下列子命令无专用 flags，完整请求体通过 --args JSON 传入，并须 --yes：

app create|update|delete、adseat create|update、adscene upsert、placement upsert|toggle、intermediary upsert、group-placement update|toggle、abtest create|modify|start|close、token update、account-template save

各写操作字段定义与校验规则见 ssp_api 对应章节；缺参时先执行不带 --yes 的命令，CLI 会输出与 MCP 相同的参数说明。

tp placement toggle（MCP: toggle_placement）

字段	类型	必传	说明
placement_ids	String	Y	逗号分隔，最多 100
is_on	Int	Y	0=关闭, 1=开启

tp placement toggle --args '{"placement_ids":"123,456","is_on":0}'
tp placement toggle --args '{"placement_ids":"123","is_on":1}' --yes

tp placement upsert（MCP: upsert_placement）

字段	类型	必传	说明
adseat_uuid	String	Y*	创建时必填
name	String	Y*	创建时必填
adsource_id	Int	Y*	广告平台 ID
api_token_id	Int	Y*	授权 ID
placement_config	JSON	Y*	含 placementId、appId 等；AdMob 填写见 ssp_api §7.3.1
auto_app_id	String	N	仅 Meta 自动化创建（is_auto_create=1）时必填；AdMob 勿传，App ID 写在 placement_config.appId
currency	String	Y	USD 或 CNY
placement_id	Int	Y*	更新时必填；创建传 0 或不传
is_auto_create	Int	N	1=自动化创建（海外部分平台）
is_header_bidding	Int	N	0/1
rate / is_auto_price	—	N*	非 HB 时通常必填

# 创建（dry-run 先看参数说明）
tp placement upsert --args '{
  "adseat_uuid":"<adseat_uuid>",
  "name":"AdMob激励01",
  "adsource_id":2,
  "api_token_id":123,
  "placement_config":{"appId":"ca-app-pub-xxx~yyy","placementId":"ca-app-pub-xxx/yyy"},
  "currency":"USD",
  "rate":1.5,
  "is_auto_price":2
}'

# 确认后执行
tp placement upsert --args '{...}' --yes

自动化创建（is_auto_create=1）平台差异较多；缺参时 CLI 会展开 自动化创建广告源 参数表。详见 ssp_api 广告源自动化章节。

tp app create（MCP: create_app）

字段	类型	必传	说明
app_name	String	Y	最长 100 字符
os	Int	Y	1=Android, 2=iOS（创建后不可改）
package_name	String	N*	无 app_url 时必填
category_id	Int	N*	无 app_url 时必填；tp meta categories 查询
app_url	String	N	商店链接；iOS 可自动补全

tp app create --args '{"app_name":"Demo","os":1,"package_name":"com.example.app","category_id":101}' --yes

tp adseat create（MCP: create_adseat）

字段	类型	必传	说明
app_uuid	String	Y	所属应用
seat_name	String	Y	广告位名称
ad_type	Int	Y	1 原生 2 插屏 3 开屏 4 横幅 5 激励
cache_num	Int	Y	并行请求数

开屏/原生开屏另需 skip_time、countdown_time、is_skip 等，见 ssp_api 广告位接口。

tp intermediary upsert（MCP: upsert_intermediary_group）

字段	类型	必传	说明
adseat_uuid	String	Y	广告位 UUID
group_name	String	Y	最长 30 字符
bucket_id	Int	Y	无 AB 时填 0
currency	String	Y	USD 或 CNY
group_id	Int	N	更新时传已有组 ID
country	String	N	ISO 码逗号分隔

8.8 典型工作流（可复制命令）

下列流程展示 从查 ID 到改配置 的完整传参方式（将 <...> 替换为实际值）。

流程 A：查某广告位下全部广告源（含已关闭）

tp adseat list --app-uuid "<app_uuid>" --format table --fields adseat_uuid,seat_name,ad_type
tp placement list --currency USD --adseat-uuid "<adseat_uuid>" --args '{"is_on":-1}' --format json

流程 B：创建 AdMob 瀑布流广告源（手动填写）

须同时提供 AdMob 应用 ID（placement_config.appId）与 广告单元 ID（placement_config.placementId），均从 AdMob 控制台复制；勿传 auto_app_id。Android / iOS 要求相同，见 ssp_api §7.3.1。

tp platform legacy --format table --fields adsource_id,name
tp token list --format json
tp account-template get --adsource-id 2
tp placement upsert --args '{
  "adseat_uuid":"<adseat_uuid>",
  "name":"AdMob Banner",
  "adsource_id":2,
  "api_token_id":<token_id>,
  "placement_config":{"appId":"<admob_app_id>","placementId":"<admob_unit_id>"},
  "currency":"USD",
  "rate":0.5,
  "is_auto_price":2
}' --print-request
# 核对 stderr 后：
tp placement upsert --args '{...}' --yes

流程 B2：AdMob 自动化创建广告源（Header Bidding）

• 勿传 auto_app_id
• placement_config.appId：必填（Android / iOS 相同）
• placement_config.placementId：可传 ""，成功后系统回填
• 另须 is_auto_create=1、is_header_bidding=1，且 api_token_id 已开启自动化
• 完整矩阵见 ssp_api §7.3.1

tp placement upsert --args '{
  "adseat_uuid":"<adseat_uuid>",
  "name":"AdMob Banner Auto",
  "adsource_id":2,
  "api_token_id":<token_id>,
  "is_auto_create":1,
  "is_header_bidding":1,
  "placement_config":{"appId":"<admob_app_id>","placementId":""},
  "currency":"USD"
}' --print-request
# 核对 stderr 后：
tp placement upsert --args '{...}' --yes

流程 C：报表导出 CSV

tp report v4 \
  --start 2026-05-01 --end 2026-05-07 \
  --args '{"app_uuids":"<app_uuid>","metrics":"revenue,impression,click","group_by":"date,adsourceId"}' \
  --format csv --fields date,revenue,impression

流程 D：AI / Agent 按 MCP 工具名调用

tp debug tools --format json
tp debug invoke list_placements --args '{"currency":"USD","adseat_uuids":"<uuid>"}' --format json
tp debug invoke summarize_app_configuration --args '{"app_uuid":"<uuid>","currency":"USD"}' --format json

8.9 常用枚举速查

字段	取值	含义
os	1 / 2	Android / iOS
ad_type	1–5	原生 / 插屏 / 开屏 / 横幅 / 激励
currency	USD / CNY	货币（大写）
is_on	0 / 1 / -1	关闭 / 开启 / 全部（列表过滤）
is_header_bidding	0 / 1	否 / 是
is_auto_price	1 / 2	自动定价开 / 关
status（场景）	1 / 2	启用 / 停用

9. 常见问题

9.1 安装脚本下载失败

请依次检查：

1. 本机网络、VPN、公司代理是否能访问安装服务域名。

2. 安装脚本是否可访问：

   curl -sS -o /dev/null -w "%{http_code}\n" "https://mcp.tradplusad.com/cli/tp/install-tp.sh?version=latest"

   预期返回 200。

3. macOS / Linux 是否有 curl、tar、chmod 等基础命令。

4. Windows 是否允许执行 PowerShell 脚本。

9.2 安装成功但找不到 tp

通常是安装目录不在 PATH 中。可以先直接执行安装目录下的二进制确认：

/path/to/install/dir/tp version

再根据安装脚本提示把安装目录加入 PATH。

9.3 鉴权失败

请检查：

1. bear 和 secret 是否来自同一个账号。
2. TRADPLUS_BASE_URL 或 --base-url 是否指向正确环境。
3. 当前 API Key 是否有目标应用、广告位或报表权限。
4. 本地配置、环境变量、命令行参数是否存在混用；命令行参数优先级最高。

9.4 提示「参数不完整」或缺少 currency

常见原因是使用了 tp xxx list currency USD 这类 positional 写法。请改为 --currency USD 或 --args '{"currency":"USD"}'。详见 §5.1 参数传递规范 与 §8.3 placement list。

9.5 安全注意事项

• 不要把 bear、secret 写入工单、聊天记录、截图或公开仓库。
• 不要提交包含密钥的 .env、config.yaml 或脚本文件。
• 生产环境写操作必须先 dry-run，再确认后加 --yes。
• 不同环境的 base_url 必须明确区分，避免把测试凭证或测试参数用于生产环境。

10. 获取帮助

查看全局帮助：

tp --help

查看某个子命令帮助：

tp app list --help
tp placement upsert --help
tp report v4 --help