siluzan-tso-cli 1.1.21 → 1.1.22-beta.3

package/dist/skill/references/core/agent-conventions.md

@@ -0,0 +1,180 @@
+# Agent 执行规范
+
+> 本文件定义 siluzan-tso Skill 下 **AI 助手必须遵守** 的加载纪律、执行流程与硬规范。  
+> CLI 参数细节见各功能 reference；标准任务步骤见 `references/core/playbooks.md`。
+
+---
+
+## 文档加载纪律
+
+本 Skill 采用 **SKILL 路由 + references 按需加载**；**「按需」= 每个用户任务都要按需，不是整段对话只读一次**。
+
+### 何时必须 Read references
+
+| 触发 | 动作 |
+| ---- | ---- |
+| **新的用户任务**（新需求、新账户、新媒体、新报告类型） | 用 `SKILL.md`「任务 → 文档」表确定路径，**Read 全部必读项**后再计划/执行 CLI |
+| **同一对话内换话题**（例：刚查余额 → 改问建系列 / 预警 / 发票） | **重新 Read** 新话题对应 references，**禁止**沿用上一任务的参数记忆 |
+| **Playbook 编号不同**（P1→P3、P4→P5） | 即使刚做过 P1，执行 P3 仍须 Read `accounts/accounts.md`（`accounts-digest`）等 P3 专属节 |
+| **专用 report-templates**（OKKI / 询盘分析） | Read 对应 `report-templates/*.md` **全文**，勿只凭 SKILL 摘要 |
+| **上下文被压缩 / 记不清字段或命令** | 重读 `SKILL.md` 路由表 + 当次任务 references |
+| **CLI 返回 400 / 字段对不上** | 回到对应 reference 核对参数名与口径，勿猜 |
+
+### 禁止
+
+- **禁止**「上次已经读过 `accounts/accounts.md` / `google-ads/google-ads.md`，本任务直接 `siluzan-tso …`」
+- **禁止**用对话记忆中的示例 ID、金额、命令 flags 代替当次 Read 文档
+- **禁止**跳过 `references/core/tips.md` 里的 outline→JSON 顺序
+
+---
+
+## 执行流程
+
+**计划 → 确认 → 执行 → 验证 → 推测下一步**：
+
+1. **按加载纪律 Read 当次任务 references** → 用 `-h` 确认命令 → 向用户输出操作计划
+2. 涉及写入/修改/删除的操作必须与用户确认
+3. 按计划执行，说明每步意图
+4. 用成对的读命令复核写入结果；异步任务每 5s 轮询直到完成
+5. 全部完成后预测用户下一步操作
+
+### 执行模式速查
+
+| 模式 | 说明 |
+| ---- | ---- |
+| **数据交付类** | `google-analysis` / `stats` / `ad campaigns` 等带 `--json-out`：必须脚本读盘转换，见下文「数据转换硬规范」 |
+| **客户/产品背景** | 拓词、方案、报告背景段：先 `rag list` + `rag query`，再衔接 `keyword` / `ad` / `google-analysis` |
+| **仅调接口** | 优化记录、线索表单、预警、财务命令：无需输出转换 |
+
+---
+
+## 硬规范
+
+- **账户状态 ≠ 系列状态**：`stats` / `balance` / `list-accounts` 的 `status` 只表示账户是否可用；系列状态必须来自 `ad campaigns`。
+- **数据时效性**：涉及「今天/当天/今日消耗」「实时消耗排行」前，必读 `references/analytics/account-analytics.md` 顶部「数据时效性」表。TikTok / Yandex / BingV2 / Kwai 仍是 `accountsoverview` 同步昨天数据，**不能查今天**。
+- **先查账户再操作**：`list-accounts -m [mediaType] -k [mediaCustomerId]`；涉及金额前必读 `references/accounts/currency.md`，从 `ma.currencyCode` 确定 CNY/USD，**禁止**默认 Google=美金。
+- **不猜测账户 ID**：`entityId` ≠ `mediaCustomerId`，两者均来自 `list-accounts`。
+- **媒体类型区分大小写**：`Google`、`TikTok`、`MetaAd`、`BingV2`、`Kwai`。
+- **CLI 输出忠实**：数值与 ID 须与本次落盘 JSON / stdout 一致，不编造示例 ID；`data` 为空时只说「当前返回无记录」并附 JSON 路径。
+- **破坏性操作必须确认 + `--commit`**：账户解绑/关闭/取消分享、BC/MCC 解绑、删除预警/报告/广告/关键词、发票申请、广告发布等。
+- **不确定时读文档**：先读对应 references 或用 `-h`，不要猜参数。
+- **Google 新建搜索系列**：流程仅在 `references/google-ads/google-ads-campaign-plan.md` 维护。
+- **Google 开户**：`open-account google-wizard` 仅限真实 TTY；Agent/自动化用非交互 `open-account google ...`，审核进度用 `account-history`。
+- **主动更新**：详见 `references/core/setup.md`。
+
+---
+
+## 数据转换硬规范
+
+本 Skill 下**所有**业务数据均以 CLI `--json-out`（或用户提供的同构 JSON）落盘为唯一真相源。Agent **不得**在对话或脚本里「代替」磁盘数据。
+
+| 必须 | 禁止 |
+| ---- | ---- |
+| 编写并**执行** Node/Python 脚本：`readFile` / `require` 读落盘 JSON → 计算 → 写出 | 用 `Read` 读大 JSON 后在回复里手填、改数、心算汇总 |
+| **先 outline 后 JSON**：`outlineFile`（`.outline.txt`）→ `writtenFiles[0]` | 跳过 outline 猜字段名；把 outline 当数据贴给用户 |
+| 字段路径以 `outlineFile` + 当次 `writtenFiles` / manifest 为准 | 把国家名、ID、金额、词表等**业务值**写成源码字面量 |
+| 映射表 / 模板契约在运行时加载（`analytics/geo-continents.json`、`campaign-create-template.json`） | 复制配置条目进源码常量 |
+| 脚本输出与落盘 JSON 可复核 | 用「上次对话记住的数」「占位数」写入交付物 |
+
+**允许的字面量**：输出目录、Sheet/列标题、技术格式、`focusCountries` 等**用户当轮明确给出**的配置（建议落盘为 `config.json` 再读）。
+
+完整协议见 `references/core/tips.md` § 处理顺序、§ 已有 JSON 时。
+
+---
+
+## 时间范围
+
+涉及「投放数据 / 消耗 / 报告 / 周报 / 月报 / 优化建议」且用户未给明确起止日期时**必须反问**（示例：A) 最近完整自然周 B) 本月 1 号到昨天 C) 自定义 YYYY-MM-DD）。给出范围后，报告首行标注 `统计区间：YYYY-MM-DD ~ YYYY-MM-DD（货币：XXX）`。
+
+**例外**（不反问）：
+
+- `list-accounts` 全量：用 `--json-out`，注意翻页
+- 「昨天」单日 stats：默认 `Asia/Shanghai` 日历日；先 `list-accounts` 再 `stats`
+- 仅持有 `entityId`：先 `list-accounts` 解出 `mediaCustomerId`，**禁止**把 `entityId` 传给 `stats -a` / `balance -a`
+- `forewarning records`、`invoice list`「本月」、TikTok `clue`「最近一周」：见对应 references
+
+**默认值白名单**（仅用户明确授权「你决定」时使用）：
+
+| 场景 | 默认窗口 |
+| ---- | -------- |
+| 日常巡检 / 余额扫描 | `now - 7d` ~ `now - 1d` |
+| 周报 | 上一个完整自然周（周一 ~ 周日） |
+| 月报 | 上一个完整自然月 |
+| Google 关键词/系列分析 | `now - 30d` ~ `now - 1d` |
+| MetaAd 账户分析 | 不得默认，必须问 |
+
+---
+
+## 币种与金额（速查）
+
+完整字段表见 `references/accounts/currency.md`。
+
+- **币种只认接口字段**：`list-accounts` → `items[].ma.currencyCode`；同媒体可同时有 CNY 与 USD，不得凭媒体猜币种。
+- **符号**：`CNY` → **￥**；`USD` → **$**。多账户按 `currencyCode` 分表，**禁止**跨币种求和。
+- **金额单位统一为「元」**：报告保留 2 位小数。
+- **品牌名优先级**：(1) 用户明确提供 → (2) `list-accounts.mag.advertiserName` → (3) 网址域名占位 `[待确认品牌名]`。**严禁**把英文域名翻译为虚构中文品牌。
+
+---
+
+## 批量任务硬约束
+
+| 任务 | 推荐命令 | 禁止 |
+| ---- | -------- | ---- |
+| 多账户余额 / 预算不足预警 | `balance-scan -m <媒体> --threshold-days 7` | 逐账户 `balance --accounts ...` |
+| 多账户投放画像 | `accounts-digest -m <媒体> [-a ...] --start --end --json-out` | 逐账户 `stats` |
+| 多账户 × 多维度 Google 数据 | 全量：`google-analysis-batch run`（省略 `-a`）；2~10：`google-analysis -a id1,id2,...` | 外层 for-loop；先 list 再拼 `-a` |
+| 多系列诊断 | `ad campaigns --json-out` + node 读文件过滤 | 逐系列 `ad campaign-get` |
+
+**`google-analysis-batch` 纪律**（详见 `references/analytics/google-analysis-batch.md`）：
+
+1. 拉全量时**省略** `-a`；中断后**必须** `resume --run-id <id>`，**禁止**重新 `run`。
+2. stdout 始终是单行 JSON（`kind=siluzan-tso-batch-summary`）。
+3. 退出码：`0` 全成功 / `2` 部分成功 / `3` 全失败或 Token 失效 / `4` 用法错误。
+4. 401 → 整批终止；按 `references/core/setup.md` 重登录后 `resume`。
+
+---
+
+## 运行时长与进度
+
+预估超 2 分钟的任务先告知预计耗时；超 5 分钟未完成时主动检查并告知用户。长任务中断后用对应 `resume` 入口续跑，**禁止**直接重跑 `run`。
+
+---
+
+## 账户 ID 示例
+
+先用位数判断类型，不确定再 `list-accounts -m [mediaType] -k [id]`：
+
+- Google: `454xxx5137` 或 `270-xxx-0720`（去掉 `-`）
+- TikTok: `70083497xxx59820033`
+- Meta(Facebook): `1716030xxx734076`
+- Bing: `138xxx763`
+- Yandex: `porg-uthxxxrk`
+- Kwai: `act_1716030xxx734076`
+
+---
+
+## 常见 HTTP 状态码
+
+- **400**：参数错误，查看对应 reference 或 `-h`
+- **401**：平台方返回则需用户重新授权；**我方凭据失效**则优先 `send-login-code` + `login --phone --code`，见 `references/core/setup.md`
+- **500**：服务可能正在部署/升级，建议反馈 Siluzan 相关人员
+
+---
+
+## 风险预警与自动化（主动介绍）
+
+加载本 skill 时须向用户介绍 `references/operations/hosted-automation-user-catalog.md` 中的能力：
+
+- **预算 & ROI 控制**：单日预算熔断、CPA 飙升自动降价、连续空耗自动暂停
+- **异常监控与报警**：账户封禁检测、落地页死链强停、素材拒审提醒、花费异动、余额枯竭预警
+- **自动优化**：差广告降价/关停、高转化提价扩量、A/B 测试自动决出胜者
+
+---
+
+## 消息平台语法
+
+需 webhook 发送消息时，先阅读对应平台文档：
+
+- 企业微信：https://developer.work.weixin.qq.com/document/path/99110
+- 飞书：https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot
+- 其他平台默认 markdown 输出

