@bluevs/vhcli 0.5.8 → 0.5.9

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@bluevs/vhcli",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "description": "Vision Hub CLI - query projects and resources, designed for AI Agent and developers",
   "bin": {
     "vhcli": "scripts/run.js"
   },
   "scripts": {},
   "optionalDependencies": {
-    "@bluevs/vhcli-darwin-arm64": "0.5.8",
-    "@bluevs/vhcli-darwin-x64": "0.5.8",
-    "@bluevs/vhcli-linux-arm64": "0.5.8",
-    "@bluevs/vhcli-linux-x64": "0.5.8",
-    "@bluevs/vhcli-win32-arm64": "0.5.8",
-    "@bluevs/vhcli-win32-x64": "0.5.8"
+    "@bluevs/vhcli-darwin-arm64": "0.5.9",
+    "@bluevs/vhcli-darwin-x64": "0.5.9",
+    "@bluevs/vhcli-linux-arm64": "0.5.9",
+    "@bluevs/vhcli-linux-x64": "0.5.9",
+    "@bluevs/vhcli-win32-arm64": "0.5.9",
+    "@bluevs/vhcli-win32-x64": "0.5.9"
   },
   "engines": {
     "node": ">=16"
@@ -23,6 +23,7 @@
   },
   "license": "MIT",
   "files": [
-    "scripts/run.js"
+    "scripts/run.js",
+    "skill/"
   ]
 }

package/skill/SKILL.md

