sino-bc-cli 1.8.20 → 1.8.21

package/dist/skills/custom/biz-line-strategy-generate/references/output-excel.md

@@ -8,7 +8,7 @@
 | --- | --- |
 | 组别 | `biz-line-list` 出参 `ssoTeamCodeName`（组别名称，已直接返回，**不需要**再用 `ssoTeamCode` 去 `sso +group-list` 反查） |
 | 业务线 | `biz-line-list` 出参 `name` |
-| 本期/上期 | 本次请求实际使用的时间范围，**写在同一单元格内两行**：`本期：yyyy-MM-dd～yyyy-MM-dd` + 换行 + `上期：yyyy-MM-dd～yyyy-MM-dd`。用户指定了就用用户的，否则用 `periodStart/periodEnd` 与 `prevPeriodStart/prevPeriodEnd` |
+| 本期/上期 | 本次请求实际使用的时间范围，**写在同一单元格内，并附实际覆盖范围**：`本期：yyyy-MM-dd～yyyy-MM-dd` + 换行 + `上期：yyyy-MM-dd～yyyy-MM-dd`。用户指定了就用用户的，否则用 `periodStart/periodEnd` 与 `prevPeriodStart/prevPeriodEnd` |
 | 项目名称 | `biz-line-project-list` 出参 `result[].projectName`；一个业务线的多个项目**写在同一单元格内，一个项目一行**（用 `\n` 分隔） |
 | 预算策略内容 / 预算策略learning | 见 [`four-strategies.md`](four-strategies.md) 预算策略 与 [`metrics.md`](metrics.md) learning 生成规则 |
 | 广告产品策略内容 / 广告产品策略learning | 同上，广告产品策略 |
@@ -27,65 +27,16 @@
 - learning：先 `结论` / `依据` / `KPI`，再按维度用 `·` 列明细（最多 8 条，其余写「另有 N 个」），最后一行 `建议`。
 - 不要再用 `{...}` 把明细包成一段，也不要用分号把几十条广告串在同一行。
 
-## 调用方式
+## 固定导出流程
 
-先用 `scripts/summarize.py --request-dir <本次目录>` 写出 `payload.json` 草稿，Agent 复核文案后再调导出脚本。不要从原始回包手拼 12 列。
+业务生成调用 `scripts/run_workflow.py`，每条业务线单独生成一份 Excel；不先汇总全部业务线再导一份。`build_report.py` 是内部标准库导出器，正常流程不由 Agent 手改 payload 或另用第三方库二次排版。
 
-脚本在本技能目录的 `scripts/build_report.py`（与 `SKILL.md` 同级）。先定位本技能目录再执行，不要用仓库相对路径：
+主表 12 列不变，明细固定为：业务线、明细类型、动作、渠道、名称、补充。明细保留完整国家、同名不同 ID 广告/广告组、出价字段、新增成效、KPI 原文及数据周期覆盖。最终布局统一列宽、表头、冻结首行、筛选、换行及行高；主表过长内容转入「完整说明」明细，明细过长按续行完整保存，禁止静默截断。
 
-```bash
-python3 scripts/summarize.py --request-dir <本次 requestId 目录>
-python3 scripts/build_report.py --input <本次目录>/payload.json
-```
+## 输出与校验
 
-`payload.details` 写入 `明细` sheet，列固定为：业务线、明细类型、动作、渠道、名称、补充。
+先在本条临时目录生成一次最终样式，通过 ZIP、两张表、列名及逐单元格完整性校验后，以独占创建方式发布；再次回读验证成功才交付。最终目录必须在批次临时根外。
 
-payload 结构：
+默认最终目录为桌面 `~/Desktop`，不存在时回退用户主目录，可用 `--output-dir` 指定。文件名为 `业务线策略_<ID>_<名称>_<随机标识>.xlsx`，同名目标拒绝覆盖。
 
