@bluevs/ttcli 0.0.3 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluevs/ttcli",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "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.3",
-    "@bluevs/ttcli-darwin-x64": "0.0.3",
-    "@bluevs/ttcli-linux-arm64": "0.0.3",
-    "@bluevs/ttcli-linux-x64": "0.0.3",
-    "@bluevs/ttcli-win32-arm64": "0.0.3",
-    "@bluevs/ttcli-win32-x64": "0.0.3"
+    "@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"
   },
   "engines": {
     "node": ">=16"

package/skills/ttcli/SKILL.md

@@ -1,14 +1,48 @@
 ---
 name: ttcli
+version: 0.0.5
 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`
+>
+> 当用户问"ttcli skill 版本是多少 / skill 装好了吗 / 升级生效了没" 时，**直接念出上面的版本号**。
+> 用户期望更高版本但没看到 → 让他们：(1) 重跑 `npm install -g @bluevs/ttcli && bash $(npm root -g)/@bluevs/ttcli/skills/ttcli/scripts/install-skill.sh` (2) 然后**新开一个会话**（skill 在会话启动时加载，老会话不刷新）。
+
 `ttcli` wraps TikTok Marketing API (`business-api.tiktok.com`) as a CLI optimized for AI agents. JSON output by default; the `--human` flag exists for project-owner debugging only — agents should never pass it.
 
 This skill is intentionally short. Always treat `ttcli -h` and `ttcli <subcommand> -h` as the primary reference for flags.
 
+## 🚨 与用户对话的硬性约定：错误信息要翻译
+
+ttcli 和 TikTok 返回的报错都是技术语言（`missing required fields: [adgroup_id]`、`Invalid optimization goal`、`code=40002 ...`）。**严禁原样把这些贴给用户**——非技术用户看到字段名、code 数字会懵。
+
+**做法**：把每个技术错误翻译成业务语言后回给用户，**保留 request_id 仅供你自己排查**。
+
+参考翻译表（不全，按这个方式扩展）：
+
+| 技术错误（你看到的） | 翻给用户（你要说的） |
+|---|---|
+| `missing required fields: [adgroup_id]` | "我还需要知道把广告挂在哪个广告组下，能告诉我广告组 ID 或名字吗？" |
+| `missing required fields: [campaign_name]` | "你这条 campaign 想叫什么名字？" |
+| `code=40105 Access token is incorrect or has been revoked` | "你的授权过期或被撤销了，请去 TikTok Marketing 后台重新生成 access token 给我" |
+| `code=40001 No permission to operate advertiser` | "当前 token 没权限管这个广告主，你的 token 对应的广告主 ID 可能不一样" |
+| `code=40002 placement_type only supports PLACEMENT_TYPE_NORMAL` | "小游戏只能选'手动版位'，我帮你设好" |
+| `code=40002 Invalid optimization goal. Please change your goal or promotion type` | "这个推广类型不支持你说的优化目标，小游戏一般用 ROAS（投产比）优化，要换吗？" |
+| `code=40002 This ad does not support infinite budget mode` | "这种广告必须有日预算，不能无限。我帮你设个最低日预算" |
+| `code=40002 Allowlist not enabled` | "这个高级功能你账户没开通白名单，要联系 TikTok 客户经理开通；我们换一种简单方案吧" |
+| `code=40002 Something went wrong. Contact support` | "TikTok 后台报了个不明错误。我先把请求 ID 记下来：`<request_id>`，必要时你拿这个找 TikTok 技术支持。我们试另一种配置看能不能绕过" |
+| `body is not a JSON object` / 客户端 validation | 不要暴露 JSON / body 概念。直接说"我组装的请求格式有问题，让我重做"——然后自己重组 |
+| 网络层错误（EOF、context deadline）| "网络抖了一下，我重试一次" |
+
+**原则**：
+- 用户看到的应该是"接下来你/我做什么"，不是"什么字段错了"
+- 翻译要保留**关键判断点**（让用户能给出对的输入），不能含糊到"出错了"
+- 多个字段同时缺 → 合并成一个自然问句，不要逐个列字段名
+- request_id 留你脑子里 / 日志里，**不主动甩给用户**，除非用户明确要"找 TikTok 提工单"
+
 ## ttcli vs vhcli tiktok — 选哪一个
 
 openclaw 同时装了两个 TikTok 广告工具，触发条件不同：
@@ -68,14 +102,21 @@ Before creating a campaign or adgroup, gather the IDs you'll reference:
 
 ```
 ttcli auth show                       # confirm credentials loaded + their source
+ttcli bc list                         # → bc_id (Business Centers; needed for BC_AUTH_TT identities)
 ttcli app list                        # → app_id (Android/iOS apps)
 ttcli minis list                      # → minis_id (TikTok Minis: MINI_GAME / MINI_SERIES)
 ttcli identity list                   # → identity_id (Spark Ads publishing identity)
 ttcli smart-plus campaign list        # → existing campaign_id (or you'll create one)
+ttcli smart-plus adgroup list         # → existing adgroup_id (filter by --campaign-ids / --promotion-type)
+ttcli smart-plus ad list              # → existing smart_plus_ad_id + creative_list (only explicitly-selected creatives)
 ttcli tool region \
   --placements=PLACEMENT_TIKTOK \
   --objective-type=APP_PROMOTION \
   --level-range=TO_COUNTRY            # → location_id for targeting_spec.location_ids
+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)
 ```
 
 `tool region` accepts `--language=zh-CN` (or any of 78 supported codes) for localized region names — useful when surfacing options to the user.
@@ -272,7 +313,9 @@ Per the doc: "对于现有广告账号，当广告组的投放广告位为自动
 | `tiktok_item_id` (Spark Ads) | `/tt_video/info/` | `ttcli tt-video info --auth-code=...` |
 | List posts under an identity | `/identity/video/get/` | `ttcli identity video list --identity-id=... --identity-type=...` |
 | Verify `identity_id` | `/identity/info/` | `ttcli identity info --identity-id=... --identity-type=...` |
-| Upload video → `video_id` | `/file/video/ad/upload/` | ⏳ not yet wrapped (rare; non-Spark only) |
+| Search ad-library videos (`video_id`) | `/file/video/ad/search/` | `ttcli file video search` |
+| Search ad-library images (`image_id`) | `/file/image/ad/search/` | `ttcli file image search` |
+| Upload video → `video_id` | `/file/video/ad/upload/` | ⏳ not yet wrapped |
 | Upload image → `web_uri` | `/file/image/ad/upload/` | ⏳ not yet wrapped |
 | Music → `music_id` | (separate music API) | ⏳ not yet wrapped |
 
@@ -330,6 +373,65 @@ Common codes:
 
 The CLI does NOT validate enum values, type correctness, or conditional-required fields. It only checks that unconditionally required fields are present. TikTok is the source of truth for everything else — surface its error messages directly.
 
+## TikTok user OAuth (Login Kit / Content Posting API) — separate token type
+
+ttcli's main job is Marketing API. But it also wraps OAuth-side endpoints under `tt-user` and `business`:
+
+```
+ttcli tt-user token-info \                           # inspect a user OAuth token
+  --app-id=aw1234abcd5678 \
+  --tt-access-token=act.xxxxx
+
+ttcli business get \                                 # account profile + insights
+  --business-id=open_id_xxx \                        #   (= creator_id from tt-user token-info)
+  --tt-access-token=act.xxxxx \
+  --fields=username,display_name,followers_count,video_views,audience_countries
+```
+
+**These are different token types** from the rest of ttcli. The Marketing API token in `auth show` is for ad management (`/smart_plus/...`, `/report/...`). The token here is a **TikTok user OAuth token** from Login Kit / Content Posting API consumer flow — used for posting videos, reading user profile, etc. They are not interchangeable.
+
+| Endpoint | Auth model | Required scopes (some) |
+|---|---|---|
+| `/tt_user/token_info/get/` | access_token in JSON body, no header | n/a (introspection) |
+| `/business/get/` | Access-Token header (with user OAuth token) | `user.info.basic`, `user.info.username`, `user.info.profile`, `user.info.stats`, `user.account.type`, `user.insights` |
+
+If the user only has a Marketing API token, both will return `code=40105 access_token invalid` — that's the signal to ask for a Login-Kit-flow token instead.
+
+**`business get` defaults**: TikTok defaults `fields=["display_name","profile_image"]` — pass `--fields=...` to get more. Daily metrics have **24-48h delay**; same-day data is unavailable. Audience demographic fields require **≥100 followers**.
+
+## Reporting (async)
+
+`ttcli report task create` posts to `/report/task/create/` and returns a `task_id`. The actual report data is NOT in the response — async reports are three steps:
+
+1. **Create task** — `ttcli report task create ...` → `task_id`
+2. **Poll status** — `ttcli report task check --task-id=...` → `status` (QUEUING / PROCESSING / SUCCESS / FAILED / CANCELED). Poll every ~30s; tasks typically take 30s–a few minutes.
+3. **Download** — `ttcli report task download --task-id=...`. Behavior depends on what `--output-format` you used at create:
+   - **CSV_STRING** (default at create) → returns raw CSV bytes directly to stdout. AI agents: parse CSV from stdout.
+   - **CSV_DOWNLOAD / XLSX_DOWNLOAD** → returns JSON with a 1-hour signed `download_url`. Pass `--out=FILE --fetch` to follow the URL and write the file in one shot.
+
+**Bad task_id gotcha**: TikTok returns `code=51010 internal system error` for unknown task_ids on `task check` (not a clean 4xx). Treat 51010 as "task not found / not yours" when polling.
+
+**Stdout vs JSON**: `task download` is the one ttcli command where `--human`/JSON modes are ignored on the CSV_STRING branch — the body IS the data, so it's written verbatim to stdout. Other commands honor JSON-by-default.
+
+**Async filtering is restricted**: only `campaign_ids` / `adgroup_ids` / `ad_ids` / `country_code` (max 20000 IDs total). For other filters, use sync `/report/integrated/get/` (also not yet wrapped).
+
+**Lifetime metrics**: pass `--query-lifetime` to get all-time metrics; ignores `--start-date`/`--end-date`. No time/audience/country breakdowns allowed in lifetime mode.
+
+**Recommended**: pass `--enable-title-translation=false` for stable header rows (TikTok periodically updates translated headers — raw field names don't change).
+
+```
+ttcli report task create \
+  --report-type=BASIC --data-level=AUCTION_AD \
+  --dimensions=ad_id,stat_time_day \
+  --metrics=spend,impressions,clicks,cpc,ctr \
+  --start-date=2026-05-01 --end-date=2026-06-01 \
+  --filter-ad-ids=1866239337888050,1866239351340034 \
+  --output-format=CSV_DOWNLOAD \
+  --enable-title-translation=false
+```
+
+Limits: 1 QPS per app; 500 async tasks/hour per advertiser; 30-day task validity.
+
 ## Credentials
 
 Priority: `--flag` > env var > config file (`~/.config/ttcli/credentials.json`, mode 0600).

package/skills/ttcli/scripts/install-skill.sh

@@ -33,14 +33,32 @@ WORKSPACE_SKILL_DIR="$WORKSPACE/skills/ttcli"
 NPM_ROOT="$(npm root -g 2>/dev/null || echo '')"
 PKG_DIR="${NPM_ROOT:+$NPM_ROOT/@bluevs/ttcli}"
 
-# 版本来源：当 SOURCE_DIR 在 npm 包目录内（post-install 场景）→ 用 npm 包版本号
-# 否则（开发期从仓库跑）→ 用 SKILL.md 的 mtime，确保每次改动都触发同步
+# 版本来源（按优先级）：
+#   1. SKILL.md frontmatter 的 version: 字段 —— 单一权威源
+#   2. SKILL.md mtime fallback —— frontmatter 缺 version: 字段时兜底
+#
+# 开发期（SOURCE_DIR 不在 npm 包目录内）会在 frontmatter 版本号后加 -dev-{mtime}
+# 后缀，确保改 SKILL.md 不动 frontmatter 时也能触发同步。
+# 生产期（SOURCE_DIR 在 npm 包目录内，post-install 场景）直接用 frontmatter
+# 版本号，跟 npm package.json 对齐，便于用户报"我装的是哪个版本"。
 get_version() {
-  if [ -n "$PKG_DIR" ] && [ -f "$PKG_DIR/package.json" ] && [[ "$SOURCE_DIR" == "$PKG_DIR"* ]]; then
-    node -p "require('$PKG_DIR/package.json').version" 2>/dev/null && return
+  local v
+  v=$(awk -F': *' '/^version: *[^ ]/ { print $2; exit }' "$SKILL_FILE" | tr -d '\r ')
+  if [ -z "$v" ]; then
+    date -r "$SKILL_FILE" "+local-%Y%m%d-%H%M%S" 2>/dev/null || echo "local-unknown"
+    return
+  fi
+
+  # 生产模式：SOURCE_DIR 在 npm 包内 → 直接用 frontmatter 版本
+  if [ -n "$PKG_DIR" ] && [ -d "$PKG_DIR" ] && [[ "$SOURCE_DIR" == "$PKG_DIR"* ]]; then
+    echo "$v"
+    return
   fi
-  # 开发期 / 仓库源：用 SKILL.md mtime
-  date -r "$SKILL_FILE" "+local-%Y%m%d-%H%M%S" 2>/dev/null || echo "local-unknown"
+
+  # 开发模式：加 -dev-{mtime} 后缀
+  local mtime
+  mtime=$(date -r "$SKILL_FILE" "+%Y%m%d-%H%M%S" 2>/dev/null || echo "unknown")
+  echo "${v}-dev-${mtime}"
 }
 
 # ============================================================