v0.5: deep quality refactor (P0+P1+P2)

- Split dr-chief-editor (Phase 3 read-only) vs new dr-editor-in-chief (Opus, Phase 4 lead) - New dr-translator (en->zh) and new humanizer-cn / output-hygiene / en-zh-translation skills - Switch to English working language (Phase 2-3), final Chinese translation (Phase 4) - /dr-init: add report title proposals + word budget mode - /dr-frame: bilingual framework - /dr-finalize: new chain editor->translator->polisher->reporter - report-template.py: widows/orphans/keepWithNext, 3-color hierarchy, confidentiality banner - dr-reporter: mandatory citations backfill + output hygiene check - dr-pm: batch-level context compression via manifest.batches_summary - mckinsey-method: SCQA only for Executive Summary + chapter intros (no explicit labels) - length-budget: 4 word-budget modes + en/zh 1:1.4 ratio
2026-04-21 13:02:54 +08:00
parent 4a38f6bed1
commit a092af4398
20 changed files with 3376 additions and 1246 deletions
@@ -1,255 +1,303 @@
 ---
 name: pdf-reportlab
-description: 用 ReportLab 生成专业中文 PDF 研究报告。包含思源宋体/黑体+霞鹜文楷的字体注册、集中样式管理、封面/目录/正文/参考文献多页模板、matplotlib 图表嵌入。dr-reporter 用于 Phase 4 出 PDF 稿；也可被用户直接调用渲染单章。
+description: 用 ReportLab 生成专业中文 PDF 研究报告。集中样式管理、紧凑分页（widows/orphans/keepWithNext）、颜色层次、封面保密标识、页眉页脚简洁化。基于 9MW1911 综合战略报告的编排参考。
 ---

-# ReportLab 中文 PDF 模板使用指南
+# ReportLab 中文 PDF 模板使用指南（v0.5）

 ## 一、为什么是 ReportLab

- **完全可控**：每个字号、行距、缩进都是代码说了算，不像 CSS/LaTeX 会被引擎意外改变
- **中文字体一次搞定**：`pdfmetrics.registerFont` 注册后全局可用，子集嵌入 PDF，分发无忧
- **速度快**：纯 Python，30,000 字报告 3-5 秒出稿（matplotlib 图表预渲染后）
- **图表质量高**：matplotlib 生成 300 DPI PNG 嵌入，比 LaTeX 的 pgfplots 快得多
- **样式集中**：用 `StyleSheet` 管理，避免你之前碰到的"中文字号不一"问题
+- **完全可控**：每个字号、行距、颜色由代码说了算，不被引擎意外改动
+- **中文字体一次搞定**：`pdfmetrics.registerFont` 注册后全局可用，子集嵌入 PDF，无授权问题
+- **分页规则精确**：支持 widows/orphans、keepWithNext、splitByRow 等避免孤行/寡行
+- **图表嵌入高质量**：matplotlib 300 DPI PNG，速度快
+- **样式集中在 StyleSheet**：避免字号不一

 ---

-## 二、项目模板入口
+## 二、模板入口

-模板脚本：`.opencode/templates/report-template.py`
+脚本：`.opencode/templates/report-template.py`

-调用方式：
+调用：
 ```bash
-python3 .opencode/templates/report-template.py \
+uv run python .opencode/templates/report-template.py \
    --input projects/<slug>/phase4/final.md \
    --manifest projects/<slug>/manifest.json \
    --output projects/<slug>/phase4/final.pdf \
    --fonts-dir .opencode/templates/fonts
 ```

-首次运行前必须：
+首次使用前：
 ```bash
 bash .opencode/templates/fonts/download-fonts.sh
 ```

 ---

-## 三、字体注册（模板已封装，此处仅说明原理）
+## 三、字体注册（7 个字重）

