literaf/dsh-ai4scholar

dsh-ai4scholar

适用于 DeepSeek Harness 的 AI4Scholar

npm CI dsh-plugin license

面向 DeepSeek Harness（dsh）的学术文献工具，以 38 个原生 agent 工具的形式提供——与 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）不带额度行。

截图

| Settings → Plugins card | /ai4scholar balance card |
|---|---|
| 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. Settings → Plugins → AI4Scholar — 粘贴你的 AI4Scholar API 密钥（ai4scholar.net）并点击 Save。该卡片会将其存储在 dsh 凭据存储中（$DSH_HOME/.credentials.yaml，权限模式 0600，与 Models 页面保存提供商密钥的位置相同），立即测试它（✓ Key works · 89,419 credits available），并在下一次工具调用时生效——无需重启。Refresh 链接可随时重新检查；浏览器永远不会看到密钥（检查通过插件的主机路由 GET /ai4scholar/balance 进行）。

选择一个工作区文件夹，然后开始提问。升级：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.

配置

该 bundle 挂载一行（id: ai4scholar），并带有以下默认值。可从你的 profile 的 cordis.patch.yml 中覆盖（patch 会替换整个 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 密钥通过 ctx.credentials 按调用解析，因此存储或轮换密钥会在下一次工具调用时生效，无需重启。当凭据服务不存在时（自定义组合），插件会回退到 process.env[apiKeyEnv]。

设置卡片始终编辑 AI4SCHOLAR_API_KEY（浏览器端不会收到行配置）；覆盖 apiKeyEnv 的部署则通过环境变量或凭据文件来管理该引用。会话额度统计是进程本地的（它会随 dsh 重启）；余额本身始终来自 API。

它如何融入 dsh

- 一个包中包含两部分：Node 部分注册工具；浏览器部分（exports["./client"]，由 dsh.client 声明）通过 settings.plugin.item 插槽贡献设置卡片，并且仅通过凭据传输 API 与 Host 通信——密钥字面量绝不会出现在响应中，也绝不会到达模型。
- 工具通过 defineTool 注册在 ctx.tools 上：类型化、经 schema 校验的参数；每次调用产生一个规范的 JSON 值（{ source, query, total, papers[], truncated, nextOffset? }）；为模型提供 Markdown 渲染；以及为 Web UI 提供 web 结果卡片（结构化来源）。
- 一个 tool:ai4scholar 系统提示词段落告诉模型何时使用哪个平台，以及按 DOI/链接引用。
- 一切都是 effect：卸载插件（或编辑其配置，这会触发 HMR）会撤回所有工具和提示词段落。
- 除工具结果外，不添加任何模型可见的输入，因此会话可从日志中完全重放。

开发

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:/dsh-ai4scholar 也可以：prepare 脚本会从源码构建 lib/，pnpm 会要求你通过 profile 的 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。

许可证
麻省理工学院