convez.ai
AgenteBusca & PesquisaAvançado
Justaboringname

Deep Research Harness

Justaboringname/deep-research-harness

Pesquisa paralela multi-agente com verificação adversarial e relatórios citados

Ver no GitHub
InicialPluginScore · de 0 a 100

Pipeline multi-agente de pesquisa profunda que executa como workflow dinâmico no Claude Code. Decompõe um tópico em sub-tópicos investigados em paralelo por subagentes independentes, aplica verificação adversarial estilo GAN para validar claims, e gera relatório HTML auto-contido e totalmente citado.

Instalação

$npx convez-ai Justaboringname/deep-research-harness

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Pesquisa aprofundada de tópicos complexos com múltiplas perspectivas
  • Fact-checking e verificação de claims com painel de agentes críticos
  • Geração de relatórios técnicos ou jornalísticos auto-contidos e citados

Veredito

Solução robusta e honesta para pesquisa profunda, explicitamente otimizada para qualidade e paralelização em vez de custo de tokens. Arquitetura bem pensada que escapa dos limites clássicos (contexto, degradação, latência), mas demanda alto consumo de API — ideal para pesquisas críticas onde precisão supera custo.

README

A tradução para o português deste README ainda está na fila.

deep-research-harness

A multi-agent deep-research pipeline that runs as a single Claude Code dynamic workflow. You give it a topic; it fans out a tree of subagents to research it, adversarially fact-checks the load-bearing claims, and renders a self-contained, fully-cited HTML report — fire-and-forget.

It is built around two ideas:

  • Fan-out like an NFA. A leader decomposes the topic into sub-topics, and each sub-topic is investigated by its own subagent in parallel — a tree of independent search paths rather than one long serial chain.
  • Adversarial verification, GAN-style. Before a claim makes it into the report, a panel of skeptic agents tries to refute it from several angles. Claims that survive are kept; claims that can only be defended by reaching for new, stronger evidence are corrected; the rest are killed and logged in a transparent ledger.

Honest naming. It's GAN-shaped, not a real GAN — there is no gradient or training. The "generator" objective is inverted: instead of rewording a claim until the critic stops complaining (which optimizes for slippery, unfalsifiable claims), the generator must correct the claim toward the evidence or concede. See Adversarial verification below.


Why a workflow of subagents instead of one big prompt?

A single agent doing deep research hits three walls. This architecture is designed around all three:

  1. Context window. The volume of fetched source text in a real research task overflows even a 1M-token context. Here, each search subagent writes its full brief to disk (raw/Sx.json) and returns only a few bytes of control-flow metadata to the orchestrator. The leader's context never holds all the source material at once.
  2. Long-context degradation & hallucination. Model quality degrades and hallucination rises as a context fills up. Short-lived, single-purpose subagents each work in a small, clean context.
  3. Wall-clock. The sub-topics are researched in parallel. What would be a many-hour serial crawl finishes in the time of the slowest single branch.

The trade-off is honest and deliberate: this is expensive. It is optimized for quality and wall-clock, not for token cost. A broad topic with adversarial verification on can make 100+ agent calls and burn several hundred thousand tokens in one run.


Architecture

        ┌─────────────────────────────────────────────────────────────┐
        │ orchestrator (you / the main agent)                          │
        │ pre-captures what a sandboxed script can't: slug, temp dir,   │
        │ cost baseline, run-start ms — then fires the workflow         │
        └───────────────────────────────┬─────────────────────────────┘
                                         │  Workflow({ name:'deep-research-harness', args })
                                         ▼
  ┌────────┐   ┌───────────────────┐   ┌────────┐   ┌──────────┐   ┌───────────┐   ┌──────────────────────┐   ┌────────┐
  │ 1 Plan │──▶│ N Search          │──▶│ Critic │──▶│ Gap-fill │──▶│ Synthesis │──▶│ Adversarial Verify   │──▶│ Render │
  │ leader │   │ parallel,         │   │ gap    │   │ 0–3      │   │ 1 agent,  │   │ + Reconcile          │   │ HTML   │
  │ N ≥ 8  │   │ 1 subagent/topic, │   │ finder │   │ targeted │   │ marks     │   │ (GAN-shaped, ON by   │   │ + cite │
  │        │   │ writes brief→disk │   │        │   │ refills  │   │ claims    │   │ default)             │   │ pool   │
  └────────┘   └───────────────────┘   └────────┘   └──────────┘   └───────────┘   └──────────────────────┘   └────────┘
       │               │                                                                    │
   raw/plan.json   raw/Sx.json ✕N                                                    raw/verify.json

The stages