-```python
-from reportlab.pdfbase import pdfmetrics
-from reportlab.pdfbase.ttfonts import TTFont
-
-# 思源宋体 = 正文
-pdfmetrics.registerFont(TTFont('SrcSerif',      'fonts/SourceHanSerifSC-Regular.otf'))
-pdfmetrics.registerFont(TTFont('SrcSerif-Bold', 'fonts/SourceHanSerifSC-Bold.otf'))
-pdfmetrics.registerFontFamily('SrcSerif', normal='SrcSerif', bold='SrcSerif-Bold')
-
-# 思源黑体 = 标题/UI
-pdfmetrics.registerFont(TTFont('SrcSans-Light',  'fonts/SourceHanSansSC-Light.otf'))
-pdfmetrics.registerFont(TTFont('SrcSans-Medium', 'fonts/SourceHanSansSC-Medium.otf'))
-pdfmetrics.registerFont(TTFont('SrcSans-Bold',   'fonts/SourceHanSansSC-Bold.otf'))
-pdfmetrics.registerFont(TTFont('SrcSans-Heavy',  'fonts/SourceHanSansSC-Heavy.otf'))
-
-# 霞鹜文楷 = 引文/摘要
-pdfmetrics.registerFont(TTFont('Kai', 'fonts/LXGWWenKai-Regular.ttf'))
+```
+SrcSerif-Regular   思源宋体 Regular   正文
+SrcSerif-Bold      思源宋体 Bold      正文粗体
+SrcSans-Light      思源黑体 Light     页眉页脚
+SrcSans-Medium     思源黑体 Medium    三级标题/图表
+SrcSans-Bold       思源黑体 Bold      一二级标题
+SrcSans-Heavy      思源黑体 Heavy     封面大标题
+Kai                霞鹜文楷 Regular   摘要/引文
 ```

-**关键**：`TTFont` 虽然类名含 "TT"，但也接受 `.otf`（OpenType），别犹豫。
+---
+
+## 四、样式表（StyleSheet，集中管理）
+
+| 样式名 | 字体 | 字号 | 行高 | 颜色 | 备注 |
+|---|---|---|---|---|---|
+| `body` | SrcSerif | 10.5 | 18 | `#1a1a1a` | 正文，首行缩进 21pt |
+| `body-bold` | SrcSerif-Bold | 10.5 | 18 | `#1a1a1a` | 行内加粗 |
+| `h1` | SrcSans-Bold | 18 | 28 | `#1e3a8a` | 章标题，前强制分页 |
+| `h2` | SrcSans-Bold | 14 | 22 | `#2c5282` | 节标题 |
+| `h3` | SrcSans-Medium | 12 | 18 | `#374151` | 小节标题 |
+| `quote` | Kai | 10.5 | 18 | `#4b5563` | 引文 |
+| `caption` | SrcSans-Medium | 9 | 13 | `#6b7280` | 图表标题 |
+| `footnote` | SrcSerif | 9 | 13 | `#374151` | 脚注/参考文献 |
+| `header-footer` | SrcSans-Light | 8 | 12 | `#9ca3af` | 页眉页脚 |
+| `cover-title` | SrcSans-Heavy | 28 | 40 | `#0f172a` | 封面主标题 |
+| `cover-subtitle` | SrcSans-Medium | 15 | 24 | `#475569` | 封面副标题 |
+| `cover-confidential` | SrcSans-Bold | 11 | 16 | `#dc2626` | 封面保密标识（红色）|
+| `cover-meta` | SrcSerif | 11 | 18 | `#334155` | 封面元信息 |
+| `summary` | SrcSerif | 11 | 20 | `#1a1a1a` | 执行摘要 |

 ---

-## 四、样式表（集中管理，避免字号不一）
+## 五、分页规则（关键升级点）

-所有样式集中在模板的 `build_styles()` 函数：
+### 章（h1）

-| 样式名 | 字体 | 字号 | 行高 | 用途 |
-|---|---|---|---|---|
-| `body` | SrcSerif | 10.5 | 18 | 正文 |
-| `body-bold` | SrcSerif-Bold | 10.5 | 18 | 术语 |
-| `h1` | SrcSans-Bold | 18 | 28 | 章标题 |
-| `h2` | SrcSans-Bold | 14 | 22 | section 标题 |
-| `h3` | SrcSans-Medium | 12 | 18 | sub-section |
-| `quote` | Kai | 10.5 | 18 | 引文、摘要 |
-| `caption` | SrcSans-Medium | 9 | 13 | 图表标题 |
-| `footnote` | SrcSerif | 9 | 13 | 脚注/参考文献 |
-| `header-footer` | SrcSans-Light | 8 | 12 | 页眉页脚 |
-| `cover-title` | SrcSans-Heavy | 32 | 42 | 封面大标题 |
+- `pageBreakBefore=1`（每章新起一页）
+- `keepWithNext=1`（标题和下一段不分离）

