git:20260428.616e7c2 to git:20260630.e4eeb3c

- description: 基于已有研究材料或草稿生成/修改最终 Markdown 研究报告的成稿 skill。遇到以下情况使用：①已有 deep research 产物 `synthesis.md`、`plan.json`、`sub_reports/*.md`，需要写成最终 `report.md`；②已有报告、草稿或文稿路径，需要重写、改写、润色、压缩、扩写、重组结构、增强摘要或补充表格/图示；③需要在报告成稿阶段主动规划并插入 Markdown 表格、Mermaid 图、AI 概念配图等视觉元素。仅用于终稿生成和文稿定向编辑；不用于从零调研、研究规划、联网取证、分维度研究或生成 `synthesis.md`。如果用户只是要求“深度研究/调研/写一份研究报告”且没有现成材料，应优先使用 `sn-deep-research`。

- # Research Report

-

- 把已经形成的判断写成读者能使用的报告。报告不是材料拼接，而是围绕读者任务、主线判断、证据和不确定性组织出来的交付物。

-

- ## 适用模式

-

- 按顺序判断：

-

- 1. 有 `{report_dir}/synthesis.md`、`plan.json`、`sub_reports/*.md`：走**终稿生成模式**，默认写入 `{report_dir}/report.md`。

- 2. 没有完整研究链路，但有现成草稿、文稿路径或待修改文本：走**写作修改模式**，默认写回用户指定目标文件。

- 3. 两者都缺：先要求输入文稿或研究材料，不要硬写。

-

- ## 边界

-

- 做：

-

- - 按读者、用途和结构约束组织报告。

- - 在终稿生成模式下，以 `synthesis.md` 的判断层为主输入写出 `report.md`。

- - 在写作修改模式下，忠于原稿事实和核心判断做重写、压缩、扩写、重组或润色。

- - 从 supporting notes、子报告或附加材料中抽取表格、案例、数据、时间线和风险点。

- - 主动规划视觉节点，并用表格、Mermaid 或 AI 图片降低理解成本。

- - 清楚呈现条件、限制、冲突和不确定性。

-

- 不做：

-

- - 不在缺少依据时新增关键事实或关键结论。

- - 不把写作修改变成重新研究。

- - 不把子报告或笔记按顺序拼成终稿。

- - 不写脚注、文末参考文献或来源编号。

- - 不用 AI 图片承载精确数字、坐标轴、表格或可核验地图。

-

- ## 终稿生成模式

-

- 输入：

-

- - `{report_dir}/request.md`

- - `{report_dir}/plan.json`

- - `{report_dir}/synthesis.md`

- - 全部 `{report_dir}/sub_reports/*.md`

- - 可选：`{report_dir}/images/`

-

- 目标：把 `synthesis.md` 中已经想清楚的结论，转成面向目标读者的图文报告。

- ### 生成流程

- 不要先写完整正文再事后补图。先设计读者理解路径，再同步规划正文、表格、图表和 AI 配图。

- 1. **确认读者任务**：从 `request.md` 和 `plan.json.scope` 判断读者要了解全貌、比较选项、调查对象、追踪事件、评估风险还是制定行动。

- 2. **提炼主线判断**：从 `synthesis.md` 抽出 2-5 条核心判断、证据强弱、关键冲突、不确定性和对原始问题的回答。

- 3. **搭建章节骨架**：优先遵循 `plan.json.report_shape.sections`；若缺失，按读者任务选择默认结构。每个主章节只回答一个关键问题。

- 4. **标注章节认知任务**：逐章判断读者需要比较、排序、追踪、定位、归因、分层、决策还是建立语境。

- 5. **制定并落盘视觉计划**：为候选视觉节点写明 `slot`、`purpose`、`type`、`content_source`、`must_have`，并写入 `{report_dir}/visual_plan.md`；不要把视觉计划写入 `report.md`。长报告默认安排 2-4 个视觉元素，复杂报告可安排 4-7 个。

- 6. **先落关键图表**：对供应链、传导机制、风险路径、情景矩阵、趋势数据等强结构内容，先做表格或 Mermaid，再写解释，以便暴露逻辑缺口。

- 7. **嵌入视觉元素**：每张图表前说明为什么看它，图表后提炼读者应带走的判断；视觉元素必须贴近解释它的段落或章节，不要集中堆在文末。

- 8. **生成 AI 配图**：对视觉计划中选为 AI 图片的概念图、场景图、封面图、地理/产业图景，调用 `sn-image-base` 生成文件并嵌入。

- 9. **自检并写入**：确认结构完整、结论清楚、`visual_plan.md` 已落盘、视觉类型合理、图片路径可解析，再写入 `report.md`。

- 如果写作时发现关键事实缺口导致主线无法成立，回到对应研究或综合阶段；不要硬写。

