Paper Chaser MCP

Paper Chaser MCP

发布状态： 仓库、CLI、Docker 镜像元数据和公开的 MCP 身份现已统一为 paper-chaser-mcp。GHCR 镜像和 GitHub Release 资源是主要的公开分发渠道；PyPI 仍有意暂缓开放，直到账户恢复和可信发布者设置完成。

一个用于学术研究的 MCP 服务——可搜索论文、追踪引用、查找作者、修复失效参考文献、探索物种档案并检索监管文本，所有功能都由一个 AI 助手可直接调用的 FastMCP 服务提供。

数据源： Semantic Scholar · arXiv · OpenAlex · CORE · SerpApi Google Scholar（选择启用，付费）· Crossref · Unpaywall · ECOS · FederalRegister.gov · GovInfo

---

目录

• 它能做什么？
• 引导式与专家配置
• 快速开始
• 工具快速选择指南
• 核心工作流
• Agent 响应约定
• 延后导出设计
• 迁移说明
• 安装
• 配置
• 工具
• 资源与提示词
• Microsoft 打包资源
• 使用 MCP Inspector 进行测试
• 开发
• 指南
• 许可证
• 链接

---

它能做什么？

Paper Chaser MCP 现在以引导式使用为先：默认公开界面旨在降低误用风险，并明确说明信任状态。

• 默认研究入口：research 在一条按信任等级划分的路径中处理发现、已知条目查找、引文修复和法规路由，并采用由服务端控制、质量优先的引导式使用策略。
• 有据可依的后续研究：follow_up_research 基于一个已保存的 searchSessionId 作答；如果省略此参数，服务端只会在选项唯一时推断会话。若已保存会话的元数据足够，后续研究还可以将混合来源分类为相关证据、较弱的背景信息和偏题线索。
• 决策元数据：引导式响应会显示 executionProvenance；后续研究或来源检查流程存在歧义时，会返回结构化的 sessionResolution / sourceResolution 内容，而不是含糊的错误。
• 以参考文献为先的查找：resolve_reference 处理 DOI/arXiv/URL、引文片段和法规类参考文献；精确的 DOI/arXiv/论文 URL 输入会作为精确锚点解析，不会转而进行模糊修复。对于仅标题匹配存在歧义或元数据冲突的情况，现在可能返回 multiple_candidates 或 needs_disambiguation；请将其视为候选锚点，而非可直接用于引文的解析结果。
• 精简的顶层答案：引导式 research 会先提供简短的建议优先 summary，同时在下方保留结构化证据、线索和来源信息字段。
• 来源可审计性：inspect_source 会提供一个 sourceId，以及来源信息、信任状态、弱匹配理由和考虑质量的直接读取后续步骤；只有存在一个兼容的已保存会话时，才可省略 searchSessionId。
• 运行时真实状态：get_runtime_status 会显示当前配置文件/传输方式和提供方状态警告，无需低级诊断。configuredSmartProvider 是已配置的智能组合；activeSmartProvider 是最近一次实际执行路径。冷启动快照会发出明确的临时警告，而不会在首次智能调用完成前声称确定采用了回退方案；顶层提供方集合现在会分别显示 disabledProviderSet、suppressedProviderSet、degradedProviderSet 和 quotaLimitedProviderSet，而不再将它们合并。
• 仍可使用专家级深度功能：面向原始数据、智能功能和特定提供方的工具仍然存在，可在专家配置文件下用于运维工作流。

引导式与专家配置文件

使用 PAPER_CHASER_TOOL_PROFILE 选择要公布的工具界面：

配置文件	默认值	公开界面	目标用户
guided	是	research、follow_up_research、resolve_reference、inspect_source、get_runtime_status	上下文较少的用户和 Agent
expert	否	引导式工具，以及面向原始数据/特定提供方的工具系列（search_papers*、智能图谱工具、法规直连工具、完整诊断工具），具体取决于已启用的功能和禁用工具的可见性	高级用户和运维工作流

实用的默认配置：PAPER_CHASER_TOOL_PROFILE=guided，并设置 PAPER_CHASER_HIDE_DISABLED_TOOLS=true。

快速开始

如需最快捷的本地使用方式，请从源代码安装，并以 stdio 模式将服务添加到 MCP 客户端：

pip install -e .

{
  "mcpServers": {
    "paper-chaser": {
      "command": "python",
      "args": ["-m", "paper_chaser_mcp"],
      "env": {
        "PAPER_CHASER_TOOL_PROFILE": "guided",
        "PAPER_CHASER_HIDE_DISABLED_TOOLS": "true",
        "PAPER_CHASER_ENABLE_SEMANTIC_SCHOLAR": "true",
        "PAPER_CHASER_ENABLE_ARXIV": "true",
        "PAPER_CHASER_ENABLE_CORE": "false"
      }
    }
  }
}

然后在 MCP 客户端中使用以下任一提示词开始：

• 研究面向编码 Agent 的检索增强生成，并且只返回可信的发现。
• 使用我上次的 searchSessionId，回答一个有依据的后续问题。
• 解析此引文片段：Vaswani et al. 2017 Attention Is All You Need.
• 研究加利福尼亚神鹫在 50 CFR 17.95 下的法规沿革。

如果需要用于 shell 运行或 Docker Compose 的本地环境模板，请将 .env.example 复制为 .env，并仅填写你会使用的提供方。

---

快速工具选择指南

目标	从这里开始
探索、文献综述或法规沿革	research
基于已保存结果进行有据可依的后续研究	follow_up_research
清理引用、DOI、arXiv、URL 或参考文献	resolve_reference
在依赖某个返回来源前对其进行审核	inspect_source
说明环境／运行时差异	get_runtime_status
需要直接控制提供方或使用专用分页	切换到专家配置文件，并使用原始／提供方专用工具

核心工作流

1. 先进行引导式研究

research(query="retrieval-augmented generation for coding agents", limit=5)
→ inspect resultStatus, answerability, summary, evidence, leads, routingSummary
→ if resultStatus=needs_disambiguation with clarification.reason=underspecified_reference_fragment:
  tighten the anchor or pivot to resolve_reference instead of forcing retrieval
→ if resultStatus=abstained and sources are suppressed: inspect suppressedSourceSummaries before rerunning or escalating
→ save searchSessionId for follow-up or source inspection

2. 提出一个有依据的后续问题

follow_up_research(searchSessionId="...", question="What evaluation tradeoffs show up here?")
→ inspect answerStatus
→ if answered: use answer + evidence (compact default: sources are identified by selectedEvidenceIds)
→ if abstained/insufficient_evidence: use nextActions, suppressedSourceSummaries, and inspect_source
→ mixed saved sessions can still answer relevance-triage questions such as which items are on-topic vs off-target
→ uniquely anchored recommendation asks can also return a safe start-here answer plus topRecommendation
→ if you omit searchSessionId and multiple saved sessions exist: provide it explicitly
→ for full source records pass responseMode="standard"; for diagnostics responseMode="debug"
→ for selection asks ("where should I start?", "most recent?"), read topRecommendation

