| name | deep-research |
| description | 深度调研的多实例（多 Agent）编排工作流：把一个调研目标拆成可并行子目标，用 Codex CLI 子进程采集和分析证据，再聚合、核验并精修为完整报告。用于系统性网页或资料调研、竞品与行业分析、批量链接或数据集分片、长文证据整合，以及用户提及深度调研、Deep Research、Wide Research、多 Agent 并行调研或多进程调研的场景。 |
Deep Research
把深度调研作为可重复、可审计的生产流程执行。主控负责目标澄清、样本摸底、子任务设计、结果核验和最终综合；子进程负责边界清晰的采集或局部分析。
核心约束
- 保持用户当前模型和推理配置，不传
--model，不覆盖无关配置。
- 子进程默认使用
workspace-write；只有确实需要 shell 网络访问时才启用 runner 的 --network。
- 先检查当前会话可用的 Skills、连接器和 MCP，再按来源适配能力；不要假设固定服务或工具名存在。
- 不使用
--dangerously-bypass-approvals-and-sandbox。
- 所有运行产物写入独立的
.research/<name>/ 目录。
- 在开始批量执行前向用户展示拆分方案；需要明显成本、长时间运行或外部系统访问时，等待明确同意。
Bundled scripts
先解析当前 Skill 的绝对目录并记为 <skill-dir>。
scripts/run_children.py：跨平台并行执行 codex exec，负责超时、重试、日志和结果状态。scripts/aggregate.py：按 manifest 顺序聚合成功的子报告，缺失或空结果时失败。
两个脚本都使用 Python 标准库，不生成临时 shell 脚本。
Workflow
1. 澄清与摸底
明确目标、受众、时间范围、来源边界、评价标准和最终格式。通过当前可用工具获取少量真实样本，记录代表性来源和缺口，避免只凭经验拆分。
2. 创建运行目录
使用不重复的语义化名称，例如：
.research/20260712-codex-skills-a3f2/
├── prompts/
├── logs/
├── child_outputs/
├── raw/
├── cache/
└── manifest.json
把网页原文、数据和解析结果缓存到 raw/ 或 cache/，避免重复抓取。
3. 设计子任务
每个子任务只负责一个明确边界，Prompt 至少包含：
- 子目标、输入和允许访问的范围
- 输出结构和证据要求
- 失败时必须说明原因，不得编造结果
- 输出自然语言 Markdown，并把来源链接放在对应结论附近
将 Prompt 分别写入 prompts/，然后创建 manifest：
{
"tasks": [
{
"id": "market-history",
"title": "市场历史",
"prompt_file": "prompts/market-history.md"
},
{
"id": "current-competitors",
"title": "当前竞品",
"prompt_file": "prompts/current-competitors.md"
}
]
}
id 只能包含字母、数字、点、下划线和短横线。Prompt 必须位于本次运行目录内。
4. 预检和执行
先预览命令，不启动 Codex 子进程：
python3 "<skill-dir>/scripts/run_children.py" \
--run-dir ".research/<name>" \
--workspace "$PWD" \
--dry-run
检查 manifest 和 Prompt 后执行：
python3 "<skill-dir>/scripts/run_children.py" \
--run-dir ".research/<name>" \
--workspace "$PWD" \
--parallel 8 \
--timeout 600 \
--retries 1
只有子任务必须通过 shell 直接联网时才添加 --network。根据任务成本调整并发和超时，先用 1–2 个子任务验证链路，再扩大并发。
Runner 固定输出：
child_outputs/<id>.mdlogs/<id>.logresults.json
5. 核验和失败处理
读取 results.json，检查失败、超时、空输出和引用缺失。只重试失败的边界任务；不要因为单个失败重新运行所有成功任务。需要改变模型、权限或来源范围时先说明原因。
6. 聚合原始材料
python3 "<skill-dir>/scripts/aggregate.py" \
--run-dir ".research/<name>"
默认生成 aggregated_raw.md。该文件只是按 manifest 顺序整理的内部材料，不是最终报告。
7. 综合与精修
通读子报告和关键原始来源，先设计章节大纲和素材映射，再分章节写入 polished_report.md。处理重复信息、来源冲突和证据强弱；验证关键数据和引用，不能把子报告简单拼接后直接交付。
8. 交付
最终回复提供：
- 成品报告绝对路径
- 关键结论和可执行建议摘要
- 未解决的证据缺口或失败子任务
- 是否启用了额外网络权限或其他例外
不要把内部 Prompt、调度日志或完整中间稿当作成品发送给用户。
