siluzan-tso-cli 1.0.0-beta.4

package/assets/siluzan-ads/SKILL.md

@@ -0,0 +1,774 @@
+---
+name: siluzan-tso
+description: >-
+  管理 Siluzan TSO 平台的广告投放全流程：账户查询与余额、消耗数据、开户申请（Google/TikTok/Yandex/Bing/Kwai）、
+  账号分享/断开关联、开户历史、优化报告、媒体转账、开票管理、AI智投记录、AI广告优化、
+  智能预警规则（创建/编辑/启停/删除）、广告线索表单（TikTok/Meta）、
+  Google 广告管理（系列/组/创意/关键词）、关键字推荐。
+  注意：本 skill 仅处理「广告投放管理」，发布视频/图文内容请使用 siluzan-platform skill。
+description_zh: >-
+  管理 Siluzan TSO 平台的广告投放全流程：账户查询与余额、消耗数据、开户申请（Google/TikTok/Yandex/Bing/Kwai）、
+  账号分享/断开关联、开户历史、优化报告、媒体转账、开票管理、AI智投记录、AI广告优化、
+  智能预警规则（创建/编辑/启停/删除）、广告线索表单（TikTok/Meta）、
+  Google 广告管理（系列/组/创意/关键词）、关键字推荐。
+  注意：本 skill 仅处理「广告投放管理」，发布视频/图文内容请使用 siluzan-platform skill。
+description_en: >-
+  Manage the full advertising workflow on Siluzan TSO: account list & balance, spend data,
+  account opening (Google/TikTok/Yandex/Bing/Kwai), account sharing/delink,
+  account opening history, optimization reports, media transfers, invoice management,
+  AI creation records, AI ad optimization, intelligent alerts, Google ad management
+  (campaigns/groups/ads/keywords), and keyword suggestions.
+  Supported media: Google, TikTok, Meta, Bing, Yandex, Kwai.
+  Note: This skill handles AD MANAGEMENT only. For content publishing (video/image-text),
+  use the siluzan-platform skill instead.
+---
+
+# Siluzan TSO Skill
+
+## 核心原则
+
+**通过 `siluzan-tso` CLI 完成广告投放管理，不要手动调接口。**
+
+| 场景 | 命令 |
+|------|------|
+| 查询广告账户 | `siluzan-tso list-accounts` |
+| 查询账户余额 | `siluzan-tso balance -m Google -a <id>` |
+| 查询投放数据 | `siluzan-tso stats -m TikTok` |
+| **开户申请（Google）** | `siluzan-tso open-account google --advertiser-id <magKey> ...` |
+| **开户申请（TikTok）** | `siluzan-tso open-account tiktok --advertiser-id <magKey> --license-file <path> ...` |
+| **开户申请（Yandex）** | `siluzan-tso open-account yandex --advertiser-id <magKey> ...` |
+| **开户申请（Bing）** | `siluzan-tso open-account bing --advertiser-id <magKey> --license-file <path> ...` |
+| **开户申请（Kwai）** | `siluzan-tso open-account kwai --advertiser-id <magKey> --license-file <path> ...` |
+| **查广告主组（取 magKey）** | `siluzan-tso open-account list-groups` |
+| **添加 OAuth 授权** | `siluzan-tso account auth -m Google` |
+| **断开账户关联** | `siluzan-tso account delink --id <entityId>` |
+| **账号分享** | `siluzan-tso account share --id <entityId> --phone <手机号>` |
+| **取消账号分享** | `siluzan-tso account unshare --id <entityId> --account-id <userId>` |
+| **查分享详情** | `siluzan-tso account share-detail --customer-id <mediaCustomerId>` |
+| 开户申请历史 | `siluzan-tso account-history` |
+| 优化报告列表 | `siluzan-tso report list -m Google` |
+| **现金充值 / 月结充值 / 钱包** | 引导至网页（见 recharge 章节） |
+| 媒体转账记录 | `siluzan-tso transfer -m Google` |
+| 开票记录 | `siluzan-tso invoice list` |
+| AI智投记录 | `siluzan-tso ai-creation list` |
+| AI广告优化 | `siluzan-tso optimize list` |
+| **线索表单（TikTok）** | `siluzan-tso clue -m TikTok -a <advertiserId>` |
+| **线索表单（Meta）** | `siluzan-tso clue -m Meta -a <pageId>` |
+| 智能预警列表 | `siluzan-tso forewarning list -m Google` |
+| **创建预警规则** | `siluzan-tso forewarning create -m Google --name "..." --accounts <ids> --field cost --operator GREATER_EQUALS --value 500` |
+| **编辑预警规则** | `siluzan-tso forewarning update -m Google --id <ruleId> ...` |
+| **查看单条预警规则** | `siluzan-tso forewarning get -m Google --id <ruleId>` |
+| **查看报告（网页）** | `{webUrl}/media-report/publish/{entityId}?culture=zh-CN` |
+| Google 广告管理 | `siluzan-tso ad campaigns -a <accountId>` |
+| 关键字推荐 | `siluzan-tso keyword -k "running shoes"` |
+
+---
+
+## 认证
+
+`siluzan-tso` 与 `siluzan-cso` **共用同一个 Token**（存储在 `~/.siluzan/config.json`）。
+
+- 若用户已通过 `siluzan-cso login` 配置过 Token，**无需重新配置**，直接使用 `siluzan-tso` 命令即可。
+- 若未配置，引导用户运行：`siluzan-cso login`
+
+验证配置是否就绪：
+```bash
+siluzan-tso config show
+```
+
+**环境切换**（默认指向生产环境，测试环境需手动切换）：
+
+| 配置项 | 生产环境（默认） | 测试环境 |
+|--------|-----------------|---------|
+| `apiBaseUrl`（TSO 主 API） | `https://tso-api.siluzan.com` | `https://tso-api-ci.siluzan.com` |
+| `googleApiUrl`（Google 广告网关） | `https://googleapi.mysiluzan.com` | `https://googleapi-ci.mysiluzan.com` |
+
+切换到测试环境：
+```bash
+siluzan-tso config set --api-base https://tso-api-ci.siluzan.com
+siluzan-tso config set --google-api https://googleapi-ci.mysiluzan.com
+```
+
+切换回生产环境（或删除 config.json 中对应字段以恢复默认）：
+```bash
+siluzan-tso config set --api-base https://tso-api.siluzan.com
+siluzan-tso config set --google-api https://googleapi.mysiluzan.com
+```
+
+---
+
+## 命令详细说明
+
+### list-accounts — 查询广告账户列表
+
+```bash
+siluzan-tso list-accounts [选项]
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-m, --media <type>` | 媒体类型（留空查全部）：`Google \| TikTok \| Yandex \| MetaAd \| BingV2 \| Kwai` |
+| `-k, --keyword <text>` | 按账户名称或 ID 搜索 |
+| `-s, --status <status>` | 账户状态：`normal \| invalid \| all`（默认 all）|
+| `-p, --page <n>` | 页码（默认 1） |
+| `--page-size <n>` | 每页数量（默认 20） |
+| `--json` | 输出原始 JSON |
+
+```bash
+siluzan-tso list-accounts -m Google
+siluzan-tso list-accounts -k "品牌A" --json
+```
+
+---
+
+### balance — 查询实时余额
+
+```bash
+siluzan-tso balance -m <媒体类型> -a <账户ID列表>
+```
+
+```bash
+siluzan-tso balance -m Google -a 1234567890
+siluzan-tso balance -m TikTok -a 111111,222222 --json
+```
+
+---
+
+### stats — 查询投放数据
+
+```bash
+siluzan-tso stats -m <媒体类型> [选项]
+```
+
+| 选项 | 说明 | 默认 |
+|------|------|------|
+| `-m, --media <type>` | 媒体类型（必填） | — |
+| `-a, --accounts <ids>` | 账户 ID 列表（留空查全部） | 全部 |
+| `--start <YYYY-MM-DD>` | 开始日期 | 7 天前 |
+| `--end <YYYY-MM-DD>` | 结束日期 | 昨天 |
+
+```bash
+siluzan-tso stats -m TikTok
+siluzan-tso stats -m Google --start 2026-03-01 --end 2026-03-31
+```
+
+---
+
+### account-history — 开户申请历史
+
+```bash
+siluzan-tso account-history [选项]
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-m, --media <type>` | 媒体类型 |
+| `-s, --status <status>` | 申请状态 |
+| `-k, --keyword <text>` | 账户名/ID 关键字 |
+| `--start / --end <date>` | 日期范围 |
+
+```bash
+siluzan-tso account-history -m Google
+siluzan-tso account-history --status Approved --json
+```
+
+---
+
+### report — 优化报告
+
+#### 报告列表
+
+```bash
+siluzan-tso report list -m <媒体> [选项]
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-m, --media` | 媒体类型（必填）：`Google \| TikTok` |
+| `-t, --type <type>` | 报告类型，如 `Daily \| Hourly` |
+| `-s, --status <ready>` | 生成状态 `true \| false` |
+| `-k, --keyword` | 报告名称关键字 |
+| `--start / --end` | 日期范围 |
+
+```bash
+siluzan-tso report list -m Google
+siluzan-tso report list -m TikTok -t Daily --start 2026-03-01 --end 2026-03-15
+```
+
+#### 批量生成报告
+
+```bash
+siluzan-tso report create -m Google -a <账户ID列表> -t Daily --start 2026-03-01 --end 2026-03-07
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-m, --media` | 媒体类型（必填） |
+| `-a, --accounts <ids>` | 账户 ID，逗号分隔（必填） |
+| `-t, --type` | 报告类型（必填） |
+| `--start / --end` | 日期范围（必填） |
+
+#### 删除报告
+
+```bash
+siluzan-tso report delete --id <entityId>
+siluzan-tso report delete --ids <id1,id2,id3>
+```
+
+#### 推送管理
+
+```bash
+siluzan-tso report push list -m Google          # 查询推送列表
+siluzan-tso report push start -m Google --id <id>   # 启动推送
+siluzan-tso report push stop  -m Google --id <id>   # 停止推送
+siluzan-tso report push delete -m Google --id <id>  # 删除推送
+```
+
+#### 查看报告（引导打开网页）
+
+报告生成后，用户可在网页上查看内容。通过 `siluzan-tso config show` 获取 `webUrl`，按以下规则拼接查看链接：
+
+| 媒体 | 报告类型 | URL 模板 |
+|------|---------|---------|
+| Google | 日报（Daily） | `{webUrl}/media-report/publish/{entityId}?culture=zh-CN` |
+| Google | 小时报（Hourly） | `{webUrl}/media-report/hour/{entityId}?culture=zh-CN` |
+| TikTok | 日报 | `{webUrl}/media-report/publish/{entityId}?culture=zh-CN` |
+
+- `entityId` 来自 `siluzan-tso report list --json` 结果中每条记录的 `entityId` 字段
+- `webUrl` 示例：`https://www-ci.siluzan.com`（测试环境）或 `https://www.siluzan.com`（生产环境）
+
+```bash
+# 完整示例（Google 日报）
+siluzan-tso report list -m Google --json
+# 找到 entityId 后拼接：
+# https://www-ci.siluzan.com/media-report/publish/<entityId>?culture=zh-CN
+```
+
+---
+
+### recharge — 充值业务
+
+充值业务分为两类：**CLI 已实现**的可直接调用命令；**CLI 未实现**的需引导用户打开对应网页操作。
+
+#### 如何获取 Web 页面基地址
+
+```bash
+siluzan-tso config show
+# 输出中 webUrl 行即为前端基地址，例如：
+#   webUrl : https://www.siluzan.com        （生产环境）
+#   webUrl : https://www-ci.siluzan.com     （测试环境）
+```
+
+> 规律：将 `apiBaseUrl` 中的 `tso-api` 替换为 `www` 即得 `webUrl`。
+
+#### 充值功能总览
+
+| 功能 | 对应页面路径 | CLI 支持 |
+|------|-------------|----------|
+| 现金充值（单笔） | `/recharge/pay` | ❌ 引导网页 |
+| 现金充值（批量） | `/recharge/pay_batch` | ❌ 引导网页 |
+| 月结充值 | `/recharge/accountBillingQuota` | ❌ 引导网页 |
+| 丝路赞钱包（充值/提现/明细） | `/recharge/siluzanWallet` | ❌ 引导网页 |
+| 媒体转账记录 | `/recharge/accountTransfer` | ✅ `transfer` 命令 |
+| 开票记录 | `/recharge/invoiceList` | ✅ `invoice list` |
+| 开票申请列表 | `/recharge/invoicingApplicationList` | ✅ `invoice billable` / `invoice apply` |
+
+#### 引导用户跳转的标准话术
+
+当用户询问现金充值、月结充值或钱包相关操作时，先通过 `siluzan-tso config show` 获取 `webUrl`，再给出完整链接：
+
+```
+需要进行充值，请访问丝路赞平台对应页面完成操作：
+
+- 现金充值（单笔）：{webUrl}/recharge/pay
+- 现金充值（批量）：{webUrl}/recharge/pay_batch
+- 月结充值：        {webUrl}/recharge/accountBillingQuota
+- 丝路赞钱包：      {webUrl}/recharge/siluzanWallet
+```
+
+---
+
+### transfer — 媒体转账记录
+
+```bash
+siluzan-tso transfer -m <媒体> [选项]
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-m, --media` | 媒体类型（必填）：`Google \| TikTok \| MetaAd \| BingV2` |
+| `-n, --number <no>` | 转账单号 |
+| `-s, --status <status>` | 到账状态 |
+| `--start / --end` | 日期范围 |
+
+```bash
+siluzan-tso transfer -m Google
+siluzan-tso transfer -m TikTok --start 2026-03-01 --json
+```
+
+---
+
+### invoice — 开票管理
+
+#### 开票申请记录
+
+```bash
+siluzan-tso invoice list [选项]
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-k, --keyword` | 发票号/关键字 |
+| `--start / --end` | 日期范围 |
+
+```bash
+siluzan-tso invoice list
+siluzan-tso invoice list --start 2026-03-01 --json
+```
+
+#### 可开票订单列表
+
+```bash
+siluzan-tso invoice billable [选项]
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-m, --media` | 媒体类型 |
+| `-c, --currency <code>` | 币种，如 `USD \| CNY` |
+| `--wallet` | 查询钱包充值可开票记录 |
+| `--start / --end` | 日期范围 |
+
+```bash
+siluzan-tso invoice billable -m Google -c USD
+siluzan-tso invoice billable --wallet
+```
+
+#### 提交开票申请
+
+```bash
+siluzan-tso invoice apply \
+  --bill-ids "id1,id2" \
+  --bill-type AmountAccount \
+  --invoice-info '{"invoiceTitle":"...","taxNo":"..."}' \
+  --recipient-info '{"name":"...","address":"...","phone":"..."}'
+```
+
+---
+
+### ai-creation — AI智投记录
+
+对应页面：`/advertising/AICreationList`（AI智投记录列表）
+
+#### 子命令总览
+
+| 子命令 | 说明 |
+|--------|------|
+| `list` | 查询 AI 智投记录列表 |
+| `get --id <id>` | 获取单条记录/草稿详情（JSON 输出） |
+| `update --id <id>` | 更新草稿字段（预算/推广链接/系列名称）后保存 |
+| `publish --id <id>` | 发布草稿（Draft → 提交 Google 异步创建） |
+
+#### list — 查询列表
+
+```bash
+siluzan-tso ai-creation list [选项]
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-s, --state <state>` | 状态：`Creating \| Successfully \| Failed \| HasFailed \| Unpublished` |
+| `--customer-id <id>` | 客户 mediaCustomerId |
+| `--customer-name <name>` | 客户名称 |
+| `-k, --keyword <text>` | 关键字 |
+| `--start / --end <date>` | 创建日期范围（YYYY-MM-DD） |
+| `-p, --page <n>` | 页码（默认 1） |
+| `--page-size <n>` | 每页数量（默认 20） |
+| `--json` | 输出原始 JSON |
+
+```bash
+siluzan-tso ai-creation list
+siluzan-tso ai-creation list --customer-id 6326027735
+siluzan-tso ai-creation list --state Failed --json
+```
+
+#### get — 获取详情
+
+```bash
+siluzan-tso ai-creation get --id <recordId>
+```
+
+#### update — 更新草稿
+
+```bash
+siluzan-tso ai-creation update --id <recordId> [选项]
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--budget <amount>` | 新预算（最小货币单位，如 `8500` = 85元 CNY） |
+| `--url <url>` | 新推广链接 |
+| `--campaign-name <name>` | 新广告系列名称 |
+
+> 只有 `draftStatus === "Draft"` 的记录可更新。
+
+```bash
+siluzan-tso ai-creation update --id <id> --campaign-name "新名称" --url "https://example.com"
+```
+
+#### publish — 发布草稿
+
+```bash
+siluzan-tso ai-creation publish --id <recordId>
+```
+
+> 只有 `draftStatus === "Draft"` 的记录可发布；发布后状态变为 `Creating`，Google 后台异步执行创建。
+
+---
+
+### optimize — AI广告优化
+
+```bash
+siluzan-tso optimize list [选项]       # 账户级优化主列表
+siluzan-tso optimize records [选项]    # 优化记录列表
+siluzan-tso optimize children --parent-id <id>  # 广告系列级明细
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-a, --account <id>` | 账户 mediaCustomerId |
+| `--start / --end` | 日期范围（格式 YYYY-MM-DD，自动附加 +08:00） |
+
+```bash
+siluzan-tso optimize list -a 1234567890
+siluzan-tso optimize records --start 2026-03-01 --json
+siluzan-tso optimize children --parent-id <id>
+```
+
+---
+
+### clue — 广告线索表单
+
+对应页面：`/clue-form`。支持 **TikTok** 和 **Meta（Facebook）** 两种媒体的广告线索数据查询。
+
+> **注意**：线索数据由 TikTok/Meta API 直接返回，**不支持服务端分页**，数据量大时建议配合 `--json` 导出后自行处理。
+
+```bash
+# 查询 TikTok 线索（全部区域）
+siluzan-tso clue -m TikTok -a <advertiserId>
+
+# 只查欧洲区线索
+siluzan-tso clue -m TikTok -a <advertiserId> --region eu
+
+# 查询 Meta 线索（指定日期范围）
+siluzan-tso clue -m Meta -a <pageId> --start 2026-03-01 --end 2026-03-31
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-m, --media` | `TikTok \| Meta`（默认 TikTok） |
+| `-a, --account <id>` | TikTok：`advertiserId`（mediaCustomerId）；Meta：Facebook 页面 ID | 
+| `--region <region>` | TikTok 专用：`eu \| us \| other \| ALL`（默认 ALL） |
+| `--start <date>` | Meta 专用：开始日期（YYYY-MM-DD） |
+| `--end <date>` | Meta 专用：结束日期（YYYY-MM-DD） |
+| `--json` | 输出原始 JSON |
+
+**输出字段说明（TikTok）**
+
+- 姓名、邮箱、手机（来自 `custom_fields`）
+- 表单名、广告名、区域、时间（来自 `system_fields`）
+
+**输出字段说明（Meta）**
+
+- 姓名、邮箱、手机（来自 `field_Data`）
+- 表单名、创建时间
+
+---
+
+### forewarning — 智能预警
+
+```bash
+siluzan-tso forewarning list -m <媒体> [选项]      # 规则列表
+siluzan-tso forewarning records -m <媒体> [选项]   # 预警触发记录
+siluzan-tso forewarning start -m <媒体> --id <id>  # 启动规则
+siluzan-tso forewarning stop  -m <媒体> --id <id>  # 停止规则
+siluzan-tso forewarning delete -m <媒体> --id <id> # 删除规则
+```
+
+规则列表选项：
+
+| 选项 | 说明 |
+|------|------|
+| `-m, --media` | 媒体类型（必填）：`Google \| TikTok` |
+| `-a, --account <id>` | 账户 ID 筛选 |
+| `-k, --keyword` | 规则名称关键字 |
+| `--start / --end` | 日期范围 |
+
+预警记录额外选项：
+
+| 选项 | 说明 |
+|------|------|
+| `-r, --rule-id <id>` | 规则 ID（留空查全部） |
+| `-s, --status <result>` | 执行结果筛选 |
+
+```bash
+siluzan-tso forewarning list -m Google
+siluzan-tso forewarning records -m TikTok --start 2026-03-01
+siluzan-tso forewarning stop -m Google --id <ruleId>
+```
+
+#### 创建预警规则（自定义类型）
+
+```bash
+siluzan-tso forewarning create \
+  -m Google \
+  --name "消费超限预警" \
+  --accounts "<entityId1>,<entityId2>" \
+  --field cost \
+  --operator GREATER_EQUALS \
+  --value 500 \
+  --days 1 \
+  --frequency QuarterHour \
+  --notify "<notifyEntityId>"
+```
+
+| 选项 | 说明 | 必填 |
+|------|------|------|
+| `-m, --media` | `Google \| TikTok` | ✅ |
+| `--name` | 规则名称 | ✅ |
+| `--accounts <ids>` | 监控账户 entityId，逗号分隔 | ✅ |
+| `--field <field>` | 监控指标（见下表） | ✅ |
+| `--operator <op>` | 比较运算符（见下表） | ✅ |
+| `--value <n>` | 阈值（数字） | ✅ |
+| `--scope <type>` | 层级：`Campaign \| AdGroup \| Ad`（默认 `Campaign`） | |
+| `--days <n>` | 统计周期（天）：`1 \| 3 \| 7`（默认 1） | |
+| `--frequency <freq>` | 检查频率：`QuarterHour \| HalfHour \| Hour` | |
+| `--notify <ids>` | 通知账户 entityId，逗号分隔 | |
+
+**监控指标（--field）**
+
+| 媒体 | 可选值 |
+|------|--------|
+| Google | `cost` `CPA` `CPM` `CPC` `conversions_count` `conversions_rate` `valid_click_count` `ctr` |
+| TikTok | `spend` `cpc` `cpm` `cost_per_conversion` `conversion` `ctr` `clicks` `result` `result_rate` |
+
+**比较运算符（--operator）**
+
+`GREATER_EQUALS`（≥）、`GREATER`（>）、`LESS_EQUALS`（≤）、`LESS`（<）、`EQUALS`（=）
+
+#### 更新预警规则
+
+```bash
+siluzan-tso forewarning update \
+  -m Google \
+  --id <ruleEntityId> \
+  --name "新名称" \
+  --accounts "<entityId>" \
+  --field cost --operator LESS_EQUALS --value 200
+```
+
+与 `create` 参数相同，额外必填 `--id`（规则 entityId）。
+
+#### 查看单条规则详情（编辑前用于获取当前配置）
+
+```bash
+siluzan-tso forewarning get -m Google --id <ruleEntityId>
+```
+
+---
+
+### account — 账号管理（授权 / 断开关联 / 分享）
+
+#### 添加授权（OAuth 绑定新账户）
+
+```bash
+siluzan-tso account auth -m Google    # 打开 Google Ads OAuth 授权页
+siluzan-tso account auth -m TikTok    # 打开 TikTok Ads OAuth 授权页
+siluzan-tso account auth -m Meta      # 打开 Facebook Ads OAuth 授权页
+siluzan-tso account auth -m Yandex
+siluzan-tso account auth -m BingV2
+siluzan-tso account auth -m Kwai
+```
+
+执行后 CLI 会自动在**系统默认浏览器**中打开对应媒体的 OAuth 授权页面；无法打开浏览器时输出链接供手动粘贴。用户在浏览器中完成授权后会自动跳回丝路赞回调页面，账户绑定即时生效。
+
+#### 断开关联 / 分享
+
+```bash
+siluzan-tso account delink --id <entityId>                          # 断开单个账户关联
+siluzan-tso account delink --ids <id1,id2,id3>                     # 批量断开
+siluzan-tso account share --id <entityId> --phone <手机号>          # 分享 Google 账户给指定用户
+siluzan-tso account unshare --id <entityId> --account-id <userId>  # 取消分享
+siluzan-tso account share-detail --customer-id <mediaCustomerId>   # 查看分享详情
+```
+
+- `--id` / `--ids` 中的 ID 是 `entityId`（来自 `list-accounts --json` 中 `ma.entityId` 字段），**不是** `mediaCustomerId`
+- `account share` 只支持 Google 账户；手机号必须已在丝路赞注册
+- `account share-detail --customer-id` 传的是 `mediaCustomerId`（数字型账户 ID）
+
+---
+
+### open-account — 开户申请
+
+#### 第一步：查询广告主组，取 magKey
+
+```bash
+siluzan-tso open-account list-groups
+```
+
+所有开户命令都需要 `--advertiser-id <magKey>`。
+
+#### Google 开户（无需图片）
+
+```bash
+siluzan-tso open-account google \
+  --advertiser-id <magKey> \
+  --account-name "我的广告账户" \
+  --currency USD \
+  --timezone "Asia/Hong_Kong" \
+  --invite-email "xxx@company.com" \
+  --company "公司名称" \
+  --industry1 "科技" \
+  --industry2 "互联网服务" \
+  --promotion-link "https://example.com" \
+  --promotion-type b2b
+```
+
+| 选项 | 说明 | 必填 |
+|------|------|------|
+| `--advertiser-id` | 广告主组 magKey | ✅ |
+| `--account-name` | 账户名称（≤22字符） | ✅ |
+| `--currency` | 货币：`USD \| CNY` | ✅ |
+| `--timezone` | 时区，如 `Asia/Hong_Kong` | ✅ |
+| `--invite-email` | 受邀邮箱（`.com` 结尾） | ✅ |
+| `--company` | 公司名称 | ✅ |
+| `--industry1 / --industry2` | 行业一/二级 | ✅ |
+| `--promotion-link` | 推广链接 | ✅ |
+| `--promotion-type` | `b2b \| b2c \| app` | ✅ |
+| `--invite-role` | `Standard \| Admin`（默认 Standard） | |
+| `--counts` | 开户数量 1-3（默认 1） | |
+
+#### TikTok 开户（需要营业执照图片）
+
+```bash
+siluzan-tso open-account tiktok \
+  --advertiser-id <magKey> \
+  --account-name "我的TT账户" \
+  --currency USD \
+  --timezone "UTC+8" \
+  --company "公司名称" \
+  --industry-id 159141 \
+  --registered-area CN \
+  --promotion-link "https://example.com" \
+  --license-no "91xxxxxx" \
+  --license-file "/path/to/license.jpg"
+```
+
+> CLI 自动完成：① 上传图片到 TikTok → 获取 `license_image_id`；② 存档到 Siluzan；③ 检查是否需要法人银联验证。  
+> 若需要银联验证，追加：`--representative-name 李xx --representative-id 身份证号 --unionpay-account 银联号 --representative-phone 手机号`
+
+#### Yandex 开户（无需图片）
+
+```bash
+siluzan-tso open-account yandex \
+  --advertiser-id <magKey> \
+  --login "yandex_login_name" \
+  --first-name "名" --last-name "姓" \
+  --email "xxx@company.com" \
+  --tin "税号" \
+  --phone "+8618800000000"
+```
+
+#### Bing/BingV2 开户（需要营业执照图片）
+
+```bash
+siluzan-tso open-account bing \
+  --advertiser-id <magKey> \
+  --advertiser-name "公司全称" \
+  --name-short "简称" \
+  --province "广东省" --city "深圳市" \
+  --address "详细地址" \
+  --promotion-link "https://example.com" \
+  --trade-id "1001" \
+  --license-file "/path/to/license.jpg"
+```
+
+#### Kwai 开户（需要营业执照图片）
+
+```bash
+siluzan-tso open-account kwai \
+  --advertiser-id <magKey> \
+  --licence-id "91xxxxxx" \
+  --licence-country CN \
+  --licence-location "广东省深圳市xx路xx号" \
+  --business-scope "电商零售" \
+  --product "品牌名称" \
+  --ad-type 1 \
+  --product-url "https://example.com" \
+  --licence-id-type ENTERPRISE \
+  --account-name "账户名称" \
+  --company-name "公司名称" \
+  --industry-id1 "1234" --industry-id2 "5678" \
+  --expire-type 2 \
+  --target-country US \
+  --license-file "/path/to/license.jpg"
+```
+
+> `--ad-type`：`1`=效果广告，`2`=品牌广告  
+> `--expire-type`：`1`=有限期（需追加 `--expire-at <毫秒时间戳>`），`2`=长期有效
+
+---
+
+### ad — Google 广告管理
+
+> 需要先配置 Google API 地址：`siluzan-tso config set --google-api <URL>`
+
+```bash
+siluzan-tso ad campaigns -a <accountId> [--start <date>] [--end <date>]   # 广告系列列表
+siluzan-tso ad groups    -a <accountId>                                     # 广告组列表
+siluzan-tso ad list      -a <accountId>                                     # 广告列表
+siluzan-tso ad keywords  -a <accountId>                                     # 关键词列表
+siluzan-tso ad keywords  -a <accountId> --negative                          # 否定关键词列表
+```
+
+所有子命令均支持 `--json` 输出。
+
+```bash
+siluzan-tso ad campaigns -a 1234567890 --start 2026-03-01 --end 2026-03-31
+siluzan-tso ad keywords -a 1234567890 --json
+```
+
+---
+
+### keyword — 关键字推荐
+
+> 需要先配置 Google API 地址：`siluzan-tso config set --google-api <URL>`
+
+```bash
+siluzan-tso keyword -k <搜索词> [选项]
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-k, --keyword <words>` | 搜索词，多个逗号分隔（必填） |
+| `--url <url>` | 公司/产品网址，填写后触发「网址拓词 + 轮询」流程 |
+| `--include <words>` | 结果必须包含的词（逗号或空格分隔，本地过滤） |
+| `--exclude <words>` | 结果不包含的词（本地过滤） |
+
+```bash
+siluzan-tso keyword -k "running shoes,sports"
+siluzan-tso keyword -k "跑步" --url "https://example.com" --exclude "kids,cheap"
+siluzan-tso keyword -k "coffee" --json
+```
+
+---
+
+## AI 行为规范
+
+1. **先查账户再操作**：对具体账户做操作前，先通过 `list-accounts` 确认账户 ID。
+2. **使用 --json 处理数据**：需要对返回数据做计算或筛选时，加 `--json` 输出 JSON。
+3. **不要猜测账户 ID**：账户 ID 必须来自 `list-accounts` 的输出。
+4. **媒体类型区分大小写**：如 `Google`、`TikTok`、`MetaAd`、`BingV2`、`Kwai`，不要用小写。
+5. **Google 专属命令前置检查**：使用 `ad` 或 `keyword` 命令前，先用 `config show` 确认 `googleApiUrl` 已配置；若未配置，引导用户执行 `siluzan-tso config set --google-api <URL>`。
+6. **时区说明**：所有日期按北京时间（UTC+8），`optimize` 命令会自动附加 `+08:00`。
+7. **分页说明**：默认每页 20 条，数据量大时可增加 `--page-size 100` 或翻页查询。