-**行高 = 字号 × 1.5~1.7**，不要用默认值。
+### 节（h2）
+
+- **禁止单独触发分页**
+- `keepWithNext=1`（标题紧跟内容）
+
+### 小节（h3）
+
+- 同 h2，`keepWithNext=1`
+
+### 段落
+
+- `widows=2, orphans=2`（避免寡行/孤行）
+- 每段之间 `spaceBefore=6, spaceAfter=6`
+
+### 表格
+
+- `TableStyle` 中启用 `splitByRow=True`（长表格按行分页）
+- `repeatRows=1`（表头在分页后重复）
+- 单元格 padding 统一 4-6pt
+
+### 摘要/术语表/目录/参考文献
+
+- 每个独占起始页（用 `PageBreak`）

 ---

-## 五、报告 11 件套结构
+## 六、封面模板（参考 9MW1911）

-模板会按以下顺序生成页面：
+封面独立一页，无页眉页脚，布局：

-1. **封面页**（`PageTemplate: cover`）
-   - 主标题：`cover-title`
-   - 副标题：`h2`
-   - 作者、日期：`body`
-   - 单独版心，无页眉页脚
+```
+（上 30% 空白）

-2. **免责声明**（`PageTemplate: normal`）
-   - 固定模板，来源 manifest.json 的 `disclaimer` 字段
+     主标题（cover-title，黑色，居中）
+     副标题（cover-subtitle，深灰，居中）

-3. **执行摘要**（Executive Summary）
-   - `quote` 样式，1-2 页
-   - 来源 final.md 的 `## 摘要` 段
+（中部 40% 空白）

-4. **术语表**
-   - 两列表格，术语+解释
-   - 来源 final.md 的 `## 术语表` 段
+     [机密 | 仅供 XX 内部决策使用]  （cover-confidential，红色，居中）

-5. **目录**
-   - 自动从 h1/h2 生成，支持超链接
+（下部 20%）

-6. **主体正文**
-   - 来源 final.md 的各 `## 第 N 章 ...` 段
-   - 页眉：左=主题缩写 / 右=章节名
-   - 页脚：居中页码
+     类型：研究类
+     作者：Deep Research 系统 / <公司名>
+     编制日期：YYYY 年 M 月
+     版本：v1.0
+```

-7. **结论与建议**
-   - final.md 的最后一章
-
-8. **参考文献**
-   - 来源 `projects/<slug>/phase4/citations.bib` 或 `sources.jsonl`
-   - 按引用顺序编号，GB/T 7714 格式
-   - `footnote` 样式
-
-9. **附录 A：数据表**（可选）
-
-10. **附录 B：方法论说明**（可选）
-
-11. **版本信息**
-    - 生成时间、版本号、生成者（dr-reporter）、字数统计
+字段来源：
+- `manifest.report_title` / `report_subtitle`
+- `manifest.confidentiality` （如 "机密 | 仅供迈威生物内部决策使用"）
+- `manifest.author` / `manifest.date` / `manifest.version`

 ---

-## 六、图表嵌入规范
+## 七、页眉页脚（简洁化）

-**不要用 ReportLab 原生绘图**，全部预渲染为 PNG：
+### 页眉
+
+左边：报告简称（从 `manifest.report_title` 取前 15 字）
+右边：章节名（动态，从当前 h1 内容取）
+底线：`#e5e7eb` 浅灰分隔线
+
+### 页脚
+
+居中：页码（格式 `— X —`）
+字号：8pt，`#9ca3af` 浅灰
+
+### 特殊页
+
+- 封面：无页眉页脚
+- 免责声明：无页眉，仅页脚
+- 其他（摘要/术语表/目录/正文/附录/参考文献）：有页眉页脚
+
+---
+
+## 八、报告结构（11 件套）
+
+ReportLab 按以下顺序组装：
+
+1. **封面**（cover PageTemplate）
+2. **免责声明**（normal PageTemplate，单页）
+3. **Executive Summary / 执行摘要**（summary PageTemplate，1-2 页）
+4. **Abstract / 摘要**（normal，单页）
+5. **Glossary / 术语表**（normal）
+6. **Table of Contents / 目录**（TOC，自动生成）
+7. **正文各章**（normal，每章 h1 强制分页）
+8. **结论与建议**（正文的一部分）
+9. **附录**（normal）
+10. **参考文献**（bibliography PageTemplate，footnote 样式）
+11. **版本信息**（normal，单页）
+
+---
+
+## 九、Markdown 支持范围
+
+| Markdown | ReportLab 渲染 |
+|---|---|
+| `# 第 X 章 ...` | h1（新起一页，深蓝色）|
+| `## X.Y ...` | h2（节，蓝色，不分页）|
+| `### X.Y.Z ...` | h3（小节，深灰）|
+| `**粗体**` | inline `<b>` |
+| `*斜体*` | inline `<i>` |
+| `` `代码` `` | 等宽字体 |
+| `> 引文` | quote 样式（楷体，浅底色）|
+| `- 项` / `1. 项` | 项目符号列表 |
+| 表格 `\| \| \|` | Table，自动列宽 + splitByRow |
+| `![caption](path)` | 图片 + caption 样式 |
+| `[src_001]` | 上标引用 |
+| `---` | 分页符 |
+
+**不支持**：HTML 标签、数学公式、代码块高亮。
+
+---
+
+## 十、图表嵌入
+
+不用 ReportLab 原生绘图，全部预渲染为 PNG：

 ```python
-# 在 dr-analyst / dr-reporter 阶段，用 matplotlib 出图
 import matplotlib.pyplot as plt
 import matplotlib.font_manager as fm

-# 注册中文字体给 matplotlib
 font_path = '.opencode/templates/fonts/SourceHanSansSC-Medium.otf'
 fm.fontManager.addfont(font_path)
 plt.rcParams['font.family'] = 'Source Han Sans SC'
 plt.rcParams['axes.unicode_minus'] = False

-fig, ax = plt.subplots(figsize=(6, 4), dpi=150)
-# ...绘图代码
-plt.savefig('projects/<slug>/phase4/figures/fig_01_market_size.png', dpi=300, bbox_inches='tight')
+fig, ax = plt.subplots(figsize=(6, 4), dpi=300)
+# ...
+plt.savefig('projects/<slug>/phase4/figures/fig_01_XXX.png', dpi=300, bbox_inches='tight')
 ```

