---
name: sn-research-report
description: 研究报告写作与修改；当需要把 deep research 的判断层写成最终 `report.md`，或单独对已有报告/文稿做重写、改写、润色、重组结构、增强摘要、补充表格、规划插图并调用 `sn-image-base` 生成合适配图时使用。适用于完整终稿生成，也适用于已有草稿的定向编辑，不负责从零重新做研究综合判断。
---

# Research Report

这个 skill 既可以用于：

- **终稿生成模式**：把 deep research 的判断层转成最终交付。
- **写作修改模式**：对已有报告、草稿、说明文、分析文做定向改写、重组、压缩、扩写或润色。

一句话区分：

- 有 `synthesis.md` 时，它负责把**已经想清楚的结论讲清楚**
- 没有 `synthesis.md` 但有现成草稿时，它负责把**已有内容改得更清楚**

## 任务边界

做：

- 按给定结构、读者和用途组织报告。
- 在终稿生成模式下，以 `synthesis.md` 为主输入写出 `report.md`。
- 在写作修改模式下，基于现有草稿进行重写、压缩、扩写、重组、改写或润色。
- 从 supporting notes、子报告或附加材料中抽取支撑内容。
- 用表格、时间线、Mermaid 或图片提升可读性；需要 AI 配图时，调用 `sn-image-base` 生成图片并嵌入报告。
- 清楚呈现条件、限制、冲突和不确定性。

不做：

- 不在缺少依据时擅自新增关键事实或关键结论。
- 不把写作修改变成重新做一轮研究。
- 不把子报告或笔记逐段拼接成终稿。
- 不把终稿写成内部工作笔记。
- 不写脚注、文末参考文献或来源编号。

## 依赖能力

需要 AI 配图时，调用底层 skill `sn-image-base` 的 `sn-image-generate` 工具。

`$SN_IMAGE_BASE` 是 `sn-image-base` skill 的安装目录，目录下应存在 `SKILL.md`。

解析 `$SN_IMAGE_BASE`：

1. 优先使用环境变量 `SN_IMAGE_BASE`。
2. 否则按已安装 skills 列表中的 skill 名称 `sn-image-base` 定位。
3. 否则在当前 skills 根目录或相邻目录查找 `sn-image-base/`。
4. 找不到时，不要假装已生成图片；先询问用户提供 `sn-image-base` 路径，或确认是否改用 Mermaid/表格替代。

调用参数以 `$SN_IMAGE_BASE/references/api_spec.md` 为准。需要认证或服务地址时，优先使用 `sn-image-base` 支持的默认配置与环境变量；如果运行时报缺少 API key、base URL、model 或其他必要配置，不要跳过、不伪造、不自行编造默认值，先询问用户提供对应配置。

## 输入模式

### 模式 A：终稿生成

输入：

- `{report_dir}/request.md`
- `{report_dir}/plan.json`
- `{report_dir}/synthesis.md`
- 全部 `{report_dir}/sub_reports/*.md`
- 可选：`{report_dir}/images/`

适用：

- 已经完成 deep research，准备产出最终 `report.md`

### 模式 B：写作修改

最小输入：

- 现有草稿文件；或
- 一段待修改文本；或
- 用户明确的修改要求 + 原始文稿路径

可选补充：

- 目标读者
- 目标长度
- 期望语气
- 想保留或想删掉的部分
- 希望增强的内容：摘要、结构、表格、结论、逻辑、语言、过渡
- supporting notes / 素材文件 / 参考结构

适用：

- “把这份报告改得更清楚”
- “帮我重写这个摘要”
- “把这份分析改成正式报告”
- “把这个草稿整理成对外可发版本”
- “重组结构，不改核心观点”

## 模式判定

按下面顺序判断：

1. 有 `synthesis.md`、`plan.json`、`sub_reports/*.md`：走**终稿生成模式**
2. 没有完整研究链路，但有现成草稿或待修改文本：走**写作修改模式**
3. 两者都缺：先要求输入文稿或研究材料，不要硬写

## 终稿生成模式

### 目标

把 `synthesis.md` 中已经形成的判断层，转成面向读者的最终交付。

### 执行流程