3. 尽可能在广泛搜索前解析参考文献

resolve_reference(reference="10.1038/nrn3241")
→ exact DOI/arXiv/paper URL should resolve directly when supported
resolve_reference(reference="Rockstrom et al planetary boundaries 2009 Nature 461 472")
→ inspect status and bestMatch/alternatives
→ only treat bestMatch as citation-ready when status=resolved
→ if status=multiple_candidates or needs_disambiguation: pick a candidate or add a stronger author/year/venue clue before citing it
→ if resolved: run research with the resolved anchor

4. 引用前检查某个来源

inspect_source(searchSessionId="...", evidenceId="...")
→ inspect verificationStatus, topicalRelevance, whyClassifiedAsWeakMatch, confidenceSignals, canonicalUrl, directReadRecommendations
→ if searchSessionId is omitted and inference is ambiguous, rerun with an explicit saved session id

5. 明确处理弃答和澄清

• 如果 research.resultStatus 为 abstained 或 needs_disambiguation，请勿编造 综合结论。请用具体线索缩小范围：DOI、准确标题、物种名称、 机构、年份或刊物。
• 当 research 返回 needs_disambiguation，且 clarification.reason=underspecified_reference_fragment 时，服务会 有意在对模糊的引用／参考文献片段进行推测性检索前停止。请补充线索 或切换到 resolve_reference。
• 如果 follow_up_research.answerStatus 为 abstained 或 insufficient_evidence，请将其视为安全信号。使用 inspect_source 并缩小范围后重新运行 research。

6. 需要精细控制时的专家备用方案

PAPER_CHASER_TOOL_PROFILE=expert
→ search_papers_smart / ask_result_set / map_research_landscape / expand_research_graph
→ search_papers / search_papers_bulk and provider-specific families
→ search_federal_register / get_federal_register_document / get_cfr_text for direct regulatory primary-source control

对于专家智能工具，deep 是默认的质量优先模式。只有在降低延迟足以证明缩小检索范围合理时，才使用 balanced；fast 则仅用于冒烟测试或调试。

引导式 research 不再接受公开的 latencyProfile 参数。该策略由服务 负责，目前采用以深度为基础、质量优先的路径；如果首轮结果过弱，则进行一次有界的审核升级。

Agent 响应约定

以下是主要的引导式约定：

字段或模式	出现位置	操作说明
resultStatus	research	succeeded、partial、needs_disambiguation、abstained、failed
answerability	research、follow_up_research	grounded、limited、insufficient
evidence	research、follow_up_research	用于检查和引用的规范化、有依据的来源记录
leads	research、follow_up_research、专家智能工具	查看较弱、经过筛选或偏离主题的线索，但不要将其提升为有依据的证据
evidenceGaps	research、follow_up_research	将其视为当前回答的明确限制，而非未明说的保留意见
routingSummary	research、follow_up_research	检查意图、锚点、提供方计划、监管子类型或实体卡片（如有），以及结果不完整的原因
coverageSummary	research、follow_up_research	在依赖综合结果之前，检查提供方覆盖范围和完整性
executionProvenance	引导式工具	检查产生结果所用的服务器策略、延迟默认值和回退路径
confidenceSignals	research、follow_up_research、inspect_source	检查证据质量、综合模式和来源范围标签等附加信任线索，但不要用它们替代 answerability
evidenceUsePlan	follow_up_research	对综合式后续查询，在信任回答之前，检查回答子类型、直接相关的证据 ID、不受支持的部分以及检索充分性
sessionResolution	follow_up_research、inspect_source	当会话是推断得出、经过修复、缺失或含糊不清时使用
sourceResolution	inspect_source	当请求的来源 ID 已匹配、无法解析，或需要使用可用 ID 重试时使用
abstentionDetails	证据较弱时的引导式工具	将其视为弃答或证据不足时可采取行动的原因和恢复提示
nextActions	引导式工具	将其视为服务器在证据较弱时优先推荐的恢复路径
clarification	research	仅在提供了范围明确的澄清请求时询问用户
answerStatus	follow_up_research	answered、abstained、insufficient_evidence。要得到有依据的 answered，必须有切题且经过验证的来源、可供问答读取的文本、非确定性提供方，以及中等或更高置信度；否则应预期结果为 insufficient_evidence。
topRecommendation	follow_up_research（比较／选择类提问）	结构化推荐项，包含 sourceId、recommendationReason、comparativeAxis（例如 beginner_friendly、recency、authority）。对于有唯一锚点的“我应该从哪里开始？”类提问，即使更广泛的综合结果仍会受限，也可以安全地通过此路径回答。
responseMode	follow_up_research 输入	compact（默认，隐藏完整来源和旧版字段）、standard、debug。
includeLegacyFields	follow_up_research 输入	设为 true，即可在紧凑模式下恢复旧版 verifiedFindings／unverifiedLeads。
fullTextUrlFound / bodyTextEmbedded / qaReadableText	inspect_source	区分 URL 发现、内嵌正文文本，以及问答综合实际可用的文本。fullTextObserved 仍可能作为兼容别名出现，但这些拆分后的字段才是稳定契约。
evidenceId	evidence[*]	传递给 inspect_source，用于检查单个来源的出处信息
runtimeSummary	get_runtime_status 和专家诊断	确认生效的配置、智能提供方状态和警告

对于广泛的机构指导信息发现，引导式路由会继续采用监管类一手来源路径。偏离主题的权威文件仍可能作为 leads 出现，但不应取代更相关、与查询锚定的指导文件或政策文件，成为顶层推荐。 对于源代码级审计，请将 whyClassifiedAsWeakMatch 和 confidenceSignals.sourceScopeLabel / confidenceSignals.sourceScopeReason 视为 解释为何将权威记录保留为弱匹配或离题线索的主要依据。

在 llm-guidance 第 4 阶段中，又加入了更多信任度和依据支撑信号。引导式响应可以公开 confidenceSignals.evidenceQualityProfile、confidenceSignals.synthesisMode、confidenceSignals.evidenceProfileDetail、confidenceSignals.synthesisPath、confidenceSignals.trustRevisionNarrative，以及 trustSummary.authoritativeButWeak 分类，用于收纳权威但与主题关联度不高的一手来源记录。searchStrategy 可能会提供 regulatoryIntent、intentFamily、用于物种和监管依据的 subjectCard，以及描述缺失主体链证据的 subjectChainGaps。inspect_source 会为每条直接读取建议配对一个 directReadRecommendationDetails 条目，结构为 {trustLevel, whyRecommended, cautions}，以便 Agent 按质量确定直接读取的优先级。有关如何解读并使用这些信号，请参阅 Paper Chaser Golden Paths 和 Guided And Smart Robustness Notes。

延后导出设计

本阶段有意延后会话导出。计划中的未来形式为 export_search_session(searchSessionId, format)，其中 format 为 ris、 bibtex 或 csv，并使用 guided-v2 来源/引用架构，以便实现导出时无需再次重写公开契约。

