asta-skill

Asta MCP — 学术论文搜索

Asta 是 Ai2 的 Scientific Corpus Tool，通过 MCP（可流式传输的 HTTP 传输）提供 Semantic Scholar 学术图谱。本技能将告诉 Agent 针对不同意图应调用哪个 Asta 工具，以及如何将它们组合成实用的工作流。

• MCP 端点： https://asta-tools.allen.ai/mcp/v1
• 身份验证： x-api-key 请求头（请访问 https://share.hsforms.com/1L4hUh20oT3mu8iXJQMV77w3ioxm 申请密钥）
• 传输方式： 可流式传输的 HTTP

前置检查

调用任何工具前，请确认 Asta MCP 服务已在宿主 Agent 中注册。工具名称将以安装时选择的 MCP 服务名称作为前缀（通常为 asta__<tool> 或 mcp__asta__<tool>）。

如果看不到任何 Asta 工具，不要发起原始 HTTP 请求，也不要编造结果。请告知用户，将 https://asta-tools.allen.ai/mcp/v1 注册为带有 x-api-key 请求头的可流式传输 HTTP MCP 服务，然后重启或重新加载宿主。最简配置提示：

• Codex CLI：将 [mcp_servers.asta] url = "https://asta-tools.allen.ai/mcp/v1" 和 env_http_headers = { "x-api-key" = "ASTA_API_KEY" } 添加到 ~/.codex/config.toml。
• Claude Code：运行 claude mcp add -t http -s user asta https://asta-tools.allen.ai/mcp/v1 -H "x-api-key: $ASTA_API_KEY"。
• 通用 MCP 客户端：将服务 URL 配置为 https://asta-tools.allen.ai/mcp/v1，并设置请求头 { "x-api-key": "<YOUR_API_KEY>" }。

工具速查表 — 意图 → Asta 工具

用户意图	Asta 工具	备注
广泛的主题搜索	search_papers_by_relevance	支持会议和日期筛选
已知论文标题	search_paper_by_title	可选的 venues 和 publication_date_range 筛选
已知 DOI / arXiv / PMID / CorpusId / MAG / ACL / SHA / URL	get_paper	查询单篇论文
一次查询多个已知 ID	get_paper_batch	批量查询——将 ids 作为 JSON 数组传入（不要传逗号分隔的字符串，这与 snippet_search 的 paper_ids 不同）；优先使用此工具，而非依次调用 N 次 get_paper；无法解析的 ID 会被静默丢弃（不会返回 null 或错误），因此请将返回的 paperId 与输入进行核对
谁引用了论文 X	get_citations	查询后续引用，支持分页；接受 publication_date_range，但不接受 venues；limit 默认值为 100
按姓名查找作者	search_authors_by_name	默认 fields="name" 只返回 name 和 authorId——若要获取任何可用于排名的信息，请显式请求 affiliations,paperCount,citationCount,hIndex,externalIds；externalIds 包含 ORCID/DBLP（也可选择 url/homepage）
某位作者的论文	get_author_papers	传入作者 ID；字段参数为 paper_fields（不是 fields）；limit 默认值为 1000——请显式设置
查找提及 X 的段落	snippet_search	约 500 词的摘录（标题/摘要/正文，不包括图注和参考文献）；请参阅下方针对 snippet 的参数

大多数搜索/引用工具都接受 publication_date_range（格式为 YYYY-MM-DD:YYYY-MM-DD；也接受 "2021:"、":2015-01"、"2015:2020" 这类年份简写）、venues 和用于选择字段的 fields——当用户意图限定了范围时（例如“近期”“自 2022 年以来”“在 NeurIPS 上”），请传入这些参数。venues 与 Semantic Scholar 的精确会议名称匹配（以逗号分隔，例如 "Nature,N. Engl. J. Med."）；随意使用的名称（如 "NeurIPS"）可能无法匹配，因此若会议查询结果为空，请改用日期/关键词筛选。

各工具的参数例外情况（已对照在线服务验证——参数使用错误会导致参数格式错误或被静默忽略）：

• get_author_papers 的字段选择参数名为 paper_fields，而非 fields（传入 fields= 会被静默忽略——你只会获得标题）；该工具接受 publication_date_range，但不接受 venues 筛选。它会在分页之后应用日期筛选，因此可能漏掉范围内的有效论文（某位知名作者使用 2024:2024 查询时返回了 []），因此要获取可靠结果，请在客户端按主题/会议和日期缩小范围。
• get_citations 接受 publication_date_range，但不接受 venues。
• snippet_search 既不接受 fields，也不接受 publication_date_range。它提供的参数为：inserted_before（日期筛选，格式为 YYYY-MM-DD/YYYY-MM/YYYY）、paper_ids（以逗号分隔的 ID 列表，最多 100 个，用于将摘录限定到特定论文）和 venues。

⚠️ fields 参数 — 避免上下文溢出

get_paper / get_paper_batch 接受 fields 字符串。切勿通过 fields 请求 citations 或 references — 单篇引用量极高的论文（例如 Attention Is All You Need）会返回超过 200k 个字符，导致超出 Agent 的上下文窗口。对于前向引用，请使用专用的 get_citations 工具（支持分页）。Asta 不提供专用的 get_references 工具 — 如需获取论文的参考文献列表，仅对确定参考文献数量较少的论文使用 get_paper 和 fields=references（通常少于 100 条）。

也要留意行数，而不仅是每行的大小：默认的 limit 值较大 — get_author_papers 最多返回 1000 条，get_citations 返回 100 条，search_papers_by_relevance 返回 50 条，snippet_search 返回 20 条（每个片段约 500 个词，因此它是每行开销最大的工具）。请传入明确且较小的 limit — 例如，论文／引用列表设为 20–50，片段设为约 5–10 — 除非用户要求完整列表。

