dsh-academic-research-plugin

DeepSeek Harness 学术研究插件：把"文献核验、论据核验表、复现记录、投稿前准入门槛"落成 磁盘上的可审计状态，而不是模型在对话里的口头承诺。

模型在对话里说什么不算，claims.jsonl 里是什么才算。

为什么是插件而不是 skill 集合

• 工具（tool）：检索、DOI 核验、跑命令、写证据档案——这些动作有真实副作用，论断必须经过它们。
• 状态（state）：passport.json / claims.jsonl / runs.jsonl 跨会话、可审计。
• 准入门槛（gate）：工具层面拒绝"未核实引用进入稿件"，不靠提示词自觉。
• 可分发：bundle 一行安装，随插件附带 3 个方法论 skill（ar-reading / ar-reproduction / ar-response）。

安装

本插件是零运行时依赖的 Host bundle，安装不需要访问 npm registry：

# 在 DSH 插件管理器中：Bundles → 安装本地 bundle，指向本目录
# 或对 profile 使用 dsh 命令行插件管理器（以本地环境实际命令为准）
dsh plugin --profile <你的profile> add <本目录绝对路径>

安装后确认：

dsh --profile <你的profile> --dump-config   # 能看到 academic-research 行

配置（cordis.patch.yml 中该行的 config）

键	默认	说明
workspace	./.research	证据档案目录，相对会话工作目录或绝对路径
network	false	false 时 paper_search/ref_verify/claim_check 直接拒绝
allowShell	false	false 时 repro_run 只做 dry-run，绝不执行命令
maxHits	20	单次检索候选上限（1..100），控制上下文
sources	[arxiv, crossref]	检索源路由顺序（可含 semanticscholar）
requireAnchors	true	无 locator 的结论不得成为 verified
gateBlockOn	[unverified, contradicted]	准入门槛的拦截条件

覆盖配置时重述整行（id + name + 完整 config），Loader 不做深合并。

快速上手

装好后不需要记命令——直接对 Agent 说自然语言即可。完整示例（从一篇论文到 "可以投稿"）见 docs/usage-example.md，包含每个场景 你说什么、Agent 调哪个工具、你看到什么输出、被拒绝时怎么修复。

工具清单（11 个）

工具	作用	副作用
paper_search	多源检索论文候选（arxiv/crossref/semanticscholar）	无
paper_ingest	论文入库 lit/index.json（同一 paperId 只入库一次；元数据不全标 metadata_only）	写 lit/
ref_verify	对照源核验 DOI/arXiv ID，返回 VERIFIED / NOT_FOUND / MISMATCH	无
note_read	四问题精读笔记写入 lit/<paperId>.md（强制 anchors）	写 lit/
claim_add	声明入账（源必须已入库 + 带 locator；初始 unverified）	追加 claims.jsonl
claim_check	重新核验声明：VERIFIED→verified，MISMATCH→contradicted（终态）	更新 claims.jsonl
repro_plan	生成复现计划 + 确定性风险清单	写 repro/plan.md
repro_run	受控执行命令并记 runs.jsonl；allowShell=false 时 dry-run	执行命令、写 runs.jsonl
gate_check	论据核验表的准入门槛：unverified/contradicted 即 blocked，追加研究档案的 gates	追加研究档案
review_panel	只读稿件 + 证据档案的确定性投前评审（拦截项硬编码）	写 review/round-N.md
review_response	审稿意见 → tracker（AUTHOR_INPUT_NEEDED）+ 回复信骨架	写 review/

准入门槛的强制规则（违反即报错，无法绕过）

• status ∈ {unverified, verified, contradicted}；
• metadata_only 源永远不能支撑 claim、不能成为 verified；
• contradicted 终态保留，不得删除或改写为 unverified；
• verified 必须带 checkedAt 与 checker（工具名@版本）；
• 取消的运行记 cancelled: true，绝不记 exitCode: 0。

目录产物

<workspace>/.research/
  passport.json      schema=ar.passport/1；stage 只能前进（回退需 gate_check 带 reason）
  claims.jsonl       论据核验表（append-only，原子写）
  runs.jsonl         复现运行记录（append-only）
  lit/index.json  lit/<paperId>.md
  repro/plan.md  repro/delta.md  repro/code/
  review/round-N.md  review/tracker.md  review/letter.md

.research/ 建议进 git；repro/code/ 与大数据产物走 .gitignore，只保留 runs.jsonl 里的哈希与指标。

安全模型（务必阅读）

• 默认双关：network=false、allowShell=false。开启即授权：network 只允许 arxiv / crossref / semanticscholar 三个域；shell 开启后每次 repro_run 都会 记录命令全文与 gitSha。
• 密钥：只从环境读，runs.jsonl 只记环境变量名（envKeys），不记值。
• 宿主同进程：插件在 DSH 宿主进程内运行，等同本地代码权限。安装前请审阅 源码（本仓库 index.js + lib/ 约 1500 行、零依赖），并 pin 版本。

开发与测试

npm test                  # 57 个用例：证据档案的强制规则、准入门槛、评审、检索解析、命令执行
npm run check             # test + npm pack --dry-run

CI：GitHub Actions（ubuntu / windows × node 22.19 / 24）跑 npm test 与 npm pack --dry-run，见 .github/workflows/ci.yml。

设计文档与 API 核对结论见 docs/api-baseline.md； 与上游方法论仓库的对照见 NOTICE。

上游致谢

方法论概念借鉴自 academic-research-skills（Material Passport、claim 支撑等级）、 nature-skills（图表契约、回复信编号）、scientific-agent-skills（多源路由）、 paper-reading-skill（四问题框架）与 phd-skills（复现检查项）。只借鉴概念， 不重分发任何上游文本/代码，许可与出处见 NOTICE。

License

MIT