迁移说明

如果你之前直接使用 smart/raw-first 接口：

1. 使用 research，而不是 search_papers_smart 或 search_papers。
2. 对于默认的依据支撑型问答，使用 follow_up_research，而不是 ask_result_set。
3. 将 resolve_reference 用作已知条目恢复的第一步，而不是 resolve_citation/search_papers_match。
4. 如需通过显式操作员工作流使用专家工具，请设置 PAPER_CHASER_TOOL_PROFILE=expert。
5. 不要向引导式 research 发送 latencyProfile；该策略现在由服务端在内部管理。
6. 对于专家智能工具，deep 现在是默认选项。若希望采用延迟更低的回退方案，请显式选择 balanced。
7. 预期引导式封装会提供 executionProvenance、sessionResolution、 sourceResolution 和 abstentionDetails。

有关详细的重大变更说明，请参阅 Guided Reset Migration Note。

---

安装

当前的分发选项：

• 源码检出：目前最直接的本地方式，尤其适用于开发和 MCP 桌面客户端。
• GHCR 镜像：面向使用 Docker 的 MCP 客户端的主要容器分发渠道。
• GitHub Release 资源：v* 标签会构建 wheel 和 sdist 构件，并将它们附加到草稿 GitHub Release 供审核。
• PyPI：目前暂不开放；在重新启用该渠道前，请使用源码安装或 GitHub Release 构件。

本地源码安装：

pip install -e .

AI 增强层的可选扩展：

• 仅安装共享的智能层运行时，包括确定性模式：pip install -e ".[ai]"
• OpenAI 或 Azure OpenAI 提供方支持：pip install -e ".[ai,openai]"
• Hugging Face 聊天路由器支持：pip install -e ".[ai,huggingface]"
• NVIDIA 提供方支持：pip install -e ".[ai,nvidia]"
• Anthropic 提供方支持：pip install -e ".[ai,anthropic]"
• Google 提供方支持：pip install -e ".[ai,google]"
• Mistral 提供方支持：pip install -e ".[ai,mistral]"
• Azure AI Foundry 评估发布辅助工具：pip install -e ".[eval-foundry]"
• Hugging Face 评估发布辅助工具：pip install -e ".[eval-huggingface]"
• 安装两种评估发布辅助工具：pip install -e ".[eval]"
• 如果要使用可选的 FAISS 后端，请将 ,ai-faiss 添加到上述任一命令中。

Azure OpenAI 使用相同的 openai 扩展。 Hugging Face 使用专用的 huggingface 扩展，该扩展会安装兼容 OpenAI 的 SDK 和 LangChain OpenAI 适配器；本仓库将其说明为仅支持聊天的智能提供方路径，并禁用嵌入功能。 评估发布辅助工具有意使用独立的扩展：eval-foundry 用于 Azure AI Foundry 数据集上传支持，eval-huggingface 用于 Hugging Face 数据集仓库或存储桶发布支持。这些扩展与智能提供方聊天运行时相互独立。

配置

完整的本地环境变量约定见 .env.example。该文件列出了 docker-compose.yaml 支持的公开本地配置项。Azure 专属标识符、密钥和 Bicep 参数单独记录在 docs/azure-deployment.md 中。

桌面 MCP 客户端

除非确实需要 HTTP，否则桌面 MCP 客户端请使用 stdio 传输。 服务器定义的 JSON 示例请参见上文的快速入门。

• Claude Desktop 配置路径：
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json
• Cursor：在 Cursor 设置中添加相同的 MCP 服务定义。

搜索代理与功能标志

引导模式从 research 开始。以下代理和特定提供方的控制项 适用于专家路径。

区域	默认值	主要变量	备注
工具配置	guided	PAPER_CHASER_TOOL_PROFILE	guided 提供 5 个低上下文工具；expert 提供更广泛的原始／提供方专属工具集，具体取决于启用的功能以及 PAPER_CHASER_HIDE_DISABLED_TOOLS
引导策略	优先保证质量	PAPER_CHASER_GUIDED_RESEARCH_LATENCY_PROFILE、PAPER_CHASER_GUIDED_FOLLOW_UP_LATENCY_PROFILE、PAPER_CHASER_GUIDED_ALLOW_PAID_PROVIDERS、PAPER_CHASER_GUIDED_ESCALATION_ENABLED、PAPER_CHASER_GUIDED_ESCALATION_MAX_PASSES、PAPER_CHASER_GUIDED_ESCALATION_ALLOW_PAID_PROVIDERS	引导模式下的 research／follow_up_research 使用这些由服务端管理的默认值，而不遵循客户端的 latencyProfile 设置
搜索代理	semantic_scholar,arxiv,core,serpapi_google_scholar	PAPER_CHASER_ENABLE_SEMANTIC_SCHOLAR、PAPER_CHASER_ENABLE_ARXIV、PAPER_CHASER_ENABLE_CORE、PAPER_CHASER_ENABLE_SERPAPI、PAPER_CHASER_PROVIDER_ORDER	SerpApi 需选择启用且为付费服务；CORE 默认关闭
OpenAlex 工具系列	已启用	PAPER_CHASER_ENABLE_OPENALEX、OPENALEX_API_KEY、OPENALEX_MAILTO	独立工具系列，不是默认的代理跳转目标
ScholarAPI 工具系列	已禁用	PAPER_CHASER_ENABLE_SCHOLARAPI、SCHOLARAPI_API_KEY	独立的发现、监控、全文和 PDF 工具系列；也可通过 preferredProvider 或 providerOrder 选择作为代理目标。现在，来源于 ScholarAPI 的论文结果会包含单独的 contentAccess 区块，其中提供访问／全文元数据。
信息补全	已启用	PAPER_CHASER_ENABLE_CROSSREF、CROSSREF_MAILTO、CROSSREF_TIMEOUT_SECONDS、PAPER_CHASER_ENABLE_UNPAYWALL、UNPAYWALL_EMAIL、UNPAYWALL_TIMEOUT_SECONDS、PAPER_CHASER_ENABLE_OPENALEX	适用于已经有论文或 DOI 的情况
ECOS	已启用	PAPER_CHASER_ENABLE_ECOS、ECOS_BASE_URL、ECOS_TIMEOUT_SECONDS、文档超时与大小变量、TLS 变量	物种和文档工作流
Federal Register／GovInfo	已启用	PAPER_CHASER_ENABLE_FEDERAL_REGISTER、PAPER_CHASER_ENABLE_GOVINFO_CFR、GOVINFO_API_KEY、GovInfo 超时与大小变量	Federal Register 搜索无需密钥；权威 CFR 检索使用 GovInfo
智能层	已禁用	OPENAI_API_KEY、OPENROUTER_API_KEY、OPENROUTER_BASE_URL、OPENROUTER_HTTP_REFERER、OPENROUTER_TITLE、HUGGINGFACE_API_KEY、HUGGINGFACE_BASE_URL、NVIDIA_API_KEY、NVIDIA_NIM_BASE_URL、AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_VERSION、ANTHROPIC_API_KEY、GOOGLE_API_KEY、MISTRAL_API_KEY、PAPER_CHASER_ENABLE_AGENTIC、模型和索引变量	仅作增量扩展；支持 openai、azure-openai、anthropic、nvidia、google、mistral、huggingface、openrouter 和 deterministic。OpenAI 附带已检入的模型默认值；如果 Anthropic、NVIDIA、Google 和 Mistral 的 OpenAI 默认值未被修改，它们会自动切换为各自提供方的默认值；Azure OpenAI 则可使用部署名称覆盖这两个角色。Hugging Face 和 OpenRouter 被文档说明为通过 HUGGINGFACE_BASE_URL 和 OPENROUTER_BASE_URL 配置的 OpenAI 兼容聊天路由器；在此代码库中，两者都仅支持聊天，不会启用嵌入。OpenRouter 会保留显式指定的规划器和合成模型名称，例如带提供方前缀的模型 ID。对于可自托管的 NIM，NVIDIA_NIM_BASE_URL 是可选项；访问托管的 NVIDIA API Catalog 时，请将其留空。嵌入默认保持禁用，因为它在此代码库中一直不可靠；改进嵌入不属于当前版本的范围。启用 ScholarAPI 后，智能发现也可以通过它进行路由，并使用 providerBudget.maxScholarApiCalls 对其调用次数设限。
隐藏已禁用的工具	引导模式默认 true，专家模式默认 false	PAPER_CHASER_HIDE_DISABLED_TOOLS	引导模式下保持开启，以减少选中无法使用的工具；专家模式通常关闭此项，以便操作人员查看