-```json
-{
-  "output_path": "可选，未传时默认写到用户桌面 业务线策略生成_YYYYMMDD_HHMMSS.xlsx",
-  "details": [
-    {"bizLine": "示例", "kind": "国家", "action": "新增", "channel": "TikTok", "name": "西撒哈拉", "extra": "消耗 $0"}
-  ],
-  "rows": [
-    {
-      "group": "华东组",
-      "bizLine": "示例业务线",
-      "period": "本期：2026-09-08～2026-09-10\n上期：2026-09-06～2026-09-08",
-      "project": "项目A\n项目B\n项目C",
-      "budgetStrategy": "...",
-      "budgetLearning": "...",
-      "productStrategy": "...",
-      "productLearning": "...",
-      "audienceStrategy": "...",
-      "audienceLearning": "...",
-      "creativeStrategy": "...",
-      "creativeLearning": "..."
-    }
-  ]
-}
-```
-
-也支持 stdin：`python3 scripts/build_report.py --input -`（把 JSON 从 stdin 喂入）。
-
-## 默认输出位置
-
-用户未指定路径时，默认写到当前用户桌面（`~/Desktop`，找不到则退回主目录），文件名 `业务线策略生成_YYYYMMDD_HHMMSS.xlsx`，避免覆盖**其他请求**已经落盘的文件。用户明确要求其他路径 / 文件名时，通过 `--output` 或 payload 的 `output_path` 指定。
-
-## 一次请求只留最终文件
-
-时间戳文件名是为了不覆盖**别的请求**，不是让同一次请求导很多份。同一次用户请求：
-
-1. payload 全部行定稿后再调用脚本，默认只成功写一次。
-2. 把 stdout 里的 `output_path` 记进本次 `excels_written`。
-3. 若必须重导：新文件成功后再删清单里的旧路径，可用 `scripts/cleanup.py --keep-excel <最终> --written-excel <旧1> --written-excel <旧2>`。
-4. **不要**用桌面 glob（`*策略生成*.xlsx`）再「只留最新」；未出现在本次 `excels_written` 里的文件一律当别人的，不准删。
-
-汇报给用户时给最终 Excel 路径，并附带本次 request 目录。原始 JSON 默认保留，见 [`runtime.md`](runtime.md)。
-
-## 返回值与校验
-
-脚本成功时输出 `{"ok": true, "output_path": "...", "row_count": N}`；失败（如 `rows` 为空）输出 `{"ok": false, "error": "..."}` 并以非 0 退出。Agent 应读取 `output_path` 回报给用户，不要凭假设的路径汇报。
-
-生成后不做自动打开或回读校验（脚本没有 Excel 运行环境可用），Agent 汇报时按 `row_count` 与实际处理的业务线/项目数核对是否一致，不一致要说明原因（如某业务线被 7.1 判定为不可生成而跳过）。
+每条业务线完成后只保留验证成功的最终文件，其他本次临时产物全部清理。汇报 `output_path` 及错误/残留（如有）；不附带已经删除的 request 目录。完整生命周期见 [`runtime.md`](runtime.md)。

package/dist/skills/custom/biz-line-strategy-generate/references/runtime.md

@@ -1,72 +1,37 @@
-# 运行时约定（临时文件 / Excel 落盘 / Windows 传参）
+# 执行、并发与清理
 
-接口字段与策略文案规则仍以 [`api-flow.md`](api-flow.md)、[`four-strategies.md`](four-strategies.md)、[`output-excel.md`](output-excel.md) 为准。本文件只约定调用方式、本次请求目录和清理范围。
+业务流程统一使用 `scripts/run_workflow.py`，低层 fetch/summarize/build 脚本仅供维护诊断，不作为日常生成入口。
 
-## 调用 CLI
+## 并发与调用
 
-- 输出用 `--format json`，**不要**传 `--json`（会 `validation`：未知参数）。
-- `--data` 必须是合法 JSON 对象字符串。`+list` 的名称/ID 也放进 `--data`（`list_query_body`），禁止 `+list --name` / `--id`。
-- CLI 回包用 `exec_cli_to_file` **直写文件**，不要 `capture_output=True`（沙箱里约 64KB 截断，出价/广告组明细会变成空页）。
-- **推荐直接跑 `scripts/fetch_data.py`**（内部用参数数组调 CLI，`shell=False`）。不要在 PowerShell 里手写 `--data '{"id":1}'`，也不要为了躲引号去写死本机 `dist/index.js` 路径。
-- **每次现拉**，不要拿上次 request 目录当命中缓存跳过接口。拉到的页立刻落盘。Excel 生成后**默认保留**整个 request 目录，不要 `cleanup.py --request-dir`。
-- 成功看信封 `ok == true` 或退出码 0。
-- 回包必须写 UTF-8 文件再解析。合并文件是 JSON **数组**（以 `[` 开头），`json.loads` 要从第一个 `[` 或 `{` 里更靠前的那个开始，不能先 `find("{")`——否则会把第一行对象当全文，解析失败后当成空数据。
+- 默认同时处理至多 3 条业务线，可显式设置 1 或 2。单条从查询到清理占一个名额，清理结束即补位。同一批次不能拆成多个入口绕过上限；不做跨会话全局调度。
+- 单条内部接口、渠道和分页串行；只通过已安装 `sino-bc-cli`，不手写 HTTP。
+- Windows 通过已安装 CLI 对应 Node 入口传参数数组，避免 cmd 重新解释 JSON。权限错误应报告，不当成未安装去自动下载。
+- `--format json`，请求用 `--data`。成功必须同时满足退出码 0 和信封 `ok == true`；stderr 与 stdout 都直写本次文件。
+- 列表行为 `data.result`，项目为 `data` 数组，维度/成效为 `data.data` 和 `data.total`。分页 `size=1000`、`PAGE_CAP=80`；总数未取全、提前空页、失败或总数变化均中止该条，不导出部分成功文件。
 