package/dist/skill/references/core/playbooks.md

@@ -0,0 +1,141 @@
+# 高频任务 Playbook（P1–P7）
+
+> **开始前**：按 `references/core/agent-conventions.md` § 文档加载纪律，Read 各 Playbook 列出的 references（**不因同对话内刚做过其他 Playbook 而跳过**）。
+
+| 编号 | 场景 | 必读 references |
+| ---- | ---- | --------------- |
+| P1 | 单账户投放画像 | `analytics/account-analytics.md`、`accounts/currency.md`、`core/tips.md` |
+| P2 | 多账户余额扫描 | `accounts/accounts.md`（`balance-scan`）、`accounts/currency.md` |
+| P3 | 多账户投放画像汇总 | `accounts/accounts.md` § accounts-digest、`accounts/currency.md`、`core/tips.md` |
+| P4 | Google 账户周期报告 | `report-templates/google-period-report.md`、`analytics/account-analytics.md`、`core/tips.md` |
+| P5 | 多账户多维度报告 | `analytics/google-analysis-batch.md`、`analytics/account-analytics.md`、`core/tips.md` |
+| P6 | OKKI 周报 | `report-templates/okki-weekly-google-client.md`（全文）、`analytics/account-analytics.md`、`core/tips.md` |
+| P7 | Google 询盘分析 | `report-templates/google-inquiry-analysis.md`（全文）、`analytics/account-analytics.md`、`core/tips.md`、`analytics/geo-continents.json` |
+
+---
+
+## P1 · 单账户投放画像
+
+1. 反问时间范围（已授权默认时按 `core/agent-conventions.md` 白名单并写明区间）。
+2. `list-accounts -m Google -k <mediaCustomerId> --json-out ./snap-p1`
+3. `stats -m Google -a <mediaCustomerId> --start <S> --end <D> --json-out ./snap-p1`
+4. `ad campaigns -a <mediaCustomerId> --start <S> --end <D> --json-out ./snap-p1`
+5. 用 `report-templates/google-account-diagnosis-report.md` 模板输出，首行标注统计区间和货币。
+
+---
+
+## P2 · 多账户余额扫描
+
+**全量巡检**：
+
+```bash
+siluzan-tso balance-scan -m BingV2 --threshold-days 7 --json-out ./snap-p2
+# 可选：--min-balance 100 / --target-days 60
+```
+
+按 `remainingDays` 升序输出；消耗过低的僵尸账户不纳入预警。
+
+**已知 ID 子集**：
+
+```bash
+siluzan-tso balance-scan -m Google -a id1,id2,id3 --json-out ./snap-p2-subset
+```
+
+跳过翻页全部展示；`hitReason="none"` 表示未触阈值。
+
+---
+
+## P3 · 多账户投放画像汇总
+
+```bash
+siluzan-tso accounts-digest -m Google -a id1,id2,... --start <S> --end <D> --json-out ./snap-p3
+```
+
+1. 反问时间范围后执行。
+2. 基于落盘 `data.items` 与 `meta.totals` 生成报告，**不要**再逐账户 `stats`。
+3. 表格覆盖用户请求的**每一个** ID；某 ID 未返回时仍占一行标注「未返回」。
+4. 跨币种账户按 `currencyCode` 分表或分币种小计。
+
+---
+
+## P4 · Google 账户周期报告
+
+1. 确认时间范围；区间 > 3 个月时分段（季度/月）。
+2. 按 P1 步骤拿数据，用 `report-templates/google-period-report.md` 模板输出，首行标注统计区间和货币。
+3. 报告须含：账户概览、投放趋势、Top 关键词/系列/地区分布、优化建议。
+
+---
+
+## P5 · 多账户多维度报告
+
+> 适用：账户数 ≥ 2 且需拉取 ≥ 2 个 google-analysis 维度。**禁止**外层 for-loop。
+
+**入口选择**：全量 → 省略 `-a`；2~10 子集 → `google-analysis -a id1,id2,...`；≥10 子集或需 resume → `google-analysis-batch run -a id1,id2,...`
+
+1. 反问时间范围 + 维度（默认 `campaigns,geographic,keywords`）。
+2. **执行**：
+
+   ```bash
+   # 全量账号（推荐）：省略 -a
+   siluzan-tso google-analysis-batch run \
+     --start <S> --end <D> \
+     --sections campaigns,geographic,keywords \
+     --account-concurrency 4 --section-concurrency 6 \
+     --min-spend 1 --keyword-limit 1000 \
+     --json-out ./snap-p5
+
+   # 仅当用户明确给出 ID 子集时才传 -a
+   siluzan-tso google-analysis-batch run \
+     -a id1,id2,id3,id4 \
+     --start <S> --end <D> \
+     --sections campaigns,geographic,keywords \
+     --json-out ./snap-p5
+   ```
+
+3. **中断后只能 resume**：`siluzan-tso google-analysis-batch resume --json-out ./snap-p5 --run-id <runId>`
+4. **只读进度**：`siluzan-tso google-analysis-batch status --json-out ./snap-p5 --run-id <runId>`
+5. **产物消费**：先 outline 后 JSON 再脚本，详见 `references/core/tips.md` § 处理顺序。
+
+---
+
+## P6 · OKKI 周报
+
+> **触发**：用户话术含 `使用okki周报模板` / `OKKI 周报` / `okki 周报` 等，且指向 Google 账户 + 日期区间。
+
+1. **不要**按 `google-period-report.md` 展开默认 8 维；改读 `report-templates/okki-weekly-google-client.md` 全文。
+2. 确认 `mediaCustomerId` 与 `--start` / `--end`（未给齐按 `core/agent-conventions.md` 时间范围规则反问）。
+3. 同一 `--json-out` 目录执行模板中的命令组合：`list-accounts`（可选）、`stats`、`balance`、`google-analysis --sections overview,campaigns,keywords,search-terms,campaign-device,campaign-geo`。
+4. **先 outline 后脚本** → 交付话术 + 多 Sheet `.xlsx`（无 CLI 写表命令）。
+5. 遵守硬规范：金额读 `*Yuan`、禁止手填业务数、禁止编造 ID。
+
+---
+
+## P7 · Google 账户询盘分析
+
+> **触发**：用户话术含 `Goog账户询盘分析` / `Google 账户询盘分析` / `分析XXX Google账号的询盘效果`，或同时包含「询盘 + 账户 + Google」三要素。  
+> **不要**按 `google-period-report.md` 默认 8 维流程。
+
+1. **时间窗口强约束**：**严格 3 个月** = 分析月份 + 向前 2 个完整自然月。**禁止**扩展到 7 个月。
+2. **询盘资料入场**：
+   - **流程 A**（用户已附文件）：解析 → 落盘 `./snap-inquiry/inquiries.json`（字段见模板「询盘字段清单」）。
+   - **流程 B**（仅给账户 ID）：反问账户 + 分析月份，贴字段清单 + 示例。**禁止**自行编造询盘数据。
+3. **CLI 拉数**（同一 `--json-out` 目录）：
+
+   ```bash
+   siluzan-tso list-accounts -m Google -k <mediaCustomerId> --json-out ./snap-inquiry
+   siluzan-tso google-analysis -a <mediaCustomerId> \
+     --start <S> --end <D> \
+     --sections campaigns,keywords,search-terms,campaign-geo \
+     --json-out ./snap-inquiry
+   # Sheet 4/6：每月 campaigns+geographic（禁止用 daily-metrics 填 Sheet 4 上区）
+   siluzan-tso google-analysis -a <mediaCustomerId> --start <M1S> --end <M1E> \
+     --sections campaigns,geographic --json-out ./snap-inquiry/m1
+   siluzan-tso google-analysis -a <mediaCustomerId> --start <M2S> --end <M2E> \
+     --sections campaigns,geographic --json-out ./snap-inquiry/m2
+   siluzan-tso google-analysis -a <mediaCustomerId> --start <M3S> --end <M3E> \
+     --sections campaigns,geographic --json-out ./snap-inquiry/m3
+   ```
+
+4. **先 outline 后脚本** → 聚合脚本读 JSON → 计算 8 Sheet 数据。
+5. **国家 → 大洲映射**：脚本读 `references/analytics/geo-continents.json`；Sheet 4 重点国按 `focusCountries`（详见模板「重点国家配置」节），**禁止**硬编码国家名。
+6. **必产 8 Sheet xlsx**：版式以 `report-templates/google-inquiry-analysis.md` 为准；**只能**由 Agent 执行脚本生成，**禁止**假设 `siluzan-tso … excel` 子命令存在。

