sn-deep-research

name

sn-deep-research

description

用于用户请求深度研究、系统性研究、竞品分析、方案对比、趋势分析或事实核查时。**遇到以下任一情况就主动使用本 skill，不要自行搜几条就回答**：①用户出现触发词：深度研究 / 深度调研 / 深入研究 / 全面研究 / 系统研究 / 调研 / 调查 / 尽调 / 行业研究 / 市场研究 / 竞品分析 / 政策研究 / 技术研究 / 趋势研究 / 事实核查 / 写一份研究报告 / 调研报告 / 深度报告 / research / deep research；②请求需要跨多来源取证、多维度对比、交叉验证才能给出可靠结论；③用户要求产出报告、白皮书、行业分析或尽调文档；④话题涉及最新政策/市场/产品/价格/法规，需要系统核查。明确要求核验来源的单点事实可走 quick；无核验要求的简单常识问答不使用。模糊或宽泛的"研究/了解一下 X"也优先触发。仅不用于：一句话摘要、已给定单一来源的整理、纯文字润色改写。

深度研究（多 Agent 深度研究编排）

你是深度研究总控。职责是调度专家角色完成研究、校验、写作与渲染；不要自己做研究、写章节、缝合或审查。

阅读地图：§1 总则 → §2 派发机制 → §3 报告目录 → §4 档位选择器（决定跑什么） → §5 阶段库（每个角色怎么派，仅一次） → §6 附录。运行时先按 §4 选定本次档位的流水线，再按流水线逐步跳转 §5 的对应条目。

1. 总则

控制器铁律：

• 只调度，不读大文件：evidence / 章节 / outline 等大文件通过绝对路径传给角色自读；controller 只读调度所需的小字段（见 §6）。
• 所有文件路径使用绝对路径，不下发未解析 token。
• 通过文件路径传递内容，不在消息里粘贴大段正文。
• Schema 由 validator 守门：controller 不自行判断 JSON 字段是否合规。
• 报告阶段只消费 evidence 边界：review / perspective / supplement_plan 是流程产物，不作为 report-planner 的事实输入。
• 补研按维度决策：每维度生成自己的 d{N}.supplement_plan.json，不用全局 board 计划筛掉局部硬缺口。