-### 信封里行数据在哪（认错会漏页）
-
-| 接口 | CLI 信封 `data` | 行数组 | 总数 |
-| --- | --- | --- | --- |
-| `+list` | 对象 | `data.result` | `data.total` |
-| `+detail` | 业务线对象本身 | — | — |
-| `+project-list` | **数组**（或对象里的 `result`） | `data` 或 `data.result` | `len` |
-| 维度 / 成效 | 对象 | **`data.data`** | **`data.total`** |
-
-维度/成效**不要**读 `data.result`。上一轮调试里认错字段会把 `got=0` 当成空页，1800+ 行广告只留下第 1 页。翻页：`page`/`size`（`size`≤1000），`acc < total` 就继续。`scripts/cli_json.py` 的 `unwrap_page` 已按上表处理。
-
-## 本次请求的工作目录
-
-每次用户请求开始时新建**唯一**目录，后续原始回包、payload 都只写这里，禁止写仓库、禁止和其他请求共用一个扁平目录：
+## 目录归属
 
 ```text
-%TEMP%/sino-bc-strategy/<requestId>/
-  bl-<bizLineId>/     ← 该业务线维度/成效原始 JSON
-  payload.json        ← 全部业务线行拼好后再写
+%TEMP%/sino-bc-strategy/batch-<随机标识>/
+  .strategy-owner.json
+  line-<业务线ID>-<随机标识>/
+    .strategy-owner.json
+    请求体、回包、stderr、merged JSON、payload、summary、临时 Excel
 ```
 
-`requestId` 用本次开始时刻，如 `20260910_174600`。心里维护两份清单（可写在该目录的 `manifest.json`）：
-
-- `temp_dirs`：已创建的 `bl-<id>/` 路径
-- `excels_written`：本次请求里 `build_report.py` 成功返回的每一个 `output_path`（按时间追加）
-
-## 按业务线清理临时文件
+每次现拉，新建目录，不复用历史缓存。所有本次临时文件写入本次目录；不向技能源码树写缓存。最终 Excel 写在批次临时根以外，文件名包含业务线 ID 和随机请求标识，独占创建、不覆盖已有文件。
 
-对**一条**业务线：接口全部拉完 → 文案写入 `payload.json` → **保留** `bl-<bizLineId>/` 原始回包，不要删。跳过（未绑定项目/账号）的业务线若没有建目录，则不用处理。
+## 逐条清理
 
-## 整次请求结束时清理
+成功路径：最终文件发布并回读验证 → 清理该业务线临时目录 → 输出完成结果。失败路径：保存可返回的错误摘要 → 关闭子进程 → 清理该业务线临时目录。所有任务停止后清理本次批次共享目录。
 
-Excel 成功落盘之后：
-
-1. 按下面规则处理 Excel（只动本次清单的旧 xlsx）。
-2. **保留**整个 `%TEMP%/sino-bc-strategy/<requestId>/`（原始回包 + `payload.json`），汇报时带上该路径。
-3. 只有用户明确要求清缓存时才 `cleanup.py --request-dir`。不要删其他 `requestId`。
-
-中途失败也保留本次 `requestId` 目录，便于对照回包排障；不要和下次请求共用同一目录。新请求必须新建 `requestId`。
-
-可用本技能脚本：
-
-```bash
-python3 scripts/cleanup.py --request-dir <本次 requestId 目录>
-python3 scripts/cleanup.py --keep-excel <最终xlsx> --written-excel <本次写过的xlsx1> --written-excel <xlsx2>
-```
+清理不限扩展名，包括 JSON、TXT、图片、日志副本、临时 Python、检查文件、缓存和所有临时 Excel；仅保留已验证的最终 Excel。清理范围以进程新建的目录、随机所有权标记及真实父路径为边界，不扫桌面、历史请求、其他任务或 CLI 全局审计日志，不动源码、技能和凭证。
 
