siluzan-tso-cli 1.1.29-beta.2 → 1.1.29-beta.21

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

@@ -1,175 +1,205 @@
-# Agent 执行规范
+# Agent 执行规范（唯一规则真相源）
 
-> 本文件定义 siluzan-tso Skill 下 **AI 助手必须遵守** 的加载纪律、执行流程与硬规范。  
-> CLI 参数细节见各功能 reference；标准任务步骤见 `references/core/playbooks.md`。
+> 本文件是 siluzan-tso Skill 下 AI 助手的**全部通用纪律**：加载纪律、数据处理协议、时间/币种、批量约束、交付自检。
+> 其他文档（SKILL.md、playbooks、workflows、各域 reference）**不再重复**这些规则，只在需要处单行指向本文件。
+> CLI 参数细节见各域 reference；脚本示例见 `references/core/tips.md`（食谱，按需查）。
 
 ---
 
-## 文档加载纪律
+## 一、文档加载纪律
 
 本 Skill 采用 **SKILL 路由 + references 按需加载**；**「按需」= 每个用户任务都要按需，不是整段对话只读一次**。
 
-### 何时必须 Read references
+| 触发                                                                                               | 动作                                                                                                                                                                      |
+| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **新的用户任务 / 同对话内换话题**（新需求、新账户、新媒体、新报告类型；例：刚查余额 → 改问建系列） | 按 `SKILL.md` 路由表 **重新 Read** 该任务的「必读文档」与工作流卡片后再执行 CLI；**禁止**沿用上一任务的参数记忆——对话会被压缩，「读过」≠ 当前上下文仍含正确字段名与 flags |
+| **工作流编号不同**（P1→P3、P4→P5）                                                                 | 即使刚做过 P1，仍须 Read 新卡片及其必读文档                                                                                                                               |
+| **专用 report-templates**（OKKI / 询盘分析 / 周期报告纲要）                                        | Read `references/report-templates/<名>.md` **全文**（与 `report-templates/<名>.md` 同源）；勿只凭 SKILL 摘要                                                              |
+| **上下文被压缩 / 记不清字段或命令**                                                                | 重读 `SKILL.md` 路由表 + 当次任务 references                                                                                                                              |
+| **CLI 返回 400 / 字段对不上**                                                                      | 回到对应 reference 核对参数名与口径，勿猜                                                                                                                                 |
+| **JSON 契约模板**（建搜索系列、PMax 等）                                                           | **必须先 Read** `assets/*-template.json`（结构真相源），再 Read 同目录 `.md`（字段说明与踩坑）；**禁止**只读 `.md` 凭印象拼 JSON |
 
