siluzan-tso-cli 1.1.15 → 1.1.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/skill/SKILL.md
CHANGED
|
@@ -9,14 +9,12 @@ allowed-tools: Bash(siluzan-tso:*) Read Write
|
|
|
9
9
|
|
|
10
10
|
# Siluzan TSO Skill
|
|
11
11
|
|
|
12
|
-
本 Skill
|
|
12
|
+
本 Skill 只保留任务边界、文档路由与执行规则。具体业务细节、参数、模板、流程与示例均以 references 文档为准。
|
|
13
13
|
|
|
14
14
|
---
|
|
15
15
|
|
|
16
16
|
## 一键安装
|
|
17
17
|
|
|
18
|
-
如果 CLI 尚未安装，直接帮用户执行对应平台的安装脚本：
|
|
19
|
-
|
|
20
18
|
- **macOS / Linux / WSL：**
|
|
21
19
|
```bash
|
|
22
20
|
bash <(curl -fsSL https://unpkg.com/siluzan-tso-cli@latest/dist/skill/scripts/install.sh)
|
|
@@ -26,8 +24,6 @@ allowed-tools: Bash(siluzan-tso:*) Read Write
|
|
|
26
24
|
irm https://unpkg.com/siluzan-tso-cli@latest/dist/skill/scripts/install.ps1 | iex
|
|
27
25
|
```
|
|
28
26
|
|
|
29
|
-
---
|
|
30
|
-
|
|
31
27
|
参照 `references/setup.md` 完成安装与配置。
|
|
32
28
|
|
|
33
29
|
---
|
|
@@ -37,21 +33,21 @@ allowed-tools: Bash(siluzan-tso:*) Read Write
|
|
|
37
33
|
| 文档 | 功能 |
|
|
38
34
|
|------|------|
|
|
39
35
|
| `references/setup.md` | 安装、登录、配置、环境切换、更新 |
|
|
40
|
-
| `references/workflows.md` |
|
|
41
|
-
| `references/tips.md` | **Agent 拉数一律 `--json-out`**（目录或 `*.json` 文件）+ 读 `cli-manifest[-<查询id>].json` / 各 `<section>[-<查询id>].json` + **`*.outline.txt`**（TS
|
|
36
|
+
| `references/workflows.md` | 多步骤业务流程、跨命令串联 |
|
|
37
|
+
| `references/tips.md` | **Agent 拉数一律 `--json-out`**（目录或 `*.json` 文件）+ 读 `cli-manifest[-<查询id>].json` / 各 `<section>[-<查询id>].json` + **`*.outline.txt`**（TS 式类型，**几百字节，描述完整字段结构**——写聚合脚本前先读它而不是 `Read` 整个 JSON，省 2~3 个数量级 context）；stdout 一行摘要含 `manifestFile` / `writtenFiles` / `outlineFile` 等 |
|
|
42
38
|
| `references/accounts.md` | 账户列表、余额、消耗、开户记录、授权/解绑/分享/MCC/BC/BM/邮箱授权 |
|
|
43
39
|
| `references/open-account-by-media.md` | 各媒体开户、参数与资料要求 |
|
|
44
|
-
| `references/google-ads.md` | Google Ads
|
|
40
|
+
| `references/google-ads.md` | Google Ads 创建、修改、优化与管理；含 `ad list` 等读命令的 JSON 拒审字段（`policyApprovalStatusV2`、`approvalStatusDetails` 等） |
|
|
45
41
|
| `references/reporting.md` | Siluzan TSO 优化报告（Google/TikTok）的生成、推送与查看 |
|
|
46
42
|
| `references/account-analytics.md` | 广告平台账户分析数据拉取与分析/诊断报告模板 |
|
|
47
|
-
| `references/google-analysis-batch.md` | **多账户 × 多维度** Google 数据批处理引擎（`
|
|
43
|
+
| `references/google-analysis-batch.md` | **多账户 × 多维度** Google 数据批处理引擎（`run/resume/status`）；产物目录、退出码、stdout 协议、错误分类、resume 语义 |
|
|
48
44
|
| `references/optimize.md` | AI 优化建议记录、详情与历史查询 |
|
|
49
45
|
| `references/clue.md` | TikTok / Meta 线索表单 |
|
|
50
|
-
| `references/forewarning.md` | Siluzan
|
|
51
|
-
| `references/hosted-automation-user-catalog.md` |
|
|
46
|
+
| `references/forewarning.md` | Siluzan 智能预警规则与通知服务（仅微信推送）；只负责创建，后续由 Siluzan 服务完成 |
|
|
47
|
+
| `references/hosted-automation-user-catalog.md` | 更强大的智能预警：预算/ROI 自控、异常监控、自动优化、自动化风控 |
|
|
52
48
|
| `references/finance.md` | 转账、开票、发票抬头、充值网页引导 |
|
|
53
|
-
| `references/write-audit-restore.md` | 本机写审计、`--commit`、补偿写 `audit restore-plan` / `restore-apply
|
|
54
|
-
| `report-templates/report-template.html` | 默认 HTML
|
|
49
|
+
| `references/write-audit-restore.md` | 本机写审计、`--commit`、补偿写 `audit restore-plan` / `restore-apply` |
|
|
50
|
+
| `report-templates/report-template.html` | 默认 HTML 报告样式参考 |
|
|
55
51
|
|
|
56
52
|
---
|
|
57
53
|
|
|
@@ -63,40 +59,22 @@ allowed-tools: Bash(siluzan-tso:*) Read Write
|
|
|
63
59
|
|
|
64
60
|
| 由 **本 Skill + CLI** 保证 | 由 **宿主客户端 / 外部调度** 负责 |
|
|
65
61
|
|---------------------------|-----------------------------------|
|
|
66
|
-
| 单次/按需调用下，命令能拉取验证所需的 **结构化字段**（**Agent：`--json-out <目录>`**
|
|
67
|
-
| 写操作命令语义清晰，文档给出
|
|
68
|
-
| 金额与 ID 口径与文档一致（`*Display`、`entityId` vs `mediaCustomerId`
|
|
62
|
+
| 单次/按需调用下，命令能拉取验证所需的 **结构化字段**（**Agent：`--json-out <目录>`** 落盘后读文件） | **何时**跑一轮检查（cron、事件、对话触发） |
|
|
63
|
+
| 写操作命令语义清晰，文档给出 **写后如何用读命令复核** | **IF 条件**（多指标 AND/OR、滑动时间窗等）的计算与决策 |
|
|
64
|
+
| 金额与 ID 口径与文档一致（`*Display`、`entityId` vs `mediaCustomerId` 等） | 命中后的 **触达**（钉钉/飞书/Slack 等）与内部 **P1/工单** 流程 |
|
|
69
65
|
| `references/google-ads.md` 等与命令、字段含义对齐 | 多账户、多系列的 **批处理循环**、限速、失败重试策略 |
|
|
70
66
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
具体检查项↔命令见 `references/hosted-automation-self-control.md`；异常监控 JSON 键名见 `references/hosted-automation-monitoring-json.md`；自动优化见 `references/hosted-automation-optimize-index.md`；总览见 `references/workflows.md`。
|
|
67
|
+
具体检查项见 `references/hosted-automation-self-control.md`、异常监控 JSON 键名见 `references/hosted-automation-monitoring-json.md`、自动优化见 `references/hosted-automation-optimize-index.md`、总览见 `references/workflows.md`。
|
|
74
68
|
|
|
75
69
|
---
|
|
76
70
|
|
|
77
71
|
## Skill 使用方式
|
|
78
72
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
-
|
|
82
|
-
- **禁止**用 `Read` 扫 JSON 后在对话里手填数或粘贴整份交付稿；**禁止**在报告脚本中以字面量写死应从 JSON 得到的业务数据。
|
|
83
|
-
- **（不推荐）Siluzan 平台异步生成**：调用接口后返回报告链接，你无法用它做数据分析。详见 `references/reporting.md`。
|
|
84
|
-
|
|
85
|
-
**写报告前必读**：`stats` / `balance` / `list-accounts` 里的账户 `status` 只表示**广告账户**是否可用，**不能**当作**广告系列**是否启用；系列状态须用 `ad campaigns`。详见 `references/account-analytics.md`「账户状态 ≠ 广告系列状态」。
|
|
86
|
-
|
|
87
|
-
### 广告账户相关
|
|
88
|
-
|
|
89
|
-
- 开户：`references/open-account-by-media.md`
|
|
90
|
-
- 账户管理：`references/accounts.md`
|
|
91
|
-
- 账户分析：`references/account-analytics.md`
|
|
92
|
-
- Google 广告管理：`references/google-ads.md`
|
|
73
|
+
- **报告生成（推荐）**：`google-analysis … --json-out <目录>`（通过 `--sections` 选取维度），**须编写并执行代码**（Node/Python）从目录读取 JSON 完成计算再写出最终文件。详见 `references/account-analytics.md`。**禁止**用 `Read` 扫 JSON 后在对话里手填数，**禁止**在报告脚本中以字面量写死应从 JSON 得到的业务数据。
|
|
74
|
+
- **广告账户**：开户→`references/open-account-by-media.md`；管理→`references/accounts.md`；分析→`references/account-analytics.md`；Google 广告→`references/google-ads.md`
|
|
75
|
+
- **仅调用接口、无需你输出**：优化记录（`references/optimize.md`）、线索表单（`references/clue.md`）、预警（`references/forewarning.md`）、财务（`references/finance.md`）
|
|
93
76
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
- 优化记录（`references/optimize.md`）：Siluzan 自动执行，你只能查询结果。注意与 `references/google-ads.md` 中的优化流程区分——后者更强大且由你控制，推荐使用后者。
|
|
97
|
-
- 线索表单：`references/clue.md`
|
|
98
|
-
- 预警（`references/forewarning.md`）：仅微信推送；若宿主已有通知能力，可不依赖此功能。
|
|
99
|
-
- 财务：`references/finance.md`
|
|
77
|
+
**写报告前必读**：`stats` / `balance` / `list-accounts` 里的 `status` 只表示**广告账户**是否可用，**不能**当作**广告系列**是否启用；系列状态须用 `ad campaigns`。
|
|
100
78
|
|
|
101
79
|
---
|
|
102
80
|
|
|
@@ -104,35 +82,32 @@ allowed-tools: Bash(siluzan-tso:*) Read Write
|
|
|
104
82
|
|
|
105
83
|
### 执行流程
|
|
106
84
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
5. **完成**：确认所有步骤已执行完毕，结合 CLI 与 references 对用户下一步操作进行预测
|
|
85
|
+
**计划 → 确认 → 执行 → 验证 → 推测下一步**：
|
|
86
|
+
1. 读对应 references → 用 `-h` 确认命令 → 向用户输出操作计划
|
|
87
|
+
2. 涉及写入/修改/删除的操作必须与用户确认
|
|
88
|
+
3. 按计划执行，说明每步意图
|
|
89
|
+
4. 用成对的读命令复核写入结果；异步任务每 5s 轮询直到完成
|
|
90
|
+
5. 确认所有步骤已执行完毕，对用户下一步操作进行预测
|
|
114
91
|
|
|
115
92
|
### 硬规范
|
|
116
93
|
|
|
117
|
-
- **账户状态 ≠ 广告系列状态**：`stats`/`balance`/`list-accounts` 的 `status`
|
|
118
|
-
-
|
|
119
|
-
-
|
|
120
|
-
- **使用 `--json-out`
|
|
94
|
+
- **账户状态 ≠ 广告系列状态**：`stats`/`balance`/`list-accounts` 的 `status` 只表示账户是否可用，系列状态**必须**来自 `ad campaigns`。
|
|
95
|
+
- **不确定时读文档**：先读对应 references 或用 `-h` 查看帮助，不要猜参数。
|
|
96
|
+
- **先查账户再操作**：`list-accounts -m [mediaType] -k [mediaCustomerId]`。
|
|
97
|
+
- **使用 `--json-out` 处理数据**：处理顺序：先读 `outlineFile`（schema 描述，扩展名 **`.outline.txt`** 不是 `.json`，**禁止 `require()`**，用 `fs.readFileSync(outlineFile,'utf8')` 取最后一行 TS 式类型字面量即可了解全部字段路径）→ 再让脚本读 `writtenFiles[0]`（真实数据 JSON）做聚合。**outline 通常几百字节、JSON 常见几 MB，先读 outline 能节省 2~3 个数量级的上下文**——尤其多账户多维度场景，直接 `Read` 全量 JSON 几次就把对话窗口塞满了。**禁止**把 outline 当数据、跳过 outline 猜字段、把 outline 内容贴给用户当结论。
|
|
121
98
|
- **CLI 输出忠实**：数值与 ID 须与本次落盘 JSON 或表格 stdout 一致，不编造示例 ID。`data` 为空时只说明「当前返回无记录」并附原始 JSON 路径。
|
|
122
99
|
- **不猜测账户 ID**：`entityId` ≠ `mediaCustomerId`，两者均来自 `list-accounts`。
|
|
123
100
|
- **媒体类型区分大小写**：`Google`、`TikTok`、`MetaAd`、`BingV2`、`Kwai`。
|
|
124
|
-
-
|
|
125
|
-
- **写操作后确认**：完成写/修改/编辑/更新后确认数据正确。
|
|
126
|
-
- **主动更新**：详见 `references/setup.md`。
|
|
127
|
-
- **破坏性操作必须确认**：账户解绑/关闭/取消分享、BC/MCC 解绑、删除预警/报告/广告/关键词、发票申请、广告发布等操作前，必须明确告知并获得确认。
|
|
101
|
+
- **破坏性操作必须确认**：账户解绑/关闭/取消分享、BC/MCC 解绑、删除预警/报告/广告/关键词、发票申请、广告发布等。
|
|
128
102
|
- **Google 广告结构性改动**：须遵守 `references/google-ads.md` 开篇流程——先读规则、列计划与文档清单，用户确认后才执行写命令。
|
|
129
103
|
- **Google 开户（CLI 指引）**：`open-account google-wizard` 仅适用真实 TTY；Agent/自动化环境一律用非交互 `open-account google ...`，审核进度用 `account-history`。
|
|
104
|
+
- **主动更新**：详见 `references/setup.md`。
|
|
130
105
|
|
|
131
106
|
### 时间范围强制反问
|
|
132
107
|
|
|
133
|
-
涉及"投放数据 / 消耗 / 报告 / 周报 / 月报 / 优化建议"的任务，用户未给明确起止日期时**必须反问**（示例：A) 最近完整自然周 B) 本月 1 号到昨天 C) 自定义 YYYY-MM-DD
|
|
108
|
+
涉及"投放数据 / 消耗 / 报告 / 周报 / 月报 / 优化建议"的任务，用户未给明确起止日期时**必须反问**（示例：A) 最近完整自然周 B) 本月 1 号到昨天 C) 自定义 YYYY-MM-DD）。给出范围后，报告首行标注 `统计区间：YYYY-MM-DD ~ YYYY-MM-DD（货币：XXX）`。
|
|
134
109
|
|
|
135
|
-
|
|
110
|
+
**例外**（不反问）：
|
|
136
111
|
- `list-accounts` 全量：用 `--json-out`，注意翻页
|
|
137
112
|
- 「昨天」单日 stats：默认 `Asia/Shanghai` 日历日；先 `list-accounts` 再 `stats`
|
|
138
113
|
- 仅持有 `entityId`：先 `list-accounts` 解析出 `mediaCustomerId`，禁止把 `entityId` 传给 `stats -a` / `balance -a`
|
|
@@ -140,103 +115,88 @@ allowed-tools: Bash(siluzan-tso:*) Read Write
|
|
|
140
115
|
|
|
141
116
|
**默认值白名单**（仅用户明确授权"你决定"时使用）：
|
|
142
117
|
|
|
143
|
-
| 场景
|
|
144
|
-
|
|
145
|
-
| 日常投放巡检 / 余额扫描 | `now - 7d` ~ `now - 1d
|
|
146
|
-
| 周报
|
|
147
|
-
| 月报
|
|
148
|
-
| Google 关键词/系列分析
|
|
149
|
-
| MetaAd 账户分析
|
|
118
|
+
| 场景 | 默认窗口 |
|
|
119
|
+
|------|---------|
|
|
120
|
+
| 日常投放巡检 / 余额扫描 | `now - 7d` ~ `now - 1d` |
|
|
121
|
+
| 周报 | 上一个完整自然周（周一 ~ 周日） |
|
|
122
|
+
| 月报 | 上一个完整自然月（1 号 ~ 月末） |
|
|
123
|
+
| Google 关键词/系列分析 | `now - 30d` ~ `now - 1d` |
|
|
124
|
+
| MetaAd 账户分析 | 不得默认，必须问 |
|
|
150
125
|
|
|
151
|
-
###
|
|
126
|
+
### 金额与品牌名
|
|
152
127
|
|
|
153
|
-
- **永远使用 `*Display`
|
|
154
|
-
-
|
|
128
|
+
- **永远使用 `*Display` 字段或表格展示值**做用户可见金额。报告/表格金额保留 2 位小数，写明货币代码（例如 `¥50.00 CNY`）。
|
|
129
|
+
- **品牌名**必须来自（按优先级）：(1) 用户明确提供 (2) `list-accounts` 返回的 `mag.advertiserName` (3) 用户提供的网址→域名占位并标注 `[待确认品牌名]`。**严禁**把英文域名自行翻译为虚构中文品牌。
|
|
155
130
|
|
|
156
|
-
###
|
|
131
|
+
### 批量任务硬约束
|
|
157
132
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
|
163
|
-
|
|
|
164
|
-
| 多账户余额 / 预算不足预警 | `balance-scan -m <媒体> --threshold-days 7` | 逐账户循环 `balance --accounts ...` |
|
|
165
|
-
| 多账户投放画像（消耗/点击/转化汇总） | `accounts-digest -m <媒体> [-a id1,id2] --start --end --json-out <dir>` | 逐账户 `stats` |
|
|
166
|
-
| **多账户 × 多维度 Google 数据**（系列 / 地区 / 关键词等同时拉） | 2~10 账户：`google-analysis -a id1,id2,...`（自动转发到 batch 引擎）；≥10 账户或需 resume / deadline：`google-analysis-batch run [-a id1,id2 \| --min-spend 1] --json-out <dir> --start --end --sections ...` | 外层 for-loop `google-analysis -a <单 id>` |
|
|
167
|
-
| 多系列诊断 | `ad campaigns --json-out <dir>` + node 读文件过滤 | 逐系列 `ad campaign-get` |
|
|
168
|
-
|
|
169
|
-
若无批量命令（如 117 个 Bing 账户剩余天数计算）：先 `list-accounts --json-out <dir>` 一次性拿全量 → `node -e` 本地计算 → 只对命中账户做后续操作。
|
|
133
|
+
| 任务 | 推荐命令 | 禁止做法 |
|
|
134
|
+
|------|---------|---------|
|
|
135
|
+
| 多账户余额 / 预算不足预警 | `balance-scan -m <媒体> --threshold-days 7` | 逐账户循环 `balance --accounts ...` |
|
|
136
|
+
| 多账户投放画像 | `accounts-digest -m <媒体> [-a id1,id2] --start --end --json-out <dir>` | 逐账户 `stats` |
|
|
137
|
+
| 多账户 × 多维度 Google 数据 | **全量账号**：`google-analysis-batch run`（省略 `-a`）**2~10 子集**：`google-analysis -a id1,id2,...`（自动转发 batch）；**≥10 子集或需 resume**：`google-analysis-batch run -a id1,id2,...` | 外层 for-loop；先跑 `list-accounts -m Google` 再把 ID 拼进 `-a` |
|
|
138
|
+
| 多系列诊断 | `ad campaigns --json-out <dir>` + node 读文件过滤 | 逐系列 `ad campaign-get` |
|
|
170
139
|
|
|
171
140
|
**`google-analysis-batch` 使用纪律**（详见 `references/google-analysis-batch.md`）：
|
|
141
|
+
1. **拉全量 Google 数据时省略 `-a`**：CLI 内部自动拉清单，**禁止**先跑 `list-accounts -m Google` 再把 ID 拼进 `-a`。
|
|
142
|
+
2. 中断后**必须**用 `resume --run-id <id>` 续跑，**禁止**重新 `run`。
|
|
143
|
+
3. stdout 始终是单行 JSON（`kind=siluzan-tso-batch-summary`）；进度读 `progress.json`、轨迹读 `state/tasks.jsonl`。
|
|
144
|
+
4. 退出码：`0` 全成功 / `2` 部分成功 / `3` 全失败或 Token 失效 / `4` 用法错误。
|
|
145
|
+
5. 401 响应 → 整批终止 + `tokenInvalidated:true`，提示用户 `siluzan-tso login` 后再 resume。
|
|
172
146
|
|
|
173
|
-
|
|
174
|
-
2. stdout 始终是单行 JSON（`kind=siluzan-tso-batch-summary`）；进度详情读 `progress.json`、轨迹读 `state/tasks.jsonl`。
|
|
175
|
-
3. 退出码：`0` 全成功 / `2` 部分成功或 paused / `3` 全失败或 Token 失效 / `4` 用法错误。
|
|
176
|
-
4. 401 响应一旦出现，runner 会立刻终止整批并返回 `tokenInvalidated:true`，应提示用户 `siluzan-tso login` 后再 resume。
|
|
147
|
+
若无批量命令（如 117 个 Bing 账户剩余天数计算）：先 `list-accounts --json-out <dir>` 一次性拿全量 → `node -e` 本地计算 → 只对命中账户做后续操作。
|
|
177
148
|
|
|
178
149
|
### 运行时长与进度
|
|
179
150
|
|
|
180
|
-
预估超 2
|
|
181
|
-
|
|
182
|
-
**长任务被中断后**：使用对应命令的 resume 入口续跑（如 `google-analysis-batch resume --run-id <id>`），**禁止**直接重跑 `run`；重跑会从零开始重复请求已完成的 task，浪费配额且可能再次触发限流。
|
|
151
|
+
预估超 2 分钟的任务先告知预计耗时；超 5 分钟未完成时主动检查并告知用户。长任务中断后用对应 resume 入口续跑，**禁止**直接重跑 `run`。
|
|
183
152
|
|
|
184
153
|
---
|
|
185
154
|
|
|
186
155
|
## Playbook：高频任务标准动作
|
|
187
156
|
|
|
188
|
-
|
|
157
|
+
### P1 · 单账户投放画像
|
|
189
158
|
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
1. **反问时间范围**（用户已授权默认时用白名单并写明区间）。
|
|
159
|
+
1. **反问时间范围**（已授权默认时用白名单并写明区间）。
|
|
193
160
|
2. `list-accounts -m Google -k <mediaCustomerId> --json-out ./snap-p1`
|
|
194
161
|
3. `stats -m Google -a <mediaCustomerId> --start <S> --end <D> --json-out ./snap-p1`
|
|
195
|
-
4. `ad campaigns -a <mediaCustomerId> --start <S> --end <D> --json-out ./snap-p1
|
|
162
|
+
4. `ad campaigns -a <mediaCustomerId> --start <S> --end <D> --json-out ./snap-p1`
|
|
196
163
|
5. 用 `report-templates/google-account-diagnosis-report.md` 模板输出，首行标注统计区间和货币。
|
|
197
|
-
6. 用户要求「先拉 JSON 再文字总结」时：指向具体 JSON 文件路径，再写总结。
|
|
198
164
|
|
|
199
|
-
### P2 · 多账户余额扫描
|
|
165
|
+
### P2 · 多账户余额扫描
|
|
200
166
|
|
|
201
|
-
|
|
167
|
+
**一条命令**：
|
|
202
168
|
```bash
|
|
203
169
|
siluzan-tso balance-scan -m BingV2 --threshold-days 7 --json-out ./snap-p2
|
|
204
170
|
# 可选：--min-balance 100 筛绝对余额；--target-days 60 算建议充值额
|
|
205
171
|
```
|
|
206
172
|
按 `remainingDays` 升序输出；消耗过低的僵尸账户不纳入预警。
|
|
207
173
|
|
|
208
|
-
### P3 ·
|
|
174
|
+
### P3 · 多账户投放画像汇总
|
|
209
175
|
|
|
210
|
-
**首选**：
|
|
211
176
|
```bash
|
|
212
177
|
siluzan-tso accounts-digest -m Google -a id1,id2,... --start <S> --end <D> --json-out ./snap-p3
|
|
213
178
|
```
|
|
214
179
|
1. 反问时间范围后再执行。
|
|
215
180
|
2. 基于落盘 `data.items` 与 `meta.totals` 生成报告，**不要**再逐账户 `stats`。
|
|
216
|
-
3. 表格须覆盖用户请求的**每一个** ID；某 ID
|
|
181
|
+
3. 表格须覆盖用户请求的**每一个** ID；某 ID 未出现时仍占一行标注「未返回」。
|
|
217
182
|
4. 跨币种账户按 `currencyCode` 分表或分币种小计。
|
|
218
183
|
|
|
219
|
-
### P4 · Google
|
|
184
|
+
### P4 · Google 账户周期报告
|
|
220
185
|
|
|
221
186
|
1. 确认时间范围；区间 > 3 个月时分段（季度/月）。
|
|
222
|
-
2. 按 P1
|
|
223
|
-
3.
|
|
224
|
-
4. 报告须含：账户概览、投放趋势、Top 关键词/系列/地区分布/优化建议；不得编造未拉取到的指标。
|
|
225
|
-
5. 品牌名遵守品牌名来源硬约束；系列启停只引用系列级状态字段。
|
|
226
|
-
|
|
227
|
-
### P5 · 多账户多维度报告（"X 个 Google 账户的系列/地理/关键词数据"）
|
|
187
|
+
2. 按 P1 步骤拿数据，用 `report-templates/google-period-report.md` 模板输出，首行标注统计区间和货币。
|
|
188
|
+
3. 报告须含：账户概览、投放趋势、Top 关键词/系列/地区分布、优化建议。
|
|
228
189
|
|
|
229
|
-
|
|
190
|
+
### P5 · 多账户多维度报告
|
|
230
191
|
|
|
231
|
-
|
|
192
|
+
> 适用：账户数 ≥ 2 且需拉取 ≥ 2 个 google-analysis 维度。**禁止**外层 for-loop。
|
|
232
193
|
|
|
233
|
-
|
|
234
|
-
- **≥ 10 账户 / 需要 resume / 需要 deadline / 全账户扫描**：用 `google-analysis-batch run`
|
|
194
|
+
**入口选择**：全量→省略 `-a`；2~10 子集→`google-analysis -a id1,id2,...`（自动转发 batch）；≥10 子集/需 resume→`google-analysis-batch run -a id1,id2,...`
|
|
235
195
|
|
|
236
|
-
1. **反问时间范围 +
|
|
237
|
-
2.
|
|
196
|
+
1. **反问时间范围 + 维度**（默认 `campaigns,geographic,keywords`，可按需追加）。
|
|
197
|
+
2. **执行**：
|
|
238
198
|
```bash
|
|
239
|
-
#
|
|
199
|
+
# 全量账号（推荐）：省略 -a，CLI 自动拉清单
|
|
240
200
|
siluzan-tso google-analysis-batch run \
|
|
241
201
|
--start <S> --end <D> \
|
|
242
202
|
--sections campaigns,geographic,keywords \
|
|
@@ -244,68 +204,53 @@ siluzan-tso accounts-digest -m Google -a id1,id2,... --start <S> --end <D> --jso
|
|
|
244
204
|
--min-spend 1 --keyword-limit 1000 \
|
|
245
205
|
--json-out ./snap-p5
|
|
246
206
|
|
|
247
|
-
#
|
|
207
|
+
# 仅当用户明确给出 ID 子集时才传 -a
|
|
248
208
|
siluzan-tso google-analysis-batch run \
|
|
249
209
|
-a id1,id2,id3,id4 \
|
|
250
210
|
--start <S> --end <D> \
|
|
251
211
|
--sections campaigns,geographic,keywords \
|
|
252
212
|
--json-out ./snap-p5
|
|
253
213
|
```
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
```
|
|
260
|
-
4. **只读查询**当前进度（不发起 HTTP）：
|
|
261
|
-
```bash
|
|
262
|
-
siluzan-tso google-analysis-batch status --json-out ./snap-p5 --run-id <runId>
|
|
263
|
-
```
|
|
264
|
-
5. **产物消费**：每个账户的产物在 `<json-out>/<runId>/results/<accountId>/<section>-<accountId>.json`，配套 `manifest-<accountId>.json` 与 `*.outline.txt`。先读 outline 再写脚本聚合，与单账户 `google-analysis` 完全同口径。
|
|
265
|
-
6. 退出码：`0` 全成功 / `2` 部分成功或 paused / `3` 全失败或 Token 失效 / `4` 用法错误；Agent 据此决定是否继续后续步骤或提示用户 `siluzan-tso login`。
|
|
266
|
-
7. 详细产物结构、错误分类、stdout 协议见 `references/google-analysis-batch.md`。
|
|
214
|
+
3. **中断后只能 resume**：`siluzan-tso google-analysis-batch resume --json-out ./snap-p5 --run-id <runId>`
|
|
215
|
+
4. **只读进度**：`siluzan-tso google-analysis-batch status --json-out ./snap-p5 --run-id <runId>`
|
|
216
|
+
5. **产物消费**：每个账户产物在 `<json-out>/<runId>/results/<accountId>/<section>-<accountId>.json`，配套 `<section>-<accountId>.outline.txt` 与 `manifest-<accountId>.json`。
|
|
217
|
+
- **强制顺序**：先 `fs.readFileSync(outlineFile,'utf8')` 读 outline 的最后一行（TS 式类型，几百字节）→ 再写聚合脚本 → 由脚本 `require()` 真实 JSON 做计算。**禁止**直接 `Read` JSON 看结构——批跑常见 `keywords-*.json` 数 MB × N 账户，几次 `Read` 就把对话窗口塞满。
|
|
218
|
+
- 注意 outline 是 **`.outline.txt`** 不是 `.outline.json`，**禁止 `require()`**；其第 1 行注释明确写了 `// schema-only, NOT the data.`，**禁止**把它当业务数据贴给用户。
|
|
267
219
|
|
|
268
220
|
---
|
|
269
221
|
|
|
270
222
|
## Tips
|
|
271
223
|
|
|
272
|
-
### 账户 ID
|
|
224
|
+
### 账户 ID 示例（通过位数判断类型，不确定再用 `list-accounts -m [mediatype] -k [id]`）
|
|
273
225
|
|
|
274
|
-
|
|
275
|
-
- Google: `454xxx5137` 或 `270-xxx-0720`（使用时去掉 `-` → `270xxx0720`）
|
|
226
|
+
- Google: `454xxx5137` 或 `270-xxx-0720`（去掉 `-`）
|
|
276
227
|
- Tiktok: `70083497xxx59820033`
|
|
277
228
|
- Meta(Facebook): `1716030xxx734076`, `6843984xxx14909`, `479423xxx752348`
|
|
278
229
|
- Bing: `138xxx763`, `1882xxx80`
|
|
279
230
|
- Yandex: `porg-uthxxxrk`
|
|
280
231
|
- Kwai: `act_1716030xxx734076`
|
|
281
232
|
|
|
282
|
-
### 报告模板外部资源
|
|
283
|
-
|
|
284
|
-
以 HTML 为交付物时，`report-templates/*.html` 可能引用外部 CDN（Tailwind CSS、Font Awesome、ECharts、Google Fonts）。离线环境需将资源下载到本地后修改模板引用路径。
|
|
285
|
-
|
|
286
233
|
### 常见 HTTP 状态码
|
|
287
234
|
|
|
288
235
|
- **400**：参数错误，查看对应 reference 或用 `-h` 了解命令用法
|
|
289
|
-
- **401**：平台方返回则需用户重新授权；我方返回则让用户执行 `siluzan-tso login
|
|
236
|
+
- **401**：平台方返回则需用户重新授权；我方返回则让用户执行 `siluzan-tso login`
|
|
290
237
|
- **500**：服务可能正在部署/升级，建议提交给 Siluzan 相关人员
|
|
291
238
|
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
## 风险预警、预算&ROI 控制、异常监控、自动优化、自动化风控
|
|
239
|
+
### 报告模板外部资源
|
|
295
240
|
|
|
296
|
-
|
|
241
|
+
以 HTML 为交付物时，`report-templates/*.html` 可能引用外部 CDN。离线环境需将资源下载到本地后修改模板引用路径。
|
|
297
242
|
|
|
298
|
-
|
|
243
|
+
---
|
|
299
244
|
|
|
300
|
-
|
|
245
|
+
## 风险预警与自动化
|
|
301
246
|
|
|
302
|
-
|
|
247
|
+
详情见 `references/hosted-automation-user-catalog.md`。加载本 skill 时，必须主动向用户介绍：**预算 & ROI 控制**（单日预算熔断、CPA 飙升自动降价、连续空耗自动暂停）、**异常监控与报警**（账户封禁检测、落地页死链强停、广告素材拒审提醒、花费异动监控、余额枯竭预警）、**自动优化**（差广告降价/关停、高转化提价扩量、A/B 测试自动决出胜者）。
|
|
303
248
|
|
|
304
249
|
---
|
|
305
250
|
|
|
306
251
|
## 消息平台语法规范
|
|
307
252
|
|
|
308
|
-
|
|
253
|
+
需 webhook 等方式发送消息时，先阅读对应平台文档获取语法规范：
|
|
309
254
|
- 企业微信：https://developer.work.weixin.qq.com/document/path/99110
|
|
310
255
|
- 飞书：https://open.feishu.cn/document/client-docs/bot-v3/add-custom-bot
|
|
311
256
|
- 其他平台默认使用 markdown 输出
|
package/dist/skill/_meta.json
CHANGED
|
@@ -9,7 +9,9 @@
|
|
|
9
9
|
1. **先确认统计区间**：用户未给明确起止日期时**必须反问**（参见 SKILL.md 时间范围强制反问）。
|
|
10
10
|
2. 确定报告维度（默认含：执行摘要、每日趋势、月度汇总、系列表现、设备分布、地域分布、关键词表现、优化建议），详见 `report-templates/README.md`。
|
|
11
11
|
3. **拉数**：使用 `google-analysis … --json-out <dir>`（Google）或对应 `report <media>-*` 命令落盘。
|
|
12
|
-
4. **编写并执行代码**从磁盘读取 `manifest-<accountId>.json` 与各 `<section>-<accountId>.json
|
|
12
|
+
4. **编写并执行代码**从磁盘读取 `manifest-<accountId>.json` 与各 `<section>-<accountId>.json` 来完成筛选、聚合、排序等计算；**禁止**用 `Read` 看 JSON 后在对话里心算或手填报告数字。
|
|
13
|
+
- **写脚本前先读 `<section>-<accountId>.outline.txt`**（与 JSON 同 stem 的纯文本，最后一行是 TS 式类型字面量）了解字段结构；它体积只有几百字节、不含数据，比直接 `Read` 整个 `*.json`（动辄几 MB / 几万行）省**两到三个数量级**的上下文。**注意是 `.outline.txt` 不是 `.outline.json`**，不要 `require()`，用 `fs.readFileSync(outlineFile,'utf8')` 读最后一行即可。
|
|
14
|
+
- 真实数据始终从 `<section>-<accountId>.json` 由脚本读，**不要**把 outline 当作业务数据贴给用户。
|
|
13
15
|
5. **由代码写出最终文件**（HTML/Excel/PDF/PPT/Markdown 等）。**禁止**在报告脚本中以源码字面量写死应从 JSON 读取的业务数据（消耗金额、系列名、日期区间等）。允许的常量仅限：快照目录路径、JSON 字段键名、版式/结构占位。
|
|
14
16
|
6. **报告首行**须标注：`统计区间：YYYY-MM-DD ~ YYYY-MM-DD（货币：XXX）`，由脚本从 JSON 拼接写入，不得手写常量冒充。
|
|
15
17
|
7. 交付后帮用户打开报告文件。
|
|
@@ -1,43 +1,35 @@
|
|
|
1
1
|
# `google-analysis-batch` —— 多账户 × 多维度 Google 数据批处理引擎
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> 适用：账户数 ≥ 5 且需拉 ≥ 2 个 google-analysis 维度。**禁止**外层 for-loop 替代。中断后**必须** `resume`，不得重跑 `run`。
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
- **单 Node 进程**完成全部 task，复用 keep-alive，不再启动子进程做账户并发
|
|
8
|
-
- **双层并发**：账户级 × 维度级（默认 4 × 6 = 24），自适应降级
|
|
9
|
-
- **断点续跑**：被中断后用 `resume --run-id` 从断点继续，已成功的 task 不重复请求
|
|
10
|
-
- **错误分类**：401 立即终止整批；4xx 永久失败；429/5xx/超时/网络错误指数退避重试
|
|
11
|
-
- **machine-first**：stdout 一行 JSON 摘要；详细进度全部落盘，Agent 通过 `status` 读取
|
|
5
|
+
单 Node 进程，复用 keep-alive，双层并发（账户级 × 维度级），断点续跑，错误自动分类重试。
|
|
12
6
|
|
|
13
7
|
---
|
|
14
8
|
|
|
15
9
|
## 子命令
|
|
16
10
|
|
|
17
|
-
| 子命令
|
|
18
|
-
|
|
19
|
-
| `run`
|
|
20
|
-
| `resume` | 续跑：仅重做 pending / failed_retryable 的 task
|
|
21
|
-
| `status` |
|
|
11
|
+
| 子命令 | 用途 |
|
|
12
|
+
|--------|------|
|
|
13
|
+
| `run` | 首次执行：自动拉账户清单 + 双层并发 + 落盘 |
|
|
14
|
+
| `resume` | 续跑：仅重做 pending / failed_retryable 的 task |
|
|
15
|
+
| `status` | 只读查询进度与失败样例（不发起 HTTP） |
|
|
22
16
|
|
|
23
17
|
---
|
|
24
18
|
|
|
25
19
|
## 命令示例
|
|
26
20
|
|
|
27
|
-
###
|
|
21
|
+
### 获取所有google账号的指定section数据（省略 `-a`，CLI 自动拉账户清单）
|
|
28
22
|
|
|
29
23
|
```bash
|
|
30
24
|
siluzan-tso google-analysis-batch run \
|
|
31
25
|
--start 2026-04-30 --end 2026-05-06 \
|
|
32
26
|
--sections campaigns,geographic,keywords \
|
|
33
|
-
--account-concurrency 4 \
|
|
34
|
-
--
|
|
35
|
-
--keyword-limit 1000 \
|
|
36
|
-
--min-spend 1 \
|
|
27
|
+
--account-concurrency 4 --section-concurrency 6 \
|
|
28
|
+
--keyword-limit 1000 --min-spend 1 \
|
|
37
29
|
--json-out ./snap-batch
|
|
38
30
|
```
|
|
39
31
|
|
|
40
|
-
###
|
|
32
|
+
### 显式指定账户（仅用户给出 ID 子集时）
|
|
41
33
|
|
|
42
34
|
```bash
|
|
43
35
|
siluzan-tso google-analysis-batch run \
|
|
@@ -47,31 +39,7 @@ siluzan-tso google-analysis-batch run \
|
|
|
47
39
|
--json-out ./snap-batch
|
|
48
40
|
```
|
|
49
41
|
|
|
50
|
-
`-a`
|
|
51
|
-
- **跳过**账户清单拉取与余额/消耗查询，直接用传入 ID 构造任务（首条 stderr 提示也会消失）
|
|
52
|
-
- **不应用** `--min-spend` 过滤（即使同时传也无效）
|
|
53
|
-
- 账户元信息（`advertiserName` / `currencyCode` / `spend`）在 `accounts.json` 中为空，因为没拉清单
|
|
54
|
-
- 等价于 `siluzan-tso google-analysis -a id1,id2,id3 --json-out <dir>`，但额外支持 `--run-id` / `--deadline` / `--max-attempts` / 自适应限流
|
|
55
|
-
|
|
56
|
-
参数说明：
|
|
57
|
-
|
|
58
|
-
| 参数 | 说明 | 默认值 |
|
|
59
|
-
| ----------------------------- | -------------------------------------------------------------------- | --------------------------------- |
|
|
60
|
-
| `--json-out <baseDir>` | 必填，产物根目录；每个 runId 一个子目录 | — |
|
|
61
|
-
| `--run-id <id>` | 自定义 runId；留空自动生成 `run-YYYYMMDD-HHmmss-<rand4>` | 自动 |
|
|
62
|
-
| `-a, --accounts <ids>` | 显式 mediaCustomerId 列表（逗号分隔）；传入则跳过清单拉取与 min-spend | 不传=自动拉清单 |
|
|
63
|
-
| `--start` / `--end` | 统计区间（YYYY-MM-DD）；range 类维度未传时回落到 google-analysis 默认 | 近 7 天截至昨天 |
|
|
64
|
-
| `--sections <list>` | 维度（逗号分隔），合法值见 `references/account-analytics.md` | `campaigns,geographic,keywords` |
|
|
65
|
-
| `--account-concurrency <n>` | 账户级并发，1~16 | 4 |
|
|
66
|
-
| `--section-concurrency <n>` | 单账户内维度并发，1~16 | 6 |
|
|
67
|
-
| `--keyword-limit <n>` | 透传给 keywords / search-terms 等大账户场景的条数上限 | google-analysis 默认 |
|
|
68
|
-
| `--min-spend <n>` | 区间消耗 ≤ 此值的账户跳过；0=不过滤（与 `--accounts` 同传时无效） | 0 |
|
|
69
|
-
| `--deadline <duration>` | 整任务硬截止（如 `30m` / `2h` / `90s`），到期未完成标记 paused | 不设 |
|
|
70
|
-
| `--task-timeout-ms <n>` | 单 task 硬超时毫秒 | 60000 |
|
|
71
|
-
| `--max-attempts <n>` | 可重试错误的最大尝试次数 | 3 |
|
|
72
|
-
| `--refresh-dp` | 执行前强制刷新 Datapermission（一般无需） | false |
|
|
73
|
-
| `--no-verbose-progress` | 关闭 stderr 进度条（CI 推荐） | 默认开启 |
|
|
74
|
-
| `-t, --token` | 临时覆盖 Token | 走 ~/.siluzan/config.json |
|
|
42
|
+
`-a` 给定时：跳过清单拉取与余额/消耗查询；不应用 `--min-spend`；`accounts.json` 元信息为空。**任何情况下都不要**先 `list-accounts` 再把全部 ID 拼进 `-a`。
|
|
75
43
|
|
|
76
44
|
### 中断后续跑
|
|
77
45
|
|
|
@@ -79,68 +47,83 @@ siluzan-tso google-analysis-batch run \
|
|
|
79
47
|
siluzan-tso google-analysis-batch resume --json-out ./snap-batch --run-id <runId>
|
|
80
48
|
```
|
|
81
49
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
1. 从 `state/tasks.jsonl` 重建每个 task 的"最后一次状态"
|
|
85
|
-
2. 跳过 `success` / `failed_permanent` / `skipped` 的 task
|
|
86
|
-
3. 重新派发 `pending` / `running` / `failed_retryable` 的 task（`running` 是上次进程被强杀留下的"幽灵"状态）
|
|
50
|
+
从 `state/tasks.jsonl` 重建状态，跳过 success / failed_permanent / skipped，重做 pending / running / failed_retryable。
|
|
87
51
|
|
|
88
|
-
###
|
|
52
|
+
### 只读进度
|
|
89
53
|
|
|
90
54
|
```bash
|
|
91
55
|
siluzan-tso google-analysis-batch status --json-out ./snap-batch --run-id <runId>
|
|
92
56
|
```
|
|
93
57
|
|
|
94
|
-
|
|
58
|
+
不发起 HTTP，只读 `progress.json` + `tasks.jsonl`。
|
|
95
59
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 参数
|
|
63
|
+
|
|
64
|
+
| 参数 | 说明 | 默认值 |
|
|
65
|
+
|------|------|--------|
|
|
66
|
+
| `--json-out <dir>` | 必填，产物根目录 | — |
|
|
67
|
+
| `--run-id <id>` | 自定义 runId | 自动 `run-YYYYMMDD-HHmmss-<rand4>` |
|
|
68
|
+
| `-a, --accounts <ids>` | 显式 ID 列表；传入则跳过清单拉取与 `--min-spend` | 省略时自动拉全量 Google 账号 |
|
|
69
|
+
| `--start` / `--end` | 统计区间（YYYY-MM-DD） | 近 7 天截至昨天 |
|
|
70
|
+
| `--sections <list>` | 维度（逗号分隔），合法值见 `references/account-analytics.md` | `campaigns,geographic,keywords` |
|
|
71
|
+
| `--account-concurrency <n>` | 账户级并发（1~16） | 4 |
|
|
72
|
+
| `--section-concurrency <n>` | 单账户内维度并发（1~16） | 6 |
|
|
73
|
+
| `--keyword-limit <n>` | keywords / search-terms 条数上限 | google-analysis 默认 |
|
|
74
|
+
| `--min-spend <n>` | 区间消耗 ≤ 此值跳过（与 `-a` 同传无效） | 0 |
|
|
75
|
+
| `--deadline <dur>` | 整任务硬截止（如 `30m` / `2h`），到期标记 paused | 不设 |
|
|
76
|
+
| `--task-timeout-ms <n>` | 单 task 硬超时 | 60000 |
|
|
77
|
+
| `--max-attempts <n>` | 可重试错误最大尝试次数 | 3 |
|
|
78
|
+
| `--refresh-dp` | 执行前强制刷新 Datapermission | false |
|
|
79
|
+
| `--no-verbose-progress` | 关闭 stderr 进度条（CI 推荐） | false |
|
|
80
|
+
| `-t, --token` | 临时覆盖 Token | `~/.siluzan/config.json` |
|
|
110
81
|
|
|
111
82
|
---
|
|
112
83
|
|
|
113
|
-
##
|
|
84
|
+
## 产物目录
|
|
114
85
|
|
|
115
86
|
```
|
|
116
87
|
<json-out>/<runId>/
|
|
117
|
-
├── run-manifest.json #
|
|
118
|
-
├── progress.json # 实时进度（每 5
|
|
119
|
-
├── accounts.json #
|
|
120
|
-
├── results
|
|
121
|
-
│
|
|
122
|
-
│
|
|
123
|
-
│
|
|
124
|
-
|
|
125
|
-
│
|
|
126
|
-
│ ├── keywords-<accountId>.json
|
|
127
|
-
│ ├── keywords-<accountId>.outline.txt
|
|
128
|
-
│ └── manifest-<accountId>.json
|
|
129
|
-
├── errors/
|
|
130
|
-
│ └── <accountId>/
|
|
131
|
-
│ └── <section>.error.json # 失败 task 的详情（class/status/message/attempts）
|
|
88
|
+
├── run-manifest.json # 参数、账户总数、限流配置
|
|
89
|
+
├── progress.json # 实时进度（每 5 task 原子刷新）
|
|
90
|
+
├── accounts.json # 筛选后账户清单
|
|
91
|
+
├── results/<accountId>/
|
|
92
|
+
│ ├── <section>-<accountId>.json # 与 google-analysis 同口径
|
|
93
|
+
│ ├── <section>-<accountId>.outline.txt
|
|
94
|
+
│ └── manifest-<accountId>.json
|
|
95
|
+
├── errors/<accountId>/
|
|
96
|
+
│ └── <section>.error.json # class / status / message / attempts
|
|
132
97
|
└── state/
|
|
133
|
-
├── tasks.jsonl
|
|
134
|
-
└── tasks.lock
|
|
98
|
+
├── tasks.jsonl # 事件溯源日志
|
|
99
|
+
└── tasks.lock # 运行时锁
|
|
135
100
|
```
|
|
136
101
|
|
|
137
|
-
|
|
102
|
+
**产物消费（Agent 强制顺序）**：先读 `*.outline.txt` 了解字段类型 → 再写聚合脚本 → 由脚本读 `<section>-<accountId>.json`。与单账户 `google-analysis` 完全同口径。
|
|
103
|
+
|
|
104
|
+
**为什么先读 outline 而不是直接 `Read` JSON**：
|
|
105
|
+
|
|
106
|
+
- `*.outline.txt` 是与 `*.json` **同 stem 的纯文本**（**注意扩展名 `.txt` 不是 `.json`，不要 `require()`**），最后一行是 TS 式类型字面量（如 `{ items: { id: number; spend: number; ... }[]; meta: { ... } }`），通常几百字节。
|
|
107
|
+
- 真实 `<section>-<accountId>.json` 在批跑场景常见 `keywords-*.json` 数 MB、`campaigns-*.json` × N 账户合计几十万行，`Read` 会**几次就把对话窗口塞满**，还有截断风险。
|
|
108
|
+
- 读 outline 节省 **2~3 个数量级**的上下文 token，足够你确定字段路径再写脚本聚合。
|
|
109
|
+
|
|
110
|
+
读 outline 的最小写法（脚本里也只读最后一行）：
|
|
111
|
+
|
|
112
|
+
```js
|
|
113
|
+
const fs = require('node:fs');
|
|
114
|
+
// outlineFile 来自 manifest-<accountId>.json 的 sections[].outlineFile
|
|
115
|
+
const outline = fs.readFileSync(outlineFile, 'utf8');
|
|
116
|
+
const tsType = outline.trimEnd().split('\n').filter(l => !l.startsWith('//')).pop();
|
|
117
|
+
// tsType 形如：{ items: { id: number; spend: number; ... }[]; meta: { ... } }
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
**禁止**：把 outline 内容当业务数据贴给用户当结论（第 1 行注释明确写了 `// outline of \`<xxx>.json\` — schema-only, NOT the data.`）。
|
|
138
121
|
|
|
139
122
|
---
|
|
140
123
|
|
|
141
124
|
## stdout 摘要协议
|
|
142
125
|
|
|
143
|
-
`run` / `resume` / `status` 的 stdout
|
|
126
|
+
`run` / `resume` / `status` 的 stdout 始终一行 JSON（`kind=siluzan-tso-batch-summary`）：
|
|
144
127
|
|
|
145
128
|
```json
|
|
146
129
|
{
|
|
@@ -153,96 +136,76 @@ siluzan-tso google-analysis-batch status --json-out ./snap-batch --run-id <runId
|
|
|
153
136
|
"tokenInvalidated": false,
|
|
154
137
|
"elapsedMs": 423000,
|
|
155
138
|
"stats": {
|
|
156
|
-
"totalTasks": 468,
|
|
157
|
-
"
|
|
158
|
-
"
|
|
159
|
-
"failedRetryable": 2,
|
|
160
|
-
"skipped": 0,
|
|
161
|
-
"throttleEvents": 1
|
|
139
|
+
"totalTasks": 468, "success": 462,
|
|
140
|
+
"failedPermanent": 4, "failedRetryable": 2,
|
|
141
|
+
"skipped": 0, "throttleEvents": 1
|
|
162
142
|
}
|
|
163
143
|
}
|
|
164
144
|
```
|
|
165
145
|
|
|
166
|
-
|
|
146
|
+
进度详情读 `progress.json` 与 `state/tasks.jsonl`，不在 stdout。
|
|
167
147
|
|
|
168
148
|
---
|
|
169
149
|
|
|
170
|
-
##
|
|
150
|
+
## 退出码
|
|
171
151
|
|
|
172
|
-
|
|
|
173
|
-
|
|
174
|
-
| `0`
|
|
175
|
-
| `2`
|
|
176
|
-
| `3`
|
|
177
|
-
| `4`
|
|
152
|
+
| 码 | 含义 | 后续动作 |
|
|
153
|
+
|----|------|---------|
|
|
154
|
+
| `0` | 全部成功，state=`succeeded` | 继续后续 |
|
|
155
|
+
| `2` | 部分成功（`partial`）或超时（`paused`） | 看 `errors/` 或消费已有产物 |
|
|
156
|
+
| `3` | 全失败 / Token 失效 / 致命错误（`failed`） | `tokenInvalidated:true` → `siluzan-tso login` |
|
|
157
|
+
| `4` | 参数错误（命令未执行） | 修正参数重试 |
|
|
178
158
|
|
|
179
159
|
---
|
|
180
160
|
|
|
181
161
|
## 错误分类与重试
|
|
182
162
|
|
|
183
|
-
| 分类
|
|
184
|
-
|
|
185
|
-
| `abort`
|
|
186
|
-
| `failed_permanent` | HTTP 400 / 403 / 404
|
|
187
|
-
| `failed_retryable` | HTTP 408 / 429 / 5xx / 超时 / 网络错误
|
|
188
|
-
| `skipped`
|
|
163
|
+
| 分类 | 触发条件 | 处理 |
|
|
164
|
+
|------|---------|------|
|
|
165
|
+
| `abort` | HTTP 401 | **立即终止整批**，`tokenInvalidated:true`，可 resume |
|
|
166
|
+
| `failed_permanent` | HTTP 400 / 403 / 404 | 不重试，记入 `errors/` |
|
|
167
|
+
| `failed_retryable` | HTTP 408 / 429 / 5xx / 超时 / 网络错误 | 指数退避 `1s × 2^attempt + jitter`（cap 30s），最多 `--max-attempts` 次 |
|
|
168
|
+
| `skipped` | `invalidOAuthToken=true` 或被 `--min-spend` 过滤 | 不发起 HTTP |
|
|
189
169
|
|
|
190
|
-
**自适应降级**：滚动 20
|
|
170
|
+
**自适应降级**：滚动 20 task 内错误率 ≥ 30% → 账户并发与维度并发同时减半；冷却 60s。`progress.throttleEvents` 记录次数。
|
|
191
171
|
|
|
192
172
|
---
|
|
193
173
|
|
|
194
174
|
## 与 google-analysis 的关系
|
|
195
175
|
|
|
196
|
-
`google-analysis`
|
|
176
|
+
`google-analysis` 会根据 `-a` 的 ID 数量自动选路，底层共享同一引擎：
|
|
197
177
|
|
|
198
|
-
|
|
|
199
|
-
|
|
200
|
-
|
|
|
201
|
-
| 调度
|
|
202
|
-
| 失败处理
|
|
203
|
-
| 中断恢复
|
|
204
|
-
| stdout
|
|
205
|
-
|
|
|
206
|
-
| Resume 能力 | — | 用 `google-analysis-batch resume --run-id <runId>` | 同左 |
|
|
178
|
+
| | `google-analysis -a <单ID>` | `google-analysis -a id1,id2,id3` | `google-analysis-batch run` |
|
|
179
|
+
|--------|------|------|------|
|
|
180
|
+
| 账户数 | 1 | 2~10 | 任意（含 0→自动拉全量） |
|
|
181
|
+
| 调度 | 单账户多维度 | 双层并发 | 双层并发 |
|
|
182
|
+
| 失败处理 | 抛错 | 自动分类 + 退避 + 401 终止 | 同左 |
|
|
183
|
+
| 中断恢复 | 不支持 | `resume` | `resume` |
|
|
184
|
+
| stdout | snapshot-batch | `siluzan-tso-batch-summary`（含 `forwardedFrom`） | `siluzan-tso-batch-summary` |
|
|
185
|
+
| 产物 | `<dir>/<section>-<id>.json` | `<dir>/<runId>/results/<accountId>/<section>-<id>.json` | 同左 |
|
|
207
186
|
|
|
208
|
-
|
|
187
|
+
单 section JSON 结构完全一致，仅目录组织不同。
|
|
209
188
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
- 1 个账户 → `google-analysis -a id`（最简，无 runId 子目录）
|
|
213
|
-
- 2~10 个账户 + 一次性出报告 → `google-analysis -a id1,id2,...`（隐式走 batch，仍是 stdout 单行 JSON）
|
|
214
|
-
- ≥ 10 个账户、需要 `--deadline` / `--max-attempts` / `--run-id` / 中途 resume → 直接用 `google-analysis-batch run`
|
|
189
|
+
**选用**：1 账户 → `google-analysis -a id`；2~10 子集 → `google-analysis -a id1,id2,...`（隐式 batch）；≥10 子集/需 resume → `google-analysis-batch run -a id1,id2,...`；全量 → `google-analysis-batch run`（省略 `-a`）。
|
|
215
190
|
|
|
216
191
|
---
|
|
217
192
|
|
|
218
193
|
## 常见问题
|
|
219
194
|
|
|
220
|
-
**Q
|
|
221
|
-
A
|
|
222
|
-
|
|
223
|
-
**Q：怎么知道上次的 runId？**
|
|
224
|
-
A：上次 `run` stdout 摘要里的 `runId` 字段；或浏览 `--json-out` 目录下最新的 `run-*` 子目录名。
|
|
225
|
-
|
|
226
|
-
**Q：401 触发整批终止后，是否需要重新跑全量？**
|
|
227
|
-
A：不需要。
|
|
228
|
-
1. `siluzan-tso login` 重新登录
|
|
229
|
-
2. `siluzan-tso google-analysis-batch resume --run-id <id> --refresh-dp` 续跑剩余 task
|
|
195
|
+
**Q：拉全量是不是先 `list-accounts` 再把 ID 拼进 `-a`？**
|
|
196
|
+
A：**不要**。`run` 不传 `-a` 时内部自动拉清单+余额+消耗，先 `list-accounts` 只是重复请求。直接 `google-analysis-batch run ...` 即可。
|
|
230
197
|
|
|
231
|
-
**Q：
|
|
232
|
-
A
|
|
198
|
+
**Q：Ctrl+C 后能否重新 `run`？**
|
|
199
|
+
A：**不能**。会生成新 runId，所有 task 从零开始。只能 `resume --run-id <旧id>`。
|
|
233
200
|
|
|
234
|
-
**Q
|
|
235
|
-
A
|
|
201
|
+
**Q：怎么知道上次 runId？**
|
|
202
|
+
A：上次 stdout 摘要的 `runId` 字段，或浏览 `--json-out` 下最新 `run-*` 目录名。
|
|
236
203
|
|
|
237
|
-
**Q：
|
|
238
|
-
A
|
|
239
|
-
- `class=permanent` → 通常是账户权限或参数问题，对该账户单独排查
|
|
240
|
-
- `class=retryable` 但仍失败 → 通常是网络或服务端持续不稳定，过段时间 `resume` 即可
|
|
241
|
-
|
|
242
|
-
---
|
|
204
|
+
**Q：401 后需要重跑全量吗？**
|
|
205
|
+
A：不需要。`siluzan-tso login` 后 `resume --run-id <id> --refresh-dp` 即可。
|
|
243
206
|
|
|
244
|
-
|
|
207
|
+
**Q：accounts.json 何时快照？能否手工改账户范围再 resume？**
|
|
208
|
+
A：首次 `run` 时写入并定型。要改账户范围，新建 runId 重新 `run`。
|
|
245
209
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
- 401 后整批终止，需 `login` 后再 resume（见 SKILL.md 退出码描述）
|
|
210
|
+
**Q：errors 文件能做什么？**
|
|
211
|
+
A：`class=permanent` → 对账户单独排查权限/参数；`class=retryable` 仍失败 → 过段时间 `resume`。
|