智能层模型默认值

启用 PAPER_CHASER_ENABLE_AGENTIC=true 且未刻意覆盖模型变量时，以下是生效的规划器／合成默认值。

PAPER_CHASER_AGENTIC_PROVIDER	默认规划器	默认合成模型	解析规则
openai	gpt-5.4-mini	gpt-5.4	直接使用仓库中已提交的 PAPER_CHASER_PLANNER_MODEL 和 PAPER_CHASER_SYNTHESIS_MODEL 默认值
azure-openai	gpt-5.4-mini	gpt-5.4	使用相同的模型变量，除非设置了 AZURE_OPENAI_PLANNER_DEPLOYMENT 或 AZURE_OPENAI_SYNTHESIS_DEPLOYMENT；若已设置，则优先使用这些部署名称
anthropic	claude-haiku-4-5	claude-sonnet-4-6	仅当规划器／合成模型仍设置为仓库中已提交的 OpenAI 默认值时，运行时才会切换为这些提供商的默认值
nvidia	nvidia/nemotron-3-nano-30b-a3b	nvidia/nemotron-3-super-120b-a12b	仅当规划器／合成模型仍设置为仓库中已提交的 OpenAI 默认值时，运行时才会切换为这些提供商的默认值
google	gemini-2.5-flash	gemini-2.5-pro	仅当规划器／合成模型仍设置为仓库中已提交的 OpenAI 默认值时，运行时才会切换为这些提供商的默认值
mistral	mistral-medium-latest	mistral-large-latest	仅当规划器／合成模型仍设置为仓库中已提交的 OpenAI 默认值时，运行时才会切换为这些提供商的默认值
huggingface	moonshotai/Kimi-K2.5	moonshotai/Kimi-K2.5	仅当规划器／合成模型仍设置为仓库中已提交的 OpenAI 默认值时，运行时才会切换为这些提供商的默认值；请求会发送到 HUGGINGFACE_BASE_URL，且路径仍仅支持聊天
openrouter	无	无	运行时保留显式设置的规划器／合成模型值，并将请求发送到 OPENROUTER_BASE_URL；首轮路径仍仅支持聊天
deterministic	不适用	不适用	不会调用外部大模型；模型选择元数据会报告为 deterministic

PAPER_CHASER_EMBEDDING_MODEL 默认值为 text-embedding-3-large，但在设置 PAPER_CHASER_DISABLE_EMBEDDINGS=false 之前，嵌入功能会保持关闭。默认关闭是因为嵌入功能在此代码库中一直不可靠，而改进该功能不在当前引导式策略版本的范围内。在当前支持的提供商中，只有明确支持嵌入功能的提供商才会使用嵌入。这意味着，尽管 Hugging Face 路径使用兼容 OpenAI 的路由器，文档所述路径仍仅支持聊天。

建议的基础配置：对于常规学术工作流，启用 Semantic Scholar、OpenAlex、Crossref 和 Unpaywall；需要明确检索全文或 PDF 时，启用 ScholarAPI；SerpApi 是付费的召回补全路径，建议仅在需要时启用。

最重要的 Broker 规则：

• 默认搜索回退顺序为 Semantic Scholar、arXiv、CORE，最后是启用时的 SerpApi。
• preferredProvider、providerOrder 和 PAPER_CHASER_PROVIDER_ORDER 接受 core、semantic_scholar、arxiv、scholarapi 和 serpapi 或 serpapi_google_scholar。
• 仅适用于 Semantic Scholar 的筛选条件，例如 publicationDateOrYear、fieldsOfStudy、publicationTypes、openAccessPdf 和 minCitationCount，可能会使 Broker 跳过不兼容的提供商。
• Broker 响应会提供 brokerMetadata.providerUsed、brokerMetadata.attemptedProviders 和 brokerMetadata.recommendedPaginationTool，以便 Agent 采取正确的后续步骤。

传输和部署模式

模式	默认值	主要变量	适用场景
桌面 stdio	stdio	无需设置	Claude Desktop、Cursor、本地 MCP 子进程启动
直接运行 HTTP	选择启用	PAPER_CHASER_TRANSPORT、PAPER_CHASER_HTTP_HOST、PAPER_CHASER_HTTP_PORT、PAPER_CHASER_HTTP_PATH	无需部署包装器的本地集成测试
HTTP 包装器	选择启用	PAPER_CHASER_HTTP_AUTH_TOKEN、PAPER_CHASER_HTTP_AUTH_HEADER、PAPER_CHASER_ALLOWED_ORIGINS	在本地模拟托管 HTTP 部署
Docker Compose 发布设置	默认仅限 localhost	PAPER_CHASER_PUBLISHED_HOST、PAPER_CHASER_PUBLISHED_PORT	仅控制主机端 HTTP 端口映射

主要区别：

• PAPER_CHASER_HTTP_HOST 和 PAPER_CHASER_HTTP_PORT 控制直接通过 shell 运行和托管部署。Docker Compose 将容器绑定地址固定为 0.0.0.0:8080，并使用 PAPER_CHASER_PUBLISHED_HOST / PAPER_CHASER_PUBLISHED_PORT 设置主机端映射。
• paper-chaser-mcp deployment-http 运行 Compose 和 Azure 使用的部署包装器。它会在 MCP 端点前添加 /healthz，以及可选的身份验证和 Origin 校验。

