@shulex/cxclawctl 0.0.0-stage → 0.1.2

package/skills/delivery/scripts/gen_delivery_report.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+"""Delivery 批测报告生成器：读 batch_test.py 输出的 results JSON，渲染 HTML+MD。
+
+输入 results JSON schema（与 batch_test.py 输出一致）：
+  {
+    "summary": {total_conversations, total_messages, total_replied, reply_rate,
+                agents:[...], handoff:[...], errors:[...], no_reply_reasons:[...]},
+    "details": [{source_chat_id, new_chat_id, intent, action, round,
+                 question, answer, no_reply_reason, judge, correct}, ...]
+  }
+
+输出：
+  - HTML：交互式（KPI / agent / handoff / error / 详情 / Judge / CSV 下载）
+  - MD  ：纯文本表格
+
+用法：
+  python3 gen_delivery_report.py --results results.json
+  python3 gen_delivery_report.py --results results.json --html out.html --md out.md
+  python3 gen_delivery_report.py --results results.json --no-md
+"""
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.environ.get("SOLVEA_LIB_DIR", os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "__lib__"))), "skill-runtime"))
+from bootstrap import *  # noqa: F401,F403
+
+
+def _pct(v):
+    """Format float 0-1 as percentage string, or '-' if None."""
+    if v is None:
+        return '-'
+    return f"{v * 100:.1f}%"
+
+
+def generate_html_report(summary: dict, details: list, output_path: str):
+    """Generate a self-contained HTML report and write to output_path."""
+    agents_rows = ""
+    for a in summary.get('agents', []):
+        agents_rows += f"""
+        <tr>
+          <td>{a.get('name','')}</td>
+          <td>{a.get('total_conversations',0)}</td>
+          <td>{a.get('total_messages',0)}</td>
+          <td>{_pct(a.get('reply_rate'))}</td>
+          <td>{_pct(a.get('r1_reply_rate'))}</td>
+          <td>{_pct(a.get('r2_reply_rate'))}</td>
+          <td>{_pct(a.get('r3_reply_rate'))}</td>
+          <td>{_pct(a.get('rs_reply_rate'))}</td>
+        </tr>"""
+
+    handoff_rows = "".join(
+        f"<tr><td>{h['type']}</td><td>{h['count']}</td><td>{_pct(h.get('rate'))}</td></tr>"
+        for h in summary.get('handoff', [])
+    ) or "<tr><td colspan='3' style='color:#999'>无</td></tr>"
+
+    error_rows = "".join(
+        f"<tr><td>{e['type']}</td><td>{e['count']}</td><td>{_pct(e.get('rate'))}</td></tr>"
+        for e in summary.get('errors', [])
+    ) or "<tr><td colspan='3' style='color:#999'>无</td></tr>"
+
+    detail_rows = ""
+    for d in details:
+        src = d.get('source_chat_id', '')
+        new = d.get('new_chat_id', '')
+        chat_display = f"{new}<br><small style='color:#999'>{src}</small>" if src else new
+        answer_raw = d.get('answer', '')
+        if isinstance(answer_raw, dict):
+            answer_raw = answer_raw.get('content', str(answer_raw))
+        answer = str(answer_raw).replace('<', '&lt;').replace('>', '&gt;')
+        question_raw = d.get('question', '')
+        if isinstance(question_raw, dict):
+            question_raw = question_raw.get('content', str(question_raw))
+        question = str(question_raw).replace('<', '&lt;').replace('>', '&gt;')
+        ng_cls = ' active' if d.get('judge', '') in ('✗', 'ng', 'fail', 'FAIL', '0') else ''
+        correct_esc = d.get('correct', '').replace('<', '&lt;').replace('>', '&gt;').replace('"', '&quot;')
+        detail_rows += f"""
+        <tr>
+          <td class='col-chatid'><div class='cc'>{chat_display}</div></td>
+          <td class='col-round' style='text-align:center'>{d.get('round','')}</td>
+          <td class='col-intent'><div class='cc'>{d.get('intent','')}</div></td>
+          <td class='col-agent'><div class='cc'>{d.get('action','')}</div></td>
+          <td class='col-q'><div class='cc'>{question}</div></td>
+          <td class='col-a'><div class='cc'>{answer}</div></td>
+          <td class='col-judge'><div class='jcell'><button type='button' class='jbtn ng{ng_cls}' onclick='toggleJudge(this)'>&#10007;</button></div></td>
+          <td class='col-correct'><textarea class='rinp' rows='3' placeholder='填写正确回答...'>{correct_esc}</textarea></td>
+        </tr>"""
+
+    reply_rate_pct = _pct(summary.get('reply_rate'))
+    html = rf"""<!DOCTYPE html>
+<html lang="zh">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>批测报告</title>
+<style>
+  *{{box-sizing:border-box;margin:0;padding:0}}
+  body{{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;
+        background:#f5f6fa;color:#2d3436;font-size:14px;padding:24px}}
+  h1{{font-size:20px;font-weight:700;margin-bottom:20px;color:#1a1a2e}}
+  h2{{font-size:15px;font-weight:600;margin:28px 0 12px;color:#444}}
+  .kpi-grid{{display:grid;grid-template-columns:repeat(4,1fr);gap:16px;margin-bottom:8px}}
+  .kpi{{background:#fff;border-radius:10px;padding:18px 20px;
+        box-shadow:0 1px 4px rgba(0,0,0,.08)}}
+  .kpi .label{{font-size:12px;color:#888;margin-bottom:6px}}
+  .kpi .value{{font-size:26px;font-weight:700;color:#2d3436}}
+  .kpi .value.green{{color:#00b894}}
+  table{{width:100%;border-collapse:collapse;background:#fff;border-radius:10px;
+         box-shadow:0 1px 4px rgba(0,0,0,.08);overflow:hidden}}
+  th{{background:#f0f0f5;padding:10px 14px;text-align:left;
+      font-size:12px;font-weight:600;color:#555;white-space:nowrap}}
+  td{{padding:9px 14px;border-top:1px solid #f0f0f0;vertical-align:top;line-height:1.5}}
+  tr:hover td{{background:#fafbff}}
+  .dist-grid{{display:grid;grid-template-columns:1fr 1fr;gap:16px}}
+  .detail-wrap{{overflow-x:auto;border-radius:10px;
+                box-shadow:0 1px 4px rgba(0,0,0,.08)}}
+  .detail-wrap table{{border-radius:0;table-layout:fixed;width:100%}}
+  .col-chatid{{width:155px}}.col-round{{width:44px}}.col-intent{{width:110px}}
+  .col-agent{{width:130px}}.col-q{{width:240px}}.col-a{{width:280px}}
+  .col-judge{{width:44px}}.col-correct{{width:222px}}
+  .cc{{max-height:80px;overflow:hidden;word-break:break-word;
+       white-space:pre-wrap;font-size:13px;line-height:1.45;position:relative}}
+  .cc.open{{max-height:none}}
+  .xbtn{{display:none;color:#0984e3;font-size:11px;cursor:pointer;
+          margin-top:3px;user-select:none;white-space:nowrap}}
+  .xbtn.vis{{display:inline-block}}
+  .jcell{{display:flex;gap:5px;justify-content:center;padding-top:2px}}
+  .jbtn{{-webkit-appearance:none;appearance:none;border:1px solid #ddd;
+          background:#f7f7f7;border-radius:5px;padding:4px 9px;cursor:pointer;
+          font-size:15px;color:#bbb;
+          transition:background .15s,color .15s,border-color .15s;line-height:1}}
+  .jbtn.ng.active{{background:#e17055 !important;border-color:#e17055 !important;color:#fff !important}}
+  .jbtn:hover:not(.active){{background:#eee;color:#666}}
+  .rinp{{width:100%;box-sizing:border-box;border:1px solid #e0e0e0;border-radius:5px;
+          padding:5px 7px;font-size:12px;font-family:inherit;color:#444;
+          resize:vertical;min-height:54px;line-height:1.4}}
+  .rinp:focus{{outline:none;border-color:#0984e3;box-shadow:0 0 0 2px rgba(9,132,227,.1)}}
+  .dl-btn{{background:#0984e3;color:#fff;border:none;border-radius:6px;
+            padding:6px 14px;font-size:13px;cursor:pointer;white-space:nowrap}}
+  .dl-btn:hover{{background:#076dc1}}
+  small{{font-size:11px}}
+</style>
+</head>
+<body>
+<h1>批测报告</h1>
+
+<h2>KPI 总览</h2>
+<div class="kpi-grid">
+  <div class="kpi"><div class="label">总会话数</div>
+    <div class="value">{summary.get('total_conversations',0)}</div></div>
+  <div class="kpi"><div class="label">总消息数</div>
+    <div class="value">{summary.get('total_messages',0)}</div></div>
+  <div class="kpi"><div class="label">回复消息数</div>
+    <div class="value">{summary.get('total_replied',0)}</div></div>
+  <div class="kpi"><div class="label">整体回复率</div>
+    <div class="value green">{reply_rate_pct}</div></div>
+</div>
+
+<h2>Agent Performance</h2>
+<table>
+  <thead><tr>
+    <th>Action</th><th>会话数</th><th>消息数</th><th>回复率</th>
+    <th>R1</th><th>R2</th><th>R3</th><th>Rs</th>
+  </tr></thead>
+  <tbody>{agents_rows}</tbody>
+</table>
+
+<h2>分布详情</h2>
+<div class="dist-grid">
+  <div>
+    <h2 style="margin-top:0">Handoff 分布</h2>
+    <table>
+      <thead><tr><th>类型</th><th>数量</th><th>占比</th></tr></thead>
+      <tbody>{handoff_rows}</tbody>
+    </table>
+  </div>
+  <div>
+    <h2 style="margin-top:0">Error 分布</h2>
+    <table>
+      <thead><tr><th>类型</th><th>数量</th><th>占比</th></tr></thead>
+      <tbody>{error_rows}</tbody>
+    </table>
+  </div>
+</div>
+
+<div style='display:flex;align-items:center;justify-content:space-between;margin:28px 0 12px'><h2 style='margin:0'>回复详情</h2><button class='dl-btn' onclick='downloadCSV()'>&#11015; 下载 CSV</button></div>
+<div class="detail-wrap">
+<table>
+  <thead><tr>
+    <th class='col-chatid'>Chat ID</th><th class='col-round'>Round</th>
+    <th class='col-intent'>意图</th><th class='col-agent'>Action</th>
+    <th class='col-q'>Question</th><th class='col-a'>Answer</th>
+    <th class='col-judge'>Judge</th><th class='col-correct'>Correct</th>
+  </tr></thead>
+  <tbody>{detail_rows}</tbody>
+</table>
+</div>
+
+<script>
+document.querySelectorAll('.cc').forEach(function(el){{
+  if(el.scrollHeight > el.clientHeight + 4){{
+    var b = document.createElement('span');
+    b.className = 'xbtn vis';
+    b.textContent = '展开';
+    b.onclick = function(){{
+      var open = el.classList.toggle('open');
+      b.textContent = open ? '收起' : '展开';
+    }};
+    el.parentNode.appendChild(b);
+  }}
+}});
+function toggleJudge(btn){{ btn.classList.toggle('active'); }}
+function downloadCSV(){{
+  var hdr = ['new_chat_id','source_chat_id','round','intent','action','question','answer','judge','correct'];
+  var rows = [hdr];
+  document.querySelectorAll('.detail-wrap tbody tr').forEach(function(tr){{
+    var td = tr.querySelectorAll('td');
+    function txt(el){{ return el ? (el.innerText||el.textContent||'').replace(/\s+/g,' ').trim() : ''; }}
+    var chatRaw = txt(td[0].querySelector('.cc'));
+    var parts = chatRaw.split('\\n');
+    var newId = parts[0]||''; var srcId = parts[1]||'';
+    var round  = txt(td[1]);
+    var intent = txt(td[2].querySelector('.cc'));
+    var action = txt(td[3].querySelector('.cc'));
+    var question = txt(td[4].querySelector('.cc'));
+    var answer   = txt(td[5].querySelector('.cc'));
+    var ab = td[6].querySelector('.jbtn.active');
+    var judge = ab ? '✗' : '';
+    var correct = td[7].querySelector('.rinp') ? td[7].querySelector('.rinp').value : '';
+    rows.push([newId,srcId,round,intent,action,question,answer,judge,correct]);
+  }});
+  var csv = rows.map(function(r){{
+    return r.map(function(v){{
+      return '"' + (v||'').replace(/\\r?\\n/g,' ').replace(/"/g,'""') + '"';
+    }}).join(',');
+  }}).join('\\r\\n');
+  var blob = new Blob([''+csv],{{type:'text/csv;charset=utf-8'}});
+  var url = URL.createObjectURL(blob);
+  var a = document.createElement('a');
+  a.href=url; a.download='batch_test_result.csv';
+  document.body.appendChild(a); a.click();
+  document.body.removeChild(a); URL.revokeObjectURL(url);
+}}
+</script>
+</body></html>"""
+
+    with open(output_path, 'w', encoding='utf-8') as f:
+        f.write(html)
+
+
+def generate_md_report(summary: dict, details: list, output_path: str):
+    """Generate a Markdown report and write to output_path."""
+    lines = ["# 批测报告\n"]
+
+    lines.append("## KPI 总览\n")
+    lines.append("| 总会话 | 总消息数 | 回复消息数 | 回复率 |")
+    lines.append("|--------|---------|-----------|--------|")
+    lines.append(f"| {summary.get('total_conversations',0)} "
+                 f"| {summary.get('total_messages',0)} "
+                 f"| {summary.get('total_replied',0)} "
+                 f"| {_pct(summary.get('reply_rate'))} |\n")
+
+    lines.append("## Agent Performance\n")
+    lines.append("| Action | 会话数 | 消息数 | 回复率 | R1 | R2 | R3 | Rs |")
+    lines.append("|--------|--------|--------|--------|----|----|----|----|")
+    for a in summary.get('agents', []):
+        lines.append(f"| {a.get('name','')} | {a.get('total_conversations',0)} "
+                     f"| {a.get('total_messages',0)} | {_pct(a.get('reply_rate'))} "
+                     f"| {_pct(a.get('r1_reply_rate'))} | {_pct(a.get('r2_reply_rate'))} "
+                     f"| {_pct(a.get('r3_reply_rate'))} | {_pct(a.get('rs_reply_rate'))} |")
+    lines.append("")
+
+    lines.append("## Handoff 分布\n")
+    for h in summary.get('handoff', []):
+        lines.append(f"- {h['type']}: {h['count']} 条 ({_pct(h.get('rate'))})")
+    lines.append("")
+
+    lines.append("## Error 分布\n")
+    for e in summary.get('errors', []):
+        lines.append(f"- {e['type']}: {e['count']} 条 ({_pct(e.get('rate'))})")
+    lines.append("")
+
+    lines.append("## 回复详情\n")
+    lines.append("| Chat ID | Round | 意图 | Action | Question | Answer | Judge | Correct |")
+    lines.append("|---------|-------|------|-------|----------|--------|-------|--------|")
+    for d in details:
+        q = d.get('question', '').replace('|', '｜')
+        a = d.get('answer', '').replace('|', '｜').replace('\n', ' ')
+        lines.append(f"| {d.get('new_chat_id','')} | {d.get('round','')} "
+                     f"| {d.get('intent','')} | {d.get('action','')} "
+                     f"| {q} | {a} | {d.get('judge','')} | {d.get('correct','')} |")
+
+    with open(output_path, 'w', encoding='utf-8') as f:
+        f.write('\n'.join(lines) + '\n')
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Delivery 批测报告生成器")
+    parser.add_argument("--results", required=True,
+                        help="batch_test.py 输出的 results JSON 路径")
+    parser.add_argument("--html", default=None,
+                        help="HTML 输出路径，默认 <results基名>.html")
+    parser.add_argument("--md", default=None,
+                        help="MD 输出路径，默认 <results基名>.md")
+    parser.add_argument("--no-html", action="store_true", help="跳过 HTML 渲染")
+    parser.add_argument("--no-md", action="store_true", help="跳过 MD 渲染")
+    args = parser.parse_args()
+
+    if not os.path.exists(args.results):
+        print(f"results file not found: {args.results}", file=sys.stderr)
+        sys.exit(1)
+
+    with open(args.results, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    summary = data.get("summary", {})
+    details = data.get("details", [])
+
+    base = os.path.splitext(os.path.abspath(args.results))[0]
+    html_path = args.html or (base + ".html")
+    md_path = args.md or (base + ".md")
+
+    if not args.no_html:
+        os.makedirs(os.path.dirname(os.path.abspath(html_path)) or ".", exist_ok=True)
+        generate_html_report(summary, details, html_path)
+        print(f"Report rendered → {html_path}", file=sys.stderr)
+    if not args.no_md:
+        os.makedirs(os.path.dirname(os.path.abspath(md_path)) or ".", exist_ok=True)
+        generate_md_report(summary, details, md_path)
+        print(f"Report rendered → {md_path}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/skills/delivery/scripts/gen_excel.py

@@ -0,0 +1,234 @@
+"""
+Generate intent classification detail Excel from items_*.json + results_*.json.
+
+Columns: L1 Intent | L2 Intent | Case Text
+L1 and L2 cells are merged across rows of the same value.
+
+Usage:
+  python3 scripts/gen_excel.py [--brand "Acme"]
+"""
+
+import os, sys
+sys.path.insert(0, os.path.join(os.environ.get("SOLVEA_LIB_DIR", os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "__lib__"))), "skill-runtime"))
+from bootstrap import *
+
+import json, argparse
+import openpyxl
+
+
+def _read_state() -> dict:
+    _sf = STATE_DIR / "progress.json"
+    if _sf.exists():
+        try:
+            return json.loads(_sf.read_text(encoding="utf-8"))
+        except Exception:
+            pass
+    return {}
+
+
+def _write_state(data: dict) -> None:
+    _sf = STATE_DIR / "progress.json"
+    _sf.parent.mkdir(parents=True, exist_ok=True)
+    _sf.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+from openpyxl.styles import PatternFill, Font, Alignment, Border, Side
+from openpyxl.utils import get_column_letter
+
+
+COLOR_PALETTE = [
+    "FEF3C7", "DBEAFE", "D1FAE5", "FCE7F3", "EDE9FE",
+    "FEE2E2", "ECFDF5", "FFF7ED", "F0F9FF", "F7FEE7",
+]
+
+
+def thin_border():
+    s = Side(style="thin", color="D1D5DB")
+    return Border(left=s, right=s, top=s, bottom=s)
+
+
+def build_excel(items, results, brand=""):
+    wb = openpyxl.Workbook()
+    ws = wb.active
+    ws.title = "Intent Detail"
+
+    all_intents = results.get("intents", []) + results.get("new_intents", [])
+    l1_color = {}
+    for i, intent in enumerate(all_intents):
+        l1_color[intent["name"]] = COLOR_PALETTE[i % len(COLOR_PALETTE)]
+
+    l1_canonical_l2s = {}
+    for intent in all_intents:
+        l1_canonical_l2s[intent["name"]] = {
+            s["name"] for s in intent.get("sub_intents", []) if s["name"] != "Other"
+        }
+
+    def canonical_l2(l1, l2):
+        allowed = l1_canonical_l2s.get(l1, set())
+        if not allowed:
+            return l2 or "Other"
+        return l2 if l2 in allowed else "Other"
+
+    l1_order = {intent["name"]: i for i, intent in enumerate(all_intents)}
+    items_sorted = sorted(items, key=lambda x: (
+        l1_order.get(x["l1"], 999),
+        canonical_l2(x["l1"], x.get("l2") or ""),
+    ))
+
+    headers = ["L1意图", "L2意图", "分类依据(LLM)", "title", "first_message", "messages"]
+    col_widths = [22, 28, 45, 25, 55, 70]
+
+    header_fill = PatternFill("solid", fgColor="1E3A5F")
+    header_font = Font(bold=True, color="FFFFFF", size=11)
+    header_align = Alignment(horizontal="center", vertical="center", wrap_text=True)
+
+    for col, (h, w) in enumerate(zip(headers, col_widths), start=1):
+        cell = ws.cell(row=1, column=col, value=h)
+        cell.fill = header_fill
+        cell.font = header_font
+        cell.alignment = header_align
+        cell.border = thin_border()
+        ws.column_dimensions[get_column_letter(col)].width = w
+
+    ws.row_dimensions[1].height = 30
+    ws.freeze_panes = "A2"
+
+    row_num = 2
+
+    for item in items_sorted:
+        l1 = item["l1"]
+        l2 = item.get("l2") or "(unclassified)"
+        title_val = item.get("title", "")
+        first_msg_val = item.get("first_message", "") or item.get("text", "")
+        messages_val = item.get("messages", "")
+        raw_text = item.get("text", "")
+        text_val = raw_text[:1000] + f"...[截断 {len(raw_text)-1000} 字]" if len(raw_text) > 1000 else raw_text
+        color = l1_color.get(l1, "F9FAFB")
+
+        fill = PatternFill("solid", fgColor=color)
+        border = thin_border()
+
+        c1 = ws.cell(row=row_num, column=1, value=l1)
+        c1.fill = fill
+        c1.border = border
+        c1.alignment = Alignment(horizontal="center", vertical="top", wrap_text=True)
+        c1.font = Font(bold=True, size=10)
+
+        l2_display = canonical_l2(l1, l2)
+        l2_label = l2_display
+        if item.get("is_new_l2") and l2_display not in ("Other", ""):
+            l2_label = f"★ {l2_display}"
+        if item.get("is_new_l1"):
+            l2_label = f"[新] {l2_display}"
+
+        c2 = ws.cell(row=row_num, column=2, value=l2_label)
+        c2.fill = PatternFill("solid", fgColor="F8FAFC")
+        c2.border = border
+        c2.alignment = Alignment(horizontal="left", vertical="top", wrap_text=True)
+        c2.font = Font(size=10)
+
+        for col_idx, val in [(3, text_val), (4, title_val), (5, first_msg_val), (6, messages_val)]:
+            cx = ws.cell(row=row_num, column=col_idx, value=val)
+            cx.fill = PatternFill("solid", fgColor="FFFFFF")
+            cx.border = border
+            cx.alignment = Alignment(horizontal="left", vertical="top", wrap_text=True)
+            cx.font = Font(size=9)
+        ws.row_dimensions[row_num].height = max(15, min(80, len(first_msg_val) // 3))
+
+        row_num += 1
+
+    # Summary sheet
+    ws2 = wb.create_sheet("Summary")
+    ws2.column_dimensions["A"].width = 28
+    ws2.column_dimensions["B"].width = 28
+    ws2.column_dimensions["C"].width = 10
+    ws2.column_dimensions["D"].width = 10
+
+    h_fill = PatternFill("solid", fgColor="1E3A5F")
+    h_font = Font(bold=True, color="FFFFFF", size=11)
+    for col, val in enumerate(["一级意图", "二级意图", "数量", "占比 %"], start=1):
+        c = ws2.cell(row=1, column=col, value=val)
+        c.fill = h_fill
+        c.font = h_font
+        c.alignment = Alignment(horizontal="center", vertical="center")
+        c.border = thin_border()
+    ws2.row_dimensions[1].height = 28
+    ws2.freeze_panes = "A2"
+
+    sr = 2
+    for intent in all_intents:
+        l1n = intent["name"]
+        color = l1_color.get(l1n, "F9FAFB")
+        fill = PatternFill("solid", fgColor=color)
+        subs = intent.get("sub_intents", [])
+        if not subs:
+            c = ws2.cell(row=sr, column=1, value=l1n)
+            c.fill = fill; c.font = Font(bold=True, size=10); c.border = thin_border()
+            c.alignment = Alignment(horizontal="center", vertical="center", wrap_text=True)
+            ws2.cell(row=sr, column=2, value="(no sub-intents)").border = thin_border()
+            ws2.cell(row=sr, column=3, value=intent["count"]).border = thin_border()
+            ws2.cell(row=sr, column=4, value=round(intent["pct"], 1)).border = thin_border()
+            sr += 1
+        else:
+            l1_start_row = sr
+            for sub in subs:
+                c = ws2.cell(row=sr, column=1, value=l1n)
+                c.fill = fill; c.font = Font(bold=True, size=10); c.border = thin_border()
+                c.alignment = Alignment(horizontal="center", vertical="center", wrap_text=True)
+                ws2.cell(row=sr, column=2, value=sub["name"]).border = thin_border()
+                ws2.cell(row=sr, column=2).alignment = Alignment(horizontal="left", vertical="center")
+                ws2.cell(row=sr, column=3, value=sub["count"]).border = thin_border()
+                ws2.cell(row=sr, column=3).alignment = Alignment(horizontal="center")
+                ws2.cell(row=sr, column=4, value=round(sub["pct"], 1)).border = thin_border()
+                ws2.cell(row=sr, column=4).alignment = Alignment(horizontal="center")
+                sr += 1
+            if sr - 1 > l1_start_row:
+                ws2.merge_cells(start_row=l1_start_row, start_column=1,
+                                end_row=sr - 1, end_column=1)
+                ws2.cell(row=l1_start_row, column=1).alignment = Alignment(
+                    horizontal="center", vertical="center", wrap_text=True)
+
+    return wb
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--brand", default="")
+    parser.add_argument("--results", default=None,
+                        help="Override results JSON path (default: read from state)")
+    parser.add_argument("--items", default=None,
+                        help="Override items JSON path (default: read from state)")
+    args = parser.parse_args()
+
+    state = _read_state()
+    results_path = args.results or state.get("results_path")
+    items_path = args.items or state.get("items_path")
+
+    if not results_path or not os.path.exists(results_path):
+        raise FileNotFoundError(
+            f"Results file missing (state.results_path={results_path}). Run classify.py first."
+        )
+    if not items_path or not os.path.exists(items_path):
+        raise FileNotFoundError(
+            f"Items file missing (state.items_path={items_path}). "
+            "Run classify.py with --xlsx first."
+        )
+
+    with open(items_path) as f:
+        items = json.load(f)
+    with open(results_path) as f:
+        results = json.load(f)
+
+    wb = build_excel(items, results, args.brand)
+
+    OUTPUTS_DIR.mkdir(parents=True, exist_ok=True)
+    out_path = str(OUTPUTS_DIR / f"detail_{timestamp()}.xlsx")
+    wb.save(out_path)
+    print(f"[gen_excel] Excel -> {out_path} ({len(items)} rows)")
+
+    state = _read_state()
+    state["excel_path"] = out_path
+    state["updated_at"] = timestamp()
+    _write_state(state)
+
+
+if __name__ == "__main__":
+    main()