exa-search

用途

Exa Web Toolkit 是一个由 Exa 提供支持的网页研究技能，用于网页搜索与 URL 内容提取两类任务。Exa 的索引结合了高质量的关键词检索与语义检索，因此特别适合科学、技术和概念性查询。

主要能力

该技能提供两项能力，需根据用户请求进行路由选择：

Web Search（网页搜索）：用于查找信息、研究主题、获取当前信息。详细说明见 references/web-search.md。
Web Extract（网页提取）：用于从指定 URL 获取内容（网页、文章、PDF）。详细说明见 references/web-extract.md。

决策指南

对于主题查询、研究问题或“X 是什么”类查询，默认使用 Web Search。当主题属于科学或技术领域时，可传入 --category "research paper" 以偏向学术来源，和/或使用学术 --include-domains 允许列表。学术两遍检索策略见 references/web-search.md。
当用户提供 URL 或要求读取/获取特定页面时，使用 Web Extract。相比内置 WebFetch，在批量提取（一次调用多个 URL）和学术 PDF 场景下优先使用本技能。

学术来源优先级

对于技术或科学查询，优先选择学术与科学来源：

同行评审期刊文章和会议论文，优先于博客文章或新闻
当没有同行评审版本时，使用预印本（arXiv、bioRxiv、medRxiv）
机构与政府来源（NIH、WHO、NASA、NIST），优先于商业网站
一手研究，优先于二手摘要

引导 Exa 偏向学术内容有两个杠杆：

--category "research paper" 使检索偏向学术来源。
--include-domains 配合学术允许列表（arxiv.org、nature.com、pubmed.ncbi.nlm.nih.gov 等）限制域名池。

两者结合可获得严格学术结果。完整模式见 references/web-search.md。

引用学术来源时，除标准引用格式外，还应尽可能包含作者姓名和出版年份（例如 Smith et al., 2025）。如果存在 DOI，优先使用 DOI 链接。

使用方式

安装

该技能使用 exa-py Python SDK。scripts/ 中的脚本通过 PEP 723 内联元数据声明依赖，因此可直接用 uv run 运行，无需单独安装步骤：

uv run --with exa-py python "$SKILL_PATH/scripts/exa_search.py" --help

如需持久安装：

uv pip install "exa-py>=1.14.0"

认证

所有命令从 EXA_API_KEY 环境变量读取 API 密钥。可在 dashboard.exa.ai/api-keys 获取 Exa API 密钥。

首先检查项目根目录是否存在 .env 文件且包含 EXA_API_KEY。如果存在，加载它：

dotenv -f .env run -- uv run --with exa-py python "$SKILL_PATH/scripts/exa_search.py" "your query"

如果 dotenv 不可用，安装它：uv pip install python-dotenv[cli]。

如果没有 .env，为当前会话导出密钥：

export EXA_API_KEY="your-key"

通过运行任意脚本并加 --help 进行验证——如果密钥已设置，它会干净退出；认证检查仅在发起真实查询时运行。

跟踪请求头

该技能中的每个脚本都会将 x-exa-integration 请求头设置为 kalarislabs--research-agent-skills，以便 Exa 将来自 research-agent-skills 项目的使用归因到该集成。在改编脚本时，不要移除或重命名此请求头。

技能内文件

SKILL.md — 本文件（路由与设置）
references/web-search.md — 详细的网页搜索参考，含学术策略
references/web-extract.md — URL 内容提取参考
scripts/exa_search.py — client.search_and_contents 的 CLI 封装
scripts/exa_extract.py — client.get_contents 的 CLI 封装

适用场景

需要搜索网页、研究主题、查找当前信息时
需要从特定 URL（网页、文章、PDF）获取内容时
批量提取多个 URL 内容时
处理学术 PDF 时
科学、技术或概念性查询，需要偏向学术来源时

限制与注意事项

智能体操作流程

检查环境。确认研究问题、数据库、日期范围和纳入标准。
确定输入。从数据或用户处确认格式、标识符和参数。对于任何会改变结果的取值，应询问而非猜测。
先运行小规模版本。在单个数据库上以窄查询运行搜索，检查结果是否相关。
使用上述说明和参考执行完整任务。
验证结果。每条引用都来自具有可解析标识符的真实记录；记录计数和搜索字符串。
报告。说明运行了什么（版本、命令、参数）、检查了什么，以及仍不确定的内容。

异常处理

API 触发速率限制或返回错误：退避重试、减小批量大小或切换数据库，并报告缺口。
说明中的函数、标志或端点与已安装版本不符：查阅已安装版本自身的文档（help()、--help、官方文档），进行调整并告知用户。绝不虚构 API。
必需输入、标识符或参数不明确：询问用户，或在运行前明确说明假设。

完整性规则

绝不捏造结果、参数、标识符、引用或统计数据。如果某项无法运行或验证，应明确说明。
绝不总结未检索到的论文；绝不凭记忆引用。
将此处特定版本的细节视为可能过时：对照已安装版本的官方文档进行确认。
在涉及花钱、消耗共享 GPU 或云配额、触及个人或患者数据、或不可撤销的操作前，先询问。

技能介绍

用途