直接在本地运行 HTTP 的示例：

PAPER_CHASER_TRANSPORT=streamable-http \
PAPER_CHASER_HTTP_HOST=127.0.0.1 \
PAPER_CHASER_HTTP_PORT=8000 \
python -m paper_chaser_mcp

如需了解完整的 Azure 部署方案，包括 bootstrap 和 full 工作流模式，请阅读 docs/azure-deployment.md、docs/azure-architecture.md 和 docs/azure-security-model.md。

Docker MCP 包（stdio）

对于将服务作为子进程启动的本地 MCP 客户端，请使用 stdio 模式的镜像。若要在本地迭代且不发布，请构建并运行 paper-chaser-mcp:local。若要使用可复用的公共包，请使用已发布的 GHCR 标签：

docker run --rm -i ghcr.io/joshuasundance-swca/paper-chaser-mcp:latest

对于本地构建的镜像：

docker run --rm -i paper-chaser-mcp:local

基于 Docker 的 MCP 客户端条目通常如下所示：

{
  "mcpServers": {
    "paper-chaser": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/joshuasundance-swca/paper-chaser-mcp:latest"]
    }
  }
}

此模式非常适合本地桌面 MCP 使用，因为主机会启动服务进程并管理其生命周期。

仓库还提供了 server.json，以确保公共 OCI 镜像与 MCP 包元数据在注册表和发现工具中保持一致。面向 GHCR 的公共包工作流由标签驱动：v* 标签会将可复用的容器镜像发布到 ghcr.io/joshuasundance-swca/paper-chaser-mcp。MCP Registry 的发布有意拆分为单独的手动工作流，因此发布到 GHCR 不会受注册表可用性的影响。

Python 包的发布准备工作单独配置在 .github/workflows/publish-pypi.yml 中：拉取请求会构建发行包并运行 twine check，而实际发布任务会保持休眠状态，直到仓库变量 ENABLE_PYPI_PUBLISHING 被设为 true。在恢复 PyPI/TestPyPI 访问权限并注册受信任的发布者后，可通过手动触发发布到 TestPyPI，也可通过 v* 标签发布到 PyPI。

GitHub Release 资源由 .github/workflows/publish-github-release.yml 单独处理：v* 标签或手动触发会构建 wheel 和 sdist 构件，使用 twine check 验证，生成 SHA256SUMS，并将其上传到 GitHub Release 草稿页面，以便在更大范围公开发布前审查 Python 构件。

Docker Compose（HTTP 包装器模式）

用于本地 HTTP 测试、MCP Inspector 或桥接式集成时，此仓库提供了带有仅限 localhost 默认设置的 docker-compose.yaml。Compose 会显式启动 deployment-http 子命令，因此 HTTP 包装器行为不依赖镜像的默认传输方式。

Compose 会将容器绑定主机和内部端口固定为 0.0.0.0:8080，并将应用默认传输方式覆盖为 streamable-http，因此浏览器工具和桥接式客户端无需额外的 shell 标志即可通过 http://127.0.0.1:8000/mcp 连接。Compose 文件提供面向用户的可配置项：传输方式、MCP 路径、提供商密钥、提供商开关、身份验证以及发布的主机端口映射。

1. 将 .env.example 复制为 .env。
2. 填入你想使用的任何可选提供商密钥。
3. 启动服务：

docker compose -f docker-compose.yaml up --build

服务默认监听 http://127.0.0.1:8000，提供用于探测的 /healthz，并通过 http://127.0.0.1:8000/mcp 提供 MCP。

curl http://127.0.0.1:8000/healthz

如果设置了 PAPER_CHASER_HTTP_AUTH_TOKEN，并保留 PAPER_CHASER_HTTP_AUTH_HEADER=authorization，部署包装器会要求在 /mcp 上提供 Authorization: Bearer <token>。仓库中附带的 Azure 脚手架会将标头名称覆盖为 x-backend-auth，并让 API Management 为仅限后端的流量注入该标头。发布的主机默认是 127.0.0.1；只有在你明确希望容器可从本机以外访问时，才更改 PAPER_CHASER_PUBLISHED_HOST。

如果提供商密钥字段留空，本地客户端仍可使用。服务器会在支持的情况下回退到免费／默认提供商路径，而 SerpApi 默认保持禁用状态。

Docker Compose Inspector 辅助服务

无需在本地安装 Node，即可通过浏览器进行调试；请使用专用的 Inspector 堆栈：

docker compose -f compose.inspector.yaml up --build

此堆栈将 Inspector 与 MCP 服务镜像分开，并且仅将 UI 和代理绑定到 localhost：

• Inspector UI：http://127.0.0.1:6274
• Inspector 代理：http://127.0.0.1:6277

Inspector 代理身份验证默认保持启用。使用 docker compose -f compose.inspector.yaml logs mcp-inspector 查看 Inspector 启动时输出的会话令牌。

在 Inspector 中，使用 Streamable HTTP 连接并设置：

• URL：http://paper-chaser-mcp:8080/mcp
• 传输方式：streamable-http

compose.inspector.yaml 接受 IMAGE 覆盖项，因此无需编辑文件即可测试指定标签：

IMAGE=ghcr.io/joshuasundance-swca/paper-chaser-mcp:latest docker compose -f compose.inspector.yaml up

工具

完整的工具参考。请参阅上方的快速工具选择指南，了解从何处开始。

默认引导工具

工具	描述
research	默认的信任评级入口，用于发现、找回已知项目、修复引文和监管路由。
follow_up_research	基于已保存的 searchSessionId 开展有依据的后续研究；必要时会返回明确的弃答／证据不足状态。
resolve_reference	将类似引文的输入（引文、DOI、arXiv、URL、标题片段、监管引用）解析为最安全的后续锚点。
inspect_source	检查引导结果集中的一个 sourceId，了解其来源、信任状态以及后续直接读取情况。
get_runtime_status	引导式运行时摘要，包含当前配置、传输方式、智能提供商状态和警告。

专家级智能研究层

这些工具是用于深度编排和提供方控制的专家级配置路径。

工具	描述
search_papers_smart	概念级发现，支持查询扩展、多提供方融合、重排序、可复用的 searchSessionId，以及证据优先的专家级契约（resultStatus、answerability、routingSummary、evidence、leads、evidenceGaps、structuredSources、coverageSummary、failureSummary）。旧版信任字段仍可作为兼容视图使用。在 auto 模式下，它还可以将明显的监管类问题路由至一手来源时间线。latencyProfile 默认设为 deep，以进行质量最高的专家级工作；若要降低延迟，可使用 balanced，而 fast 仅用于冒烟测试。高级客户端仍可选用 providerBudget。
ask_result_set	基于已保存的 searchSessionId 进行有依据的问答、主张核查和比较。
map_research_landscape	将已保存的结果集归纳为主题、空白、分歧和后续搜索建议。
expand_research_graph	将论文锚点或已保存的会话扩展为引文／参考文献／作者关系图，并对前沿节点进行排序。