使用针对具体任务的字段预设：

元数据查询：

title,year,authors,venue,tldr,url,abstract

搜索／排序／结果表格：

title,year,authors,venue,tldr,url,abstract,citationCount,influentialCitationCount

DOI／导出交接：

title,year,authors,venue,tldr,url,externalIds

仅在需要时添加 journal、publicationDate、fieldsOfStudy、isOpenAccess。如果未来的响应中缺少 citationCount 等直通字段，请妥善降级：按相关性／时效性排序，并省略基于引用量的说法。

调用示例（按引用量排序的主题搜索，并提供 DOI 供下游获取）：

search_papers_by_relevance(
  keyword="mixture of experts routing",
  publication_date_range="2023:",
  fields="title,year,authors,venue,tldr,url,externalIds,citationCount",
  limit=20,
)

获取 DOI／外部 ID（未公开文档但受支持）

Asta 官方的 fields 列表不包含 externalIds，但该字段会透明地传递到底层 Semantic Scholar API，实际可用。将 externalIds 添加到 fields，即可获取 DOI、PubMed、PubMedCentral、ArXiv、MAG、DBLP、CorpusId。同样的直通方式也适用于 citationCount 和 influentialCitationCount（它们也不在官方列表中，但已验证可正常返回）— 按引用量对结果排序时，请请求这些字段。注意事项：

• 并非所有论文都有 DOI — 纯 arXiv 预印本通常只返回 ArXiv 和 CorpusId。
• 使用 get_paper("DOI:...") 查询的可靠性并非 100%；某些有效 DOI 会返回 not found。建议先按标题搜索，再从结果中读取 externalIds。
• 由于此功能未记录在文档中，请将其视为尽力提供；如果未来版本的 Asta 移除了该功能，请妥善降级。

工作流模式

模式 1 — 主题发现

1. search_papers_by_relevance(keyword, publication_date_range="<current_year-5>:", venues=?, fields="title,year,authors,venue,tldr,url,abstract,citationCount,influentialCitationCount", limit=20) → 初始结果（根据今天的日期计算起始年份 — 例如，2026 年传入 publication_date_range="2021:"；如果用户要求较早的研究，则调整或移除筛选条件）
2. 按 citationCount + 时效性排序／呈现排名靠前的 N 篇
3. 提供后续选项：对影响力最大的论文使用 get_citations，或使用 snippet_search 查找具体论断

模式 2 — 种子论文扩展

1. get_paper(DOI|arXiv|...) → 验证种子论文
2. get_citations(paperId) → 向前扩展
3. 可选：使用种子论文标题中的关键词调用 search_papers_by_relevance，进行横向发现
4. 呈现前按 paperId 去重

模式 3 — 作者深入研究

1. search_authors_by_name(name, fields="name,affiliations,paperCount,citationCount,hIndex,externalIds") → 选择正确的作者档案。必须请求这些字段 — 默认的 fields="name" 只返回 name 和 authorId，没有可用于排序的字段。如果存在 externalIds.ORCID，请优先用它消歧（这是最强的信号），其次参考 paperCount／citationCount／hIndex；即使请求了 affiliations，它也经常为空，因此仅将其用作决胜因素
2. get_author_papers(authorId, limit=50, paper_fields="title,year,authors,venue,tldr,url,abstract,citationCount") → 获取数量有限的第一页；只有用户要求完整列表时才继续获取
3. 在客户端按主题关键词或日期筛选

模式 4 — 证据检索

1. snippet_search(claim_query) → 查找提出或支持某项主张的段落
2. 若要在特定论文范围内为某项主张提供依据，请传入 paper_ids="<id1>,<id2>,…"（≤100），这样检索到的片段只会来自该集合
3. 对于每条结果，可选用 get_paper(id) 获取完整元数据

输出与交互规则

• 始终报告使用了哪个工具。仅当工具提供总数时才报告总数；否则报告返回数量／每页数量，不要暗示这是整个语料库的总数。
• 最多将 10 条结果以表格形式呈现（标题、年份、刊物，若已获取则包括引用数），然后详细介绍最相关的结果。
• 如果用户用中文提问，请用中文呈现摘要；标题保留原文。
• 展示结果后，提供以下选项：Details / Refine / Citations / Snippet / Export / Done。

关键规则

• 优先批量处理意图，避免来回询问。 如果用户的问题需要两次独立查询，请在同一轮中并行调用 MCP 工具，而不是依次调用。
• 切勿猜测 ID。 如果用户提供的标题不明确，请先使用 search_paper_by_title，再调用 get_paper。
• 遵守速率限制。 API 密钥可以提高限额，但并非无限制；不要超出用户要求，继续扩展引用关系图。
• 不要编造字段。 如果 Asta 返回的 abstract 或 venue 为 null，请如实说明，不要凭空补充。

处理 Asta 响应

情况	处理方式
abstract 为空	并非语料库中的所有论文都有全文——请使用 snippet_search，或退而仅依据标题和 TLDR
作者消歧不确定	提前请求排名字段（参见模式 3——默认情况下不会返回这些字段）；优先使用 externalIds.ORCID，其次参考 paperCount／citationCount／hIndex，仅在平局时参考 affiliations
按日期筛选的结果	publication_date_range 筛选条件可能会返回 publicationDate 为 null 的记录（仅保证有 year）；日期未知的论文会按其年份的 1 月 1 日处理，因此对边界年份的筛选只是近似结果
429 Too Many Requests	请稍后重试；使用 get_paper_batch 批量获取，而不要依次调用 get_paper
需要 DOI／PubMed ID／arXiv ID	将 externalIds 添加到 fields（参见上文“获取 DOI”）；如果没有 DOI，则退而使用 ArXiv ID