- ### 默认结构

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

- - **全景研究**：摘要 -> 背景与范围 -> 核心发现 -> 分维度分析 -> 综合判断 -> 风险与不确定性 -> 下一步。

- - **对比选型**：摘要与推荐 -> 评估背景 -> 对比矩阵 -> 逐维度分析 -> 场景化建议 -> 风险与限制。

- - **实体调查**：执行摘要 -> 对象概览 -> 关键维度审查 -> 重大风险/机会 -> 综合评价 -> 后续关注。

- - **事件追踪**：摘要 -> 时间线 -> 各方立场 -> 影响分析 -> 后续走向 -> 不确定性。

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

- ## 视觉规划

- 第一性原理：先判断读者面对某段内容要完成的认知任务，再选图。图形的职责是降低比较、排序、追踪、定位、归因、分层、决策或记忆成本。

- | 认知任务 / 内容结构 | 最适合的视觉形式 | 使用要点 |

- |---|---|---|

- | 精确查数、多个对象多个指标比较 | Markdown 表格 | 需要保留精确数字、口径、证据强弱时优先表格 |

- | 排名、规模差异、单指标横向比较 | Mermaid `xychart-beta` 柱状图，或表格 | 对象超过 8 个时优先表格；少量对象可用柱状图强化差距 |

- | 时间趋势、价格/产量/份额变化 | Mermaid `xychart-beta` 折线/柱状图 | 只在有明确时间点和数值时使用 |

- | 事件先后、政策演进、危机升级过程 | Mermaid `timeline` 或时间线表 | 事件多且需要日期时用时间线表；强调阶段变化时用 `timeline` |

- | 组成占比、份额结构 | Mermaid `pie` 或表格 | 类别不超过 5 个且合计口径清楚时用饼图；否则用表格 |

- | 流程、产业链、供应链、传导机制 | Mermaid `flowchart` | 用箭头表达方向、瓶颈和传导节点；避免把长段文字塞进节点 |

- | 因果链、反馈回路、风险扩散路径 | Mermaid `flowchart` 或因果链示意 | 明确触发条件、放大机制和结果；复杂回路可拆成多段 |

- | 组织、角色、国家/企业关系网络 | Mermaid `graph` | 表达谁影响谁、谁依赖谁；关系过密时改成分组表 |

- | 情景分析、风险矩阵、二维判断 | Markdown 矩阵表；必要时 Mermaid `quadrantChart` | 需要概率、影响、触发条件时优先矩阵表；四象限只用于快速定位 |

- | 决策路径、应对策略选择 | Mermaid `flowchart` 或决策树 | 用于“如果 A 则 B”的行动建议，不用于罗列普通建议 |

- | 地理位置、战略通道、物流路径 | 真实地图/可核验示意优先；无地图数据时用 Mermaid 示意或 AI 概念图 | AI 图只能建立空间语境，不能承担精确地图职责 |

- | 架构、系统分层、能力框架 | Mermaid `flowchart`、分层框架图或表格 | 分层清晰时用框架图；维度和说明多时用表格 |

- | 抽象主线、封面、章节开场、行业图景 | AI 概念图 | 用来建立语境和记忆锚点；不承载精确事实、数字或地图 |

- | 对比前后状态、演化路径 | 并列表格、时间线或 Mermaid `flowchart` | 需要精确差异用表格；强调转变过程用流程图 |

- | 不确定性、证据强弱、假设边界 | 表格、风险矩阵或范围说明 | 避免用单一确定图形制造过度确定的错觉 |

- 视觉计划必须单独写入 `{report_dir}/visual_plan.md`，不要写入 `report.md`。`report.md` 只保留实际交付给读者的正文、表格、Mermaid 图和图片引用；`visual_plan.md` 用作生成过程记录和质量检查依据。

- `visual_plan.md` 建议格式：

- ```markdown

- # Visual Plan

- ## Context

- - report: report.md

- - purpose: 一句话说明视觉规划服务的读者任务

- - status: planned / partially_applied / applied

- ## Plan

- | slot | purpose | type | content_source | must_have | output |

- |---|---|---|---|---|---|

- | 执行摘要后 | 建立报告整体语境 | AI 概念图 | 主线判断 | 可选 | images/overview.png |

- | 第二章开头 | 展示市场结构或战略通道 | Mermaid 示意图 / AI 概念图 | 子报告 d2 | 必须 | report.md 内 Mermaid |

- | 供应影响章节 | 展示冲击传导路径 | Mermaid `flowchart` | 子报告 d3 | 必须 | report.md 内 Mermaid |

- | 情景分析章节 | 比较概率、冲击和触发条件 | Markdown 矩阵表 | synthesis + 子报告 d5 | 必须 | report.md 内表格 |

- ## Notes

- - 记录为什么选择或放弃 AI 图、Mermaid、表格。

- - 如视觉计划在写作过程中调整，更新本文件，而不是把调整过程写进 `report.md`。

- ```

