report-writing

name	report-writing
description	把分析结果、进展、流程或操作要求写成结论先行、数据有源、面向行动的中文报告、指南、备忘或纪要。只要正文时不调用 docx；实际生成 Word 时再配合 docx。不用于论文与投稿材料（academic-publishing）或咨询交付包打包（consulting-delivery）。

专业报告内容写作 skill

一句话定位：把已经成立的事实（分析结果 / 流程 / 进展）写成读者一眼能用、无模板化写作痕迹的专业中文报告；用户要求文件时再生成对应载体。 报告 ≠ 论文：论文为审稿人证明严谨，报告为读者快速决策与执行服务。

---

〇、强制要求（每次生成都适用，违反 = 未完成）

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"），不用口语、网络词或助手口吻（"我建议你…""让我们…"）。 标题用名词短语、不用反问；英文缩写首次出现给全称。
3. 无模板化痕迹与零装饰符号：不堆开场闭场套话，不用表情符号或长破折号，不出现生成过程、助手口吻或未完成标记。 中文文风统一过 academic-humanizer 的不可变事实清单、学术语体与论断证据审校。
4. 体例匹配信息功能：分析、结果、讨论和论证用连贯段落把数字与解释织在一起；执行摘要、行动项、风险清单、SOP 和纯枚举可用简短列表或表格。不要把同一论证拆成碎片化短句，也不要为“报告感”强制写成长段。
5. 图表自动入文（强制要求）：报告涉及的数据，凡 03_tables/（xlsx）有对应表就读取并作为三线表插入正文、 凡 04_figures/ 有对应图就作为图片嵌入正文，不要只在文字里描述"见表 X / 如图所示"而不放实际表图。 表题在表上方、图题在图下方，编号按行文顺序连续。无现成表图时，统计图按 publication-figures；封面、章节图、流程、结构、机制、场景和概念插图按 research-visuals 的报告载体规范建立视觉简报并调用 imagegen，适用的 Image 2 先于 SVG，全部适用生成路径耗尽后才最终回退 svg-diagrams；表格按 xlsx 规范现做再插。
6. 输出载体服从请求（强制要求）：用户只要正文时直接返回净稿，不创建文件。用户指定 Markdown 或 Word 时只生成该载体；明确要求双格式时才同时生成 .md 与 .docx。
7. 结论先行：报告开头先给最重要的结论 / 要点 / 行动项，再展开依据。读者读前 1/4 就应抓住核心。 7bis. 结果/统计报告写成论文体，不暴露工程过程（强制要求）：结果类 / 统计分析报告面向读者，NEVER 写 "代码在 02_code/""详见 DECISIONS.md""方法决策记录在…""所有脚本/文件在…""基于 xx.R"之类的工程内部痕迹—— 这些是内部审计内容，不进交付报告。方法节只写中性可复现的最终口径（用了什么模型/检验/校正），像论文的 Methods， 不提脚本名、文件路径、决策记录、版本、调参。例外：报告本身就是"基于某些文件的说明/操作指引/文档类" （如填写指南、流程说明、代码文档），这类才按需引用具体文件。判据：统计结果报告 = 论文式，不谈代码与文件归档。
8. 疑点先问：读者对象 / 报告目的 / 关键口径 / 结论方向不明 → 先问用户，不擅自定调（同全局 CLAUDE.md §1 与 §8）。
9. 局部修改也走完整标准：哪怕只改一段，动后按 §五自检清单复扫，确保与全文术语、口径、编号一致。
10. 版本边界：正式项目只保留一组稳定命名的当前报告，被替代的载体、脚本和核验输出按项目归档合同整组进入 09_backup/。轻量任务不补建归档目录，只覆盖用户明确指定的输出或另存到其指定位置。
11. 默认中性排版：用户和既有模板未指定品牌色或深色主题时，标题、章节、正文、表题、表头和全部单元格保持白底黑字。层级只用字号、字重、间距和边框；不得自动生成深色标题条、深色表头、彩色首列、色块汇总行、渐变底或大面积灰底。

---

一、报告 ≠ 论文（写之前先认清差别）

维度	论文（academic-publishing）	报告（本 skill）
读者	审稿人、同行	决策者、客户、团队、执行人
目的	证明结论可信、可发表	让读者快速理解并据以行动
结构	IMRaD 固定、参考文献规范	灵活，按"读者需要先知道什么"组织
开头	背景铺垫 → 逐步推进	执行摘要 / 结论先行
语气	客观克制、回避主观	客观但更直接，可给明确建议
篇幅取向	完整论证	抓重点、去冗余、可要点化
引用	严格文献规范	注明来源即可，不强求文献格式

报告仍要：数据有源、书面语、无模板化写作痕迹、零编造，这几条与论文一致，不放松。

---

二、报告结构（按报告类型取用，不必全有）

通用骨架（按需裁剪、重排）：

1. 标题页 / 抬头：报告名（名词短语）、副标题、日期、版本 / 编制方（可选）。
2. 执行摘要 / 核心要点（多数报告必备）：3–6 条，给最重要的结论、数字、行动项。读者只读这一段也不致误判。
3. 背景 / 目的：为什么有这份报告、要解决什么问题、范围边界。
4. 方法 / 过程（分析或操作类报告）：做了什么、依据什么标准。简明，不展开论文级细节。
5. 结果 / 发现：核心内容。按主题分节，每节"先结论后依据"，配表 / 图 / 要点。
6. 建议 / 行动项（决策类报告）：可执行步骤，必要时给"谁、何时、按什么标准"。
7. 附录：明细表、原始数据指引、术语表、参考资料。

