@bluevs/ttcli 0.0.7 → 0.0.8

package/package.json

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

package/skills/ttcli/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: ttcli
-version: 0.0.7
+version: 0.0.8
 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.7`
+> **Skill version**: `0.0.8`
 >
 > 当用户问"ttcli skill 版本是多少 / skill 装好了吗 / 升级生效了没" 时，**直接念出上面的版本号**。
 > 用户期望更高版本但没看到 → 让他们：(1) 重跑 `npm install -g @bluevs/ttcli && bash $(npm root -g)/@bluevs/ttcli/skills/ttcli/scripts/install-skill.sh` (2) 然后**新开一个会话**（skill 在会话启动时加载，老会话不刷新）。
@@ -33,6 +33,70 @@ This skill is intentionally short. Always treat `ttcli -h` and `ttcli <subcomman
 
 如果用户问「能不能直接调 X 接口」，先回「我们走 ttcli，让我看看包了没；没包的话我把这个接口加到 ttcli 里再用，会更稳」。
 
+## 🚨 硬性约定：Token 走 vhcli bridge，禁止找用户直接要 token
+
+**ttcli 不自己持有 token**，靠 vhcli（Vision Hub CLI）发证。用户**永远**不需要手填 access_token——你看到 ttcli 报缺 token 时，自动走下面这段流程，不要把 token 这种技术词汇暴露给用户。
+
+### 协议触发条件
+
+ttcli 在 token 缺失时返回的错误**首行包含 `TTCLI_TOKEN_MISSING`** marker。看到这串就触发 bridge，**不要把这条原文展示给用户**——它是机器协议，不是用户对话。
+
+### Bridge 步骤
+
+1. **拿 customer_project_id**：
+   - 用户对话里已经提到的项目（"VH 项目 PO_xxxx"、"客户项目 ID 12345"等）→ 优先用
+   - 没提到 → `vhcli project list` 自己捞，然后跟用户确认是哪个项目（**用项目名字而不是 ID**：「你这次想用哪个项目，A / B / C？」）
+   - 用户没绑过任何项目 → 让用户去 VH 后台先绑，然后回来再说
+
+2. **拿 advertiser_id（TikTok 广告账户 ID）**：
+   - 用户对话里已经给过 / ttcli 的 `--advertiser-id` 已经设了 → 用那个
+   - 没有 → 从 vhcli 列出的项目下属账户里挑（**用账户名而不是 ID**），跟用户确认
+
+3. **调 vhcli 拿 token**：
+
+   ```bash
+   vhcli project account-token \
+     --customer-project-id=<NUM> \
+     --account-id=<advertiser_id> \
+     --format=json
+   ```
+
+   vhcli 会**同时**：
+   - stdout 输出 JSON，含 `access_token` 字段
+   - 落到 `~/.vhcli/ad_tokens.json`
+
+4. **把 token 喂给 ttcli**——选其一：
+
+   **临时（推荐）**：从 vhcli stdout JSON 抽 `access_token`，紧接着的 ttcli 调用加 `--token=<TOKEN>`：
+
+   ```bash
+   TOKEN=$(vhcli project account-token --customer-project-id=N --account-id=A --format=json | jq -r .access_token)
+   ttcli --token="$TOKEN" --advertiser-id=A bc list ...
+   ```
+
+   **持久化（用户长期就这一个账号、不切换时）**：
+
+   ```bash
+   ttcli auth set --token="$TOKEN" --advertiser-id=A
+   # 之后所有 ttcli 调用都不用再传 --token
+   ```
+
+5. **重跑**用户最初的 ttcli 命令。
+
+### 跟用户怎么说
+
+用户**完全不应该**看到 `TTCLI_TOKEN_MISSING`、access_token、customer_project_id 这些词。整个 bridge 在你脑子里悄悄跑。需要用户输入时只问业务问题，比如：
+- ❌ "ttcli 报 TTCLI_TOKEN_MISSING，请提供 customer_project_id 和 advertiser_id"
+- ✅ "我先确认一下：你这次是用哪个项目下的哪个广告账户？"
+
+token 拿到之后也不要回报"我已经从 vhcli 取了 token"——直接做用户要的事。
+
+### 失败模式
+
+- vhcli 报"账户没授权"/"未绑定项目" → 翻译给用户：「这个广告账户在 VH 这边还没绑到这个项目下，麻烦先在 VH 后台关联一下」
+- vhcli 找不到（没装 / PATH 没配）→ 这是部署问题，跟用户说「我这边 vhcli 跑不起来，请联系部署的同事看看」
+- vhcli 拿到的 token ttcli 一调就 `code=40105 token expired/revoked` → 重跑 vhcli 那一步，token 可能 vhcli 本地缓存过期
+
 ## 🔍 如何发现 ttcli 能力（不要靠记忆）
 
 SKILL.md **不**枚举所有 ttcli 子命令；项目还在长。新会话或不确定 ttcli 是否已支持某能力时，走两步发现：
