mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-05-24 08:55:59 +00:00
16aa51c9b3
* feat(skills): add systematic-literature-review skill for multi-paper SLR workflows Adds a new skill that produces a structured systematic literature review (SLR) across multiple academic papers on a topic. Addresses #1862 with a pure skill approach: no new tools, no architectural changes, no new dependencies. Skill layout: - SKILL.md — 4+1 phase workflow (plan, search, extract, synthesize, present) - scripts/arxiv_search.py — arXiv API client, stdlib only, with a requests->urllib fallback shim modeled after github-deep-research's github_api.py - templates/{apa,ieee,bibtex}.md — citation format templates selected dynamically in Phase 4, mirroring podcast-generation's templates/ pattern Design notes: - Multi-paper synthesis uses the existing `task` tool to dispatch extraction subagents in parallel. SKILL.md's Phase 3 includes a fixed decision table for batch splitting to respect the runtime's MAX_CONCURRENT_SUBAGENTS = 3 cap, and explicitly tells the agent to strip the "Task Succeeded. Result: " prefix before parsing subagent JSON output. - arXiv only, by design. Semantic Scholar and PubMed adapters would push the scope toward a standalone MCP server (see #933) and are intentionally out of scope for this skill. - Coexists with the existing `academic-paper-review` skill: this skill does breadth-first synthesis across many papers, academic-paper-review does single-paper peer review. The two are routed via distinct triggers and can compose (SLR on many + deep review on 1-2 important ones). - Hard upper bound of 50 papers, tied to the Phase 3 concurrency strategy. Larger surveys degrade in synthesis quality and are better split by sub-topic. BibTeX template explicitly uses @misc for arXiv preprints (not @article), which is the most common mistake when generating BibTeX for arXiv papers. arxiv_search.py was smoke-tested end-to-end against the live arXiv API with two query shapes (relevance sort, submittedDate sort with category filter); all returned JSON fields parse correctly (id normalization, Atom namespace handling, URL encoding for multi-word queries). * fix(skills): prevent LLM from saving intermediate search results to file Adds an explicit "do not save" instruction at the end of Phase 2. Observed during Test 1 with DeepSeek: the model saved search results to a markdown file before proceeding to Phase 3, wasting 2-3 tool call rounds and increasing the risk of hitting the graph recursion limit. The search JSON should stay in context for Phase 3, not be persisted. * fix(skills): use relevance+start-date instead of submittedDate sorting Test 2 revealed that arXiv's submittedDate sorting returns the most recently submitted papers in the category regardless of query relevance. Searching "diffusion models" with sortBy=submittedDate in cs.CV returned papers on spatial memory, Navier-Stokes, and photon-counting CT — none about diffusion models. The LLM then retried with 4 different queries, wasting tool calls and approaching the recursion limit. Fix: always sort by relevance; when the user wants "recent" papers, combine relevance sorting with --start-date to constrain the time window. Also add an explicit "run the search exactly once" instruction to prevent the retry loop. * fix(skills): wrap multi-word arXiv queries in double quotes for phrase matching Without quotes, `all:diffusion model` is parsed by arXiv's Lucene as `all:diffusion OR model`, pulling in unrelated papers from physics (thermal diffusion) and other fields. Wrapping in double quotes forces phrase matching: `all:"diffusion model"`. Also fixes date filtering: the previous bug caused 2011 papers to appear in results despite --start-date 2024-04-09, because the unquoted query words were OR'd with the date constraint. Verified: "diffusion models" --category cs.CV --start-date 2024-04-09 now returns only relevant diffusion model papers published after April 2024. * fix(skills): add query phrasing guide and enforce subagent delegation Two fixes from Test 2 observations with DeepSeek: 1. Query phrasing: add a table showing good vs bad query examples. The script wraps multi-word queries in double quotes for phrase matching, so long queries like "diffusion models in computer vision" return 0 results. Guide the LLM to use 2-3 core keywords + --category instead. 2. Subagent enforcement: DeepSeek was extracting metadata inline via python -c scripts instead of using the task tool. Strengthen Phase 3 to explicitly name the task tool, say "do not extract metadata yourself", and explain why (token budget, isolation). This is more direct than the previous natural-language-only approach while still providing the reasoning behind the constraint. * fix(skills): strengthen search keyword guidance and subagent enforcement Address two issues found during end-to-end testing with DeepSeek: 1. Search retry: LLM passed full topic descriptions as queries (e.g. "diffusion models in computer vision"), which returned 0 results due to exact phrase matching and triggered retries. Added explicit instruction to extract 2-3 core keywords before searching. 2. Subagent bypass: LLM used python -c to extract metadata instead of dispatching via task tool. Added explicit prohibition list (python -c, bash scripts, inline extraction) with ❌ markers for clarity. * fix(skills): address Copilot review feedback on SLR skill - Fix legacy arXiv ID parsing: preserve archive prefix for pre-2007 papers (e.g. hep-th/9901001 instead of just 9901001) - Fix phase count: "four phases" -> "five phases" - Add subagent_enabled prerequisite note to SKILL.md Notes section - Remove PR-specific references ("PR 1") from ieee.md and bibtex.md templates, replace with workflow-scoped wording - Fix script header: "stdlib only" -> "no additional dependencies required", fix relative path to github_api.py reference - Remove reference to non-existent docs/enhancement/ path in header * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Willem Jiang <willem.jiang@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
157 lines
7.2 KiB
Markdown
157 lines
7.2 KiB
Markdown
# BibTeX Citation Template
|
|
|
|
Use this template when the user mentions BibTeX, LaTeX, wants machine-readable references, or is writing a paper that will be typeset with a LaTeX citation style (natbib, biblatex, etc.).
|
|
|
|
## Critical: use `@misc`, not `@article`, for arXiv papers
|
|
|
|
**arXiv preprints must be cited as `@misc`, not `@article`.** This is the most common mistake when generating BibTeX for arXiv papers, and it matters:
|
|
|
|
- `@article` requires a `journal` field. arXiv is not a journal — it is a preprint server. Using `@article` with `journal = {arXiv}` is technically wrong and some bibliography styles will complain or render it inconsistently.
|
|
- `@misc` is the correct entry type for preprints, technical reports, and other non-journal publications. It accepts `howpublished` and `eprint` fields, which is exactly what arXiv citations need.
|
|
- Only switch to `@article` (or `@inproceedings`) when the paper has been **formally published** in a peer-reviewed venue and you have the venue metadata. In this workflow we only have arXiv metadata, so always emit `@misc`.
|
|
|
|
## Citation Format Rules
|
|
|
|
### Entry structure for arXiv preprints
|
|
|
|
```bibtex
|
|
@misc{citekey,
|
|
author = {LastName1, FirstName1 and LastName2, FirstName2 and ...},
|
|
title = {Title of the Paper},
|
|
year = {YYYY},
|
|
eprint = {ARXIV_ID},
|
|
archivePrefix = {arXiv},
|
|
primaryClass = {PRIMARY_CATEGORY},
|
|
url = {https://arxiv.org/abs/ARXIV_ID}
|
|
}
|
|
```
|
|
|
|
**Real example**:
|
|
|
|
```bibtex
|
|
@misc{vaswani2017attention,
|
|
author = {Vaswani, Ashish and Shazeer, Noam and Parmar, Niki and Uszkoreit, Jakob and Jones, Llion and Gomez, Aidan N. and Kaiser, {\L}ukasz and Polosukhin, Illia},
|
|
title = {Attention Is All You Need},
|
|
year = {2017},
|
|
eprint = {1706.03762},
|
|
archivePrefix = {arXiv},
|
|
primaryClass = {cs.CL},
|
|
url = {https://arxiv.org/abs/1706.03762}
|
|
}
|
|
```
|
|
|
|
### Field rules
|
|
|
|
- **Cite key**: `<firstauthorlast><year><firstwordoftitle>`, all lowercase, no punctuation. Example: `vaswani2017attention`. Keys must be unique within the report.
|
|
- **`author`**: `LastName, FirstName and LastName, FirstName and ...` — note the literal word `and` between authors, not a comma. LaTeX requires this exact separator. LastName comes first, then a comma, then the given names.
|
|
- **Special characters**: escape or wrap LaTeX-sensitive characters. For example, `Łukasz` becomes `{\L}ukasz`, `é` becomes `{\'e}` (or wrap the whole name in braces to preserve casing: `{Łukasz}`). If unsure, wrap the problematic name in curly braces.
|
|
- **`title`**: preserve the paper's capitalization by wrapping it in double braces if it contains acronyms or proper nouns you need to keep capitalized: `title = {{BERT}: Pre-training of Deep Bidirectional Transformers}`. Otherwise plain braces are fine.
|
|
- **`year`**: the 4-digit year from the paper's `published` field.
|
|
- **`eprint`**: the **bare arXiv id** (e.g. `1706.03762`), **without** the `arXiv:` prefix and **without** the version suffix.
|
|
- **`archivePrefix`**: literal string `{arXiv}`.
|
|
- **`primaryClass`**: the first category from the paper's `categories` list (e.g. `cs.CL`, `cs.CV`, `stat.ML`). This is the paper's primary subject area.
|
|
- **`url`**: the full `abs_url` from paper metadata.
|
|
|
|
## Report Structure
|
|
|
|
The BibTeX report is slightly different from APA / IEEE: the **bibliography is a separate `.bib` file**, and the main report uses LaTeX-style `\cite{key}` references that would resolve against that file. Since we are emitting markdown, we show `\cite{key}` verbatim in the prose and emit the BibTeX entries inside a fenced code block at the end.
|
|
|
|
```markdown
|
|
# Systematic Literature Review: <Topic>
|
|
|
|
**Date**: <YYYY-MM-DD>
|
|
**Papers surveyed**: <N>
|
|
**Scope**: <arXiv search query, category, time window>
|
|
**Citation format**: BibTeX
|
|
|
|
## Executive Summary
|
|
|
|
<3-5 sentences. Use \cite{key} form for citations, e.g. "Transformer architectures \cite{vaswani2017attention} have become the dominant approach.">
|
|
|
|
## Methodology
|
|
|
|
This review surveyed <N> arXiv papers retrieved on <YYYY-MM-DD> using the query `<query>`<, filtered to category <cat>><, published between <start_date> and <end_date>>. Metadata extraction was performed by language-model agents, with cross-paper synthesis performed by the lead agent. All citations in this report use BibTeX cite keys; the corresponding `.bib` entries are at the end of this document.
|
|
|
|
**Limitations of this review**: arXiv preprints are not peer-reviewed; coverage is limited to arXiv.
|
|
|
|
## Themes
|
|
|
|
### Theme 1: <Theme name>
|
|
|
|
<Paragraphs describing the theme. Cite with \cite{key} form: "The original transformer architecture \cite{vaswani2017attention} introduced self-attention, which was later extended in \cite{dai2019transformerxl}.">
|
|
|
|
### Theme 2: <Theme name>
|
|
|
|
<...>
|
|
|
|
## Convergences and Disagreements
|
|
|
|
**Convergences**: <e.g. "Multiple papers \cite{key1,key2,key3} agree that X is necessary.">
|
|
|
|
**Disagreements**: <...>
|
|
|
|
## Gaps and Open Questions
|
|
|
|
<...>
|
|
|
|
## Per-Paper Annotations
|
|
|
|
### \cite{vaswani2017attention} — "Attention Is All You Need" (2017)
|
|
|
|
**Research question**: <1 sentence>
|
|
**Methodology**: <1-2 sentences>
|
|
**Key findings**:
|
|
- <bullet>
|
|
- <bullet>
|
|
- <bullet>
|
|
**Limitations**: <1-2 sentences>
|
|
|
|
### \cite{devlin2018bert} — "BERT: Pre-training of Deep Bidirectional Transformers" (2018)
|
|
|
|
<...>
|
|
|
|
## BibTeX Bibliography
|
|
|
|
Save the entries below to a `.bib` file and reference them from your LaTeX document with `\bibliography{filename}`.
|
|
|
|
\`\`\`bibtex
|
|
@misc{vaswani2017attention,
|
|
author = {Vaswani, Ashish and Shazeer, Noam and Parmar, Niki and Uszkoreit, Jakob and Jones, Llion and Gomez, Aidan N. and Kaiser, {\L}ukasz and Polosukhin, Illia},
|
|
title = {Attention Is All You Need},
|
|
year = {2017},
|
|
eprint = {1706.03762},
|
|
archivePrefix = {arXiv},
|
|
primaryClass = {cs.CL},
|
|
url = {https://arxiv.org/abs/1706.03762}
|
|
}
|
|
|
|
@misc{devlin2018bert,
|
|
author = {Devlin, Jacob and Chang, Ming-Wei and Lee, Kenton and Toutanova, Kristina},
|
|
title = {{BERT}: Pre-training of Deep Bidirectional Transformers for Language Understanding},
|
|
year = {2018},
|
|
eprint = {1810.04805},
|
|
archivePrefix = {arXiv},
|
|
primaryClass = {cs.CL},
|
|
url = {https://arxiv.org/abs/1810.04805}
|
|
}
|
|
|
|
... more entries, one per paper ...
|
|
\`\`\`
|
|
```
|
|
|
|
(Note: in the actual saved report, use a real fenced code block `` ```bibtex `` — the backticks above are escaped only because this template file itself is inside a markdown code block when rendered.)
|
|
|
|
## Quality checks before finalizing
|
|
|
|
Before saving the report, verify:
|
|
|
|
- [ ] Every entry is `@misc`, not `@article` (this workflow only has arXiv metadata).
|
|
- [ ] Cite keys are unique within the report.
|
|
- [ ] Cite keys follow the `<firstauthorlast><year><firstword>` pattern, all lowercase.
|
|
- [ ] `author` field uses ` and ` (the literal word) between authors, not commas.
|
|
- [ ] LaTeX special characters in author names are escaped or brace-wrapped.
|
|
- [ ] `eprint` is the bare arXiv id (no `arXiv:` prefix, no version suffix).
|
|
- [ ] `primaryClass` is set from the paper's first category.
|
|
- [ ] Every `\cite{key}` in the text has a matching `@misc` entry in the bibliography.
|
|
- [ ] The bibliography is emitted inside a fenced ```` ```bibtex ```` code block so users can copy-paste directly into a `.bib` file.
|