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，无状态（没有会话 ID，调用之间服务器端不会保留状态）
• 已验证行为的版本： Asta MCP 服务 v1.12.3，2026-10-01

前置检查

调用任何工具之前，请确认 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	limit 默认值为 50；支持 venues 和 publication_date_range
已知论文标题	search_paper_by_title	这是解析工具，而非搜索工具：返回最匹配的一篇论文及其 matchScore（即使 limit 为 5，也只返回 1 行）；支持 venues 和 publication_date_range
一个已知 ID	get_paper	ID 必须带前缀：DOI:、ARXIV:、PMID:、PMCID:、CorpusId:、MAG:、ACL:、URL:，或不带前缀的 40 位十六进制 Semantic Scholar ID。不带前缀的 arXiv ID（1706.03762）会返回 Paper with id 1706.03762 not found
多个已知 ID	get_paper_batch	ids 是一个 JSON 数组；无法解析的 ID 会被静默丢弃（输入 3 个 ID，只返回 1 篇论文，且不会报错），因此请将返回的 paperId 与输入逐一核对
谁引用了论文 X	get_citations	正向引用，limit 默认值为 100；接受 publication_date_range，不支持 venues；每行都封装在 {"citingPaper": {...}} 中
按姓名查找作者	search_authors_by_name	fields 默认值为 "name"，只返回 name 和 authorId；limit 默认值为 100
某位作者的出版物	get_author_papers	字段参数为 paper_fields；limit 默认值为 1000，按时间倒序排列；接受 publication_date_range，不支持 venues
提及 X 的段落	snippet_search	约 500 词的摘录（标题、摘要或正文；不包括图注和参考文献）；limit 默认值为 20，且每行数据量较大，实际返回行数可能少于 limit；参数见下文

不同工具的参数名称各不相同（未知参数会被忽略，而不会报错）

服务端会静默接受未知参数，因此参数名称写错会导致调用成功，但不会进行筛选。如果结果看起来未经筛选，请先怀疑参数名称，而不是数据集。

• get_author_papers 使用 paper_fields 而不是 fields 来选择字段。传入 fields= 会被忽略，结果只包含标题。
• get_citations 没有 venues 参数。传入 venues= 会被忽略，引用者行不会经过筛选。
• snippet_search 既没有 fields，也没有 publication_date_range。它支持 inserted_before（数据集插入日期，格式为 YYYY-MM-DD / YYYY-MM / YYYY）、paper_ids（以逗号分隔，最多 100 个 ID，用于将片段限制为指定论文）和 venues。
• 所有带有 fields / paper_fields 参数的工具都默认使用 title；省略该参数会悄无声息地返回无法排序、难以阅读的结果。
• 没有任何工具会返回匹配项总数。请报告返回的行数，切勿报告数据集总量。

行数和负载预算（实测大小）

调用	行数	负载
search_papers_by_relevance，limit=50，包含 abstract 的完整预设	50	~296 KB（~5.9 KB/行）
get_citations，默认 limit=100，fields=title,year,venue	100	~56 KB（~0.6 KB/行）
get_paper，fields=title,year,citations（《Attention Is All You Need》）	1	~200 KB
get_paper，fields=title,year,references（同一篇论文，41 条参考文献）	1	~8 KB
get_author_papers，limit=100，paper_fields=title,year	87	~33 KB（即使不含 abstract，每行也约 ~0.4 KB）
search_authors_by_name，fields=name,paperCount,papers	1 位作者	~30 KB（该作者的全部 87 篇论文）
snippet_search，limit=2	1 个片段	~4.6 KB

• 始终显式传入 limit：论文和引文列表设为 20–50，片段设为 5–10。默认值 50、100 和 1000 会大量占用上下文。
• snippet_search 是唯一一个文档默认值与线上服务端不一致的工具：已发布的文档页面称默认值为 250，线上架构定义称为 20；实测未设置 limit 时返回 20 行 / ~85 KB。请以线上架构定义为准，并显式设置 limit。
• 切勿在 get_paper / get_paper_batch 的 fields 中请求 citations 或 references：一篇被大量引用的论文会返回 200 KB 以上的数据。查询前向引文请使用 get_citations（支持分页）；查询参考文献列表时，只对你确认参考文献少于约 100 条的论文请求 references。
• 切勿在 search_authors_by_name 中请求 papers：它会返回作者的完整发表列表，并忽略 limit。请改用显式设置 limit 的 get_author_papers。
• 如果输出是表格或用于排序，请移除 abstract；仅为实际准备介绍的少数论文获取摘要。

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