-`--written-excel` 可重复。脚本**只删除出现在 `--written-excel` 里、且不是 `--keep-excel` 的文件**；路径对不上的一律跳过。
+符号链接和 Windows junction/reparse point 只移除本次目录中的链接本身，不能递归跟随目标。最终路径落入临时根时拒绝执行。文件占用或归属异常会返回残留路径并令批次非零退出，已验证最终文件仍保留。
 
-## 一次请求只留一份最终 Excel
+Ctrl+C/SIGTERM 停止启动新任务，并等待在途 CLI 终止后清理；强杀/断电无法保证清理，不自动删除历史遗留目录。
 
-- 先把**全部**业务线行的策略文案定稿，再调用一次 `scripts/build_report.py`。不要「先导一版再改文案再导一版」。
-- 若必须重导（脚本失败、列数不对、文案发现硬伤）：记下新的 `output_path`，立刻删掉本次清单里**上一份** Excel。只删 `excels_written` 里的精确路径。
-- **禁止**：按桌面文件名 glob（`业务线策略生成_*.xlsx`）再「只留最新」——会把**其他请求**的最终文件删掉。
-- **禁止**：`Remove-Item -Force` 扫整个桌面时间戳范围。
-- 其他请求、用户自己放在桌面的 xlsx，一律不动。
+## 输出
 
-向用户汇报最终 Excel 路径，并附带本次 `request_dir`。
+控制台 JSON 行返回业务线 ID、阶段进度、各阶段耗时和完成结果；最终事件包含成功/失败数量及每条 `output_path` 或错误。任意生成/导出/清理失败时批次非零退出，其他成功文件保留。不额外保留性能报告、预览图或分析日志。

package/dist/skills/custom/biz-line-strategy-generate/references/spec.md