- 计划表字段：

- | 字段 | 含义 |

- |---|---|

- | `slot` | 视觉元素插入或支撑的章节位置 |

- | `purpose` | 这张图/表帮助读者完成什么认知任务 |

- | `type` | Markdown 表格、Mermaid 图、AI 概念图等 |

- | `content_source` | 来自 `synthesis.md`、某个子报告、原稿段落或用户材料 |

- | `must_have` | 必须 / 可选 |

- | `output` | 最终落点，例如 `report.md 内 Mermaid`、`report.md 内表格`、`images/xxx.png`、`放弃：原因` |

- 视觉规则：

- - 每个主章节通常最多放 1 个视觉元素；信息密度高的章节可放 2 个，且类型要互补。

- - 有明确数据、比较、流程、时间线或关系结构时，使用表格或 Mermaid，保证内容可校验。

- - 当目标是建立语境、呈现地理/产业图景、解释抽象主线或作为封面/章节开场时，可以使用 AI 概念图。

- - 不要默认排除 AI 图；如果章节缺少数据但需要直观语境，应考虑 AI 概念图。

- - 不要为了好看生成图片；每个视觉元素必须解释章节主判断、降低理解门槛或建立报告语境。

- - 如果最终没有任何 AI 图片，必须是视觉计划判断所有候选位置更适合表格、Mermaid 或文字，而不是省略生图步骤。

- ### Mermaid 插入格式

- 在 `report.md` 中直接使用 fenced code block 插入 Mermaid。图前用 1-2 句话说明读者为什么要看这张图，图后提炼应带走的判断。不要只给图不解释，也不要把大量长句塞进节点。

- Mermaid 配色遵循：白底、浅灰蓝边框、深青绿主强调、蓝色辅助、橙红表示约束或风险。颜色必须有语义，不做装饰。

- | class | fill | stroke | color | 语义 |

- |---|---|---|---|---|

- | `core` | `#eef7f5` | `#0f766e` | `#134e4a` | 核心判断、主变量、结论 |

- | `support` | `#eef4f8` | `#2563eb` | `#17324d` | 支撑因素、传导环节、技术模块 |

- | `neutral` | `#ffffff` | `#dbe2ea` | `#1c2430` | 普通对象、中性节点 |

- | `muted` | `#f7f8fb` | `#94a3b8` | `#475467` | 次要信息、背景信息 |

- | `warning` | `#fff7ed` | `#c2410c` | `#7c2d12` | 约束、瓶颈、成本压力 |

- | `risk` | `#fff1f0` | `#b42318` | `#7a271a` | 风险、冲突、负面冲击 |

- 使用规则：

- - 一张图最多使用 3-4 类颜色。

- - 主线用 `core`，传导用 `support`，普通节点用 `neutral`。

- - 约束用 `warning`，真实风险用 `risk`。

- - 同类节点同色；不要给每个节点单独配色。

- 示例：

- ````markdown

- 下图用于说明冲突如何通过航运、保险和预期三个渠道传导到油价，而不是表示精确量化幅度。

- ```mermaid

- flowchart LR

- A[地区冲突升级] --> B[霍尔木兹通道风险上升]

- B --> C[油轮绕行与运费上升]

- B --> D[保险费率上升]

- A --> E[市场风险溢价抬升]

- C --> F[到岸成本上行]

- D --> F

- E --> G[原油期货价格波动加剧]

- F --> H[炼化与终端燃料成本承压]

- G --> H

- classDef core fill:#eef7f5,stroke:#0f766e,color:#134e4a,stroke-width:1.5px;

- classDef support fill:#eef4f8,stroke:#2563eb,color:#17324d,stroke-width:1.2px;

- classDef warning fill:#fff7ed,stroke:#c2410c,color:#7c2d12,stroke-width:1.2px;

- classDef risk fill:#fff1f0,stroke:#b42318,color:#7a271a,stroke-width:1.2px;

- class A risk;

- class B,E warning;

- class C,D,F,G support;

- class H core;

- 读者应带走的判断是：短期价格冲击未必来自实际供应中断，航运成本、保险成本和风险溢价也会先行放大波动。

- ````

- ## AI 配图

- 需要 AI 配图时，依赖并使用已注入的 `sn-image-base` skill。请查阅 `sn-image-base` 的使用说明，并按它当前公开的接口调用 `sn-image-generate`。

- 依赖规则：

- 1. 需要生成图片时，先查阅 `sn-image-base` 的 `SKILL.md`；如需精确参数，再查阅它的 `reference/api_spec.md`。

- 2. 使用 `sn-image-base` 暴露的 `sn-image-generate` 能力实际生成图片文件。

- 3. 保存路径必须位于 `{report_dir}/images/`，并在 `report.md` 中使用相对路径嵌入。

- 4. 如果当前运行环境无法加载或调用 `sn-image-base`，不要假装已生成图片；说明依赖不可用，并询问用户是否修复依赖或改用 Mermaid/表格替代。

- 生成每张图前先确定：

- - `slot`：插入位置，例如“摘要后”或“第二章：市场结构开头”。

- - `purpose`：这张图帮助读者理解什么。

- - `alt`：Markdown alt 文本。

- - `filename`：保存到 `{report_dir}/images/` 的文件名，小写字母、数字和连字符，例如 `market-structure.png`。

- - `prompt`：图像提示词，包含主题、构图、风格、禁用文字或少文字要求。

- 调用命令：

- ```bash

