sn-research-report · diff
git:20260427.6d18553 to git:20260428.616e7c2
184 added, 166 removed. Audit A to A.
---
name: sn-research-report
- description: 研究报告写作与修改；当需要把 deep research 的判断层写成最终 `report.md`，或单独对已有报告/文稿做重写、改写、润色、重组结构、增强摘要、补充表格、规划插图并调用 `sn-image-base` 生成合适配图时使用。适用于完整终稿生成，也适用于已有草稿的定向编辑，不负责从零重新做研究综合判断。
+ description: 基于已有研究材料或草稿生成/修改最终 Markdown 研究报告的成稿 skill。遇到以下情况使用：①已有 deep research 产物 `synthesis.md`、`plan.json`、`sub_reports/*.md`，需要写成最终 `report.md`；②已有报告、草稿或文稿路径，需要重写、改写、润色、压缩、扩写、重组结构、增强摘要或补充表格/图示；③需要在报告成稿阶段主动规划并插入 Markdown 表格、Mermaid 图、AI 概念配图等视觉元素。仅用于终稿生成和文稿定向编辑；不用于从零调研、研究规划、联网取证、分维度研究或生成 `synthesis.md`。如果用户只是要求“深度研究/调研/写一份研究报告”且没有现成材料，应优先使用 `sn-deep-research`。
---
# Research Report
- 这个 skill 既可以用于：
+ 把已经形成的判断写成读者能使用的报告。报告不是材料拼接，而是围绕读者任务、主线判断、证据和不确定性组织出来的交付物。
- - **终稿生成模式**：把 deep research 的判断层转成最终交付。
- - **写作修改模式**：对已有报告、草稿、说明文、分析文做定向改写、重组、压缩、扩写或润色。
+ ## 适用模式
- 一句话区分：
+ 按顺序判断：
- - 有 `synthesis.md` 时，它负责把**已经想清楚的结论讲清楚**
- - 没有 `synthesis.md` 但有现成草稿时，它负责把**已有内容改得更清楚**
+ 1. 有 `{report_dir}/synthesis.md`、`plan.json`、`sub_reports/*.md`：走**终稿生成模式**，默认写入 `{report_dir}/report.md`。
+ 2. 没有完整研究链路，但有现成草稿、文稿路径或待修改文本：走**写作修改模式**，默认写回用户指定目标文件。
+ 3. 两者都缺：先要求输入文稿或研究材料，不要硬写。
- ## 任务边界
+ ## 边界
做：
- - 按给定结构、读者和用途组织报告。
- - 在终稿生成模式下，以 `synthesis.md` 为主输入写出 `report.md`。
- - 在写作修改模式下，基于现有草稿进行重写、压缩、扩写、重组、改写或润色。
- - 从 supporting notes、子报告或附加材料中抽取支撑内容。
- - 用表格、时间线、Mermaid 或图片提升可读性；需要 AI 配图时，调用 `sn-image-base` 生成图片并嵌入报告。
+ - 按读者、用途和结构约束组织报告。
+ - 在终稿生成模式下，以 `synthesis.md` 的判断层为主输入写出 `report.md`。
+ - 在写作修改模式下，忠于原稿事实和核心判断做重写、压缩、扩写、重组或润色。
+ - 从 supporting notes、子报告或附加材料中抽取表格、案例、数据、时间线和风险点。
+ - 主动规划视觉节点，并用表格、Mermaid 或 AI 图片降低理解成本。
- 清楚呈现条件、限制、冲突和不确定性。
不做：
- - 不在缺少依据时擅自新增关键事实或关键结论。
- - 不把写作修改变成重新做一轮研究。
- - 不把子报告或笔记逐段拼接成终稿。
- - 不把终稿写成内部工作笔记。
+ - 不在缺少依据时新增关键事实或关键结论。
+ - 不把写作修改变成重新研究。
+ - 不把子报告或笔记按顺序拼成终稿。
- 不写脚注、文末参考文献或来源编号。
-
- ## 依赖能力
-
- 需要 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 或其他必要配置，不要跳过、不伪造、不自行编造默认值，先询问用户提供对应配置。
-
- ## 输入模式
+ - 不用 AI 图片承载精确数字、坐标轴、表格或可核验地图。
- ### 模式 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`
+ 目标：把 `synthesis.md` 中已经想清楚的结论，转成面向目标读者的图文报告。
- ### 模式 B：写作修改
+ ### 生成流程
- 最小输入：
+ 不要先写完整正文再事后补图。先设计读者理解路径，再同步规划正文、表格、图表和 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`。
- 可选补充：
+ 如果写作时发现关键事实缺口导致主线无法成立，回到对应研究或综合阶段；不要硬写。
- - 目标读者
- - 目标长度
- - 期望语气
- - 想保留或想删掉的部分
- - 希望增强的内容：摘要、结构、表格、结论、逻辑、语言、过渡
- - supporting notes / 素材文件 / 参考结构
+ ### 默认结构
- 适用：
+ 优先遵循 `plan.json.report_shape.sections` 或用户指定结构。若两者都没有，按任务选择：
- - “把这份报告改得更清楚”
- - “帮我重写这个摘要”
- - “把这份分析改成正式报告”
- - “把这个草稿整理成对外可发版本”
- - “重组结构，不改核心观点”
+ - **全景研究**：摘要 -> 背景与范围 -> 核心发现 -> 分维度分析 -> 综合判断 -> 风险与不确定性 -> 下一步。
+ - **对比选型**：摘要与推荐 -> 评估背景 -> 对比矩阵 -> 逐维度分析 -> 场景化建议 -> 风险与限制。
+ - **实体调查**：执行摘要 -> 对象概览 -> 关键维度审查 -> 重大风险/机会 -> 综合评价 -> 后续关注。
+ - **事件追踪**：摘要 -> 时间线 -> 各方立场 -> 影响分析 -> 后续走向 -> 不确定性。
- ## 模式判定
+ 复合意图只保留一个主结构；次要意图压缩成章节或小节。
- 按下面顺序判断：
+ ## 视觉规划
- 1. 有 `synthesis.md`、`plan.json`、`sub_reports/*.md`：走**终稿生成模式**
- 2. 没有完整研究链路，但有现成草稿或待修改文本：走**写作修改模式**
- 3. 两者都缺：先要求输入文稿或研究材料，不要硬写
+ 第一性原理：先判断读者面对某段内容要完成的认知任务，再选图。图形的职责是降低比较、排序、追踪、定位、归因、分层、决策或记忆成本。
- ## 终稿生成模式
+ | 认知任务 / 内容结构 | 最适合的视觉形式 | 使用要点 |
+ |---|---|---|
+ | 精确查数、多个对象多个指标比较 | 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` 用作生成过程记录和质量检查依据。
- 把 `synthesis.md` 中已经形成的判断层，转成面向读者的最终交付。
+ `visual_plan.md` 建议格式：
- ### 执行流程
+ ```markdown
+ # Visual Plan
- 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` 正常解析。
+ ## Context
- 如果没有 `synthesis.md`，不要硬写终稿；先回到综合判断阶段。
+ - 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. **读取现有文稿**：先理解主张、结构、信息密度和主要问题。
- 3. **锁定不变项**：识别必须保留的事实、观点、术语、口径和结构约束。
- 4. **决定改写粒度**：
- - 小改：摘要、段落、标题、语句层面优化
- - 中改：章节重组、逻辑重排、表格化表达
- - 大改：整体重写，但保留原文核心内容和事实边界
- 5. **执行修改**：优先改结构和逻辑，再改语言和可读性。
- 6. **自检**：确认没有无依据新增关键事实，也没有误改原文立场。
- 7. **输出修改稿**：写回目标文件或用户指定路径。
+ 视觉规则：
- ### 修改原则
+ - 每个主章节通常最多放 1 个视觉元素；信息密度高的章节可放 2 个，且类型要互补。
+ - 有明确数据、比较、流程、时间线或关系结构时，使用表格或 Mermaid，保证内容可校验。
+ - 当目标是建立语境、呈现地理/产业图景、解释抽象主线或作为封面/章节开场时，可以使用 AI 概念图。
+ - 不要默认排除 AI 图；如果章节缺少数据但需要直观语境，应考虑 AI 概念图。
+ - 不要为了好看生成图片；每个视觉元素必须解释章节主判断、降低理解门槛或建立报告语境。
+ - 如果最终没有任何 AI 图片，必须是视觉计划判断所有候选位置更适合表格、Mermaid 或文字，而不是省略生图步骤。
- - 用户没有要求改观点时，不擅自改核心判断。
- - 用户没有提供新证据时，不擅自补新的关键事实。
- - 原文结构差时，优先解决结构，不先做逐句抛光。
- - 如果现有文本是“研究笔记”，允许重写成报告，但要保留原始不确定性。
+ ### Mermaid 插入格式
- ## 报告结构
+ 在 `report.md` 中直接使用 fenced code block 插入 Mermaid。图前用 1-2 句话说明读者为什么要看这张图，图后提炼应带走的判断。不要只给图不解释，也不要把大量长句塞进节点。
- 优先遵循 `plan.json.report_shape.sections` 或用户指定结构。若两者都没有，可按任务选择：
+ 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
- | 内容类型 | 推荐形式 |
- |---|---|
- | 多对象多指标比较 | Markdown 表格 |
- | 评估维度和权重 | Markdown 表格 |
- | 时间序列事件 | Mermaid `timeline` 或时间线表 |
- | 流程、产业链、因果链 | Mermaid `flowchart` |
- | 关系网络、组织关系 | Mermaid `graph` |
- | 趋势或份额，有明确数据 | Mermaid `xychart-beta` / `pie` |
- | 抽象概念、场景、封面、架构氛围 | AI 生图 |
+ 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;
+ ```
- 写终稿前先做一个轻量视觉计划，不需要写入 `report.md`，但必须指导正文：
+ 读者应带走的判断是：短期价格冲击未必来自实际供应中断，航运成本、保险成本和风险溢价也会先行放大波动。
+ ````
- - 每个主章节最多放 0-1 个视觉元素。
- - 有数据、流程、时间线或关系结构时，优先使用表格或 Mermaid。
- - 只有抽象概念、场景、封面、用户旅程、架构氛围、产业图景等无法用数据图准确表达时，才使用 AI 配图。
- - 不要为了“好看”生成图片；图片必须解释章节主判断、降低理解门槛或建立报告语境。
+ ## AI 配图
- 使用 AI 配图时：
+ 需要 AI 配图时，依赖并使用已注入的 `sn-image-base` skill。请查阅 `sn-image-base` 的使用说明，并按它当前公开的接口调用 `sn-image-generate`。
- - 只用于非数据驱动的概念图、场景图、封面图或架构示意。
- - 图片保存到 `{report_dir}/images/`，使用相对路径引用。
- - 同一份文稿图片风格要统一。
- - 只有确实帮助理解时才加图。
- - 每张图片必须紧贴它解释的段落或章节，不要集中堆在文末。
- - Markdown 格式使用 ``。
- - 配图文件名使用小写字母、数字和连字符，例如 `images/market-structure.png`。
+ 依赖规则：
- ### 调用 sn-image-base 生图
+ 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/` 的文件名。
- - `prompt`：英文图像提示词，包含主题、构图、风格、禁用文字或少文字要求。
+ - `filename`：保存到 `{report_dir}/images/` 的文件名，小写字母、数字和连字符，例如 `market-structure.png`。
+ - `prompt`：图像提示词，包含主题、构图、风格、禁用文字或少文字要求。
调用命令：
```bash
mkdir -p <report_dir>/images
- python "$SN_IMAGE_BASE/scripts/sn_agent_runner.py" sn-image-generate \
+ 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" \
- -o json
+ --output-format json
```
- 调用后确认文件存在且非空，再把相对路径写入 `report.md`：
+ 调用后确认文件存在且非空，再写入 `report.md`：
```markdown
```
- 如果生图失败：
+ 失败处理：
- 不要留下失效图片链接。
- - 如果失败原因是缺少 API key、base URL、model 或其他必要配置，先询问用户提供配置，或确认是否改用 Mermaid/表格替代。
+ - 缺少 API key、base URL、model 或其他必要配置时，先询问用户提供配置，或确认是否改用 Mermaid/表格替代。
- 优先改用 Mermaid、表格或文字说明。
- 在最终回复中说明失败原因和替代方式。
- ## 输出
+ ## 写作修改模式
- ### 终稿生成模式
+ 输入：
- 默认写入 `{report_dir}/report.md`
+ - 现有草稿文件；或
+ - 一段待修改文本；或
+ - 用户明确的修改要求 + 原始文稿路径。
- ### 写作修改模式
+ 可选补充：目标读者、目标长度、语气、保留/删除要求、希望增强的摘要/结构/表格/结论/逻辑/语言/过渡、supporting notes、素材文件或参考结构。
- 默认覆写用户指定目标文件；如果用户要求保留原稿，则输出到新路径。
+ 流程：
+ 1. **识别修改目标**：判断用户是重写、压缩、扩写、润色、重组，还是组合任务。
+ 2. **读取现有文稿**：理解主张、结构、信息密度和主要问题。
+ 3. **锁定不变项**：识别必须保留的事实、观点、术语、口径和结构约束。
+ 4. **决定改写粒度**：小改处理摘要/段落/标题/语句；中改处理章节重组和表格化；大改整体重写但保留事实边界。
+ 5. **执行修改**：优先改结构和逻辑，再改语言和可读性；需要时补表格、清单、时间线或视觉元素。
+ 6. **自检**：确认没有无依据新增关键事实，也没有误改原文立场。
+ 7. **输出修改稿**：默认写回目标文件；如用户要求保留原稿，则输出到新路径。
+
+ 原则：
+
+ - 用户没有要求改观点时，不擅自改核心判断。
+ - 用户没有提供新证据时，不擅自补新的关键事实。
+ - 原文结构差时，先解决结构，再做逐句抛光。
+ - 研究笔记可以重写成正式报告，但要保留原始不确定性。
+
## 质量门槛
- - 输出结构与给定结构约束一致，或说明为什么调整。
- - 终稿生成模式下：主线判断来自 `synthesis.md`，而不是写作时临时发明。
- - 写作修改模式下：修改结果忠于原文事实与核心判断，除非用户明确要求改写立场。
- - 主要判断都能从 `synthesis.md`、子报告或用户提供文稿追溯。
- - 关键对比优先使用表格，而不是长段落堆叠。
- - AI 配图已实际生成到 `{report_dir}/images/`，且 `report.md` 中的相对路径可用。
- - 图片出现的位置与它解释的章节相邻，不集中堆在开头或结尾。
+ - 输出结构与 `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` 名称、环境变量或命令写错，导致找不到依赖。