@@ -96,18 +160,59 @@ ttcli 和 TikTok 返回的报错都是技术语言（`missing required fields: [
 - 多个字段同时缺 → 合并成一个自然问句，不要逐个列字段名
 - request_id 留你脑子里 / 日志里，**不主动甩给用户**，除非用户明确要"找 TikTok 提工单"
 
-## ttcli vs vhcli tiktok — 选哪一个
+## 🚨 与用户对话的硬性约定：能力清单也要翻译
+
+跟用户聊"你能做什么"的时候，**严禁直接吐 CLI 命令名 / namespace / 技术术语**。用户问"你有哪些财务能力"，不要回：
+
+> ❌ "ttcli advertiser 模块有 balance / transaction / budget；ttcli bc 模块有 cost / transfer / invoice / billing-group / payment-portfolio / changelog-task ..."
 
-openclaw 同时装了两个 TikTok 广告工具，触发条件不同：
+这是把内部命令树原样念给用户。非技术用户看不懂 namespace 划分、不关心 CLI 路径、不知道 BC / Portfolio / 异步任务是什么。
 
-| 用户提供的上下文 | 用 |
+**正确做法**：把能力翻译成**用户视角的事情**——"你想干嘛 → 我能帮你做"，不是"我有哪些命令"。
+
+参考翻译表：
+
+| 技术能力名（你看到的） | 翻给用户（你要说的） |
 |---|---|
-| 原生 `access_token` + `advertiser_id`（用户从 TikTok Marketing 后台直接复制的）| **ttcli** |
-| `po_xxxx` 项目 ID、提到 VH 平台、`customer_project_id` / `account_id` | **vhcli tiktok** |
-| 想直连 TikTok 调试原生 API 行为 / 看真实错误码 | **ttcli** |
-| 想要 VH 的项目级审计、审批、异步任务 | **vhcli tiktok** |
+| `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 — 它们是什么关系
 
-**鉴权材料是关键判断点**——access_token 直接给的走 ttcli，从 VH project 拿的走 vhcli。如果用户没说清楚，**先问**他要给你哪种 token，不要猜。
+**两个工具不是 either/or 替代品**，是上下游：
+
+```
+   vhcli (project / token / audit)
+        │
+        │ 发 access_token
+        ▼
+   ttcli (TikTok Marketing API consumer)
+        │
+        │ Access-Token header
+        ▼
+   business-api.tiktok.com
+```
+
+| 工具 | 干什么 | 何时用 |
+|---|---|---|
+| **vhcli** | VH 平台项目管理：列项目、列账户、**发 access_token**、项目级审计/审批 | (1) token bridge 的发证方（见上面"Token 走 vhcli bridge"协议）（2) 用户问"项目 PO_xxxx 下有哪些账户"这种 VH 元数据问题 |
+| **ttcli** | TikTok Marketing API 的瘦客户端：~700 个 cobra 命令对应官方所有 endpoint | 一切实际 TikTok 业务操作（创广告、查余额、列 campaign、看流水……） |
+
+**判断准则**：操作目标是 TikTok 实体（campaign/adgroup/ad/identity/...）→ ttcli。操作目标是 VH 元数据（project/team/audit）→ vhcli。token 永远走 vhcli 发，永远不让用户手填。
 
 
 ## Installation
@@ -600,6 +705,8 @@ Limits: 1 QPS per app; 500 async tasks/hour per advertiser; 30-day task validity
 
 ## Credentials
 
+**主流程**：token 走 vhcli bridge（见上面"🚨 Token 走 vhcli bridge"那节）。下面是 ttcli 自己的 credential 解析链——开发者本地调试或排查"用了哪个 token"时会用到。
+
 Priority: `--flag` > env var > config file (`~/.config/ttcli/credentials.json`, mode 0600).
 
 | Field | Flag | Env |
@@ -608,13 +715,9 @@ Priority: `--flag` > env var > config file (`~/.config/ttcli/credentials.json`,
 | Advertiser ID | `--advertiser-id` | `TIKTOK_ADVERTISER_ID` |
 | Base URL | `--base-url` | `TIKTOK_BASE_URL` |
 
-Persist for the local user with:
-
-```
-ttcli auth set --token=... --advertiser-id=...
-```
+bridge 流程里 token 是从 vhcli stdout 直接 pipe 进 `--token=` 或 `ttcli auth set`，前者临时（推荐多账户场景）后者持久化（推荐单账户长期场景）。
 
-`auth show` reports each value and where it came from (`flag` / `env:VAR` / `file` / `default` / `unset`); useful when a write fails with `40001` and you suspect the wrong advertiser is being used.
+`auth show` 报每个值的来源（`flag` / `env:VAR` / `file` / `default` / `unset`）；当一次写操作报 `40001 No permission` 而你怀疑用错了广告主，先 `ttcli auth show` 确认。
 
 ## Standard end-to-end flow