Deep Research

Deep Research（深度调研编排工作流）

把"深度调研"当作一个可复用、可并行的生产流程来执行：主控负责澄清目标、拆解子目标、调度子进程、聚合与精修；子进程负责采集/抽取/局部分析并输出结构化 Markdown 素材；最终交付物必须是独立成品文件而不是聊天贴文。

关键约束（必须遵守）

任务目标

1. 从用户的高层目标推导出可并行的子目标集合（如链接清单、数据分片、模块列表、时间切片等）。 2. 为每个子目标启动独立的 claude -p 子进程，并为其分配合适权限（通过 --allowedTools 参数）。 3. 并行执行并产出子报告（自然语言 Markdown，可含小节/表格/列表）；失败时输出带原因的错误说明与后续建议。 4. 用脚本按顺序聚合子输出，生成统一的基础稿。 5. 对基础稿做理智检查与最小化修复，然后给出最终 artefact 路径与关键发现摘要。

交付标准

任务规模分级与执行路径

根据子目标数量选择执行路径：

| 规模 | 子目标数 | 执行方式 | 目录要求 | |------|----------|----------|----------| | 微型 | 1-2 | 主进程直接执行 | 仍需 raw/、logs/、final_report.md | | 小型 | 3-5 | 启动子进程，串行或少量并行 | 完整目录结构 | | 中型 | 6-15 | 并行子进程（默认 8 并发） | 完整目录结构 + 调度脚本 | | 大型 | >15 | GNU Parallel + 分批调度 | 完整目录结构 + 多阶段调度 |

注意：即使是微型任务，也必须： 1. 将原始搜索结果保存到 raw/ 目录 2. 记录执行日志到 logs/dispatcher.log 3. 等待用户确认后再执行（除非用户明确说"直接执行"）

端到端流程（严格按序执行）

0. 预执行规划与摸底（必做；主控亲自完成） - 先澄清目标、风险、资源/权限约束，并识别后续扩散依赖的核心维度（主题簇、人物/组织、地域、时间切片等）。 - 若存在公开目录/索引（标签页、API 列表等），用最小化方式抓取缓存并统计条目；若不存在，做"案头调研"获取真实样本（新闻、资料、数据集等），记录来源/时间/要点作为证据。 - 形成清单前至少展示一次真实检索或浏览的代表样本；只靠经验推测不算完成摸底。 - 摸底阶段必须至少通过一次"可追溯的工具链"拿到真实样本并记录引用：优先使用已安装 skills；若需要 MCP，则优先 firecrawl，其次 exa；若都不可用，记录原因并选择替代方案（必要时再降级到 WebFetch/WebSearch）。 - 输出初步（或草拟）清单：列出发现的维度、各维度已掌握的选项及样本、规模估算，并标注不确定性/缺口。若尚未获得真实样本，先补齐调研，禁止进入下一步。 - 依据上述结构补全可执行计划（拆分、脚本/工具、输出格式、权限、超时策略等），用用户语言汇报维度统计与计划内容；在得到明确"执行/开始"回应前保持等待。

1. 初始化与总体规划 - 明确目标、预期输出格式与评价标准。 - 根据当前任务生成一个语义化且不重复的名字 name（建议：-<短题>-<随机后缀>，全小写、短横线分隔、无空格）。 - 创建运行目录 .research//，并把所有产物都保存到该目录下（子目录如 prompts/、logs/、child_outputs/、raw/、cache/、tmp/）。 - 保持默认模型与配置不变；需要调整任何模型/推理/权限相关设置时先征得用户同意，并在日志中注明变更原因与影响范围。

2. 子目标识别 - 通过脚本/命令提取或构造子目标列表。 - 源数据不足时（例如页面只给两个主链接），如实记录原因，然后由主进程直接接手完成剩余工作。

3. 生成调度脚本 - 创建调度脚本（例如 .research//run_children.sh），要求： - 接收子目标列表（可存 JSON/CSV）并逐项调度。 - 为每个子目标构造 claude -p 调用，推荐要点： - 推荐形式：claude -p "prompt" --allowedTools "Read,Write,Edit,Bash,WebFetch,WebSearch,mcp__firecrawl__*"（以 claude --help 为准）。 - 在 prompt 中声明：一切联网需求优先使用已安装 skills（技能优先）；若必须走 MCP，则优先 firecrawl，其次 exa；确实没办法才用 WebFetch/WebSearch；不使用 plan 工具与"人工交互等待"。 - 非经用户要求不传模型参数。 - 为子输出指定落盘路径（例如 .research//child_outputs/.md）。 - 可引用如下调用模板（仅演示参数，不涉及并行）：

         timeout 600 claude -p "$(cat "$prompt_file")" \
            --allowedTools "Read,Write,Edit,Bash,Glob,Grep,WebFetch,WebSearch,mcp__firecrawl__firecrawl_scrape,mcp__firecrawl__firecrawl_search" \
            --output-format json \
            > "$output_file" 2>&1
         

