@bluevs/ttcli 0.0.5 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluevs/ttcli",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "TikTok CLI - designed for AI Agent and developers",
   "bin": {
     "ttcli": "scripts/run.js"
@@ -9,12 +9,12 @@
     "postinstall": "node -e \"console.log('\\n📦 ttcli installed. To install the openclaw skill, run:\\n  bash $(npm root -g)/@bluevs/ttcli/skills/ttcli/scripts/install-skill.sh\\n')\""
   },
   "optionalDependencies": {
-    "@bluevs/ttcli-darwin-arm64": "0.0.5",
-    "@bluevs/ttcli-darwin-x64": "0.0.5",
-    "@bluevs/ttcli-linux-arm64": "0.0.5",
-    "@bluevs/ttcli-linux-x64": "0.0.5",
-    "@bluevs/ttcli-win32-arm64": "0.0.5",
-    "@bluevs/ttcli-win32-x64": "0.0.5"
+    "@bluevs/ttcli-darwin-arm64": "0.0.6",
+    "@bluevs/ttcli-darwin-x64": "0.0.6",
+    "@bluevs/ttcli-linux-arm64": "0.0.6",
+    "@bluevs/ttcli-linux-x64": "0.0.6",
+    "@bluevs/ttcli-win32-arm64": "0.0.6",
+    "@bluevs/ttcli-win32-x64": "0.0.6"
   },
   "engines": {
     "node": ">=16"

package/skills/ttcli/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: ttcli
-version: 0.0.5
+version: 0.0.6
 description: 直接调用 TikTok Marketing API（access token 鉴权，不经 VH 平台/项目层）。当用户提供原生 TikTok access_token + advertiser_id、要直连 TikTok 创建或查询 Smart+ campaign/adgroup/ad、或查 identity/app/region 等元数据时使用。注意：用户走 VH 项目流程（po_xxxx + account_id）的 TikTok 创编应改走 vhcli tiktok。
 ---
 
 # TikTok CLI (`ttcli`)
 
-> **Skill version**: `0.0.5`
+> **Skill version**: `0.0.6`
 >
 > 当用户问"ttcli skill 版本是多少 / skill 装好了吗 / 升级生效了没" 时，**直接念出上面的版本号**。
 > 用户期望更高版本但没看到 → 让他们：(1) 重跑 `npm install -g @bluevs/ttcli && bash $(npm root -g)/@bluevs/ttcli/skills/ttcli/scripts/install-skill.sh` (2) 然后**新开一个会话**（skill 在会话启动时加载，老会话不刷新）。
@@ -15,6 +15,24 @@ description: 直接调用 TikTok Marketing API（access token 鉴权，不经 VH
 
 This skill is intentionally short. Always treat `ttcli -h` and `ttcli <subcommand> -h` as the primary reference for flags.
 
+## 🚨 硬性约定：所有 TikTok 操作必须经 ttcli，不允许直接调 TikTok 接口
+
+**严禁**绕过 ttcli 直接 `curl` / `wget` / `python requests` / 任何 HTTP 客户端调用 `business-api.tiktok.com` 的任何端点。**严禁**自己手搓接口、伪造 header、临时验证 token，或在 ttcli 没包某个端点时"先用 curl 临时跑一下"。
+
+**理由**（每条都是真实踩过的坑）：
+- ttcli 已沉淀的字段名/枚举值校验（如 MINI_GAME 的 7 个隐性约束、`app_promotion_type` vs `promotion_type` 双层关系、`output_format` 决定 download 走 CSV 还是 JSON 等）一旦绕过就全丢
+- 写操作的 `--dry-run` 安全网、`operation_status=DISABLE` 兜底、`request_id` 自动幂等都失效，容易真创出花钱的实体
+- TikTok 的错误码不会自动经过 SKILL.md 的"错误信息要翻译"对照表，会原样甩到用户
+- 日志/排查链路断掉，request_id 拿不到，工单提不了
+
+**正确做法**：
+- 想要的接口 ttcli 没包 → 告诉用户「这个接口 ttcli 还没封装，要我加吗？需要把官方文档贴给我」**而不是**自己 curl 临时跑
+- 调试某个字段行为 → 用 `ttcli <cmd> --dry-run` 看 ttcli 会发什么 body，再用 `--human` 看响应；不要绕开
+- 单纯查 ttcli 命令树 → `ttcli -h` / `ttcli <ns> -h` / `ttcli <ns> <cmd> -h`
+- 只有当用户**明确说**"绕过 ttcli 直接 curl 这一次"时才允许直连——否则一律走 ttcli
+
+如果用户问「能不能直接调 X 接口」，先回「我们走 ttcli，让我看看包了没；没包的话我把这个接口加到 ttcli 里再用，会更稳」。
+
 ## 🚨 与用户对话的硬性约定：错误信息要翻译
 
 ttcli 和 TikTok 返回的报错都是技术语言（`missing required fields: [adgroup_id]`、`Invalid optimization goal`、`code=40002 ...`）。**严禁原样把这些贴给用户**——非技术用户看到字段名、code 数字会懵。
@@ -117,6 +135,10 @@ ttcli tool targeting search \
   --objective-type=APP_PROMOTION --promotion-type=APP_ANDROID \
   --placements=PLACEMENT_TIKTOK --search-type=FUZZY_SEARCH \
   --keywords=Kentucky                  # → geo_id by name (location_ids OR zipcode_ids)
+ttcli tool targeting info \
+  --objective-type=APP_PROMOTION --promotion-type=APP_ANDROID \
+  --placements=PLACEMENT_TIKTOK \
+  --targeting-ids=6254925,6254928      # ← reverse: name + parent hierarchy from IDs (use --scene=ISP for isp_id lookup)
 ```
 
 `tool region` accepts `--language=zh-CN` (or any of 78 supported codes) for localized region names — useful when surfacing options to the user.
@@ -200,6 +222,15 @@ Minimal Android APP_INSTALL adgroup body (use as a template):
 
 Creating MINI_GAME adgroups has many undocumented or scattered constraints. The combination below was end-to-end verified. Use as the starting template; do not relax fields without a specific reason.
 
+**🚨 Two-level terminology — don't conflate:**
+
+| Field | Level | Valid values |
+|---|---|---|
+| `app_promotion_type` | **campaign** | `APP_INSTALL` / `APP_RETARGETING` / `MINIS` (only these 3) |
+| `promotion_type` | **adgroup** (optimization placement) | `APP_ANDROID` / `APP_IOS` / `WEBSITE` / `MINI_APP` / `MINI_GAME` / `NATIVE_SERIES` / `LEAD_GENERATION` |
+
+For TikTok Minis: **campaign** uses `app_promotion_type=MINIS`, then **adgroup** uses `promotion_type=MINI_GAME` (game) or `MINI_APP` (legacy minis) or `NATIVE_SERIES` (short drama). Sending `--app-promotion-type=MINI_GAME` will fail with `Invalid app_promotion_type` — that value lives one level down.
+
 **Campaign must be CBO=off + INFINITE**:
 
 ```