- mkdir -p <report_dir>/images

- python3 <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" \

- --output-format json

-

- 调用后确认文件存在且非空，再写入 `report.md`：

-

- ```markdown

- 

- 失败处理：

-

- - 不要留下失效图片链接。

- - 缺少 API key、base URL、model 或其他必要配置时，先询问用户提供配置，或确认是否改用 Mermaid/表格替代。

- - 优先改用 Mermaid、表格或文字说明。

- - 在最终回复中说明失败原因和替代方式。

- ## 写作修改模式

- 输入：

- - 现有草稿文件；或

- - 一段待修改文本；或

- - 用户明确的修改要求 + 原始文稿路径。

- 可选补充：目标读者、目标长度、语气、保留/删除要求、希望增强的摘要/结构/表格/结论/逻辑/语言/过渡、supporting notes、素材文件或参考结构。

- 流程：

- 1. **识别修改目标**：判断用户是重写、压缩、扩写、润色、重组，还是组合任务。

- 2. **读取现有文稿**：理解主张、结构、信息密度和主要问题。

- 3. **锁定不变项**：识别必须保留的事实、观点、术语、口径和结构约束。

- 4. **决定改写粒度**：小改处理摘要/段落/标题/语句；中改处理章节重组和表格化；大改整体重写但保留事实边界。

- 5. **执行修改**：优先改结构和逻辑，再改语言和可读性；需要时补表格、清单、时间线或视觉元素。

- 6. **自检**：确认没有无依据新增关键事实，也没有误改原文立场。

- 7. **输出修改稿**：默认写回目标文件；如用户要求保留原稿，则输出到新路径。

- 原则：

- - 用户没有要求改观点时，不擅自改核心判断。

- - 用户没有提供新证据时，不擅自补新的关键事实。

- - 原文结构差时，先解决结构，再做逐句抛光。

- - 研究笔记可以重写成正式报告，但要保留原始不确定性。

- ## 质量门槛

- - 输出结构与 `plan.json.report_shape.sections` 或用户指定结构一致；若调整，说明原因。

- - 终稿生成模式下，主线判断来自 `synthesis.md`，不是写作时临时发明。

- - 写作修改模式下，修改结果忠于原文事实与核心判断，除非用户明确要求改变立场。

- - 主要判断能从 `synthesis.md`、子报告或用户提供文稿追溯。

- - 正文沿主线展开，不按材料顺序机械展开；相同事实不重复铺陈。

- - 结论标注确定性：已确认、较可能、存在争议、信息不足。

- - 冲突、不确定性和适用范围清楚呈现。

- - 已完成视觉计划，且已写入 `{report_dir}/visual_plan.md`；不要把视觉计划写进 `report.md`。

- - 已将表格、Mermaid 或图片放在能支撑正文判断的位置。

- - 视觉类型合理：数据不用 AI 图伪造，概念/场景/封面不强行写成复杂表格。

- - 视觉计划选中的 AI 配图已实际生成到 `{report_dir}/images/`，且 `report.md` 中相对路径可用。

- ## 常见失败

- - 没有 `synthesis.md` 也没有草稿，却硬写终稿。

- - 把写作修改变成重新研究。

- - 把子报告或原稿按顺序拼起来，缺少主线。

- - 摘要只有背景，没有判断。

- - 只讲结论，不讲条件和不确定性。

- - 逐句润色很多，但结构问题完全没解决。

- - 没有做视觉规划，导致报告只有文字和堆叠表格。

- - 只在上下文里临时规划视觉元素，没有把视觉计划写入 `{report_dir}/visual_plan.md`。

- - 明明适合图解的位置却没有插入任何视觉元素。

- - 用图片做装饰，不能帮助理解。

- - 只写“可加入配图”，但没有调用 `sn-image-base` 生成文件。

- - 生成了图片文件，却没有在 `report.md` 的合适章节嵌入。

- - 把 `sn-image-base` 名称、环境变量或命令写错，导致找不到依赖。