StageAgentsWhat it does
Plan1Decomposes the topic into N ≥ 8 narrow, non-overlapping, web-searchable sub-topics. Captures the cost baseline. Scans raw/ to resume a prior run.
SearchN (parallel)One rigorous fact-aggregation subagent per sub-topic. Runs WebSearch/WebFetch, extracts evidence quotes, cross-checks confidence, and writes a structured brief to raw/Sx.json — returning only metadata.
Critic1Fresh-context gap analyst. Reads every brief and finds coverage gaps, weak (single-source) evidence, contradictions, staleness, and failed sub-topics. Not a score — a hunt for holes.
Gap-fill0–3+Conditionally re-runs the search agent against the most severe gaps: all fatal gaps, plus the most severe major gaps up to 3 total (so an all-fatal run can exceed 3 — fatal is meant to be rare).
Synthesis1Merges all briefs into a markdown report, resolves contradictions by source quality, and marks the load-bearing claims the conclusions actually hang on.
Adversarial Verify + ReconcilemanyThe GAN-shaped stage (below). On by default. Patches the synthesis and writes a verify.json ledger.
Render1Builds a global citation pool (dedup + global numbering), renders the report into the chosen HTML template, and fills the cost/wall-clock panel. One self-contained HTML file out.

Adversarial verification (the GAN-shaped stage)

Only load-bearing claims that are weak-evidence or below high confidence are attacked (single-source / community-only / inferential, or merely medium/low); strong, high-confidence claims are skipped. Capped at adversarialMaxClaims (default 8).

  Synthesis marks load-bearing claims
        │  select (load-bearing × weak-evidence), cap N
        ▼
  R1 refute-panel    per claim, 3 independent lenses:
        │              ① attribution  — does the cited source actually contain this?
        │              ② counter      — is there a standing counter-example / better reading?
        │              ③ overclaim    — is it stronger than the evidence, or narrowed to a truism?
        │            majority refute ⇒ claim is "attacked"
        ▼ attacked
  Generator          correct WITH new/stronger evidence, OR concede.
        │            (rewording or same/weaker evidence ⇒ forced concede)
        ▼ corrected
  R2 refute-panel    re-run the SAME panel on the revised claim.
        │            no 2nd correction allowed — it stands or it dies.
        ▼
  Ledger:  ✅ confirmed   ✏️ corrected (+new evidence)   ❌ refuted (+reason)
        │
        ▼
  Reconcile agent patches synthesis.md and writes verify.json