4. 设计子进程 Prompt - 动态生成 prompt 模板，至少包含： - 子目标描述、输入数据、约束边界。 - 规划阶段限制联网检索/抽取的总轮数不超过 X（按复杂度选择；通常建议 10），信息足够就收敛结束；工具优先级：skills → MCP（firecrawl → exa）→ WebFetch/WebSearch。 - 结果输出为自然语言 Markdown：包含结论、关键证据列表、引用链接；出现错误时给出 Markdown 形式的错误说明与后续建议。 - 生成实际 prompt 文件时，优先用 printf/逐行写入注入变量，避免 Bash 3.2 在多字节字符场景下 cat < 截断变量的已知问题。 - 将模板写入文件（例如 .research//child_prompt_template.md）以便审计与复用。 - 在启动调度脚本前，逐一快速审阅生成的 prompt 文件（例如 cat .research//prompts/.md），确认变量替换正确、指令完整后再派发任务。

5. 并行执行与监控 - 运行调度脚本。 - 记录每个子进程的开始/结束时间、耗时与状态。 - 对失败/超时子进程做明确决策：标记、重试、或在最终报告中说明；触及 15 分钟超时上限时记录 prompt/流程待排查。长任务执行中可提示用户用 tail -f .research//logs/.log 追踪实时输出。

6. 程序化聚合（生成基础稿） - 用脚本（例如 .research//aggregate.py）读取 .research//child_outputs/ 下所有 Markdown，按预设顺序聚合为初版主文档（例如 .research//final_report.md）。

7. 解读聚合结果并设计结构 - 通读 .research//final_report.md 与关键子输出。 - 设计精修报告章节大纲与"素材映射"（例如 .research//polish_outline.md），明确目标受众、章节顺序与每章核心论点。

8. 分章精修与出稿 - 新建精修稿（例如 .research//polished_report.md），按大纲逐章撰写；每写完一章立刻自查事实、引用与语言要求，必要时回溯子稿核实。 - 避免一次性全篇重写；坚持"按章迭代"以维持一致性并降低遗漏风险，同时记录每章亮点、问题与处理方式。 - 对重复信息、引用格式、待确认条目做统一整理，同时保留核心事实与量化数据。

9. 落地交付 - 确认精修稿满足交付标准（结构完整、语气统一、引用准确），以该成品作为对外报告。 - 最终交付物必须落地为独立文件（位于 .research//）；通过提供文件路径与必要摘要向用户回报，禁止在聊天中贴出完整成稿。 - 在最终答复中概述核心结论与可执行建议；必要时补充待确认事项的跟进方式。 - 不对外附带中间稿或内部笔记，确保用户看到的是高质量成品。

注意事项

# 基本非交互调用
claude -p "Your prompt here"
指定允许的工具（无需人工确认）
claude -p "Your prompt" --allowedTools "Read,Write,Edit,Bash"
JSON 格式输出（便于脚本解析）
claude -p "Your prompt" --output-format json
流式 JSON 输出
claude -p "Your prompt" --output-format stream-json
继续上一次对话
claude -p "Follow up question" --continue
继续指定会话
claude -p "Follow up" --resume 

#!/bin/bash
子进程调度示例
prompt_file="$1"
output_file="$2"
log_file="$3"
读取 prompt 并执行
timeout 600 claude -p "$(cat "$prompt_file")" \
    --allowedTools "Read,Write,Edit,Bash,Glob,Grep,WebFetch,WebSearch,mcp__firecrawl__firecrawl_scrape,mcp__firecrawl__firecrawl_search,mcp__firecrawl__firecrawl_map" \
    --output-format json \
    2>&1 | tee "$log_file" > "$output_file"
exit_code=${PIPESTATUS[0]}
echo "Exit code: $exit_code" >> "$log_file"

#!/bin/bash
并行执行多个子任务
max_parallel=8
research_dir=".research/$name"
使用 GNU Parallel（推荐）
cat "$research_dir/tasks.txt" | parallel -j $max_parallel \
    "timeout 600 claude -p \"\$(cat $research_dir/prompts/{}.md)\" \
    --allowedTools 'Read,Write,Edit,Bash,WebFetch,WebSearch' \
    --output-format json > $research_dir/child_outputs/{}.json 2>&1"
或使用后台任务
for task_id in $(cat "$research_dir/task_ids.txt"); do
    (
        timeout 600 claude -p "$(cat "$research_dir/prompts/$task_id.md")" \
            --allowedTools "Read,Write,Edit,Bash,WebFetch,WebSearch" \
            --output-format json \
            > "$research_dir/child_outputs/$task_id.json" 2>&1
    ) &
    # 控制并行数量
    while [ $(jobs -r | wc -l) -ge $max_parallel ]; do
        sleep 1
    done
done
wait  # 等待所有后台任务完成