research-deep

Research Deep——逐项深度研究

读取 /research-outline 生成的大纲，每批启动一个后台 Agent，每个 Agent 根据字段架构填充一个条目的完整 JSON。

触发方式

/research-deep

工作流位置

/research-outline → /research-add-* → ► /research-deep ◄ → /research-report

工作流

步骤 1——自动定位大纲

从当前工作目录使用 Glob 查找 */outline.yaml。使用 Read 读取文件，获取 items、execution.batch_size、execution.items_per_agent 和 execution.output_dir。

步骤 2——检查是否可续跑

使用 Glob 查找 {output_dir}/*.json，以确定已完成的条目。跳过这些条目——只安排尚无 JSON 文件的条目。

步骤 3——分批执行

• 将剩余条目按 batch_size 分组。
• 对于每批：通过 Task 工具启动 Agent，设置 subagent_type: general-purpose（或项目中已注册的研究子 Agent）和 run_in_background: true。禁用每个 Agent 的输出——Agent 会直接写入指定的 JSON 路径，因此将对话流式传回父上下文只会浪费 token。
• 每个 Agent 最多处理 items_per_agent 个条目。
• 启动下一批之前，等待用户批准（让用户抽查第一批的输出；如果质量不佳，可以提前停止）。

每个条目捕获的参数：

• {topic}——outline.yaml 中的 topic 字段
• {item_name}——条目的 name 字段
• {item_related_info}——条目的完整 YAML 段落（name + category + description + …）
• {output_dir}——outline.yaml 中的 execution.output_dir（默认值为 ./results）
• {fields_path}——{topic_dir}/fields.yaml 的绝对路径
• {output_path}——{output_dir}/{item_name_slug}.json 的绝对路径

**{item_name_slug} 的 Slug 规则：**转换为小写，将连续的任意非字母数字字符替换为 _，并去掉开头和结尾的 _。具体来说：re.sub(r"[^a-z0-9]+", "_", item_name.lower()).strip("_")。示例：GitHub Copilot → github_copilot，Cursor (Anysphere) → cursor_anysphere。

**为什么下面的提示词要逐字模板化：**子 Agent 在隔离环境中运行。它的提示词会明确包含所有参数，而措辞上的细微差异会导致不同运行生成的 JSON 结构不一致。请将此模板视为固定约定——只替换 {xxx} 变量，其余部分保持原样。

提示词模板：

## Task
Research {item_related_info}, output structured JSON to {output_path}

## Field Definitions
Read {fields_path} to get all field definitions

## Output Requirements
1. Output JSON according to fields defined in fields.yaml
2. Mark uncertain field values with [uncertain]
3. Add uncertain array at the end of JSON, listing all uncertain field names
4. All field values must be in English

## Output Path
{output_path}

## Validation
After completing JSON output, run validation script to ensure complete field coverage:
python ~/.claude/skills/research-outline/validate_json.py -f {fields_path} -j {output_path}
Task is complete only after validation passes.

示例（条目 = "GitHub Copilot"）：

## Task
Research name: GitHub Copilot
category: International Product
description: Developed by Microsoft/GitHub, first mainstream AI coding assistant, ~40% market share, output structured JSON to {project_dir}/results/github_copilot.json

## Field Definitions
Read {project_dir}/fields.yaml to get all field definitions

## Output Requirements
1. Output JSON according to fields defined in fields.yaml
2. Mark uncertain field values with [uncertain]
3. Add uncertain array at the end of JSON, listing all uncertain field names
4. All field values must be in English

## Output Path
{project_dir}/results/github_copilot.json

## Validation
After completing JSON output, run validation script to ensure complete field coverage:
python ~/.claude/skills/research-outline/validate_json.py -f {project_dir}/fields.yaml -j {project_dir}/results/github_copilot.json
Task is complete only after validation passes.

步骤 4——等待并监控

• 等待当前批次完成（每个 Agent 会通过输出其 JSON 来表示已完成）。
• 获得用户同意后，启动下一批。
• 显示进度（已完成条目数/总条目数）。

步骤 5——摘要报告

所有批次完成后，输出：

• 已完成条目数
• 标记为失败或包含 uncertain 条目的列表
• {output_dir}/ 的路径

Agent 配置

• 后台执行：是（run_in_background: true）
• Task 输出：禁用——每个 Agent 的交付物都是其写入的 JSON 文件
• 支持续跑：是（步骤 2 会跳过已完成的条目）

注意事项

• 校验器路径 ~/.claude/skills/research-outline/validate_json.py 与安装位置绑定。 它假定 research-outline 技能已安装在 ~/.claude/skills/research-outline/，这是 claude-code-skills/scripts/link-skills.sh 和 install-skills.sh 配置的路径。如果你将该技能复制到了其他位置（例如项目本地的 .claude/skills/），模板提示词中的校验器路径就会失效，子 Agent 会卡在校验步骤。解决方法是保留规范安装路径，或在启动 /research-deep 前，将上方模板中的校验器路径替换为你安装位置对应的正确绝对路径。
• 禁用了任务输出的后台 Agent 无法在偏离方向时向你发出早期警告。 这是有意为之的权衡——优先节省 token，而非提供冗长反馈。批准更多结果前，请抽查第一批 JSON。
• 恢复执行完全依赖文件名匹配。 崩溃运行留下的半写入 JSON 会被步骤 2 视为“已完成”。如果上次运行中断，请在重新运行前删除损坏的 JSON 文件。
• {item_name_slug} 冲突会静默覆盖。 名称转换为 slug 后相同的两个条目（例如 GPT-4 和 GPT 4）会相互覆盖。如果怀疑发生冲突，请在条目的 category 字段中添加区分标识，并改用 {category_slug}_{name_slug} 作为 slug。
• 校验器唯一的后置条件是必填字段检查。 如果 fields.yaml 没有将任何字段标记为 required: true，校验器就会放行任何内容，包括几乎返回空 JSON 的 Agent。请将每个类别至少一个字段标记为 required，以实现有意义的把关。