@bluevs/ttcli 0.0.9 → 0.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluevs/ttcli",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "TikTok CLI - designed for AI Agent and developers",
   "bin": {
     "ttcli": "scripts/run.js"
@@ -9,12 +9,12 @@
     "postinstall": "bash $(npm root -g)/@bluevs/ttcli/skills/ttcli/scripts/install-skill.sh 2>&1 || echo '⚠️  skill auto-sync skipped (likely permission/container env). Run manually: bash $(npm root -g)/@bluevs/ttcli/skills/ttcli/scripts/install-skill.sh'"
   },
   "optionalDependencies": {
-    "@bluevs/ttcli-darwin-arm64": "0.0.9",
-    "@bluevs/ttcli-darwin-x64": "0.0.9",
-    "@bluevs/ttcli-linux-arm64": "0.0.9",
-    "@bluevs/ttcli-linux-x64": "0.0.9",
-    "@bluevs/ttcli-win32-arm64": "0.0.9",
-    "@bluevs/ttcli-win32-x64": "0.0.9"
+    "@bluevs/ttcli-darwin-arm64": "0.0.11",
+    "@bluevs/ttcli-darwin-x64": "0.0.11",
+    "@bluevs/ttcli-linux-arm64": "0.0.11",
+    "@bluevs/ttcli-linux-x64": "0.0.11",
+    "@bluevs/ttcli-win32-arm64": "0.0.11",
+    "@bluevs/ttcli-win32-x64": "0.0.11"
   },
   "engines": {
     "node": ">=16"

package/skills/ttcli/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: ttcli
-version: 0.0.9
-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。
+version: 0.0.11
+description: TikTok Marketing API 的 CLI 客户端（700+ endpoint 覆盖）。token 由 vhcli 发证（vhcli project account-token），ttcli 自己不持有 token、也禁止找用户手填——看到 ttcli 报 TTCLI_TOKEN_MISSING 就走 vhcli bridge。当用户要做任何 TikTok 业务操作（创/查广告系列、广告组、广告，查余额/花费/流水，管商品目录/受众/像素/转化等）都用这个 skill。
 ---
 
 # TikTok CLI (`ttcli`)
 
-> **Skill version**: `0.0.9`
+> **Skill version**: `0.0.11`
 >
 > 当用户问"ttcli skill 版本是多少 / skill 装好了吗 / 升级生效了没" 时，**直接念出上面的版本号**。
 > 用户期望更高版本但没看到 → 让他们：(1) 重跑 `npm install -g @bluevs/ttcli && bash $(npm root -g)/@bluevs/ttcli/skills/ttcli/scripts/install-skill.sh` (2) 然后**新开一个会话**（skill 在会话启动时加载，老会话不刷新）。
@@ -97,7 +97,104 @@ token 拿到之后也不要回报"我已经从 vhcli 取了 token"——直接
 - vhcli 找不到（没装 / PATH 没配）→ 这是部署问题，跟用户说「我这边 vhcli 跑不起来，请联系部署的同事看看」
 - vhcli 拿到的 token ttcli 一调就 `code=40105 token expired/revoked` → 重跑 vhcli 那一步，token 可能 vhcli 本地缓存过期
 
-## 🔍 如何发现 ttcli 能力（不要靠记忆）
+## 🚨 硬性约定：用户问"能干啥"时禁止开发术语，但表格/分组没问题
+
+**这条规则被反复违反——所以放到很前面，并且给死模板。**
+
+### 默认动作：**直接照抄下面这个模板**，只能改"反问"那行
+
+用户问任何形式的"ttcli 能干啥 / 你能干嘛 / 你支持哪些操作 / 都有什么能力" → 你的回答**就是**这个表，一字不差地用，**不要自由发挥**：
+
+> 可以帮你做这些（按场景分）：
+>
+> | 场景 | 能干啥 |
+> |---|---|
+> | **广告创编** | 建/调/查广告系列、广告组、广告；Smart+ 智能投放全流程、搜索广告、A/B 测试、商品销量最大化广告 |
+> | **素材与创意** | 上传管理视频图片音乐、智能工具优化创意（自动剪辑、智能文案、试玩广告、Spark 授权视频） |
+> | **账户与财务** | 查余额和实际花费、看流水、商务中心和广告账户之间调钱、管发票、账单分组 |
+> | **受众与定向** | 管人群包、配兴趣/行为/话题/地域定向、查地区语言设备等基础数据 |
+> | **数据与报表** | 拉异步报表、看创意疲劳度、做投放诊断 |
+> | **应用与电商** | 管 App 推广、Minis 小程序、商品目录、店铺、Pangle 流量定向 |
+> | **TikTok 账号运营** | 管账号 profile、评论、私信、品牌提及、话题，授权视频做广告 |
+> | **追踪与转化** | 配像素/事件/自定义转化、订阅事件回调 |
+> | **其他** | 屏蔽词、自动化规则、营销组合归因 |
+>
+> **<反问句>** ← 这里换成贴合上下文的反问，例如："你想从哪开始？" / "你具体想看哪类？" / "你最近的目标是什么？"
+
+如果用户问的是某一**子领域**（"你的财务能力" / "素材这块" / "广告创编"），只用上面表的对应那一行 + 反问。**不要**重新生成、不要扩展、不要"补充更多细节"——那一行已经够。
+
+### ❌ 反面教材（**就是这个失败模式反复在犯**）
+
+> "ttcli v0.0.10，714 个命令节点，62 个顶层模块：
+>
+> | # | 命令 | 说明 |
+> |---|---|---|
+> | 1 | ad | 广告（查询/审核/ACO智能创意 create/get/update） |
+> | 2 | adgroup | 广告组（查询/申诉/配额/审核/R&F） |
+> | 3 | advertiser | 广告主（余额/交易流水/预算变更/详情/更新） |
+> | ... |"
+
+错的点（每一个都是死规则）：
+
+1. **"ttcli v0.0.10"、"714 个命令节点"、"62 个顶层模块"** ← 内部实现规模，禁止提
+2. **"# / 命令 / 说明"列结构** ← 这是 CLI 命令字典的形态，禁止用
+3. **"ad / adgroup / advertiser / app ..."当列值** ← CLI 字面量直接当 key 摆出来
+4. **"ACO智能创意"、"R&F"** ← 中英混搭，等于变相暴露 jargon
+5. **逐个模块罗列** ← 不是按用户场景组织，是按内部命令树组织
+
+### 自检步骤（生成回答之后，发出之前必须过一遍）
+
+1. 我有没有提"ttcli vX.Y.Z" / "X 个命令" / "X 个模块" / "X 个节点"？→ 有就删
+2. 我的表格里有没有任何形如 `ad` / `bc` / `dmp` / `pixel` / `webhook` / `ACO` / `R&F` / `GMV Max` / `Spark Ads` 的英文 token？→ 有就用上面的"翻译参考"换成中文
+3. 我的列名是不是"# / 命令 / 模块 / 子命令 / Module"这种内部分类词？→ 是就改成"场景 / 能干啥 / 你想做什么"
+4. 结尾有没有问号反问？→ 没有就加
+
+任何一条 fail，整段重写——**不要**贴出去。
+
+### 翻译参考（CLI 字面量 → 中文）
+
+不在表里的 namespace 用"白话动词 + 名词"翻译，**不要原样吐英文**。
+
+| ❌ CLI 字面量 | ✅ 中文 |
+|---|---|
+| `ad` / `adgroup` / `campaign` | 广告 / 广告组 / 广告系列 |
+| `smart-plus` | Smart+ 智能投放 |
+| `bc` / `BC` / `Business Center` | 商务中心 |
+| `advertiser` | 广告主账户 |
+| `identity` | 投放身份 |
+| `creative` / `creative-fatigue` | 创意素材 / 创意疲劳度 |
+| `dmp` / `DMP` / `segment` / `audience` | 人群包 / 受众洞察 |
+| `pixel` / `event` / `custom-conversion` / `offline` | 像素 / 事件 / 自定义转化 / 离线转化 |
+| `webhook` / `subscription` | 事件订阅 |
+| `tt-video` / `tt-user` / `Spark Ads` | TikTok 视频 / TikTok 用户 / 授权视频 |
+| `gmv-max` / `GMV Max` | 商品销量最大化广告 |
+| `R&F` / `Reach & Frequency` | 预订式触达广告 |
+| `ACO` / `Smart Creative` | 智能创意 |
+| `catalog` / `store` | 商品目录 / 店铺 |
+| `mmm` / `MMM` | 营销组合归因 |
+| `app` / `minis` | App 推广 / Minis 小程序 |
+| `optimizer` | 自动化规则 |
+| `comment` / `lead` / `page` / `business` | 评论 / 线索 / 落地页 / 账号运营 |
+| `report` / `diagnostic` / `delivery` | 报表 / 诊断 / 投放数据 |
+| `playable` | 试玩广告 |
+| `split-test` | A/B 测试 |
+| `blockedword` / `term` | 屏蔽词 / 协议术语 |
+| `pangle-audience-package` / `pangle-block-list` | Pangle 受众包 / Pangle 屏蔽列表 |
+| `tiktok-inventory-filters` | 库存过滤 |
+| `auth` | （凭证管理——这是内部细节，**对用户对话不提**） |
+| `schema` | （命令树自省——内部用，**对用户对话不提**） |
+
+### 唯一例外
+
+用户**明确**说"我是开发者，给我列出所有 CLI 命令" / "把命令树给我" / "我要看 schema"——这时才允许列 `ttcli` 字面量。先回一句"以下是开发者视角"再列。
+
+### 小总结
+
+普通对话里关于"能干啥"的问题 = **抄默认模板那个表 + 改反问**。任何"我自己组织一份"的冲动都是失败的开端，每次都会滑回列模块。
+
+## 🔍 如何发现 ttcli 能力（给你 AI Agent，不是给用户）
+
+> ⚠️ 区分两件事：(1) **schema 原始输出**（JSON / dev 术语 / `path: ttcli campaign get` / `flags: [--token]` 这些字面量）= 内部决策用，**不直接贴给用户**。(2) **你从 schema 提炼后的能力概念**（中文化、按用户场景重组）= 给用户当然可以，按上一节"形式 OK 词要翻"的规则操作。**别把(1)的字节直接念给用户**就行——这跟上一节允许给用户列能力清单不冲突。
 
 SKILL.md **不**枚举所有 ttcli 子命令；项目还在长。新会话或不确定 ttcli 是否已支持某能力时，走两步发现：
 
@@ -144,7 +241,7 @@ ttcli 和 TikTok 返回的报错都是技术语言（`missing required fields: [
 |---|---|
 | `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=40105 Access token is incorrect or has been revoked` | "我这边的授权过期了，让我重新拿一下"——然后 agent 自动重跑 vhcli bridge（**不要让用户去 TikTok 后台找 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（投产比）优化，要换吗？" |
@@ -160,37 +257,6 @@ ttcli 和 TikTok 返回的报错都是技术语言（`missing required fields: [
 - 多个字段同时缺 → 合并成一个自然问句，不要逐个列字段名
 - request_id 留你脑子里 / 日志里，**不主动甩给用户**，除非用户明确要"找 TikTok 提工单"
 
-## 🚨 与用户对话的硬性约定：能力清单也要翻译
-
-跟用户聊"你能做什么"的时候，**严禁直接吐 CLI 命令名 / namespace / 技术术语**。用户问"你有哪些财务能力"，不要回：
-
-> ❌ "ttcli advertiser 模块有 balance / transaction / budget；ttcli bc 模块有 cost / transfer / invoice / billing-group / payment-portfolio / changelog-task ..."
-
-这是把内部命令树原样念给用户。非技术用户看不懂 namespace 划分、不关心 CLI 路径、不知道 BC / Portfolio / 异步任务是什么。
-
-**正确做法**：把能力翻译成**用户视角的事情**——"你想干嘛 → 我能帮你做"，不是"我有哪些命令"。
-
-参考翻译表：
-
-| 技术能力名（你看到的） | 翻给用户（你要说的） |
-|---|---|
-| `ttcli advertiser balance` / `bc balance` | "查你的广告账户里还剩多少钱" |
-| `ttcli bc cost` | "查最近广告实际花了多少（注意有约 10 小时延迟）" |
-| `ttcli advertiser transaction` / `bc transaction` | "看充值、扣款、退款的流水明细" |
-| `ttcli bc transfer` | "把钱从商务中心调到广告账户、或反向调回" |
-| `ttcli bc invoice` | "查发票、下载发票" |
-| `ttcli bc billing-group` | "管理账单分组（哪些广告账户合并成一张账单）" |
-| `ttcli bc payment-portfolio` | "管理财务资产组合（多账户共享一个钱袋的高级功能）" |
-| `ttcli advertiser budget` | "查广告主预算和它的变更历史" |
-| `ttcli bc changelog-task` | "导出广告账户的修改历史" — 用户说"我想看谁改了什么"就够了，**不要提"异步任务"**|
-
-**原则**：
-- 用户视角组织，不是 namespace 视角。"管钱"是一类，不是"advertiser 一类 + bc 一类"
-- 不出现 CLI 命令字面量、不出现 `ttcli` / `--help` / `namespace` / `endpoint`、不出现"白名单功能 / 异步任务 / changelog"等纯实现术语
-- 用动词起头："查"、"导"、"调钱"、"看明细"，让用户立刻判断"我要不要做这个"
-- 末尾邀请用户给具体诉求："你具体想看哪个？"，**不要**列 `ttcli xxx --help` 让用户自己研究
-- 唯一例外：用户**明确说自己是开发者 / 想看命令 / 想自己跑**，那时再列 CLI 命令
-
 ## ttcli vs vhcli — 它们是什么关系
 
 **两个工具不是 either/or 替代品**，是上下游：
@@ -235,10 +301,14 @@ bash $(npm root -g)/@bluevs/ttcli/skills/ttcli/scripts/install-skill.sh
 
 ## Trigger
 
-Use when the user wants to:
-- Create / list TikTok Smart+ campaigns or adgroups
-- Look up `app_id`, `location_id`, or other targeting metadata
-- Set or inspect TikTok API credentials
+Use when the user wants to do anything against TikTok (create / list / inspect):
+- Campaigns, ad groups, ads (Smart+ or manual)
+- Account finance: balance, spend, transactions, transfers, invoices
+- Catalog, audience, identity, pixel, conversion tracking
+- Reports & diagnostics
+- TikTok account operations (comments, messages, brand mentions, post authorization)
+
+Token acquisition is automatic via vhcli bridge (see "🚨 Token 走 vhcli bridge"); the user is **never** asked to provide an access_token directly.
 
 ## Network: requires HTTPS_PROXY in mainland China
 
@@ -639,8 +709,8 @@ Error: tiktok api error: code=40105 message="Access token is incorrect or has be
 ```
 
 Common codes:
-- `40105` → access token invalid or revoked. Tell the user to refresh.
-- `40001` → token has no permission for the advertiser_id in use. Likely `TIKTOK_ADVERTISER_ID` doesn't match what the token was authorized for.
+- `40105` → token invalid or revoked. **Don't ask the user to refresh** — re-run the vhcli bridge (`vhcli project account-token ...`) to get a fresh token, then retry. See "🚨 Token 走 vhcli bridge".
+- `40001` → token has no permission for the advertiser_id in use. Likely the vhcli bridge was run for a different (project, account) pair than the current `--advertiser-id`. Re-bridge with the matching `--account-id=<advertiser_id>`.
 
 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.
 
@@ -721,7 +791,8 @@ bridge 流程里 token 是从 vhcli stdout 直接 pipe 进 `--token=` 或 `ttcli
 
 ## Standard end-to-end flow
 
-1. `ttcli auth show` — confirm credentials
+0. (auto) Token bridge — if `ttcli` reports `TTCLI_TOKEN_MISSING`, fetch via vhcli (see "🚨 Token 走 vhcli bridge"), then continue. The user never sees this step.
+1. `ttcli auth show` — sanity-check that the bridged credentials are loaded (only when debugging "用了哪个广告主"; not part of every flow)
 2. `ttcli app list` → pick `app_id`
 3. `ttcli tool region --placements=... --objective-type=...` → pick `location_id`
 4. `ttcli smart-plus campaign create --dry-run ...` → review body