📑 dsh-research-report

DeepSeek Harness 的可核查研究报告引擎。

每条结论（claim）都绑定到不可变的证据快照，逐字节核查，并封存进版本化报告——其 manifest 哈希任何人都可重算验证。

English · 简体中文 · Español · Português · हिन्दी

Compatibility

• DeepSeek Harness 0.1.1-rc.2（peer 依赖钉版 0.1.1-rc.2）。
• Node ^22.19.0 || >=24.0.0，仅 ESM（"type": "module"）。
• Peer 依赖：@deepseek-ai/cordis ^4.0.1、@deepseek-ai/schemastery ^3.18.0，以及 0.1.1-rc.2 的 @deepseek-ai/dsh-session、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-system-prompt、@deepseek-ai/dsh-web、@deepseek-ai/dsh-jobs。
• 可选协同（绝不强制）：URL 抓取/检索用 ctx.web provider；后台组装用 ctx.jobs；数据集引文核查用 ctx.dataQuality（dsh-data-quality）。

What you get

• 证据账本——内容寻址快照存储（<ledgerRoot>/objects/<sha256> + JSONL 日志）。同一内容只存一份；快照不可变；每次读取都重算哈希——篡改或删除会被发现，而不是被信任。
• claim ↔ 证据绑定——claim 登记时声明其依赖的证据 id；账本保存绑定关系与每一次核查结论（最新为准）。
• 字节级核查——claim 文本中的每个数字与引文子串都必须能在其绑定快照中字面定位。定位不到 → unverified；标签在快照中对应不同数值（且声称值不存在）→ contradicted。不做语义理解、不做向量相似——只做可审计的字节核对。
• 可选数字核查桥——当 claim 引用 workspace 内结构化数据集（CSV/JSON）且 dsh-data-quality 已挂载时，经其冻结的 verifyCitations 契约做容差核对。
• 版本化封存报告——<reportRoot>/<slug(topic)>/<YYYYMMDD-HHmmss>/report.md + manifest.json；封印哈希 = manifest 的 SHA-256，manifest 内含报告哈希与全部证据哈希。
• 诚实缺口——未核实/有矛盾的 claim 在正文中保留醒目标记 [未核实] / [与证据矛盾]，并在附录 A 列明。绝不静默通过。
• 不做深研循环——检索编排刻意复用官方底座：搜索/抓取走 ctx.web，长任务走 ctx.jobs。规划与综合交给模型（或上游插件）。

Quick start

git 通道

# 在 scratch profile 中（钉住 commit；运行自包含的 `prepare` 构建）
dsh plugin --profile demo add "github:YOUR_ORG/dsh-research-report#<sha>"
# 首次 add 时，profile 的 pnpm-workspace.yaml 会增加 dsh-research-report 的 allowBuilds 条目。

npm 通道

dsh plugin --profile demo add dsh-research-report

两条通道都会把 bundle 行（见 cordis.patch.yml）装入 profile 的 dsh.profile.bundles 层栈，重启生效。

然后，在会话中：

evidence_add({ origin: "docs/market.md", title: "市场快照" })            # → ev-1a2b3c4d5e6f
research_report({ topic: "示例行业概览", sections: [...], claims: [...], evidenceRefs: ["ev-1a2b…"] })
ledger_query({ claimId: "c1" })                                          # 绑定关系 + 核查结论

Install & uninstall

dsh plugin --profile demo add dsh-research-report       # 安装
dsh plugin --profile demo remove dsh-research-report    # 卸载

验证行已挂载：dsh --profile demo --dump-config | grep dsh-research-report。

Configuration

全部可调项都是 Schemastery Config 字段；非法值在加载期响亮失败。相对路径根目录相对 harness 工作目录（workspace）解析。

| Key | Default | Description | | --- | --- | --- | | enabled | true | 总开关；false 时什么都不挂载。 | | ledgerRoot | .research-ledger | 证据账本目录（对象 + JSONL 日志）。 | | reportRoot | research-reports | 封存报告根目录（按主题 + 时间戳版本化）。 | | maxEvidenceBytes | 2097152 | 单条证据快照的 UTF-8 字节硬上限。 | | maxEvidencePerReport | 200 | 单份报告可绑定证据条数硬上限。 | | fetchTimeoutMs | 20000 | 抓取时单次 ctx.web fetch 的超时（毫秒）。 |

Tools & surfaces