-然后在 final.md 里用标准 Markdown 引用：
-```markdown
-![图 1：2020-2025 GLP-1 市场规模](figures/fig_01_market_size.png)
-```
-
-模板会自动：
- 按 Markdown 解析图片
- 用 `caption` 样式渲染标题
- 图表居中，宽度适配页宽
+Markdown 中引用：`![图 1-1：2020-2025 GLP-1 市场规模（数据来源：[src_042]）](figures/fig_01_XXX.png)`

 ---

-## 七、Markdown → ReportLab 的支持范围
-
-模板支持以下 Markdown 元素：
-
-| Markdown | ReportLab 渲染 |
-|---|---|
-| `# 标题` | h1（章标题，自动分页） |
-| `## 标题` | h2（section，不分页） |
-| `### 标题` | h3（sub-section） |
-| `**粗体**` | `<b>` inline |
-| `*斜体*` | `<i>` inline |
-| `` `代码` `` | 等宽字体 inline |
-| `> 引文` | `quote` 样式块 |
-| `- 列表项` / `1. 项` | 项目符号列表 |
-| `表格`（\| \| \|） | ReportLab Table，自动列宽 |
-| `![caption](path)` | 图片 + caption |
-| `[src_001]` | 上标引用链接到参考文献 |
-| `---` | 分页符（`PageBreak`） |
-
-**不支持**（请在 Markdown 里避免）：
- HTML 标签（除少数 inline）
- 数学公式（后续可加 matplotlib 渲染）
- 代码块高亮（只保留等宽显示）
-
---
-
-## 八、manifest.json 的必需字段
+## 十一、manifest 必需字段

 ```json
 {
-  "slug": "glp1-obesity-2026",
-  "topic": "GLP-1 减重药物竞争格局与投资机会",
-  "subtitle": "2026 年产业深度研究",
-  "author": "Deep Research 系统 v0.1",
-  "date": "2026-04-20",
-  "type": "研究类",
+  "slug": "...",
+  "report_title": "自研 O-糖苷酶立项可行性研究报告",
+  "report_subtitle": "对标 NEB 与 Merck 经典产品的技术路径、IP 壁垒与差异化战略",
+  "confidentiality": "机密 | 仅供内部决策使用",
+  "author": "Deep Research 系统",
+  "date": "2026-04-21",
  "version": "1.0",
-  "disclaimer": "本报告基于公开信息与 AI 辅助研究生成，仅供参考，不构成投资建议。",
-  "cover_theme": "blue"
+  "type": "研究类",
+  "disclaimer": "本报告基于公开信息与 AI 辅助研究生成，仅供参考..."
 }
 ```

 ---

-## 九、常见坑与对策
+## 十二、常见坑与对策

 | 坑 | 对策 |
 |---|---|
