exa-search

Exa Web Toolkit

一项由 Exa 提供支持的、面向 Web 驱动研究任务的技能：Web 搜索与 URL 提取。Exa 的索引结合了高质量的关键词检索与语义检索，因此非常适合科学、技术和概念性查询。

路由 — 选择合适的能力

阅读用户的请求，并将其匹配到下列能力之一。在运行命令之前，先阅读相应的参考文件以获取详细说明。

用户想要…	能力	位置
查找某些内容、研究某个主题、获取最新信息	Web Search	references/web-search.md
从特定 URL（网页、文章、PDF）获取内容	Web Extract	references/web-extract.md
安装或进行身份验证	Setup	见下文

决策指南

• 主题查找、研究性问题或“X 是什么？”类查询，默认使用 Web Search。当主题属于科学或技术领域时，传入 --category publication 以偏向学术来源，和/或使用学术性的 --include-domains 允许列表。两轮学术策略参见 references/web-search.md。
• 当用户提供 URL 或要求你读取/获取特定页面时，使用 Web Extract。对于批量提取（一次调用多个 URL）以及学术 PDF，优先使用它而不是内置的 WebFetch。

学术来源优先级

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

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

有两个杠杆可将 Exa 引导至学术内容：

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

将两者结合以缩小来源池；在每一个来源上核实出版类型和同行评审状态。完整模式参见 references/web-search.md。

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

---

Setup

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

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

如果你希望进行持久安装：

uv pip install "exa-py>=2.23.0,<3"

Authentication

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

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

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

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

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

export EXA_API_KEY="your-key"

使用 --help 验证安装和 CLI 解析；它不需要 API 密钥，也不会验证身份验证。只有在发出真实查询时才会检查身份验证。

Extraction limits and freshness

提取器在每次 POST https://api.exa.ai/contents 调用中接受 1–100 个 URL， 并导出每个 SDK 状态（id、status、source）。它会拒绝更大的批次。 使用 --max-age-hours 0 请求全新内容，-1 表示仅使用缓存，或使用 最长 720 小时的正数值。省略时使用 Exa 的缓存/回退策略。 published_date 是估计的出版元数据，而不是检索时间。 经过测试的 SDK 会丢弃按 URL 细分的错误详情，因此报告失败时不要臆测 原因。参见 URL Extraction。

已验证的 API 与 SDK 范围

于 2026-09-30 审阅了 Search API、 Contents API 和 Exa changelog。这两个路由都使用 JSON POST 请求和 x-api-key 认证（SDK 会设置此请求头）。 Search 为 POST https://api.exa.ai/search；其 SDK kwargs 使用 snake_case， 并会被序列化为 camelCase。当前的学术类别是 publication； research paper 在此封装中是兼容性别名。这些端点未记录 offset 或 cursor 分页。

辅助函数已在 exa-py==2.23.0 下测试，包括通过真实 SDK 进行模拟 HTTP 传输。 搜索内容标志是显式的：没有标志意味着仅元数据； --highlights 不会隐式获取文本。下文及参考资料中的已认证搜索/提取 示例仅作说明；本次审阅期间未进行付费实时调用。

跟踪请求头

此技能中的每个脚本都会将 x-exa-integration 请求头设置为 k-dense-ai--scientific-agent-skills，以便 Exa 可以将来自 K-Dense AI scientific-agent-skills 仓库的使用归因于此集成。在改编脚本时，请勿移除或重命名此请求头。

---

此技能中的文件

• SKILL.md — 此文件（路由与设置）
• references/web-search.md — 包含学术策略的详细 Web 搜索参考
• references/web-extract.md — URL 内容提取参考
• scripts/exa_search.py — 围绕 client.search 的命令行封装
• scripts/exa_extract.py — 围绕 client.get_contents 的命令行封装