sino-bc-cli 1.8.19 → 1.8.21

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]
@@ -13,16 +13,15 @@
 payload.json 结构：
 {
   "output_path": "可选，未传时默认写到桌面 业务线策略生成_YYYYMMDD_HHMMSS.xlsx",
-  "rows": [
+  "rows": [ { "...策略摘要行..." } ],
+  "details": [
     {
-      "group": "组别",
-      "bizLine": "业务线名称",
-      "period": "本期：2026-09-08～2026-09-10\n上期：2026-09-06～2026-09-08",
-      "project": "项目A\n项目B",
-      "budgetStrategy": "预算策略内容", "budgetLearning": "预算策略learning",
-      "productStrategy": "广告产品策略内容", "productLearning": "广告产品策略learning",
-      "audienceStrategy": "受众策略内容", "audienceLearning": "受众策略learning",
-      "creativeStrategy": "素材策略内容", "creativeLearning": "素材策略learning"
+      "bizLine": "业务线",
+      "kind": "国家|广告组|出价|兴趣词|关键词|广告",
+      "action": "新增|本期未出现|上调|下调|当期",
+      "channel": "Meta|Google|TikTok",
+      "name": "名称",
+      "extra": "补充"
     }
   ]
 }
@@ -39,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
 
@@ -58,11 +62,20 @@ COLUMNS = [
 ]
 
 # 策略内容列文字量最大，给最宽的列宽（前 4 列是基础信息列）
+DETAIL_COLUMNS = [
+    ("bizLine", "业务线"),
+    ("kind", "明细类型"),
+    ("action", "动作"),
+    ("channel", "渠道"),
+    ("name", "名称"),
+    ("extra", "补充"),
+]
+
 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"}
 
@@ -72,6 +85,7 @@ CONTENT_TYPES_XML = """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <Default Extension="xml" ContentType="application/xml"/>
 <Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>
 <Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>
+<Override PartName="/xl/worksheets/sheet2.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>
 <Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>
 <Override PartName="/xl/sharedStrings.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml"/>
 </Types>"""
@@ -86,11 +100,15 @@ WORKBOOK_RELS_XML = """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>
 <Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>
 <Relationship Id="rId3" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings" Target="sharedStrings.xml"/>
+<Relationship Id="rId4" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet2.xml"/>
 </Relationships>"""
 
 WORKBOOK_XML = """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
-<sheets><sheet name="业务线策略生成" sheetId="1" r:id="rId1"/></sheets>
+<sheets>
+<sheet name="策略" sheetId="1" r:id="rId1"/>
+<sheet name="明细" sheetId="2" r:id="rId4"/>
+</sheets>
 </workbook>"""
 
 # cellXfs: 0=默认, 1=表头(粗体+浅底), 2=内容(自动换行+顶对齐)
@@ -129,8 +147,7 @@ def col_letter(index: int) -> str:
     return letters
 
 
-def build_shared_strings(rows):
-    """收集全部字符串去重，返回 (sst_xml, header_indices, row_indices)"""
+def _intern_factory():
     seen = {}
     order = []
 
@@ -140,34 +157,47 @@ def build_shared_strings(rows):
             order.append(value)
         return seen[value]
 
+    return intern, order
+
+
+def build_shared_strings(rows, details=None):
+    """收集策略表 + 明细表全部字符串去重。"""
+    intern, order = _intern_factory()
     header_indices = [intern(label) for _key, label in COLUMNS]
-    row_indices = []
-    for row in rows:
-        row_indices.append(
-            [intern(str(row.get(key, "") or "")) for key, _label in COLUMNS]
+    row_indices = [
+        [intern(str(row.get(key, "") or "")) for key, _label in COLUMNS] for row in rows
+    ]
+    detail_header = [intern(label) for _key, label in DETAIL_COLUMNS]
+    detail_rows = []
+    for row in details or []:
+        detail_rows.append(
+            [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"?>'
         f'<sst xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" '
         f'count="{len(order)}" uniqueCount="{len(order)}">{items}</sst>'
     )
-    return sst_xml, header_indices, row_indices
+    return sst_xml, header_indices, row_indices, detail_header, detail_rows
 
 
-def build_sheet_xml(header_indices, row_indices):
-    """生成 sheet1.xml：首行表头样式 s="1"，其余行内容样式 s="2"（自动换行）"""
-    col_count = len(COLUMNS)
+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()
+    col_count = len(columns)
     dimension_ref = f"A1:{col_letter(col_count - 1)}{len(row_indices) + 1}"
 
     cols_xml_parts = []
-    for i, (key, _label) in enumerate(COLUMNS):
-        if key in CONTENT_KEYS:
+    for i, (key, _label) in enumerate(columns):
+        if key in content_keys:
             width = COL_WIDTH_CONTENT
-        elif key in MULTILINE_KEYS:
+        elif key in multiline_keys:
             width = COL_WIDTH_MULTILINE
         else:
             width = COL_WIDTH_DEFAULT
@@ -181,7 +211,14 @@ def build_sheet_xml(header_indices, row_indices):
         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):
@@ -196,7 +233,7 @@ def build_sheet_xml(header_indices, row_indices):
         '<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>'
     )
 
@@ -209,18 +246,89 @@ 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 write_xlsx(rows, output_path: str) -> str:
-    sst_xml, header_indices, row_indices = build_shared_strings(rows)
-    sheet_xml = build_sheet_xml(header_indices, row_indices)
+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
+    )
+    sheet_xml = build_sheet_xml(
+        header_indices,
+        row_indices,
+        COLUMNS,
+        content_keys=CONTENT_KEYS,
+        multiline_keys=MULTILINE_KEYS,
+        values=rows,
+    )
+    detail_xml = build_sheet_xml(
+        detail_header,
+        detail_rows,
+        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)
@@ -228,10 +336,31 @@ def write_xlsx(rows, output_path: str) -> str:
         zf.writestr("xl/styles.xml", STYLES_XML)
         zf.writestr("xl/sharedStrings.xml", sst_xml)
         zf.writestr("xl/worksheets/sheet1.xml", sheet_xml)
