---
name: ethanyoq/report-bundle-builder
source: https://app.decimal.ai/s/ethanyoq-report-bundle-builder@1/SKILL.md
source_sha256: 1288feb68613
---

# report-bundle-builder · 报告交付物 L2 skill

## 一句话定义

把市场调研项目的 `main.html + page_*.html + flowchart_*.png` 资产组装成
"双击即可阅读 / 邮件可发 / Excel 可分析"三件套。所有图片 base64 内嵌、PDF 自动 TOC、XLSX schema 驱动。

---

## 何时调用

- 用户说"生成 standalone HTML / PDF / XLSX"
- 多页 HTML 报告完工,要做最后的交付物组装
- 邮件/即时通讯/网盘分享前的"合并 + 内嵌"
- 需要把数据导出 Excel 给同事做透视

## 何时不调用

- 还在生成 HTML 内容 → 用 `disease-market-sizing-html-template`
- 还没召回数据 → 用 7 retrieval skill 走 `disease-market-sizing-orchestration` 流水线
- 只要 Markdown 不要 HTML/PDF → 用 `article-writing` 或 `docx`

---

## 与其他 skill 的协作

```
召回层 (7 retrieval skill: pubmed-eutils / europepmc-search / clinical-trials-v2 /
        aact-bulk-trials / bioc-fulltext-fetch / pubtator-entity-search /
        medical-evidence-grading)
        ↓
内容层 (disease-market-sizing-html-template + market-sizing-mece-foundation
        + decision-tree-with-lp-embedding + evidence-appendix-sync)
        ↓ 输出: main.html, page_*.html, flowchart_*.png
交付层 (本 skill: report-bundle-builder)  ← YOU ARE HERE
        ↓ 输出: report_standalone.html, .pdf, _data.xlsx, delivery_manifest.json
分发层 (邮件 / IM / 网盘 / 打印)
```

---

## 4 个核心函数

### 1. build_standalone_html

```python
from pathlib import Path
from build_standalone_html import build_standalone_html

result = build_standalone_html(
    main_html=Path("output/report.html"),
    sub_pages=[
        ("AML", Path("output/page_AML.html")),
        ("MDS", Path("output/page_MDS.html")),
    ],
    png_dir=Path("output"),
    out_path=Path("output/report_standalone.html"),
    intra_page_anchors=["decision", "calc", "lp", "evidence"],  # 血液项目用,通用场景留 None
)
# {"ok": True, "size_mb": 9.3, "png_count": 8,
#  "missing_pngs": [], "validation": {...}}
```

**关键参数:**

- `sub_pages`: `[(slug, path), ...]` · slug 用作 anchor id(`#page-{slug}`)
- `png_dir`: PNG 资产目录(`<img src="X.png">` 相对此目录解析)
- `intra_page_anchors`: 子页内部 `href="#decision"` 等改写为 `href="#page-{slug}-decision"` 的 anchor 名列表;None/空时不改写
- `auto_validate`: 默认 True · size > MIN_BUNDLE_BYTES(1 MB)+ anchor_count == 子页数
- 缺失 PNG 不抛错,记录在 result["missing_pngs"](见 [bundle-manifest-spec.md](references/bundle-manifest-spec.md))

### 2. build_pdf

```python
from build_pdf import build_pdf

# 单遍模式(快)
result = build_pdf(
    html_path=Path("output/report_standalone.html"),
    out_path=Path("output/report.pdf"),
)

# 两遍模式(注入 TOC 页码)
result = build_pdf(
    html_path=Path("output/report.html"),
    out_path=Path("output/report.pdf"),
    toc_anchors=[
        ("#ch1", "一、执行摘要"),
        ("#ch2", "二、研究方法"),
    ],
)
# {"ok": True, "size_mb": 9.6, "pages": 32, "mode": "two-pass"}
```

**安全保证:**

- 两遍模式自动备份 html_path,Pass 2 失败时从备份恢复
- pass1 临时 PDF 用 `tempfile.mkstemp` 避免并发碰撞
- pypdf 不可用时 `pages=None`,`pages_ok=True`(不算失败)

详见 [chrome-headless-setup.md](references/chrome-headless-setup.md)。

### 3. build_xlsx

```python
from build_xlsx import build_xlsx

result = build_xlsx(
    data={
        "overview": [["总 PMID", 200, "PubMed"], ["NCT", 30, "CT.gov"]],
        "lp_ranking": [["LP1", 8.5, "GRADE A"]],
    },
    schema_yaml=Path("data/xlsx_schema.yaml"),
    out_path=Path("output/report_data.xlsx"),
)
# {"ok": True, "sheets": ["T1_overview", "T2_lp_ranking"]}
```

**Schema YAML 格式:**

```yaml
sheets:
  - name: T1_overview
    headers: ["指标", "值", "来源"]
    column_widths: [22, 16, 28]
    data_key: overview

  - name: T2_lp_ranking
    headers: ["LP 名称", "得分", "证据等级"]
    column_widths: [30, 12, 18]
    data_key: lp_ranking
```