@@ -0,0 +1,124 @@
+# 业务线策略生成
+
+## Purpose
+
+为业务线策略生成技能规定可复用的分析、Excel 导出与批量执行行为，保证多条业务线运行时有明确的并发上限、独立结果和失败信息，并在每条任务结束后仅保留验证通过的最终文件，避免临时数据持续堆积或误删其他任务产物。
+
+## Requirements
+
+### Requirement: 统一生成入口与业务线隔离
+
+技能 MUST 提供覆盖查询、拉数、分析、校验、导出和清理的统一入口。单业务线与多业务线 MUST 使用相同分析规则。输入 MUST 支持名称查找和显式业务线 ID 列表；批量候选 MUST 按 ID 去重。名称匹配不唯一时 MUST 明确报告歧义而非自动取第一条。业务请求 MUST 复用现有 CLI，MUST NOT 手写网关 HTTP 或绕过身份约束。
+
+#### Scenario: 批量重复 ID 不重复生成
+- **GIVEN** 输入列表包含相同业务线 ID 两次
+- **WHEN** 执行统一入口
+- **THEN** 该业务线只执行一次，拥有独立工作目录和唯一最终 Excel
+
+#### Scenario: 名称存在歧义
+- **GIVEN** 名称查询返回多条候选
+- **WHEN** 解析单业务线目标
+- **THEN** 返回候选与歧义错误，不启动这些候选的投放拉数任务
+
+### Requirement: 单次执行最多并发三条业务线
+
+一次技能调用 MUST 默认最多同时运行 3 条业务线任务，允许设置 1 至 3，超出范围 MUST 在启动业务任务前拒绝。一个业务线从拉数到清理结束 MUST 占用同一个并发名额。该业务线内部的 CLI 请求和分页 MUST 继续顺序执行，MUST NOT 叠加子级并发。待处理业务线在名额释放后继续启动。
+
+#### Scenario: 十条业务线受并发上限约束
+- **GIVEN** 请求生成 10 条不同业务线
+- **WHEN** 默认执行批量入口
+- **THEN** 任意时刻运行中的业务线数不超过 3，且有名额后继续处理队列
+- **AND** 已完成业务线立即交付并清理，不等待全部 10 条结束
+
+#### Scenario: 非法并发参数不发起请求
+- **GIVEN** 并发参数为 0、4 或非整数
+- **WHEN** 启动统一入口
+- **THEN** 返回参数错误，不创建业务输出或调用业务接口
+
+### Requirement: 分页与失败回包必须完整校验
+
+每页 CLI 回包 MUST 直写文件并检查退出码、信封和分页总数。异常、解析失败、未到总数即遇空页、达到分页上限仍未取全，MUST 阻止该业务线生成成功报告。CLI stderr 错误 MUST 保留到本次任务结果摘要，而非当作无数据。其他业务线 MUST 可以继续执行。
+
+#### Scenario: 后续页失败不导出部分结果
+- **GIVEN** 首页成功且声明仍有下一页
+- **WHEN** 后续页调用失败或返回空页但累计数量不足
+- **THEN** 该业务线失败，不将不完整数据生成最终 Excel，其他业务线继续执行
+
+### Requirement: 指标与周期口径固定
+
+分析 MUST 从同粒度基础指标先求和再计算比率，分母为零或所需指标缺失时明确不可计算。安装 CPI MUST 标注为美元消耗除以平台安装量，MUST NOT 直接改称客户激活或留存成本。缺少同币种、同转化定义或留存数据时，客户 KPI MUST 标为不可判定，MUST NOT 使用固定 CPM 阈值替代。首期按可判定 KPI 输出，否则待观察；第二期按可计算核心指标环比判定，绝对变化不超过 10% 为稳定；成本下降、收益指标上升为改善。无可比核心指标时 MUST 待观察并说明原因。
+
+请求周期与实际返回的数据覆盖范围 MUST 分别展示。数据未覆盖完整请求周期时 MUST 提示不完整，MUST NOT 将较短周期消耗下降直接解释为主动减预算。新增部分成效 MUST 单独聚合，MUST NOT 将业务线整体环比宣称为单一动作的因果效果。
+
+#### Scenario: 人民币 CPA 与美元安装数据不可直接对标
+- **GIVEN** 客户目标是人民币 CPA 与次日留存，接口返回美元消耗和平台安装量
+- **WHEN** 缺少汇率、CPA 定义或留存数据
+- **THEN** 仅计算已支持的观察指标，明确客户 KPI 暂不可判定，不生成 CPM 默认达标结论
+
+#### Scenario: 本期六天与上期七天
+- **GIVEN** 请求两个七天周期，但本期只返回六个日期
+- **WHEN** 生成策略及 learning
+- **THEN** 展示请求日期和实际覆盖日期，并提示消耗总额比较存在周期差异
+
+### Requirement: 对象与明细按稳定标识统计
+
+广告和广告组 MUST 按渠道及 ID 判断新增与本期未出现，MUST NOT 仅按名称去重。完整明细 MUST 保留同名不同 ID 的记录。两期集合差异 MUST NOT 被描述为已确认的创建或暂停操作。出价变化 MUST 按广告组日快照计算，并区分上调、下调、期内变化但首末持平；无值 MUST NOT 默认为零。国家全量与过消耗门槛的新增成效 MUST 可在明细追溯。
+
+#### Scenario: 同名广告不可合并
+- **GIVEN** 两个不同广告 ID 使用同一名称
+- **WHEN** 统计新增广告并导出明细
+- **THEN** 分别计数并输出 ID，不因名称相同而丢失其中一条
+
+#### Scenario: 期内调价后恢复原价
+- **GIVEN** 一个广告组期内出价变化但首末有效快照一致
+- **WHEN** 生成出价摘要
+- **THEN** 计为首末持平的期内变化，不归类为下调
+
+### Requirement: 每条业务线只交付一份校验通过的最终 Excel
+
+每条业务线 MUST 独立产出一份包含固定 12 列策略摘要及完整明细的 Excel。分析与排版 MUST 由固定脚本完成；正常流程 MUST 一次生成最终样式，MUST NOT 依赖 Agent 临时生成修订脚本或二次导入重排。文件发布前 MUST 检查 Excel 容器、两张表、列名及记录完整性。最终路径 MUST 位于待清理工作目录之外，名称 MUST 能区分业务线与请求，MUST NOT 覆盖已存在的其他文件。
+
+#### Scenario: 并发生成不覆盖结果
+- **GIVEN** 两条业务线在同一秒完成导出
+- **WHEN** 发布最终文件
+- **THEN** 获得两个不同且可读取的文件路径，各自包含对应业务线数据
+
+#### Scenario: 校验失败不发布损坏文件
+- **GIVEN** Excel 缺少明细表或明细行数不一致
+- **WHEN** 执行发布前校验
+- **THEN** 该任务失败，不对外声明最终 Excel 已生成
+
+### Requirement: 任务结束后按归属清理全部临时产物
+
+每条业务线任务完成后，MUST 清理本次任务创建的全部非最终产物，包括但不限于 JSON、请求/响应、日志副本、预览图片、临时脚本、临时 Excel、检查文件及运行时缓存。成功时 MUST 先确认最终文件已发布且验证通过，再清理；失败时 MUST 先保存可返回的错误摘要到内存/输出，再清理其临时和不完整产物。所有任务结束后 MUST 清理本次批次共享临时目录。MUST NOT 保留额外磁盘分析报告或将已删除目录作为交付物。
+
+清理 MUST 以本次创建的独立目录及登记文件为边界，校验规范化绝对路径及所有权，MUST NOT 按扩展名或桌面 glob 广泛扫描。MUST NOT 删除历史请求、其他并行业务线、仓库源码、技能目录、平台凭证或 CLI 全局审计日志。符号链接、Windows junction/reparse point MUST NOT 被递归跟随到边界外。存在清理失败时 MUST 明确报告残留路径和原因，不宣称已完全清理。
+
+#### Scenario: 成功后只保留最终文件
+- **GIVEN** 本次业务线目录中存在 JSON、PNG、TXT、无扩展名文件和临时子目录
+- **WHEN** 最终 Excel 发布并校验成功
+- **THEN** 上述临时产物及业务线临时目录均被清理，最终 Excel 仍可读取
+
+#### Scenario: 失败任务不残留临时文件
+- **GIVEN** 拉数或分析失败且已创建部分回包和临时输出
+- **WHEN** 该业务线任务结束
+- **THEN** 返回业务线 ID、失败阶段和错误摘要，清理其拥有的临时产物，继续处理其他任务
+
+#### Scenario: 清理链接时保护外部目录
+- **GIVEN** 本次临时目录中有链接指向另一任务或用户目录
+- **WHEN** 执行清理
+- **THEN** 不遍历或删除链接目标，外部文件及其他任务目录保持不变
+
+#### Scenario: 文件占用导致清理失败
+- **GIVEN** 最终 Excel 已验证，但一个临时文件被占用且删除失败
+- **WHEN** 工作流结束清理
+- **THEN** 返回最终文件路径及清理失败状态和残留路径，批次以非成功状态结束
+
+### Requirement: 批次结果可观察且失败互不掩盖
+
+工作流 MUST 按业务线返回阶段状态、最终 Excel 路径或失败原因，并提供阶段耗时和批次成功/失败数量。结果 MUST 区分生成失败、导出失败、清理失败；任一任务失败时批次 MUST 非零退出，同时保留其他任务的成功文件。耗时结果 MUST 通过输出或最终 Excel 内已有适当区域提供，MUST NOT 为此保留额外临时报告。用户可处理的中断 MUST 停止启动新任务并等待/终止子进程后执行边界内清理；进程被强制杀死或断电的情形不得宣称已完成清理。
+
+#### Scenario: 混合结果完整汇报
+- **GIVEN** 三条业务线分别成功、拉数失败、清理失败
+- **WHEN** 批次收尾
+- **THEN** 输出三条各自结果与阶段耗时，保留成功的最终 Excel，批次非零退出