1. **确定读者任务**：从 `request.md` 和 `plan.json.scope` 判断读者是要了解全貌、比较选择、调查对象、追踪事件还是制定行动。
2. **读取主线**：从 `synthesis.md` 提取主线判断、证据强弱、关键冲突、不确定性和对原始问题的回答。
3. **搭建结构**：优先使用 `plan.json.report_shape.sections`；如果缺失，再按读者任务选择通用结构。
4. **写摘要**：让读者不看正文也能理解核心判断、关键依据和主要不确定性。
5. **组织正文**：按“本章判断 -> 支撑材料 -> 分析解释 -> 小结”展开。
6. **嵌入证据**：从子报告里抽表格、案例、数据、时间线和风险点，放进最合适的章节。
7. **处理冲突与限制**：把 `synthesis.md` 里的冲突和不确定性写进相关章节或“风险与不确定性”部分。
8. **规划视觉元素**：先列出每个章节最适合的视觉形式，只保留能帮助理解的表格、Mermaid 或图片。
9. **生成与嵌入配图**：对需要 AI 配图的位置，调用 `sn-image-base` 生成图片，保存到 `{report_dir}/images/`，并在对应章节用 Markdown 相对路径嵌入。
10. **完成终稿**：写入 `report.md`，保证结构完整、结论清楚、语言克制，图片引用路径可从 `report.md` 正常解析。

如果没有 `synthesis.md`，不要硬写终稿；先回到综合判断阶段。

## 写作修改模式

### 目标

在不无依据改变核心事实与判断的前提下，把现有文稿改得更适合目标用途。

### 常见修改任务

- **结构重组**：调整章节顺序、合并重复内容、补标题层级
- **摘要改写**：重写开头、执行摘要、结论摘要
- **语言润色**：让语言更清晰、克制、专业、简洁
- **逻辑增强**：补过渡、补小结、明确“结论 -> 依据 -> 限制”
- **篇幅调整**：压缩、扩写、提炼要点
- **表达转写**：把笔记式文本改成正式报告，把内部稿改成对外稿
- **可读性增强**：把堆叠段落改成表格、清单、时间线

### 执行流程

1. **识别修改目标**：判断用户是想重写、压缩、扩写、润色、重组，还是组合任务。
2. **读取现有文稿**：先理解主张、结构、信息密度和主要问题。
3. **锁定不变项**：识别必须保留的事实、观点、术语、口径和结构约束。
4. **决定改写粒度**：
   - 小改：摘要、段落、标题、语句层面优化
   - 中改：章节重组、逻辑重排、表格化表达
   - 大改：整体重写，但保留原文核心内容和事实边界
5. **执行修改**：优先改结构和逻辑，再改语言和可读性。
6. **自检**：确认没有无依据新增关键事实，也没有误改原文立场。
7. **输出修改稿**：写回目标文件或用户指定路径。

### 修改原则

- 用户没有要求改观点时，不擅自改核心判断。
- 用户没有提供新证据时，不擅自补新的关键事实。
- 原文结构差时，优先解决结构，不先做逐句抛光。
- 如果现有文本是“研究笔记”，允许重写成报告，但要保留原始不确定性。

## 报告结构

优先遵循 `plan.json.report_shape.sections` 或用户指定结构。若两者都没有，可按任务选择：

- **全景研究**：摘要 → 背景与范围 → 核心发现 → 分维度分析 → 综合判断 → 风险与不确定性 → 下一步。
- **对比选型**：摘要与推荐 → 评估背景 → 对比矩阵 → 逐维度分析 → 场景化建议 → 风险与限制。
- **实体调查**：执行摘要 → 对象概览 → 关键维度审查 → 重大风险/机会 → 综合评价 → 后续关注。
- **事件追踪**：摘要 → 时间线 → 各方立场 → 影响分析 → 后续走向 → 不确定性。
- **普通写作修改**：标题 → 摘要/导语 → 主体章节 → 结论/下一步。

复合意图只保留一个主结构；次要意图压缩成一个章节。

## 逻辑要求

- 摘要必须可独立阅读。
- 每章开头说明本章回答什么问题。
- 正文优先沿主线展开，不按材料顺序机械展开。
- 结论要标注确定性：已确认、较可能、存在争议、信息不足。
- 相同事实不要在多个章节重复展开。
- 不确定性必须说明会如何影响判断。

## 视觉元素

优先使用结构化视觉，而不是装饰图。