package/dist/skill/references/{setup.md → core/setup.md}

@@ -10,7 +10,7 @@
 ## 安装 CLI
 
 ```bash
-npm install -g siluzan-tso-cli
+npm install -g siluzan-tso-cli@beta
 ```
 
 ---
@@ -64,7 +64,7 @@ siluzan-tso config set --api-key <Key>               # 或 config 直接写入
 siluzan-tso config set --token <Token>               # 备用：设置 JWT Token
 ```
 
-API Key 获取入口：`https://www.siluzan.com/v3/foreign_trade/settings/apiKeyManagement`
+API Key 获取入口：`https://www-ci.siluzan.com/v3/foreign_trade/settings/apiKeyManagement`
 
 ```bash
 # 第 1 步：让用户报出手机号后，立刻发码（命令立即返回，不会等待输入）
@@ -129,9 +129,9 @@ siluzan-tso config show
 
 ```
   构建环境     : production
-  apiBaseUrl   : https://tso-api.siluzan.com
-  googleApiUrl : https://googleapi.mysiluzan.com
-  webUrl       : https://www.siluzan.com
+  apiBaseUrl   : https://tso-api-ci.siluzan.com
+  googleApiUrl : https://googleapi-ci.mysiluzan.com
+  webUrl       : https://www-ci.siluzan.com
   apiKey       : abcd****1234
 ```
 

package/dist/skill/references/core/skill-authoring.md

@@ -0,0 +1,192 @@
+# Agent SKILL 最佳实践（siluzan-tso 维护指南）
+
+本文档基于 [Agent Skills 开放规范](https://agentskills.io/specification) 与 [Cursor Skills 文档](https://cursor.com/docs/skills)，结合 siluzan-skill monorepo 的 TSO 实践，供维护 `tso-cli/assets/siluzan-ads/` 时对照。
+
+---
+
+## 1. 协议要点（agentskills.io）
+
+### 1.1 目录结构
+
+```
+siluzan-tso/                    # 安装后目录名
+├── AGENTS.md                   # Agent 域目录（gstack 风格）
+├── SKILL.md.tmpl → SKILL.md    # 构建生成
+├── snippets/                   # 共享注入块
+├── docs/skill-guide.md         # 人类导读
+├── references/
+│   ├── core/                   # 纪律、安装、playbooks
+│   ├── accounts/               # 账户、开户、财务
+│   ├── google-ads/             # CLI + rules/
+│   ├── analytics/              # 拉数、批处理、拓词
+│   └── operations/             # 预警、线索、自动化
+├── assets/
+└── report-templates/
+```
+
+源码位于 `tso-cli/assets/siluzan-ads/`，构建时 `copy-skill-assets.mjs` 替换占位符后写入 `dist/skill/`。
+
+### 1.2 SKILL.md  frontmatter
+
+| 字段 | 要求 | siluzan-tso 用法 |
+| ---- | ---- | ---------------- |
+| `name` | 小写+连字符，≤64 字，**须与安装目录名一致** | `siluzan-tso`（非 `siluzan-ads`） |
+| `description` | ≤1024 字，**第三人称**，含 WHAT + WHEN + 触发词 | 列出媒体、开户、Google Ads、报告、预警等 |
+| `license` | 可选 | `MIT` |
+| `compatibility` | 可选，≤500 字，环境依赖 | Node 18+、`siluzan-tso-cli`、鉴权 |
+| `metadata` | 可选键值 | `requires: nodejs,siluzan-tso-cli` |
+| `allowed-tools` | 可选（实验性） | `Bash(siluzan-tso:*) Read Write` |
+| `disable-model-invocation` | Cursor 扩展 | TSO 需自动激活，**不设** true |
+
+### 1.3 渐进式披露（三层加载）
+
+| 层级 | 内容 | Token 预算建议 |
+| ---- | ---- | -------------- |
+| L1 元数据 | `name` + `description` | ~100 tokens，启动时索引 |
+| L2 指令 | `SKILL.md` 正文 | <500 行，<5000 tokens，激活时加载 |
+| L3 资源 | `references/`、`assets/`、`report-templates/` | 任务相关时才 Read |
+
+**原则**：SKILL.md 只做路由与不可妥协的纪律；参数表、Playbook 步骤、优化 SOP 放 references。
+
+### 1.4 文件引用规则
+
+- 从 SKILL.md **只链接一层**（`references/foo.md`），避免 A→B→C 链式引用。
+- 路径用正斜杠，不用 Windows 反斜杠。
+- 占位符 `https://www-ci.siluzan.com`、`https://tso-api-ci.siluzan.com`、`npm install -g siluzan-tso-cli@beta` 由构建脚本替换，文档中禁止硬编码环境 URL。
+
+---
+
+## 2. 内容编写原则
+
+### 2.1 简洁（Concise is Key）
+
+Agent 已具备通用能力。文档只写 **CLI 特有** 内容：字段口径、批量命令、门禁流程、与前端不一致处。
+
+❌ 解释「什么是 Google Ads」  
+✅ `budgetAmountYuan` 已是元，禁止再 ÷100
+
+### 2.2 单一术语
+
+全库统一：
+
+| 概念 | 统一用词 | 禁止混用 |
+| ---- | -------- | -------- |
+| 广告账户 ID | `mediaCustomerId` | customer id、账户号（无上下文时） |
+| 实体 ID | `entityId` | 内部 id |
+| 落盘 | `--json-out` | --json（Agent 编排禁止） |
+| 媒体 | `Google`、`TikTok`、`MetaAd`… | google、meta |
+
+### 2.3 默认 + 逃生口
+
+每个决策点给一个默认路径，例外单独一行：
+
+```markdown
+全量 Google 批处理：省略 `-a`（CLI 内部拉清单）。
+仅当用户明确给出 ID 子集时才传 `-a id1,id2,...`。
+```
+
+### 2.4 反馈环（Feedback Loop）
+
+写操作文档须含：**写命令 → 读命令复核 → 失败时查 reference**。
+
+破坏性操作统一：**用户确认 → `--commit` → 读命令验证**。
+
+### 2.5 禁止时间敏感表述
+
+不写「2025 年 8 月前用旧 API」。废弃内容放 `## 已废弃` 折叠或删除。
+
+---
+
+## 3. siluzan-tso 文档分层
+
+| 文件 | 职责 |
+| ---- | ---- |
+| `SKILL.md` | 安装、能力边界、文档路由表、任务→文档速查、Playbook 索引 |
+| `references/core/agent-conventions.md` | Agent 纪律：加载时机、硬规范、数据转换、时间/币种/批量 |
+| `references/core/playbooks.md` | P1–P7 标准动作（可复制命令块） |
+| `references/core/tips.md` | `--json-out` 协议、outline 处理顺序 |
+| `references/*.md` | 单功能域：命令、参数、输出示例 |
+| `references/google-ads/rules/` | Google 优化/合规 SOP（非 CLI 参数） |
+| `assets/*.json` / `*.md` | 创建类 JSON 契约 |
+| `report-templates/*.md` | 报告内容纲要（优先于 HTML） |
+| `report-templates/*.html` | 视觉样式，**不含业务数据** |
+| `README.md` | 给「通过 URL 安装」的大模型说明（不进 dist 路由） |
+
+### 3.1 与 CLI 代码同步
+
+**代码变更 → 必须同步 Skill**（tutorial-10 #2）。新命令注册在 `_register.ts` / `index.ts` 后：
+
+1. 更新对应 `references/*.md`
+2. 更新 `SKILL.md` 路由表（若新功能域）
+3. 评估场景：`tso-cli/eval/scenarios/` + `pnpm --filter siluzan-tso-cli run eval:export-cases`
+
+### 3.2 灰度开关（tutorial-10 #11）
+
+| 状态 | CLI 注册 | SKILL 文档 | AI 可见 |
+| ---- | -------- | ---------- | ------- |
+| 内测 | 是 | 否 | 否 |
+| 公开 | 是 | 是 | 是 |
+
+---
+
+## 4. description 写法模板
+
+```yaml
+description: >-
+  Operates Siluzan TSO ad accounts via siluzan-tso-cli: Google/Bing/Yandex/TikTok/Kwai/Meta
+  account management, Google Ads CRUD, analytics, optimization reports, forewarning, leads,
+  invoicing, and RAG knowledge lookup. Use when the user mentions ad accounts, balance, spend,
+  campaigns, keywords, PMax, open account, MCC/BC binding, or TSO reporting.
+  Each new task requires re-reading routed references per SKILL.md.
+```
+
+中文项目可保留中文 description，但仍须：**第三人称 + 能力列表 + 触发场景 + 重读纪律一句**。
+
+---
+
+## 5. 体积与质量检查清单
+
+发布前逐项确认：
+
+### Frontmatter
+- [ ] `name` === 安装目录名 `siluzan-tso`
+- [ ] `description` 含 WHAT、WHEN、关键词
+- [ ] `compatibility` 列出 Node + CLI + 鉴权
+
+### SKILL.md
+- [ ] 正文 < 500 行
+- [ ] 无重复 parameters 表（细节在 references）
+- [ ] 路由表覆盖所有 `references/*.md` 入口
+- [ ] Playbook 仅索引，步骤在 `core/playbooks.md`
+
+### References
+- [ ] 每个 CLI 命令族有且仅有一个主 reference
+- [ ] 含 `--json-out` 示例（查询类）
+- [ ] 写命令含 `--commit` 与复核命令
+- [ ] 无断链（如 `accounts/open-account-by-media.md` 必须存在）
+
+### 构建
+- [ ] `pnpm run build:tso:test` 后 `dist/skill/SKILL.md` 占位符已替换
+- [ ] `_meta.json` 版本与 package.json 一致
+
+---
+
+## 6. 反模式（Avoid）
+
+| 反模式 | 正确做法 |
+| ------ | -------- |
+| SKILL.md 内嵌 200 行 Playbook | 移至 `references/core/playbooks.md` |
+| Agent 用 `--json` 落大 JSON 到对话 | 一律 `--json-out` + 脚本读盘 |
+| 路由表缺文件 | 补文件或删链接 |
+| google-ads-rules 深链三层 | SKILL → `google-ads/rules/README.md` → 具体规则 |
+| HTML 模板假数据当示例 | 纲要 `.md` 定义维度，数据来自 CLI |
+| 凭记忆跨任务复用参数 | 每任务重读 `core/agent-conventions.md` § 加载纪律 |
+
+---
+
+## 7. 相关仓库文档
+
+- `.cursor/rules/tutorial-05-core/skill-authoring.mdc` — 项目内 Skill 结构速查
+- `.cursor/rules/tutorial-10-best-practices.mdc` — CLI + Skill 同步等 12 条
+- `cso-cli/assets/siluzan-cso/SKILL.md` — 姊妹包参考（命令索引表风格）
+- https://agentskills.io/specification — 开放规范原文