论文搜索

工具	描述
search_papers	经由代理执行的单页搜索（默认顺序：Semantic Scholar → arXiv → CORE → SerpApi）。请查看 brokerMetadata.nextStepHint；ScholarAPI 也可作为明确选择的代理目标。
search_papers_bulk	使用布尔查询语法进行分页批量搜索（Semantic Scholar），每次调用最多搜索 1,000 篇论文。
search_papers_semantic_scholar	仅搜索 Semantic Scholar 的单页搜索，支持完整筛选。
search_papers_arxiv	仅搜索 arXiv 的单页搜索。
search_papers_core	仅搜索 CORE 的单页搜索。
search_papers_serpapi	使用 SerpApi 搜索 Google Scholar 的单页搜索。需要 SerpApi。
search_papers_scholarapi	使用 ScholarAPI 进行相关性排序的单页搜索。需要 ScholarAPI。
search_papers_openalex	仅搜索 OpenAlex 的单页搜索。
search_papers_openalex_bulk	使用游标分页搜索 OpenAlex。
list_papers_scholarapi	使用游标分页的 ScholarAPI 监控／列表流程，按 indexed_at 排序。
search_papers_openalex_by_entity	将 OpenAlex 作品搜索范围限定为一个来源、机构或主题实体 ID。

已知条目查找与引文修复

工具	描述
resolve_citation	用于修复不完整或格式错误参考文献的工作流。遇到监管类参考文献时会弃答。
search_papers_match	通过跨提供方确认，查找标题不规范或不完整的已知条目。
get_paper_details	通过 DOI、arXiv ID、Semantic Scholar ID 或 URL 查找。可选使用 includeEnrichment。
get_paper_details_openalex	通过 W-id、URL 或 DOI 查找 OpenAlex 作品，并重建摘要。
paper_autocomplete	论文标题输入联想。
paper_autocomplete_openalex	OpenAlex 作品输入联想，用于消歧已知条目。

引文、参考文献和作者

工具	描述
get_paper_citations	引用指定论文的论文（Semantic Scholar）。使用游标分页。
get_paper_citations_openalex	OpenAlex 引用该论文的扩展结果。使用游标分页。
get_paper_references	指定论文的参考文献（Semantic Scholar）。使用游标分页。
get_paper_references_openalex	OpenAlex 向后扩展参考文献。使用游标分页。
get_paper_authors	指定论文的作者（Semantic Scholar）。
search_authors	按姓名搜索作者（Semantic Scholar）。
search_authors_openalex	按姓名搜索 OpenAlex 作者。
get_author_info	根据 Semantic Scholar 作者 ID 获取作者档案。
get_author_info_openalex	根据 A-id 或 URL 获取 OpenAlex 作者档案。
get_author_papers	Semantic Scholar 作者发表的论文。使用游标分页。
get_author_papers_openalex	OpenAlex 作者发表的论文，支持 year 筛选和游标分页。
batch_get_papers	一次调用获取最多 500 个论文 ID 的详情。
batch_get_authors	一次调用获取最多 1,000 个作者 ID 的详情。
get_paper_recommendations	根据单篇种子论文获取相似论文（GET）。
get_paper_recommendations_post	根据正向／负向种子论文集合获取相似论文（POST）。

论文信息补充与开放获取发现

工具	描述
enrich_paper	综合 Crossref、Unpaywall 和 OpenAlex，为一篇已知论文或 DOI 补充信息。仅提供查询内容而没有锚点的调用会放弃查询，而不会解析论文。
get_paper_metadata_crossref	为已知论文或 DOI 显式补充 Crossref 信息。
get_paper_open_access_unpaywall	根据 DOI 查询 Unpaywall 开放获取状态、PDF URL 和许可信息。需要 UNPAYWALL_EMAIL。

ScholarAPI 文本和 PDF 检索

工具	描述
get_paper_text_scholarapi	根据 ScholarAPI 论文 ID 获取一篇 ScholarAPI 纯文本全文文档。
get_paper_texts_scholarapi	批量检索最多 100 个 ScholarAPI 论文 ID 的全文。保留顺序和 null 占位符。
get_paper_pdf_scholarapi	获取一篇 ScholarAPI PDF，并返回结构化元数据及 Base64 编码的内容。

OpenAlex 实体

工具	描述
search_entities_openalex	搜索 OpenAlex 来源、机构或主题实体，用于枢纽工作流。

ECOS 物种档案

工具	描述
search_species_ecos	根据通用名或学名搜索 ECOS 物种。
get_species_profile_ecos	获取完整的 ECOS 物种档案：名录、文档和保护计划。
list_species_documents_ecos	将单个档案整理为排序后的文档清单。
get_document_text_ecos	获取 ECOS 文档（PDF/HTML/文本）并转换为 Markdown。

Federal Register 和 CFR

工具	描述
search_federal_register	无需密钥即可搜索 Federal Register 中的通知、规则和拟议规则。
get_federal_register_document	根据编号、FR 引用或 GovInfo 链接获取一份 Federal Register 文档。
get_cfr_text	获取 GovInfo 中的 CFR 部分或条文文本。需要 GOVINFO_API_KEY。

SerpApi 附加功能 (可选启用，付费)

工具	描述
search_papers_serpapi_cited_by	通过 SerpApi 扩展获取 Google Scholar 引用该论文的结果。
search_papers_serpapi_versions	通过 SerpApi 集群 ID 扩展获取 Google Scholar 的所有版本。
get_author_profile_serpapi	通过 SerpApi 获取 Google Scholar 作者档案。
get_author_articles_serpapi	通过 SerpApi 分页获取 Google Scholar 作者文章。
get_paper_citation_formats	从 Google Scholar 导出引文（MLA、APA、BibTeX 等）。需要 SerpApi。
get_serpapi_account_status	SerpApi 配额和吞吐量快照。

恢复与诊断

工具	描述
search_snippets	标题或关键词搜索效果不佳时，用于引文或短语恢复。最后手段。
get_provider_diagnostics	实时提供方健康状况、限流状态、重试情况和回退原因。

ECOS 使用流程

加州燕鸥是一个具有代表性的端到端 ECOS 流程：

1. 调用 search_species_ecos，并设置 query="California least tern"，获取 ECOS 物种 ID 8104。
2. 调用 get_species_profile_ecos，并设置 species_id="8104"，查看物种档案、按组整理的恢复文件、生物学意见和保护计划链接。
3. 调用 list_species_documents_ecos，并设置 species_id="8104"，例如设置 documentKinds=["recovery_plan","five_year_review","biological_opinion"]，以展平文档清单。
4. 对 2025 年五年审查 PDF 或修订后的恢复计划 PDF 调用 get_document_text_ecos，将源文档转换为 Markdown，供下游分析使用。

资源和提示词

