# Siluzan TSO Skill — 给大模型的安装说明

当用户发来本页面的 **URL** 时，请按顺序协助用户完成安装。

## 0. 安全与透明性说明

本 Skill 是 **instruction-only**（纯指令型），不包含可执行代码文件。它通过指导 AI 助手调用 `siluzan-tso` CLI 来操作丝路赞广告管理平台。

### 运行时依赖

| 项目                   | 说明                                     |
| ---------------------- | ---------------------------------------- |
| **Node.js 18+**        | CLI 运行时                               |
| **npm 8+** 或 **pnpm** | 安装 CLI 全局包                          |
| **siluzan-tso** CLI    | 由 `npm install -g siluzan-tso-cli` 安装 |

### 凭据与网络

| 项目            | 说明                                                   |
| --------------- | ------------------------------------------------------ |
| API Key / Token | 存储在 `~/.siluzan/config.json`，用于所有 API 调用鉴权 |
| 前端页面        | `www.siluzan.com`（充值、激活等浏览器操作）            |
| 错误追踪        | `o605862.ingest.us.sentry.io`（匿名崩溃日志）          |
| 版本检查        | `registry.npmjs.org`                                   |

### 可执行的操作范围

- **只读**：查询账户列表、余额、消耗数据、报告、预警记录等
- **写入**（需用户确认）：创建/修改/发布广告、开户申请、创建预警规则、报告推送配置
- **破坏性**（必须用户确认）：账户解绑/关闭、MCC/BC 解绑、删除预警/报告/广告、发票申请

### 报告模板外部资源

HTML 报告模板外部资源：**ECharts** 统一使用 `https://staticpn.siluzan.com/assets/slz/homeCDN/echarts.js`；其余样式/脚本可能引用 `cdn.tailwindcss.com`、`cdnjs.cloudflare.com`、`fonts.googleapis.com` 等。

## 1. 环境

- Node.js **18+**
- 可执行 `npm` 或 `pnpm`

## 2. 安装 CLI 并初始化 Skill

在**用户的目标项目根目录**执行（根据用户使用的助手选择 `--ai`）：

```bash
npm install -g siluzan-tso-cli@beta
siluzan-tso init --ai cursor         # 写入 Cursor（默认）
siluzan-tso init --ai cursor,claude  # 同时写入多个平台
siluzan-tso init --ai all            # 写入所有支持的平台
siluzan-tso init -d /path/to/skills  # 写入自定义目录
siluzan-tso init --force             # 强制覆盖已存在文件
```

> **注意**：当前为测试版（1.1.29-beta.15），供内部测试使用。正式发布后安装命令将改为 `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`                                |

## 3. 登录 / 鉴权

`siluzan-tso` 与 `siluzan-cso` **共用同一个凭据**（存储在 `~/.siluzan/config.json`）。

**若用户已安装 `siluzan-cso` 并完成登录，无需重复操作，直接跳到第 4 步。**

**推荐顺序**：① **手机号 + 验证码**（首选）完整参数与排错见 `references/core/setup.md`（随 Skill 安装到本地）。

### 方式 A：手机号 + 验证码（**推荐**）

```bash
siluzan-tso send-login-code --phone <手机号>
siluzan-tso login --phone <手机号> --code <6位验证码>
```

不向终端索要交互输入；Agent 先发码、用户回填验证码后再执行第二步。手机号须已在丝路赞注册。

### 方式 B：交互式登录（需真人 TTY）

```bash
siluzan-tso login
```

按提示访问丝路赞控制台「个人设置 → API Key 管理」页面创建 API Key 后粘贴到终端，自动保存。也可跳过交互直接传入：

```bash
siluzan-tso login --api-key <YOUR_API_KEY>
```

### 方式 C：直接设置（适合自动化场景）

```bash
siluzan-tso config set --api-key <你的ApiKey>
```

### 方式 D：Token 登录（已有 siluzan-cso 账号）

```bash
npm install -g siluzan-cso-cli
siluzan-cso login
```

向导会提示用户访问 [https://www.siluzan.com](https://www.siluzan.com) 注册登录，在「个人设置 → API Token」页面复制 Token 粘贴到命令行，自动保存后 `siluzan-tso` 会读取该 Token。

提醒用户：**不要将 Token / API Key 提交到 Git。**

## 4. 验证

确认以下路径已存在且含 `SKILL.md` 和 `_meta.json`：

| 助手             | Skill 文件路径                             |
| ---------------- | ------------------------------------------ |
| Cursor           | `.cursor/skills/siluzan-tso/SKILL.md`      |
| Claude Code      | `.claude/skills/siluzan-tso/SKILL.md`      |
| OpenClaw 工作区  | `skills/siluzan-tso/SKILL.md`              |
| OpenClaw 全局    | `~/.openclaw/skills/siluzan-tso/SKILL.md`  |
| WorkBuddy 项目级 | `.workbuddy/skills/siluzan-tso/SKILL.md`   |
| WorkBuddy 全局   | `~/.workbuddy/skills/siluzan-tso/SKILL.md` |

完成后，用户可在对话中描述广告账户管理需求（查账户、查余额、查消耗、充值、开户、绑定 MCC/BC/BM、管理 Google 广告等），由已加载的 Skill 指导 `siluzan-tso` CLI 的使用方式。

## 5. 更新

CLI 在每次命令执行后会静默检查是否有新版本可用，有更新时会提示：

```
💡 发现新版本 x.x.x（测试版），运行以下命令升级：
   npm install -g siluzan-tso-cli@beta
```

**发现提示后，Agent 应主动执行以下两步完成升级：**

```bash
# 第一步：升级 CLI
{{INSTALL_CMD}}

# 第二步：用新版 CLI 重新写入 Skill 文件（--force 覆盖旧版）
siluzan-tso init --ai xxx --force
```

> `--ai` 参数换成实际使用的平台（如 `claude`、`openclaw-global` 等）。
> 若不确定当前安装在哪个平台，可查看 `~/.siluzan/config.json` 中的 `tsoInstalledTargets` 字段。

## 6. Token 续期

Token 过期后：**优先**再走一遍**方式 A**（手机验证码）签发新 API Key；或 `siluzan-cso login` / `siluzan-tso config set --api-key <新Key>`，`siluzan-tso` 自动读取新凭据。
