| name | report-writing |
| description | 把分析结果、进展、流程或操作要求写成结论先行、数据有源、面向行动的中文报告、指南、备忘或纪要。只要正文时不调用 docx；实际生成 Word 时再配合 docx。不用于论文与投稿材料（academic-publishing）或咨询交付包打包（consulting-delivery）。
|
专业报告内容写作 skill
一句话定位：把已经成立的事实（分析结果 / 流程 / 进展）写成读者一眼能用、无模板化写作痕迹的专业中文报告；用户要求文件时再生成对应载体。
报告 ≠ 论文：论文为审稿人证明严谨，报告为读者快速决策与执行服务。
〇、强制要求（每次生成都适用，违反 = 未完成）
- 数据有源、零编造、单源取数：所有数字（样本量、估计值、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 就地改。
- 学术书面语：研究者/执行者视角（"本报告/我们完成了 X"），不用口语、网络词或助手口吻（"我建议你…""让我们…"）。
标题用名词短语、不用反问；英文缩写首次出现给全称。
- 无模板化痕迹与零装饰符号：不堆开场闭场套话，不用表情符号或长破折号，不出现生成过程、助手口吻或未完成标记。
中文文风统一过
academic-humanizer 的不可变事实清单、学术语体与论断证据审校。
- 体例匹配信息功能：分析、结果、讨论和论证用连贯段落把数字与解释织在一起；执行摘要、行动项、风险清单、SOP 和纯枚举可用简短列表或表格。不要把同一论证拆成碎片化短句，也不要为“报告感”强制写成长段。
- 图表自动入文（强制要求）：报告涉及的数据，凡
03_tables/（xlsx）有对应表就读取并作为三线表插入正文、
凡 04_figures/ 有对应图就作为图片嵌入正文，不要只在文字里描述"见表 X / 如图所示"而不放实际表图。
表题在表上方、图题在图下方，编号按行文顺序连续。无现成表图时，统计图按 publication-figures；封面、章节图、流程、结构、机制、场景和概念插图按 research-visuals 的报告载体规范建立视觉简报并调用 imagegen，适用的 Image 2 先于 SVG，全部适用生成路径耗尽后才最终回退 svg-diagrams；表格按 xlsx 规范现做再插。
- 输出载体服从请求（强制要求）：用户只要正文时直接返回净稿，不创建文件。用户指定 Markdown 或 Word 时只生成该载体；明确要求双格式时才同时生成
.md 与 .docx。
- 结论先行：报告开头先给最重要的结论 / 要点 / 行动项，再展开依据。读者读前 1/4 就应抓住核心。
7bis. 结果/统计报告写成论文体，不暴露工程过程（强制要求）：结果类 / 统计分析报告面向读者，NEVER 写
"代码在
02_code/""详见 DECISIONS.md""方法决策记录在…""所有脚本/文件在…""基于 xx.R"之类的工程内部痕迹——
这些是内部审计内容，不进交付报告。方法节只写中性可复现的最终口径（用了什么模型/检验/校正），像论文的 Methods，
不提脚本名、文件路径、决策记录、版本、调参。例外：报告本身就是"基于某些文件的说明/操作指引/文档类"
（如填写指南、流程说明、代码文档），这类才按需引用具体文件。判据：统计结果报告 = 论文式，不谈代码与文件归档。
- 疑点先问：读者对象 / 报告目的 / 关键口径 / 结论方向不明 → 先问用户，不擅自定调（同全局
CLAUDE.md §1 与 §8）。
- 局部修改也走完整标准：哪怕只改一段，动后按 §五自检清单复扫，确保与全文术语、口径、编号一致。
- 版本边界：正式项目只保留一组稳定命名的当前报告，被替代的载体、脚本和核验输出按项目归档合同整组进入
09_backup/。轻量任务不补建归档目录，只覆盖用户明确指定的输出或另存到其指定位置。
- 默认中性排版：用户和既有模板未指定品牌色或深色主题时，标题、章节、正文、表题、表头和全部单元格保持白底黑字。层级只用字号、字重、间距和边框；不得自动生成深色标题条、深色表头、彩色首列、色块汇总行、渐变底或大面积灰底。
一、报告 ≠ 论文（写之前先认清差别）
| 维度 | 论文（academic-publishing） | 报告（本 skill） |
|---|
| 读者 | 审稿人、同行 | 决策者、客户、团队、执行人 |
| 目的 | 证明结论可信、可发表 | 让读者快速理解并据以行动 |
| 结构 | IMRaD 固定、参考文献规范 | 灵活，按"读者需要先知道什么"组织 |
| 开头 | 背景铺垫 → 逐步推进 | 执行摘要 / 结论先行 |
| 语气 | 客观克制、回避主观 | 客观但更直接，可给明确建议 |
| 篇幅取向 | 完整论证 | 抓重点、去冗余、可要点化 |
| 引用 | 严格文献规范 | 注明来源即可，不强求文献格式 |
报告仍要：数据有源、书面语、无模板化写作痕迹、零编造，这几条与论文一致，不放松。
二、报告结构（按报告类型取用，不必全有）
通用骨架（按需裁剪、重排）：
- 标题页 / 抬头：报告名（名词短语）、副标题、日期、版本 / 编制方（可选）。
- 执行摘要 / 核心要点（多数报告必备）：3–6 条，给最重要的结论、数字、行动项。读者只读这一段也不致误判。
- 背景 / 目的：为什么有这份报告、要解决什么问题、范围边界。
- 方法 / 过程（分析或操作类报告）：做了什么、依据什么标准。简明，不展开论文级细节。
- 结果 / 发现：核心内容。按主题分节，每节"先结论后依据"，配表 / 图 / 要点。
- 建议 / 行动项（决策类报告）：可执行步骤，必要时给"谁、何时、按什么标准"。
- 附录：明细表、原始数据指引、术语表、参考资料。
按类型选骨架：
- 分析 / 结果报告：执行摘要 → 背景目的 → 方法 → 发现（分主题）→ 结论建议 → 附录。
- 进展 / 工作报告：核心要点 → 已完成 → 进行中 → 待办与风险 → 下一步。
- 操作指南 / 手册（如填写指南、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)
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、三线表、表上图下、统计符号斜体）
→ 正式项目按需归档被替代旧版 → 生成用户要求的载体 → 自检 → 交付时先报告已自检项。
完成前自检（不等用户挑错）：
六、与其它 skill 的关系
- 正式论文 / 投稿材料 →
academic-publishing（本 skill 不处理论文）。
- 学术与专业文风润色 → 统一使用
academic-humanizer 的不可变事实清单、语体和论断—证据一致性审查。
- 统计图 →
publication-figures；封面、章节、流程、结构、机制、包含关系和研究场景视觉 → research-visuals 按报告载体建立视觉系统并调用 imagegen，适用的 Image 2 先于 SVG，全部适用生成路径耗尽后才最终回退 svg-diagrams。
- docx 底层机制（读改、转换、模板）→
docx skill。
- 咨询交付 zip 打包 →
consulting-delivery（本 skill 只管报告本身的写作与排版）。