• 资源：guide://paper-chaser/agent-workflows — 精简的入门指南，介绍如何选择工具并安全地处理分页
• 资源：paper://{paper_id} — 已解析论文的精简 Markdown 和结构化载荷
• 资源：author://{author_id} — 已解析作者的精简 Markdown 和结构化载荷
• 资源：search://{searchSessionId} — 从工具输出中呈现的已保存结果集
• 资源：trail://paper/{paper_id}?direction=citations|references — 精简的引文／参考文献追踪资源
• 提示词：plan_paper_chaser_search — 可复用的规划提示词，默认优先使用引导模式，并明确提供专家回退方案
• 提示词：plan_smart_paper_chaser_search — 用于有意采用专家智能模式工作流的规划提示词
• 提示词：triage_literature — 用于信任感知主题映射和后续步骤选择的引导式文献筛查工作流
• 提示词：plan_citation_chase — 引文扩展规划提示词
• 提示词：refine_query — 用于宽泛或含噪搜索的有限查询优化提示词

主要读取工具的响应还会提供：

• agentHints — 推荐的后续工具、重试指导和警告
• clarification — 当服务无法自行安全消除歧义时提供的有限澄清回退方案
• resourceUris — 兼容客户端可直接打开的后续资源
• searchSessionId — 可复用的结果集句柄，用于智能后续工作流以及缓存的扩展／搜索轨迹

Microsoft 打包资产

此仓库保留了统一的 MCP 服务接口，并为面向 Microsoft 的客户端提供附加打包资产：

• mcp-tools.core.json — 引导式低上下文默认接口（research、follow_up_research、resolve_reference、inspect_source、get_runtime_status）
• mcp-tools.full.json — 面向有意使用 PAPER_CHASER_TOOL_PROFILE=expert 运行的环境提供的引导式 + 专家版软件包
• microsoft-plugin.sample.json — 声明式 Agent／面向插件的元数据示例

这些资产面向 Streamable HTTP 和精简工具输出。它们提供的是打包指南，而非独立的运行时构建版本。

使用 MCP Inspector 进行测试

推荐的本地方式是 Docker sidecar 工作流：

docker compose -f compose.inspector.yaml up --build

这样可以将 Inspector 排除在生产 MCP 镜像之外，并且只将 Inspector 端口绑定到 localhost。

如果你更愿意在主机上安装 Inspector，也可以运行：

npm install -g @modelcontextprotocol/inspector
mcp-inspector python -m paper_chaser_mcp

开发

安装包含开发额外依赖项的软件包：

pip install -e ".[dev]"

如果还想在同一环境中使用额外的 AI 层以及所有托管提供商集成：

pip install -e ".[all]"

all 会展开为 ai,openai,huggingface,nvidia,anthropic,google,mistral,dev，因此 Azure OpenAI 仍使用相同的 openai 额外依赖项，而 Hugging Face 仍是单独的、仅支持聊天的 OpenAI 兼容安装选项。

如果还需要在本地使用可选的 FAISS 后端：

pip install -e ".[all,ai-faiss]"

项目依赖项在 pyproject.toml 中声明；无需维护单独的运行时 requirements.txt 并确保其同步。

运行本地测试套件：

pytest

安装并运行已配置的 pre-commit 钩子：

pre-commit install
pre-commit run --all-files

pre-commit install 会同时安装快速的 pre-commit 钩子和 .pre-commit-config.yaml 中配置的、开销较大的 pre-push 检查。手动阶段钩子不会自动运行；需要执行完整的本地检查时，请运行 pre-commit run --hook-stage manual --all-files（或上面的直接命令）。

开发额外依赖项包括 pytest、pytest-asyncio、pytest-cov、 ruff、mypy、bandit、build、bumpver、pip-audit、 shellcheck-py、types-defusedxml 和 pre-commit。GitHub 依赖项自动化通过 Dependabot 同时配置了 Python 包和 GitHub Actions，并由依赖项审查工作流检查拉取请求。

为了在本地检查 GitHub 工作流文件并与 CI 保持一致，请确保运行 pre-commit 前 PATH 中有 shellcheck。在当前仓库虚拟环境中安装 shellcheck-py 可满足许多环境的要求；请使用 shellcheck --version 进行验证，而不要默认认为工作流中的内嵌 bash 脚本已在本地接受 lint 检查。

版本升级

版本元数据由 bumpver 管理，配置位于 pyproject.toml。仓库中跟踪的 软件包版本采用纯 PEP 440 格式，例如 0.2.0；而发布标签仍采用 v0.2.0 的形式，以匹配现有的发布工作流触发条件。

为了安全地在 PR 分支上进行审查，可试运行补丁版本升级，而不更改 git 状态：

bumpver update --patch --dry --no-fetch --no-commit --no-tag-commit --no-push

对于实际的发布准备分支，请更新仓库中跟踪的版本约定，但提交、打标签和推送仍由维护者明确控制：

bumpver update --patch --no-commit --no-tag-commit --no-push

完整本地验证

仓库中与 CI 等效的本地检查范围不止 pytest。如需进行全面的本地检查，请运行：

python -m pip check
pre-commit run --all-files
python -m pytest --cov=paper_chaser_mcp --cov-report=term-missing --cov-fail-under=87
python -m mypy --config-file pyproject.toml
python -m ruff check .
python -m bandit -c pyproject.toml -r paper_chaser_mcp
python -m build
python -m pip_audit . --progress-spinner off

如果希望通过 pre-commit 调用开销较大的钩子检查， pre-commit run --hook-stage manual --all-files 会运行 .pre-commit-config.yaml 中定义的手动阶段 pip check、覆盖率、构建和 pip-audit 钩子。

修改 Azure IaC、部署文档、Dockerfile、APIM 策略或 Azure 部署工作流时，还请运行：

python scripts/validate_psrule_azure.py
python scripts/validate_deployment.py --skip-docker

如需与 Deploy Azure 工作流的完整部署验证流程保持一致，请运行：

python scripts/validate_deployment.py --require-az --require-docker --image-tag paper-chaser-mcp:ci-validate

GitHub Agentic Workflow 冒烟测试

仓库包含一个 Agentic 回归工作流，位于 .github/workflows/test-paper-chaser.md（源文件）和 .github/workflows/test-paper-chaser.lock.yml（编译后的锁定文件）。该工作流会在 GitHub Actions 中针对本地 MCP 服务运行 Agent，测试主要黄金路径、评估 Agent 的用户体验质量，并可为后续工作创建可执行的议题。

编辑 Markdown 工作流后，请重新编译并验证：

gh aw compile test-paper-chaser --dir .github/workflows
pre-commit run --all-files

同时提交 .md 源文件和 .lock.yml 输出文件，然后在 GitHub Actions 界面中运行 Test Paper Chaser MCP。

工作流输入： mode（smoke、comprehensive 或 feature_probe）、 tool_profile（默认为 guided；如果有意测试原始／提供商特定的覆盖范围，则设为 expert），以及可选的 focus_prompt。通过 workflow_dispatch 输入项选择这些值。

