siluzan-tso-cli 1.1.46-beta.8 → 1.1.47-beta.1
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/README.md +1 -1
- package/dist/index.js +6 -32
- package/dist/skill/SKILL.md +1 -1
- package/dist/skill/_meta.json +2 -2
- package/dist/skill/references/accounts/accounts-balance-stats.md +1 -1
- package/dist/skill/references/accounts/accounts-permissions.md +2 -0
- package/dist/skill/references/accounts/accounts.md +1 -1
- package/dist/skill/references/analytics/account-analytics.md +6 -7
- package/dist/skill/references/core/agent-conventions.md +4 -4
- package/dist/skill/references/operations/hosted-automation-bing.md +1 -1
- package/dist/skill/references/report-templates/bing-period-report.md +4 -4
- package/dist/skill/report-templates/bing-period-report.md +4 -4
- package/dist/skill/report-templates/report-template-dark.html +1 -1
- package/dist/skill/report-templates/report-template-mobile.html +1 -1
- package/dist/skill/report-templates/report-template-print.html +1 -1
- package/dist/skill/scripts/install.ps1 +1 -1
- package/dist/skill/scripts/install.sh +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -51,7 +51,7 @@ siluzan-tso init -d /path/to/skills # 写入自定义目录
|
|
|
51
51
|
siluzan-tso init --force # 强制覆盖已存在文件
|
|
52
52
|
```
|
|
53
53
|
|
|
54
|
-
> **注意**:当前为测试版(1.1.
|
|
54
|
+
> **注意**:当前为测试版(1.1.47-beta.1),供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
|
|
55
55
|
|
|
56
56
|
| 助手 | 建议 `--ai` |
|
|
57
57
|
| ----------------------- | ------------------------------------ |
|
package/dist/index.js
CHANGED
|
@@ -132184,23 +132184,6 @@ function formatLocalYmd(d) {
|
|
|
132184
132184
|
const day = String(d.getDate()).padStart(2, "0");
|
|
132185
132185
|
return `${y}-${m}-${day}`;
|
|
132186
132186
|
}
|
|
132187
|
-
function bingRangeTouchesTodayOrYesterday(startDate, endDate) {
|
|
132188
|
-
const s = parseLocalYmd(startDate);
|
|
132189
|
-
const e = parseLocalYmd(endDate);
|
|
132190
|
-
if (Number.isNaN(s.getTime()) || Number.isNaN(e.getTime()) || s > e) {
|
|
132191
|
-
return true;
|
|
132192
|
-
}
|
|
132193
|
-
const today = stripLocalDate(/* @__PURE__ */ new Date());
|
|
132194
|
-
const yesterday = new Date(today);
|
|
132195
|
-
yesterday.setDate(yesterday.getDate() - 1);
|
|
132196
|
-
for (let cur = new Date(s); cur <= e; cur.setDate(cur.getDate() + 1)) {
|
|
132197
|
-
const c = stripLocalDate(cur);
|
|
132198
|
-
if (c.getTime() === today.getTime() || c.getTime() === yesterday.getTime()) {
|
|
132199
|
-
return true;
|
|
132200
|
-
}
|
|
132201
|
-
}
|
|
132202
|
-
return false;
|
|
132203
|
-
}
|
|
132204
132187
|
function resolveBingDateRange(start, end, allowToday = false) {
|
|
132205
132188
|
if (start && end) {
|
|
132206
132189
|
const s = parseLocalYmd(start);
|
|
@@ -132213,12 +132196,6 @@ function resolveBingDateRange(start, end, allowToday = false) {
|
|
|
132213
132196
|
console.error("\n\u274C \u5F00\u59CB\u65E5\u671F\u4E0D\u80FD\u665A\u4E8E\u7ED3\u675F\u65E5\u671F\u3002\n");
|
|
132214
132197
|
process.exit(1);
|
|
132215
132198
|
}
|
|
132216
|
-
if (!allowToday && bingRangeTouchesTodayOrYesterday(start, end)) {
|
|
132217
|
-
console.error(
|
|
132218
|
-
"\n\u274C Bing \u62A5\u8868\u65F6\u95F4\u8303\u56F4\u4E0D\u80FD\u5305\u542B\u300C\u4ECA\u5929\u300D\u6216\u300C\u6628\u5929\u300D\uFF08\u63A5\u53E3\u9650\u5236\uFF09\u3002\u8BF7\u6539\u7528\u66F4\u65E9\u7684\u7ED3\u675F\u65E5\u671F\uFF0C\u4F8B\u5982\u524D\u5929\u53CA\u4EE5\u524D\uFF1B\u82E5\u9700\u67E5\u4ECA\u5929/\u8FD1\u5B9E\u65F6\u6570\u636E\uFF0C\u5BF9 campaigns/ad-groups/ads \u4F20 --aggregation \u6216 --return-only-complete-data\u3002\n"
|
|
132219
|
-
);
|
|
132220
|
-
process.exit(1);
|
|
132221
|
-
}
|
|
132222
132199
|
return { startDate: start, endDate: end };
|
|
132223
132200
|
}
|
|
132224
132201
|
if (!start && !end) {
|
|
@@ -132227,13 +132204,13 @@ function resolveBingDateRange(start, end, allowToday = false) {
|
|
|
132227
132204
|
return { startDate: today, endDate: today };
|
|
132228
132205
|
}
|
|
132229
132206
|
const endD = stripLocalDate(/* @__PURE__ */ new Date());
|
|
132230
|
-
endD.setDate(endD.getDate() -
|
|
132207
|
+
endD.setDate(endD.getDate() - 1);
|
|
132231
132208
|
const startD = new Date(endD);
|
|
132232
132209
|
startD.setDate(startD.getDate() - 6);
|
|
132233
132210
|
return { startDate: formatLocalYmd(startD), endDate: formatLocalYmd(endD) };
|
|
132234
132211
|
}
|
|
132235
132212
|
console.error(
|
|
132236
|
-
"\n\u274C --start \u4E0E --end \u987B\u540C\u65F6\u4F20\u5165\uFF0C\u6216\u540C\u65F6\u7701\u7565\u4EE5\u4F7F\u7528\u9ED8\u8BA4\u533A\u95F4\uFF08\u622A\u81F3\
|
|
132213
|
+
"\n\u274C --start \u4E0E --end \u987B\u540C\u65F6\u4F20\u5165\uFF0C\u6216\u540C\u65F6\u7701\u7565\u4EE5\u4F7F\u7528\u9ED8\u8BA4\u533A\u95F4\uFF08\u622A\u81F3\u6628\u5929\u5171 7 \u5929\uFF09\u3002\n"
|
|
132237
132214
|
);
|
|
132238
132215
|
process.exit(1);
|
|
132239
132216
|
}
|
|
@@ -132304,9 +132281,6 @@ async function enrichBingOverviewPreviousPeriod(config, accountId, record2, star
|
|
|
132304
132281
|
}
|
|
132305
132282
|
const prevRange = calcBingPreviousPeriodRange(startDate, endDate);
|
|
132306
132283
|
if (!prevRange) return record2;
|
|
132307
|
-
if (bingRangeTouchesTodayOrYesterday(prevRange.startDate, prevRange.endDate)) {
|
|
132308
|
-
return record2;
|
|
132309
|
-
}
|
|
132310
132284
|
try {
|
|
132311
132285
|
const params = new URLSearchParams({
|
|
132312
132286
|
startDate: prevRange.startDate,
|
|
@@ -133340,7 +133314,7 @@ function registerBatchCommand2(sectionHelp, aliasHelp) {
|
|
|
133340
133314
|
"\u7ED3\u679C\u843D\u76D8\u76EE\u5F55\uFF1B\u6BCF\u7EF4\u5EA6 `<section>-<accountId>.json` + `report-manifest-<accountId>.json`"
|
|
133341
133315
|
).option("-t, --token <token>", "Auth Token").option(
|
|
133342
133316
|
"--start <date>",
|
|
133343
|
-
"\u5F00\u59CB\u65E5\u671F YYYY-MM-DD\uFF08\u4E0E --end \u540C\u4F20\u6216\u540C\u7701\u7565\uFF1B\
|
|
133317
|
+
"\u5F00\u59CB\u65E5\u671F YYYY-MM-DD\uFF08\u4E0E --end \u540C\u4F20\u6216\u540C\u7701\u7565\uFF1B\u53EF\u542B\u6628\u5929/\u4ECA\u5929\uFF0C\u6570\u636E\u53EF\u80FD\u4E0D\u5B8C\u6574\uFF1B\u7701\u7565=\u622A\u81F3\u6628\u5929\u8FD1 7 \u5929\uFF09"
|
|
133344
133318
|
).option("--end <date>", "\u7ED3\u675F\u65E5\u671F YYYY-MM-DD").option(
|
|
133345
133319
|
"--sections <list>",
|
|
133346
133320
|
`\u4EC5\u6267\u884C\u6307\u5B9A\u7EF4\u5EA6\uFF08\u9017\u53F7\u5206\u9694\uFF09\uFF0C\u5982 overview,campaigns,keywords\uFF1B\u7701\u7565=\u5168\u90E8 11 \u4E2A\u3002\u53EF\u9009\uFF1A${sectionHelp}\uFF1B\u522B\u540D\uFF1A${aliasHelp}`
|
|
@@ -133350,10 +133324,10 @@ function registerBatchCommand2(sectionHelp, aliasHelp) {
|
|
|
133350
133324
|
(v) => parseInt(v, 10)
|
|
133351
133325
|
).option("--concurrency <n>", "\u5E76\u53D1\u6570\uFF0C\u9ED8\u8BA4 5\uFF0C\u4E0A\u9650 16", (v) => parseInt(v, 10)).option(
|
|
133352
133326
|
"--aggregation <value>",
|
|
133353
|
-
"\u4EC5 campaigns/ad-groups/ads\uFF1A\u5B98\u65B9 ReportAggregation\uFF08Summary \u9ED8\u8BA4/Daily/Hourly/Weekly \u7B49\uFF09\uFF1B\u4F20\u5165\
|
|
133327
|
+
"\u4EC5 campaigns/ad-groups/ads\uFF1A\u5B98\u65B9 ReportAggregation\uFF08Summary \u9ED8\u8BA4/Daily/Hourly/Weekly \u7B49\uFF09\uFF1B\u4F20\u5165\u4E14\u7701\u7565\u65E5\u671F\u65F6\u9ED8\u8BA4\u4ECA\u5929\u5F53\u5929\uFF0C\u7528\u4E8E\u8FD1\u5B9E\u65F6\u76D1\u63A7"
|
|
133354
133328
|
).option(
|
|
133355
133329
|
"--return-only-complete-data <bool>",
|
|
133356
|
-
"\u4EC5 campaigns/ad-groups/ads\uFF1Atrue/false\uFF0C\u663E\u5F0F\u8986\u76D6\u7F51\u5173\
|
|
133330
|
+
"\u4EC5 campaigns/ad-groups/ads\uFF1Atrue/false\uFF0C\u663E\u5F0F\u8986\u76D6\u7F51\u5173\u6309\u65E5\u671F\u81EA\u52A8\u5224\u65AD\uFF1B\u542B\u6628\u5929/\u4ECA\u5929\u65F6\u4E0D\u8981\u4F20 true"
|
|
133357
133331
|
).option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF\u4FE1\u606F", false).action(
|
|
133358
133332
|
async (opts) => {
|
|
133359
133333
|
await runAllBingSections({
|
|
@@ -133367,7 +133341,7 @@ function registerBingAnalysisCommands(program2) {
|
|
|
133367
133341
|
const sectionHelp = BING_SECTION_NAMES.join(", ");
|
|
133368
133342
|
const aliasHelp = Object.keys(BING_SECTION_ALIASES).join(", ");
|
|
133369
133343
|
const root = program2.command("bing-analysis").description(
|
|
133370
|
-
"Bing\uFF08BingV2\uFF09\u8D26\u6237\u5206\u6790\uFF1A\u6279\u91CF\u62C9\u53D6 Section \u62A5\u8868\u6570\u636E\uFF08\u9ED8\u8BA4\
|
|
133344
|
+
"Bing\uFF08BingV2\uFF09\u8D26\u6237\u5206\u6790\uFF1A\u6279\u91CF\u62C9\u53D6 Section \u62A5\u8868\u6570\u636E\uFF08\u9ED8\u8BA4\u622A\u81F3\u6628\u5929\u8FD1 7 \u5929\uFF0C\u53EF\u542B\u6628\u5929/\u4ECA\u5929\uFF09\u3001\u7531 render \u751F\u6210 bing-period-report.html \u7EC8\u7A3F\uFF0C\u6216\u67E5\u8BE2\u8D26\u6237\u72B6\u6001/\u7CFB\u5217\u4E0E\u5E7F\u544A\u539F\u59CB\u5B9E\u4F53/\u62D2\u5BA1 Bulk \u5DE1\u68C0/IO/\u6708\u6D88\u8017"
|
|
133371
133345
|
);
|
|
133372
133346
|
root.addCommand(registerBatchCommand2(sectionHelp, aliasHelp), { isDefault: true });
|
|
133373
133347
|
root.command("render").description(
|
package/dist/skill/SKILL.md
CHANGED
|
@@ -40,7 +40,7 @@ siluzan-tso -h
|
|
|
40
40
|
|
|
41
41
|
- `entityId`(UUID)≠ `mediaCustomerId`(`list-accounts` 的 `ma.mediaCustomerId`:Google/TikTok/Bing 多为数字;**Yandex=`porg-…`**;Meta 常带 `act_`)。`stats`/`balance`/`accounts-digest`/`ad *` 的 `-a` **只传 mediaCustomerId**;空结果或 verbose 打出 403 时**先核验 ID**,禁止把 UUID/`entityId` 传给 `-a`,也**禁止**据此直接 `reauth`。
|
|
42
42
|
- **Google CID 特殊性**:UI 常写 `123-456-7890`(带连字符),平台 `mediaCustomerId` 为纯数字 `1234567890`。CLI 会自动去连字符;**勿**把带横杠 403 误判为 OAuth 失效。优先用 `list-accounts` 的纯数字 ID。
|
|
43
|
-
- **禁止臆测授权过期**:见 403/`HTTP 403`/拉数失败/「可能 OAuth 失效」时,**禁止**口头推断授权过期或直接 `reauth`。须先核验 ID(及 Google
|
|
43
|
+
- **禁止臆测授权过期**:见 403/`HTTP 403`/拉数失败/「可能 OAuth 失效」时,**禁止**口头推断授权过期或直接 `reauth`。须先核验 ID(及 Google 连字符)。**`account check-access` 仅支持 Google**(无 `-m`,禁止对 TikTok/Meta/Bing/Yandex/Kwai 调用):Google 跑 `account check-access -a <mediaCustomerId>`,以 `accessible` / `reauth_required` / `no_permission` 为准;非 Google 看 `list-accounts` 的 `invalidOAuthToken`。仅当 `list-accounts` 输出含激活字段且可判定未激活时才跳过用其判断授权过期;细则见 `accounts-permissions.md`。
|
|
44
44
|
- **Google 广告命令名**:列表是 `ad campaigns`(不是 `ad-campaigns` / `campaign list`);`balance`/`stats` 须带 `-m Google`;单国地域用 `ad geo search … --json-out`(或 `geo resolve`)。
|
|
45
45
|
- **Google 广告类型边界**:CLI/Skill **仅支持** Google **搜索广告(Search)** 与 **Performance Max(PMax)** 的方案、创建与精细管理;**不支持展示广告(Display)**(含自适应展示广告 RDA、独立 Display 系列)。用户要做展示广告时须明确告知不支持,可改推 Search / PMax;**禁止**用 `campaign-create` / `ad-create` 伪装创建 Display。
|
|
46
46
|
- **创建完成后交付(硬性)**:`ad batch diff` 的 stdout 含 `BEGIN_USER_DELIVERY_MARKDOWN`…`END_USER_DELIVERY_MARKDOWN`——**立刻**把中间全文原样发给用户(可先于补建);禁止只摘要、禁止只说「创建成功/详情已交付/未发现缺失」、禁止等全部补建结束再交付。
|
package/dist/skill/_meta.json
CHANGED
|
@@ -160,7 +160,7 @@ siluzan-tso accounts-digest -m Google --start 2026-07-20 --end 2026-07-20 \
|
|
|
160
160
|
>
|
|
161
161
|
> - **Google**:走 `account-spend-overview`;`--start` / `--end` 日历日按 **UTC+8** 转为 `YYYY-MM-DDTHH:mm:ss+08:00` 再请求(起 00:00:00、止 23:59:59,含今天时 end 截到当前时刻)。与 `google-analysis`(只传年月日)口径不同。
|
|
162
162
|
> - 窗口完全在历史 → `database` 模式;窗口含今天 → `googleCombined` 模式(仅实时消耗,无余额/状态/币种/账户名)。
|
|
163
|
-
> - **TikTok / Yandex / BingV2 / Kwai**:走旧版 `accountsoverview
|
|
163
|
+
> - **TikTok / Yandex / BingV2 / Kwai**:走旧版 `accountsoverview`,每日凌晨同步昨天数据,**不能查今天**。Bing 看昨天/今天消耗用 `bing-analysis`(数据可能不完整);TikTok 用 `tiktok-analysis official-report`。Google「今天」仍走 `google-analysis(-batch) --sections overview`。
|
|
164
164
|
> - 完整时效性表见 `references/analytics/account-analytics.md` 顶部。
|
|
165
165
|
|
|
166
166
|
```bash
|
|
@@ -33,6 +33,8 @@ siluzan-tso account me --check-phone 15130150466 --json-out ./snap-me
|
|
|
33
33
|
|
|
34
34
|
### check-access — Google 账户访问权限校验
|
|
35
35
|
|
|
36
|
+
**仅支持 Google。** 无 `-m`;`-a` 只接受 Google 纯数字 `mediaCustomerId`。TikTok / MetaAd / BingV2 / Yandex / Kwai **禁止**调用本命令,授权是否失效看 `list-accounts` 的 `invalidOAuthToken`。
|
|
37
|
+
|
|
36
38
|
校验当前丝路赞凭据是否对指定 **Google** 广告账户有访问权限。应在拉数/诊断前调用,避免误用他户 ID。
|
|
37
39
|
|
|
38
40
|
> **硬约束**:**禁止**凭 403、空结果或经验臆测「授权/OAuth 过期」。要对用户下「授权不可用 / 需重授权」结论前,**必须**先跑本命令,以 CLI 返回的 `status` 为准;**禁止**跳过本命令直接 `reauth` 或口头推断。
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
- `entityId`(UUID,分享/delink/账单/`reauth`)≠ `mediaCustomerId`(`balance`/`stats`/`accounts-digest`/`ad` 的 `-a`)。**Yandex 的 mediaCustomerId 形如 `porg-…`,不是 UUID。**
|
|
21
21
|
- MetaAd OAuth 户的 `mediaCustomerId` **须带 `act_` 前缀**。
|
|
22
22
|
- **Google CID**:广告后台展示常为 `XXX-XXX-XXXX`(连字符),`list-accounts` / 网关要的是**纯数字**(无横杠)。`stats`/`balance`/`ad *`/`google-analysis` 的 `-a` 可带连字符(CLI 会去掉);若仍见 `HTTP 403:123-456-7890` 这类**回显带横杠 ID**,优先改成纯数字重试,**不要**直接当 OAuth 失效去 `reauth`。
|
|
23
|
-
- **禁止臆测授权过期**:403 / 拉数失败时**禁止**口头说「可能授权过期」。须 ID
|
|
23
|
+
- **禁止臆测授权过期**:403 / 拉数失败时**禁止**口头说「可能授权过期」。须 ID 核验后,**仅 Google** 执行 `account check-access -a <mediaCustomerId>`(无 `-m`,其他媒体禁止调用),以返回 `status` 为准(见 [`accounts-permissions.md`](accounts-permissions.md));仅当 `list-accounts` 输出含激活字段且可判定未激活时,勿用其判断授权过期;非 Google 看 `invalidOAuthToken`。
|
|
24
24
|
- `stats`/`balance` 空结果 + verbose `HTTP 403`:先确认 `-a` 是否为 `ma.mediaCustomerId`(且 Google 已去连字符);**禁止**把 `entityId` / tokenId 当 `-a`;未跑 `account check-access`(或未见 `invalidOAuthToken=true`)**禁止** `reauth`。
|
|
25
25
|
- 多账户余额预警用 `balance-scan`(P2),多账户消耗汇总用 `accounts-digest`(P3);**禁止**外层 for-loop 逐户 `balance`/`stats`。
|
|
26
26
|
- `stats` 默认 `spend` = **区间合计**,不是日消耗;日均看 `balance-scan.dailySpend` 或合计÷天数。
|
|
@@ -355,7 +355,7 @@ siluzan-tso tiktok-analysis official-report -a <mediaCustomerId> --json-out ./sn
|
|
|
355
355
|
|
|
356
356
|
## Bing(BingV2)账户分析
|
|
357
357
|
|
|
358
|
-
>
|
|
358
|
+
> **日期**:可含昨天(及今天,数据可能不完整)。网关未显式传 `returnOnlyCompleteData` 时,区间碰到今天/昨天会自动改为近实时。省略时 CLI 默认截至昨天的近 7 天。用户要**已结束的完整自然月**(如「6月份」)→ `--start` 当月 1 日、`--end` 当月最后一天(6 月 = `06-30`,**禁止**减 1 天),见 `report-templates/bing-period-report.md` §日期规则。
|
|
359
359
|
>
|
|
360
360
|
> **自动化巡检步骤**(封禁 / 拒审 / 落地页 / 当日超预算 / 空耗预警,只读告警):`references/operations/hosted-automation-bing.md`。
|
|
361
361
|
|
|
@@ -365,7 +365,7 @@ siluzan-tso tiktok-analysis official-report -a <mediaCustomerId> --json-out ./sn
|
|
|
365
365
|
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
366
366
|
| `--sections` / `--exclude` | `overview` `device` `geographic` `age-audience` `gender-audience` `audience-merged` `campaigns` `ad-groups` `ads` `keywords` `search-terms`(11 个);**别名**:`devices`→`device`,`geo`→`geographic`,`search-queries`→`search-terms` |
|
|
367
367
|
| `--limit` | 仅 `keywords` / `search-terms`:条数上限,默认 100 |
|
|
368
|
-
| `--start` / `--end` |
|
|
368
|
+
| `--start` / `--end` | 同传或同省略;可含昨天/今天(可能不完整);省略=截至昨天的近 7 天 |
|
|
369
369
|
| `--concurrency` | 默认 5,上限 16 |
|
|
370
370
|
|
|
371
371
|
```bash
|
|
@@ -431,12 +431,11 @@ siluzan-tso bing-analysis monthly-spend -a <mediaCustomerId>
|
|
|
431
431
|
- `ad-entities` 单系列查必须带 `--campaign-id`;查全账户拒审/落地页用 `bulk-ads`,不要按系列遍历 `ad-entities`。
|
|
432
432
|
- `bulk-ads` 底层为官方异步下载任务,网关等文件就绪才返回,大账户可能要几分钟,不适合放在页面同步加载场景,适合定时巡检。
|
|
433
433
|
|
|
434
|
-
### Bing 近实时报表(`bing-analysis --aggregation
|
|
434
|
+
### Bing 近实时报表(`bing-analysis --aggregation`,按日/小时分桶)
|
|
435
435
|
|
|
436
|
-
> `
|
|
437
|
-
>
|
|
438
|
-
>
|
|
439
|
-
> (分别对应网关 `CampaignReport`/`AdGroupReport`/`AdReport`)。
|
|
436
|
+
> `--aggregation` / `--return-only-complete-data` 仅 `campaigns`/`ad-groups`/`ads` 三个 section 支持
|
|
437
|
+
> (分别对应网关 `CampaignReport`/`AdGroupReport`/`AdReport`)。省略这两个参数时,含昨天/今天的区间
|
|
438
|
+
> 同样可以拉(网关自动近实时);`--aggregation` 用来拿 Daily/Hourly 分桶。省略日期且传了 `--aggregation` 时默认今天当天。
|
|
440
439
|
|
|
441
440
|
```bash
|
|
442
441
|
# 单日花费与日预算(同一 campaignId 算 spend / dailyBudget;isSharedBudget=true 时 dailyBudget 是共享总额)
|
|
@@ -125,9 +125,9 @@
|
|
|
125
125
|
## 四、硬规范
|
|
126
126
|
|
|
127
127
|
- **账户状态 ≠ 系列状态**:`stats` / `balance` / `list-accounts` 的 `status` 只表示账户是否可用;系列状态必须来自 `ad campaigns`。
|
|
128
|
-
- **数据时效性**:涉及「今天/当天/今日消耗」「实时消耗排行」前,必读 `references/analytics/account-analytics.md` 顶部「数据时效性」表。TikTok / Yandex / BingV2 / Kwai
|
|
128
|
+
- **数据时效性**:涉及「今天/当天/今日消耗」「实时消耗排行」前,必读 `references/analytics/account-analytics.md` 顶部「数据时效性」表。TikTok / Yandex / BingV2 / Kwai 的 `stats`/`accountsoverview` 同步昨天数据,**不能查今天**。Bing 昨天/今天消耗走 `bing-analysis`;TikTok 走 `tiktok-analysis official-report`。
|
|
129
129
|
- **先查账户再操作**(拉数 / 改账户 / 报告 / **创建广告**):`list-accounts -m [mediaType] -k [mediaCustomerId]`;用户给出的 `mediaCustomerId` 必须 `-k` 核验,无结果则告知用户并停止,**禁止**翻页 grep 自行换 ID(会导致报告错户);拉数、脚本、报告文件名全链路用同一 ID(以 stdout `accountId` 为准)。
|
|
130
|
-
- **禁止臆测授权过期(硬约束)**:任何 403、空结果、「可能授权/OAuth 过期」话术,**禁止**凭感觉下结论或直接 `reauth
|
|
130
|
+
- **禁止臆测授权过期(硬约束)**:任何 403、空结果、「可能授权/OAuth 过期」话术,**禁止**凭感觉下结论或直接 `reauth`。`account check-access` **仅支持 Google**(无 `-m`,禁止对 TikTok/Meta/Bing/Yandex/Kwai 调用)。Google:**必须**执行 `account check-access -a <mediaCustomerId>`,仅当结果为 `reauth_required`(或列表 `invalidOAuthToken=true` 与之交叉确认)才谈重授权;`no_permission` 也可能是账户不在当前丝路赞账号下。若 `list-accounts` **输出含** `scopeActivatedSources` 且可判定未激活,则勿用 check-access 判断授权过期;**无该字段时禁止谈套餐激活**。非 Google 媒体以 `list-accounts` 的 `invalidOAuthToken` 为准,同样禁止臆测。详见 `accounts-permissions.md`。
|
|
131
131
|
- **一律走 CLI,禁止自拼网关请求**:查余额 / 拉数 / 写操作只用 `siluzan-tso …`。**禁止**用 curl、自写脚本或改请求头直连 TSO/Google 网关「另辟蹊径」取数;`balance` 等无数据时按 CLI/`list-accounts` **实际出现的字段**向用户说明(如授权失效;仅当输出含激活字段时才可谈套餐),**禁止**尝试任何绕过平台门禁的取数方式。
|
|
132
132
|
- **W3 仅出方案例外(覆盖上条)**:用户只要「投放方案 / 规划 / 表格 / 先别创建·开户·投钱」,或未给账户且未要求创建/发布时——**禁止**把「请先提供 Google 广告账户」当作第一步;按 `google-ads-campaign-plan.md` §「仅出方案 vs 创建」落盘 JSON 后 **写代码**投影完整审查稿(默认 MD;用户指定则 Excel 等;`account`=`[PENDING_ACCOUNT]`),跳过 `list-accounts` / `geo resolve` / validate / create。**禁止**只交概览表。用户确认要创建后再要账户并续跑创建流水线。
|
|
133
133
|
- **W3 审查稿(搜索与 PMax)**:JSON 落盘后、创建前,必须 **写代码**读取 JSON,按 `google-ads-launch-plan-template.md`(搜索)或 `google-ads-pmax-launch-plan-template.md`(PMax)生成完整审查文件交给用户;须含全部关键词/RSA 或全部 PMax 文案与附加资产。**禁止**用「方案总结」条数勾选代替。用户要求其他格式时改脚本输出,数据仍只从 JSON 来。
|
|
@@ -197,7 +197,7 @@
|
|
|
197
197
|
**完整自然月口径**(用户说「X 月 / X月份 / 月报」且该月已结束,或上表「月报」默认):
|
|
198
198
|
|
|
199
199
|
- `--start` = 当月 1 日,`--end` = 当月最后一天(6 月 → `06-01` ~ `06-30`,**禁止** `06-29`)。
|
|
200
|
-
- **Bing** `bing-analysis
|
|
200
|
+
- **Bing** `bing-analysis`:可含昨天/今天(今天可能不完整);**已结束的历史自然月必须用该月最后一天**,细则见 `report-templates/bing-period-report.md` §日期规则。交付前核对 `overview` 的 `activeDays` = 该月日历天数。
|
|
201
201
|
|
|
202
202
|
---
|
|
203
203
|
|
|
@@ -278,7 +278,7 @@
|
|
|
278
278
|
|
|
279
279
|
- **400**:参数错误,查看对应 reference 或 `-h`
|
|
280
280
|
- **401 / OAuth 失效**:仅当 `list-accounts` 的 `invalidOAuthToken=true`(或表格「授权状态」为失效)且用户确认后——Siluzan Agent **优先**用平台重新授权工具(如 `present_reauth`);备选 `account reauth -m <媒体> --id <entityId> --i-confirm --commit "…"`(内置 delink→OAuth,见 W9 / `accounts-permissions.md`)。走 CLI 时**必须把 stdout 中的完整授权 URL 原样贴给用户**,禁止只说「链接已生成」,也**禁止**自行改写/补全该 URL。解绑后若列表已无该户,恢复用平台授权工具或 `account auth -m <媒体>`。**丝路赞登录凭据失效** → `send-login-code` + `login --phone --code`,见 `references/core/setup.md`
|
|
281
|
-
- **403(拉数空结果 / ad 网关)**:① **优先核验 `-a` 是否为 `ma.mediaCustomerId`**(勿传 `entityId`/UUID;Google 注意连字符 CID;Yandex 形如 `porg-…`);② 仅当 `list-accounts` **输出含** `scopeActivatedSources` 且可判定未激活时,才可说明需先激活;**无该字段则禁止谈套餐**;**禁止**非 CLI 绕过取数;③
|
|
281
|
+
- **403(拉数空结果 / ad 网关)**:① **优先核验 `-a` 是否为 `ma.mediaCustomerId`**(勿传 `entityId`/UUID;Google 注意连字符 CID;Yandex 形如 `porg-…`);② 仅当 `list-accounts` **输出含** `scopeActivatedSources` 且可判定未激活时,才可说明需先激活;**无该字段则禁止谈套餐**;**禁止**非 CLI 绕过取数;③ **禁止臆测授权过期**:Google **必须**跑 `account check-access -a <mediaCustomerId>`(**仅 Google**,无 `-m`),以 `status` 为准后再决定是否 `reauth`;非 Google 看 `list-accounts` 的 `invalidOAuthToken`,**禁止**对 TikTok/Meta/Bing/Yandex/Kwai 跑 `check-access`;**禁止**仅凭 403 文案对用户说「授权过期」。
|
|
282
282
|
- **500**:服务可能正在部署/升级,建议反馈 Siluzan 相关人员
|
|
283
283
|
|
|
284
284
|
---
|
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
**硬约束**:
|
|
10
10
|
|
|
11
11
|
- `guard` **只支持 Google**。禁止 `guard … -m BingV2`。
|
|
12
|
-
-
|
|
12
|
+
- 周期报表日期**可以含昨天**;今天数据可能不完整。省略则默认截至昨天的近 7 天。含昨天/今天时不要显式传 `--return-only-complete-data true`。
|
|
13
13
|
- 当日花费、近两小时 CPA 必须显式传 `--aggregation Daily|Hourly`,且 `--sections` 只能是 `campaigns` / `ad-groups` / `ads`。
|
|
14
14
|
- Hourly 时间桶是**太平洋时区**,和北京日期可能差一天;阈值按 `timePeriod` 对齐,不要按北京日历硬切。
|
|
15
15
|
- 花费/转化用 `bing-analysis run --sections …`;日预算/启停状态用 `campaign-entities`。两套数据不要混成一行。
|
|
@@ -76,9 +76,9 @@ Agent 只需撰写 `narrative`;**禁止手写 HTML**,也**禁止**自填 `kp
|
|
|
76
76
|
|
|
77
77
|
## 日期规则(必读)
|
|
78
78
|
|
|
79
|
-
-
|
|
80
|
-
- **CLI**:`--start` / `--end`
|
|
81
|
-
-
|
|
79
|
+
- 可以含**昨天**;**今天**也可以拉,但可能不完整(网关未显式传 `returnOnlyCompleteData` 时自动近实时)。含昨天/今天时**不要**显式传 `--return-only-complete-data true`。
|
|
80
|
+
- **CLI**:`--start` / `--end` 须**同传或同省略**;省略时默认**截至昨天**的近 7 天(与 `bing-analysis` 实现一致)。
|
|
81
|
+
- 小时/日分桶(当日花费、近两小时 CPA)仍须对 `campaigns`/`ad-groups`/`ads` 传 `--aggregation Daily|Hourly`。
|
|
82
82
|
|
|
83
83
|
### 用户说「X 月 / X月份 / 月报」(已结束的完整自然月)
|
|
84
84
|
|
|
@@ -96,7 +96,7 @@ Agent 只需撰写 `narrative`;**禁止手写 HTML**,也**禁止**自填 `kp
|
|
|
96
96
|
siluzan-tso bing-analysis -a <id> --start 2026-06-01 --end 2026-06-30 --json-out ./snap-bing
|
|
97
97
|
```
|
|
98
98
|
|
|
99
|
-
|
|
99
|
+
**禁止**因旧规则「Bing 不能含今天/昨天」而对**已结束的历史自然月**把 `--end` 减 1 天。6 月 30 日在 7 月 8 日拉数完全合法。拉数后核对 `overview` 落盘里的 `activeDays` 应等于该月日历天数(6 月 = 30)。
|
|
100
100
|
|
|
101
101
|
---
|
|
102
102
|
|
|
@@ -76,9 +76,9 @@ Agent 只需撰写 `narrative`;**禁止手写 HTML**,也**禁止**自填 `kp
|
|
|
76
76
|
|
|
77
77
|
## 日期规则(必读)
|
|
78
78
|
|
|
79
|
-
-
|
|
80
|
-
- **CLI**:`--start` / `--end`
|
|
81
|
-
-
|
|
79
|
+
- 可以含**昨天**;**今天**也可以拉,但可能不完整(网关未显式传 `returnOnlyCompleteData` 时自动近实时)。含昨天/今天时**不要**显式传 `--return-only-complete-data true`。
|
|
80
|
+
- **CLI**:`--start` / `--end` 须**同传或同省略**;省略时默认**截至昨天**的近 7 天(与 `bing-analysis` 实现一致)。
|
|
81
|
+
- 小时/日分桶(当日花费、近两小时 CPA)仍须对 `campaigns`/`ad-groups`/`ads` 传 `--aggregation Daily|Hourly`。
|
|
82
82
|
|
|
83
83
|
### 用户说「X 月 / X月份 / 月报」(已结束的完整自然月)
|
|
84
84
|
|
|
@@ -96,7 +96,7 @@ Agent 只需撰写 `narrative`;**禁止手写 HTML**,也**禁止**自填 `kp
|
|
|
96
96
|
siluzan-tso bing-analysis -a <id> --start 2026-06-01 --end 2026-06-30 --json-out ./snap-bing
|
|
97
97
|
```
|
|
98
98
|
|
|
99
|
-
|
|
99
|
+
**禁止**因旧规则「Bing 不能含今天/昨天」而对**已结束的历史自然月**把 `--end` 减 1 天。6 月 30 日在 7 月 8 日拉数完全合法。拉数后核对 `overview` 落盘里的 `activeDays` 应等于该月日历天数(6 月 = 30)。
|
|
100
100
|
|
|
101
101
|
---
|
|
102
102
|
|
|
@@ -83,7 +83,7 @@
|
|
|
83
83
|
<i class="fa-solid fa-circle-info text-amber-400" aria-hidden="true"></i>
|
|
84
84
|
数据口径提示(示例)
|
|
85
85
|
</p>
|
|
86
|
-
<p class="mt-2 pl-7 text-amber-100/80">BingV2
|
|
86
|
+
<p class="mt-2 pl-7 text-amber-100/80">BingV2 昨天/今天可能不完整;以接口与 CLI 为准。</p>
|
|
87
87
|
</aside>
|
|
88
88
|
|
|
89
89
|
<section class="mb-14" data-section-id="section-executive-summary">
|
|
@@ -94,7 +94,7 @@
|
|
|
94
94
|
<i class="fa-solid fa-triangle-exclamation mr-1 text-amber-500" aria-hidden="true"></i
|
|
95
95
|
>口径提示
|
|
96
96
|
</p>
|
|
97
|
-
<p class="mt-1">BingV2
|
|
97
|
+
<p class="mt-1">BingV2 昨天/今天数据可能不完整。</p>
|
|
98
98
|
</aside>
|
|
99
99
|
|
|
100
100
|
<section class="mb-10" data-section-id="section-executive-summary">
|
|
@@ -60,7 +60,7 @@
|
|
|
60
60
|
|
|
61
61
|
<aside class="no-print mb-8 border-2 border-black border-dashed bg-neutral-50 p-4 text-sm">
|
|
62
62
|
<p class="font-bold">数据口径(示例)</p>
|
|
63
|
-
<p class="mt-1 text-neutral-800">BingV2
|
|
63
|
+
<p class="mt-1 text-neutral-800">BingV2:昨天/今天数据可能不完整。</p>
|
|
64
64
|
</aside>
|
|
65
65
|
|
|
66
66
|
<section class="mb-10" data-section-id="section-executive-summary">
|
|
@@ -9,7 +9,7 @@ $ErrorActionPreference = 'Stop'
|
|
|
9
9
|
# -- Package info (injected at build time) ------------------------------------
|
|
10
10
|
$PKG_NAME = 'siluzan-tso-cli'
|
|
11
11
|
# PKG_VERSION 锁定到与本脚本同批构建产物一致的版本,避免与 dist/skill 错位
|
|
12
|
-
$PKG_VERSION = '1.1.
|
|
12
|
+
$PKG_VERSION = '1.1.47-beta.1'
|
|
13
13
|
$CLI_BIN = 'siluzan-tso'
|
|
14
14
|
$SKILL_LABEL = 'Siluzan TSO'
|
|
15
15
|
$INSTALL_CMD = 'npm install -g siluzan-tso-cli@beta'
|
|
@@ -9,7 +9,7 @@ set -euo pipefail
|
|
|
9
9
|
# -- Package info (injected at build time) ------------------------------------
|
|
10
10
|
readonly PKG_NAME="siluzan-tso-cli"
|
|
11
11
|
# PKG_VERSION 锁定到与本脚本同批构建产物一致的版本,避免与 dist/skill 错位
|
|
12
|
-
readonly PKG_VERSION="1.1.
|
|
12
|
+
readonly PKG_VERSION="1.1.47-beta.1"
|
|
13
13
|
readonly CLI_BIN="siluzan-tso"
|
|
14
14
|
readonly SKILL_LABEL="Siluzan TSO"
|
|
15
15
|
readonly INSTALL_CMD="npm install -g siluzan-tso-cli@beta"
|