Markdown 报告写作（术层 · 格式）

术-格式 · 术层 skill 全文

本页是 <code>rules/skills/drafts/bestpractice_markdown_report.md</code> 的逐字投影（仅隐私清洗，零改写）。

Markdown 报告写作（术层 · 格式）

元数据

• 类型：BestPractice
• 适用场景：报告以 Markdown 形态交付时（保持 MD，或先写 MD 再转），怎么把它写好，重点是图像和图表
• 状态：Draft（2026-05-31）
• 矩阵位置：报告写作矩阵的「× MD 格式」格。写什么归 bestpractice_report_readability（实现报告）/ workflow_analytical_writing（调研报告）；MD→HTML 转换机制归 bestpractice_markdown_html_conversion；发布上线归 share_report；富交互 HTML 渲染归 bestpractice_final_report。全图见 workflow_report_writing_matrix

这个 skill 管什么

报告决定用 MD 交付时的格式纪律。重点是用图表现变化（人对图像理解更快，变化记录的要求见 bestpractice_report_readability），以及 MD 特有的图像处理。语言去 AI 味由 COMMUNICATION.md 管，本 skill 不碰。

用图：MD 里怎么画

• before / after、流程、架构优先用 mermaid 代码块（ `mermaid ）。GitHub、Obsidian、VS Code 和多数 MD→HTML 都能渲染，渲染不了时降级成纯文本也读得懂。
• mermaid 不可靠的场合，用并排表格或 ASCII 框图兜底，保证退化到纯文本仍读得懂。
• "之前 → 之后"的结构化差异用三列表格最稳：| 维度 | 之前 | 之后 |。
• 时间线用有序列表或 mermaid timeline。

before/after 架构图模板（变更可视化）

记录架构 / 结构变更的报告，变更对比用下面的 before/after mermaid 模板，不要纯文字叙述。何时画、画哪种图、怎么 look-back 取证是判断，归道 skill workflow_change_visualization；本节只给可复制的格式骨架。

模板：同框 before/after + 三色

一张 flowchart LR 里两个 subgraph 并排放 before 和 after，相同节点保持相同相对位置（small multiples，眼睛平移找 delta）：

flowchart LR
subgraph BEFORE["改前：&lt;一句话现状&gt;"]
direction TB
a1[组件A] --> a2[组件B]
end
subgraph AFTER["改后：&lt;一句话结果&gt;"]
direction TB
b1[组件A]:::existing --> b2[新组件]:::added
end
BEFORE ==>|"&lt;变更动作&gt;"| AFTER
classDef existing fill:#f5f5f5,stroke:#999,stroke-dasharray:4 3,color:#555;
classDef added fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;
classDef changed fill:#fff3e0,stroke:#e8820c,stroke-width:2px,color:#b35900;
classDef removed fill:#ffebee,stroke:#c62828,stroke-dasharray:4 3,color:#b71c1c;

三色 + 形状语义（仓库约定，固定）

颜色只标 delta，不变的用灰，让视线先落在变化上：

• :::existing 灰虚线 ＝ 不变的上下文（视觉权重最低）
• :::added 绿 ＝ 新增
• :::changed 橙 ＝ 修改 / 承重 delta（最显眼）
• :::removed 红虚线 ＝ 删除（画在 before 侧）

节点形状按类型（本仓库语境）：[工具] 方框＝确定层工具｜([skill]) 圆角＝语义层 skill｜[(数据真源)] 桶＝真源文件｜{{检测器}} 六边＝gate。边：--> 调用｜-.-> 数据流｜==> 依赖｜~~~> 误差信号。

标注：delta 就近写判决

变更点用图说或节点文字就近标判决，不写描述：写「新增 rate-limit 层」「合并 A＋B」「方向反转」，不写「此处为 X」。每个 delta 锚真实证据（commit / file:line / run 记录），不编造结构（取证纪律见道 skill 的 look-back 要求）。

图说 ＝ 结论句

每张图配一句结论性图说，指明「请读者看什么、关键变化在哪」：写「去掉 session 层后跨节点请求少 2 跳」，不写「新旧架构对比」。

渲染降级（mermaid 为 source of truth）

mermaid 在无 JS 的纯文本查看器（cat / less）退化成代码块仍可读，这是底线。复杂到 mermaid 排版不稳、或要精确对齐时，用三列表格 | 对象 | 改前 | 改后 | ＋ 一句 delta 说明兜底。不为渲染在 MD 里手写大段 HTML / SVG（那是 bestpractice_final_report 的格）。

用图：嵌入外部图片

• 用 !alt（path） 语法，alt 文本写清这张图说明什么，截图和图表尤其要写。
• 路径：报告要跨机器或上传时用绝对路径，或随报告同目录的相对路径，不要指向只在本机存在的临时路径。
• 大图先压，说明文字放图旁，不靠读者自己猜图在讲什么。

MD 本身的格式纪律

• 列表、表格、代码块前后留空行，否则部分渲染器不识别（详见 bestpractice_markdown_html_conversion）。
• 标题层级连续不跳级，标题里不塞【】等装饰符号。
• 关键引用保留原文摘录 ＋ 绝对链接（与 workflow_analytical_writing 共享约定）。

边界（不做什么）

• 何时画、画哪种图（结构对比 vs 流程对比）、画前怎么 look-back 取真实结构：道 skill workflow_change_visualization。本 skill 只给 before/after 的格式骨架，不做选图判断。
• 写什么、变化记录、证据链：bestpractice_report_readability（实现报告）/ workflow_analytical_writing（调研报告）
• 这份 MD 之后要转 HTML 上线：转换机制见 bestpractice_markdown_html_conversion，发布见 share_report，不要在 MD 里手写一堆 HTML 凑渲染
• 想要富交互 HTML（注释、dark mode、推挤 panel）：那是 bestpractice_final_report 的格，不在 MD 范畴

已知陷阱

初版，随真实使用再补，不预先编造。

<!-- created 2026-05-31 by zlx: MD 报告格式（图优先），报告写作矩阵「× MD 格式」格 -->