report-writing

# 报告类 Word 文档写作 skill > **一句话定位**：把已经成立的事实（分析结果 / 流程 / 进展）写成读者一眼能用、看不出 AI 痕迹的专业中文报告 docx。 > 报告 ≠ 论文：论文为审稿人证明严谨，报告为读者快速决策与执行服务。 --- ## 〇、铁律（每次生成都适用，违反 = 未完成） 1. **数据有源、零编造、单源取数**：所有数字（样本量、估计值、CI、P、百分比、日期、金额）必须取自项目结果文件 （`07_paper/results.yaml` 机器单源 / 其派生 `0_result_summaries.md`、`03_tables/` 导出表或用户明确给的来源）， 逐字一致、不四舍五入到与源不符。脚本化生成时用 `build_report.py` 的 `val("07_paper/results.yaml", "key")` 取数， **禁止手敲数字**（"禁手敲"指数字须经 `val()` 从单源取以保持同步，**不是禁止阿拉伯数字**——统计值一律用阿拉伯数字、按各自精度呈现，NEVER 为规避而虚化成中文数字如"零点四四"）。源里没有的 → 标 `[待确认]`，不要瞎填。**双向一致性**：改数字回 results.yaml 改再传播，NEVER 就地改。 2. **学术书面语**：研究者/执行者视角（"本报告/我们完成了 X"），不用口语、网络词、AI 助手腔（"我建议你…""让我们…"）。 标题用名词短语、不用反问；英文缩写首次出现给全称。 3. **零 AI 痕迹与零 emoji**：不堆开场闭场套话、不用 emoji / emdash、不出现 AI 工作痕迹字样 （AI辅助 / assistant / 待人工复核 等）。中文文风过 `humanizer-zh` 的反 AI 黑名单意识。 4. **正文以完整段落叙述为主（核心铁律）**：分析 / 结果 / 讨论 / 结论一律写成连贯的成段散文，像真实统计报告一样把数字 织进句子里逐一解读（"S2 组调整后变化为 1.24 kg（95%CI：0.21，2.26），组内 *P* = 0.019，提示…"）。 **NEVER** 把正文写成"点点点"项目符号清单（一连串 `- xxx` / `• xxx` 短句堆叠 = 报告不合格）。项目符号只允许用于 极少数真正并列的离散项（如分步操作 SOP、勾选清单、纯枚举），且连续不超过一组；凡是带因果 / 解读 / 对比的内容， 一律成段。执行摘要可用"加粗标签 + 整句"的短段，不用点。 5. **图表自动入文（核心铁律）**：报告涉及的数据，凡 `03_tables/`（xlsx）有对应表就**读取并作为三线表插入正文**、 凡 `04_figures/` 有对应图就**作为图片嵌入正文**，不要只在文字里描述"见表 X / 如图所示"而不放实际表图。 表题在表上方、图题在图下方，编号按行文顺序连续。无现成表图时按 `publication-figures` / `xlsx` 规范现做再插。 6. **默认双格式输出（核心铁律）**：每次生成报告**同时产出 `.md` 与 `.docx` 两个版本**（同名、同目录、内容一致）， 除非用户明确只要其中一种。md 供快速预览 / 版本管理，docx 为正式交付件。 7. **结论先行**：报告开头先给最重要的结论 / 要点 / 行动项，再展开依据。读者读前 1/4 就应抓住核心。 7bis. **结果/统计报告写成论文体，不暴露工程过程（核心铁律）**：结果类 / 统计分析报告面向读者，**NEVER** 写 "代码在 `02_code/`""详见 DECISIONS.md""方法决策记录在…""所有脚本/文件在…""基于 xx.R"之类的工程内部痕迹—— 这些是内部审计内容，不进交付报告。方法节只写中性可复现的最终口径（用了什么模型/检验/校正），像论文的 Methods， 不提脚本名、文件路径、决策记录、版本、调参。**例外**：报告本身就是"基于某些文件的说明/操作指引/文档类" （如填写指南、流程说明、代码文档），这类才按需引用具体文件。判据：统计结果报告 = 论文式，不谈代码与文件归档。 8. **疑点先问**：读者对象 / 报告目的 / 关键口径 / 结论方向不明 → 先问用户，不擅自定调（同 CLAUDE.md §5）。 9. **局部修改也走完整标准**：哪怕只改一段，动后按 §五自检清单复扫，确保与全文术语、口径、编号一致。 --- ## 一、报告 ≠ 论文（写之前先认清差别） | 维度 | 论文（academic-publishing） | 报告（本 skill） | |---|---|---| | 读者 | 审稿人、同行 | 决策者、客户、团队、执行人 | | 目的 | 证明结论可信、可发表 | 让读者快速理解并据以行动 | | 结构 | IMRaD 固定、参考文献规范 | 灵活，按"读者需要先知道什么"组织 | | 开头 | 背景铺垫 → 逐步推进 | 执行摘要 / 结论先行 | | 语气 | 客观克制、回避主观 | 客观但更直接，可给明确建议 | | 篇幅取向 | 完整论证 | 抓重点、去冗余、可要点化 | | 引用 | 严格文献规范 | 注明来源即可，不强求文献格式 | 报告仍要：数据有源、书面语、零 AI 痕迹、零编造——这几条与论文一致，不放松。 --- ## 二、报告结构（按报告类型取用，不必全有） **通用骨架**（按需裁剪、重排）： 1. **标题页 / 抬头**：报告名（名词短语）、副标题、日期、版本 / 编制方（可选）。 2. **执行摘要 / 核心要点**（多数报告必备）：3–6 条，给最重要的结论、数字、行动项。读者只读这一段也不致误判。 3. **背景 / 目的**：为什么有这份报告、要解决什么问题、范围边界。 4. **方法 / 过程**（分析或操作类报告）：做了什么、依据什么标准。简明，不展开论文级细节。 5. **结果 / 发现**：核心内容。按主题分节，每节"先结论后依据"，配表 / 图 / 要点。 6. **建议 / 行动项**（决策类报告）：可执行步骤，必要时给"谁、何时、按什么标准"。 7. **附录**：明细表、原始数据指引、术语表、参考资料。 **按类型选骨架**： - 分析 / 结果报告：执行摘要 → 背景目的 → 方法 → 发现（分主题）→ 结论建议 → 附录。 - 进展 / 工作报告：核心要点 → 已完成 → 进行中 → 待办与风险 → 下一步。 - 操作指南 / 手册（如填写指南、SOP）：用途与适用对象 → 核心概念 → 分步操作 → 结果解读 → 注意事项 / 常见问题。 - 说明 / 备忘：结论先行 → 关键事实 → 影响 → 需对方决策的点。 --- ## 三、写作风格 - **完整段落为默认体例（最重要）**：正文以连贯散文成段写，把数字、估计值、CI、P 值、方向解读织进句子里逐句展开， 参照真实统计报告的笔法（见 §四之"参照范式"）。**默认不用项目符号**；只有分步操作、纯枚举清单、勾选项才用点， 且一组不超过 5–7 项。判断"这段能不能成段"：凡含因果 / 对比 / 解读 / 推论 → 必成段，不许拆成短句点列。 - **结论先行**：每个章节、每个段落都先给判断 / 结论，再给支撑。避免"铺垫半页才到重点"。 - **一节一主题**：标题用名词短语点明该节结论（"低体重提示更差预后"优于"关于低体重的分析"）。 - **数据贴着解读走**：每报一个数就跟一句它意味着什么（"较 S1 平均少 1.82 kg，差异达统计学显著"），不堆裸数字。 - **可操作**：行动类内容动词开头写步骤（"核对…""填写…""提交…"），给明确判定标准而非含糊形容。 - **量化优先**：能给数字就给数字并注来源；避免"较多 / 明显 / 大幅"等无依据修饰。 - **读者语言**：少用内部变量名 / 脚本名 / 调参过程；必要的专业术语首次出现给一句解释。 - **专业中性、不哄读者**：标题与标签用中性名词，不用照顾式 / 哄人式措辞。禁用"（先读这一段）""一句话任务""本指南教你…""手把手""必须先弄清""三个你要知道的…"等预设读者水平、口语化的说法——直接写"核心要点""概念""范围""任务"即可。把读者当专业同行。 --- ## 四、docx 排版规范（程序生成，统一用 python-docx） **参照范式**：成稿的视觉与文风对标一份真实统计咨询报告——居中加粗多行标题、中文数字章节（一、二、三…）+ `4.1/4.2` 子节、全段落叙述、三线表、表上图下题注、统计符号斜体。**没有任何灰色说明小字，没有"点点点"清单。** **字体（中英分设，必须设 eastAsia；这是用户硬要求）**：正文 **中文宋体 / 英文 Times New Roman** 10.5–12pt； 标题用黑体（或微软雅黑）加粗；一级标题 14–16pt、二级 13pt、三级 11–12pt。中文统一一种字体，不混用。 **每个 run 都要同时设 `font.name`（英文）与 `w:eastAsia`（中文）**，否则英文数字会回退成宋体、中文会变默认西文字体。 ```python from docx.oxml.ns import qn from docx.shared import Pt, RGBColor def setfont(run, cn="宋体", en="Times New Roman", size=10.5, bold=False, italic=False, color=(0,0,0)): run.font.size = Pt(size); run.font.bold = bold; run.font.italic = italic run.font.name = en # 英文/数字字体 run._element.rPr.rFonts.set(qn("w:eastAsia"), cn) # 关键：中文 eastAsia 字体 run.font.color.rgb = RGBColor(*color) # 默认纯黑 ``` **标题页（重点修复"标题下灰色小字"问题）**： - 标题为居中、加粗的名词短语，长题可拆成多行居中（每行一段，均加粗）。 - **标题下严禁出现灰色 / 浅色的说明性小字**（如"本报告由…生成""说明：…""副标题解说"之类）。 标题区只允许出现：标题本身，以及（可选）日期 / 版本 / 编制方——且一律**纯黑、正常字号**，不灰、不缩小、不加解说句。 - 不要自动塞入用途说明、生成方式、免责声明等冗余抬头；这些内容用户没要就不写。 **正文版式**： - 章节标题用中文数字编号（一、二、三…），子节用 `4.1`、`4.2`；**正文 1.5 倍行距、首行缩进 2 字符**（论文式，`build_report.py` 的 `para()` 已内置）；段后 3–6pt，不靠空行撑版面。标题/题注/执行摘要标签段不缩进。 - 统计符号斜体：`P`、`vs`、`t`、`F`、`r`、`n`（变量符号）等用 *斜体*；单位（kg、%）和"95%CI"正体。 - **正文以段落为主，禁止把结果写成项目符号清单**（见 §〇.4 / §三）。执行摘要可用"**加粗标签**＋整句"短段。 **表格（三线表，自动从数据生成）**： - 三线表：顶线 / 表头下线 / 底线，**无竖线、无内部横线**；表头加粗，文字左对齐、数字右对齐； **所有单元格垂直居中**（`cell.vertical_alignment = WD_CELL_VERTICAL_ALIGNMENT.CENTER`）。 - **自动取数入表**：优先读 `03_tables/` 对应 xlsx（用 `xlsx`/openpyxl 读单元格）填入三线表，不要手敲数字另起炉灶； 无现成 xlsx 时据 `0_result_summaries.md` 构表。表题在表**上方**（"表1 …"），必要时表下加一行斜体小号注。 **图片（自动嵌入）**： - **自动嵌图**：报告涉及的图，从 `04_figures/` 取对应 PNG 用 `doc.add_picture(path, width=Inches(...))` 嵌入正文， 居中，宽度约占版心（通常 5.5–6.5 in）。图题在图**下方**（"图1 …"）。无现成图时按 `publication-figures` 现做再插。 - **全文字体一律黑色**（标题、正文、表头、注释一律纯黑 #000000）；**不用彩色字、不用灰字**；层级靠字号与加粗区分，不靠颜色。**禁止 emoji、禁止彩虹色、禁止默认灰底。** **硬禁止**：标题下灰色说明小字；正文"点点点"清单；emoji；emdash 当连接号；口语 / 网络词；AI 痕迹字样；无来源的"最佳 / 显著 / 证明"。 --- ## 五、生成流程与自检清单 **构建助手**：排版统一用 `references/build_report.py`（`Report` 类）——已封装中文宋体/英文 Times New Roman（每 run 设 eastAsia）、 干净标题页（无灰字）、三线表、`table_from_xlsx()` 自动取数、`figure()` 嵌图、统计符号斜体、`save(..., also_md=True)` 同时落 md+docx。 内容仍须按铁律手写传入，助手只保证排版正确。 **流程**：定读者与目的 → 选骨架（§二）→ 取数（铁律 1）→ 收集要插的表（`03_tables/` xlsx）与图（`04_figures/` png） → 逐节"结论先行 + 完整段落"写，把数与图表引用织进正文 → 套排版（§四，宋体/Times、三线表、表上图下、统计符号斜体） → **同时生成 `.md` 与 `.docx`** → 自检 → 交付时先报告"已自检项"。 **完成前自检（不等用户挑错）**： - [ ] **同时产出 .md 与 .docx**（同名同目录、内容一致） - [ ] **正文为完整段落叙述，无"点点点"项目符号清单**（仅 SOP/纯枚举处少量用点） - [ ] **该有的表已作为三线表插入、该有的图已嵌入正文**（非仅文字"见表/见图"）；表取自 `03_tables/` xlsx、图取自 `04_figures/` - [ ] **标题下无灰色说明小字**；标题区只有标题 +（可选）纯黑日期/版本 - [ ] **中文宋体、英文 Times New Roman，每个 run 都设了 eastAsia**；标题黑体；统计符号（*P*、*vs* 等）斜体 - [ ] 执行摘要 / 核心要点已在开头给出，读者读前段即抓住核心 - [ ] 所有数字有源且与来源逐字一致；无源处标 `[待确认]` - [ ] 每节先结论后依据；标题为名词短语；行动项可执行（动词开头 + 判定标准） - [ ] 中文书面语、零口语 / 零 AI 痕迹 / 零 emoji；术语首现有解释；全文字体纯黑 - [ ] 表为三线表（无竖线）、有题注（表上图下）、编号按行文连续 - [ ] 已实际生成 docx 并 Read 核验（无乱码、无空表、无错位、字体生效） - [ ] 术语 / 口径 / 编号全文一致（局部修改也复扫） --- ## 六、与其它 skill 的关系 - 正式论文 / 投稿材料 → `academic-publishing`（本 skill 不处理论文）。 - 文风去 AI 味 / 更像人 → 复用 `humanizer-zh` 的反 AI 清单。 - 出图 → `publication-figures`。 - docx 底层机制（读改、转换、模板）→ `docx` skill。 - 咨询交付 zip 打包 → `consulting-delivery`（本 skill 只管报告本身的写作与排版）。