@bluevs/ttcli 0.0.9 → 0.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluevs/ttcli",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "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.10",
+    "@bluevs/ttcli-darwin-x64": "0.0.10",
+    "@bluevs/ttcli-linux-arm64": "0.0.10",
+    "@bluevs/ttcli-linux-x64": "0.0.10",
+    "@bluevs/ttcli-win32-arm64": "0.0.10",
+    "@bluevs/ttcli-win32-x64": "0.0.10"
   },
   "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.10
+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.10`
 >
 > 当用户问"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,102 @@ token 拿到之后也不要回报"我已经从 vhcli 取了 token"——直接
 - vhcli 找不到（没装 / PATH 没配）→ 这是部署问题，跟用户说「我这边 vhcli 跑不起来，请联系部署的同事看看」
 - vhcli 拿到的 token ttcli 一调就 `code=40105 token expired/revoked` → 重跑 vhcli 那一步，token 可能 vhcli 本地缓存过期
 
-## 🔍 如何发现 ttcli 能力（不要靠记忆）
+## 🚨 硬性约定：用户问"能干啥"时禁止开发术语，但表格/分组没问题
+
+**这是被反复违反的规则，所以放到很前面。**
+
+`ttcli schema` 拿到的是给你（AI Agent）看的**内部能力索引**——内容（`campaign` / `子命令` / `714 行 / 节点`这些词）是 dev 视角，**不能原样回给用户**。
+
+但**形式上**用表格、分模块、列举多个能力都没问题——这些反而帮用户结构化看到全貌。问题只在**词汇**：把 CLI 字面量替换成中文业务词、把 jargon 替换成白话、不要暴露内部实现概念。
+
+### 用户问的常见问题
+
+- "ttcli 都有什么能力？"
+- "你能干嘛？"
+- "你有哪些财务能力？"
+- "ttcli 支持哪些操作？"
+
+### 词汇黑名单——这些词**永远不要**出现在用户对话
+
+**内部实现概念**（一律不出现）：
+- `子命令` / `namespace` / `命令树` / `X 节点` / `X 行 / 共 X 个命令`
+- `endpoint` / `flag` / `--token` / `ttcli` 这种 CLI 字面量
+- `Marketing token vs 非 Marketing token` / `Marketing API vs Account API` 这种内部分层
+
+**CLI 命令字面量**（要翻译成中文业务词，不直接念名字）：
+
+| ❌ 不能直接说 | ✅ 翻成 |
+|---|---|
+| `campaign` | 广告系列 |
+| `adgroup` | 广告组 |
+| `ad` | 广告 |
+| `smart-plus` | Smart+ 智能投放 |
+| `bc` / `BC` / `Business Center` | 商务中心 |
+| `advertiser` | 广告主账户 |
+| `identity` | 投放身份（用于发广告的 TikTok 账号） |
+| `creative` | 创意素材 |
+| `dmp` / `DMP` | 人群包 |
+| `pixel` | 像素（网页转化追踪） |
+| `webhook` | 事件订阅 |
+| `tt-video` / `Spark Ads` | 授权视频 / 帮播视频（Spark Ads 用户听不懂） |
+| `gmv-max` / `GMV Max` | 商品销量最大化广告 |
+| `R&F` / `Reach & Frequency` | 预订式触达广告 |
+| `ACO` / `Smart Creative` | 智能创意（自动组合素材） |
+| `Catalog` | 商品目录 |
+| `MMM` | 营销组合归因 |
+
+不在表里的词遇到了就翻成白话，不要原样吐。
+
+### 正面例子（这次想要的样子）
+
+✅ 用户问 "ttcli 都有什么能力？"——表格分组都行，**只是要换词**：
+
+> "可以帮你做这些（按场景分）：
+>
+> | 场景 | 能干啥 |
+> |---|---|
+> | **广告创编** | 建/调/查广告系列、广告组、广告；Smart+ 智能投放全流程 |
+> | **素材与创意** | 上传管理视频图片音乐，用智能工具优化创意（自动剪辑/智能文案/试玩广告） |
+> | **账户与财务** | 查余额和实际花费、看流水、商务中心和广告账户之间调钱、管发票/账单 |
+> | **受众与定向** | 管人群包、配兴趣/行为/话题定向、查地区语言设备等基础数据 |
+> | **数据与报表** | 拉异步报表、看创意疲劳度、做投放诊断 |
+> | **应用与电商** | 管 App 推广、Minis 小程序、商品目录、店铺、商品销量最大化广告 |
+> | **TikTok 账号运营** | 管账号 profile、评论、私信、品牌提及、话题，授权视频做广告 |
+> | **其他** | 屏蔽词、自动化规则、A/B 测试、自定义转化、事件订阅 |
+>
+> **你想从哪开始**？"
+
+注意：用了表格 ✓ / 用了"模块"概念分组 ✓ / 但把 `campaign` 写成"广告系列"、把 `BC` 写成"商务中心"、把 `R&F` 写成"预订式触达广告"。
+
+### 反面例子（这次踩的真坑——形式没错，词错了）
+
+❌
+
+> "ttcli v0.0.9 完整命令树有 714 行，按模块分类给你一个全景表：
+>
+> **广告创编**
+> 模块 / 子命令 / 能力
+> campaign / get / 查询广告系列
+> adgroup / get, appeal, quota, ... / 广告组查询/申诉/配额
+> ad / get, review-info, aco ... / 广告查询/审核/ACO智能创意
+> ..."
+
+错在哪：(1) "完整命令树有 714 行" 是内部实现，(2) "子命令" 这列是 CLI 概念，(3) `campaign / adgroup / ad` 是字面量没翻译，(4) `ACO智能创意` 既出现了 ACO 又出现了翻译——前者多余。
+
+### 硬规则
+
+- 形式自由：表格、列表、分组都可以
+- **结尾必须反问**："你想从哪开始？" / "你具体想做哪一类？"——把球还给用户
+- **词必须中文化**：CLI 字面量、英文 jargon、内部分层词全替换
+- **不许提"完整命令树"、"X 行"、"X 节点"、"子命令"** 这种实现内幕
+
+### 唯一例外
+
+用户**明确**说"我是开发者，给我列出所有 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 +239,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 +255,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 +299,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 +707,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 +789,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