- 调用方在 `data` dict 用 `data_key` 索引,值是 `[[row...], [row...]]`
- 缺字段(name/headers/data_key)→ 带索引的 ValueError(`Sheet #2 missing 'headers'`)
- out_path 父目录自动 mkdir

### 4. build_all_deliverables(一键封装)

```python
from build_all import build_all_deliverables

manifest = build_all_deliverables(
    report_dir=Path("output"),
    out_dir=Path("output"),
    sub_pages=None,           # None → 自动扫描 page_*.html
    toc_anchors=[("#ch1","一、执行摘要")],  # 给 PDF
    xlsx_schema=Path("data/xlsx_schema.yaml"),
    xlsx_data={...},
    disease_slug="lung-tb-china",
)
# 写入 output/delivery_manifest.json
# 任一失败不阻塞其余,manifest 记录详情
```

**自动检测顺序**(main.html):

1. `report_dir/main.html`
2. `report_dir/report.html`
3. `report_dir/report_v<N>.html` 中版本号最大的(`report_v25.html` > `report_v9.html`)

**部分失败处理:**

- HTML 失败 → PDF 用 main.html fallback,manifest 标 `pdf.fallback_input=True`
- PDF 失败 → XLSX 仍尝试
- xlsx_schema 或 xlsx_data 缺一 → xlsx 跳过,标 `ok=False, error=skipped`

详见 [bundle-manifest-spec.md](references/bundle-manifest-spec.md)。

---

## 自动验证规则

| 函数 | 默认验证 | auto_validate=False 时 |
|-----|---------|----------------------|
| build_standalone_html | size > 1 MB,anchor_count == 子页数 | 跳过 |
| build_pdf | size > 1 MB,pages ≥ 1(或 pypdf 不可用 → 不算失败) | 跳过 |
| build_xlsx | size > 1 KB,sheet_count ≥ 1 | 跳过 |

阈值常量集中在 `_validate.py`:`HTML_MIN_SIZE_BYTES` / `PDF_MIN_SIZE_BYTES` / `PDF_MIN_PAGES` / `XLSX_MIN_SIZE_BYTES` / `XLSX_MIN_SHEET_COUNT`。

---

## 失败模式速查

| 症状 | 原因 | 修复 |
|------|------|------|
| `RuntimeError: No Chrome/Edge/Chromium found` | PDF 渲染缺浏览器 | 装 Chrome 或显式 `chrome_path=` · 见 [chrome-headless-setup.md](references/chrome-headless-setup.md) |
| `ValueError: Main HTML missing <body>` | 主页 HTML 不含 `<body>` | 检查 main_html 是否真页面 |
| `ValueError: Sheet #N missing 'X'` | xlsx schema 字段缺失 | 补全 schema 的 name/headers/data_key |
| `KeyError: data['xxx'] missing` | xlsx schema 引用 data_key 在 data dict 中缺失 | 对齐 schema.sheets[].data_key 与 data 的 key |
| HTML size < 1 MB,validation.size_ok=False | 内容太少或 PNG 丢失 | 检查 png_dir 是否对、PNG 文件存在 |
| PDF pages 远低于预期 | HTML 渲染异常或 Chrome 崩溃 | 用 Chrome 手动开 HTML 看是否正常,看 Chrome stderr |
| anchor_count < anchor_target | 子页 HTML 不含 main 标签或 slug 命名冲突 | 子页必须有 `<main>` 包裹主体内容 |
| build_all 报 xlsx skipped | xlsx_schema 或 xlsx_data 任一为 None | 同时传两个,或接受 xlsx ok=False |
| Output HTML 在浏览器打不开 | 主页编码非 UTF-8 | 重新生成主页保证 UTF-8 BOM 无 |
| `result["missing_pngs"]` 非空 | 主页/子页引用了 png_dir 不存在的 PNG | 检查 PNG 文件名拼写或是否生成 |
| 两遍模式 Pass 2 失败但 HTML 未损坏 | 备份恢复机制工作正常 | 排查 Chrome 错误,原 HTML 已自动从备份恢复 |

---

## 跨平台兼容

- Windows / Linux / macOS 全部支持(Chrome 检测分平台,见 [chrome-headless-setup.md](references/chrome-headless-setup.md))
- Python 3.10+(PEP 604 `X | None` 语法)
- 依赖:`httpx` + `lxml` + `pyyaml` + `openpyxl` + 可选 `pypdf`(无则 PDF 不能测量页数,但仍能渲染)

---

## 版本

- v1.0(2026-04-25):从血液科 IFI v2.5.3 项目下沉而来,首个领域无关版本
  - build_standalone_html(parametric API,intra_page_anchors 可配)
  - build_pdf(单/两遍模式,跨平台 Chrome,备份恢复)
  - build_xlsx(schema YAML 驱动)
  - build_all_deliverables(一键封装 + delivery_manifest.json)