+        zf.writestr("xl/worksheets/sheet2.xml", detail_xml)
 
     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(
@@ -258,12 +387,20 @@ def main() -> int:
 
     output_path = args.output or payload.get("output_path") or default_output_path()
     output_path = os.path.abspath(output_path)
+    details = payload.get("details") or []
+    if not isinstance(details, list):
+        details = []
 
-    write_xlsx(rows, output_path)
+    write_xlsx(rows, output_path, details=details)
 
     print(
         json.dumps(
-            {"ok": True, "output_path": output_path, "row_count": len(rows)},
+            {
+                "ok": True,
+                "output_path": output_path,
+                "row_count": len(rows),
+                "detail_count": len(details),
+            },
             ensure_ascii=False,
         )
     )

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

@@ -1,96 +1,87 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-"""只清理「本次请求」登记过的临时目录和 Excel。
-
-不会按桌面文件名 glob，也不会删除未出现在 --written-excel 里的文件。
-"""
+"""仅清理本次进程创建并登记的目录，所有类型临时文件统一处理。"""
 from __future__ import annotations
 
-import argparse
 import json
 import os
-import shutil
-import sys
-
+import stat
+import tempfile
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
 
-def rm_request_dir(path: str) -> dict:
-    if not path:
-        return {"ok": False, "error": "empty --request-dir"}
-    abs_path = os.path.abspath(path)
-    if not os.path.isdir(abs_path):
-        return {"ok": True, "removed_dir": abs_path, "existed": False}
-    # 只允许删 sino-bc-strategy 下的某一层 requestId 目录，防止误传桌面/主目录
-    parent = os.path.basename(os.path.dirname(abs_path)).lower()
-    if parent != "sino-bc-strategy":
-        return {
-            "ok": False,
-            "error": "refuse: --request-dir 必须是 .../sino-bc-strategy/<requestId>",
-        }
-    shutil.rmtree(abs_path, ignore_errors=False)
-    return {"ok": True, "removed_dir": abs_path, "existed": True}
+MARKER = '.strategy-owner.json'
 
 
-def rm_extra_excels(keep: str | None, written: list[str]) -> dict:
-    keep_abs = os.path.abspath(keep) if keep else None
-    deleted = []
-    skipped = []
-    for raw in written:
-        if not raw:
-            continue
-        target = os.path.abspath(raw)
-        if keep_abs and os.path.normcase(target) == os.path.normcase(keep_abs):
-            skipped.append({"path": target, "reason": "keep"})
-            continue
-        if not os.path.isfile(target):
-            skipped.append({"path": target, "reason": "missing"})
-            continue
-        os.remove(target)
-        deleted.append(target)
-    return {"ok": True, "deleted": deleted, "skipped": skipped, "kept": keep_abs}
+def is_link(path: Path) -> bool:
+    """Windows junction 等重解析点与符号链接都不允许递归跟随。"""
+    info = path.lstat()
+    return stat.S_ISLNK(info.st_mode) or bool(getattr(info, 'st_file_attributes', 0) & 0x400)
 
 
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument(
-        "--request-dir",
-        default=None,
-        help="本次请求工作目录 TEMP/sino-bc-strategy/<requestId>，整目录删除",
-    )
-    parser.add_argument(
-        "--keep-excel",
-        default=None,
-        help="最终保留的 xlsx 绝对路径",
-    )
-    parser.add_argument(
-        "--written-excel",
-        action="append",
-        default=[],
-        help="本次请求成功写出过的 xlsx，可重复；只从这份名单里删",
-    )
-    args = parser.parse_args()
+@dataclass(frozen=True)
+class OwnedDirectory:
+    """创建时保存真实父路径与随机令牌，清理时不能只相信目录名。"""
+    path: Path
+    parent: Path
+    token: str
 
-    if not args.request_dir and not args.written_excel:
-        print(
-            json.dumps(
-                {"ok": False, "error": "至少传 --request-dir 或 --written-excel"},
-                ensure_ascii=False,
-            )
-        )
-        return 1
+    @classmethod
+    def create(cls, parent: Path, prefix: str):
+        parent = parent.resolve()
+        parent.mkdir(parents=True, exist_ok=True)
+        path = Path(tempfile.mkdtemp(prefix=prefix, dir=parent))
+        token = uuid.uuid4().hex
+        (path / MARKER).write_text(json.dumps({'token': token, 'path': str(path)}), encoding='utf-8')
+        return cls(path, parent, token)
 
-    result = {"ok": True}
-    if args.written_excel:
-        result["excels"] = rm_extra_excels(args.keep_excel, args.written_excel)
-        if result["excels"].get("ok") is False:
-            result["ok"] = False
-    if args.request_dir:
-        result["temps"] = rm_request_dir(args.request_dir)
-        if result["temps"].get("ok") is False:
-            result["ok"] = False
+    def validate(self):
+        """根目录或父路径被替换后拒绝删除，防止越界。"""
+        if is_link(self.path) or self.path.resolve() != self.path or self.path.parent.resolve() != self.parent:
+            raise ValueError(f'清理范围已变化：{self.path}')
+        marker = self.path / MARKER
+        if is_link(marker):
+            raise ValueError('所有权文件不能是链接')
+        data = json.loads(marker.read_text(encoding='utf-8'))
+        if data != {'token': self.token, 'path': str(self.path)}:
+            raise ValueError(f'所有权不匹配：{self.path}')
 
-    print(json.dumps(result, ensure_ascii=False))
-    return 0 if result["ok"] else 1
+    def cleanup(self, final: Path | None = None) -> dict:
+        """不按后缀筛选；保留可返回的失败清单，绝不静默忽略残留。"""
+        errors = []
+        try:
+            self.validate()
+            if final is not None and final.resolve().is_relative_to(self.path):
+                raise ValueError('最终 Excel 位于临时目录内，拒绝清理')
+        except Exception as exc:
+            return {'ok': False, 'residual': [{'path': str(self.path), 'error': str(exc)}]}
 
+        def remove(path):
+            try:
+                # 先 lstat 再决定删除方式；对 junction 仅解除链接自身。
+                if is_link(path):
+                    if path.is_symlink():
+                        path.unlink()
+                    else:
+                        os.rmdir(path)
+                elif path.is_dir():
+                    for child in path.iterdir():
+                        remove(child)
+                    path.rmdir()
+                else:
+                    path.unlink()
+            except Exception as exc:
+                errors.append({'path': str(path), 'error': str(exc)})
 
-if __name__ == "__main__":
-    sys.exit(main())
+        # 若某子项未能删除，留下所有权标记供诊断，不伪报清理成功。
+        for child in self.path.iterdir():
+            if child.name != MARKER:
+                remove(child)
+        if not errors:
+            remove(self.path / MARKER)
+            try:
+                self.path.rmdir()
+            except Exception as exc:
+                errors.append({'path': str(self.path), 'error': str(exc)})
+        return {'ok': not errors, 'residual': errors}