siluzan-tso-cli 1.0.0-beta.10

package/README.md

@@ -0,0 +1,66 @@
+# Siluzan TSO Skill — 给大模型的安装说明
+
+当用户发来本页面的 **URL** 时，请按顺序协助用户完成安装（不要编造不存在的 npm 包名；若公司尚未发布，请改用用户提供的 Git 地址或本地 `tso-cli` 路径）。
+
+## 1. 环境
+
+- Node.js **18+**
+- 可执行 `npm` 或 `pnpm`
+
+## 2. 安装 CLI 并初始化 Skill
+
+在**用户的目标项目根目录**执行（根据用户使用的助手选择 `--ai`）：
+
+```bash
+npm install -g siluzan-tso-cli@beta
+siluzan-tso init --ai cursor
+```
+
+> **注意**：当前为测试版（1.0.0-beta.10），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
+
+| 助手 | 建议 `--ai` |
+|------|-------------|
+| Cursor | `cursor` |
+| Claude Code | `claude` |
+| OpenClaw（项目内技能） | `openclaw` 或 `openclaw-workspace` |
+| OpenClaw（全局技能） | `openclaw-global` |
+| WorkBuddy（项目内技能） | `workbuddy` 或 `workbuddy-workspace` |
+| WorkBuddy（全局技能） | `workbuddy-global` |
+| 一次写入多处 | `all` |
+
+若 CLI 未发布：指导用户在克隆的仓库根目录执行 `npm install && npm run build`，再 `node tso-cli/dist/index.js init --ai cursor`。
+
+## 3. 登录 / Token
+
+`siluzan-tso` 与 `siluzan-cso` **共用同一个 Token**（存储在 `~/.siluzan/config.json`）。
+
+**若用户已安装 siluzan-cso 并完成登录，无需重复操作，直接跳到第 4 步。**
+
+若尚未登录，请先安装 `siluzan-cso-cli` 并完成登录：
+
+```bash
+npm install -g siluzan-cso-cli
+siluzan-cso login
+```
+
+向导会在终端中提示用户访问 [https://www.siluzan.com](https://www.siluzan.com) 注册登录，然后在控制台的「个人设置 → API Token」页面复制 Token，粘贴到命令行提示处，自动保存到 `~/.siluzan/config.json`，后续 `siluzan-tso` 命令自动读取。
+
+提醒用户：**不要将 Token 提交到 Git。**
+
+## 4. 验证
+
+确认以下路径已存在且含 `SKILL.md`：
+
+| 助手 | Skill 文件路径 |
+|------|----------------|
+| Cursor | `.cursor/skills/siluzan-tso/SKILL.md` |
+| Claude Code | `.claude/skills/siluzan-tso/SKILL.md` |
+| OpenClaw 工作区 | `skills/siluzan-tso/SKILL.md` |
+| WorkBuddy 项目级 | `.workbuddy/skills/siluzan-tso/SKILL.md` |
+| WorkBuddy 全局 | `~/.workbuddy/skills/siluzan-tso/SKILL.md` |
+
+完成后，用户可在对话中描述广告账户管理需求（查账户、查余额、查消耗、充值、绑定 MCC/BC/BM 等），由已加载的 Skill 指导 `siluzan-tso` CLI 使用方式。
+
+## 5. Token 续期
+
+Token 过期后，重新运行 `siluzan-cso login` 即可更新，`siluzan-tso` 会自动读取新 Token，无需额外操作。

package/assets/siluzan-ads/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: siluzan-tso
+description: >-
+  Use when the user needs to manage advertising on the Siluzan TSO platform:
+  querying ad accounts / balance / spend data, opening new ad accounts
+  (Google / TikTok / Yandex / Bing / Kwai), managing Google ad campaigns /
+  groups / creatives / keywords (full CRUD), generating optimization reports,
+  managing media transfers or invoices, viewing AI creation records and
+  intelligent alerts, querying lead forms (TikTok / Meta), or running any
+  AIGC ad-plan preparation workflow.
+  Do NOT use for content publishing (videos / images) — use siluzan-cso instead.
+---
+
+# Siluzan TSO Skill
+
+通过 `siluzan-tso` CLI 完成广告投放管理，不要手动调接口。
+
+登录与配置详见 `references/setup.md`。
+
+---
+
+## 参考文档导航
+
+| 文档 | 内容 |
+|------|------|
+| `references/workflows.md` ⭐ | **多命令组合流程**（优先读取） |
+| `references/tips.md` | **`--json` + Node.js 精准查询技巧**（过滤 / 提取 / 多步串联） |
+| `references/accounts.md` | 账户查询 / 余额 / 消耗 / 开户 / 账号管理 |
+| `references/open-account-google-ui.md` | **Google 开户**：网页五步 + 两步表单与 CLI 对照（向导/时区列表） |
+| `references/open-account-by-media.md` | **各媒体开户差异**：路由、所需资料、接口路径与 CLI 对照（Google/TikTok/Yandex/Bing/Kwai） |
+| `references/google-ads.md` | Google 广告 CRUD（系列 / 组 / 创意 / 关键词） |
+| `references/google-ads-test.md` | Google 广告业务矩阵与 Agent 测试 |
+| `references/aigc.md` | AIGC 广告方案数据准备（`aigc prepare`）及落地流程 |
+| `references/reporting.md` | 报告 / AI 智投 / 优化 / 预警 / 线索 |
+| `references/finance.md` | 转账 / 发票（充值需网页） |
+| `references/tso-home.md` | TSO 首页看板页面与 CLI 对照 |
+| `references/setup.md` | 安装 / 登录 / 配置 / 环境切换 |
+
+---
+
+## 业务流程速查
+
+| 场景 | 参考 |
+|------|------|
+| 开通新广告账户（Google/TikTok/Bing/Kwai/Yandex） | `references/workflows.md` 流程一 |
+| AI 智投草稿 → 发布 Google 广告 | `references/workflows.md` 流程二 |
+| 手动搭建 Google 广告（系列→组→词→广告） | `references/workflows.md` 流程三 |
+| 查看 AI 优化建议并执行 | `references/workflows.md` 流程四 |
+| 创建/管理智能预警规则 | `references/workflows.md` 流程五 |
+| 生成报告 → 设置推送 → 获取查看链接 | `references/workflows.md` 流程六 |
+| 开票申请完整流程 | `references/workflows.md` 流程七 |
+| 定期拉取 TikTok/Meta 广告线索 | `references/workflows.md` 流程八 |
+| 账户分享 / OAuth 重授权 / 解绑 | `references/workflows.md` 流程九 |
+| 日/周消耗数据巡检 | `references/workflows.md` 流程十 |
+| 媒体转账到账核查 | `references/workflows.md` 流程十一 |
+| TSO 首页看板 CLI 巡检 | `references/workflows.md` 流程十二 + `references/tso-home.md` |
+| AIGC 广告方案生成（全 CLI） | `references/workflows.md` 流程十三 |
+| 网站诊断与落地页评估 | `references/workflows.md` 流程十四 |
+| 账户管理（关闭/BM绑定/BC绑定/激活/邮箱） | `references/workflows.md` 流程十五 |
+
+---
+
+## 常用命令速查
+
+| 场景 | 命令 |
+|------|------|
+| 首次登录 | `siluzan-tso login` |
+| 查看配置 | `siluzan-tso config show` |
+| 查询广告账户 | `siluzan-tso list-accounts -m Google` |
+| 查询账户余额 | `siluzan-tso balance -m Google -a <mediaCustomerId>` |
+| 查询投放数据 | `siluzan-tso stats -m Google -a <mediaCustomerId>` |
+| TSO 首页（网页） | `config show` 取 `webUrl` → `{webUrl}/v3/foreign_trade/tso/home` |
+| 查广告主组（TikTok 等取 magKey） | `siluzan-tso open-account list-groups` |
+| Google 开户（交互，推荐） | `siluzan-tso open-account google-wizard`（对齐 `/openAnAccount` 五步说明 + 两步表单） |
+| Google 开户（脚本） | `siluzan-tso open-account google --company "…" --promotion-link "…" --promotion-type b2c ...`（**无需 magKey**） |
+| Google 开户时区列表 | `siluzan-tso open-account google-timezones`（与网页下拉同源，可加 `--keyword`） |
+| TikTok 开户时区列表 | `siluzan-tso open-account tiktok-timezones`（可加 `--keyword`） |
+| TikTok 行业列表 | `siluzan-tso open-account tiktok-industries`（两级结构，传叶子节点 ID） |
+| TikTok 注册地列表 | `siluzan-tso open-account tiktok-areas`（`--registered-area` 的合法值） |
+| TikTok 开户 | `siluzan-tso open-account tiktok --advertiser-id <magKey> ...` |
+| BingV2 行业列表 | `siluzan-tso open-account bing-industries`（`--trade-id` 的合法值） |
+| 查询 Google 被封账户（可提现） | `siluzan-tso account withdraw-list` |
+| 提交 Google 被封账户提现申请 | `siluzan-tso account withdraw-submit --accounts <entityId>`（**仅 Google**） |
+| 添加 OAuth 授权 | `siluzan-tso account auth -m Google` |
+| 解除授权 / 解绑 | `siluzan-tso account delink --id <entityId>` |
+| Google MCC 绑定 | `siluzan-tso account mcc-bind --customers <mediaCustomerId> --mcc <MCC客户ID>` |
+| Google MCC 解绑 | `siluzan-tso account mcc-unbind --customers <mediaCustomerId> --mcc <MCC客户ID>` |
+| 账号分享 | `siluzan-tso account share --id <entityId> --phone <手机号>` |
+| TikTok 关闭账户 | `siluzan-tso account close --accounts <mediaCustomerId>` |
+| Meta BM 绑定 | `siluzan-tso account bm-bind --account-id <mediaCustomerId> --bm-id <bmId>` |
+| TikTok BC 绑定 | `siluzan-tso account bc-bind --customers <mediaCustomerId> --bc-ids <bcId>` |
+| TikTok BC 解绑 | `siluzan-tso account bc-unbind --customers <mediaCustomerId> --bc-id <bcId>` |
+| Google 账户激活（网页） | `{webUrl}/v3/foreign_trade/tso/manageAccounts` |
+| AIGC 方案数据准备 | `siluzan-tso aigc prepare -a <accountId> --url <url> -w "词1,词2"`（详见 `references/aigc.md`） |
+| 优化报告列表 | `siluzan-tso report list -m Google` |
+| 充值 / 钱包（网页） | 见 `references/finance.md` |
+| 媒体转账记录 | `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` |
+| Google 广告系列列表 | `siluzan-tso ad campaigns -a <accountId>` |
+| Google 广告组创建 | `siluzan-tso ad adgroup-create -a <accountId> --campaign-id <id> ...` |
+| Google 关键字推荐 | `siluzan-tso keyword -k "running shoes"` |
+| Google 搜索字词报告 | `siluzan-tso ad search-terms -a <accountId> [--start YYYY-MM-DD] [--end YYYY-MM-DD]`（**仅 Google**，只读） |
+
+---
+
+## AI 行为规范
+
+- **先查账户再操作**：对具体账户做操作前，先通过 `list-accounts` 确认 ID。
+- **使用 --json 处理数据**：需对返回数据做计算或筛选时，加 `--json`，再用 `node -e` 过滤提取（见 `references/tips.md`）。
+- **不要猜测账户 ID**：`entityId` ≠ `mediaCustomerId`，两者均来自 `list-accounts`。
+- **媒体类型区分大小写**：`Google`、`TikTok`、`MetaAd`、`BingV2`、`Kwai`。
+- **Google 网关**：使用 `ad`、`keyword`、`account mcc-*` 前，先 `config show` 确认 `googleApiUrl` 已配置。
+- **时区**：所有日期按北京时间（UTC+8），`optimize` 命令自动附加 `+08:00`。
+- **分页**：默认每页 20 条，数据量大时加 `--page-size 100` 或 `--page` 翻页。
+- **充值等网页操作**：先 `config show` 取 `webUrl`，再拼路径引导用户。
+- **Google 新开户**：终端用户优先建议 `open-account google-wizard`；说明网页「五步」里**充值激活**必须网页完成。详见 `references/open-account-google-ui.md`。
+- **不确定时读文档**：遇到不熟悉的命令，先读对应 references 文件，不要猜参数。