package/dist/skill/references/{tips.md → core/tips.md}

@@ -1,6 +1,6 @@
 # CLI 使用技巧：`--json-out` 落盘 + Node.js 精准查询
 
-> **文档重读（与落盘无关，但同样硬）**：**每个新的用户任务**或**同对话内换话题**时，须按 `SKILL.md`「文档加载纪律」**重新 Read** 当次任务对应的 `references/*.md` / `report-templates/*.md`，再执行 CLI。**禁止**因上一轮已读过某 reference 而跳过（参数、批量命令、Playbook 编号会随任务变化）。
+> **文档重读（与落盘无关，但同样硬）**：**每个新的用户任务**或**同对话内换话题**时，须按 `references/core/agent-conventions.md` § 文档加载纪律 **重新 Read** 当次任务对应的 `references/*.md` / `report-templates/*.md`，再执行 CLI。
 
 > **AI 助手（本 Skill）**：凡需结构化数据，一律使用 **`--json-out <路径>`**（**目录** 或 **`*.json` 具体文件**）将 JSON 写入磁盘（并更新 **`cli-manifest[-<查询id>].json`**，与 `google-analysis` 的 **`manifest-<accountId>.json`**、`report …` 的 **`report-manifest[-<accountId>].json`** 并存于各自目录），再用 **脚本读文件**（`fs.readFileSync` / `require`）做筛选与聚合；**不要**依赖对话里粘贴的 stdout 整包 JSON。命令成功时 **stdout 仅一行摘要 JSON**（体积小），其中 **`outlineFile`** 指向与当次 `*.json` **同 stem** 的 **`*.outline.txt`**（纯文本单行，接近 **TypeScript 类型字面量**：`{ a: number; b: string }`、`(T | U)[]` 等；数组由**前 8 项**去重推断并集；环 / 同对象再出现为 `any`）。完整数据仍以落盘 `*.json` 为准，类型扫一眼读 outline 文件即可。
 >