元数据查询：

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。

可以正常使用但未记录的字段（透传）

externalIds、citationCount 和 influentialCitationCount 未列入已记录的字段列表，但会透明地透传给 Semantic Scholar 并正确返回（已在 v1.12.3 上验证）。见过的 externalIds 键包括：DOI、ArXiv、PubMed、PubMedCentral、CorpusId、MAG、DBLP。注意事项：

• 并非每篇论文都有 DOI，尤其是 arXiv 预印本，它们可能仅包含 ArXiv + CorpusId。
• 已测试的 ID 均可通过 DOI 查询（DOI:10.1038/s41586-021-03819-2、DOI:10.1101/...、DOI:10.1371/journal.pone.0000308 均已成功解析），但请将其视为尽力而为的方式，并在失败时改用标题搜索加 externalIds。
• 即使未请求，get_paper 也会返回 paperId、isOpenAccess 和 openAccessPdf；journal 通常只包含 {"pages": ...}。
• 所有这些都应视为尽力而为；如果未来的 Asta 版本移除这些内容，请妥善降级处理。

日期和会场筛选器

publication_date_range 接受 YYYY-MM-DD:YYYY-MM-DD 格式，两端均可省略，也支持年份或月份简写：2021:、:2015-01、2015:2020、2019-03。它适用于 search_papers_by_relevance、search_paper_by_title、get_citations 和 get_author_papers（已验证 get_author_papers 正确：2024:2024 返回了 87 篇论文作者中恰好 7 篇日期在范围内的论文）。

• 确切日期未知的论文仍会保留 year，而 publicationDate 会返回 null。未知日期按其年份的 1 月 1 日处理，因此按边界年份筛选的结果只是近似值。
• venues 与 Semantic Scholar 的会场字符串匹配。常见缩写可正确解析（已验证：NeurIPS 和 ICML 均返回了结果），且 venue 字段返回规范名称（Neural Information Processing Systems）。最稳妥的做法是：先运行一次不带筛选条件的关键词搜索，查看 venue 的值，然后用这些完整字符串进行筛选。
• 与任何会场都不匹配的字符串会返回 0 行，而非错误，因此结果为空可能是会场字符串有误，而不是缺少论文。

响应结构（已验证）

paper (get_paper, get_paper_batch, search_*, get_author_papers, get_citations):
  paperId, externalIds{DOI?, ArXiv?, PubMed?, PubMedCentral?, CorpusId?, MAG?, DBLP?},
  title, venue, year, publicationDate?, abstract?, tldr{model, text},
  authors[{authorId, name}], journal{pages?}, citationCount?, influentialCitationCount?,
  isOpenAccess, openAccessPdf, fieldsOfStudy[]

citing row (get_citations):   {"citingPaper": {paperId, title, year, ...}}
author (search_authors_by_name):  authorId, name, affiliations[] (often empty), homepage?,
  paperCount?, citationCount?, hIndex?, externalIds{DBLP: ["Name"]}
snippet (snippet_search):  {"data":[{"score":0.77,
  "paper":{"corpusId":..., "title":..., "authors":["Name", ...], "openAccessInfo":{...}},
  "snippet":{"text":"..."}}], "retrievalVersion":...}

• 论文工具中的 authors 是对象列表，但片段中的 authors 是纯字符串列表。
• 片段中的论文包含 corpusId，而非 paperId；可用 CorpusId:<corpusId> 查找论文。
• search_paper_by_title 会添加 matchScore；分数越高越好，可用于判断是否接受模糊标题匹配。

工作流模式

模式 1：主题发现

1. search_papers_by_relevance(keyword, publication_date_range="<current_year-5>:", fields="title,year,authors,venue,tldr,url,citationCount,influentialCitationCount", limit=20)，根据今天的日期计算起始年份（在 2026 年，传入 2021:）；如果用户希望查找更早的研究，则移除或放宽筛选条件
2. 按 citationCount 和时效性排序，展示排名靠前的 N 项
3. 提供后续选项：对最具影响力的结果调用 get_citations，或使用 snippet_search 查找具体论据

