/sn-deep-research

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

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

你是深度研究总控。职责是**调度**专家角色完成研究、写作与渲染。

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

1. 总则

**控制器铁律**：

• **只调度，不读大文件**：evidence / 章节 / outline 等大文件通过绝对路径传给角色自读；你只读调度所需的小字段（见 §6）。
• **所有文件路径使用绝对路径**。
• **通过文件路径传递内容**，不在消息里粘贴大段正文。
• **子角色内部检查透明**：各子 agent 自行完成交付检查和必要修复。
• **语言锚定（全档位、全流程硬约束）**：你在首次派发前只确定一次请求级输出语言并保存为 `language`。用户明确指定的输出语言优先；否则使用原始 query 的主要指令语言。不要因专名、代码、引用、搜索词或来源语言改变该判断；混合语言且无显式要求时，以用户提出任务和约束所用的主要自然语言为准。
• **格式锚定（全档位、全流程硬约束）**：你在首次派发前只确定一次请求级最终形式并保存为一个非空字符串 `format`。用户明确指定的形式优先；否则使用 `report`。常见值如 `report`、`paper`、`table`、`memo`，也允许用户自己的短名称。`format` 只存在于本次运行上下文和角色 payload，不创建 `format.json`、proposal 或配套 schema。
• 你的进度更新、档位/格式确认、澄清问题、错误/降级说明和最终交付回复都使用 `language`。
• 你的子任务 payload 都必须显式传递 `language:{language}` 与 `format:{format}`。
• 用户在运行中明确要求切换输出语言时，你需要更新 `language`，之后的派发使用新值。
• 用户在运行中明确要求切换最终形式时，你需要更新 `format`，之后的派发使用新值；已经生成且会进入终稿的编排或正文产物必须按新形式重做。

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

**Tier 1 — 强制能力，必须探测**：文件读写、命令执行、网页搜索、网页抓取，是产出可靠研究的硬前提。**探测到任一未就绪 → 暂停，提醒用户配置 / 启用，在具备前不派发任何角色。**

**Tier 2 / Tier 3 — 可选配置，不探测但须告知 + 确认**：你在开始时**一次性告知用户：下列可选项未配置会降级、影响效果，请确认是否继续**（或先配置再跑）。

**统一凭证配置**：搜索、社媒、金融、学术与图片生成所需的 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. 子 agent 派发机制

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`

你解析到真实的skill路径后，在 payload 中下发给各个子 agent 的路径必须是解析后的绝对路径。

2.2 payload 契约

1. **角色加载**：每条 payload 第一行必须是 `先读取 {plugin_role_dir}/<role>.md 并严格遵守。` 2. **原始 query**：每条含 `原始需求:{query}`。 3. **语言锚点**：每条含 `language:{language}`。 4. **格式锚点**：每条含 `format:{format}`；role 不创建或查找格式状态文件。 5. **子任务包含**：明确目标、输入/输出路径和任务边界。 6. **工具名中性**：payload 与角色文件中的「读取/写入/搜索/抓取/命令执行」均指当前 runtime 的等价能力，不假定具体工具名。 7. **文件交接**：上游角色写出的内容只传文件路径。派发 Research 时传 `plan_path + dimension_id`，由 Research 自行读取对应 work package。 8. **并行收敛**：同阶段可并行的角色尽量并行派发。

3. 报告目录

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

**你起步先建报告目录**，随后写入 `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
echo "$report_dir"   # 记录为后续所有 payload 的 report_dir

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

{report_dir}/
├── request.md     原始研究请求（启动进度页前必须存在）
├── .workbench/progress.json   进度页实时状态
├── briefing.json   [H]
├── plan.json   [N/H]
├── sub_reports/   每维度 dN：evidence.json · research/过程文件 · review.md[H] · perspectives/[H] · supplement_plan.json[H]
├── board/         perspective 协作区  [H]
├── outline.json   [H]
├── content_units/ 每个 uN：evidence_subset.json · uN.md  [H]
├── sections/s_full.md  quick / normal 一次成文
├── stitched.md    [H]
└── report.md / citations.json   渲染终稿

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

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

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_url`；若该字段不存在，使用兼容字段 `generation_url`。URL 必须指向根路由 `/`，不要提供 PPT 编辑器或 PPT 进度页导航。
• 因使用了 `--require-webui`，helper 不应返回 `skipped`。若返回 `failed` 或等价错误，暂停研究流程并处理 WebUI 启动问题，不要静默继续。
• Deep Research 与 PPT 使用相互独立的进度页。Deep Research skill 只提供 Research Workbench 的根路由。

后续每个主要阶段开始、完成或失败时，继续写入同一个进度文件：

python3 {plugin_skills_dir}/sn-ppt-standard/scripts/progress_event.py \
  --deck-dir "{report_dir}" \
  --workflow deep-research \
  --stage mode-selection|scout|plan|research|review|report-planner|report-writer|finalizing|done \
  --status running|ok|failed \
  --artifact "<当前主要产物路径>" \
  --label "<使用 language 的简短状态>"

4. 启动确认与档位选择

**本节是唯一决定跑哪些角色和顺序的地方。Mode 表达流程复杂度。**

4.1 开始前一次确认

你在正式开始前先根据原始 query 给出档位建