package/dist/skills/custom/biz-line-strategy-generate/scripts/build_report.py

@@ -4,7 +4,7 @@
 把业务线策略生成结果写成 .xlsx（业务线策略生成 skill 专用，纯标准库实现，无第三方依赖）。
 
 职责边界：本脚本只负责「结构化数据 -> Excel 文件」的机械落盘，
-不做任何数据拉取、策略文案生成或判断——那些都由调用方（Agent）在此之前完成。
+不做数据拉取和业务判断；统一入口先通过固定汇总脚本生成内容。
 
 用法：
     python3 build_report.py --input payload.json [--output /path/to/file.xlsx]
@@ -18,7 +18,7 @@ payload.json 结构：
     {
       "bizLine": "业务线",
       "kind": "国家|广告组|出价|兴趣词|关键词|广告",
-      "action": "新增|关停|上调|下调|当期",
+      "action": "新增|本期未出现|上调|下调|当期",
       "channel": "Meta|Google|TikTok",
       "name": "名称",
       "extra": "补充"
@@ -38,6 +38,11 @@ import json
 import os
 import sys
 import zipfile
+import math
+import unicodedata
+import uuid
+from pathlib import Path
+from xml.etree import ElementTree as ET
 from datetime import datetime
 from xml.sax.saxutils import escape as xml_escape
 
@@ -70,7 +75,7 @@ CONTENT_KEYS = {key for key, _label in COLUMNS[4:]}
 
 # 列宽：策略内容列最宽；项目名称列因单元格内多行罗列项目而适度加宽
 COL_WIDTH_DEFAULT = 14
-COL_WIDTH_CONTENT = 40
+COL_WIDTH_CONTENT = 48
 COL_WIDTH_MULTILINE = 22
 MULTILINE_KEYS = {"period", "project"}
 
@@ -169,8 +174,9 @@ def build_shared_strings(rows, details=None):
             [intern(str(row.get(key, "") or "")) for key, _label in DETAIL_COLUMNS]
         )
 
