sino-bc-cli 1.0.0-beta.0

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

@@ -0,0 +1,629 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+把业务线策略生成结果写成 .xlsx（业务线策略生成 skill 专用，纯标准库实现，无第三方依赖）。
+
+职责边界：本脚本只负责「结构化数据 -> Excel 文件」的机械落盘，
+不做数据拉取和业务判断；统一入口先通过固定汇总脚本生成内容。
+
+用法：
+    python3 build_report.py --input payload.json [--output /path/to/file.xlsx]
+    cat payload.json | python3 build_report.py --input -
+
+payload.json 结构（统一工作流另将 Agent 回包传给导出函数）：
+{
+  "output_path": "可选，未传时默认写到桌面 业务线策略生成_YYYYMMDD_HHMMSS.xlsx",
+  "rows": [ { "...策略摘要行..." } ],
+  "details": [{"kind": "广告组", "action": "新增", "channel": "Meta",
+               "id": "广告组ID", "name": "名称", "spend_usd": "本期（上期：...）",
+               "...其余28项指标...": "...", "extra": ""}]
+}
+
+列固定为：组别、业务线、本期/上期、项目名称、广告账号、
+预算策略标签、预算策略内容、预算策略learning、广告产品策略标签、广告产品策略内容、广告产品策略learning、
+受众策略标签、受众策略内容、受众策略learning、素材策略内容、素材策略learning。
+
+一个业务线一行；本期/上期与多个项目名称都放在同一单元格内用换行分隔。
+数据行统一套用 wrapText 样式，单元格内换行会正常展示。
+固定策略与明细先组成双表草稿，另导出明细-only 工作簿供 AI 阅读；
+取得 AI 文字后追加横向八列的 AI策略 表，三类标签直接复制主表值。
+"""
+import argparse
+import json
+import os
+import sys
+import zipfile
+import math
+import unicodedata
+import uuid
+import re
+from pathlib import Path
+from xml.etree import ElementTree as ET
+from datetime import datetime
+from xml.sax.saxutils import escape as xml_escape
+from cli_json import REPORT_METRICS
+
+COLUMNS = [
+    ("group", "组别"),
+    ("bizLine", "业务线"),
+    ("period", "本期/上期"),
+    ("project", "项目名称"),
+    ("adAccounts", "广告账号"),
+    ("budgetTags", "预算策略标签"),
+    ("budgetStrategy", "预算策略内容"),
+    ("budgetLearning", "预算策略learning"),
+    ("productTags", "广告产品策略标签"),
+    ("productStrategy", "广告产品策略内容"),
+    ("productLearning", "广告产品策略learning"),
+    ("audienceTags", "受众策略标签"),
+    ("audienceStrategy", "受众策略内容"),
+    ("audienceLearning", "受众策略learning"),
+    ("creativeStrategy", "素材策略内容"),
+    ("creativeLearning", "素材策略learning"),
+]
+
+# 策略内容列文字量最大，给最宽的列宽（前 5 列是基础信息列）
+DETAIL_COLUMNS = [
+    ("kind", "明细数据"),
+    ("action", "动作"),
+    ("channel", "渠道"),
+    ("id", "id"),
+    ("name", "名称"),
+    *((code, label) for code, label, _is_percent in REPORT_METRICS),
+    ("extra", "补充"),
+]
+
+CONTENT_KEYS = {key for key, _label in COLUMNS[5:]}
+
+# 列宽：策略内容列最宽；项目名称列因单元格内多行罗列项目而适度加宽
+COL_WIDTH_DEFAULT = 14
+COL_WIDTH_CONTENT = 48
+COL_WIDTH_MULTILINE = 22
+MULTILINE_KEYS = {"period", "project", "adAccounts"}
+
+# XML 1.0 与 Excel sharedStrings 不接受这些控制码及孤立代理项；保留制表、换行和回车。
+_INVALID_XML_TEXT = re.compile(r'[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f\ud800-\udfff\ufffe\uffff]')
+
+
+def _sanitize_xml_text(value: str) -> str:
+    """仅剔除无法写入 XML 的字符，不改变正常广告名称与换行。"""
+    return _INVALID_XML_TEXT.sub('', value)
+
+CONTENT_TYPES_XML = """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+<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>"""
+
+ROOT_RELS_XML = """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>
+</Relationships>"""
+
+WORKBOOK_RELS_XML = """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+<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"/>
+<sheet name="明细" sheetId="2" r:id="rId4"/>
+</sheets>
+</workbook>"""
+
+# cellXfs: 0=默认, 1=表头(粗体+浅底), 2=内容(自动换行+顶对齐)
+STYLES_XML = """<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<styleSheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
+<fonts count="2">
+<font><sz val="10"/><name val="Microsoft YaHei"/></font>
+<font><b/><sz val="10"/><color rgb="FFFFFFFF"/><name val="Microsoft YaHei"/></font>
+</fonts>
+<fills count="3">
+<fill><patternFill patternType="none"/></fill>
+<fill><patternFill patternType="none"/></fill>
+<fill><patternFill patternType="solid"><fgColor rgb="FF4472C4"/><bgColor indexed="64"/></patternFill></fill>
+</fills>
+<borders count="1"><border><left/><right/><top/><bottom/><diagonal/></border></borders>
+<cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>
+<cellXfs count="3">
+<xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0"/>
+<xf numFmtId="0" fontId="1" fillId="2" borderId="0" xfId="0" applyFont="1" applyFill="1">
+<alignment horizontal="center" vertical="center"/>
+</xf>
+<xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0" applyAlignment="1">
+<alignment vertical="top" wrapText="1"/>
+</xf>
+</cellXfs>
+</styleSheet>"""
+
+
+def col_letter(index: int) -> str:
+    """0-based 列号转 Excel 列字母（A, B, ..., Z, AA, ...）"""
+    letters = ""
+    n = index + 1
+    while n > 0:
+        n, rem = divmod(n - 1, 26)
+        letters = chr(65 + rem) + letters
+    return letters
+
+
+def _intern_factory():
+    seen = {}
+    order = []
+
+    def intern(value, rich=False):
+        # 同文字的策略富文本与普通单元格分别去重，避免格式串到明细或learning。
+        key = (value, rich)
+        if key not in seen:
+            seen[key] = len(order)
+            order.append(key)
+        return seen[key]
+
+    return intern, order
+
+
+def build_shared_strings(rows, details=None, *, include_strategy=True, ai_cells=None):
+    """按输出范围收集字符串；AI 输入文件只包含明细文字。"""
+    intern, order = _intern_factory()
+    header_indices = [intern(label) for _key, label in COLUMNS] if include_strategy else []
+    row_indices = ([
+        [intern(str(row.get(key, "") or ""), key.endswith('Strategy') or key == 'adAccounts') for key, _label in COLUMNS] for row in rows
+    ] if include_strategy else [])
+    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]
+        )
+
+    # AI 表复用共享字符串池并追加到末尾，前两张表的字符串索引保持不变。
+    ai_header = [intern(label) for label in AI_COLUMNS] if ai_cells is not None else []
+    ai_values = [intern(plain, tuple(parts) if any(bold for _text, bold in parts) else False)
+                 for plain, parts in ai_cells] if ai_cells is not None else []
+
+    def string_xml(text, rich):
+        """共享字符串统一保留换行与加粗，避免 AI 表使用预览器不兼容的 inlineStr。"""
+        escape_text = lambda value: xml_escape(value, {chr(13): '&#13;'})
+        if not rich:
+            return f'<si><t xml:space="preserve">{escape_text(text)}</t></si>'
+        if isinstance(rich, tuple):
+            # AI 的 Markdown 已被拆为文字及样式，不重新解释投放内容。
+            parts = rich
+        else:
+            pattern = r'(【[^\n】]+】|\[[^\n\]]+\]|(?m:^)(?:Meta|Google|TikTok)(?=：))'
+            parts, start = [], 0
+            for match in re.finditer(pattern, text):
+                parts.extend((part, bold) for part, bold in
+                             ((text[start:match.start()], False), (match.group(), True)) if part)
+                start = match.end()
+            if text[start:] or not parts:
+                parts.append((text[start:], False))
+        runs = ''.join(f'<r>{"<rPr><b/></rPr>" if bold else ""}'
+                       f'<t xml:space="preserve">{escape_text(part)}</t></r>' for part, bold in parts)
+        return '<si>' + runs + '</si>'
+    items = ''.join(string_xml(text, rich) for text, rich in order)
+    count = len(header_indices) + sum(map(len, row_indices)) + len(detail_header) + sum(map(len, detail_rows)) + len(ai_header) + len(ai_values)
+    sst_xml = (
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+        f'<sst xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" '
+        f'count="{count}" uniqueCount="{len(order)}">{items}</sst>'
+    )
+    return sst_xml, header_indices, row_indices, detail_header, detail_rows, (ai_header, ai_values)
+
+
+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 = []
+    widths = {}
+    for i, (key, _label) in enumerate(columns):
+        if key in content_keys:
+            width = COL_WIDTH_CONTENT
+        elif key in multiline_keys:
+            width = COL_WIDTH_MULTILINE
+        else:
+            width = COL_WIDTH_DEFAULT
+        # 尽量扩列减少换行；达到Excel行高上限仍保留单元格全文，不拆业务线行。
+        if key.endswith('Strategy'):
+            while width < 255 and any(visual_lines(str(record.get(key) or ''), width) > 26 for record in (values or [])):
+                width = min(255, width + 4)
+        widths[key] = width
+        cols_xml_parts.append(
+            f'<col min="{i + 1}" max="{i + 1}" width="{width}" customWidth="1"/>'
+        )
+    cols_xml = f"<cols>{''.join(cols_xml_parts)}</cols>"
+
+    def row_xml(row_num, indices, style_id):
+        cells = []
+        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>')
+        # 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 ""), widths[key]) 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):
+        rows_xml_parts.append(row_xml(offset + 2, indices, 2))
+
+    sheet_data = f"<sheetData>{''.join(rows_xml_parts)}</sheetData>"
+
+    return (
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+        '<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">'
+        f'<dimension ref="{dimension_ref}"/>'
+        '<sheetViews><sheetView workbookViewId="0">'
+        '<pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/>'
+        '</sheetView></sheetViews>'
+        f'{cols_xml}{sheet_data}<autoFilter ref="{dimension_ref}"/>'
+        '</worksheet>'
+    )
+
+
+def default_output_path() -> str:
+    """未指定输出路径时，默认写到用户桌面"""
+    home = os.path.expanduser("~")
+    desktop = os.path.join(home, "Desktop")
+    if not os.path.isdir(desktop):
+        # 部分中文 Windows / OneDrive 环境桌面路径不同，找不到就退回主目录
+        desktop = home
+    stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    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 prepare_layout(rows, details):
+    """每条业务线与维度明细均保持原行，动作列只记录业务动作。"""
+    # 写入与回读校验都走相同清洗，避免源数据中的非法控制字符使 sharedStrings.xml 无法解析。
+    def clean(record):
+        return {key: _sanitize_xml_text(value) if isinstance(value, str) else value
+                for key, value in record.items()}
+
+    rows = [clean(r) for r in rows]
+    details = [clean(r) for r in details or []]
+    # 单元格全文保留；超过 Excel 字符上限时在写入前明确报错，避免隐式截断。
+    return rows, details
+
+
+AI_STRATEGY_HEADINGS = ('预算策略', '广告产品策略', '受众策略', '创意策略')
+AI_COLUMNS = ('一页速览', '预算策略标签', '预算策略', '广告产品策略标签',
+              '广告产品策略', '受众策略标签', '受众策略', '创意策略')
+AI_SECTION_PATTERN = re.compile(r'(?m)^[ \t]*【(预算策略|广告产品策略|受众策略|创意策略)】[ \t]*$')
+
+
+def prepare_ai_sections(text):
+    """只按顶层标题机械分段与排版，不分析 AI 文案的投放结论。"""
+    if not isinstance(text, str) or not text.strip():
+        raise ValueError('AI 策略正文为空')
+    normalized = _sanitize_xml_text(text.replace('\r\n', '\n').replace('\r', '\n'))
+    matches = list(AI_SECTION_PATTERN.finditer(normalized))
+    if [match.group(1) for match in matches] != list(AI_STRATEGY_HEADINGS):
+        raise ValueError('AI 策略必须按预算、广告产品、受众、创意顺序各包含一个独立标题')
+    # 顶层标题用于确定 Excel 列；正文及其内部换行完整保留在同一格。
+    sections = [normalized[:matches[0].start()].strip()]
+    sections.extend(normalized[match.end():matches[index + 1].start() if index + 1 < len(matches)
+                               else len(normalized)].strip()
+                    for index, match in enumerate(matches))
+    if any(not section for section in sections):
+        raise ValueError('AI 策略速览或策略段为空')
+    prepared = []
+    for section in sections:
+        parts, cursor = [], 0
+        for match in re.finditer(r'\*\*(.+?)\*\*', section, re.DOTALL):
+            if match.start() > cursor:
+                parts.append((section[cursor:match.start()], False))
+            parts.append((match.group(1), True))
+            cursor = match.end()
+        if cursor < len(section) or not parts:
+            parts.append((section[cursor:], False))
+        plain = ''.join(value for value, _bold in parts)
+        if len(plain.encode('utf-16-le')) // 2 > 32767:
+            raise ValueError('AI 策略单列超过 Excel 单元格 32767 字符上限')
+        prepared.append((plain, parts))
+    return prepared
+
+
+def ai_cell_values(ai_sections, strategy_row):
+    """把主表三类标签原值插入对应 AI 正文左侧，不由 AI 重新选标签。"""
+    def tag_cell(key):
+        value = str(strategy_row.get(key) or '')
+        return value, [(value, False)]
+
+    return [ai_sections[0], tag_cell('budgetTags'), ai_sections[1],
+            tag_cell('productTags'), ai_sections[2], tag_cell('audienceTags'),
+            ai_sections[3], ai_sections[4]]
+
+
+def build_ai_sheet_xml(ai_sections, strategy_row, ai_indices):
+    """一行业务线横向放速览、三类标签及四段正文，并保留原生加粗。"""
+    cells = ai_cell_values(ai_sections, strategy_row)
+    headers, values = [], []
+    for number, (header_index, value_index) in enumerate(zip(*ai_indices)):
+        letter = col_letter(number)
+        headers.append(f'<c r="{letter}1" s="1" t="s"><v>{header_index}</v></c>')
+        values.append(f'<c r="{letter}2" s="2" t="s"><v>{value_index}</v></c>')
+    height = min(409, max(36, *(visual_lines(plain, 75) * 15 + 8 for plain, _ in cells)))
+    return ('<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+            '<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">'
+            '<dimension ref="A1:H2"/>'
+            '<sheetViews><sheetView workbookViewId="0"><pane ySplit="1" topLeftCell="A2" '
+            'activePane="bottomLeft" state="frozen"/></sheetView></sheetViews>'
+            '<cols><col min="1" max="1" width="55" customWidth="1"/>'
+            '<col min="2" max="2" width="22" customWidth="1"/>'
+            '<col min="3" max="3" width="78" customWidth="1"/>'
+            '<col min="4" max="4" width="22" customWidth="1"/>'
+            '<col min="5" max="5" width="78" customWidth="1"/>'
+            '<col min="6" max="6" width="22" customWidth="1"/>'
+            '<col min="7" max="8" width="78" customWidth="1"/></cols>'
+            f'<sheetData><row r="1" ht="30" customHeight="1">{"".join(headers)}</row>'
+            f'<row r="2" ht="{height}" customHeight="1">{"".join(values)}</row></sheetData>'
+            '<autoFilter ref="A1:H2"/></worksheet>')
+
+
+def write_xlsx(rows, output_path: str, details=None, *, ai_strategy=None) -> str:
+    if not rows:
+        raise ValueError('策略数据为空')
+    rows, details = prepare_layout(rows, details)
+    ai_sections = prepare_ai_sections(ai_strategy) if ai_strategy is not None else None
+    if ai_sections is not None and len(rows) != 1:
+        raise ValueError('AI 策略 sheet 必须对应唯一业务线')
+    # 保持单元格全文；超过Excel实际字符限制时明确失败，不拆行或静默丢字。
+    for row, columns in [(r, COLUMNS) for r in rows] + [(r, DETAIL_COLUMNS) for r in details]:
+        for key, _ in columns:
+            if len(str(row.get(key) or '').encode('utf-16-le')) // 2 > 32767:
+                raise ValueError(f'{key} 超过Excel单元格32767字符上限，请精简内容；不会拆分原始记录行')
+    sst_xml, header_indices, row_indices, detail_header, detail_rows, ai_indices = build_shared_strings(
+        rows, details, ai_cells=ai_cell_values(ai_sections, rows[0]) if ai_sections is not None else None
+    )
+    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={'id', *(code for code, _label, _is_percent in REPORT_METRICS)},
+        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, "x", zipfile.ZIP_DEFLATED) as zf:
+        # 第三张表只在最终工作簿追加；草稿仍维持原两张表结构。
+        content_types = CONTENT_TYPES_XML
+        workbook_rels = WORKBOOK_RELS_XML
+        workbook_xml = WORKBOOK_XML
+        if ai_sections is not None:
+            content_types = content_types.replace('</Types>',
+                '<Override PartName="/xl/worksheets/sheet3.xml" '
+                'ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/></Types>')
+            workbook_rels = workbook_rels.replace('</Relationships>',
+                '<Relationship Id="rId5" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" '
+                'Target="worksheets/sheet3.xml"/></Relationships>')
+            workbook_xml = workbook_xml.replace('</sheets>',
+                '<sheet name="AI策略" sheetId="3" r:id="rId5"/></sheets>')
+        zf.writestr("[Content_Types].xml", content_types)
+        zf.writestr("_rels/.rels", ROOT_RELS_XML)
+        zf.writestr("xl/workbook.xml", workbook_xml)
+        zf.writestr("xl/_rels/workbook.xml.rels", workbook_rels)
+        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)
+        if ai_sections is not None:
+            zf.writestr("xl/worksheets/sheet3.xml", build_ai_sheet_xml(ai_sections, rows[0], ai_indices))
+
+    return output_path
+
+
+def write_detail_workbook(details, output_path):
+    """给 AI 单独导出只有明细 sheet 的工作簿，不暴露固定策略正文。"""
+    _rows, clean_details = prepare_layout([], details)
+    for row in clean_details:
+        for key, _label in DETAIL_COLUMNS:
+            if len(str(row.get(key) or '').encode('utf-16-le')) // 2 > 32767:
+                raise ValueError(f'明细 {key} 超过 Excel 单元格上限')
+    strings, _head, _rows, detail_head, detail_rows, _ai = build_shared_strings(
+        [], clean_details, include_strategy=False)
+    sheet = build_sheet_xml(detail_head, detail_rows, DETAIL_COLUMNS,
+                            content_keys={'name', 'extra'},
+                            multiline_keys={'id', *(code for code, _label, _is_percent in REPORT_METRICS)},
+                            values=clean_details)
+    # 从现有标准库工作簿结构裁剪成单 sheet 包，不保留策略表的共享字符串。
+    content_types = re.sub(r'<Override PartName="/xl/worksheets/sheet2.xml"[^>]*/>\n?', '', CONTENT_TYPES_XML)
+    relationships = re.sub(r'<Relationship Id="rId4"[^>]*/>\n?', '', WORKBOOK_RELS_XML)
+    workbook = (WORKBOOK_XML.replace('<sheet name="策略" sheetId="1" r:id="rId1"/>', '')
+                .replace('<sheet name="明细" sheetId="2" r:id="rId4"/>',
+                         '<sheet name="明细" sheetId="1" r:id="rId1"/>'))
+    out_dir = os.path.dirname(output_path)
+    if out_dir:
+        os.makedirs(out_dir, exist_ok=True)
+    with zipfile.ZipFile(output_path, 'x', zipfile.ZIP_DEFLATED) as archive:
+        for name, value in (('[Content_Types].xml', content_types), ('_rels/.rels', ROOT_RELS_XML),
+                            ('xl/workbook.xml', workbook), ('xl/_rels/workbook.xml.rels', relationships),
+                            ('xl/styles.xml', STYLES_XML), ('xl/sharedStrings.xml', strings),
+                            ('xl/worksheets/sheet1.xml', sheet)):
+            archive.writestr(name, value)
+    return output_path
+
+
+def validate_detail_workbook(path, details):
+    """回读 AI 输入，确认唯一 sheet 与本条明细逐格一致。"""
+    ns = {'s': 'http://schemas.openxmlformats.org/spreadsheetml/2006/main'}
+    _rows, clean_details = prepare_layout([], details)
+    with zipfile.ZipFile(path) as archive:
+        if archive.testzip():
+            raise ValueError('AI 明细工作簿 ZIP 校验失败')
+        workbook = ET.fromstring(archive.read('xl/workbook.xml'))
+        if [item.attrib['name'] for item in workbook.findall('s:sheets/s:sheet', ns)] != ['明细']:
+            raise ValueError('AI 输入工作簿只能包含明细 sheet')
+        strings = [''.join(item.itertext()) for item in ET.fromstring(archive.read('xl/sharedStrings.xml'))]
+        sheet = ET.fromstring(archive.read('xl/worksheets/sheet1.xml'))
+        actual = [[strings[int(cell.find('s:v', ns).text)] for cell in row]
+                  for row in sheet.findall('s:sheetData/s:row', ns)]
+        expected = [[label for _key, label in DETAIL_COLUMNS]] + [
+            [str(row.get(key) or '') for key, _label in DETAIL_COLUMNS] for row in clean_details]
+        if actual != expected:
+            raise ValueError('AI 输入明细 sheet 内容不完整')
+    return {'details': len(clean_details)}
+
+
+def _read_ai_sheet(archive):
+    """回读本导出器的唯一 AI 数据行，核对表名、关联路径、坐标与八列表头。"""
+    ns = {'s': 'http://schemas.openxmlformats.org/spreadsheetml/2006/main'}
+    workbook = ET.fromstring(archive.read('xl/workbook.xml'))
+    sheets = workbook.findall('s:sheets/s:sheet', ns)
+    if [sheet.get('name') for sheet in sheets] != ['策略', '明细', 'AI策略']:
+        raise ValueError('AI 策略工作簿 sheet 名称或顺序不完整')
+    relation_id = sheets[-1].get('{http://schemas.openxmlformats.org/officeDocument/2006/relationships}id')
+    relations = ET.fromstring(archive.read('xl/_rels/workbook.xml.rels'))
+    targets = [item.get('Target') for item in relations if item.get('Id') == relation_id
+               and item.get('Type', '').endswith('/worksheet') and item.get('TargetMode') != 'External']
+    if targets != ['worksheets/sheet3.xml']:
+        raise ValueError('AI 策略 sheet 关联路径无效')
+    sheet = ET.fromstring(archive.read('xl/' + targets[0]))
+    rows = sheet.findall('s:sheetData/s:row', ns)
+    if len(rows) != 2 or [row.get('r') for row in rows] != ['1', '2']:
+        raise ValueError('AI 策略 sheet 必须有唯一业务线数据行')
+    strings = [''.join(node.text or '' for node in item.findall('.//s:t', ns))
+               for item in ET.fromstring(archive.read('xl/sharedStrings.xml'))]
+    actual = []
+    for index, row in enumerate(rows, 1):
+        cells = row.findall('s:c', ns)
+        if [cell.get('r') for cell in cells] != [f'{col_letter(i)}{index}' for i in range(len(AI_COLUMNS))]:
+            raise ValueError('AI 策略 sheet 八列坐标不完整')
+        values = []
+        for cell in cells:
+            reference = cell.find('s:v', ns)
+            if cell.get('t') != 's' or cell.find('s:f', ns) is not None or reference is None \
+                    or not re.fullmatch(r'[0-9]+', reference.text or ''):
+                raise ValueError('AI 策略 sheet 必须引用共享字符串')
+            ident = int(reference.text)
+            if ident >= len(strings):
+                raise ValueError('AI 策略 sheet 共享字符串索引越界')
+            values.append(strings[ident])
+        actual.append(values)
+    if actual[0] != list(AI_COLUMNS):
+        raise ValueError('AI 策略 sheet 八列表头不完整')
+    return dict(zip(AI_COLUMNS, actual[1]))
+
+
+def read_ai_sheet(path):
+    """上传前读取最终 Excel 的可见文字，不从生成前 payload 替代入库来源。"""
+    with zipfile.ZipFile(path) as archive:
+        if archive.testzip():
+            raise ValueError('Excel ZIP 校验失败')
+        return _read_ai_sheet(archive)
+
+
+def validate_xlsx(path, rows, details, *, ai_strategy=None):
+    """逐单元格回读，与布局后的完整输入比较，避免只检验文件存在。"""
+    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'))
+        names = ['策略', '明细'] + (['AI策略'] if ai_strategy is not None else [])
+        if [s.attrib['name'] for s in workbook.findall('s:sheets/s:sheet', ns)] != names:
+            raise ValueError('Excel sheet 名称或顺序不完整')
+        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} 张表内容或行列数不完整')
+        if ai_strategy is not None:
+            if len(expected[0]) != 1:
+                raise ValueError('AI 策略 sheet 必须对应唯一业务线')
+            ai_sections = prepare_ai_sections(ai_strategy)
+            actual = _read_ai_sheet(archive)
+            cells = ai_cell_values(ai_sections, expected[0][0])
+            if actual != dict(zip(AI_COLUMNS, [plain for plain, _parts in cells])):
+                raise ValueError('AI 策略 sheet 横向八列内容、标签或行数不完整')
+    result = {'rows': len(expected[0]), 'details': len(expected[1])}
+    if ai_strategy is not None:
+        result['ai_columns'] = len(AI_COLUMNS)
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--input", required=True, help="payload JSON 文件路径，传 - 表示从 stdin 读取"
+    )
+    parser.add_argument(
+        "--output",
+        default=None,
+        help="输出 .xlsx 路径；未传时用 payload.output_path，仍未传则默认桌面",
+    )
+    args = parser.parse_args()
+
+    if args.input == "-":
+        raw = sys.stdin.read()
+    else:
+        with open(args.input, "r", encoding="utf-8") as f:
+            raw = f.read()
+
+    payload = json.loads(raw)
+    rows = payload.get("rows", [])
+    if not isinstance(rows, list) or len(rows) == 0:
+        print(json.dumps({"ok": False, "error": "payload.rows 为空或不是数组"}, ensure_ascii=False))
+        return 1
+
+    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, details=details)
+
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "output_path": output_path,
+                "row_count": len(rows),
+                "detail_count": len(details),
+            },
+            ensure_ascii=False,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())