@@ -0,0 +1,383 @@
+---
+name: vh-skill
+description: VH AI营销平台 - 授权管理、项目操作、广告账户管理、素材报表、媒体平台操作。通过 vhcli CLI 与 VH 平台交互。
+---
+
+# VH SKILL - AI营销平台操作
+
+> VH平台(又称「AI营销平台」)的 CLI 工具。覆盖授权、项目管理、广告账户、素材报表、媒体平台操作。
+
+---
+
+## 安装
+
+```bash
+npm install -g @bluevs/vhcli
+```
+
+### 环境检测与自动安装
+
+```bash
+bash skills/vhcli/scripts/install-skill.sh
+```
+
+双向检测逻辑:
+
+| 场景 | 检测 | 动作 |
+|------|------|------|
+| 先装了 skill,没有 vhcli CLI | `which vhcli` | 自动 `npm install -g @bluevs/vhcli` |
+| 先装了 vhcli,没有 skill | 检测 npm 包内 `skill/` 目录 | 同步到 workspace |
+| 两者都在 + 版本一致 | 比对版本号 | 跳过 |
+| 两者都在 + 版本不同 | 比对版本号 | 同步新版(不覆盖本地 scripts/ 定制) |
+
+首次使用或升级时运行一次即可,后续无需重复执行。
+
+---
+
+## 架构概览
+
+```
+用户需求
+  │
+  ▼
+┌─────────────────────────────┐
+│ 执行前必检流程(见下方)     │
+└──────────────┬──────────────┘
+               │
+     ┌─────────┼─────────┐
+     ▼         ▼         ▼
+  第一层     第二层     第三层
+  平台授权   账户Token   下游操作
+  auth       project     media/google/
+  login      account-    material-report
+             token
+```
+
+---
+
+## 🚨 执行前必检流程(每次操作必须走完)
+
+### Step 1:确认平台用户授权
+
+```bash
+vhcli auth token
+```
+- 有 token → 继续
+- 无 token → 发起授权(飞书场景用卡片脚本)
+
+### Step 2:查项目列表,引导用户确认项目
+
+```bash
+vhcli project list
+```
+**⚠️ 即使只有一个项目,也必须让用户确认!**
+
+### Step 3:查项目下广告账户,引导用户确认账户
+
+```bash
+vhcli project accounts --project-id <project_id>
+```
+**⚠️ 必须让用户确认要操作哪个广告账户!**
+
+### Step 4:初始化该账户的 token 到本地
+
+```bash
+vhcli project account-token --customer-project-id <数字ID> --account-id <账户ID>
+```
+
+### Step 5:使用 token 进行下游操作
+
+从 `~/.vhcli/ad_tokens.json` 读取对应账户的 token。
+
+### 切换账户
+
+回到 Step 3 → 确认新账户 → 重新 account-token → 继续。
+
+---
+
+## 🚨 铁律:禁止用记忆/缓存冒充实时数据
+
+1. **任何平台数据必须实时查询**,不得用记忆中的旧数据当作查询结果
+2. 授权过期时立刻发起授权流程
+3. 记忆中的数据只能作为"提示/参考"
+
+---
+
+## 模块文档索引
+
+| 模块 | 文件 | 说明 |
+|------|------|------|
+| 认证 | [docs/auth.md](docs/auth.md) | 平台用户授权(Device Flow) |
+| 项目 | [docs/project.md](docs/project.md) | 项目查询、账户管理、成员管理、配置、开关 |
+| Google | [docs/google.md](docs/google.md) | Google Ads 直接操作 |
+| 素材报表 | [docs/material-report.md](docs/material-report.md) | 素材报表、归因报表、广告预览 |
+| Agent 日志 | [docs/agent.md](docs/agent.md) | 操作记录审计 |
+| 公司/产品 | [docs/company.md](docs/company.md) | 客户公司和产品查询 |
+| TikTok 广告创编 | [docs/tiktok.md](docs/tiktok.md) | 项目级创编任务、表单下拉选项、Spark Ads 授权 |
+
+---
+
+## Token 存储
+
+| 文件 | 内容 |
+|------|------|
+| `~/.vhcli/config.yaml` | 平台 server URL、app_id、token |
+| `~/.vhcli/ad_tokens.json` | 各广告账户的 access_token |
+
+### ad_tokens.json 结构
+
+```json
+{
+  "<customer_project_id>": {
+    "<account_id>": {
+      "token": "***",
+      "updated_at": "2026-05-19T10:35:53+08:00"
+    }
+  }
+}
+```
+
+---
+
+## 飞书授权卡片
+
+位置:`scripts/vh-auth-card.cjs`
+
+```bash
+# 显式传入 target(可选,支持任意格式)
+node skills/vhcli/scripts/vh-auth-card.cjs <oc_xxx|ou_xxx|user:ou_xxx>
+
+# 或通过环境变量传入
+OPENCLAW_CHAT_ID=user:ou_xxx node skills/vhcli/scripts/vh-auth-card.cjs
+```
+
+**Target 解析优先级(脚本内置逻辑):**
+1. `argv[2]` - 显式参数(最高优先)
+2. `VH_AUTH_TARGET` 环境变量
+3. `OPENCLAW_CHAT_ID` 环境变量(Agent spawn 时自动传入当前会话 chat_id)
+
+**格式自动解析:**
+- `oc_xxx` → 识别为群聊 chat_id
+- `ou_xxx` → 识别为 open_id
+- `user:ou_xxx` → 去掉前缀,取 open_id
+
+自动完成:获取 device code → 发蓝色卡片 → 等待授权 → patch 卡片变色
+
+### Agent 授权交互模式(必须遵守)
+
+**核心原则:在哪个会话触发的授权,就把授权卡片发到哪个会话。**
+
+#### Target 自动解析规则
+
+从当前 inbound message 的 `chat_id` 字段提取 target:
+- 群聊:`chat_id` 已是 `oc_xxx` → 直接用
+- 私聊:`chat_id` 格式为 `user:ou_xxx` → 去掉 `user:` 前缀,取 `ou_xxx`
+
+**Agent 禁止硬编码 target!必须从当前会话上下文动态提取。**
+
+当需要发起授权时,使用 **subagent 方案**:
+
+1. **主 agent 只发一句话**:"已发起授权,飞书会收到授权卡片,点击完成授权后我继续。"
+2. **spawn subagent** 执行授权脚本:
+   ```
+   sessions_spawn(mode="run", lightContext=true, task=执行授权脚本并只输出"授权成功"或"授权失败")
+   ```
+   subagent 任务内容：
+   ```bash
+   cd /root/.openclaw/workspace && node skills/vhcli/scripts/vh-auth-card.cjs <当前会话的原始chat_id，如 oc_xxx 或 user:ou_xxx，脚本自动解析>
+   ```
+3. **主 agent yield 等待** subagent announce
+4. **subagent announce 回来后**,主 agent 继续执行用户原始需求
+
+#### subagent 严格约束
+
+- subagent **只做授权**,不执行任何业务操作
+- subagent 的最终输出(announce 内容)**只允许两种**:
+  - `授权成功`
+  - `授权失败`
+- 不发消息给用户,不解释过程,不输出其他任何内容
+
+#### 主 agent 严格约束
+
+- 检测到未授权时,**只发一句话**:"已发起授权,飞书会收到授权卡片,点击完成授权后我继续。"
+- ❌ 禁止发多余的过程描述(如"先帮你查一下"、"正在发起授权"等)
+- ❌ 禁止在授权前后发超过必要的消息
+- 授权成功后直接执行业务,输出结果即可
+
+用户体验顺序:
+```
+1 主agent: "已发起授权,飞书会收到授权卡片,点击完成授权后我继续。"
+2 脚本自动发: 文字"请先完成AI营销平台授权" + 蓝色授权卡片
+3 用户点击完成授权 → 卡片变绿 + "授权成功,可以开始使用了"
+4 主agent: 直接输出业务结果
+```
+
+❗ 禁止:
+- 清除 token(auth login 本身会覆盖)
+- 暴露内部操作过程
+- 在授权脚本内耦合业务逻辑
+- 主 agent 发超过一句话的授权提示
+
+---
+
+## 清理授权
+
+```bash
+# 第一层:清除 vhcli 平台 token
+sed -i '/^token:/d; /^token_type:/d' ~/.vhcli/config.yaml
+
+# 第二层:清除账户 token
+rm -f ~/.vhcli/ad_tokens.json
+
+# 第三层:清除环境变量
+unset ACCESS_TOKEN
+```
+
+---
+
+## TikTok 广告创编
+
+`vhcli tiktok ...` 驱动 TikTok 广告创编流水线，与 `vhcli media tiktok`（需 `--auth-id`）不同，这里以项目（`--project-id`）为入口，使用 api-key 鉴权。
+
+> 完整数据模型、字段映射、错误目录：[docs/tiktok.md](docs/tiktok.md)
+
+### 三层配置（`task submit --config-file`）
+
+JSON 顶层包含 `campaign_config` / `adgroup_config` / `ad_config` 三个动态对象：
+
+| 层 | 已知字段 |
+|----|---------|
+| `campaign_config` | `campaign_name`, `budget`, `objective_type`, `app_promotion_type` |
+| `adgroup_config` | `adgroup_name`, `location_ids`, `languages`, `app_id`, `gender` |
+| `ad_config` | `ad_name`, `tiktok_account`, `identity_type`, `user_material`, `copywriting`, `selling_points` |
+
+其他 TikTok Marketing API 字段（如 `optimization_goal`、`interest_keyword_ids`、`landing_page_url`、`dark_post_status`）自动路由到对应层的 `extra_params`，无需 CLI 发版。
+
+### 典型工作流
+
+1. **并行**获取元数据：`options --type=identity|app|region|language|minis|audience`、`targeting-search`、`optimization-event`
+2. 预校验：提交前调用 `dark-post-status`（若 advertiser 或 identity 有 `ads_only_mode=true`，只允许 `dark_post_status=ON`）
+3. 组装三层 JSON；用唯一 UUID `--request-id` 提交（10 分钟幂等锁，重复 ID 被拒绝）
+4. 加 `--follow` 轮询最新任务至非 `PENDING`（`submit` 本身不返回 `task_id`）
+
+### 命令
+
+```bash
+# 1) 列出创编任务
+vhcli tiktok task list --project-id po_xxxx [--page-size 10] [--page-number 1]
+
+# 2) 提交创编任务（10 分钟幂等锁）
+vhcli tiktok task submit \
+  --project-id po_xxxx \
+  --resource-id 7234567890123456789 \
+  --request-id req_20260521_001 \
+  [--creative-app-id app_demo_001] \
+  --config-file ./payload.json \
+  [--follow]   # 每 5s 轮询最新任务至非 PENDING，超时 5 分钟
+
+# payload.json 示例
+# {
+#   "campaign_config": { "campaign_name": "Demo", "objective_type": "APP_PROMOTION" },
+#   "adgroup_config":  { "adgroup_name": "Demo", "location_ids": "6252001" },
+#   "ad_config":       { "ad_name": "Demo", "tiktok_account": "..." }
+# }
+
+# 3) 表单下拉（--type 决定返回元素结构）
+vhcli tiktok options --project-id po_xxxx --resource-id <ID> --type language
+vhcli tiktok options --project-id po_xxxx --resource-id <ID> --type region --objective-type APP_PROMOTION --language zh
+vhcli tiktok options --project-id po_xxxx --resource-id <ID> --type identity
+vhcli tiktok options --project-id po_xxxx --resource-id <ID> --type minis
+vhcli tiktok options --project-id po_xxxx --resource-id <ID> --type app
+vhcli tiktok options --project-id po_xxxx --resource-id <ID> --type audience
+
+# 4) 校验 dark_post_status（设置 ad_config.dark_post_status 前必须调用）
+vhcli tiktok dark-post-status \
+  --project-id po_xxxx \
+  --resource-id 7234567890123456789 \
+  --identity-id 7888888888888888888 \
+  --identity-type CUSTOMIZED_USER \
+  [--identity-authorized-bc-id BC_xxx]   # identity_type=BC_AUTH_TT 时必填
+
+# 5) 优化事件（仅返回 availability_status=READY；--placements 支持逗号分隔或重复传）
+vhcli tiktok optimization-event \
+  --project-id po_xxxx \
+  --resource-id 7234567890123456789 \
+  --app-id 7234567890123456789 \
+  --objective APP_PROMOTION \
+  --optimization-goal CONVERT \
+  --placements PLACEMENT_TIKTOK,PLACEMENT_PANGLE
+
+# 6) 兴趣定向树（INTEREST_AND_BEHAVIOR，按顶级分组：video_interaction / general_interest / ...）
+vhcli tiktok targeting-search \
+  --project-id po_xxxx \
+  --resource-id 7234567890123456789
+
+# 7) 批量授权 Spark Ads 帖子（服务端上限 50 并发；返回 identity_id 不匹配或失败的 auth_codes）
+vhcli tiktok spark-ads authorize \
+  --project-id po_xxxx \
+  --resource-id 7234567890123456789 \
+  --tiktok-account 7234567890123456789 \
+  --auth-codes "AUTHCODE_AAAA,AUTHCODE_BBBB,AUTHCODE_CCCC"
+```
+
+---
+
+## 命令速查
+
+```bash
+# 认证
+vhcli auth login                    # 平台授权
+vhcli auth token                    # 查看 token
+vhcli config                        # 完整配置
+
+# 项目
+vhcli project list                  # 项目列表
+vhcli project info --project-id <po_xxx>
+vhcli project accounts --project-id <po_xxx> [--platform-list Meta]
+vhcli project account-token --customer-project-id <N> --account-id <ID>
+
+# 授权
+vhcli authorization list [--platform Meta]
+
+# 媒体操作
+vhcli media campaign-list --auth-id <N>
+vhcli media ad-list --auth-id <N>
+vhcli media report-get --auth-id <N> --start-date X --end-date Y
+
+# 报表
+vhcli material-report get --customer-project-id <N> --platform Meta --start-time X --end-time Y
+
+# Google
+vhcli google update-campaign-budget --customer-project-id <N> --account-id <ID> --campaign-id <ID> --target-budget 100
+
+# Agent 日志
+vhcli agent operate-record --customer-project-id <N> --account-id <ID> --operator x@x.com --operation-type CREATE --status SUCCESS
+
+# 公司/产品
+vhcli company list
+vhcli company product-list
+
+# TikTok 广告创编
+vhcli tiktok task list --project-id po_xxxx
+vhcli tiktok task submit --project-id po_xxxx --resource-id <ID> --request-id <UUID> --config-file ./payload.json [--follow]
+vhcli tiktok options --project-id po_xxxx --resource-id <ID> --type language|region|identity|minis|app|audience
+vhcli tiktok dark-post-status --project-id po_xxxx --resource-id <ID> --identity-id <ID> --identity-type CUSTOMIZED_USER
+vhcli tiktok optimization-event --project-id po_xxxx --resource-id <ID> --app-id <ID> --objective APP_PROMOTION --optimization-goal CONVERT --placements PLACEMENT_TIKTOK
+vhcli tiktok targeting-search --project-id po_xxxx --resource-id <ID>
+vhcli tiktok spark-ads authorize --project-id po_xxxx --resource-id <ID> --tiktok-account <ID> --auth-codes "CODE1,CODE2"
+
+# API 自省
+vhcli schema                        # 所有模块
+vhcli schema <module>               # 模块端点
+vhcli schema <module.endpoint>      # 端点参数
+```
+
+---
+
+## 核心原则
+
+> 在执行任何需求前,必须明确:
+> 1. **谁**在操作(平台授权是否有效)
+> 2. 操作**哪个项目**(必须用户确认)
+> 3. 操作**哪个账户**(必须用户确认)
+> 4. 该账户的 **token 是否已初始化到本地**