@@ -12,13 +12,13 @@
 >
 > 人类/一次性调试仍可在终端使用 **`--json`**（与 **`--json-out` 互斥**）；Skill 正文与 Agent 编排**只写 `--json-out`**。
 
-**Google `google-analysis` 与 Meta/TikTok/Bing `report …` 账户分析拉数（本 Skill 推荐口径）**：统一 **`--json-out <目录>`** 落盘（分析子命令以目录为主；通用业务命令另支持 **`--json-out ./foo.json` 单文件**）；**用脚本读目录内 JSON + 数据处理库算指标，再由代码写出交付文件**（HTML / Excel / PDF / PPT / Markdown 等任选），勿用 `Read` 代替程序读数、勿在聊天里直接贴完整交付稿；脚本里勿写业务数据常量。详见 `references/account-analytics.md`「Google 分析快照工作流」及清单文件说明。
+**Google `google-analysis` 与 Meta/TikTok/Bing `report …` 账户分析拉数（本 Skill 推荐口径）**：统一 **`--json-out <目录>`** 落盘（分析子命令以目录为主；通用业务命令另支持 **`--json-out ./foo.json` 单文件**）；**用脚本读目录内 JSON + 数据处理库算指标，再由代码写出交付文件**（HTML / Excel / PDF / PPT / Markdown 等任选），勿用 `Read` 代替程序读数、勿在聊天里直接贴完整交付稿；脚本里勿写业务数据常量。详见 `references/analytics/account-analytics.md`「Google 分析快照工作流」及清单文件说明。
 
 ---
 
 ## 币种（**Agent 必读**）
 
