research-literature-search

Research Literature Search

Goal

Convert a topic and 5–25 queries into a reviewable candidate literature bundle. Responsible for recall, field normalization, canonical deduplication, source auditing, and optional abstract completion; not responsible for scoring, inclusion/exclusion, subtopics, quotas, review writing, BibTeX, or PDF/Word export.research-literature-review Must consume this Skill's manifest and canonical candidates; must not duplicate the provider or redo deduplication.

Process

Input

Required:topic with explicit query JSON (--query-file/--queries); supports {"queries": [...]}, object arrays, or string arrays.
Empty queries are removed; valid queries default to 5–25, and fail-closed if not satisfied.
Optional:domain, year/document type/preprint filtering, provider order, per-query/total caps,scope_root。
Output must be within the caller's scope_root ; reject path traversal and absolute paths outside the manifest.

Execution steps

python3 skills/research-literature-search/scripts/search_runner.py run --topic "HER2 antibody-drug conjugates in breast cancer" --query-file ./queries.json --output-dir ./.bensz-api/search-bundle
python3 skills/research-literature-search/scripts/search_runner.py enrich-abstracts --input selected_papers.jsonl --output selected_papers_enriched.jsonl
python3 skills/research-literature-search/scripts/search_runner.py validate --bundle ./.bensz-api/search-bundle

run By default does not complete full abstracts; after selecting papers, run on demand enrich-abstracts. Providers follow provider_priority to execute priority-fallback-topup, stopping once the ~70% threshold is reached, with no commitment to a full provider union;mcp/duckduckgo is recorded in the pure Python runner as skipped/host tool required. Each attempt is written to attempts、Search Log、retrieval_strategy and topup_threshold。

Output

manifest.json is the sole entry point, using a separate directory for each run:

manifest.json
candidates_raw.jsonl          # 脱敏的最小 provider 信封
candidates_normalized.jsonl  # rls.paper.v1，去重前
candidates_deduped.jsonl     # canonical 候选池
provenance.jsonl              # provider/query/rank 映射
dedupe_map.json               # 合并边与选择依据
search_log.json               # 可读审计日志

Candidates must conform to rls.paper.v1: non-empty title, string array authors、identifiers、abstract_status、publication、sources、query_matches、quality_warnings, and retain legacy flat fields; missing values may only use null/[]。manifest status only for success、partial_success、failed; review accepts only the first two and verifies hash, schema, and count.

Output management

Temporary artifacts are written to the task workspace, and formal deliverables are saved per project conventions; do not overwrite, delete, or remotely write existing files without authorization. All paths must be confined within the authorized project.

Validation

Run the Skill's existing static checks, script validation, or manual review, and record pass criteria. The manifest stores query SHA-256, provider policy, attempts, truncation, deduplication parameters, cache mode, version, and artifact hash.

Failure and recovery

When a provider returns null, a non-object, or a nested source that is null , skip/retain and record the count or warning; if no valid candidates are returned no_valid_candidates, do not silently discard. Preprints are tagged and audited per domain profile (auto→computer_science/mathematics/biology/medicine/general), and the search layer does not certify conclusions. Legacy title/year/id only via an explicit legacy adapter with a legacy_adapted warning; adding provider/union policies requires a contract upgrade.

Constraints

JSON uses UTF-8, stable ordering, and deterministic serialization; ordering is comparable under the same fixture/config.
Do not write API keys, Cookies, full responses, or other credentials; do not disguise unverified information as established conclusions.

Common hard constraints

This block is maintained centrally by docs/templates/skill-common-constraints.md ; each SKILL.md 's ## 约束 must synchronize this block verbatim, and public rules must not be rewritten in copies.

When a task requires persistence, use the unique ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/ root directory; shared materials go into shared/, Skill-specific materials are placed into that Skill's input/、output/、log/。
Formal deliverables, source code, and formal plans are stored according to project conventions and are not written into the task workspace; without authorization, do not overwrite, delete, migrate, or write remotely.
Project maintenance changes check BAC availability and record requirements, AI outputs, tool results, file changes, and verification summaries; BAC only performs process auditing and does not replace attribution, responsibility, or compliance judgments.
Do not record API Keys, access tokens, passwords, Cookies, environment/credential files, private Prompts, identity information, local usernames, hostnames, or unnecessarily large raw data.
File paths must be normalized and restricted to the authorized project scope; external URLs, subprocesses, and network access follow least privilege to prevent path traversal, SSRF, and command injection.
Skill versions are uniquely recorded in their own config.yaml:skill_info.version; public API, protocol, directory, or configuration changes synchronize documentation and CHANGELOG.md。
bensz-collect-bugs is an Agent Skill; only design flaws in Bensz Agent Skill or the Bensz infrastructure itself are reported to it. First desensitize and write to ~/.bensz-skills/bugs/, the current task is not interrupted, public reporting only occurs when the user explicitly requests it, and directly modifying the source code of Skills already installed by the user is prohibited.

Skill-specific constraints

Must not exceed the scope declared in this Skill description and the process above; do not disguise unverified information as definite conclusions.