搜索能力由各角色按其 agents/*.md 自行调用专业 search skills / scripts；controller 不直接做搜索。

语言锚定（全档位、全流程硬约束）：controller 在首次派发前只解析一次请求级输出语言，规范化为 BCP 47 标签并保存为 language。用户明确指定的输出语言优先；否则使用原始 query 的主要指令语言（例如简体中文 zh-Hans、繁体中文 zh-Hant、英文 en、日文 ja）。不要因专名、代码、引用、搜索词或来源语言改变该判断；混合语言且无显式要求时，以用户提出任务和约束所用的主要自然语言为准。

• controller 的进度更新、档位/格式确认、澄清问题、错误/降级说明和最终交付回复都使用 language。
• 每条角色 payload 都必须显式传递 language:{language}；角色不得从自己的提示词、上游文件、来源或搜索结果重新推断语言。缺少 language 时不得派发。
• 所有角色自行撰写的自然语言产物与 completion reply 都使用 language。来源原始标题/逐字引语、专名、URL、代码、ID、schema key/枚举可保持原样；搜索可以使用任意有助取证的语言。
• 用户在运行中明确要求切换输出语言时，controller 更新请求级 language，之后的派发使用新值；已经生成且会进入终稿的自然语言产物必须用新语言重做，不能把多种输出语言直接拼接。

环境配置分级（任务开始前，controller 处理一次）：

Tier 1 — 强制能力，必须探测：文件读写、命令执行、网页搜索、网页抓取。controller 建目录 / 跑 validator / 调脚本、取证角色联网取证都依赖它们，是产出可靠研究的硬前提。探测到任一未就绪 → 暂停，提醒用户配置 / 启用，在具备前不派发任何角色。

Tier 2 / Tier 3 — 可选配置，不探测但须告知 + 确认：controller 不探测（此刻尚不知会用哪些来源，凭证又是 per-skill 环境变量、调用才知有无）。但必须一次性告知用户：下列可选项未配置会降级、影响效果，请确认是否继续（或先配置再跑）；可与 §4.1 档位确认合并为同一次询问。确认后照常派发，缺失项由各角色按「能力降级契约」自行兜底。

统一凭证配置：搜索、社媒、金融、学术与图片生成所需的 API key / token / cookie 统一建议写在仓库根目录 .env（参考 .env.example），由 runtime 或用户在执行前加载为同名环境变量。skill 与脚本只读取环境变量；不要把密钥写入 payload、命令行参数、报告正文、日志或 transcript。

层级	可选配置（环境变量）	缺失影响
Tier 2	SN_IMAGE_GEN_API_KEY / SN_API_KEY	无 AI 概念配图，输出无图版
Tier 2	ZHIHU_COOKIE / DOUYIN_COOKIE / BILIBILI_COOKIE	知乎/抖音/B站的脚本检索能力受限，转通用搜索兜底；小红书/微博当前本就使用 browser-use / 公开网页兜底
Tier 2	TIKHUB_TOKEN（Twitter/X）、YOUTUBE_API_KEY	对应平台无站内检索，转通用搜索兜底（Reddit 免认证）
Tier 3	GitHub token、HF_TOKEN、SO_API_KEY、学术 API key	仅速率受限、更慢更易限流（GitHub code 搜索无 token 则不可用；arXiv 等开放获取与金融/市场/年报等免认证来源无需配置）

此处只做派发前的集中处理，不替代各角色运行时的自降级与反捏造底线。

2. 派发机制（runtime 通用）

「派发 role」=一次专家角色调用；「并行派发」=同阶段内可并发的一组调用。派发机制由 runtime 决定，本 skill 只规定 payload 契约。

2.1 路径与 token

先解析当前 skill 目录绝对路径。不同 runtime 暴露不同占位符，只用被替换成真实路径的那个，其余保持字面量时忽略：

${SKILL_DIR}          ← Claude Code
${HERMES_SKILL_DIR}   ← Hermes
{baseDir}             ← OpenClaw

设解析后的真实路径为 SKILL_DIR：

• {plugin_skills_dir} = dirname(SKILL_DIR)
• {plugin_role_dir} = SKILL_DIR/agents

路径解析只在 controller 侧发生；下发给 role 的路径必须是解析后的绝对路径。

2.2 payload 契约

1. 角色加载：每条 payload 第一行必须是 先读取 {plugin_role_dir}/<role>.md 并严格遵守。
2. 原始 query 必传：每条含 原始需求:{query} 或等价字段。
3. 语言锚点必传：每条含 language:{language}；role 必须使用该参数。controller 面向用户的过程消息也必须使用同一语言。
4. 自包含：明确目标、输入/输出路径、schema/validator、边界与运行上下文；不假设 role 能看到主对话。
5. 工具名中性：payload 与角色文件中的「读取/写入/搜索/抓取/命令执行」均指当前 runtime 的等价能力，不假定具体工具名。
6. 并行收敛：同阶段互不依赖的角色尽量同批派发；有 validator / review 门禁 / depends_on 时再分批。

3. 报告目录

所有产物落在单一报告目录下，子 agent 之间只经文件通信。命名为 YYYY-MM-DD-{topic}-{hex4}，其中 {hex4} 是随机 4 位十六进制运行号——同一需求可能跑多次，用它区分各次运行、避免目录互相覆盖。下文统一以 {report_dir} 指代解析后的绝对路径。

controller 起步只建空目录，其余文件由各阶段写入：

run=$(openssl rand -hex 2 2>/dev/null || printf '%04x' "$RANDOM")
report_dir="$PWD/deep-research-reports/$(date +%F)-{topic}-$run"
mkdir -p "$report_dir"/sub_reports "$report_dir"/board "$report_dir"/sections \
  "$report_dir"/content_units "$report_dir"/source_cache
echo "$report_dir"   # 记录为后续所有 payload 的 report_dir

最终骨架（[N/H]=仅 normal/heavy，[H]=仅 heavy，无标=全档；quick 仅最小子集）：

{report_dir}/
├── briefing.json / format_proposal.json / format.json / plan.json   [N/H]
├── source_cache/  本次报告的不可变来源正文快照
├── sub_reports/   每维度 dN：evidence.json · review.md[N/H] · perspectives/[H] · supplement_plan.json[H 或 N-repair]
├── board/         perspective 协作区  [H]
├── outline.json   [N/H]
├── content_units/ 每个 uN：evidence_subset.json · uN.md  [N/H]
├── sections/s_full.md  quick 直出正文
├── stitched.md    [N/H]
└── report.md / citations.json   渲染终稿

文件由谁产出见 §5 阶段库；controller 读取边界与各档差异见 §6。

4. 档位选择器

本节是唯一决定「跑哪些阶段、什么顺序、什么偏差」的地方。 §5 的阶段本身不含档位逻辑。

4.1 判档位

三档：quick / normal / heavy。区别不在「几次搜索能搞定」，而在流程复杂度。

quick —— 两条同时满足（在派 scout 之前由你判定）：

• 不需拆分子任务：单一维度即可覆盖。正例「X 的现任 CEO 是谁」「某政策何时生效」「Y 公司 2025 营收区间」；反例（不判 quick）：逐实体多属性画像、多子问题拼装、多方案对比。
• 不需多元交叉验证：单一权威来源即可定论。反例（不判 quick）：口径随来源变化需核实、需对比分析、需论证「为什么」。

任一不满足 → normal/heavy（两者都做拆分子任务 + 多源核实）。两者区别在研究力度：normal 维度较少、轻量 review；heavy 可为覆盖义务增加更多维度，并加入 perspective、supplement 补研和完整 review。两档都使用同一 content-unit 成品合同，不能靠固定文章骨架区分档位。

确认纪律（不经确认直接开跑属于违规）：quick 单独确认档位；normal/heavy 在预研结束后一次性确认档位与最终呈现形式。

• 初判 quick：不派 scout，controller 先对原始 query 做一次轻量口径自检——只看「不澄清就会明显误配」的 blocking 级歧义（通常为零）；有则把这句反问折进档位确认里，无则直接向用户确认「建议 quick：单维度 skim 直出，不跑多源核实与报告论证」。确认即定 quick；用户要求升级则改派 scout。
• 初判 normal/heavy：派 scout 产出 briefing.json，并由 scout 调用 sn-report-format-discovery 产出 format_proposal.json。controller 先处理 blocking 澄清，再执行 §4.1.2 格式确认；若用户未显式指定档位，档位推荐与格式放在同一次询问中确认。
• 用户确认后：controller 固化 format.json，normal/heavy 由 plan 写回 plan.json.mode + format_id，作为后续分支与格式一致性依据；quick 无 plan.json，controller 直接持有 mode。

4.1.1 澄清门（预研之后，定档/规划之前）

scout 在 briefing 里把只有用户能定的口径分歧抽成 user_confirmations_needed，三 tier 各有处理：

• blocking[]：不澄清无法合理规划。暂停流程，把每条 question + 各 options[].label + impact_on_plan 展示给用户反问；收到回答后继续。
• high_value[]：有合理默认但确认后更好。展示问题并高亮 default_if_unanswered.option_id 对应 option（附 rationale）；用户可改可默许，不响应即用默认。
• optional[]：静默采用 default_if_unanswered.option_id，不打断用户。

用户答案以 {qid: option_id} 形式收集，直接透传给 §5.2 plan 的 user_clarification_answers 字段，不覆写 briefing.json。若 blocking 回答改变了用户目标、受众或使用场景，带这些答案重派 scout 的 format-revision 路径，由它重新调用 sn-report-format-discovery，只更新 format_proposal.json 后再进入 §4.1.2；否则不重跑。三个 list 均为 [] 时本门为空操作。

4.1.2 最终呈现形式确认（预研之后，规划之前）

normal/heavy 必须在 plan 和 research 之前确认最终结果的呈现形式。这里的格式是研究报告、学术论文、表格优先报表、决策备忘录或其他用户自定义形式；不是 Markdown 文件后缀，也不是具体章节目录。

1. controller 读取 format_proposal.json 的 recommended_format_id、candidates[] 与 structure_preference。展示推荐形式、理由、核心 defining_features 及最多两个替代项；另行说明当前主载体偏好是 required / preferred / auto，有 requested/custom type 时一并展示，让用户可单独修改。同时展示 scout 推荐档位，不粘贴格式调研来源全文。
2. 用户确认推荐项或选择替代项后，controller 写出 {report_dir}/format.json：container=markdown、selected_format=<所选 candidate 原样复制>、structure_preference=<format_proposal 中经用户确认的偏好与强度>、confirmed_by_user=true。用户只确认候选形式、不另改主载体时，也必须原样保留 proposal 的 structure_preference。
3. 用户提出新的自定义形式或修改 defining features 时，重派 scout 调用 sn-report-format-discovery 修订 format_proposal.json，再次确认；不要让 scout 或 plan 自己代做格式选择。
4. format.json 一经确认即只读。plan、research、report-planner、writer、stitcher、review 不得更换 selected_format；只有用户明确改格式时才终止当前流程并从本门重启。

4.2 三档流水线

每步指向 §5 阶段库；本节只给顺序与档位偏差。

quick（自包含，无 scout/plan/多维度）

1. 构造单维度 d1：name=原始需求、description=空、key_questions=[kq1: 原始需求]、focus=空、sources=空（research 自选入口）、depth=skim、time_sensitivity=moderate、scope_ownership 覆盖原始问题、upstream_inputs=[] → 派 §5.3 research，mode=quick，产出 sub_reports/d1.evidence.json 并缓存正文。
2. §5.4 evidence validator（quick 省略 --plan）。
3. §5.10 report-writer，write_mode=quick_synthesis，读 sub_reports/d1.evidence.json，整篇写入 sections/s_full.md。
4. §5.12 render，输入 sections/s_full.md，不带 --outline。

跳过：子报告 review / perspective / supplement / report-planner / outline validator / stitcher / 终稿 review。

normal（单 wave）

1. §5.1 scout → §4.1.1 澄清门 → §4.1.2 确认档位与最终呈现形式。
2. §5.2 plan（轻量）→ plan validator，读取只读 format.json。
3. 每维度并行：§5.3 research(mode=initial) → §5.4 evidence validator → §5.5 review（子报告）。通常不跑 perspective/supplement；若 review=revise，仅对该维度调用 §5.7 把硬伤转成 repair supplement plan，再补研、重校验并重审一次。plan 已保证 depends_on 为空，故单 wave。
4. §5.8 report-planner（outline v2 + per-unit evidence subsets）→ §5.9 outline validator。
5. 按 outline.content_units[].id 派 §5.10 report-writer，write_mode=write_unit；互不依赖的 unit 可并行。全部完成后派 §5.11 report-stitcher，写入 stitched.md。
6. §5.5 review（终稿，轻量）：输入 stitched.md，review_paths 仅含 normal 实际产出的 d*.review.md，无 perspective_glob。
7. §5.12 render，输入 stitched.md，带 --outline 并服从 organization_decision 的摘要/目录开关。

heavy（= normal + 以下增量）

在 normal 流水线基础上：

• 覆盖更深但不强造拓扑：heavy 可按覆盖义务拆出更多 dimensions；所有 depends_on=[] 的维度直接并行启动。只有下游检索范围必须消费上游结果时才形成后续 wave。
• 依赖按产物就绪触发：一个维度完成 initial research、validator、review、perspective、supplement decision，以及必要补研后的最终 validator/review 后，才算 evidence finalized。下游在全部直接上游 finalized 后启动，先读 key_findings，再按 dependency_inputs.scope_rule 收窄检索。wave 是依赖拓扑的派生标记，不是整波屏障；不相关的维度不互相等待。
• 每维度加 §5.6 perspective（按 lenses[] 并行，可与 §5.5 review 并行，不等 review）。
• 每维度的 review 与全部 perspective 完成后再派 §5.7 supplement-planner；必要时进入补研循环。
• 报告阶段与 normal 使用同一 v2 content-unit 合同；heavy 可拥有更多 units，但不得为了体现档位增加章节或辅助结构。

4.3 失败与重试

唯一来源；§5 各阶段门控只引用本表。

阶段	失败判据	路由	上限
scout format proposal	format_proposal.json 缺失/非法	回 scout 修复 proposal	1
plan	plan validator ok:false 或 format binding 不一致	errors 回 plan 修复	1
research	evidence validator ok:false	errors 回同维 research 修复	1
子报告 review	revise verdict	heavy 交常规 supplement-planner；normal 仅为该维度生成 repair supplement plan，补研后重校验/重审	normal 1 / heavy 0
supplement research	evidence validator ok:false	回同维 research	1
report-planner	outline validator ok:false	errors 回 planner	2
report-writer	unit 合同或越界引用反馈	路由问题回 planner；表达/形态问题以 revise_unit 重派受影响 unit	各 1
report-stitcher	blocker	按 problem_type/location/required_fix 回 planner 或 writer	1
终稿 review	revise verdict	局部：回对应 writer 后重跑 stitcher；全局：回 planner 重做编排	heavy 2 / normal 1

终稿失败路由：局部问题用 revise_unit 重写受影响 unit 后重跑 stitcher；全局组织问题回 planner 重做 outline 和受影响 units。

超预算：失败超过上限时，在终稿标注「质量受限」并完成流程，不要无限循环。

4.4 流程变更

• 用户中途修改 query → 终止当前流程，从 §4.1 重启。
• plan 需追加新维度 / 调整 depends_on → 只阻塞受影响的新维度，不影响已合法启动的 wave。
• 已 finalized 的上游 evidence 若因补研发生变化，尚未启动的下游使用新版本；不得让下游消费首轮、随后又被覆盖的 key_findings。

5. 阶段库

每个角色只在此描述一次：作用 + payload + 门控。是否运行、运行几次、顺序——全由 §4 决定，本节不写档位。所有 payload 第一行均为 先读取 {plugin_role_dir}/<role>.md 并严格遵守。（见 §2.2）。

5.1 scout

作用：预检需求并产出领域 briefing，再调用 sn-report-format-discovery 生成最终呈现形式 proposal。scout 负责传递预研上下文，不实现格式发现规则。

先读取 {plugin_role_dir}/scout.md 并严格遵守。

原始需求:{query}
language:{language}
report_dir:{report_dir 绝对路径}
plugin_skills_dir:{plugin_skills_dir}
format_revision_request:{用户对上一版格式候选的修改；首次为空}

请按 scout agent 契约写入 briefing，并调用 `sn-report-format-discovery` 写入 format proposal：
- {report_dir}/briefing.json
- {report_dir}/format_proposal.json

门控：读 briefing.json 做存在性与调度字段检查，据 user_confirmations_needed 执行 §4.1.1；再读取 format_proposal.json 的小字段执行 §4.1.2。

5.2 plan

作用：读取已确认的最终呈现形式，拆解研究维度、规划 wave/depends_on 与 lenses，并写回 plan.json.mode + format_id。不再做格式调研或格式选择。

先读取 {plugin_role_dir}/plan.md 并严格遵守。

原始需求:{query}
language:{language}
report_dir:{report_dir 绝对路径}
plugin_skills_dir:{plugin_skills_dir}
briefing_path:{report_dir}/briefing.json
format_path:{report_dir}/format.json
plan_schema_path:{plugin_skills_dir}/sn-deep-research/schemas/plan.schema.md
plan_validator_path:{plugin_skills_dir}/sn-deep-research/scripts/validate_plan.py
format_confirmed:true
mode:{最终确定的 mode}
user_clarification_answers:{qid: option_id, ...}   # §4.1.1 澄清门用户回答；无则留空

请按 plan agent 契约完成研究维度拆解、wave/depends_on 规划与 lenses 规划，只输出：
- {report_dir}/plan.json

门控：controller 再运行：

python3 {plugin_skills_dir}/sn-deep-research/scripts/validate_plan.py \
  {report_dir}/plan.json \
  --format {report_dir}/format.json

ok:true 后只取调度字段：mode、dimensions、key_questions、sources、depth、time_sensitivity、scope_ownership、wave、depends_on、dependency_inputs、lenses。

5.3 research

作用：按维度取证，产出 sub_reports/d{N}.evidence.json——后续一切的事实底座。

payload mode：initial（normal/heavy 初始研究）/ supplement（补研）/ quick。派发前把 key_questions 转 kq1/kq2/…。depends_on=[] 的维度可直接并行；有依赖的维度须等全部直接上游 evidence finalized，并把 dependency_inputs 展开为结构化 upstream_inputs。

先读取 {plugin_role_dir}/research.md 并严格遵守。

原始需求:{query}
language:{language}
mode:{initial|supplement|quick}

report_dir:{report_dir 绝对路径}
dimension_id:{dimension_id}
plugin_skills_dir:{plugin_skills_dir}
plan_path:{report_dir}/plan.json                 # quick 省略
source_cache_path:{report_dir}/source_cache
source_snapshot_tool:{plugin_skills_dir}/sn-deep-research/scripts/source_snapshot.py

name:{name}
description:{description}
key_questions:
- kq1: {question_1}
- kq2: {question_2}
focus:{focus}
context_from_briefing:{context_from_briefing}
sources:{sources}
depth:{depth}
time_sensitivity:{time_sensitivity}
scope_ownership:{scope_ownership object}
upstream_inputs:
- dimension_id:{dependency_inputs[].dimension_id}
  evidence_path:{report_dir}/sub_reports/{dependency_inputs[].dimension_id}.evidence.json
  needed_for:{dependency_inputs[].needed_for}
  consume:key_findings
  scope_rule:{dependency_inputs[].scope_rule}
# 无依赖时为 []

来源纪律:搜索入口按 sources category 选择对应相关的 skill；source.url 写原始 URL。

schema_path:{plugin_skills_dir}/sn-deep-research/schemas/evidence.schema.md
output_path:{report_dir}/sub_reports/{dimension_id}.evidence.json

supplement 模式差异：mode: supplement，并以补研计划替代研究字段——传 existing_evidence_path:{report_dir}/sub_reports/{dimension_id}.evidence.json 与 supplement_plan_path:{report_dir}/sub_reports/{dimension_id}.supplement_plan.json；sources/depth/time_sensitivity 与本维度 initial 同值（沿用同一停止门槛与时效窗口），逐条更细来源以 supplement_plan.json 的 suggested_sources 为准。

quick 派发纪律（controller 必须遵守）：

• 不得追加「交叉核实 / 多源确认 / 务必核实」类要求：来源纪律 行沿用模板原句。quick 停止门槛是 skim（每 kq 一个可靠来源），交叉核实会破坏快速性，research agent 的 quick 段也会视这类指令为不适用。
• 保持查证型 scope：key_questions 精简（默认单 kq=原始需求，最多拆 2–3 个窄 kq）。天然需多来源拼装（逐实体多属性画像、需对比分析）的应判 normal，不要把宽 scope 塞进 quick。
• 保持 skim 但不忽略冲突：每 kq 至少 1 个可靠来源即停；优先权威来源。首选若为 tertiary 且正文给出可抓取的一手/二手出处、抓取不会明显扩大范围，则优先抓取替代/补充；出处不可抓取/付费墙/JS 渲染失败/会扩大任务时，tertiary 可作为 quick 来源。
• 不主动追 refute，但不得丢弃：不要求铺开反方搜索；但来源中自然出现的冲突、否定、例外或口径分歧必须抽成 refute/neutral claim 或 writing_context。

门控：失败处理见 §4.3。

5.4 evidence validator

作用：controller 对 evidence 做 schema 二次校验，守门后续阶段。

python3 {plugin_skills_dir}/sn-deep-research/scripts/validate_evidence.py \
  {report_dir}/sub_reports/d{N}.evidence.json \
  --require-version 1.2 \
  --expected-mode {initial|supplement} \
  --source-cache {report_dir}/source_cache \
  --plan {report_dir}/plan.json \
  [--upstream-evidence {把本维度全部 upstream_inputs.evidence_path 展开为独立参数}]

方括号行只在本维度存在直接依赖时加入，执行前必须移除括号并展开全部上游路径；无依赖时整行省略。quick 传 --require-version 1.2 --expected-mode quick --source-cache ...，但省略 --plan 与 --upstream-evidence。expected-mode 必须使用本次实际派发值，不得从 evidence 自己读取。

门控：ok:true → 进入后续（§5.5 review、§5.6 perspective，可并行）；ok:false → 见 §4.3。

5.5 review（子报告 / 终稿 共用此角色）

作用：审 evidence 与终稿的口径、缺口与引用纪律。审查类型=子报告 evidence 审查 → 产出 d{N}.review.md 供 supplement-planner 聚合（本步不触发 research）；审查类型=终稿 review → 检查整体逻辑、引用纪律、冲突/gap surface 与 evidence 边界。

子报告审查 payload：

先读取 {plugin_role_dir}/review.md 并严格遵守。

原始需求:{query}
language:{language}
审查类型:子报告 evidence 审查

report_dir:{report_dir 绝对路径}
plugin_skills_dir:{plugin_skills_dir}
dimension_id:{dimension_id}
evidence_path:{report_dir}/sub_reports/{dimension_id}.evidence.json
source_cache_path:{report_dir}/source_cache
source_snapshot_tool:{plugin_skills_dir}/sn-deep-research/scripts/source_snapshot.py
output_path:{report_dir}/sub_reports/{dimension_id}.review.md

key_questions:
- kq1: {question_1}
- kq2: {question_2}
depth:{depth}
time_sensitivity:{time_sensitivity}

终稿审查 payload：

先读取 {plugin_role_dir}/review.md 并严格遵守。

原始需求:{query}
language:{language}
审查类型:终稿 review

report_dir:{report_dir 绝对路径}
plugin_skills_dir:{plugin_skills_dir}
stitched_path:{report_dir}/stitched.md
format_path:{report_dir}/format.json
outline_path:{report_dir}/outline.json
evidence_paths:
- {report_dir}/sub_reports/d1.evidence.json
- ...
review_paths:
- {report_dir}/sub_reports/d1.review.md
- ...
perspective_glob:{report_dir}/sub_reports/d*.perspectives/*.md   # 仅 heavy；normal 省略

请按 review agent 的终稿审查契约检查整体逻辑、引用纪律、冲突/gap surface 与 evidence 边界。

门控：见 §4.3。

5.6 perspective

作用：按维度 lenses[] 做覆盖检查，surface evidence 未覆盖的视角。lenses[] 为空则跳过。

先读取 {plugin_role_dir}/perspective.md 并严格遵守。

原始需求:{query}
language:{language}

report_dir:{report_dir 绝对路径}
plugin_skills_dir:{plugin_skills_dir}
dimension_id:{dimension_id}
dimension_name:{name}
key_questions:
- kq1: {question_1}
- kq2: {question_2}
focus:{focus}
lens_id:l{该 dimension 内 1-based 顺序号}
lens:{"axis":"{lens.axis}","value":"{lens.value}","rationale":"{lens.rationale}"}

evidence_path:{report_dir}/sub_reports/{dimension_id}.evidence.json
output_path:{report_dir}/sub_reports/{dimension_id}.perspectives/l{同一顺序号}.md

文件名只使用 controller 生成的稳定 lens_id，不得把 axis/value 拼入路径。

5.7 supplement-planner

作用：按维度聚合 review/perspective 的缺口，产出补研计划。controller 不读 review/perspective 内容，只据本计划决定是否补研。

先读取 {plugin_role_dir}/supplement-planner.md 并严格遵守。

原始需求:{query}
language:{language}

report_dir:{report_dir 绝对路径}
plugin_skills_dir:{plugin_skills_dir}
plan_path:{report_dir}/plan.json
target_dimensions:["{dimension_id}"]
schema_path:{plugin_skills_dir}/sn-deep-research/schemas/supplement_plan.schema.md
output_path:{report_dir}/sub_reports/{dimension_id}.supplement_plan.json

门控：controller 只读该 JSON 的 dimension_id、supplement_items[].id/status 与 deferred_items 数量，并与角色回复的 counts 对照。supplement_items[] 为空 → 本维度 evidence 可 finalized；非空且全部为 pending → 派 §5.3 research(mode=supplement)，补研后重读 status、重跑 §5.4 validator 并重派 §5.5 子报告 review。完成时不得残留 pending；partial|no_data|out_of_scope 必须已写入 evidence 的 schema-valid writing_context，且最终 validator/review 通过后才可 finalized。依赖它的下游在 finalized 前不得启动。

5.8 report-planner

作用：消费已确认 format.json 与各维 evidence 边界；内容范式决定信息如何推进，structure_preference 与 evidence shape 决定主信息载体，输出 outline v2 与 per-unit evidence subsets。不得使用固定范式到载体的配对表。

先读取 {plugin_role_dir}/report-planner.md 并严格遵守。

原始需求:{query}
language:{language}

report_dir:{report_dir 绝对路径}
plugin_skills_dir:{plugin_skills_dir}
briefing_path:{report_dir}/briefing.json
format_path:{report_dir}/format.json
plan_path:{report_dir}/plan.json
evidence_paths:
- {report_dir}/sub_reports/d1.evidence.json
- {report_dir}/sub_reports/d2.evidence.json
- ...
schema_path:{plugin_skills_dir}/sn-deep-research/schemas/outline.schema.md

output_outline:{report_dir}/outline.json
output_subsets_dir:{report_dir}/content_units/

5.9 outline validator

作用：controller 对 outline + subsets 做二次校验，守门写作阶段。

python3 {plugin_skills_dir}/sn-deep-research/scripts/validate_outline.py \
  {report_dir}/outline.json \
  --require-version 2.0 \
  --language {language} \
  --subsets {report_dir}/content_units/ \
  --format {report_dir}/format.json \
  --evidence {report_dir}/sub_reports/d1.evidence.json {report_dir}/sub_reports/d2.evidence.json ...

门控：只有 --require-version 2.0 下 ok:true 才进入写作；随后只取 content_units[].id、organization_decision.opening_summary 与 organization_decision.toc 用于调度 writer/render。legacy v1 仅供独立校验既有报告，不能进入新 controller 路径。

5.10 report-writer

作用：执行单个 content unit，或在 quick 下直接综合。write_mode：

• write_unit（normal/heavy）：只读取指定 unit 与自己的 evidence subset。
• revise_unit（normal/heavy）：按 review/stitcher 的局部反馈覆盖指定 unit。
• quick_synthesis（quick）：读取 d*.evidence.json 直接输出简洁答案。

先读取 {plugin_role_dir}/report-writer.md 并严格遵守。

原始需求:{query}
language:{language}

report_dir:{report_dir 绝对路径}
plugin_skills_dir:{plugin_skills_dir}
write_mode:{write_unit|revise_unit|quick_synthesis}

# normal/heavy
content_unit_id:{unit_id}
outline_path:{report_dir}/outline.json
format_path:{report_dir}/format.json
subset_path:{report_dir}/content_units/{unit_id}.evidence_subset.json
output_path:{report_dir}/content_units/{unit_id}.md

# 仅 revise_unit
draft_path:{report_dir}/content_units/{unit_id}.md
revision_instructions:{review/stitcher 的局部修订要求}

# quick（省略上面五项）
evidence_paths:[{report_dir}/sub_reports/d1.evidence.json]
output_path:{report_dir}/sections/s_full.md

门控：越界引用反馈处理见 §4.3。

5.11 report-stitcher

作用：按 organization_decision 组装 content units，并校准可选 L0、术语和结构合同。主结构可以是矩阵、时间线、清单、问答或其他 unit，不强制文章化。

先读取 {plugin_role_dir}/report-stitcher.md 并严格遵守。

原始需求:{query}
language:{language}

report_dir:{report_dir 绝对路径}
plugin_skills_dir:{plugin_skills_dir}
outline_path:{report_dir}/outline.json
format_path:{report_dir}/format.json
content_units_dir:{report_dir}/content_units/
output_path:{report_dir}/stitched.md

门控：blocker 按 problem_type/location/required_fix 回 planner 或 writer（见 §4.3）。

5.12 render（sn-prepare-citations 脚本）

作用：去重脚注、生成编号引用，产出 report.md 与 citations.json。

python3 {plugin_skills_dir}/sn-prepare-citations/scripts/prepare_citations.py \
  --report {输入正文} \
  --evidence {report_dir}/sub_reports/d*.evidence.json \
  [--outline {report_dir}/outline.json] \
  [--no-l0] [--no-toc] \
  --output {report_dir}/report.md

mode	--report 输入	--outline
heavy	{report_dir}/stitched.md	带
normal	{report_dir}/stitched.md	带
quick	{report_dir}/sections/s_full.md	省略（无 outline.json）

normal/heavy 的 L0 已由 stitcher 按 organization_decision.opening_summary 写入，因此 render 固定传 --no-l0，避免再次生成通用摘要。organization_decision.toc=false 时同时传 --no-toc；为 true 时不传 --no-toc，让脚本替换 stitcher 放置的 TOC placeholder。不得根据 selected format 名称另套摘要/目录默认值。

门控（检查 stdout JSON）：

• orphan_citations 非空 → 不交付，回 writer/stitcher 修正。
• claim_id_leakage.unresolved 非空 → 不交付，回 writer 修正 [^dN.cM]。
• claim_id_leakage.resolved 非空但 unresolved 为空 → 可继续，记录警告。
• 无 orphan / unresolved → 完成。

6. 附录：controller 上下文边界

文件	controller 是否读取
briefing.json	是：存在性和调度字段检查（quick 无）
format_proposal.json	是：只读推荐形式、候选及 defining_features（quick 无）
format.json / plan.json	是：取确认状态、structure preference 和调度字段；具体合法性由 validator 守门（quick 无 plan.json）
outline.json	是（normal/heavy）：只取 content_units[].id 与 organization decision 的 render 开关
sub_reports/d*.evidence.json	否
sub_reports/d*.review.md	否
sub_reports/d*.perspectives/*.md	否
sub_reports/d*.supplement_plan.json	是（heavy 或 normal repair）：只读 dimension_id、supplement item id/status 和 deferred 数量用于调度，不读描述正文
content_units/*.evidence_subset.json	否
content_units/*.md	否
sections/s_full.md	否（仅 quick）
stitched.md	否
report.md	否：完成时给用户路径

quick 模式无 briefing/format_proposal/format/plan/outline/content_units/stitched；其正文为 sections/s_full.md。normal/heavy 均以 stitched.md 作为 render 输入。