学术文献检索 literaf/dsh-ai4scholar

dsh-ai4scholar

AI4Scholar for DeepSeek Harness

学术文献工具，面向 DeepSeek Harness（dsh），以 38 个原生智能体工具的形式提供，覆盖范围与 OpenClaw、Codex、Hermes 上的 AI4Scholar 插件一致。由 ai4scholar.net 提供支持。

| 系列 | 工具 | 费用 |
| 一次全查 | search_papers — 一次查询同时检索 Semantic Scholar + PubMed（可选 arXiv、Google Scholar），按 DOI / arXiv id / PMID / 标题去重，多平台命中的结果排在最前 | 按平台计费 |
| Semantic Scholar（2 亿+ 论文，覆盖全部学科） | search_semantic、search_semantic_bulk、search_semantic_snippets（全文摘录）、search_semantic_paper_match（标题 → 论文）、get_semantic_paper_detail、get_semantic_paper_batch、get_semantic_citations、get_semantic_references、get_semantic_paper_authors、search_semantic_authors、get_semantic_author_detail、get_semantic_author_batch、get_semantic_author_papers、get_semantic_recommendations、get_semantic_recommendations_for_paper、download_semantic、read_semantic_paper | 点数 |
| PubMed（生物医学与生命科学） | search_pubmed、get_pubmed_paper_detail、get_pubmed_paper_batch、get_pubmed_citations、get_pubmed_related | 点数 |
| Google Scholar（覆盖最广，带被引次数） | search_google_scholar | 点数 |
| arXiv | search_arxiv、download_arxiv、read_arxiv_paper | 免费 |
| bioRxiv / medRxiv | search_biorxiv、search_medrxiv、download_biorxiv、download_medrxiv、read_biorxiv_paper、read_medrxiv_paper | 免费 |
| 任意 DOI | download_by_doi、read_by_doi（任意来源的开放获取论文；付费墙出版商需在机构网络内） | 免费 |
| 写作与配图 | auto_cite（插入真实引用 + 参考文献列表 + BibTeX）、sci_draw（生成 / 编辑 / 美化 / 组合 / 评审 / SVG / 矢量化科学配图） | 点数 |
| 账户 | get_ai4scholar_credits，以及 /ai4scholar 斜杠命令 | 免费 |
每个论文列表工具都返回同一种规范化记录结构——标题、作者、年份、发表 venue、引用数、DOI/PMID/arXiv id、URL、开放获取 PDF、摘要——这样模型（以及 Code Mode 程序）就能跨平台串联调用，不用为每个平台写特例。结果在 dsh Web UI 里渲染成引用卡片；全文工具按切片返回 PDF 文本（offset / max_chars），一篇 40 页的论文不会淹没上下文。

额度可见。 聊天里每张计费工具卡片都在标题带上费用（Semantic Scholar: protein folding · 10 credits · 4,990 left），模型看到的结果末尾是 AI4Scholar credits — this call: 10 · this session: 40 · remaining: 4,960（来自 API 的 X-Credits- 响应头），并且要求模型在计费回合结束时附一行额度说明；/ai4scholar 渲染余额卡片（可用额度、明细、会员、密钥状态、会话花费），get_ai4scholar_credits 把同样的数字交给模型。免费平台（arXiv、bioRxiv/medRxiv、DOI）不带额度行。

截图

| API 密钥卡片（旧版 Settings 视图） | /ai4scholar 余额卡片 |
| AI4Scholar settings card | balance card |

安装

快速开始（macOS / Linux；Windows PowerShell 同理）：

0. Prerequisites: Node.js ≥ 22.19 (or ≥ 24) and pnpm (dsh manages plugins with pnpm)
node -v
npm i -g pnpm # skip if you already have it

1. DeepSeek Harness
npm i -g @deepseek-ai/dsh
dsh --version

2. This plugin (into the web profile; use --profile headless for the CLI runner)
dsh plugin --profile web add dsh-ai4scholar

3. Start
dsh web # prints http://127.0.0.1:3080

然后在浏览器里做一次：

1. Settings → Models —— 粘贴你的 DeepSeek API 密钥（platform.deepseek.com）。
2. Plugins → Installed → dsh-ai4scholar（或 Settings → AI4Scholar）—— 粘贴你的 AI4Scholar API 密钥（ai4scholar.net），按 Save。卡片把密钥存进 dsh 凭据存储（$DSH_HOME/.credentials.yaml，权限 0600，和 Models 页面保存服务商密钥是同一处），立刻测试（✓ Key works · 89,419 credits available），下次工具调用即生效——不用重启。Refresh 链接随时重新检查；浏览器始终看不到密钥（检查走插件的主机路由 GET /ai4scholar/balance）。
在当前的 DSH Desktop 上，点击侧边栏 Plugins → Installed 列表里的 dsh-ai4scholar：详情页上直接就能看到密钥表单。Settings → Built-in plugins 是宿主清单，所以这里不再包含该表单。旧版 Harness 仍提供原来的 Settings → Plugins → AI4Scholar 卡片。已有密钥继续可用；所有入口都使用同一个凭据引用。

选一个工作区文件夹，直接提问。升级：dsh plugin --profile web add dsh-ai4scholar@latest，然后重启 dsh web。