• evidence_add({ origin, content?, title? })——登记一条证据。给 content 则按原文存储；不给时 URL 源经 ctx.web 抓取、workspace 相对路径从磁盘读取（读取绝不逃逸 workspace）。返回证据 id 与 SHA-256 哈希。
• research_report({ topic, title?, sections, claims, evidenceRefs, gather?, depth?, background? })——组装并封存报告：校验（claim 引用不全响亮拒绝）→ 逐条核查 → 渲染带醒目标记的 report.md → 写 manifest.json → 返回封印哈希。gather: true 先经 ctx.web 做一轮检索，返回已捕获候选证据与显式缺口清单——绝不自动成稿。background: true 经 ctx.jobs 返回 { kind: 'background', jobId }。
• ledger_query({ claimId? | evidenceId? })——只读查询绑定关系与核查结论；证据读取时重算哈希，篡改/丢失会显式报告。不带 id 时返回账本摘要。
• ctx.researchReport.assemble(request)——面向兄弟插件的冻结服务表面（见 src/service.ts；由 scripts/verify-frozen-contract.mjs 逐字节门禁）。

Permissions & data

dsh-research-report 只消费公开 seam：ctx.tools、ctx.systemPrompt，以及可选的 ctx.web / ctx.jobs / ctx.dataQuality（调用时经 ctx.get 判空使用，绝不写入 inject）。写入只发生在配置的账本与报告根目录内（默认都是 workspace 本地目录）；本地文件读取不越出 workspace；网络访问只经 harness web seam——绝不直接 fetch。证据快照不可变且内容寻址；claim 登记不可变；核查结论只追加。

Security boundaries

• 构造级防篡改——每次快照读取都对照索引重算 SHA-256；不匹配时绑定 claim 核查为 contradicted，ledger_query 报告 integrity: tampered/missing。
• workspace 限制——本地证据读取相对 workspace 根解析并拒绝逃逸（比较前两侧都经 path.resolve）。
• 配置响亮失败——非法边界在挂载期抛错；claim 引用不全、未知证据 id、id/内容冲突在组装期抛错。
• 不碰凭据、无隐藏网络——URL 抓取走 ctx.web（provider 选择、错误分类、SSRF 策略都留在部署方的 web provider）。
• 注册可逆——所有贡献经 ctx.effect() / register()，卸载与热重载干净。

Known limitations

• 字节级而非语义级——内置核查只做数字/引文字面定位；没有可核查字面量的转述性 claim 判 unverified；声称值缺失而标签对应其他数值时判 contradicted。这是 v1 的刻意选择（可审计优先于聪明）。
• 会话事件自适应——插件声明了类型化的 research-report/evidence、research-report/verify、research-report/seal 会话事件，但 rc.2 的 Session.append 仍不提供 ignorable 选项、也没有插件事件注册面，所以只有宿主 build 认识这些类型时才真正落盘（否则持久化层会在恢复时拒绝该日志）。账本日志始终是权威的持久事实源。
• 默认 profile 不挂载 fetch provider——官方 dsh-base 只挂搜索，所以配置 fetch provider 之前 URL 抓取会响亮失败（WEB_UNAVAILABLE/WEB_PROVIDER_UNAVAILABLE）；基于搜索的 gather 会把未捕获的来源列入缺口清单。
• 单 workspace 作用域——账本与报告根目录在挂载时相对 harness 工作目录解析；多 workspace 部署应在各 profile 配置绝对路径。

Development

pnpm install
pnpm run typecheck && pnpm run typecheck:ci
pnpm test
pnpm run build
pnpm run verify:self-contained && pnpm run verify:artifacts
node scripts/check-readme-sync.mjs
node scripts/verify-frozen-contract.mjs
pnpm pack

• typecheck 经已安装的 0.1.1-rc.2 peer 解析 @deepseek-ai/*；typecheck:ci 关闭 skipLibCheck 并开启 verbatimModuleSyntax 对照已发布类型。两者都必须保持绿。
• 测试使用 0.1.1-rc.2 peer 的真实 Context/Session/ToolRuntime/LocalJobRegistry/WebRuntime；只有网络后端是注册进真实 ctx.web 注册表的脚本化 provider。
• 发布：node scripts/release.mjs <x.y.z>（bump、盖 CHANGELOG、重跑门禁、提交 + 打 tag；绝不 push）。

Topics

dsh、dsh-plugin、deepseek-harness、cordis、research、evidence-ledger、verifiable-report、audit、citation-verification

Contributors

dsh-research-report contributors。

PerryLink DSH Plugin Family

本项目是 PerryLink 维护的 DeepSeek Harness 插件家族成员。如果它对你有帮助，其他成员大概率也有用：

| Plugin | One-liner | |---|---| | dsh-data-quality | 数据集质量检查与引文核查（本插件可选消费的数字核查桥） | | dsh-doublecheck | 工程纪律守卫：需求拷问、测试门禁、对抗性复核 | | dsh-fast | DeepSeek Harness 只读性能诊断。 | | dsh-industry-research | 行业研究编排，经本插件的 ctx.researchReport.assemble 封存交付物 | | dsh-memento | 审批门跨会话记忆：ctx.memory seam + SQLite + memory 工具 | | dsh-score | DeepSeek Harness 插件的多维质量评分。 | | dsh-test-drive | DeepSeek Harness 插件的隔离试装冒烟。 |

License

Apache-2.0 — 见 LICENSE。