学术研究核验 Morn1nStar/dsh-academic-research-plugin

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