按类型选骨架：

• 分析 / 结果报告：执行摘要 → 背景目的 → 方法 → 发现（分主题）→ 结论建议 → 附录。
• 进展 / 工作报告：核心要点 → 已完成 → 进行中 → 待办与风险 → 下一步。
• 操作指南 / 手册（如填写指南、SOP）：用途与适用对象 → 核心概念 → 分步操作 → 结果解读 → 注意事项 / 常见问题。
• 说明 / 备忘：结论先行 → 关键事实 → 影响 → 需对方决策的点。

---

三、写作风格

• 按内容选段落或列表：数字解释、比较和推论使用连贯段落；执行摘要、并列结论、行动项、SOP 和检查清单使用列表或表格更清楚时直接使用。列表项保持完整、同层级且可执行。
• 结论先行：每个章节、每个段落都先给判断 / 结论，再给支撑。避免"铺垫半页才到重点"。
• 一节一主题：标题用名词短语点明该节结论（"低体重提示更差预后"优于"关于低体重的分析"）。
• 数据贴着解读走：每报一个数就跟一句它意味着什么（"较 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（中文），否则英文数字会回退成宋体、中文会变默认西文字体。

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；封面与章节视觉采用编辑出版构图，流程图、结构图、包含关系、概念框架、机制示意和研究场景按 research-visuals 生成最终 PNG。生成前读取实际版心、标题区、配色和图片角色；真实科研原始图像不得生成式重绘。只有走矢量回退时才保留同名 SVG+PNG，并用 PNG 供 python-docx 嵌入。正文图片居中，宽度约占版心（通常 5.5–6.5 in），图题在图下方（"图1 …"）。

• 全文字体一律黑色（标题、正文、表头、注释一律纯黑 #000000）；不用彩色字、不用灰字；层级靠字号与加粗区分，不靠颜色。禁止表情符号、禁止彩虹色、禁止默认灰底。

禁止：深色标题条、深色表头和无明确含义的单元格底色；标题下灰色说明小字；正文项目符号堆叠；表情符号；长破折号当连接号；口语 / 网络词；生成过程痕迹；无来源的"最佳 / 显著 / 证明"。

---

五、生成流程与自检清单

构建助手：排版统一用 references/build_report.py（Report 类）——已封装中文宋体/英文 Times New Roman（每 run 设 eastAsia）、 干净标题页（无灰字）、三线表、table_from_xlsx() 自动取数、figure() 嵌图和统计符号斜体。save() 的输出参数按用户请求设置，不默认双格式。 内容仍须按本节强制要求写入，助手只保证排版正确。

流程：定读者与目的 → 选骨架（§二）→ 取数（强制要求 1）→ 收集要插的表（03_tables/ xlsx）与图（统计图 PNG；非统计图默认 imagegen PNG，矢量回退为 SVG+PNG） → 逐节结论先行，把数与图表引用织进正文 → 套排版（§四，宋体/Times、三线表、表上图下、统计符号斜体） → 正式项目按需归档被替代旧版 → 生成用户要求的载体 → 自检 → 交付时先报告已自检项。

完成前自检（不等用户挑错）：

• 仅生成用户要求的载体；若要求双格式，则同名同目录且内容一致
• 正式项目当前目录仅一组稳定命名报告，归档批次已更新；轻量任务未被强制补建账本
• 分析论证使用连贯段落；执行摘要、行动项和 SOP 的列表层级清楚且不碎片化
• 该有的表已作为三线表插入、该有的图已嵌入正文（非仅文字"见表/见图"）；表取自 03_tables/ xlsx、图取自 04_figures/
• 标题下无灰色说明小字；标题区只有标题 +（可选）纯黑日期/版本
• 标题、表头、首列、汇总行和普通单元格均为白底黑字；无深色标题条、深色表头、彩色条带或渐变底
• 中文宋体、英文 Times New Roman，每个 run 都设了 eastAsia；标题黑体；统计符号（P、vs 等）斜体
• 执行摘要 / 核心要点已在开头给出，读者读前段即抓住核心
• 所有数字有源且与来源逐字一致；无源处标 [待确认]
• 每节先结论后依据；标题为名词短语；行动项可执行（动词开头 + 判定标准）
• 中文书面语、零口语、无模板化痕迹和装饰符号；术语首现有解释；全文字体纯黑
• 表为三线表（无竖线）、有题注（表上图下）、编号按行文连续
• 已实际生成 docx 并 Read 核验（无乱码、无空表、无错位、字体生效）
• 术语 / 口径 / 编号全文一致（局部修改也复扫）

---

六、与其它 skill 的关系

• 正式论文 / 投稿材料 → academic-publishing（本 skill 不处理论文）。
• 学术与专业文风润色 → 统一使用 academic-humanizer 的不可变事实清单、语体和论断—证据一致性审查。
• 统计图 → publication-figures；封面、章节、流程、结构、机制、包含关系和研究场景视觉 → research-visuals 按报告载体建立视觉系统并调用 imagegen，适用的 Image 2 先于 SVG，全部适用生成路径耗尽后才最终回退 svg-diagrams。
• docx 底层机制（读改、转换、模板）→ docx skill。
• 咨询交付 zip 打包 → consulting-delivery（本 skill 只管报告本身的写作与排版）。