kai/deep_research
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
This commit is contained in:
kai
2026-04-21 13:02:54 +08:00
parent 4a38f6bed1
commit a092af4398
20 changed files with 3376 additions and 1246 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.opencode/skills/en-zh-translation/SKILL.md
+267
View File
@@ -0,0 +1,267 @@
---
name: en-zh-translation
description: 生物医药英译中规范。专有名词双语对照策略、术语表管理、断句重构原则、数字与标点转换、去翻译腔。dr-translator 必读。
---
# 英译中规范（生物医药专业报告）
## 你的身份
你是生物医药专业报告的翻译编辑，不是机器翻译。目标：译文读起来**像母语中文写作者的原创**，不是"翻译腔"。
---
## 一、整体原则
### 1. 忠实于内容，不忠实于句式
英文长句拆成中文短句。英文习惯的 "X, which is Y, was Z" 嵌套结构，中文应断为两到三句。
**反例（翻译腔）**：
> 这种药物，它是 GLP-1 受体激动剂家族中的一员，被证明在降低 HbA1c 方面是有效的。
**改写**：
> 这种药物属于 GLP-1 受体激动剂家族，能有效降低 HbA1c。
### 2. 不保留英文的被动语态
英文被动 → 中文主动（或不提主语）。
- "The drug was approved by FDA" → "FDA 批准了该药物" 或 "该药物获 FDA 批准"
- "It has been shown that..." → 直接说"研究显示..."或"数据显示..."
### 3. 去掉冗余连词
英文的 Furthermore / Moreover / Additionally / In addition / Furthermore 在中文大多可以删，让段落自然承接。
---
## 二、专有名词双语对照策略
### 首次出现原则
专有名词**首次出现**时用"中文（英文）"格式，之后只用中文或英文单独一致使用：
- 首次：`糖苷水解酶 101 家族（GH101 family）`
- 之后：`GH101 家族` 或 `糖苷水解酶 101 家族`（选一种风格用到底）
### 行业惯例优先
以下术语在行业中**中英混用是标准做法**，不要强制翻译：
- 直接保留英文：FDA, EMA, NMPA, FEV1, BEC, sST2, CAT, SGRQ, BLA, NDA, IND, ICH, CMC, CDMO, CDMO, GH101, IgG, mAb, ADC, BsAb, GLP-1, PD-1, CAR-T, HbA1c, IL-4, IL-5, IL-13, IL-33, ST2, Th2, ILC2s
- 中英并列的术语：抗体偶联药物（ADC）、单克隆抗体（mAb）、慢性阻塞性肺疾病（COPD）
### 动词/形容词类翻译
这类不保留英文：
| 英文 | 中文 |
|---|---|
| significant | 显著（需跟数据）|
| substantial | 大幅 |
| demonstrate | 表明 / 显示 |
| exhibit | 表现出 |
| propose | 提出 |
| investigate | 研究 |
| establish | 建立 / 确立 |
| confirm | 证实 |
| underscore | （直接删，见 humanizer-cn） |
| highlight | （直接删或改为"指出"） |
---
## 三、数字与单位转换
### 数字表达
- 英文 "12,000" → 中文 "12,000"（保留千分位逗号）
- 英文 "1.2 billion USD" → 中文 "12 亿美元"
- 英文 "3.5 million patients" → 中文 "350 万名患者"
- 英文 "23%" → 中文 "23%"
### 量词
数字后面中文要加量词：
| 英文 | 中文 |
|---|---|
| 12 studies | 12 项研究 |
| 3 companies | 3 家公司 |
| 5 patents | 5 项专利 |
| 20 patients | 20 名患者 |
| 1.2 billion | 12 亿 |
| 3 years | 3 年 |
| 6 months | 6 个月 |
### 时间格式
- "2024" → "2024 年"
- "2020-2025" → "2020-2025 年"（用半角连字符）
- "Q4 2025" → "2025 年第 4 季度" 或 "2025 Q4"
- "March 2024" → "2024 年 3 月"
### 百分比
- "30%" → "30%"
- "up to 60%" → "最高 60%"
- "approximately 40%" → "约 40%"
---
## 四、标点转换
### 必须转为中文标点的情况
中文段落中，句内标点必须是**中文全角标点**：
| 英文 | 中文 |
|---|---|
| `,` | `，` |
| `.` | `。` |
| `;` | `；` |
| `:` | `：` |
| `?` | `？` |
| `!` | `！` |
| `"..."` | `"..."` |
| `'...'` | `'...'` |
| `(...)` | `（...）` |
| `—` | `——`（中文全角破折号是两个连一起）|
| `...` | `……`（中文省略号六个点）|
### 保留英文标点的情况
- 英文术语、代码、URL 内部的标点
- 行内引用的英文原文
- 数据单位前后：`3.2 mg/kg`（数字和单位之间用英文斜杠）
---
## 五、句子结构重构
### 英文长句→中文短句
**原文**：
> The observation that sST2 levels, which have been validated as a prognostic biomarker in heart failure and included in ACC/AHA guidelines, are elevated in COPD patients during acute exacerbations suggests a potential cross-disease mechanism.
**烂翻译**：
> sST2 水平（它已被验证为心力衰竭的预后生物标志物并被纳入 ACC/AHA 指南）在 COPD 患者急性加重期间升高的观察结果，提示了潜在的跨疾病机制。
**好翻译**：
> sST2 已是心力衰竭领域的预后生物标志物，纳入 ACC/AHA 指南多年。COPD 患者在急性加重期间 sST2 水平升高，提示这两类疾病可能共享同一条炎症通路。
### 修饰语位置
英文习惯把修饰语放后面（of / which / that 从句），中文要前置或拆句。
- "the company that pioneered O-glycosidase commercialization in 1990" → "1990 年率先实现 O-糖苷酶商业化的那家公司"（前置）
- 或拆句："NEB 公司在 1990 年率先将 O-糖苷酶商业化"
---
## 六、段落重构
### 英文段落首句原则
英文学术/商业写作的段落一般首句即论点（Topic sentence），后面是论据。翻译时保留这一结构，不要打乱。
### 段落长度调整
- 英文习惯长段（150-200 词 / ≈ 250-330 字）
- 中文如果一段超过 400 字，读起来累。超过 400 字应考虑拆段。
- 拆段原则：按子论点拆，不要机械按句数拆
---
## 七、翻译后校对清单
译完后自己过三遍：
### 第 1 遍：准确性
- 所有数字、日期、百分比、来源 ID `[src_xxx]` 完全一致？
- 所有专有名词首次出现有中英对照？
- 没有错译、漏译？
### 第 2 遍：流畅性
- 有没有"的"字过多？（`X 的 Y 的 Z 的 W` 这种链式改为"X 下的 Y 中的 Z"）
- 有没有翻译腔？（"...的话"、"...的话说"、"对于...来说"、"在...方面"）
- 句子长度是否有节奏变化？全长句或全短句都不行
- 读一遍念出来，是否自然？
### 第 3 遍：humanizer-cn 禁用词
加载 `skill:humanizer-cn`，扫一遍中文禁用词清单：
- 跃迁 / 赋能 / 落地 / 格局 / 生态 / 痛点 / 风口 / 闭环 / 抓手 / 颠覆 / 引领 / 重塑 / 赛道 / 范式 / 底层逻辑 / 本质上 / 从根本上
- AI 套话：随着、不断、深入、值得注意、不难发现、具有重要意义、综上所述、由此可见
---
## 八、特殊情况处理
### 原文是咨询报告风格
保留咨询报告的语感：观点前置、数字支撑、对比结构。不要为了"接地气"而口语化。
### 原文包含表格
表格翻译时：
- 表头翻译
- 单元格数字保留原格式
- 专有名词保留英文（节省宽度）
- 表格标题用 `表 X-Y：<内容>（数据来源：[src_xxx]）`
### 原文包含图表
图表标题和说明翻译；图表本身（如果是 matplotlib 生成的 PNG）可能需要 dr-reporter 用中文字体重新生成。
### 原文包含 SCQA 式段落（如 Executive Summary）
SCQA 结构保留（因为这是麦肯锡式叙事），但不要标注 "S/C/Q/A"字样，按 `mckinsey-method skill` 要求写成融合式。
---
## 九、术语表维护
dr-translator 在翻译过程中维护项目级术语表：
```
projects/<slug>/phase4/glossary.json
{
"GH101 family": "糖苷水解酶 101 家族",
"endoglycosidase": "内切糖苷酶",
"O-glycosylation": "O-糖基化",
"Core 1": "核心 1 型",
...
}
```
这个术语表会作为 final report 里的"术语表（Glossary）"章节，双语对照呈现。
---
## 十、输出要求
### 文件命名
- 英文稿：`projects/<slug>/phase4/final_en.md`
- 中文稿：`projects/<slug>/phase4/final_zh.md`（dr-translator 产出）
- 中文稿润色后：仍然 `final_zh.md`（dr-polisher 原地修改）
- PDF 主稿：`final.pdf`（中文）
- PDF 英文参考版：`final_en.pdf`
- DOCX 主稿：`final.docx`（中文）
### 交付汇报
翻译完成后向调用者返回：
```
翻译完成
英文源：projects/<slug>/phase4/final_en.md (X words)
中文译：projects/<slug>/phase4/final_zh.md (X 字)
膨胀率：X%（预期 1.4 倍）
术语表：projects/<slug>/phase4/glossary.json (X 条)
翻译质检：humanizer-cn 禁用词 X 项（已清理）
下一步：等待 dr-polisher 做最终润色
```
.opencode/skills/humanizer-cn/SKILL.md
+356
View File
@@ -0,0 +1,356 @@
---
name: humanizer-cn
description: 去除 AI 味的中英双语写作规则。基于 Wikipedia Signs of AI Writing + blader/humanizer + 生物医药中文报告特化经验。dr-polisher 必读；dr-editor-in-chief 和 dr-translator 也应遵循。
---
# Humanizer（中英双语去 AI 味规范）
## 你的任务
拿到文稿后，**按以下流程处理**：
1. **扫描**全文，识别所有 AI 模式（下述 28 条）
2. **重写**问题段落，保留原意，换掉 AI-ism
3. **注入人味**：不只是删除坏模式，要加入真正的个性
4. **做最后一遍自问**：问自己"这段里还有什么显得是 AI 写的？"逐条修正
---
## 核心原则
> **避免 AI 模式只是一半工作。没有灵魂的干净文字和 slop 一样明显。好的写作背后有真人。**
---
## 英文规则（Phase 2/3 工作语言）
### 1. 过度渲染"意义/遗产/更宏大趋势"
**禁用词**：stands/serves as, is a testament/reminder, pivotal/crucial/key moment, underscores importance, reflects broader, symbolizing enduring, contributing to, setting the stage for, marking a shift, key turning point, evolving landscape
**反例**：
> The Institute was established in 1989, marking a pivotal moment in the evolution of regional statistics and reflecting broader decentralization trends.
**改写**：
> The Institute was established in 1989 to collect regional statistics independently from the national office.
### 2. 空泛归因 / Weasel Words
**禁用词**：Industry reports suggest, Observers have cited, Experts argue, Some critics argue, several sources, It has been noted
**反例**：
> Experts believe this river plays a crucial role in the regional ecosystem.
**改写**：
> A 2019 survey by the Chinese Academy of Sciences found that this river supports 12 endemic fish species.
### 3. -ing 短语堆砌（伪深度）
**禁用模式**：highlighting/underscoring/emphasizing/ensuring/reflecting/contributing to/cultivating/fostering/encompassing/showcasing
**反例**：
> The architect chose blue, green, and gold, symbolizing Texas bluebonnets, reflecting the community's deep connection to the land.
**改写**：
> The architect chose blue, green, and gold to reference local bluebonnets and the Gulf coast.
### 4. 高频 AI 词汇
**禁用**：Actually, additionally, align with, crucial, delve, emphasizing, enduring, enhance, fostering, garner, highlight (v), interplay, intricate, key (adj), landscape (abstract), pivotal, showcase, tapestry, testament, underscore, valuable, vibrant
### 5. 规避 "is/are"（Copula Avoidance）
**禁用模式**：X serves as Y / X stands as Y / X marks Y / X represents Y / X boasts / X features / X offers
**反例**：
> Gallery 825 serves as LAAA's exhibition space and boasts over 3,000 square feet.
**改写**：
> Gallery 825 is LAAA's exhibition space, with 3,000 square feet.
### 6. 负向平行（Negative Parallelism）
**禁用**：It's not just X, it's Y / Not only X but Y / more than just
### 7. 三段式（Rule of Three）
不为凑数拼三项。"The event features keynote sessions, panel discussions, and networking opportunities" → "The event includes talks and panels with informal networking between sessions."
### 8. 同义词循环（Elegant Variation）
避免在连续句子里对同一概念使用"the protagonist / the main character / the central figure / the hero"。一个叫法用到底即可。
### 9. 伪范围（False Ranges）
**禁用**：from X to Y 当 X 和 Y 不在同一量纲上。
"Our journey has taken us from the Big Bang to the cosmic web, from star formation to dark matter" → "The book covers the Big Bang, star formation, and dark matter."
### 10. 被动/无主语片段
"No configuration file needed" → "You do not need a configuration file."
"The results are preserved automatically" → "The system preserves the results automatically."
### 11. 破折号过度使用
长破折号每章不超过 3 处。绝大多数情况下可以用逗号、句号或括号改写。
### 12. 内联粗体列表（Inline-header bullets）
**反例**：
- **Speed:** Code generation is significantly faster.
- **Quality:** Output quality has been enhanced.
- **Adoption:** Usage continues to grow.
**改写为段落**：
> The tool speeds up code generation substantially and improves output through better training. Adoption has grown alongside these improvements.
### 13. 标题 Title Case
**禁用**：## Strategic Negotiations And Global Partnerships
**改为**：## Strategic negotiations and global partnerships
### 14. Emoji 装饰
禁止在标题、段落开头用 emoji（🚀 💡 ✅）。
### 15. Curly Quotes
"这种引号" 改为普通 "straight quotes"。
### 16. Chatbot 残留
**禁用**：I hope this helps, Of course!, Certainly!, You're absolutely right!, Would you like..., Let me know, Here is a..., Great question!
### 17. 知识截止声明
**禁用**：as of [date], up to my last training update, While specific details are limited, based on available information
### 18. 谄媚语气
**禁用**：Great question! You're absolutely right! That's an excellent point.
### 19. Filler 短语
| 禁用 | 改为 |
|---|---|
| In order to achieve this goal | To achieve this |
| Due to the fact that | Because |
| At this point in time | Now |
| In the event that | If |
| Has the ability to | Can |
| It is important to note that | （直接删） |
### 20. 过度 Hedging
"It could potentially possibly be argued that..." → "The policy may..."
### 21. 通用正向总结
**禁用**：The future looks bright. Exciting times lie ahead. A major step in the right direction.
**改为**：具体说清楚下一步做什么。
### 22. 连字符成对词过多
AI 对常用词对几乎 100% 加连字符（third-party, cross-functional, data-driven, decision-making, well-known, high-quality, real-time, long-term, end-to-end）。人类用得不那么整齐。选择性去掉连字符。
### 23. 权威套话
**禁用**：The real question is, at its core, in reality, what really matters, fundamentally, the deeper issue, the heart of the matter
这些都是 AI 假装切穿表象直达真相的套路，删掉后真相还是在那里。
### 24. Signposting 预告
**禁用**：Let's dive in, let's explore, let's break this down, here's what you need to know, without further ado
直接进入内容，不要预告。
### 25. 标题后重复一遍标题内容
```
## Performance
Speed matters.
When users hit a slow page, they leave.
```
删掉 "Speed matters"。
### 26. 过度 boldface
不要在每一句里加粗 **这个** 和 **那个**。一段里粗体超过 2 处，说明你没认真思考该强调什么。
---
## 中文规则（Phase 4 翻译后适用）
中文有一套自己的 AI 味。以下是核心禁用清单。
### CN-1：AI 高频词（见到即替换）
| 禁用词 | 替换策略 |
|---|---|
| 跃迁 / 跃升 / 跃上 | 改为"升至 / 提升到" |
| 赋能 | 改为"帮助 / 支持 / 推动" |
| 落地 | 改为"实施 / 推行 / 执行" |
| 格局 | 具体说清楚是"竞争格局"还是"市场格局" |
| 生态 / 生态圈 | 少用，具体说"上下游企业" |
| 深度 / 深度的 | 少用，改为具体描述 |
| 痛点 | 改为"问题 / 困难" |
| 风口 | 直接说"市场机会" |
| 闭环 / 打通闭环 | 改为"完成了完整流程" |
| 抓手 | 删掉，直接说动作 |
| 颠覆 / 颠覆性 | 少用，过度戏剧化 |
| 引领 / 引领性 | 改为具体的"率先做了..." |
| 重塑 / 重构 | 改为"改变 / 改组" |
| 赛道 | 改为"细分领域 / 市场" |
| 范式 | 改为"方式 / 模式" |
| 底层逻辑 | 改为"根本原因 / 核心机制" |
| 本质上 / 从根本上 | 直接删除，讲具体内容 |
### CN-2：AI 套话（整句清除）
**禁用**：
- "随着 X 的不断发展"
- "在 X 背景下 / 在这一背景下"
- "值得注意的是"
- "不难发现"
- "显而易见"
- "毫无疑问"
- "具有重要意义"
- "发挥了重要作用"
- "起到了 X 的作用"
- "综上所述"
- "由此可见"
- "总的来说"
- "据报道"
- "有研究表明 / 有专家认为"（除非说出具体是哪项研究/哪位专家）
### CN-3：规避"是"的冗余句式（AI 极高频）
| 禁用 | 改为 |
|---|---|
| X 标志着 Y | X 是 Y / 从此 Y 成立 |
| X 代表着 Y | X 是 Y |
| X 构成 Y | X 是 Y |
| X 成为 Y | 直接用 "X 是 Y" |
| X 跃升为 Y | X 升到 Y |
| X 彰显着 Y | X 说明 Y |
| X 体现了 Y | X 说明 Y / X 显示 Y |
### CN-4：三段式堆砌（Rule of Three）
中文 AI 特别爱拼三段：
- "短期、中期、长期"
- "需求侧、供给侧、政策侧"
- "技术、资本、市场"
- "硬实力、软实力、巧实力"
不为凑数拼三段。如果只有两个要点就说两个，四个就说四个，节奏自然一些。
### CN-5：空洞形容词（必须跟数据）
- 巨大 → "250 亿美元"
- 快速 → "CAGR 23%"
- 显著 → "降低 40%（p<0.001）"
- 强劲 → "增速高于同行 8 个百分点"
- 显著领先 → "领先第二名 30% 市场份额"
无数据形容词直接删。
### CN-6：破折号规范
- 中文用全角破折号 `——`（两个连接起来）
- 每章不超过 3 处
- 多数情况可改为逗号、括号、句号
### CN-7：负向平行
**禁用**：
- "不仅...更..."
- "不仅仅是...，更是..."
- "不是...而是..."
- "不只是...，还是..."
偶用可以，成段出现必改。
### CN-8：过度书面腔 / 翻译腔
- "使...得以..." → "让 X 能 Y"
- "通过...方式 / 通过...的方式" → "用 X / 以 X"
- "对于 X 而言" → "X 的..."
- "在 X 方面" → 具体说哪方面
- "就 X 来说" → 删
### CN-9：内联粗体小标题（每段开头都加粗）
**反例**：
- **技术层面**：xxx
- **商业层面**：xxx
- **风险层面**：xxx
改为叙述段落。保留加粗的前提是：真的是关键强调，而不是装饰。
### CN-10：章节标题 / 小节标题禁止用符号开头
禁止：🚀 / ✅ / 💡 / ⚠️ 等 emoji 开头。如果是正式提示标志，在正文中用文字表述。
---
## 注入人味（Add Soul）
干净但没灵魂的文字和 AI slop 一样明显。合格的报告要有：
### 有立场
不要只报告事实——对事实有判断。"定价策略存在风险"比"定价策略有利有弊"好。
### 节奏变化
短句。再长一些的句子慢慢把意思讲清楚。混着用。
### 承认不确定
真人会说"我不确定"，AI 不会。允许出现"这个趋势能否持续还需观察"、"目前数据尚不足以做判断"这种诚实表达。
### 具体而非抽象
- "用户体验有待改善" → "首次打开页面要 8 秒，用户很可能就离开了"
- "存在风险" → "最大风险是 NEB 可能用专利诉讼拖延 18-24 个月"
### 有节制的第一人称
研究报告一般不用"我"，但是"我们认为 / 本报告认为"比"一般认为"好。
---
## 最后的自审流程
写完一段后，问自己三个问题：
1. **这句话是真人会说的吗？** 读出来听听看是否拗口做作
2. **能更具体吗？** 任何抽象词都问能否换成数据/案例
3. **删掉这句会失去什么？** 如果没损失，删
---
## Process Summary（给调用 agent 的操作清单）
拿到一份待润色的稿子后：
1. **扫描并标记**：全文搜索上述禁用词和模式
2. **逐段重写**：按规则替换
3. **检查节奏**：段落长短、句子长短是否有变化
4. **删减冗余**：空话 / 套话 / 无数据形容词
5. **核对格式**：没有 emoji、粗体不过度、标题 sentence case、破折号节制
6. **So What 检验**：每段都得有价值
7. **最后一遍自问**：这段还有哪里像 AI？针对性再改一轮
---
## 参考
- Wikipedia: Signs of AI writing (WikiProject AI Cleanup)
- blader/humanizer SKILL v2.5.1
- 9MW1911 综合战略报告（中文风格参考）
.opencode/skills/length-budget/SKILL.md
+120 -153
View File
@@ -1,205 +1,172 @@
---
name: length-budget
description: 报告字数预算分配与执行校验。规定综述/研究/投资/管理各类型的最低字数、章节配额算法、字数自检逻辑、不足时的补写策略。dr-plan 用于 Phase 1 分配配额，dr-pm 和 dr-analyst 用于 Phase 2 执行校验。
description: 报告字数预算分配与执行校验。支持 4 种字数模式（自动/简明/详细/深度），英中互换规则（英文词数 ≈ 中文字数 × 0.7），章节配额算法与补写策略。Phase 1 用于设定预算，Phase 2/4 用于自检。
---
# 字数预算系统（硬性 KPI）
# 字数预算系统
## 一、报告类型与字数下限
## 一、四种字数模式（Phase 1 访谈时选择）
| 报告类型 | 最小字数 | 建议章节数 | 典型单章字数 |
用户在 /dr-init 访谈时选定其中一种，写入 manifest.word_budget_mode：
| 模式 | 中文字数目标 | 英文词数目标 | 章节数 | 适用场景 |
|---|---|---|---|---|
| `auto` | 按类型默认 | 按类型默认 | 8-12 | 不明确时默认 |
| `concise` | 8,000-12,000 | 5,600-8,400 | 6-8 | 高管一阅即过 |
| `detailed` | 20,000-35,000 | 14,000-24,500 | 10-12 | 标准专业报告 |
| `deep` | 50,000-80,000 | 35,000-56,000 | 12-15 | 深度研究/行业专著 |
**auto 模式的默认字数**（按报告类型）：
| 报告类型 | 中文字数 | 英文词数 | 章节数 |
|---|---|---|---|
| 综述类（领域全景、技术综述） | **10,000** | 8-10 章 | 1,000-1,250 |
| 研究类（深度专题、竞品研究） | **30,000** | 10-12 章 | 2,500-3,000 |
| 投资报告（赛道/公司分析） | **20,000** | 10-12 章 | 1,700-2,000 |
| 管理/工艺类（运营分析、SOP） | **15,000-25,000** | 9-11 章 | 1,700-2,200 |
| 综述 | 12,000 | 8,400 | 8-10 |
| 研究 | 35,000 | 24,500 | 10-12 |
| 投资 | 22,000 | 15,400 | 10-12 |
| 管理/工艺 | 18,000 | 12,600 | 9-11 |
**总字数 = 正文字数**，不含：摘要、目录、参考文献、附录。
**字数只是参考，以把问题讲清楚为第一优先**。过少则内容单薄，过多则注水。目标区间±20% 内都可接受。
---
## 二、章节配额分配算法（dr-plan 用）
## 二、英文-中文字数换算
### Step 1：确定总字数目标
- 综述类 → 12,000 字（下限 10,000，留 20% 缓冲）
- 研究类 → 35,000 字（下限 30,000）
- 投资类 → 22,000 字
- 管理类 → 18,000 字（按选定）
**核心换算率**：1 个英文词 ≈ 1.4-1.5 个中文字
### Step 2：按章节重要性分层
Phase 2 产出英文，Phase 4 翻译为中文后字数会自然膨胀约 40%。预算时：
- Phase 2 英文稿：按英文词数目标 × 1.0 写
- Phase 4 中文稿：英文词数 × 1.4 应落在中文字数目标的 ±15% 内
```
P0 章（2-3 章）：核心论点章，字数配额 = 总字数 × 15-18% 每章
P1 章（3-5 章）：主干证据章，字数配额 = 总字数 × 8-12% 每章
P2 章（2-3 章）：辅助分析章，字数配额 = 总字数 × 5-8% 每章
引言+结论：每章 总字数 × 6-10%
自动换算工具：
```python
def en_words_to_zh_chars(en_words: int) -> int:
return int(en_words * 1.4)
def zh_chars_to_en_words(zh_chars: int) -> int:
return int(zh_chars / 1.4)
```
### Step 3：验证总和
---
- 所有章节配额之和应等于总字数目标（±5%）
- 任意两章字数差距 **不超过 ±30%**（避免头重脚轻）
- 结论章必须 ≥ 总字数 10%
## 三、章节配额分配（dr-plan 在 Phase 1 用）
### Step 4：Section 分配
### 三层优先级
每章内：
- 每 section 最少 **800 字**（不够则合并 section）
- 章内 section 数量控制在 2-5 个
- 每个 section 下可分 sub-section（300-500 字）
```
P0（核心章，2-3 章）：每章 = 总字数 × 13-16%
P1（主干章，3-5 章）：每章 = 总字数 × 8-11%
P2（辅助章，2-3 章）：每章 = 总字数 × 5-7%
引言 / 结论章：各 = 总字数 × 6-8%
```
### 示例（研究类 35,000 字 / 11 章）
### 约束
| 章 | 定位 | 字数配额 | 占比 |
- 章节字数差距 ≤ ±30%（防止头重脚轻）
- 结论章 ≥ 总字数 × 10%
- 每节 ≥ 600 字（英文 ≥ 420 词），不足则合并节
### 示例：30,000 字研究报告分配
| 章 | 定位 | 中文配额 | 英文配额 |
|---|---|---|---|
| 第 1 章 引言与边界 | intro | 2,100 | 6% |
| 第 2 章 核心观点（P0） | P0 | 5,250 | 15% |
| 第 3 章 机制剖析（P0） | P0 | 5,250 | 15% |
| 第 4 章 临床证据（P1） | P1 | 3,850 | 11% |
| 第 5 章 竞争格局（P1） | P1 | 3,500 | 10% |
| 第 6 章 产业链（P1） | P1 | 3,150 | 9% |
| 第 7 章 政策监管（P1） | P1 | 2,800 | 8% |
| 第 8 章 风险（P2） | P2 | 2,100 | 6% |
| 第 9 章 国际对比（P2） | P2 | 1,750 | 5% |
| 第 10 章 趋势判断 | P1 | 2,450 | 7% |
| 第 11 章 结论与建议 | conclusion | 2,800 | 8% |
| **合计** | | **35,000** | **100%** |
验证：
- ✅ 总和 = 35,000
- ✅ 最大（5,250）/ 最小（1,750）= 3 倍 → ❌ 超过 ±30% 了，需调整
- 调整：第 9 章升到 2,450（7%），从 P0 各降 400 → 验证通过
| 第 1 章 引言 | intro | 1,800 | 1,260 |
| 第 2 章 核心论点 | P0 | 4,500 | 3,150 |
| 第 3 章 机制剖析 | P0 | 4,500 | 3,150 |
| 第 4 章 临床证据 | P1 | 3,300 | 2,310 |
| 第 5 章 竞争格局 | P1 | 3,000 | 2,100 |
| 第 6 章 产业链 | P1 | 2,700 | 1,890 |
| 第 7 章 政策监管 | P1 | 2,400 | 1,680 |
| 第 8 章 风险 | P2 | 1,800 | 1,260 |
| 第 9 章 国际对比 | P2 | 1,500 | 1,050 |
| 第 10 章 趋势判断 | P1 | 2,100 | 1,470 |
| 第 11 章 结论与建议 | conclusion | 2,400 | 1,680 |
| **合计** | | **30,000** | **21,000** |
---
## 三、Phase 2 执行校验（dr-analyst/dr-pm 用）
## 四、Phase 2 执行校验
### dr-analyst 交稿前自检
dr-analyst 每章交稿前自检，dr-pm 每批校验。
```
章节完成后，执行：
1. wc -w projects/<slug>/phase2/drafts/chXX.md
（中文字数用 Python：sum(1 for c in text if '\u4e00' <= c <= '\u9fff')）
2. 对照 framework.md 的 "字数配额"：
- 实际 / 配额 < 0.7 → 不合格，继续挖掘
- 0.7 ≤ 实际 / 配额 < 0.85 → 警告，最好补足
- 0.85 ≤ 实际 / 配额 ≤ 1.3 → 合格
- 实际 / 配额 > 1.3 → 超纲，考虑拆分或精简
### 英文字数统计
```bash
# 英文词数
wc -w projects/<slug>/phase2/drafts/chXX.md
```
### dr-pm 汇总校验
### 中文字数统计（未来用）
Phase 2 结束时：
```
1. 统计全文字数：Σ(chXX.md 字数)
2. 对照 manifest.json 的 target_words：
- 如果 < 下限（10000/30000/20000/15000）→ ❌ 强制返工
- 在下限 ±5% → ⚠️ 需用户确认是否放行
- 超出下限 ≥ 10% → ✅ 合格
3. 写入 manifest.json 的 phase2.word_stats
```python
def count_chinese_words(text: str) -> int:
import re
cn = sum(1 for c in text if '\u4e00' <= c <= '\u9fff')
text_no_cn = re.sub(r'[\u4e00-\u9fff]', ' ', text)
en = len(re.findall(r"[A-Za-z]+(?:[-'][A-Za-z]+)*", text_no_cn))
return cn + en
```
### 不足时的补写策略（重要）
### 校验逻辑
**不要让 analyst 为凑字数注水！** 字数不足的应对顺序：
```
1. 读 chXX.md 统计英文词数
2. 对照 framework 中该章配额
3. 判断：
实际/配额 < 0.7 → 不合格，继续挖掘证据补写
0.7 ≤ 比值 < 0.85 → 警告，建议补足
0.85 ≤ 比值 ≤ 1.3 → 合格
比值 > 1.3 → 超纲，考虑精简或拆分
```
---
## 五、字数不足的正确补救路径
**绝对禁止为凑数注水**（"在此背景下"、"随着...的不断发展"等空话）。字数不足的应对顺序：
1. **检查证据覆盖**：该章观点是否有 ≥2 独立 Tier 1-2 信源？若无 → 检索补证据
2. **展开数据细节**：把表格里的数字展开成文字分析（趋势、拐点、对比）
3. **增加案例**：用 1-2 个具体公司/产品案例佐证抽象观点
4. **补反方证据**：把反方证据段落写详细（500-800 字）
5. **延伸推论**：对核心判断做 "若成立则..." 和 "若不成立则..." 分支讨论
5. **延伸推论**：对核心判断做"若成立则..."和"若不成立则..."分支
6. **国际对比**：若原文只讲中国，加一段国际对比
7. **实在不行**：和 dr-pm 商量是否拆/并章节
---
## 四、字数计算工具（中英混排）
```python
def count_chinese_words(text: str) -> int:
"""中英混排字数统计。中文字符 1 字，英文单词 1 字。"""
import re
chinese_count = sum(1 for c in text if '\u4e00' <= c <= '\u9fff')
# 去掉所有中文字符后，按空格切英文
text_no_cn = re.sub(r'[\u4e00-\u9fff]', ' ', text)
english_words = len(re.findall(r'[A-Za-z]+(?:[-\'][A-Za-z]+)*', text_no_cn))
return chinese_count + english_words
```
使用：
```bash
python3 -c "
import sys, re
with open(sys.argv[1]) as f:
text = f.read()
cn = sum(1 for c in text if '\u4e00' <= c <= '\u9fff')
en = len(re.findall(r'[A-Za-z]+(?:[-\'][A-Za-z]+)*', re.sub(r'[\u4e00-\u9fff]', ' ', text)))
print(f'中文字数: {cn}, 英文词数: {en}, 总计: {cn+en}')
" projects/<slug>/phase2/drafts/ch01.md
```
### 不计入字数的部分
- 代码块 ```...```
- Markdown 表格线框（|---|）
- 引用块 `> `
- 标题的 `#` 符号
- 链接的 URL（`[文字](url)` 只计文字部分）
---
## 五、manifest.json 字段规范
## 六、manifest 字段规范
```json
{
"slug": "glp1-obesity-2026",
"topic": "GLP-1 减重药物竞争格局与投资机会",
"type": "研究类",
"target_words": 35000,
"min_words": 30000,
"chapters_planned": 11,
"phase1": {
"approved": true,
"approved_at": "2026-04-20T10:00:00Z",
"framework_path": "projects/glp1-obesity-2026/phase1/framework.md",
"chapter_quotas": [
{"index": 1, "title": "...", "quota": 2100, "priority": "intro"},
{"index": 2, "title": "...", "quota": 5250, "priority": "P0"},
...
]
},
"phase2": {
"started_at": "...",
"progress": "7/11",
"chapters": [
{
"index": 1,
"draft_path": "projects/.../drafts/ch01.md",
"actual_words": 2180,
"quota": 2100,
"status": "completed",
"sources_count": 12,
"tbd_claims": 0
}
],
"word_stats": {
"total": 34820,
"target": 35000,
"gap_pct": -0.5,
"verdict": "合格"
}
}
"word_budget_mode": "detailed",
"target_words_zh": 30000,
"target_words_en": 21000,
"min_words_zh": 24000,
"chapter_quotas_en": [
{"index": 1, "title": "...", "en_words": 1260, "priority": "intro"},
{"index": 2, "title": "...", "en_words": 3150, "priority": "P0"}
]
}
```
---
## 六、硬规则总结
## 七、Phase 4 翻译后中文字数校验
1. ✅ 综述 ≥10,000 字；研究 ≥30,000 字；投资 ≥20,000 字；管理 ≥15,000 字
翻译完成后：
1. 读 final_zh.md，按中英混排规则统计字数
2. 对照 manifest.target_words_zh
3. 落在 ±15% 区间内 → 合格
4. 不合格 → dr-polisher 在润色时适度扩展/压缩
---
## 八、硬规则
1. ✅ auto 模式按类型默认，其他模式按用户选择
2. ✅ 章节字数差距 ≤ ±30%
3. ✅ 每 section ≥800 字
4. ✅ 结论章 ≥ 全文 10%
5. ✅ Phase 2 每章完成自检字数
6. ✅ 不足下限强制返工
7. ❌ 禁止为凑字数注水（空洞形容词、套话、重复表述）
8. ❌ 禁止"打折"交稿
3. ✅ 结论章 ≥ 全文 10%
4. ✅ Phase 2 英文稿每章自检，不足 70% 配额必须补
5. ✅ Phase 4 中文稿整体字数校验在 ±15% 内
6. ❌ 禁止为凑数注水（AI 套话、重复表述）
7. ❌ 禁止对字数"打折"交稿
.opencode/skills/mckinsey-method/SKILL.md
+142 -98
View File
@@ -1,133 +1,177 @@
---
name: mckinsey-method
description: 麦肯锡报告写作方法论。MECE 原则、SCQA 叙事结构、金字塔原理、"每个标题即一个观点"规则，以及 So What? 自检机制。dr-analyst 撰写初稿、dr-polisher 润色、dr-chief-editor 审校时必须遵循。
description: 顶级咨询公司（麦肯锡/BCG/德勤）研究报告写作方法论。金字塔原理、MECE、观点型标题、证据-数据-案例三要素、So What 自检。SCQA 仅用于 Executive Summary 和各章引入段，严禁每节机械套用。所有写作类 agent（dr-analyst/dr-editor-in-chief/dr-polisher）必读。
---
# 麦肯锡报告写作方法论
# 顶级咨询报告写作方法论（精炼版）
## 一、MECE 原则（章节划分的铁律）
## 核心定位
**Mutually Exclusive, Collectively Exhaustive** — 互斥且穷尽。
### 章节划分自检
写完章节大纲后，逐一检查：
**互斥性**（每章内容不重叠）：
- 如果读者读完第 3 章，再读第 5 章，会不会觉得"刚才好像说过这个"？
- 如果是，说明两章有重叠，需要合并或重划边界
**穷尽性**（所有重要维度都覆盖）：
- 用同一个分析框架列出所有应该涵盖的维度
- 对照框架，检查有无遗漏
- 常用框架：
- 市场分析：需求侧 / 供给侧 / 竞争格局 / 监管环境
- 技术分析：技术原理 / 临床验证 / 产业化路径 / 壁垒
- 投资分析：市场空间 / 竞争壁垒 / 财务模型 / 风险
本文档是报告写作的**唯一风格准则**。读过 9MW1911 综合战略报告吗？那是目标风格。读起来像咨询公司资深合伙人在跟董事会讲话，不像 AI 生成的综述。
---
## 二、SCQA 叙事结构（每章开头）
## 一、金字塔原理（Pyramid Principle）
每个 chapter 和重要 section 的第一段，用 SCQA 引入：
**结论先行，论据支撑，论据之间 MECE。**
| 要素 | 作用 | 字数 |
|---|---|---|
| **S (Situation)** | 描述当前已知的背景事实（读者已接受的） | 1-2 句 |
| **C (Complication)** | 引入打破现状的张力或挑战 | 1-2 句 |
| **Q (Question)** | 由此引发的核心问题（可以是隐含的） | 1 句 |
| **A (Answer)** | 本章/section 的核心结论（先行答案） | 1-2 句 |
```
章标题（= 一句判断）
↓
章首 2-3 段：直接给出本章结论 + 核心逻辑
↓
节 2.1（= 支撑论点 1）
节首 1 段：本节论点 + 核心证据
数据/事实/案例（带 [src_xxx]）
So What：这意味着什么
↓
节 2.2（= 支撑论点 2）
...
```
**示例（好的）**：
> GLP-1 受体激动剂已成为 2 型糖尿病的一线治疗选择，市场规模超过 200 亿美元[src_001]。然而，近期临床数据显示停药后体重反弹率高达 60%，挑战了其"长期治疗"的市场定位[src_002]。这一现象促使我们深入思考：GLP-1 药物究竟是一次性干预还是慢性病长期管理工具？本章认为，**GLP-1 的市场叙事正在从"减重药"向"代谢疾病管理平台"强制转型**，这一转型的成败将决定未来 5 年的市场格局。
**章标题即判断**（强制）：
- ✗ "第 2 章 市场现状"
- ✓ "第 2 章 中国 GLP-1 市场 2025 年已跨越 10 亿美元门槛，增速仍在加速"
**示例（差的）**：
> 本章将介绍 GLP-1 受体激动剂的基本情况，包括其作用机制、临床数据和市场前景。
**节标题即子判断**（强制）：
- ✗ "2.1 竞争格局"
- ✓ "2.1 双寡头格局将在 3 年内被国产厂商打破"
---
## 三、金字塔原理（段落结构）
## 二、SCQA 的正确使用（关键纠正）
**结论先行，证据支撑。**
**SCQA 不是每章每节都套的格式，是整份报告的开篇叙事工具。**
### 允许使用的位置（仅以下三处）
1. **Executive Summary 开头**（最重要）：用 SCQA 引出报告核心命题
2. **第 1 章引言**：用 SCQA 建立整份报告的分析框架
3. **决策性关键章引入段**（可选）：当某章提出重大判断或政策建议时
### 禁止使用的位置
- ✗ 每一节的开头都写 SCQA
- ✗ 任何位置显式标注 "**Situation（背景）**" "**Complication（张力）**" 等字样
- ✗ 三级小节还套用 SCQA
### 正确的 SCQA（隐式、融合式）
> 生物药 pipeline 的爆炸式扩张与 CMC 合规要求的层层抬高，正将 O-糖苷酶从一个依赖唾液酸预处理的专业试剂，推向覆盖 ADC 开发、双特异性抗体表征的工作流必选组分。然而，30 年来主导市场的 NEB 经典产品，对唾液酸化底物无活性这一根本局限始终未被突破。这就引出了一个核心问题：当下一代工程酶在 2019-2024 年集中商业化、市场标准正在重构时，后来者的进入窗口是否真实存在？本报告认为，窗口存在，但持续时间不超过 36 个月。
（这段里有 S/C/Q/A 四个要素，但没有任何显式标注，读起来像一段自然的论述。）
### 错误的 SCQA（显式标注式）
> **Situation（背景）**：生物药 pipeline 扩张...
> **Complication（张力）**：NEB 经典产品局限...
> **Question（问题）**：窗口是否存在？
> **Answer（答案）**：本章认为...
（这种写法是典型的 AI 套路，在最终报告里绝对禁止出现。）
---
## 三、MECE（章节划分铁律）
**Mutually Exclusive, Collectively Exhaustive — 互斥且穷尽。**
自检：
- 如果读者读完第 3 章再读第 5 章，会不会觉得"刚才好像说过这个"？有 → 合并或重划
- 对照分析框架列出所有应覆盖的维度，有遗漏 → 补章节
常用框架：
- 市场：需求侧 / 供给侧 / 竞争格局 / 监管环境
- 技术：原理 / 验证 / 产业化 / 壁垒
- 投资：市场空间 / 竞争壁垒 / 财务模型 / 风险
---
## 四、观点 + 证据的写作单元
每个段落的标准结构：
```
顶层：章节核心结论（标题即观点）
├── 支撑论点 1 → 数据/事实/案例
├── 支撑论点 2 → 数据/事实/案例
└── 支撑论点 3 → 数据/事实/案例
```
**纵向深入**：每个支撑论点都有更细的数据支撑。
**横向 MECE**：同层支撑论点之间互斥且穷尽。
### 段落写法模板
```
[结论句] 具体发现/判断。
[证据 1] 根据 <来源>，<数据/事实> [src_xxx]。
[论点句] 具体判断，1 句话。
[证据 1] 根据 <具体来源>，<数据> [src_xxx]。
[证据 2] 进一步，<案例/对比> [src_xxx]。
[So What] 因此，<对上层论点的意义>。
[So What] 这意味着 <对上层论点的意义>。
```
---
### 数据引用规范
## 四、标题即观点（强制规则）
**每一个 chapter 和 section 的标题必须是一个完整的判断句，而不是描述词。**
### 反例 vs 正例
| 反例（禁止） | 正例（要求） |
| 类型 | 写法示例 |
|---|---|
| 第 2 章 GLP-1 药物概述 | 第 2 章 GLP-1 的减重机制正在重塑代谢疾病的治疗范式 |
| 3.1 市场现状 | 3.1 中国 GLP-1 市场 2025 年已跨越 10 亿美元门槛，且增速仍在加速 |
| 4.2 竞争分析 | 4.2 诺和诺德与礼来的双寡头格局在 3 年内将被国产厂商打破 |
| 5.1 风险因素 | 5.1 医保覆盖缺失是 GLP-1 市场扩张的最大结构性瓶颈 |
| 市场规模 | "120 亿美元（2024 年）[src_042]" |
| 增长率 | "CAGR 23%（2023-2030）[src_018]" |
| 临床数据 | "OS 改善 23%（95% CI: 13.8-16.6，p<0.001，N=1,200）[src_007]" |
| 成功率 | "FDA 获批率 41%（N=127 项 NDA，2020-2024）[src_033]" |
**判断标准**：能不能把标题变成一个"对/错"或"同意/不同意"的命题？能则合格。
### 禁止写法
---
## 五、So What? 自检机制
每写完一个段落，问自己：**"所以呢？这对读者有什么意义？"**
- 如果答案是"没什么意义，只是客观描述"→ **要么删，要么补充 So What 句**
- So What 句通常放在段尾，1-2 句，明确点出这段内容对上层论点的贡献
**So What 句示例**：
- "这意味着，先发厂商在 2026 年之前建立的渠道优势将难以被后来者复制。"
- "因此，判断一个 GLP-1 管线的商业价值，给药频率比疗效终点更关键。"
- "上述趋势表明，当前的估值逻辑低估了国产厂商的长期竞争力。"
---
## 六、数据引用规范
| 类型 | 写法 | 示例 |
|---|---|---|
| 市场规模 | X 亿/XX 亿美元（YYYY 年）[src_xxx] | 120 亿美元（2024 年）[src_042] |
| 增长率 | CAGR XX%（YYYY-YYYY）[src_xxx] | CAGR 23%（2023-2030）[src_018] |
| 临床数据 | XX%（95% CI: X-X，p<0.001）[src_xxx] | 体重降低 15.2%（95% CI: 13.8-16.6，p<0.001）[src_007] |
| 成功率 | XX%（N=XXX）[src_xxx] | FDA 获批率 41%（N=127 项 NDA，2020-2024）[src_033] |
**禁止写法**：
- "市场规模巨大" → 必须写具体数字
- "研究表明" → 必须写是哪项研究（来源 ID）
- "近年来" → 必须写具体年份
- "有专家认为" → 必须写哪位专家（或删去该措辞，用数据代替）
- "有专家认为" → 必须写哪位专家（或删去，用数据代替）
---
## 七、常见 AI 写作坏习惯（一键检索）
## 五、So What 自检（每段都做）
润色或审校时，全文搜索以下词汇，逐一判断是否需要改写：
每写完一段，问自己："所以呢？这对读者有什么意义？"
```
随着 | 不断 | 深入 | 值得注意 | 不难发现 | 显而易见
具有重要意义 | 发挥重要作用 | 显著 | 巨大 | 快速发展
在此背景下 | 综上所述 | 由此可见 | 总的来说
据报道 | 有研究表明 | 专家指出
```
- 答案是"只是客观描述" → **要么删，要么补 So What 句**
- So What 句通常放段尾，1-2 句，明确点出这段内容对上层论点的贡献
每个命中项，问：有数据支撑吗？能删吗？能改得更具体吗？
示例：
- "这意味着，先发厂商在 2026 年之前建立的渠道优势将难以被后来者复制。"
- "因此，判断一个 GLP-1 管线的商业价值，给药频率比疗效终点更关键。"
---
## 六、报告整体结构（11 件套）
参考 9MW1911 综合战略报告的组织方式：
1. **封面**：主标题 + 副标题 + 保密标识 + 编制日期
2. **Executive Summary / 执行摘要**（≈800 字）：SCQA 开篇 + 核心结论 4 条 + 关键行动优先级
3. **Abstract / 摘要**（500-600 字）：独立一页，叙事式，面向广义读者
4. **Glossary / 术语表**（双语对照）
5. **Table of Contents / 目录**
6. **正文章节**（8-15 章）
7. **结论与建议章**
8. **附录**（2-5 个，如 CMC、临床对比、合并症分析）
9. **参考文献**（[src_xxx] 编号格式）
10. **免责声明**
11. **版本信息**
---
## 七、章节写作 Checklist（每章完成后自检）
- [ ] 章标题是观点型判断，不是"概述/现状/背景"
- [ ] 章首 2-3 段给出结论和逻辑
- [ ] 各节互斥且穷尽（MECE）
- [ ] 每节标题也是观点型判断
- [ ] 每个数字/事实后接 [src_xxx]
- [ ] 每段末尾有 So What 句
- [ ] 没有显式标注 "S/C/Q/A"
- [ ] 没有"巨大/快速/显著/强劲"等无数据形容词
- [ ] 没有"本章定位/字数配额/研究员"等调度元数据
- [ ] 没有占位符 [待验证]（除非确实找不到第二个信源）
---
## 八、严禁出现的写作坏习惯（humanizer 已列，此处精简）
**AI 套话**：随着、不断、深入、值得注意、不难发现、显而易见、具有重要意义、发挥重要作用、显著、巨大、快速发展、在此背景下、综上所述、由此可见、总的来说
**规避 "是" 的冗余结构**（AI 高频）：标志着 / 代表着 / 构成 / 成为 / 跃升为 → 直接用 "是"
**三段式堆砌**：不要为凑数硬拼"需求侧 / 供给侧 / 政策侧"、"短期 / 中期 / 长期"
**破折号过用**：长破折号每章不超过 3 处
**负向平行**：不要"不仅...更..."、"不是...而是..."（偶用可，成段出现不可）
完整规则见 `skill:humanizer-cn`。
.opencode/skills/output-hygiene/SKILL.md
+238
View File
@@ -0,0 +1,238 @@
---
name: output-hygiene
description: 报告输出卫生检查。禁止词清单（调度元数据、占位符残留、待验证标注）、格式异常检测、参考文献完整性校验。dr-polisher 在润色最后一步必跑；dr-reporter 出稿前复查一次。
---
# 输出卫生清单（Output Hygiene Checklist）
## 目的
拦截"调度元数据"和"中间产物残留"进入最终报告。9MW1911 那份报告之所以干净，是因为过滤掉了一切过程性内容，只留最终成品。
---
## 一、禁止出现在最终报告正文中的字样（元数据黑名单）
以下字符串在 final.md / final_zh.md / final_en.md 里**一旦出现即为缺陷**，dr-polisher 必须清除：
### A. 调度元数据
- `章节定位`
- `字数配额`
- `研究员：dr-analyst`
- `研究员：dr-searcher`
- `生成时间：2026-`（Year-MM 生成日期只在版本信息页出现一次）
- `P0 核心章` / `P1` / `P2`（这些是内部分级，不给读者看）
- `dr-plan` / `dr-pm` / `dr-analyst` / `dr-verifier` / `dr-chief-editor` / `dr-editor-in-chief` / `dr-polisher` / `dr-reporter` / `dr-translator`
- `Phase 1` / `Phase 2` / `Phase 3` / `Phase 4`（除非在"方法论说明"附录讨论研究流程时）
### B. 占位符残留
- `[由 dr-reporter 自动生成]`
- `[待填]` / `[TBD]` / `[TODO]`
- `<slug>` / `<topic>` / `<N>` / `<X>` 等模板占位符
- `{{ ... }}` / `${...}` 变量语法残留
### C. 中间产物引用
- `参考信源：[src_101] –[src_120] （详见 sources.jsonl ch02 条目）`
- `详见 phase2/evidence/chXX-evidence.md`
- `详见 sources.jsonl`
- `本章信源索引：...（详见 ...）`
- `⚠️ 待验证` / `⚠️ [待验证]`（这是过程性标注；如必须保留某个"存疑观点"的提示，应改为正式语言如"该数据仅有 X 个来源支持，建议人工核实"）
### D. 研究思路泄漏
- `研究思路：`
- `核心研究问题：`
- `初步假设：`
- `预期信源：`
- `预期篇幅：`
这些是 framework.md 里给 dr-analyst 看的规划信息，不能出现在读者版。
### E. Agent 交付汇报语
- `产出：` / `完成后返回：`
- `任务：` / `硬性要求：`
- `必读 skill：`
- `章节小结：` （改为自然段落收尾）
---
## 二、格式异常检测
### F. SCQA 显式标注（已禁止的机械模式）
以下组合**不应在最终报告中成对出现**（用 grep 扫）：
- `**Situation（背景）**` + `**Complication（张力）**`
- `**S（背景）**` + `**C（挑战）**` + `**Q（问题）**` + `**A（答案）**`
- `Answer-First` 显式标注
- `**核心结论（Answer-First）**`
SCQA 要写得隐式融合（见 mckinsey-method skill）。
### G. 三级以上嵌套标题乱用
正文正式章节标题不要超过 3 级：
- `# 第 X 章` （报告级）
- `## X.Y 节` （章内节）
- `### X.Y.Z 小节` （节内小节）
禁止 `####` `#####` `######`。如果需要 4 级以上，重新组织结构。
### H. 引用格式不统一
所有引用统一 `[src_XXX]` 格式（3 位数字）。禁止混用：
- `[src_1]`（没补零）
- `[source_001]`（变形）
- `(src_001)`（圆括号）
- `[ref_1]` / `[r1]`（其他简写）
### I. 中英文标点混用
中文正文里的标点应是**中文标点**：
- `，` 不是 `,`
- `。` 不是 `.`
- `；` 不是 `;`
- `：` 不是 `:`
- `"..."` 不是 `"..."`（除了直接引用英文）
- `（...）` 不是 `(...)`
例外：行内英文术语、代码、URL、数据单位前后保持英文标点合理。
---
## 三、参考文献完整性校验（最关键）
dr-reporter 出稿前**必须**执行：
```bash
# 1. 从 final.md 提取所有引用的 src_id
grep -oE '\[src_[0-9]+\]' projects/<slug>/phase4/final.md | sort -u > /tmp/cited.txt
# 2. 从 citations.md / sources.jsonl 提取所有已登记的 src_id
grep -oE 'src_[0-9]+' projects/<slug>/phase4/citations.md | sort -u > /tmp/registered.txt
# 或从 sources.jsonl
python3 -c "
import json
with open('projects/<slug>/phase2/sources.jsonl') as f:
for line in f:
d = json.loads(line)
print(d['id'])
" | sort -u > /tmp/registered.txt
# 3. 差集：cited 里有但 registered 里没有 → 严重错误
comm -23 /tmp/cited.txt <(sed 's/[][]//g' /tmp/registered.txt) > /tmp/missing.txt
# 4. 反向差集：registered 有但从未被 cited → 孤立信源，可剔除
comm -13 /tmp/cited.txt <(sed 's/[][]//g' /tmp/registered.txt) > /tmp/orphan.txt
```
### 处理规则
- 有 missing 信源（引用了但无记录）→ **致命错误**，dr-reporter 拒绝出稿，抛回上游排查
- 有 orphan 信源（有记录但未被引用）→ 警告，从 citations.md 剔除
- final.md 里的"参考文献"段落**必须包含完整的编号清单**，不能是 `[由 dr-reporter 自动生成]` 之类的占位符
- 如果 final.md 的参考文献段落是占位符 → 读 citations.md 内容回填
---
## 四、标题规范
### 章标题
- 观点型判断句，不是"概述/现状/背景"
- 长度 15-40 字（中）/ 10-25 词（英）
- 不以动词开头（如"分析/探讨/研究"），改为判断句
**反例**：
- 第 2 章 分析中国 GLP-1 市场的现状
- 第 3 章 探讨 NEB 产品的竞争优势
**正例**：
- 第 2 章 中国 GLP-1 市场 2025 年已跨越 10 亿美元门槛
- 第 3 章 NEB 的 30 年专利丛林将在 2028 年后开始瓦解
### 节标题
- 同样要求观点型
- 长度 10-25 字 / 8-15 词
- 禁止 `2.1 背景 / 2.2 现状 / 2.3 趋势` 这种模板化结构
---
## 五、图表与数据卫生
### 表格
- 表头第一行要有单位（金额 USD / 百分比 % / 年份等）
- 所有数据有来源标注（行内 [src_xxx] 或表脚注）
- 避免超过 10 列宽表（PDF 会被截断）
### 图表标题
格式：`图 X-Y：<内容描述>（数据来源：[src_xxx]）`
### 数字规范
- 阿拉伯数字 + 中文量词：`12 项研究` / `3.2 亿元`
- 大数字三位分节：`12,000` 而非 `12000`
- 百分比带 `%`，不写"百分之十二"
- 时间范围用连字符：`2020-2025 年` 不是 `2020 至 2025 年`
---
## 六、自动化检查脚本（dr-polisher / dr-reporter 必跑）
```python
# hygiene_check.py
import re, sys
BLACKLIST_ZH = [
"章节定位", "字数配额", "研究员：dr-",
"P0 核心章", "P1 主干章", "P2 辅助章",
"Phase 1", "Phase 2", "Phase 3", "Phase 4",
"dr-plan", "dr-pm", "dr-analyst", "dr-verifier",
"dr-chief-editor", "dr-editor-in-chief", "dr-polisher",
"dr-reporter", "dr-translator",
"[由 dr-reporter 自动生成]", "[待填]", "[TBD]", "[TODO]",
"详见 phase2/", "详见 sources.jsonl",
"本章信源索引", "⚠️ 待验证", "⚠️ [待验证]",
"**Situation（背景）**", "**Complication（张力）**",
"**Question（问题）**", "**Answer（答案）**",
"**S（背景）**", "**C（挑战）**",
"Answer-First", "核心结论（Answer-First）",
"研究思路：", "核心研究问题：", "初步假设：",
"预期信源：", "预期篇幅：",
"硬性要求：", "必读 skill：", "产出：",
]
path = sys.argv[1]
text = open(path, encoding='utf-8').read()
issues = []
for pattern in BLACKLIST_ZH:
if pattern in text:
count = text.count(pattern)
issues.append(f" × '{pattern}' 出现 {count} 次")
if issues:
print(f"{path} 存在 {len(issues)} 项卫生问题：")
for i in issues:
print(i)
sys.exit(1)
else:
print(f"{path} 输出卫生检查通过")
sys.exit(0)
```
---
## 七、硬规则
1. ✅ dr-polisher 润色的最后一步跑 hygiene_check
2. ✅ dr-reporter 出稿前再跑一次 hygiene_check + 参考文献完整性校验
3. ✅ 任何禁止词残留都必须修正，不能"放过一马"
4. ✅ 参考文献段落必须包含完整编号清单，不允许占位符
5. ❌ 禁止把"⚠️ 待验证"这种过程标注留到读者版
6. ❌ 禁止三级以上嵌套标题
.opencode/skills/pdf-reportlab/SKILL.md
+211 -163
View File
@@ -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 再润色一轮。