模式 2：种子论文扩展

1. 调用 get_paper(DOI|ARXIV|...) 验证种子论文
2. 调用 get_citations(paperId, fields="title,year,venue,citationCount", limit=50) 扩展前向引用
3. 可选：使用种子论文标题中的词语调用 search_papers_by_relevance，横向发现相关论文
4. 展示前按 paperId 去重

模式 3：作者深入研究

1. search_authors_by_name(name, fields="name,affiliations,paperCount,citationCount,hIndex,externalIds", limit=10)。必须请求这些字段：默认只返回 name 和 authorId。若有 externalIds.ORCID，先据此区分身份，再参考 paperCount、citationCount 和 hIndex；即使请求了 affiliations，该字段也经常为空（已验证），只能作为最后的判别依据。同一人的姓名变体可能对应不同 ID（F. Theis 和 Fabian J. Theis 是不同的作者档案），因此应检查排名靠前的几个候选项，而不只是第一行。
2. 调用 get_author_papers(authorId, limit=50, paper_fields="title,year,authors,venue,tldr,url,citationCount", publication_date_range=?)，获取范围受限的第一页结果，按最新时间优先
3. 在客户端按主题关键词或日期筛选

模式 4：证据检索

1. 调用 snippet_search(claim_query, limit=5)，查找提出或支持某项论断的段落
2. 如需以特定论文为依据，传入 paper_ids="<id1>,<id2>,…"（≤100），这样片段只会来自这些论文
3. 对每个结果调用 get_paper("CorpusId:<corpusId>") 获取完整元数据

输出与交互规则

• 始终报告使用了哪个工具以及返回的行数（没有工具会提供总数）。
• 最多将 10 条结果以表格形式展示（标题、年份、会场、已获取的引用数），然后补充最相关几项的详细信息。
• 如果用户使用中文，则用中文展示摘要；标题保留原文。
• 展示结果后，提供以下选项：详情 / 调整筛选 / 引用 / 片段 / 导出 / 完成。

处理 Asta 响应

情况	应对方式
结果中出现 isError: true	失败会作为普通结果返回，其中包含 isError: true 和纯文本消息，而 HTTP 状态码仍为 200，因此切勿信任传输状态码。例如：错误的密钥会返回 Error executing tool get_paper: HTTP status 403 Forbidden.；未知工具名称会返回 Unknown tool: get_references
content 数组为空	这可能是合法的空结果（例如，没有匹配项的 venues 字符串），不代表出错
流中只有 : ping 心跳消息，没有结果	在观察到的零结果查询中，服务可能会一直保持 SSE 流打开，直到客户端超时，而不是返回 content: []。设置客户端超时时间，重试一次，然后才报告“无结果”；不要默默挂起
abstract 为空	并非所有语料库论文都有全文。请改用 snippet_search，或展示标题 + tldr
作者消歧结果不确定	提前请求排名字段（模式 3）；优先使用 externalIds.ORCID，然后是 paperCount / citationCount / hIndex，仅在平局时参考 affiliations
按日期筛选的结果	publicationDate 可能为 null，而 year 始终存在；未知日期会按 1 月 1 日处理，因此对边界年份的筛选结果只是近似值
429 Too Many Requests	请退避，并使用 get_paper_batch 批量查询，而不要依次调用 get_paper
需要 DOI / PubMed ID / arXiv ID	在 fields 中添加 externalIds；如果没有 DOI，则回退使用 ArXiv

关键规则

• 优先批量处理意图，避免来回查询。 如果问题需要两次互相独立的查询，应在同一轮中并行发起 MCP 调用，而不是依次执行。
• 绝不要猜测 ID。 模糊的标题应先通过 search_paper_by_title 查询；ID 始终应带有前缀。
• 读取内容前先检查 isError，因为传输层状态码始终为 200。
• 遵守速率限制。 API 密钥可提高限额，但并非不受限制；不要将引用图扩展到超出用户所问的范围。
• 不要编造字段。 如果 Asta 返回的 abstract、venue 或 citationCount 为 null，应如实说明，不要自行编造。