tencentads-cli

通用腾讯广告 API CLI 工具 — 封装鉴权与 API 调用。

零运行时依赖，同时提供 CLI 命令行 和 Node.js SDK 两种使用方式。

安装

# 全局安装（CLI 工具）
npm install -g [email protected]

# 项目依赖（SDK）
npm install [email protected]

配置鉴权

在使用之前，需要保存 API Key 到本地凭证文件 ~/.tencent-ads/credentials.json：

# 方式一：手动创建
mkdir -p ~/.tencent-ads
echo '{"apiKey":"YOUR_API_KEY"}' > ~/.tencent-ads/credentials.json

# 方式二：通过环境变量自定义存储路径
export TENCENT_ADS_CONFIG_DIR=/your/custom/path

查看当前鉴权状态：

tencentads-cli auth status

CLI 使用

全局安装后可用的命令为 tencentads-cli（对应 package.json 的 bin 字段）。

JSON 模式

# GET 请求
tencentads-cli api '{"method":"GET","path":"/api/v3.0/adgroups/get","account_id":"123456"}'

# POST 请求
tencentads-cli api '{"method":"POST","path":"/api/v3.0/adgroups/add","account_id":"123456","body":{"campaign_id":100}}'

# 带查询参数
tencentads-cli api '{"method":"GET","path":"/api/v3.0/campaigns/get","account_id":"123456","params":{"page":1,"page_size":10}}'

Flag 模式

# GET 请求
tencentads-cli api --method GET --path /api/v3.0/adgroups/get --account-id 123456

# POST 请求
tencentads-cli api --method POST --path /api/v3.0/adgroups/add --account-id 123456 --body '{"campaign_id":100}'

# 带查询参数
tencentads-cli api --method GET --path /api/v3.0/campaigns/get --account-id 123456 --params '{"page":1,"page_size":10}'

查看帮助

tencentads-cli help

SDK 使用

callApi — 高级调用函数

自动加载本地凭证，返回结构化结果：

import { callApi } from 'tencentads-cli';

const result = await callApi({
  method: 'GET',
  path: '/api/v3.0/adgroups/get',
  accountId: '123456',
  params: { page: 1, page_size: 10 },
});

if (result.success) {
  console.log(result.data);
} else {
  console.error(result.error.message);
}

TencentAdsClient — HTTP 客户端

支持自定义鉴权、超时和重试策略：

import { TencentAdsClient, ENDPOINTS } from 'tencentads-cli';

const client = new TencentAdsClient({
  auth: {
    applyAuth(headers) {
      headers.set('X-MKT-API-Key', 'YOUR_API_KEY');
      headers.set('Host', 'api.e.qq.com');
    },
  },
  baseUrl: ENDPOINTS.MARKETING_API,
  timeout: 30000,
  retry: { maxRetries: 3, baseDelay: 1000 },
});

// GET
const data = await client.get('/api/v3.0/campaigns/get', { account_id: '123456' });

// POST
const resp = await client.post('/api/v3.0/adgroups/add', { campaign_id: 100 });

TencentAdsAuth — 凭证管理

import { TencentAdsAuth } from 'tencentads-cli';

const auth = new TencentAdsAuth();

// 保存 API Key
auth.saveApiKey('your-api-key');

// 读取凭证
const cred = auth.read();
// => { apiKey: 'your-api-key', updatedAt: '2025-01-01T00:00:00.000Z' }

// 查看鉴权状态
const status = auth.getStatus(); // 'active' | 'not_configured'
const info = auth.getInfo();

枚举工具

内置腾讯广告 API 常用枚举及转换工具：

import {
  resolveEnum,
  resolveEnumKey,
  deriveProductType,
  resolveTargetingFields,
  MARKETING_GOAL,
  MARKETING_CARRIER_TYPE,
} from 'tencentads-cli';

// 枚举名 → 数值
resolveEnum('MARKETING_GOAL', 'MARKETING_GOAL_PRODUCT_SALES'); // => 2

// 数值 → 枚举名
resolveEnumKey('MARKETING_GOAL', 2); // => 'MARKETING_GOAL_PRODUCT_SALES'

// 自动推导 product_type
deriveProductType('MARKETING_CARRIER_TYPE_WECHAT_OFFICIAL_ACCOUNT');

// 智能展开定向字段（支持中文简写）
resolveTargetingFields({
  os: 'ANDROID_10+',
  device_price: '2500以上',
  education: '本科',
});

可用枚举：

| 枚举 | 说明 | |------|------| | MARKETING_GOAL | 营销目标（拉新、促销、品牌等） | | MARKETING_SUB_GOAL | 营销子目标 | | MARKETING_CARRIER_TYPE | 推广载体类型（Android/iOS/微信等） | | MARKETING_TARGET_TYPE | 推广业务类型 | | SITE_SET | 广告投放版位 | | SMART_DELIVERY_PLATFORM | 智能投放平台 | | EXPLORATION_STRATEGY | 探索策略 | | CONFIGURED_STATUS | 配置状态 |

特性

• 零运行时依赖 — 仅使用 Node.js 内置模块
• TypeScript — 完整类型定义，开箱即用
• 自动重试 — 指数退避策略，默认重试 3 次
• 鉴权管理 — API Key 凭证自动加载
• 枚举映射 — 双向转换 + 中文定向字段智能展开
• ESM 模块 — 原生 ES Module 支持

构建

cd tools/tencent-ads-cli
npm install
npm run build        # tsc 编译 → dist/

构建产物在 dist/ 目录，包含 .js 和 .d.ts 文件。

发布到 npm

1. 登录 npm

   npm login

2. 确认当前已发布版本

   npm info tencentads-cli

3. 更新版本号

   npm version patch   # 修复：0.1.0 → 0.1.1
   npm version minor   # 新功能：0.1.0 → 0.2.0
   npm version major   # 破坏性变更：0.1.0 → 1.0.0

4. 构建并发布

   npm run build
   npm publish

5. 验证发布结果

   npm info tencentads-cli version

注意：发布后，使用 release-skills.sh --cli-version <新版本> 可以将 skills 仓库中的 tencentads-cli 依赖版本锁定到最新发布的版本。

环境要求

• Node.js >= 20.0.0

License

MIT