-涉及余额、消耗、预算、报告、Excel 前：**先 Read `references/currency.md`**，从 `list-accounts` / `balance` / `stats` / `google-analysis` 的 **`currencyCode`** 确定 CNY 或 USD，再选 **￥** 或 **$**。**禁止**默认 Google=美金、禁止跨币种求和。
+涉及余额、消耗、预算、报告、Excel 前：**先 Read `references/accounts/currency.md`**，从 `list-accounts` / `balance` / `stats` / `google-analysis` 的 **`currencyCode`** 确定 CNY 或 USD，再选 **￥** 或 **$**。**禁止**默认 Google=美金、禁止跨币种求和。
 
 ---
 
@@ -49,7 +49,7 @@
 - 网关原始字段 `budgetAmount`（分）、`*Micros`（微元）**已不再落盘**，无需做任何单位换算。
 - **`campaigns-*.outline.txt`** 在标准 3 行头注释之后会多 **2 行** 中文 `//` 提示；提取类型行请用 **`outlineRaw.trimEnd().split('\n').filter(l => !l.startsWith('//')).pop()`**（与上文步骤 2 一致），勿把提示行当 TS 类型。
 
-详见 `references/account-analytics.md`「金额单位」「CampaignSectionData」。
+详见 `references/analytics/account-analytics.md`「金额单位」「CampaignSectionData」。
 
 ---
 
@@ -143,7 +143,7 @@ list
 
 ### 3b. 多账户投放画像（`accounts-digest`）
 
-多账户汇总消耗/点击/转化时**优先** `accounts-digest`，不要对每个账户循环 `stats`（见 `SKILL.md` Playbook P3、`references/accounts.md` § accounts-digest）。
+多账户汇总消耗/点击/转化时**优先** `accounts-digest`，不要对每个账户循环 `stats`（见 `SKILL.md` Playbook P3、`references/accounts/accounts.md` § accounts-digest）。
 
 ```bash
 siluzan-tso accounts-digest -m Google -a id1,id2,id3 \