必需的机密： 必须设置 COPILOT_GITHUB_TOKEN。 GH_AW_MODEL_AGENT_COPILOT（Actions 变量，可选）用于控制 Agent 模型。CORE_API_KEY 和 SEMANTIC_SCHOLAR_API_KEY 为可选项。

仓库还包含 .github/workflows/agentic-assign.yml，会自动将 GitHub Copilot 分配给带有 agentic 和 needs-copilot 标签的议题（如果同时带有 needs-human、blocked 或 no-agent 标签，则不会分配）。 Validate 工作流会在 CI 中重新编译 test-paper-chaser.md，如果锁定文件已过期则会失败，因此拉取请求不会悄然出现不同步的情况。 当 GitHub Actions 在工作流应运行的分支上检测到已提交的 .lock.yml 时，该工作流即已“部署”。

关于公共仓库的安全状况，以及建议的漏洞私下报告渠道，请参阅 SECURITY.md。

模块拆分后，维护者可从 docs/agent-handoff.md 开始了解项目情况。公共 MCP 接口位于 paper_chaser_mcp/server.py，实现则位于 paper_chaser_mcp/dispatch.py、paper_chaser_mcp/search.py、paper_chaser_mcp/tools.py、paper_chaser_mcp/runtime.py、paper_chaser_mcp/models/，以及 paper_chaser_mcp/clients/ 下的提供商子包中。

指南

• GitHub Copilot 使用说明 - 面向 GitHub Copilot 和 GitHub 云端编码 Agent 的仓库专属指南，包含工作流默认设置和持久化规划要求。
• Agent 交接指南 - 当前仓库状态、验证命令，以及后续 Agent 推荐开展的工作。
• 大模型选择指南 - 规划与综合职责、当前智能层模型默认值、围绕 generate_eval_topics.py 和 run_eval_autopilot.py 的评估引导漏斗，以及在本仓库中选择大模型的标准。
• 大模型评估计划 - 按角色划分的评估策略、数据集生成计划、评估器技术栈，以及本仓库严格测量大模型性能的分阶段落地计划。
• 大模型评估数据集架构 - 按角色划分的评估种子集和未来基准扩展所用的 JSONL 架构、字段规则、治理约定和存储布局。
• 大模型评估平台策略 - 如何结合仓库本地评估与 Azure AI Foundry、Hugging Face 和实时追踪主动学习循环，同时保持可移植性。
• 大模型评估追踪推广 - 将经过审核的实时追踪推广为持久化评估数据行的工作流和辅助工具格式。

可以通过 PAPER_CHASER_ENABLE_EVAL_TRACE_CAPTURE=true 和 PAPER_CHASER_EVAL_TRACE_PATH=... 启用可选的实时评估候选项采集，然后使用 scripts/build_eval_review_queue.py 将其转换为审核队列，再进行推广。

可通过 scripts/export_eval_assets.py 导出供下游评估和训练系统使用的可移植数据，包括适用于 Foundry 的评估 JSONL、Hugging Face 数据集 JSONL，以及由审核通过的追踪生成的聊天格式训练 JSONL。 可通过 scripts/upload_foundry_eval_dataset.py 和 scripts/upload_hf_eval_assets.py 使用服务专属的发布助手，将审核通过的导出内容推送到 Foundry 项目数据集、Hugging Face 数据集仓库或 Hugging Face 存储桶。

专家批量整理任务现在可以在原始报告、捕获的事件和审核队列之外，同时生成 batch-summary.json 和 batch-ledger.csv，让离线漂移与吞吐量检查无需依赖重放完整的 JSONL 工件。

对于仓库本地的评估引导，当前的顶层工作流如下：

• scripts/generate_eval_topics.py，用于由规划器主导主题生成、分类体系分配、排序、精简、平衡和场景生成
• scripts/run_eval_autopilot.py，用于基于配置文件的生成、不可变运行包、留出集检查和受保护的工作流交接
• scripts/run_eval_workflow.py，用于专家批量捕获、审核或晋升、数据集拆分以及实时提供方矩阵评估

仓库中现有的自动驾驶示例配置文件现在包含平衡科学类默认配置，以及 single-seed-exploratory-review、single-seed-exploratory-safe 和 single-seed-diagnostic-force 等窄范围运行配置文件。这些窄范围运行配置文件可以启用单种子多样化，让单种子运行要求规划器生成更多偏审核、法规和方法论的变体，而不是仅依赖较宽松的工作流阈值。 有关当前 Foundry 和 Hugging Face 集成情况，包括何时适合将 hf-mount 用作共享捕获接收端，请参阅 docs/llm-evaluation-integrations.md。

• 发布与发布计划 - 当前针对 GHCR、GitHub Release 资源、手动发布到 MCP Registry 以及休眠的 PyPI 的发布操作手册。
• 引导式重置迁移说明 - 默认界面的破坏性变更、引导式与专家模式的划分，以及客户端迁移清单。
• Paper Chaser 黄金路径 - 主要用户角色、工作流默认设置、成功信号，以及未来以工作流为导向的后续工作。
• Azure 部署 - 私有 Azure 部署的模式、必需的密钥和变量，以及验证路径。
• Azure 架构 - Azure 脚手架的信任边界、运行时拓扑和凭据隔离。
• Azure 安全模型 - Azure 部署中的凭据类别、Key Vault 用法，以及后端身份验证隔离。
• 提供方升级计划 - 以可靠性为先的提供方升级所涉及的提供方角色、延迟特征、诊断、基准测试语料库和验收门槛。
• OpenRouter 提供方指南 - 添加和运行 OpenRouter 的实施指南。OpenRouter 是仅支持聊天的智能层提供方，其中包括当前的 Trinity 启动计划。
• ScholarAPI 集成指南 - 添加 ScholarAPI 的规划指南。它将作为明确的发现、监控、全文和 PDF 提供方，同时不削弱当前面向图谱的提供方契约。
• OpenAlex API 指南 - 针对代码库明确的 OpenAlex MCP 界面的实施指南，包括身份验证、基于额度的限制、分页、/works 语义和规范化注意事项。
• Semantic Scholar API 指南 - 使用异步速率限制、重试和基于 .env 的本地开发，得体且有效地使用 Semantic Scholar API 的实用指南。
• SerpApi Google Scholar 指南 - 关于 SerpApi 功能、权衡以及成本与合规注意事项的深入研究笔记；代码库提供了其中记录的明确引用次数、版本、作者、账户和引文格式工作流。
• FastMCP 迁移计划 - FastMCP 迁移及兼容界面的历史架构依据。

许可证

MIT

链接

协议和运行时

• Model Context Protocol
• FastMCP
• SerpApi 定价

学术提供方

• Semantic Scholar API
• arXiv API 用户手册
• CORE API v3 文档
• OpenAlex API 文档
• ScholarAPI 文档
• SerpApi Google Scholar API
• Crossref REST API
• Unpaywall API

监管与物种来源

• ECOS
• FederalRegister.gov API
• GovInfo API