| 内容类型 | 推荐形式 |
|---|---|
| 多对象多指标比较 | Markdown 表格 |
| 评估维度和权重 | Markdown 表格 |
| 时间序列事件 | Mermaid `timeline` 或时间线表 |
| 流程、产业链、因果链 | Mermaid `flowchart` |
| 关系网络、组织关系 | Mermaid `graph` |
| 趋势或份额，有明确数据 | Mermaid `xychart-beta` / `pie` |
| 抽象概念、场景、封面、架构氛围 | AI 生图 |

### 视觉规划

写终稿前先做一个轻量视觉计划，不需要写入 `report.md`，但必须指导正文：

- 每个主章节最多放 0-1 个视觉元素。
- 有数据、流程、时间线或关系结构时，优先使用表格或 Mermaid。
- 只有抽象概念、场景、封面、用户旅程、架构氛围、产业图景等无法用数据图准确表达时，才使用 AI 配图。
- 不要为了“好看”生成图片；图片必须解释章节主判断、降低理解门槛或建立报告语境。

使用 AI 配图时：

- 只用于非数据驱动的概念图、场景图、封面图或架构示意。
- 图片保存到 `{report_dir}/images/`，使用相对路径引用。
- 同一份文稿图片风格要统一。
- 只有确实帮助理解时才加图。
- 每张图片必须紧贴它解释的段落或章节，不要集中堆在文末。
- Markdown 格式使用 `![简短说明](images/<filename>.png)`。
- 配图文件名使用小写字母、数字和连字符，例如 `images/market-structure.png`。

### 调用 sn-image-base 生图

生成图片前，为每张图写清楚：

- `slot`：插入位置，例如“摘要后”或“第二章：市场结构开头”。
- `purpose`：这张图帮助读者理解什么。
- `alt`：Markdown alt 文本。
- `filename`：保存到 `{report_dir}/images/` 的文件名。
- `prompt`：英文图像提示词，包含主题、构图、风格、禁用文字或少文字要求。

调用命令：

```bash
mkdir -p <report_dir>/images
python "$SN_IMAGE_BASE/scripts/sn_agent_runner.py" sn-image-generate \
  --prompt "<image prompt>" \
  --aspect-ratio "16:9" \
  --image-size "2k" \
  --save-path "<report_dir>/images/<filename>.png" \
  -o json
```

调用后确认文件存在且非空，再把相对路径写入 `report.md`：

```markdown
![市场结构概念图](images/market-structure.png)
```

如果生图失败：

- 不要留下失效图片链接。
- 如果失败原因是缺少 API key、base URL、model 或其他必要配置，先询问用户提供配置，或确认是否改用 Mermaid/表格替代。
- 优先改用 Mermaid、表格或文字说明。
- 在最终回复中说明失败原因和替代方式。

## 输出

### 终稿生成模式

默认写入 `{report_dir}/report.md`

### 写作修改模式

默认覆写用户指定目标文件；如果用户要求保留原稿，则输出到新路径。

## 质量门槛

- 输出结构与给定结构约束一致，或说明为什么调整。
- 终稿生成模式下：主线判断来自 `synthesis.md`，而不是写作时临时发明。
- 写作修改模式下：修改结果忠于原文事实与核心判断，除非用户明确要求改写立场。
- 主要判断都能从 `synthesis.md`、子报告或用户提供文稿追溯。
- 关键对比优先使用表格，而不是长段落堆叠。
- AI 配图已实际生成到 `{report_dir}/images/`，且 `report.md` 中的相对路径可用。
- 图片出现的位置与它解释的章节相邻，不集中堆在开头或结尾。
- 冲突、不确定性和适用范围清楚呈现。
- 面向目标读者，而不是面向作者自己的工作记忆。

## 常见失败

- 没有 `synthesis.md` 也没有草稿，却硬写终稿。
- 把写作修改变成又做一次研究。
- 把子报告或原稿按顺序拼起来，缺少主线。
- 摘要只有背景，没有判断。
- 只讲结论，不讲条件和不确定性。
- 逐句润色很多，但结构问题完全没解决。
- 用图片做装饰，不能帮助理解。
- 只写“可加入配图”，但没有调用 `sn-image-base` 生成文件。
- 生成了图片文件，却没有在 `report.md` 的合适章节嵌入。
- 把 `sn-image-base` 名称、环境变量或命令写错，导致找不到依赖。