The five teeth that keep this from degenerating into "argue until the critic gives up":

  1. A correction must ship a new/stronger evidence quote, or it's forced to concede.
  2. One correction per claim, max. A corrected claim that's still refuted dies — no narrowing-to-a-truism ratchet.
  3. The adversarial pass can confirm, downgrade, or kill — never upgrade confidence past source quality. (The refuters are imperfect LLMs; surviving ≠ true. It's a culler, not a confidence pump.)
  4. Only load-bearing × weak-evidence claims are spent on panels.
  5. Fail-closed: a claim is only "confirmed" with a quorum of real verdicts that are majority-confirm. If a lens agent errors or returns nothing, the claim is routed to correct-or-concede, never silently passed.

Requirements

  • Claude Code with the Workflow (dynamic workflow) tool available. The harness is a JS workflow script executed by Claude Code's workflow runtime — not by Node directly. (node is only useful for --check syntax validation; see below.)
  • Subagents need the WebSearch and WebFetch tools.
  • python3 (for a reliable epoch-ms; macOS date +%s%3N is broken).
  • (optional, for the cost panel only) jq plus a claude usage --json that emits the ccusage JSON schema (.daily[].totalCost). On the author's machine claude usage is a shell wrapper around ccusage; the cost query is hard-coded to that shape. Without ccusage (or a wrapper that produces it) the cost panel just shows "no cost data" — nothing else depends on it.

⚠️ This repo's main file is named deep-research-harness on purpose — do not register a workflow named deep-research, which would collide with Claude Code's own built-in deep-research harness.

Install

git clone https://github.com/Justaboringname/deep-research-harness
cd deep-research-harness

# 1. put the workflow where Claude Code scans for them
cp deep-research-harness.js ~/.claude/workflows/

# 2. point the script at the templates dir — EITHER edit the constant:
#      DEFAULT_TEMPLATES_DIR = '/abs/path/to/deep-research-harness/templates'
#    OR pass args.templatesDir at call time (see Usage).

# 3. (optional) install the skill so the orchestrator steps are documented in-tool
cp -r skill ~/.claude/skills/deep-research-harness

The named-workflow registry is scanned once at session start, so a freshly-copied file isn't callable by name until the next session. In the same session, call it by scriptPath instead (see Usage).

Usage

A sandboxed workflow script can't run shell, so the orchestrator (you, or your SKILL.md) pre-captures a few values first:

TOPIC="<your research question>"
TODAY=$(date +%F)
SLUG="<ascii-safe-slug>"                 # e.g. "http2-vs-http3"
WORK="/tmp/deep-research/$TODAY-$SLUG"; mkdir -p "$WORK/raw"
HTML_OUT="$HOME/Downloads/$TODAY-$SLUG.html"
RUN_START_MS=$(python3 -c "import time;print(int(time.time()*1000))")

Then fire the workflow (fire-and-forget — you get a completion notification):

Workflow({ name: 'deep-research-harness', args: {
  topic: TOPIC,
  outDir: WORK,
  htmlOut: HTML_OUT,
  templatesDir: '/abs/path/to/deep-research-harness/templates',  // if you didn't edit the constant
  runStartMs: RUN_START_MS,
  topicLanguage: 'zh',     // language of the report prose; JSON keys stay English. use 'en' for English.
  style: 'claude',         // claude | minimal | academic | magazine
  adversarial: true        // GAN-shaped verify — on by default; pass false to skip
}})
// first-session fallback (registry not yet scanned):
// Workflow({ scriptPath: '/abs/path/to/deep-research-harness/deep-research-harness.js', args: { …same… } })

On the completion notification: ls "$HTML_OUT" to confirm, open it, then rm -rf "$WORK" — the HTML is self-contained (it embeds the full dataset in a <script type="application/json"> block, so it can be re-rendered later without the temp files).

Key args

argrequireddefaultmeaning
topic✅—the research question
outDir✅—abs path of a temp work dir (raw/ lives inside; deletable after)
htmlOutoutDir/index.htmlabs path of the final single HTML
templatesDirDEFAULT_TEMPLATES_DIR constabs path of this repo's templates/
runStartMsplan agent captures itepoch-ms at run start, for the wall-clock panel
topicLanguagezhlanguage of human-readable text
styleclaudetemplate: claude / minimal / academic / magazine
nMin8sub-topic floor
nMaxnonesub-topic ceiling (omit for topic-driven, no cap)
adversarialtruerun the GAN-shaped verify stage
adversarialMaxClaims8cap on claims sent to refute-panels

Design principles

  • Zero-baseline. Every run is standalone. Subagents are told not to anchor on prior reports or "known conclusions" — the defense against confirmation bias compounding across runs (a hallucinated source in run A becoming "verified fact" in run C). Feed objective inputs (dates, known facts) freely; just don't anchor on prior conclusions.
  • Subagent-writes-raw. Bodies go to disk; only control-flow metadata crosses agent boundaries (via JSON-Schema-validated returns). This is what keeps the orchestrator's context small.
  • Source-quality heuristics. A 5-tier ladder (primary academic → official/first-party → established secondary → community → SEO content farm). high confidence requires ≥2 independent sources, ≥1 primary/official, and a real fetched evidence quote. SEO farms are barred from being primary support; citation frequency ≠ accuracy.
  • No silent caps. Sub-topic count is topic-driven with no upper limit. The Claude Code workflow runtime — not this script — bounds how many subagents run concurrently and runs the rest in waves, so adding sub-topics past that bound buys coverage, not speed (see Concurrency & cost reality). The pipeline aborts (keeping partial raw/) if ≥ ceil(N/2) sub-topics come back empty/failed.
  • Resume-aware. The plan agent scans raw/ for completed briefs and skips them; combined with the runtime's native resumeFromRunId, an interrupted run can continue.

Concurrency & cost reality

The Claude Code workflow runtime — not this script — bounds how many subagents run concurrently. At the time of writing that bound is min(16, cores−2) (e.g. ~8 on a 10-core machine), but it's a property of the runtime and may change across versions. All N sub-topics are spawned at once; the extras queue and run as slots free. So:

  • "No sub-topic cap" is true, but finer slicing only speeds things up within that concurrency bound — beyond it you're buying coverage, and wall-clock can grow.
  • Expect ~100k–400k+ tokens and dozens to 100+ agent calls per run on a broad topic with adversarial on. This is the cost of the quality; it is not optimized away.

Templates

Four self-contained HTML templates in templates/ ({{PLACEHOLDER}}-based, no build step):

  • claude — hand-drawn, warm "Claude" aesthetic (the default).
  • minimal — clean and plain.
  • academic — paper-like.
  • magazine — editorial layout.

The report is data-self-contained — it embeds the full dataset in a <script type="application/json"> block, so it re-renders without the temp files. (Note: the claude and magazine templates pull web fonts from Google Fonts at view time and fall back to system fonts offline; academic and minimal use no font CDN.)

See examples/sample-report.html for a rendered sample (from the synthetic dataset in adapters/example-harness-output.json).

Optional: rendering Claude's built-in harness

Claude Code ships its own built-in deep-research workflow. If you'd rather use that as the research engine but still want this repo's nicely-rendered HTML report, adapters/built-in-harness-render.js is a standalone render-only adapter that eats the built-in harness's output JSON. It is not needed by the main deep-research-harness.js (which renders itself in its Render stage). See adapters/README.md.

Hacking on it

The script uses top-level await and return, so a bare node --check mis-reports errors. Validate syntax by wrapping it in an async function first:

{ echo 'async function __wf(){'; sed 's/^export //' deep-research-harness.js; echo '}'; } > /tmp/chk.mjs
node --check /tmp/chk.mjs

License

MIT © 2026 Yihan Zhu

Built with Claude Code.

Ver o original no GitHub

Bom para

Relacionados