/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 起步先建报告目录**，随后写入 `request.md` 并启动进度页；其余文件由各阶段写入：

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}/
├── request.md     原始研究请求（启动进度页前必须存在）
├── .workbench/progress.json   进度页实时状态
├── 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。

3.1 深度研究进度 WebUI（必须在研究开始时启动）

创建 `{report_dir}` 后、进入 §4 判档位之前，controller 必须完成以下操作，不得等到研究产物生成后再启动：

1. 写入 `{report_dir}/request.md`，内容包含原始用户需求与启动时间。该文件用于进度页在其他产物尚未出现时识别 Deep Research 工作区。 2. 用共享进度事件脚本写入首个事件，并显式指定 `workflow=deep-research`：

   python3 {plugin_skills_dir}/sn-ppt-standard/scripts/progress_event.py \
     --deck-dir "{report_dir}" \
     --workflow deep-research \
     --stage mode-selection \
     --status running \
     --artifact request.md \
     --label "<使用 language 的简短状态>"

3. 立即启动或复用 Research Workbench。Deep Research 进度页使用独立的根路由 `/`：

   python3 {plugin_skills_dir}/sn-ppt-standard/scripts/launch_workbench.py \
     --deck-dir "{report_dir}" \
     --product research \
     --progress-route / \
     --source-session-id "${HERMES_SESSION_KEY:-}" \
     --agent-managed 1 \
     --require-webui \
     --host 0.0.0.0

原生 Windows 环境若无 `python3`，改用 `python`。在 Windows 的 Git Bash / MSYS 下传递根路由 `/` 时，命令前加 `MSYS_NO_PATHCONV=1`，避免路径被改写。

启动结果处理：

• 若返回 `{"status":"ok", ...}`，立即使用请求级 `language` 向用户提供 `research_progress_