# 输出格式：Markdown

标准 Markdown 报告 + 独立图片目录。便于在编辑器、GitHub、Wiki 等环境中查看与二次编辑。

---

## 1. 适用场景

- 用户明确要求"生成 Markdown 报告"或"给我 .md 文件"。
- 报告需进入 Git 仓库 / 文档站 / Notion / 飞书等支持 Markdown 的平台。
- 用户希望后续手动编辑、复制片段。
- 需要轻量、纯文本、易于 diff 的产物。

## 2. 图片处理

将 `{workspace}/figures/` 下的目标图片复制到 `{workspace}/outputs/{简短标题}-images/` 目录，Markdown 中以**相对路径**引用：

```markdown
![图 1：架构图](./{简短标题}-images/fig1_architecture.png)
```

**注意**：

- 不要使用绝对路径或 `file://` 协议，否则在他人环境中无法显示。
- 图片文件名使用语义化英文（如 `fig2_results.png`、`fig3_ablation.png`），避免空格和中文。
- 图片目录与 `.md` 文件应保持同级关系，便于打包分发。

## 3. 数学公式

使用标准 LaTeX 语法：

- 行内公式：`$x = y + z$`
- 独立公式：`$$\mathcal{L} = \sum_i \log p_\theta(x_i)$$`

主流 Markdown 渲染器（GitHub、VS Code、Typora、Obsidian、Notion 等）原生支持 KaTeX/MathJax。

> 由于不同渲染器对 `\\` 换行、空行等细节有差异，公式建议保持简洁，复杂多行推导拆为多个独立公式块。

## 4. 表格处理

使用 Markdown 原生表格语法，最佳值用 `**...**` 加粗：

```markdown
| 模型 | BLEU | ROUGE-L |
|------|------|---------|
| Baseline | 32.1 | 54.2 |
| Ours | **35.8** | **57.6** |
```

表格列数较多或单元格内有换行/公式时，可降级为 HTML `<table>`（GFM 兼容）。

## 5. 模板路径

[markdown-template.md](markdown-template.md)

模板包含 YAML 风格的元信息块、章节骨架、图片引用示例和表格示例。占位符以 `{{...}}` 形式存在。

## 6. 输出文件命名

保存到 `{workspace}/outputs/`：

- `report_{简短标题}.md` —— Markdown 报告主文件
- `{简短标题}-images/` —— 图片目录（与 .md 同级）

简短标题从论文标题中提取核心关键词（去除特殊字符，空格替换为 `-` 或 `_`）。两者使用**相同的简短标题**。

## 7. 写作风格细节

- 章节标题使用 `##`（一级）、`###`（二级），避免使用 `#`（保留给文档总标题）。
- 图表引用格式："如图 1 所示，..."、"表 1 汇总了..."。
- 重点结论用 `**...**` 加粗或 `> ...` 引用块。
- 列表项之间留空行，避免 GFM 渲染合并问题。
- 代码片段使用三反引号围栏，并标注语言（如 ` ```python `）。

## 8. 校验清单

使用 Read 工具查看生成的 `.md` 文件，逐项确认：

**通用检查**：

- 各章节标题完整、层级清晰（`##` / `###`）
- 每个章节有实质内容，不存在空段落或占位符（无 `{{...}}` 残留）
- 不包含"报告生成日期"或"AI 辅助生成"相关文字

**Markdown 专项检查**：

- 公式使用 `$...$` 或 `$$...$$`，无乱码
- 所有图片引用为相对路径 `./{简短标题}-images/xxx.png`
- **图片文件验证**——必须用 `ls` 显式确认文件存在：

  ```bash
  ls {workspace}/outputs/{简短标题}-images/
  ```

- 逐个核对：Markdown 中每个 `![...](./{简短标题}-images/xxx.png)` 引用的文件确实在目录中

## 9. 已知陷阱

- **复制 vs 移动**：图片是从 `{workspace}/figures/` 复制（cp）到 outputs 子目录，**不要 mv**——避免后续重新生成时图片源丢失。
- **Windows 路径分隔符**：始终使用 `/`，不要使用 `\`，跨平台兼容。
- **GFM 与 KaTeX 差异**：GitHub 原生不支持 `$$`，需仓库启用 MathJax；用户在 GitHub 阅读时建议下载本地查看或注明渲染要求。
- **图片大小**：Markdown 不支持自动缩放，原图过大会撑爆视图。建议在 `figures/` 中预先缩放（如最大宽度 1400 px）后再复制。
- **目录命名空格**：`{简短标题}-images/` 中的简短标题不能含空格，否则在某些 Markdown 渲染器中链接断裂。