-| 中文字号不一 | **集中 StyleSheet**，不在 Paragraph 里 inline 改 fontSize |
-| 行距太挤 | 行高 = 字号 × 1.5~1.7，不要用默认 |
+| 中文字号不一 | 集中 StyleSheet，不在 Paragraph 里 inline 改 fontSize |
+| 行距太挤 | 行高 = 字号 × 1.5~1.7 |
 | 换行断错 | `wordWrap='CJK'` 必设 |
-| 字体子集缺字 | 用完整版思源字体（非 subset 精简版） |
-| 图片变形 | 先 matplotlib 出 300 DPI PNG，再 `Image(path, width=..., height=...)` |
-| 页眉页脚重叠 | 用 `BaseDocTemplate` + `PageTemplate`，`Frame` 的 margin 留足 |
-| 英文中文混排间距怪 | 思源系列自带 CJK metrics，间距会自适应，一般不用额外处理 |
+| 表格被截断 | `splitByRow=True, repeatRows=1` |
+| 标题孤行（页末一个标题后直接新页）| `keepWithNext=1` |
+| 段落寡行（末段只剩一行在下页）| `widows=2, orphans=2` |
+| 图片变形 | 先 matplotlib 出 300 DPI PNG，再 `Image(path, width=..., kind="proportional")` |
 | 生成慢 | matplotlib 图表预渲染，不要在 PDF 生成阶段现算 |
+| 参考文献丢失 | dr-reporter 出稿前检查：读 citations.md，确认内容已写入 final.md |

 ---

-## 十、调用流程（dr-reporter 阶段）
+## 十三、dr-reporter 调用流程

 ```
-1. 检查字体：ls .opencode/templates/fonts/*.otf | wc -l ≥ 6
-2. 检查输入：projects/<slug>/phase4/final.md 存在
-3. 检查配置：projects/<slug>/manifest.json 有必需字段
-4. 执行：
-   python3 .opencode/templates/report-template.py \
+1. 环境检查
+   - 字体 ≥6 个 OTF 文件
+   - final.md 存在
+   - manifest.json 有必需字段
+
+2. 回填参考文献（关键步骤，修复 v0.4 的 bug）
+   - 读 citations.md 内容
+   - 在 final.md 中找到"## 参考文献"段落
+   - 如果段落内容是占位符（如 "[由 dr-reporter 自动生成]" 或为空）
+     → 替换为 citations.md 的完整内容
+   - 写回 final.md
+
+3. 图表检查
+   - 扫描 final.md 中所有 ![...](path) 图片引用
+   - 验证每个 path 在 figures/ 目录下存在
+   - 缺失图片 → 警告并继续，但汇报中注明
+
+4. 生成 PDF
+   uv run python .opencode/templates/report-template.py \
       --input projects/<slug>/phase4/final.md \
       --manifest projects/<slug>/manifest.json \
-       --output projects/<slug>/phase4/final.pdf
-5. 验证：
-   - PDF 打得开
-   - 文件大小 > 500KB（太小说明字体没嵌）
-   - 页数合理（30,000 字约 60-80 页）
-6. 汇报：输出路径、页数、文件大小
+       --output projects/<slug>/phase4/final.pdf \
+       --fonts-dir .opencode/templates/fonts
+
+5. 生成 DOCX（可选）
+   pandoc projects/<slug>/phase4/final.md \
+       --from markdown --to docx \
+       --output projects/<slug>/phase4/final.docx \
+       --toc --toc-depth=3
+
+6. 验证
+   - PDF 文件大小 > 500KB（太小说明字体没嵌）
+   - PDF 页数合理（按字数估算）
+   - "参考文献"章节存在且非空
+
+7. 汇报
 ```

 ---

-## 十一、MVP 阶段注意
+## 十四、输出卫生检查（必跑）

-目前（MVP）`report-template.py` 是**基础版**，支持：
- 思源字体注册
- 标题 / 正文 / 引文 / 表格 / 图片
- 简单封面 + 目录
- 参考文献自动编号
+生成 PDF 前：

-**暂未实现**（Phase 4 能力阶段补齐）：
- 自动书签/大纲（PDF navigation pane）
- 交叉引用（"见第 3 章"自动跳转）
- 复杂页眉（左右对称排版）
- 附录 B 自动生成（方法论模板）
+```bash
+# 加载 skill:output-hygiene
+python3 .opencode/templates/hygiene_check.py projects/<slug>/phase4/final.md
+```

-如需上述功能，在 manifest.json 里标 `"template_features": ["bookmarks", "xref", ...]`，未来版本会处理。
+禁止词残留 → 抛回 dr-polisher 再润色一轮。