DSH 科研插件（DSH Research Plugins）

基于 DeepSeek Harness 插件体系实现的可审计科研证据系统：证据生产、核验、综合、审查四权分离，主 Agent 只能提出 provisional 结论，人类保留最终批准与学术责任。

English — An auditable scientific evidence system built as opt-in plugins on DeepSeek Harness. Evidence production, verification, synthesis, and review are separated into four authorities enforced in code: the lead agent may only propose provisional conclusions, and only a human can record a human decision. All research state is an append-only, replayable projection of research/* session events.

设计动机

科研多代理系统最常见的失败模式是"伪权威"：一个模型同时负责检索、判断与定稿，证据来源、核验过程与最终结论之间没有可审计的链路。本项目的核心转向（完整设计见 plan.md）：

• 主 Agent 拥有综合权，但没有"真理权"；
• 子 Agent 不是模拟不同人格，而是承担互相隔离的证据职责；
• 权限是代码，不是提示词——越权输出在运行时被拒绝；
• 一切模型可见状态都能从会话日志重建（model-visible means logged）。

架构

flowchart TD
    H["Human：研究问题与最终学术责任"] --> L["Lead Agent：集中规划与临时综合"]

    L --> R["Risk Router"]
    R --> S["Scout：发现权"]
    R --> BV["Bibliographic Verifier：书目核验权"]
    R --> E["Extractor：证据提取"]
    R --> CV["Claim Verifier：主张核验权"]

    S --> EL["Evidence Ledger"]
    BV --> EL
    E --> EL
    CV --> EL

    EL --> L
    L --> PC["Provisional Conclusion"]

    PC --> CA["Citation Auditor"]
    CA --> O["Objection Ledger"]
    O --> A["Adjudication"]
    A --> H

四权分离（权限表）

权限	承担者	能做什么	运行时拒绝
discovery	Scout	提出候选	输出 verified: true
bibliographic_verification	Bibliographic Verifier	记录书目判定	形成结论
evidence_extraction	Extractor	产出 claim/experiment	给出判定
claim_verification	Claim Verifier	记录主张判定	改写主张文本
synthesis	Lead Agent	提出 provisional 结论	触碰证据 span / 自批自审
review	Citation Auditor	提出 objection	把决策标记为 rejected
adjudication	Adjudicator	记录裁决判定	记录人类决策
human_adjudication	人类	记录人类决策（唯一）	——

Evidence Ledger

• research/* 事件纯 JSON、只追加、绝不原地修改；foldResearchLedger 是对会话日志的纯 fold。
• 16 个核心事件 + 3 个补充事件（experiment-extracted、human-approval-requested、review-verdict-recorded）。
• 显式状态谓词（isEligibleForSynthesis / hasUnresolvedObjections / canRequestHumanApproval），绝无 status >= X 线性比较。
• 未解决 objection 阻止进入人类批准；人类判定与 agent 判定在事件层面不可混淆。

包结构

包	角色	职责
@deepseek-ai/dsh-research	Service Definition	ctx.research、Ledger、权限、路由/Profile 注册表
@deepseek-ai/dsh-research-router-risk	Provider	廉价优先、确定性升级、超预算转人工
@deepseek-ai/dsh-research-profiles-default	Provider	默认科研模型 Profile
@deepseek-ai/dsh-research-runtime-subagent	Provider	委派子代理、结构化输出校验、写 Ledger
@deepseek-ai/dsh-tool-research	Consumer	Lead 的 5 个科研工具
@deepseek-ai/dsh-bundle-research	Bundle	可选装组合（不进默认 base bundle）

快速开始

前置

• Node ≥ 22、pnpm、npm；
• deepseek-harness 本地克隆（插件在其 monorepo 内构建）；
• dsh CLI（npx @deepseek-ai/dsh）。

本地安装（含三个已知坑）

1. 在 harness 仓库构建 6 个包：pnpm run build。
2. 打包成本地 tarball：node scripts/pack-research.mjs → ~/.dsh/tarballs/research/*.tgz。
3. 配置 profile ~/.dsh/profiles/web/：
   • package.json：6 个研究包指向 file: tarball；dsh.profile.bundles 加入 @deepseek-ai/dsh-bundle-research；
   • pnpm-workspace.yaml：overrides: 钉住 6 个包（pnpm 11 不读 package.json 里的 pnpm.overrides）。
4. 安装并启动：dsh plugin --profile web install，然后 npx @deepseek-ai/dsh web。

为什么不能直接从 registry 装（三个坑的根因）：

1. research 包从未发布到任何 npm registry（官方源没有）；
2. 包内依赖用 workspace:^ 协议，独立 profile 无法解析；
3. 因此采用"手工打包 + file: 引用 + overrides 钉死"的本地发布形态，代价是改源码后需重新打包（scripts/pack-research.mjs 已自动化）。

使用方式

在 dsh web 中直接向 Lead Agent 提问即可，例如：

「调研一下 X 问题，给我一个带文献依据的结论」

流水线自动执行：委派（scout → bibliographic-verifier → extractor → claim-verifier）→ Ledger 记录 → provisional 结论 → 提交人类审批。Lead 可见 5 个工具：

工具	作用
research_delegate	委派一项证据职责并端到端执行
research_ledger_query	投影并查询 Evidence Ledger
research_propose_decision	提出 provisional 结论（不能自批）
research_request_approval	把结论提交人类审批（需 @deepseek-ai/dsh-user-approval，base bundle 已含）
research_link_fulltext	关联已检索全文并记录哈希

重打包

改了 packages/research/ 源码并重新 build 后：

node scripts/pack-research.mjs --install   # 重打包 6 个 tarball + profile 里 pnpm install

目录结构

├── plan.md                  # 完整设计与实施计划
├── README.md
├── scripts/
│   └── pack-research.mjs    # 一键重打包 + 重装
├── packages/research/       # 插件源码快照（6 包，含 lib/ 产物）
└── docs/upstream/           # 上游仓库设计文档与 Agent Note 快照

现状与路线图

MVP（plan.md 第十三节）已实现：reasoningEffort 子代理传递、Evidence Ledger、Scout / Bibliographic Verifier / Extractor / Claim Verifier、provisional 结论、Citation Auditor、确定性风险升级、人类批准边界。

尚未实现：等预算实验记录（Best-of-N 基线对比）、学习型路由器（plan PR 7）、Ledger UI（dsh-ui-research）。

已知限制

• 路由器是确定性规则，非学习式；
• 用量按字节估算，非真实 provider 计费；
• 不确定性/分歧信号由 Lead 自报，暂未从 Ledger 推导；
• research_request_approval 依赖 @deepseek-ai/dsh-user-approval，未组合时 fail-closed（结论保持 awaiting_human）。

来源与许可

• 插件源码快照取自 deepseek-ai/deepseek-harness（commit 47f9438）本地工作树的 packages/research/，尚未合并上游；docs/upstream/ 为上游设计文档与 Agent Note 快照。
• 全部代码与文档沿用上游 MIT 许可，版权归原作者所有；本仓库整体以 MIT 发布（见 LICENSE）。

致谢

DeepSeek Harness 团队与上游插件架构（Service Definition / Provider / Consumer 接缝、Cordis 插件模型）。