+    # XML 会把原始 CR/CRLF 归一化为 LF；用字符引用保留客户文本，保证逐字回读。
     items = "".join(
-        f'<si><t xml:space="preserve">{xml_escape(text)}</t></si>' for text in order
+        f'<si><t xml:space="preserve">{xml_escape(text, {chr(13): "&#13;"})}</t></si>' for text in order
     )
     sst_xml = (
         '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
@@ -180,7 +186,7 @@ def build_shared_strings(rows, details=None):
     return sst_xml, header_indices, row_indices, detail_header, detail_rows
 
 
-def build_sheet_xml(header_indices, row_indices, columns, content_keys=None, multiline_keys=None):
+def build_sheet_xml(header_indices, row_indices, columns, content_keys=None, multiline_keys=None, values=None):
     """生成 worksheet xml：首行表头样式 s="1"，其余行内容样式 s="2"（自动换行）"""
     content_keys = content_keys or set()
     multiline_keys = multiline_keys or set()
@@ -205,7 +211,14 @@ def build_sheet_xml(header_indices, row_indices, columns, content_keys=None, mul
         for i, sst_index in enumerate(indices):
             ref = f"{col_letter(i)}{row_num}"
             cells.append(f'<c r="{ref}" s="{style_id}" t="s"><v>{sst_index}</v></c>')
-        return f'<row r="{row_num}">{"".join(cells)}</row>'
+        # Excel 不会可靠地对程序生成的行自动增高，按中文显示宽度确定行高。
+        if row_num == 1:
+            height = 32
+        else:
+            record = (values or [{}] * len(row_indices))[row_num - 2]
+            lines = max((visual_lines(str(record.get(key) or ""), COL_WIDTH_CONTENT if key in content_keys else (COL_WIDTH_MULTILINE if key in multiline_keys else COL_WIDTH_DEFAULT)) for key, _ in columns), default=1)
+            height = min(409, max(30, lines * 15 + 10))
+        return f'<row r="{row_num}" ht="{height}" customHeight="1">{"".join(cells)}</row>'
 
     rows_xml_parts = [row_xml(1, header_indices, 1)]
     for offset, indices in enumerate(row_indices):
@@ -220,7 +233,7 @@ def build_sheet_xml(header_indices, row_indices, columns, content_keys=None, mul
         '<sheetViews><sheetView workbookViewId="0">'
         '<pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/>'
         '</sheetView></sheetViews>'
-        f'{cols_xml}{sheet_data}'
+        f'{cols_xml}{sheet_data}<autoFilter ref="{dimension_ref}"/>'
         '</worksheet>'
     )
 
@@ -233,10 +246,64 @@ def default_output_path() -> str:
         # 部分中文 Windows / OneDrive 环境桌面路径不同，找不到就退回主目录
         desktop = home
     stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    return os.path.join(desktop, f"业务线策略生成_{stamp}.xlsx")
+    return os.path.join(desktop, f"业务线策略生成_{stamp}_{uuid.uuid4().hex[:8]}.xlsx")
+
+
+def visual_lines(text, width):
+    """中日韩字符占两格，保守估算换行后高度。"""
+    return sum(max(1, math.ceil(sum(2 if unicodedata.east_asian_width(c) in 'WF' else 1 for c in line) / max(1, width - 2))) for line in text.split('\n'))
+
+
+def chunks(text, width, max_lines=20):
+    """按可见行宽拆分，续行不丢字符，避免 Excel 行高及单元格字数上限。"""
+    result, part = [], ''
+    # 线性维护行宽，不对越来越长的片段重复扫描。
+    lines, used = 1, 0
+    for char in text:
+        size = 2 if unicodedata.east_asian_width(char) in 'WF' else 1
+        next_line = char == '\n' or used + size > width - 2
+        if (next_line and lines >= max_lines) or len(part) >= 16000:
+            result.append(part)
+            part, lines, used = '', 1, 0
+        if char == '\n':
+            lines, used = lines + 1, 0
+        elif used + size > width - 2:
+            lines, used = lines + 1, size
+        else:
+            used += size
+        part += char
+    return result + [part] if part or not result else result
+
+
+def prepare_layout(rows, details):
+    """主表只放可见摘要，超长原文转完整明细；明细用续行保持全量。"""
+    rows = [dict(r) for r in rows]
+    details = [dict(r) for r in details or []]
+    for row in rows:
+        for key, label in COLUMNS:
+            text = str(row.get(key) or '')
+            width = COL_WIDTH_CONTENT if key in CONTENT_KEYS else (COL_WIDTH_MULTILINE if key in MULTILINE_KEYS else COL_WIDTH_DEFAULT)
+            parts = chunks(text, width, 18)
+            if len(parts) > 1:
+                details.append({'bizLine': row.get('bizLine', ''), 'kind': '完整说明', 'action': label, 'name': label, 'extra': text})
+                row[key] = parts[0] + '\n（完整内容见明细/完整说明）'
+    expanded = []
+    for record in details:
+        split = {key: chunks(str(record.get(key) or ''), COL_WIDTH_CONTENT if key in ('name', 'extra') else COL_WIDTH_DEFAULT, 18) for key, _ in DETAIL_COLUMNS}
+        count = max(map(len, split.values()))
+        for index in range(count):
+            # 续行有行号标识，身份短字段重复展示便于筛选；长字段逐段保留。
+            row = {key: (parts[index] if index < len(parts) else (parts[0] if len(parts) == 1 and key not in ('name', 'extra') else '')) for key, parts in split.items()}
+            if count > 1:
+                row['action'] += f' [续 {index + 1}/{count}]'
+            expanded.append(row)
+    return rows, expanded
 
 
 def write_xlsx(rows, output_path: str, details=None) -> str:
+    if not rows:
+        raise ValueError('策略数据为空')
+    rows, details = prepare_layout(rows, details)
     sst_xml, header_indices, row_indices, detail_header, detail_rows = build_shared_strings(
         rows, details
     )
@@ -246,6 +313,7 @@ def write_xlsx(rows, output_path: str, details=None) -> str:
         COLUMNS,
         content_keys=CONTENT_KEYS,
         multiline_keys=MULTILINE_KEYS,
+        values=rows,
     )
     detail_xml = build_sheet_xml(
         detail_header,
@@ -253,13 +321,14 @@ def write_xlsx(rows, output_path: str, details=None) -> str:
         DETAIL_COLUMNS,
         content_keys={"name", "extra"},
         multiline_keys=set(),
+        values=details,
     )
 
     out_dir = os.path.dirname(output_path)
     if out_dir and not os.path.isdir(out_dir):
         os.makedirs(out_dir, exist_ok=True)
 
-    with zipfile.ZipFile(output_path, "w", zipfile.ZIP_DEFLATED) as zf:
+    with zipfile.ZipFile(output_path, "x", zipfile.ZIP_DEFLATED) as zf:
         zf.writestr("[Content_Types].xml", CONTENT_TYPES_XML)
         zf.writestr("_rels/.rels", ROOT_RELS_XML)
         zf.writestr("xl/workbook.xml", WORKBOOK_XML)
@@ -272,6 +341,26 @@ def write_xlsx(rows, output_path: str, details=None) -> str:
     return output_path
 
 
+def validate_xlsx(path, rows, details):
+    """逐单元格回读，与布局后的完整输入比较，避免只检验文件存在。"""
+    ns = {'s': 'http://schemas.openxmlformats.org/spreadsheetml/2006/main'}
+    expected = prepare_layout(rows, details)
+    with zipfile.ZipFile(path) as archive:
+        if archive.testzip():
+            raise ValueError('Excel ZIP 校验失败')
+        workbook = ET.fromstring(archive.read('xl/workbook.xml'))
+        if [s.attrib['name'] for s in workbook.findall('s:sheets/s:sheet', ns)] != ['策略', '明细']:
+            raise ValueError('Excel 必须包含策略和明细两张表')
+        strings = [''.join(item.itertext()) for item in ET.fromstring(archive.read('xl/sharedStrings.xml'))]
+        for index, (records, columns) in enumerate(zip(expected, (COLUMNS, DETAIL_COLUMNS)), 1):
+            sheet = ET.fromstring(archive.read(f'xl/worksheets/sheet{index}.xml'))
+            actual = [[strings[int(cell.find('s:v', ns).text)] for cell in row] for row in sheet.findall('s:sheetData/s:row', ns)]
+            target = [[label for _, label in columns]] + [[str(r.get(key) or '') for key, _ in columns] for r in records]
+            if actual != target:
+                raise ValueError(f'Excel 第 {index} 张表内容或行列数不完整')
+    return {'rows': len(expected[0]), 'details': len(expected[1])}
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument(