Deep Research
Multi-stage research pipeline that decomposes a topic, gathers structured information, validates it, and synthesizes a final report. Supports formatted/unformatted output and skill/no-skill generation modes.
- License 许可
- MIT
- 最近更新
- 2026-06-22
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- Deep Research
- tags
- [ "research", "pipeline", "synthesis" ]
- author
- ForgeWeave Core
- version
- 1.0.0
- skill_id
- deep-research
- description
- Multi-stage research pipeline that decomposes a topic, gathers structured information, validates it, and synthesizes a final report. Supports formatted/unformatted output and skill/no-skill generation modes.
- tui_compatibility
- [ "opencode", "claude", "gemini", "qwen" ]
02 资源文件 9
- 参考文档evals/test_happy_path.json398 B
- 参考文档examples/README.md700 B
- 参考文档references/pipeline-architecture.md2.5 KB
- 参考文档references/url-sourcing-rules.md1.2 KB
- 脚本scripts/plan_generator.py2.8 KB
- 脚本scripts/synthesize_report.py2.6 KB
- 脚本scripts/validate_research.py2.2 KB
- 参考文档templates/plan_template.md413 B
- 参考文档templates/report_template.md918 B
03 SKILL.md 正文
Deep Research
Purpose
Execute a multi-stage research pipeline that decomposes a vague topic into structured subtopics, gathers usage-focused information from authoritative sources via parallel agents, validates claims for consistency, produces a synthesis-grade report, and converts raw findings into a reusable industry-grade skill. This is invoked internally by the deep-research skill — never call the pipeline stages directly.
When to Use
- A comprehensive, multi-faceted report is needed covering 3+ subtopics
- The topic requires crawling multiple authoritative sources (docs, API refs, guides)
- The output must be structured, validated, and free of hallucination
- The question cannot be answered by a single source or quick lookup
When Not to Use
- A quick factual answer is needed — use websearch instead
- Only one source needs to be checked — use the MCP data plane tools directly
- The topic is a simple how-to question — answer directly
- Real-time data is needed (stock prices, live scores) — use web-research
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
topic |
string | Yes | The research topic or question |
depth |
enum | No (default: standard) | quick, standard, deep |
focus |
enum | No (default: usage) | usage, architecture, comparison, general |
constraints |
string | No | Additional rules from AGENTS.md or user |
output_mode |
enum | No (default: formatted) | formatted, unformatted |
skill_mode |
enum | No (default: skill) | skill, no-skill |
Expected Outputs
| Output | Condition | Description |
|---|---|---|
research/<slug>-plan.md |
Always | Structured plan with subtopics, questions, seed URLs |
research/<slug>-raw/ |
Always | One file per subtopic from parallel research agents |
research/<slug>-validated.md |
Always | Cross-checked, deduplicated, hallucination-filtered |
research/<slug>-report.md |
formatted mode |
Final synthesis with all findings, code examples, sources |
.opencode/skills/<topic>/SKILL.md |
skill mode |
Reusable skill generated from findings |
Internal Workflow
Stage 1: Plan
Internal planner agent decomposes topic into 3-7 subtopics with questions and seed URLs from authoritative sources only. For JS-rendered content, Playwright MCP tools (browser_navigate, browser_snapshot) are available for interactive browsing during URL discovery.
Stage 2: Research (Parallel)
Internal research agents run concurrently — one per subtopic. Each crawls seed URLs, extracts code examples, API signatures, and edge cases. For JS-rendered pages, agents use Playwright MCP tools (browser_navigate, browser_snapshot).
Stage 3: Validate
Internal validator cross-checks all subtopic outputs: removes unsupported claims, flags contradictions, deduplicates findings.
Stage 4: Synthesize
Internal synthesizer merges validated research into a final report with sections: Overview, Getting Started, Core Content, Advanced Patterns, Migration Guide, Best Practices, Edge Cases, Sources.
Stage 5: Output
Internal output writer saves research results based on output mode:
formatted(default): Produces a structured report atresearch/<slug>-report.mdwith sections: Overview, Getting Started, Core Content, Advanced Patterns, Migration Guide, Best Practices, Edge Cases, Sourcesunformatted: Saves raw scraped data as individual markdown files inresearch/<slug>-raw/with minimal processing
Raw data is always saved to research/<slug>-raw/ regardless of mode.
Stage 6: Skill Conversion (conditional)
AI uses the skill-builder skill to convert the raw findings into a reusable SKILL.md file — only when skill mode is selected:
- Reads all
research/<slug>-raw/*.mdfiles - Identifies reusable patterns, APIs, and best practices
- Writes a structured SKILL.md with frontmatter, workflow steps, gotchas, and references
- Places the skill in
.opencode/skills/<topic-slug>/for future coding use - Reports the skill path to the user
Required Checks
- [ ] Planner ran first (never skip)
- [ ] Research agents ran in parallel
- [ ] Validator ran after all research completed
- [ ] Every claim has a source URL
- [ ] No blog posts or changelogs used as sources
Failure Modes
| Failure Condition | Response |
|---|---|
| Planner produces <3 subtopics | Respawn with "produce at least 3" |
| All seed URLs return 404 | Report "all sources unavailable" |
| Validator flags >50% claims as unsupported | Re-run research with better URLs |
| Pipeline exceeds max iterations | Stop and return partial results |
Examples
Example 1: Full research with skill (default)
Trigger: /forge-research Next.js 16 caching --depth=deep
Result: research/nextjs16-report.md + .opencode/skills/nextjs16/SKILL.md
Example 2: Raw output only, no skill
Trigger: /forge-research Next.js 16 caching unformatted no-skill
Result: research/nextjs16-raw/*.md (raw files only)
Example 3: Formatted report, no skill
Trigger: /forge-research Python 3.14 pattern matching formed no-skill
Result: research/python314-report.md (structured report only)
References
| Reference | Path |
|---|---|
| RESEARCH_INSTRUCTIONS.md | ./RESEARCH_INSTRUCTIONS.md |
04 同仓库更多 Skills
Workflow Orchestrator
Coordinates multi-skill execution pipelines (e.g., research → plan → build → test)
Web Research
Browser-driven or scraping-based skill for real-time internet extraction using Playwright and HTTP-based fetching
Validation Engine
Checks outputs from other skills for consistency, correctness, and adherence to AGENTS.md rules
Tool Selector
Determines which tools, APIs, MCP actions, or system capabilities are required for a given task
Test Generator
Creates test plans and test cases (unit, integration, edge cases) based on existing or planned code
Skill Generator
Meta-skill that creates new SKILL.md files from research outputs and patterns discovered in execution