更习惯用文件或 CI？插件解析凭据引用 AI4SCHOLAR_API_KEY，所以下面几种方式也都可以（优先级从高到低）：在启动 dsh 的 shell 里 export AI4SCHOLAR_API_KEY=… · 在 $DSH_HOME/.credentials.yaml 里写一行 · 在项目或 $DSH_HOME/.env 里写一行。卡片会显示密钥来自哪一层，环境变量提供密钥时卡片变为只读。无头模式没有设置页，所以在那里用这几种方式之一。

发布后会立即推送到 npmmirror，所以国内默认源也能在一分钟内拿到新版本。

不启动也能验证层级：dsh --profile web --dump-config 会打印 # == dsh-ai4scholar 段。

然后直接提问：

Find recent papers on CRISPR base editing for sickle cell disease and compare their delivery methods.

Search PubMed for GLP-1 receptor agonists and cardiovascular outcomes since 2022, sorted by date.

Which paper is "Attention Is All You Need"? Give me its DOI and citation count.

配置

插件包挂载一行（id: ai4scholar），默认值如下。从你配置档的 cordis.patch.yml 覆盖（补丁会替换整个 config，所以要保留的键都要重新写一遍）：

- id: ai4scholar
config:
apiKeyEnv: AI4SCHOLAR_API_KEY # credential reference; the key itself never lives in config
baseUrl: https://ai4scholar.net
tool families
semanticScholar: true
pubmed: true
googleScholar: true
arxiv: true
biorxiv: true # bioRxiv + medRxiv
doi: true
fullText: true # the read_ tools (PDF download + text extraction)
autoCite: true
sciDraw: true
creditsTool: true # get_ai4scholar_credits
command: true # the /ai4scholar slash command
balanceRoute: true # GET /ai4scholar/balance for the settings card's key test
showCredits: true # credit line on billed results
promptGuidance: true # short system-prompt section describing the tools
promptOrder: 150
sizes
defaultMaxResults: 10 # when the model omits max_results
maxResultsCap: 50 # hard upper bound per call
abstractMaxChars: 600 # abstract characters shown per paper; 0 hides abstracts
readMaxChars: 60000 # characters per full-text slice
timeouts / retry
requestTimeoutMs: 30000 # per HTTP attempt
pdfTimeoutMs: 120000 # per PDF download
generationTimeoutMs: 300000 # auto_cite / sci_draw
maxRetries: 3 # attempts on 429 / network errors
retryBackoffMs: 2000 # doubles per attempt
toolTimeoutMs: 180000 # cooperative per-call budget enforced by dsh

API key 在每次调用时通过 ctx.credentials 解析，所以存进去或轮换之后，下一次工具调用就会生效，不用重启。凭据服务不存在时（自定义组合的场景），插件回退到 process.env[apiKeyEnv]。

设置卡片始终编辑 AI4SCHOLAR_API_KEY（浏览器那一半拿不到行配置）；如果部署时覆盖了 apiKeyEnv，就要通过环境变量或凭据文件来管理这个引用。会话内的额度统计只在进程内有效（dsh 重启就清零）；余额本身始终来自 API。

与 dsh 的配合方式

- 一个包里装两半：Node 那一半注册工具；浏览器那一半（exports["./client"]，由 dsh.client 声明）通过原生 plugins.bundle.config / plugins.row.config 插槽和 settings.section（老版本宿主上还有 settings.plugin.item）提供设置卡片，并且只通过凭据 wire API 与 Host 通信——key 明文永远不会出现在响应里，也永远不会到达模型。
- 工具用 defineTool 注册到 ctx.tools：参数有类型、经过 schema 校验；每次调用返回规范的 JSON 值（{ source, query, total, papers[], truncated, nextOffset? }）；给模型的是 Markdown 渲染结果；给 Web UI 的是 web 结果卡片（结构化来源）。
- 一段 tool:ai4scholar 系统提示词告诉模型什么时候用哪个平台、按 DOI/链接引用。
- 一切都是 effect：卸载插件（或修改配置触发 HMR）会撤掉所有工具和这段提示词。
- 除工具结果之外，不添加任何模型可见的输入，所以会话完全可以从日志重放。

开发 sh
pnpm install
pnpm test # builds lib/ (Node half via tsc, browser bundle via tsdown), then runs:

unit tests, a smoke test against the real ToolRuntime, and a jsdom test that

loads the built client bundle under the dsh module-host contract and drives the card

pnpm typecheck

try it in a dsh profile without publishing:

dsh plugin --profile web add /absolute/path/to/dsh-ai4scholar

dsh plugin add github:<you>/dsh-ai4scholar 也能用：prepare 脚本会从源码构建 lib/，pnpm 会要求你在配置档的 pnpm-workspace.yaml 里通过 allowBuilds 允许一次。

说明
- download_by_doi / read_by_doi 通过 doi.org 解析，并套用已知出版商 PDF 的地址规律（Elsevier、Springer/Nature、Wiley、T&F、MDPI、IEEE、ACM、ACS、RSC、PLOS、Frontiers、bioRxiv/medRxiv、arXiv）。付费文章只有在 dsh 运行于具备机构访问权限的网络时才能下载；若被拒绝，会给出落地页地址，方便你手动获取。
- 全文提取在进程内使用 pdf-parse（pdf.js）；扫描件或纯图片 PDF 会返回明确错误，而不是空文本。
- 同一套工具也提供给 OpenClaw、Codex 和 Hermes。

License

MIT