-| 触发 | 动作 |
-| ---- | ---- |
-| **新的用户任务**（新需求、新账户、新媒体、新报告类型） | 用 `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 核对参数名与口径，勿猜 |
+所有 ID、金额、命令 flags 以**当次 Read 的文档 + 当次 CLI 输出**为准；数值只来自本次 stdout 或脚本读盘结果，不引用对话记忆里的示例值。
 
-### 应当遵循（及原因）
+### Skill 内 Read 路径约定
 
-| 应当怎么做 | 原因 |
-| -------- | ---- |
-| **每个新任务先 Read 当次必读 references，再执行 CLI** — 即使用户刚查过余额、对话里刚读过 `accounts/accounts.md` 或 `google-ads/google-ads.md`，换话题（建系列、预警、报告等）仍按 `SKILL.md` 路由表 **重新 Read** 对应文档后再 `siluzan-tso …` | 不同任务的命令、参数口径、Playbook 编号各不相同；对话会被压缩，「读过」≠ 当前上下文仍含正确字段名与 flags |
-| **所有 ID、金额、命令 flags 以当次 Read 文档 + 当次 CLI 输出为准** — 计划与执行前对照 reference 确认 `-a`/`-m`/日期等参数；数值只来自本次 stdout 或脚本读盘结果 | Skill 文档与 CLI 会迭代，对话记忆里的示例 ID、占位金额易串户、串币种或触发 400 |
-| **数据转换严格按 outline → 脚本读 JSON 顺序** — Read `references/core/tips.md` § 处理顺序；解析 stdout 得 `outlineFile` → Read outline → 编写并执行脚本读 `writtenFiles` | outline 是字段类型的唯一轻量索引；跳步会导致列名猜错（如 `keywordText` vs `keyword`）或把 MB 级 JSON 误读进对话 |
-| **大 JSON 只经脚本读盘，对话里只 Read 小文件** — Read 仅 `references/`、`*.outline.txt`、stdout 一行摘要；业务 `*.json`（`campaigns-*.json`、`list-accounts-*.json` 等）由 Node/Python `readFileSync` / `JSON.parse` 处理 | `--json-out` 落盘常为 MB 级，Read 整文件会撑爆上下文且无法可靠汇总；脚本可精确取所需字段并与落盘 JSON 复核 |
-| **报告 / Excel 走本 Skill 拉数 + outline + 脚本全流程** — 按 Playbook 与 `report-templates/*.md` 拉数、落盘、脚本转换后交付；不另加载宿主 xlsx / Excel 第三方 Skill 代劳 | 第三方 Skill 不知 TSO 字段口径、账户核验与 `deliverable-preflight`；易跳过 `-k` 核验或编造未落盘数据 |
-| **用户给出的 `mediaCustomerId` 必须 `-k` 核验，全链路同一 ID** — `list-accounts -m <媒体> -k <用户ID>`；无结果则告知用户并停止；拉数、脚本、报告文件名均用该 ID（以 stdout `accountId` 为准） | 列表第一页可能不含目标户；自行换 ID 会导致报告错户，属严重交付事故 |
-| 交付前自检产物，是否有为空的部分，是否有数据明显异常的部分，是否有字段使用错误的部分 | 如果不自检的话，出来的产物很可能无法使用 |
+| 类型 | 正确路径（相对 Skill 根目录） | 说明 |
+| ---- | ----------------------------- | ---- |
+| 命令 reference | `references/<域>/<文件>.md` | 如 `references/analytics/account-analytics.md` |
+| 报告纲要 | `references/report-templates/<文件>.md` | 如 `references/report-templates/google-period-report.md` |
+| JSON 契约模板（结构） | `assets/*-template.json`、`assets/*.schema.json` 等 | **先 Read**；如 `assets/campaign-create-template.json` |
+| 契约说明 / 规则 | `assets/<文件>.md` | 与上表 JSON **成对** Read；如 `assets/campaign-create-template.md` |
+| HTML 终稿模板 | `report-templates/*.html` | 由 CLI `render` 使用，Agent 通常只 Read 对应 `.md` 纲要 |
 
+路由表若写 `analytics/…` 或 `report-templates/…` 而无 `references/` 前缀，**Read 时仍须加上 `references/`**（`assets/`、`report-templates/*.html` 除外）。
 
-## 执行流程
+---
+
+## 二、执行流程
 
 **计划 → 确认 → 执行 → 验证 → 推测下一步**：
 
-1. **按加载纪律 Read 当次任务 references** → 用 `-h` 确认命令 → 向用户输出操作计划
-2. 涉及写入/修改/删除的操作必须与用户确认
-3. 按计划执行，说明每步意图
-4. 用成对的读命令复核写入结果；异步任务每 5s 轮询直到完成
-5. **交付前**（报告/Excel/含金额话术）：Read `references/core/deliverable-preflight.md`，**Read 最终产物文件**并按自检表 A/B/C 逐项确认后再发给用户
-6. 全部完成后预测用户下一步操作
+1. 按上表 Read 当次任务 references → 用 `-h` 确认命令 → 向用户输出操作计划。
+2. 涉及写入/修改/删除的操作必须与用户确认；多数破坏性操作还需 `--commit`。
+3. 按计划执行，说明每步意图。
+4. 用成对的读命令复核写入结果；异步任务每 5s 轮询直到完成。
+5. 报告/Excel/含金额话术交付前，按本文件 **§七 交付前自检** 审阅最终产物。
+6. 全部完成后预测用户下一步操作。
 
 ### 执行模式速查
 
-| 模式 | 说明 |
-| ---- | ---- |
-| **数据交付类** | `google-analysis` / `stats` / `ad campaigns` 等带 `--json-out`：必须脚本读盘转换，见下文「数据转换硬规范」 |
+| 模式              | 说明                                                                                             |
+| ----------------- | ------------------------------------------------------------------------------------------------ |
+| **数据交付类**    | `google-analysis` / `stats` / `ad campaigns` 等带 `--json-out`：必须按 §三 协议脚本读盘转换      |
 | **客户/产品背景** | 拓词、方案、报告背景段：先 `rag list` + `rag query`，再衔接 `keyword` / `ad` / `google-analysis` |
-| **仅调接口** | 优化记录、线索表单、预警、财务命令：无需输出转换 |
+| **仅调接口**      | 优化记录、线索表单、预警、财务命令：无需输出转换                                                 |
 
 ### Subagent（可选）
 
-宿主支持 Task / 子会话时：
+宿主支持 Task / 子会话时：**P5 / P6 / P7** 或预计 CLI 日志很长 → Read `references/core/subagent-orchestration.md`，按决策矩阵选择主会话或委派。子会话不替代 §一 加载纪律；handoff 只传路径与命令块。写入/修改/删除、`--commit`、对用户确认与最终交付始终留在**主 Agent**。
+
+---
+
+## 三、数据处理协议（最高优先级）
+
+所有业务数据以 CLI `--json-out`（或用户提供的同构 JSON）落盘为唯一真相源。每条 `--json-out` 命令成功后**必须按顺序**处理，不要跳步：
+
+1. **解析 stdout 一行摘要 JSON**：拿到 `outlineFile`、`writtenFiles[0]`、`manifestFile`、`agentHint`。摘要里**没有** `total` / `items` 等业务字段——**禁止**对 stdout 写翻页循环，业务数据只在 `writtenFiles[0]` 落盘文件里；**不要**硬编码 `<section>.json` 文件名。
+2. **【outline 门禁·先读完再动手】Read 当次产出的*每一个* `*.outline.txt`**（`*.outline.txt`，通常 <2KB，schema-only）确认字段树后**才可**写脚本。类型字面量是**最后一个不以 `//` 开头的行**（提取写法 `outlineRaw.trimEnd().split('\n').filter(l => !l.startsWith('//')).pop()`，勿用 `lines[lines.length-1]`）。outline 是结构描述，**不是数据**，勿当 JSON `require`、勿贴给用户。
+   - **多 section / 多账户必须逐一读全**：`google-analysis` 拉 N 个 `--sections`、`google-analysis-batch` 产出 N 维 × M 账户时，**每个维度至少 Read 一次它自己的 outline**（同结构的多账户文件读其一即可代表该维度）；用**一批并行 Read** 把当次所有维度 outline 一次读完，再开始写脚本。
+   - **唯一字段真相源 = 当次 outline**：SKILL.md / playbooks / report-templates / 本文件里出现的字段名都是**说明性示例**，**不是**字段真相源；凡 outline 未确认的字段路径，**禁止**凭模板印象、凭上一任务记忆、凭"通用命名"直接写进脚本。
+   - **禁止边写边猜、用空值/全 0 当反馈**：不得"先按猜测写一版脚本跑出来，发现字段空了再回头读 outline 重写"。outline 没读全就开写 = 违规。
+3. **编写并执行脚本**（`node -e` / `.mjs` / `python`）`readFileSync` 读 `writtenFiles[0]` 做筛选、聚合、计算，字段路径**逐一对照第 2 步确认的 outline**；**永远不得**用宿主 Read / `cat` / `type` / `Get-Content` 打开落盘业务 `*.json`（常为 MB 级，会撑爆上下文）。
+4. **交付物用代码写出**（HTML / Excel / PDF / Markdown 等）；向用户展示的数字须来自**脚本 stdout**，不在对话里手填、改数、心算汇总。**交付前**若某章/表为空或全 0，先怀疑"字段路径猜错（漏读该维度 outline）"，回第 2 步核对，**不要**直接当作"接口无数据"交付。
+
+| 允许 Read 的文件                                                                 | 必须用代码读取的文件                       |
+| -------------------------------------------------------------------------------- | ------------------------------------------ |
+| `references/**/*.md`、`assets/**/*.md`（Skill 文档）                             | 所有 `--json-out` 落盘业务 `*.json`（常为 MB 级） |
+| `assets/*-template.json`、`assets/*.schema.json`、`analytics/geo-continents.json` 等**小体积契约/映射** | manifest 中的路径索引（脚本 `JSON.parse`） |
+| 当次 `*.outline.txt`                                                             | 用户提供的同构大 JSON                      |
+| stdout 一行摘要、你刚写出的最终产物文件                                          | —                                          |
+
+**字面量纪律**：字段路径以 `outlineFile` + 当次 manifest 为准，禁止跳过 \*.outline.txt 猜字段名。常见踩坑（均因没逐维读 outline）：
+
+| 凭印象写错的            | 当次 outline 的真实字段                        |
+| ----------------------- | ---------------------------------------------- |
+| `ov.spend`              | `cp.spend`（消耗在 `record.currentPeriod` 下） |
+| `g.countryName`         | `g.countryOrRegion`                            |
+| `s.searchTerm`          | `s.searchTermText`                             |
+| `ctRecord.typesSummary` | 记录本身即 `{ PerformanceMax: {…} }` 结构      |
+| `ga.items[]`            | `ga` 的键直接是布尔字段，无 `items` 数组       |
+| `keywordText`           | `keyword`                                      |
+| `query`                 | `searchTermText`                               |
+
+国家名、ID、金额、词表等**业务值**禁止写成源码字面量；映射表/模板契约运行时加载（`analytics/geo-continents.json`、`campaign-create-template.json`）。允许的字面量：输出目录、Sheet/列标题、技术格式、用户当轮明确给出的配置（建议落盘 `config.json` 再脚本读）。
+
+**报告/Excel 全流程走本 Skill**：按工作流卡片与 `report-templates/*.md` 拉数、落盘、脚本转换；**禁止**加载宿主第三方 xlsx/Excel Skill 代劳（不知 TSO 字段口径与账户核验）。
 
-1. **P5 / P6 / P7** 或预计 CLI 日志很长 → Read `references/core/subagent-orchestration.md`，按决策矩阵选择主会话或委派。
-2. 子会话**不替代**本节「文档加载纪律」：主 Agent 仍须 Read 当次必读 references；handoff 只传路径与命令块，不传对话记忆。
-3. 写入/修改/删除、`--commit`、对用户确认与最终交付 → **主 Agent**。
+**中间结果一律落盘**：跨步骤数据不靠对话记忆；Windows 避免管道传 JSON，优先 `--json-out` + `node -e` 读文件。
 
 ---
 
-## 硬规范
+## 四、硬规范
 
 - **账户状态 ≠ 系列状态**：`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`。
+- **数据时效性**：涉及「今天/当天/今日消耗」「实时消耗排行」前，必读 `references/analytics/account-analytics.md` 顶部「数据时效性」表。TikTok / Yandex / BingV2 / Kwai 是 `accountsoverview` 同步昨天数据，**不能查今天**。
+- **先查账户再操作**：`list-accounts -m [mediaType] -k [mediaCustomerId]`；用户给出的 `mediaCustomerId` 必须 `-k` 核验，无结果则告知用户并停止，**禁止**翻页 grep 自行换 ID（会导致报告错户）；拉数、脚本、报告文件名全链路用同一 ID（以 stdout `accountId` 为准）。
+- **不猜测账户 ID**：`entityId` ≠ `mediaCustomerId`，两者均来自 `list-accounts`；**禁止**把 `entityId` 传给 `stats -a` / `balance -a`。
 - **媒体类型区分大小写**：`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` 维护。
-- **开户首次响应**：用户第一次提出开户（或对话内首次进入开户话题）时，**必须先**按 `references/accounts/open-account-by-media.md` §「首次响应硬规范」输出**完整必填清单**（未指明媒体则列全平台六表），再收集资料；**禁止**未列清单就执行 `open-account` 或只零散追问个别字段。
+- **跨账号 / 企业管家手机号**：用户消息中出现**中国大陆 11 位手机号**（常见语境：「企业管家」「管家账户」「账号 xxx」）且意图是查**该手机号名下**的账户数据时，**必须先**执行 `siluzan-tso account me --check-phone <手机号> --json-out ./snap-me`。**禁止**在未校验通过前用当前凭据拉他户数据。
+  - `matched: true`（或 CLI exit 0）→ 按原工作流继续（如 P3 `accounts-digest` 查 TOP 消耗）。
+  - `matched: false`（CLI exit 1）→ **停止拉数**，告知用户并询问是否切换登录，话术示例：
+    > 暂时不支持查询其他丝路赞账号下的数据。您指定的是 **{phone}**，当前登录的是 **{currentPhone}**。
+    > 如需查询该账号，请使用该手机号重新登录：`send-login-code --phone {phone}` → `login --phone {phone} --code <验证码>`。
+    > 需要我帮您切换登录吗？
+  - 用户**未指定手机号** → 不校验，按当前凭据正常执行。
+  - 当前凭据未返回手机号且用户指定了手机号 → 视同未校验通过，引导重新用手机号登录。
+- **Google 新建搜索系列**：流程在 `references/google-ads/google-ads-campaign-plan.md`；填 JSON 前**必须先 Read** `assets/campaign-create-template.json`，再 Read `assets/campaign-create-template.md`。**禁止**只读 `.md` 手写 JSON。
+- **开户首次响应**：对话内首次进入开户话题时，**必须先**按 `references/accounts/open-account-by-media.md` §「首次响应硬规范」输出**完整必填清单**（未指明媒体则列全平台六表），再收集资料；**禁止**未列清单就执行 `open-account` 或零散追问。
 - **Google 开户**：`open-account google-wizard` 仅限真实 TTY；Agent/自动化用非交互 `open-account google ...`，审核进度用 `account-history`。
 - **主动更新**：详见 `references/core/setup.md`。
 
 ---
 
-## 数据转换硬规范
+## 五、时间范围
 
-本 Skill 下**所有**业务数据均以 CLI `--json-out`（或用户提供的同构 JSON）落盘为唯一真相源。Agent **不得**在对话或脚本里「代替」磁盘数据。
-
-### 禁止 Read 完整业务 JSON（最高优先级）
+涉及「投放数据 / 消耗 / 报告 / 周报 / 月报 / 优化建议」且用户未给明确起止日期时**必须反问**（示例：A) 最近完整自然周 B) 本月 1 号到昨天 C) 自定义 YYYY-MM-DD）。给出范围后，报告首行标注 `统计区间：YYYY-MM-DD ~ YYYY-MM-DD（货币：XXX）`。
 
-`--json-out` 落盘的 `writtenFiles[0]`（及同目录 `campaigns-*.json`、`keywords-*.json` 等）往往为 **MB 级**。Agent **永远不得**用宿主 **Read** 工具、`cat`、`type`、`Get-Content` 等方式把整文件读进对话上下文。
+**例外**（不反问）：
 
-| 允许 Read 的文件 | 必须用代码读取的文件 |
-| ---------------- | -------------------- |
-| `references/**/*.md`、`assets/**/*.md`（Skill 文档） | 所有 `--json-out` 业务 `*.json` |
-| 当次 `*.outline.txt`（通常小于 2KB，仅 schema） | `cli-manifest*.json` / `manifest-*.json` 中的路径索引（应用脚本 `JSON.parse` 读，勿 Read 整份 manifest 若很大） |
-| stdout **一行**摘要 JSON（命令回显，体积小） | 用户提供的同构大 JSON 文件 |
+- `list-accounts` 列全部 / 数个数：一次 `list-accounts -m <媒体> --page-size 999 --json-out <dir>`，脚本读落盘 `total` / `items[]`；**禁止**默认 page-size 20 再翻页（详见 `accounts/accounts.md` § Agent 意图速查）。
+- 「昨天」单日 stats：默认 `Asia/Shanghai` 日历日；先 `list-accounts` 再 `stats`。
+- `forewarning records`、`invoice list`「本月」、TikTok `clue`「最近一周」：见对应 references。
 
-**正确流程**：解析 stdout 摘要 → Read **仅** `outlineFile` 了解字段类型 → **编写并执行** `node -e` / `node script.mjs` / `python`：`require` 或 `readFileSync` 读 JSON → `console.log` / 写 xlsx/html **只输出所需字段** → 用脚本打印结果回答用户。
+**默认值白名单**（仅用户明确授权「你决定」时使用）：
 
-| 必须 | 禁止 |
-| ---- | ---- |
-| 编写并**执行** Node/Python 脚本读落盘 JSON → 计算 → 写出 | 用 **Read** 打开 `writtenFiles` 业务 JSON；在回复里手填、改数、心算汇总 |
-| **先 outline 后脚本读 JSON**：`outlineFile` → 代码读 `writtenFiles[0]` | 跳过 outline 猜字段名；把 outline 当数据贴给用户 |
-| 字段路径以 `outlineFile` + 当次 `writtenFiles` / manifest 为准 | 把国家名、ID、金额、词表等**业务值**写成源码字面量 |
-| 映射表 / 模板契约在运行时加载（`analytics/geo-continents.json`、`campaign-create-template.json`） | 复制配置条目进源码常量 |
-| 脚本输出与落盘 JSON 可复核 | 用「上次对话记住的数」「占位数」写入交付物 |
+| 场景                   | 默认窗口                        |
+| ---------------------- | ------------------------------- |
+| 日常巡检 / 余额扫描    | `now - 7d` ~ `now - 1d`         |
+| 周报                   | 上一个完整自然周（周一 ~ 周日） |
+| 月报                   | 上一个完整自然月                |
+| Google 关键词/系列分析 | `now - 30d` ~ `now - 1d`        |
+| MetaAd 账户分析        | 不得默认，必须问                |
 
-**允许的字面量**：输出目录、Sheet/列标题、技术格式、`focusCountries` 等**用户当轮明确给出**的配置（建议落盘为 `config.json` 再**用脚本**读）。
+---
 
-完整协议见 `references/core/tips.md` § 处理顺序、§ 已有 JSON 时。
+## 六、币种与金额
 
----
+完整字段来源与符号表见 `references/accounts/currency.md`。三条硬规则：
 
-## 时间范围
+1. **币种只认接口字段** `currencyCode`（首选 `list-accounts` → `items[].ma.currencyCode`）；同媒体可同时有 CNY 与 USD，**禁止**默认 Google=美金。`CNY` → **￥**、`USD` → **$**。
+2. **禁止跨币种求和**：多账户按 `currencyCode` 分表或分币种小计。
+3. **金额单位统一为「元」**（CLI 出口已换算，`budgetAmountYuan`、`spend` 等直接展示），报告保留 2 位小数。
 
-涉及「投放数据 / 消耗 / 报告 / 周报 / 月报 / 优化建议」且用户未给明确起止日期时**必须反问**（示例：A) 最近完整自然周 B) 本月 1 号到昨天 C) 自定义 YYYY-MM-DD）。给出范围后，报告首行标注 `统计区间：YYYY-MM-DD ~ YYYY-MM-DD（货币：XXX）`。
+**品牌名优先级**：(1) 用户明确提供 → (2) `list-accounts.mag.advertiserName` → (3) 网址域名占位 `[待确认品牌名]`。**严禁**把英文域名翻译为虚构中文品牌。
 
-**例外**（不反问）：
+---
 
-- `list-accounts` 列全部 / 数个数：一次 `list-accounts -m <媒体> --page-size 999 --json-out <dir>`，脚本读落盘 `list-accounts-*.json` 的 `total` / `items[]`；**禁止**默认 page-size 20 再翻页；**禁止**对 stdout 摘要解析 `total`/`items`（见 `accounts/accounts.md` § Agent 意图速查）；**默认无 `--detail` 时 JSON 不含余额/消耗**；要看余额/消耗加 `--detail` 或另跑 `balance`/`stats`
-- 「昨天」单日 stats：默认 `Asia/Shanghai` 日历日；先 `list-accounts` 再 `stats`
-- 仅持有 `entityId`：先 `list-accounts` 解出 `mediaCustomerId`，**禁止**把 `entityId` 传给 `stats -a` / `balance -a`
-- `forewarning records`、`invoice list`「本月」、TikTok `clue`「最近一周」：见对应 references
+## 七、交付前自检（报告 / Excel / 含金额话术）
 
-**默认值白名单**（仅用户明确授权「你决定」时使用）：
+> 在产物文件已写入磁盘**之后、发给用户之前**执行；不靠外部校验脚本，由 Agent **亲自 Read 最终产物文件**（HTML / Markdown 等；二进制 xlsx 无法 Read 时在对话贴自检表逐条勾选，依据为生成脚本的 stdout 摘要）。审阅阶段只看最终产物 + 已掌握的账户元数据，**不**回头 Read 落盘业务 JSON。
 
-| 场景 | 默认窗口 |
-| ---- | -------- |
-| 日常巡检 / 余额扫描 | `now - 7d` ~ `now - 1d` |
-| 周报 | 上一个完整自然周（周一 ~ 周日） |
-| 月报 | 上一个完整自然月 |
-| Google 关键词/系列分析 | `now - 30d` ~ `now - 1d` |
-| MetaAd 账户分析 | 不得默认，必须问 |
+**A · 币种**：首行含 `统计区间：…（货币：CNY|USD）`；全文符号与 `currencyCode` 一致（CNY=￥、USD=$，未混用）；与当次 `list-accounts -k` 结果相同；多账户分币种分表、无跨币种「总计」行。
 
----
+**B · 结构完整**（对照当次 `report-templates/*.md`）：模板要求的每一章/Sheet 都存在；无整章空白（缺数据章节写 `[ 数据不可用：… ]`，禁止编造数字填坑）；优化建议独立成节、引用当次数字（Meta：4 条建议各 ≥150 字 + 7 维补充；Google 诊断：每模块除表格外有「分析」+「建议」）；Excel 的表头列须能在当次 `*.outline.txt` 找到对应字段、产物内账户 ID = 用户当轮给出的 `mediaCustomerId`。
 
-## 币种与金额（速查）
+**C · 数字可信**（抽样，不读大 JSON）：总消耗/CPA 数量级与生成过程中脚本 stdout 打印的汇总一致（若无，补跑一次极小 `node -e` 只打印 totals）；账户 ID、区间与用户需求一致；无「示例账户」「占位 123456」等模板残留；表格行数符合预期（如 P3 每个 `-a` ID 占一行）。
 
-完整字段表见 `references/accounts/currency.md`。
+任一项不通过 → 修正产物后**重新 Read 再审**，不得交付、不得手改数字糊弄。通过后，交付消息附简短自检结论：
 
-- **币种只认接口字段**：`list-accounts` → `items[].ma.currencyCode`；同媒体可同时有 CNY 与 USD，不得凭媒体猜币种。
-- **符号**：`CNY` → **￥**；`USD` → **$**。多账户按 `currencyCode` 分表，**禁止**跨币种求和。
-- **金额单位统一为「元」**：报告保留 2 位小数。
-- **Google 广告诊断报告**：`report-templates/google-ads-diagnosis.md` § 撰写硬约束 — 每日趋势金额/CPA 必须 2 位小数；每个模块除表格外须有「分析」+「建议」，禁止只贴数据。
-- **交付前审阅产物**：报告/Excel 交付前 Agent **Read 最终文件**并对照 `deliverable-preflight.md` 自检表；未审阅禁止交付。
-- **品牌名优先级**：(1) 用户明确提供 → (2) `list-accounts.mag.advertiserName` → (3) 网址域名占位 `[待确认品牌名]`。**严禁**把英文域名翻译为虚构中文品牌。
+```text
+交付前自检（已通过）：
+- 产物：./out/report-xxx.html
+- 币种：CNY（来自 list-accounts，与报告首行一致）
+- 章节：8/8 默认维度齐全；关键词章 [ 数据不可用：接口超时 ] 已标注
+- 区间：2026-04-01 ~ 2026-04-30
+```
 
 ---
 
-## 批量任务硬约束
+## 八、批量任务硬约束
 
-| 任务 | 推荐命令 | 禁止 |
-| ---- | -------- | ---- |
-| 多账户余额 / 预算不足预警 | `balance-scan -m <媒体> --threshold-days 7` | 逐账户 `balance --accounts ...` |
-| 多账户投放画像 | `accounts-digest -m <媒体> [-a ...] --start --end --json-out` | 逐账户 `stats` |
+| 任务                        | 推荐命令                                                                               | 禁止                             |
+| --------------------------- | -------------------------------------------------------------------------------------- | -------------------------------- |
+| 多账户余额 / 预算不足预警   | `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`）：
+| 多系列诊断                  | `ad campaigns --json-out` + node 读文件过滤                                            | 逐系列 `ad campaign-get`         |
 
-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`。
+**`google-analysis-batch` 纪律**（详见 `references/analytics/google-analysis-batch.md`）：拉全量时省略 `-a`；中断后**必须** `resume --run-id <id>`，**禁止**重新 `run`；stdout 始终单行 JSON（`kind=siluzan-tso-batch-summary`）；退出码 `0` 全成功 / `2` 部分成功 / `3` 全失败或 Token 失效 / `4` 用法错误；401 → 整批终止，按 `references/core/setup.md` 重登录后 `resume`。
 
 ---
 
-## 运行时长与进度
+## 九、运行时长与进度
 
 预估超 2 分钟的任务先告知预计耗时；超 5 分钟未完成时主动检查并告知用户。长任务中断后用对应 `resume` 入口续跑，**禁止**直接重跑 `run`。
 
 ---
 
-## 账户 ID 示例
+## 十、账户 ID 示例
 
 先用位数判断类型，不确定再 `list-accounts -m [mediaType] -k [id]`：
 
@@ -182,7 +212,7 @@
 
 ---
 
-## 常见 HTTP 状态码
+## 十一、常见 HTTP 状态码
 
 - **400**：参数错误，查看对应 reference 或 `-h`
 - **401**：平台方返回则需用户重新授权；**我方凭据失效**则优先 `send-login-code` + `login --phone --code`，见 `references/core/setup.md`
@@ -190,7 +220,7 @@
 
 ---
 
-## 风险预警与自动化（主动介绍）
+## 十二、风险预警与自动化（主动介绍）
 
 加载本 skill 时须向用户介绍 `references/operations/hosted-automation-user-catalog.md` 中的能力：
 
@@ -200,7 +230,7 @@
 
 ---
 
-## 消息平台语法
+## 十三、消息平台语法
 
 需 webhook 发送消息时，先阅读对应平台文档：
 

package/dist/skill/references/core/cli-enums.md

@@ -6,58 +6,51 @@
 
 ### 媒体类型 `-m` / `--media`（多数命令）
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令                                                                      | 选项        | 合法值                                                 |
+| ------------------------------------------------------------------------- | ----------- | ------------------------------------------------------ |
 | list-accounts, stats, balance, account-history, open-account, transfer, … | -m, --media | Google \| TikTok \| Yandex \| MetaAd \| BingV2 \| Kwai |
 
-
 > 区分大小写；Meta 广告账户用 MetaAd，不是 Facebook。
 
 ### 媒体类型（仅 forewarning）
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令                                 | 选项        | 合法值           |
+| ------------------------------------ | ----------- | ---------------- |
 | forewarning list, create, records, … | -m, --media | Google \| TikTok |
 
-
 ### `google-analysis --sections` 维度（25）
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令                                       | 选项       | 合法值                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | google-analysis, google-analysis-batch run | --sections | overview \| keywords \| search-terms \| campaigns \| campaign-hour \| ads \| extensions \| devices \| geographic \| geo-matched \| campaign-geo \| campaign-geo-matched \| campaign-device \| audience \| asset-images \| videos \| materials \| resource-counts \| conversion-actions \| daily-metrics \| gold-account \| ads-index \| final-urls \| dimension-summary \| campaign-types |
 
-
 > 逗号分隔；省略=全部。`final-urls`、`campaign-types` 不传日期。
 
 ### `google-analysis --level`（extensions 维度）
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令                                  | 选项    | 合法值                          |
+| ------------------------------------- | ------- | ------------------------------- |
 | google-analysis --sections extensions | --level | Account \| Campaign \| Ad Group |
 
-
 ### `google-analysis --audience-type`（audience 维度）
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令                                | 选项            | 合法值                       |
+| ----------------------------------- | --------------- | ---------------------------- |
 | google-analysis --sections audience | --audience-type | SystemDefined \| UserDefined |
 
-
 ### `facebook-analysis --sections` 维度（7）
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令              | 选项       | 合法值                                                                         |
+| ----------------- | ---------- | ------------------------------------------------------------------------------ |
 | facebook-analysis | --sections | overview \| ad-sets \| platform \| country \| audience \| creative \| material |
 
-
 > 默认周期报告：overview,ad-sets,platform,country,audience,creative。
 
 ### `facebook-analysis --sections` Google 别名
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
-| facebook-analysis | --sections（别名） | — |
-
+| 命令              | 选项               | 合法值 |
+| ----------------- | ------------------ | ------ |
+| facebook-analysis | --sections（别名） | —      |
 
 > 解析后映射到左侧 canonical 名。
 
@@ -65,74 +58,75 @@
 
 ### `ad extension * --level`
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
-| ad extension sitelink, callout, snippet, … | --level | Account \| Campaign \| AdGroup |
-
+| 命令                                       | 选项          | 合法值                                                                             |
+| ------------------------------------------ | ------------- | ---------------------------------------------------------------------------------- |
+| ad extension sitelink, callout, snippet, … | --level       | Account \| Campaign \| AdGroup                                                     |
+| ad extension list                          | --type        | SITELINK \| CALL \| CALLOUT \| STRUCTURED_SNIPPET \| LEAD_FORM \| BUSINESS_MESSAGE |
+| ad extension lead-form / update            | --config-file | JSON（见 `assets/pmax-lead-form-template.json`）                                   |
+| ad extension whatsapp / update             | --config-file | JSON（见 `assets/pmax-whatsapp-template.json`）                                    |
 
 ### 搜索系列 `BiddingStrategyTypeV2`
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令                                                 | 选项                           | 合法值                                                                                                       |
+| ---------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
 | ad campaign-create, campaign-validate（config JSON） | campaign.BiddingStrategyTypeV2 | TARGET_SPEND \| MANUAL_CPC \| TARGET_CPA \| TARGET_ROAS \| MAXIMIZE_CONVERSIONS \| MAXIMIZE_CONVERSION_VALUE |
 
-
 ### 系列 `ChannelTypeV2`
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令                                  | 选项                   | 合法值                                                  |
+| ------------------------------------- | ---------------------- | ------------------------------------------------------- |
 | ad campaign-create, campaign-validate | campaign.ChannelTypeV2 | SEARCH \| DISPLAY \| VIDEO \| SHOPPING \| MULTI_CHANNEL |
 
-
 ### 系列 `StatusV2`
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令                                  | 选项              | 合法值            |
+| ------------------------------------- | ----------------- | ----------------- |
 | ad campaign-create, campaign-validate | campaign.StatusV2 | Enabled \| Paused |
 
-
 ### 预算投放 `BudgetBudgetDeliveryMethodV2`
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令                                  | 选项                                  | 合法值                                            |
+| ------------------------------------- | ------------------------------------- | ------------------------------------------------- |
 | ad campaign-create, campaign-validate | campaign.BudgetBudgetDeliveryMethodV2 | STANDARD \| ACCELERATED \| UNSPECIFIED \| UNKNOWN |
 
-
 ### PMax `BiddingStrategyTypeV2`
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令                          | 选项                           | 合法值                                                                         |
+| ----------------------------- | ------------------------------ | ------------------------------------------------------------------------------ |
 | ad pmax-create, pmax-validate | campaign.BiddingStrategyTypeV2 | MAXIMIZE_CONVERSIONS \| MAXIMIZE_CONVERSION_VALUE \| TARGET_CPA \| TARGET_ROAS |
 
-
 ### 预警比较运算符
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令               | 选项       | 合法值                                                     |
+| ------------------ | ---------- | ---------------------------------------------------------- |
 | forewarning create | --operator | GREATER_EQUALS \| GREATER \| LESS_EQUALS \| LESS \| EQUALS |
 
-
 ### 开户历史状态筛选
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令            | 选项                          | 合法值                                    |
+| --------------- | ----------------------------- | ----------------------------------------- |
 | account-history | --status（mediaAccountState） | Created \| Approved \| Denied \| Inactive |
 
-
 > Google 默认含 Inactive；其他媒体默认 Created,Approved,Denied。
 
 ### 线索表单媒体
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令 | 选项        | 合法值         |
+| ---- | ----------- | -------------- |
 | clue | -m, --media | TikTok \| Meta |
 
-
 ### 网站诊断模块 status
 
-| 命令 | 选项 | 合法值 |
-| ---- | ---- | ------ |
+| 命令                                  | 选项             | 合法值                                                               |
+| ------------------------------------- | ---------------- | -------------------------------------------------------------------- |
 | website-diagnosis collect（响应字段） | modules[].status | Excellent \| Good \| Normal \| Poor \| Full \| NeedImprove \| Absent |
 
-
 > 撰写报告时转中文展示；细则见 assets/website-diagnosis-rules.md。
+
+### Kwai 开户 `--licence-id-type`（`open-account kwai`）
+
+| 命令              | 选项              | 合法值                                       |
+| ----------------- | ----------------- | -------------------------------------------- |
+| open-account kwai | --licence-id-type | `1` 统一社会信用代码 \| `2` DUNS \| `3` CNPJ |
+
+> 与网页 `KwaiOpenAnAccount.vue` 的 `licenseCodeTypeOptions` **value** 一致（数字字符串）。**勿用** `ENTERPRISE` / `INDIVIDUAL`（旧文档误写；传入 `ENTERPRISE` 时 CLI 会警告并映射为 `1`）。