package/skill/docs/agent.md

@@ -0,0 +1,43 @@
+# Agent - 广告创编操作记录
+
+> 记录 Agent 执行的广告创建/修改/删除操作日志，用于审计追踪。
+
+---
+
+## operate_record
+
+记录一次广告创编操作（campaigns/adsets/ads 创建日志）。
+
+**CLI:**
+```bash
+vhcli agent operate-record \
+  --customer-project-id <int> \
+  --account-id <string> \
+  --operator <email> \
+  --operation-type <CREATE|UPDATE|DELETE> \
+  --status <SUCCESS|FAILED|PARTIAL> \
+  [--confirmer <email>] \
+  [--campaigns-count <int>] \
+  [--adsets-count <int>] \
+  [--ads-count <int>] \
+  [--detail-json '<json>']
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID（数字） |
+| account_id | string | ✅ | 广告账户 ID |
+| operator | string | ✅ | 操作人邮箱 |
+| confirmer | string | | 确认人邮箱 |
+| operation_type | string | ✅ | 操作类型：CREATE / UPDATE / DELETE |
+| status | string | ✅ | 状态：SUCCESS / FAILED / PARTIAL |
+| campaigns_count | int32 | | 创建的 campaign 数量 |
+| adsets_count | int32 | | 创建的 adset 数量 |
+| ads_count | int32 | | 创建的 ad 数量 |
+| detail_json | object | | 操作详情 JSON 对象 |
+
+**响应:** CommonResponse
+
+**备注:** 这是写入操作（write: true），需要认证。

package/skill/docs/auth.md

@@ -0,0 +1,47 @@
+# Auth - 平台用户认证
+
+> VH AI营销平台用户级认证（Device Flow），获取平台 token 用于后续所有 API 调用。
+
+---
+
+## login
+
+发起 Device Flow 授权登录。输出授权 URL 和验证码，用户在浏览器完成授权后自动获取 token。
+
+**CLI:**
+```bash
+vhcli auth login
+```
+
+**流程:**
+1. CLI 输出授权 URL + 验证码
+2. 用户访问 URL 并输入验证码
+3. 完成后 token 自动写入 `~/.vhcli/config.yaml`
+
+**飞书场景:** 使用 `scripts/vh-auth-card.cjs` 发送交互卡片，无需用户手动复制 URL。
+
+---
+
+## token
+
+查看当前平台 token。
+
+**CLI:**
+```bash
+vhcli auth token
+```
+
+**用途:** 检查是否已认证。有输出 = 已认证，无输出 = 需要 login。
+
+---
+
+## config
+
+查看完整配置信息（server URL、app_id、token 等）。
+
+**CLI:**
+```bash
+vhcli config
+```
+
+**配置文件位置:** `~/.vhcli/config.yaml`

package/skill/docs/company.md

@@ -0,0 +1,47 @@
+# Company - 客户公司与产品查询
+
+> 查询客户公司（品牌）和产品信息。
+
+---
+
+## list
+
+列出公司列表，支持分页和搜索。
+
+**CLI:**
+```bash
+vhcli company list [--page-size 20] [--page-num 1] [--company-name <name>]
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| page_size | int32 | | 20 | 每页条数 |
+| page_num | int32 | | 1 | 页码 |
+| company_name | string | | | 按公司名搜索 |
+
+**响应:** CompanyListData（含 pagination + list）
+
+---
+
+## product_list
+
+列出产品列表，支持按公司过滤和搜索。
+
+**CLI:**
+```bash
+vhcli company product-list [--page-size 20] [--page-num 1] [--company-id <int>] [--product-name <name>] [--category <cat1,cat2>]
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| page_size | int32 | | 20 | 每页条数 |
+| page_num | int32 | | 1 | 页码 |
+| company_id | int32 | | | 按公司 ID 过滤 |
+| product_name | string | | | 按产品名搜索 |
+| category | []string | | | 按类别过滤 |
+
+**响应:** ProductListData（含 pagination + list）

package/skill/docs/google.md

@@ -0,0 +1,34 @@
+# Google - Google Ads 直接操作
+
+> Google Ads 广告系列预算等直接操作。
+
+---
+
+## update_campaign_budget
+
+更新 Google 广告系列预算。
+
+**CLI:**
+```bash
+vhcli google update-campaign-budget \
+  --customer-project-id <int> \
+  --account-id <string> \
+  --campaign-id <string> \
+  --target-budget <float>
+```
+
+**参数:**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| customer_project_id | int32 | ✅ | 客户项目 ID（数字） |
+| account_id | string | ✅ | 广告账户 ID |
+| campaign_id | string | ✅ | 广告系列 ID |
+| target_budget | float64 | ✅ | 目标预算（USD） |
+
+**响应:** CampaignBudgetData
+- campaign_name: 广告系列名称
+- before_budget: 修改前预算
+- after_budget: 修改后预算
+
+**备注:** 写入操作，需要认证。