dsh-research-report 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.4.1] - 2026-11-13
4
+
5
+ ### Changed
6
+
7
+ - **The sibling-facing seam is now declared, not implied.** `src/service.ts` documents the two supported surfaces: the frozen in-process `assemble()` → `AssembleReportResult.reportDir`, and the event-driven `tool/result.meta.{reportFile,manifestFile}` projection (absolute paths, sealed results only, additive-only fields, never renamed). `test/meta-contract.spec.ts` pins the projection's shape. No behavior change. Addresses #27.
8
+
3
9
  ## [0.4.0] - 2026-11-10
4
10
 
5
11
  ### Added
package/README.en.md ADDED
@@ -0,0 +1,467 @@
1
+ <div align="center">
2
+
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-research-report-hero-en-dark.webp">
5
+ <img src="docs/assets/dsh-research-report-hero-en-light.webp" width="100%" alt="dsh-research-report banner: the sealed report directory as a hash fan-in — report.md, the evidence hashes held in the ledger, verification.jsonl and disconfirmation.jsonl fold into manifest.json, whose SHA-256 is the seal; the strip below is the standalone dsh-research-verify recompute">
6
+ </picture>
7
+
8
+ # dsh-research-report
9
+
10
+ **Ship a report whose every claim anyone can re-check offline on their own machine — change one byte and the seal hash stops matching.**
11
+
12
+ A verifiable research-report engine for DeepSeek Harness: claims bind to immutable evidence snapshots, numbers and quotes are checked byte-for-byte, and the result is sealed into a versioned report directory whose seal is the SHA-256 of `manifest.json`.
13
+
14
+ [Install](#three-step-setup) · [Configuration](#configuration) · [FAQ](#faq) · [简体中文](README.md) · [English](README.en.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
15
+
16
+ [![License](https://img.shields.io/badge/license-Apache--2.0-3366CC?style=flat-square&labelColor=2B3245)](LICENSE)
17
+ [![DSH](https://img.shields.io/badge/DSH-%E2%89%A50.1.6%20%3C0.3.0-4B67B4?style=flat-square&labelColor=2B3245)](#compatibility)
18
+ [![npm](https://img.shields.io/npm/v/dsh-research-report?style=flat-square&labelColor=2B3245&color=CB3837)](https://www.npmjs.com/package/dsh-research-report)
19
+ [![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-research-report/ci.yml?branch=main&label=CI&style=flat-square&labelColor=2B3245)](https://github.com/PerryLink/dsh-research-report/actions/workflows/ci.yml)
20
+ [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24.9-339933?style=flat-square&labelColor=2B3245)](#compatibility)
21
+
22
+ [![Stars](https://img.shields.io/github/stars/PerryLink/dsh-research-report?style=flat-square&labelColor=2B3245)](https://github.com/PerryLink/dsh-research-report/stargazers)
23
+ [![npm downloads](https://img.shields.io/npm/dm/dsh-research-report?style=flat-square&labelColor=2B3245&color=CB3837)](https://www.npmjs.com/package/dsh-research-report)
24
+ [![dshfind](https://dshfind.com/api/badge/PerryLink/dsh-research-report?metric=downloads)](https://dshfind.com/plugins/PerryLink/dsh-research-report?ref=badge)
25
+ [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/PerryLink/dsh-research-report/badge)](https://securityscorecards.dev/viewer/?uri=github.com/PerryLink/dsh-research-report)
26
+ [![DSH Market](https://img.shields.io/badge/DSH_Market-listed-4B67B4?style=flat-square&labelColor=2B3245)](https://dsh.market/)
27
+ [![Gitee](https://img.shields.io/badge/Gitee-mirror-C71D23?style=flat-square&labelColor=2B3245&logo=gitee)](https://gitee.com/perrylink/dsh-research-report)
28
+
29
+ ```sh
30
+ dsh plugin --profile <name> add dsh-research-report
31
+ ```
32
+
33
+ </div>
34
+
35
+ <sub>Community plugin, not affiliated with DeepSeek. Canonical repository: <https://github.com/PerryLink/dsh-research-report> (Gitee is a mirror).</sub>
36
+
37
+ ## What it is
38
+
39
+ Give the model a topic and a set of sources, and `dsh-research-report` binds every claim to immutable evidence snapshots, checks the numbers and quotes byte-for-byte, then seals the result into a versioned report directory anyone can re-check independently. The directory holds `report.md`, `manifest.json`, and the audit journals; the seal is the SHA-256 of `manifest.json`, and `dsh-research-verify` recomputes it offline without mounting the plugin. It deliberately ships no deep-research loop: retrieval runs over `ctx.web`, long runs over `ctx.jobs`, and planning and synthesis stay with the model or an upstream plugin.
40
+
41
+ <picture>
42
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-research-report-flow-v5-dark.svg">
43
+ <img src="docs/assets/dsh-research-report-flow-v5-light.svg" width="100%" alt="dsh-research-report structure: panel 1 is the content-addressed evidence ledger (capture, sha256, objects snapshot, four JSONL journals); panel 2 is the per-claim verdict comb (integrity, binding, literal location; five verdicts, first match wins, written back to the ledger); panel 3 is the sealed report directory (report.md and the two audit journals fold into manifest.json, whose SHA-256 is the seal); the rail underneath is the out-of-workspace dsh-research-verify binary">
44
+ </picture>
45
+
46
+ ## Three-step setup
47
+
48
+ 1. **Install** (pick one channel):
49
+
50
+ ```sh
51
+ # npm channel (published releases)
52
+ dsh plugin --profile web add dsh-research-report
53
+ # git channel (latest main; equivalent to git+https://github.com/PerryLink/dsh-research-report.git)
54
+ dsh plugin --profile web add github:PerryLink/dsh-research-report
55
+ # tarball channel: pnpm pack in this repo, then
56
+ dsh plugin --profile web add ./dsh-research-report-<version>.tgz
57
+ ```
58
+
59
+ Both online channels install the bundle row (see [`cordis.patch.yml`](cordis.patch.yml)) into the profile's `dsh.profile.bundles` stack; **restart to take effect**.
60
+
61
+ 2. **Minimal config** (defaults are usable; relative roots resolve against the harness working directory):
62
+
63
+ ```yaml
64
+ - insert:
65
+ - id: dsh-research-report
66
+ name: dsh-research-report
67
+ config:
68
+ ledgerRoot: .research-ledger
69
+ reportRoot: research-reports
70
+ ```
71
+
72
+ 3. **Verify it mounts**:
73
+
74
+ ```sh
75
+ dsh --profile web --dump-config | grep dsh-research-report
76
+ ```
77
+
78
+ Then run the minimal loop in a session and re-check the seal with the CLI:
79
+
80
+ ```text
81
+ evidence_add({ origin: "docs/market.md", title: "Market snapshot" }) # → ev-1a2b3c4d5e6f
82
+ research_report({ topic: "...", sections: [...], claims: [...], evidenceRefs: ["ev-1a2b…"] })
83
+ ledger_query({ claimId: "c1" }) # bindings + verdict
84
+ ```
85
+
86
+ ```sh
87
+ dsh-research-verify --report research-reports/<topic>/<YYYYMMDD-HHmmss>
88
+ ```
89
+
90
+ **Uninstall**: `dsh plugin --profile web remove dsh-research-report` (or remove the row from the profile patch).
91
+
92
+ <details>
93
+ <summary>Install from the DSH Desktop market</summary>
94
+
95
+ Every PerryLink plugin is listed in the built-in DSH Desktop market: **Market → Sources → Add source → paste** `https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json` **→ select**. Installation still requires the market's npm identity check and your confirmation.
96
+
97
+ </details>
98
+
99
+ ## Core capabilities
100
+
101
+ Three things carry the trust: evidence is immutable, checks are recomputable, and gaps are never hidden.
102
+
103
+ - **Evidence ledger** — a content-addressed snapshot store (`<ledgerRoot>/objects/<sha256>` + JSONL journals). The same content is stored exactly once; snapshots are immutable; every read recomputes the hash, so tampering or deletion is detected instead of trusted.
104
+ - **Claim ↔ evidence binding** — claims register with the evidence ids they rely on; the ledger keeps the binding and every verification verdict (latest wins).
105
+ - **Byte-level verification** — every number and quoted span in a claim must be locatable verbatim in the bound snapshots. No bound evidence, or no checkable literal, marks the claim `unverified`; bound evidence that cannot confirm or deny the claimed literals marks it `insufficient`; a label whose snapshot value differs (the claimed value absent) marks it `disproven`; tampered/missing snapshots mark it `contradicted`. No semantics, no embeddings — auditable byte checks.
106
+ - **Optional numeric bridge** — when a claim cites a structured workspace dataset (CSV/JSON) and `dsh-data-quality` is mounted, citations are cross-checked with tolerances through its frozen `verifyCitations` contract; a dataset mismatch disproves the claim.
107
+ - **DOI evidence (zero network)** — DOI origins are validated deterministically (`10.xxxx/xxxx` structure, a prefix whitelist, and a DOI character set); invalid DOIs fail loud. Optional journal/year metadata is accepted, and `requireJournalMetadata` gates academic DOI evidence only when enabled.
108
+ - **Versioned sealed reports** — `<reportRoot>/<slug(topic)>/<YYYYMMDD-HHmmss>/report.md` + `manifest.json` + `verification.jsonl` + `disconfirmation.jsonl`; the seal hash is the SHA-256 of the manifest, which itself carries the report hash, every evidence hash, and the hash of each audit journal.
109
+ - **Pre-delivery re-audit & seal interception** — before sealing, every bound claim is re-verified offline and journaled to `verification.jsonl`; verdict drift, tampered/missing bound evidence, or a journal serialization failure blocks the seal (fail loud, no tunable).
110
+ - **Falsification ledger** — every contradicted or disproven claim is recorded in `disconfirmation.jsonl` (claim + evidence references + reason) and listed in the report's falsification-log appendix.
111
+ - **Negative knowledge** — a disproven claim is remembered by its content hash (`disproofs.jsonl`); the same text re-reported against unchanged evidence is forced back to `disproven` and only re-verifies once the evidence changes.
112
+ - **Read-only verifier loop** — after sealing, a deterministic `verifySealedReport` fallback (zero network, zero model) recomputes the seal and audit hashes and re-checks every claim, writing the machine check to `verifier-note.md`; when `ctx.jobs` is mounted a read-only verifier job is also spawned (the model review is an enhancement, never a replacement).
113
+ - **Session-anchored evidence** — `evidence_add` accepts an optional `sessionRef` (`sessionId` + `eventRange`, validated loud); the anchor is stored, rendered in Appendix B, and registered in the manifest and `verification.jsonl`. Session-anchored evidence verifies honestly as `unverified` (`session-anchored evidence requires a manual check against the session log`).
114
+ - **Honest gaps** — unverified, insufficient, contradicted, and disproven claims keep a visible marker in the report body and are listed in Appendix A. Nothing is silently passed.
115
+ - **No deep-research loop** — retrieval orchestration is deliberately reused: `ctx.web` for search/fetch, `ctx.jobs` for long runs. Planning and synthesis stay with the model (or an upstream plugin).
116
+
117
+ ### Tool surface
118
+
119
+ - **`evidence_add({ origin, content?, title? })`** — register one evidence snapshot. With `content` the text is stored verbatim; without it a URL origin is fetched through `ctx.web` and a workspace-relative path is read from disk (reads never escape the workspace). Returns the evidence id and SHA-256 hash.
120
+ - **`research_report({ topic, title?, sections, claims, evidenceRefs, gather?, depth?, background? })`** — assemble and seal a report: validate (unregistered claim references are rejected loudly), verify every claim, render `report.md` with visible markers, write `manifest.json`, and return the seal hash. `gather: true` runs ONE search round over `ctx.web` and returns captured candidate evidence plus an explicit gap list — it never auto-assembles. `background: true` returns `{ kind: 'background', jobId }` over `ctx.jobs`.
121
+ - **`research_trail({ limit?, format? })`** — read-only claim → evidence → verdict trail: joins registered claims with their evidence and stored verdicts, marks claims with no resolvable evidence as **unbound**, lists dangling evidence ids, and returns Markdown for a reviewer plus structured rows. No new storage, no verdict changes.
122
+ - **`ledger_query({ claimId? | evidenceId? })`** — read-only binding/verdict queries; evidence is re-hashed on read so a tampered or missing snapshot is reported explicitly. With no id, returns a ledger summary.
123
+ - **`ctx.researchReport.assemble(request)`** — the frozen service surface for sibling plugins (see `src/service.ts`; gated byte-for-byte by [`scripts/verify-frozen-contract.mjs`](scripts/verify-frozen-contract.mjs)).
124
+
125
+ ### Examples
126
+
127
+ These are the plugin's real entry points; install once, then call one.
128
+
129
+ **Detailed example**
130
+
131
+ **Command**
132
+
133
+ ~~~sh
134
+ research_report({
135
+ topic: "示例行业概览",
136
+ sections: [{ heading: "市场规模", paragraphs: [{ text: "2025 年全球示例行业市场规模为 1,280 亿元。", claimIds: ["c1"] }] }],
137
+ claims: [{ id: "c1", text: "市场规模为 1,280 亿元", evidenceIds: ["ev-5dc0a84d0e48"] }],
138
+ evidenceRefs: ["ev-5dc0a84d0e48", "ev-c6cf024e0916", "ev-61f8f4533cb7"]
139
+ })
140
+ ~~~
141
+
142
+ **Output**
143
+
144
+ ~~~text
145
+ report sealed: /tmp/rr-test-4U2mlF/reports/示例行业概览/20261019-124904
146
+ seal (sha256 of manifest.json): 5c85c97597096ced281ca191d7abaaf7434f18b397d35ac81c31aa364a3b12f9
147
+ claims: 1 verified / 0 unverified / 0 contradicted / 0 insufficient / 0 disproven (of 1); evidence bound: 3
148
+ ~~~
149
+
150
+ *Observed from `README.md:112-118,150; test/index.spec.ts:166-177; src/tools/research-report.ts:170-175`*
151
+
152
+ **Failure branch**
153
+
154
+ **Input**
155
+
156
+ ~~~text
157
+ {"topic":"probe","sections":[{"heading":"Growth","paragraphs":[{"text":"Growth was 42%.","claimIds":["c1"]}]}],"claims":[{"id":"c1","text":"Growth was 42%.","evidenceIds":[]}]}
158
+ ~~~
159
+
160
+ **Output**
161
+
162
+ ~~~text
163
+ edge-case (no throw): isError=false; kind=sealed; verdicts[0]={"claimId":"c1","status":"unverified","note":"claim binds no evidence snapshot"}; counts={"verified":0,"unverified":1,"contradicted":0,"insufficient":0,"disproven":0}; evidenceCount=0; report.md marker=Growth was 42%. [未核实]
164
+ ~~~
165
+
166
+ *Observed from `plugins/dsh-research-report/src/verify.ts:173-175 (unverified verdict); plugins/dsh-research-report/src/assemble.ts:209-220 (visible mark); plugins/dsh-research-report/README.md:87 (honest gaps); exercised through plugins/dsh-research-report/test/harness.ts`*
167
+
168
+ **Brief examples**: `research_report` · `ledger_query`
169
+
170
+ ### dsh-research-verify CLI
171
+
172
+ The standalone binary (bundled as `lib/cli.js`, zero `@deepseek-ai` imports) audits any sealed report directory without mounting the plugin:
173
+
174
+ ```sh
175
+ dsh-research-verify --report <dir> [--seal <sha256>] [--ledger <dir>] [--format json|sarif]
176
+ ```
177
+
178
+ - `--report <dir>` — the sealed report directory (`manifest.json` + `report.md` + the audit journals).
179
+ - `--seal <sha256>` — the expected seal hash to compare the recomputed manifest hash against. Omitted = the recomputed hash is reported without comparison.
180
+ - `--ledger <dir>` — the evidence ledger root (`objects/<sha256>` + `index.jsonl`) enabling per-claim byte-level re-checks. Omitted = claim re-checks are skipped honestly.
181
+ - `--format` — `json` (default) or `sarif` (SARIF 2.1.0).
182
+
183
+ It recomputes the seal hash (SHA-256 of `manifest.json`), the `report.md` hash, and the audit-journal hashes, re-runs the byte-level + integrity check for every claim, and exits non-zero when any performed check fails. The same `verifySealedReport` / `buildVerificationReport` / `renderSarif` / `renderVerificationJson` functions are exported from the package for library use.
184
+
185
+ ## Configuration
186
+
187
+ All tunables are Schemastery `Config` fields; invalid values fail the profile load loudly. Relative roots resolve against the harness working directory (the workspace). `cordis.patch.yml` documents each key inline.
188
+
189
+ Most-used keys:
190
+
191
+ | Key | Default | Meaning |
192
+ | --- | --- | --- |
193
+ | `enabled` | `true` | Master switch; `false` mounts nothing. |
194
+ | `ledgerRoot` | `.research-ledger` | Evidence-ledger directory (objects + JSONL journals). |
195
+ | `reportRoot` | `research-reports` | Sealed-report root (versioned per topic and timestamp). |
196
+ | `workspaceRoot` | *(host session working directory)* | Root for workspace-path evidence; defaults to the session working directory, then the harness cwd. |
197
+ | `maxEvidenceBytes` | `2097152` | Hard cap on one evidence snapshot's UTF-8 bytes. |
198
+ | `maxEvidencePerReport` | `200` | Hard cap on evidence items bound into one report. |
199
+
200
+ <details>
201
+ <summary>Full configuration table (8 keys)</summary>
202
+
203
+ | Key | Default | Meaning |
204
+ | --- | --- | --- |
205
+ | `enabled` | `true` | Master switch; `false` mounts nothing. |
206
+ | `ledgerRoot` | `.research-ledger` | Evidence-ledger directory (objects + JSONL journals). |
207
+ | `reportRoot` | `research-reports` | Sealed-report root (versioned per topic and timestamp). |
208
+ | `workspaceRoot` | *(host session working directory)* | Root for workspace-path evidence; defaults to the session working directory, then the harness cwd. |
209
+ | `maxEvidenceBytes` | `2097152` | Hard cap on one evidence snapshot's UTF-8 bytes. |
210
+ | `maxEvidencePerReport` | `200` | Hard cap on evidence items bound into one report. |
211
+ | `fetchTimeoutMs` | `20000` | Deadline (ms) for one `ctx.web` fetch during capture. |
212
+ | `requireJournalMetadata` | `false` | When true, DOI-typed evidence must carry a journal name and publication year at registration (fails loud otherwise). |
213
+
214
+ </details>
215
+
216
+ Example override in your profile patch:
217
+
218
+ ```yaml
219
+ - insert:
220
+ - id: dsh-research-report
221
+ name: dsh-research-report
222
+ config:
223
+ reportRoot: research-reports/acme
224
+ maxEvidencePerReport: 100
225
+ requireJournalMetadata: true
226
+ ```
227
+
228
+ ## FAQ
229
+
230
+ <details>
231
+ <summary>Where do the ledger and reports actually live? What happens if I delete them?</summary>
232
+
233
+ Both sit under the configured roots: `ledgerRoot` (default `.research-ledger`) and `reportRoot` (default `research-reports`), resolved against the harness working directory when relative. Snapshots are content-addressed and immutable, and the same content is stored only once; delete or rewrite an object and the next read's hash check fails, the claims bound to it verify as `contradicted`, and `ledger_query` reports `integrity: missing`/`tampered` — nothing is quietly treated as fine.
234
+
235
+ </details>
236
+
237
+ <details>
238
+ <summary>What happens without a fetch provider? Does it degrade silently?</summary>
239
+
240
+ Never silently. The shipped `dsh-base` mounts search only, so URL capture fails loud (`WEB_UNAVAILABLE`/`WEB_PROVIDER_UNAVAILABLE`) until a fetch provider is configured; search-based `gather` lists the uncaptured sources in the gap list and never fabricates evidence or auto-assembles a report.
241
+
242
+ </details>
243
+
244
+ <details>
245
+ <summary>Does it conflict with dsh-data-quality?</summary>
246
+
247
+ No. `ctx.dataQuality` is optional and is looked up with `ctx.get` at call time — never injected. When present it cross-checks dataset citations through its frozen `verifyCitations` contract; when absent that path is skipped honestly. This plugin registers no waterfall listeners at all.
248
+
249
+ </details>
250
+
251
+ <details>
252
+ <summary>How big is the performance overhead?</summary>
253
+
254
+ Verification is pure byte work: no network, no model calls, linear in the number and quote literals of a claim and the size of the bound snapshots. The pre-seal re-audit is the same deterministic work repeated. The only external wait is evidence capture, bounded by `fetchTimeoutMs` (default 20000 ms); long reports can run with `background: true` over `ctx.jobs`.
255
+
256
+ </details>
257
+
258
+ <details>
259
+ <summary>Why does my paraphrased claim verify as unverified?</summary>
260
+
261
+ That is the byte-level design at work: the built-in check locates number and quote literals, and cannot judge semantic equivalence across a rewrite. See the first entry under Known limitations — auditable beats clever.
262
+
263
+ </details>
264
+
265
+ ## Security boundaries
266
+
267
+ - **Tamper-evidence by construction** — every snapshot read recomputes SHA-256 against the index; a mismatch verifies the bound claims `contradicted` and `ledger_query` reports `integrity: tampered`/`missing`.
268
+ - **Workspace confinement** — local evidence reads resolve against the workspace root and refuse escapes (both sides are `path.resolve`d before comparison).
269
+ - **Fail-loud configuration** — invalid bounds throw at mount; unregistered claim references, unknown evidence ids, and id/content conflicts throw at assemble.
270
+ - **No credential handling, no hidden network** — URL capture rides `ctx.web` (provider selection, error taxonomy, and any SSRF policy stay with the deployment's web providers).
271
+ - **Reversible registrations** — every contribution goes through `ctx.effect()` / `register()`, so uninstall and hot reload are clean.
272
+
273
+ ## Permissions & data
274
+
275
+ `dsh-research-report` consumes only public seams: `ctx.tools`, `ctx.systemPrompt`, and optionally `ctx.web` / `ctx.jobs` / `ctx.dataQuality` (looked up with `ctx.get` at call time, never injected). It writes only inside the configured ledger and report roots (both default to workspace-local directories), reads workspace files only inside the workspace, and reaches the network exclusively through the harness web seam — never a direct `fetch`. Evidence snapshots are immutable and content-addressed; claim registrations are immutable; verdicts are append-only.
276
+
277
+ - **Permissions declared in the manifest**: `fs:workspace-write`, `network:ctx-web-only`, `session:read`, `session:write`, `native-code:none` (see the `dshWorkshop` block in `package.json`).
278
+ - **Session events**: `research-report/evidence`, `research-report/verify`, and `research-report/seal` are an adaptive mirror; they land in the session log only when the host knows the vocabulary, otherwise the ledger journals alone carry the durable truth (see Known limitations).
279
+
280
+ ## Known limitations
281
+
282
+ - **Byte-level, not semantic** — the built-in check locates number/quote literals verbatim; paraphrased claims without a checkable literal verify as `unverified`, and a true claim whose number is absent while its label appears with a different value reads `contradicted`. This is a deliberate v1 choice (auditable beats clever).
283
+ - **Session events are adaptive** — the plugin declares typed `research-report/evidence`, `research-report/verify`, and `research-report/seal` session events, but the 0.1.5-alpha.1 `Session.append` still exposes no `ignorable` option and no plugin event-registration surface, so appends activate only when the host build knows the types (otherwise the persistence layer would refuse the log on restore). The ledger journals are always the durable source of truth.
284
+ - **Default profiles mount no fetch provider** — the shipped `dsh-base` mounts search only, so URL capture fails loud (`WEB_UNAVAILABLE`/`WEB_PROVIDER_UNAVAILABLE`) until a fetch provider is configured; search-based `gather` lists uncaptured sources in the gap list.
285
+ - **Single-workspace scope** — ledger and report roots resolve against the harness working directory at mount; multi-workspace deployments should configure absolute roots per profile.
286
+
287
+ ## Interoperability with other DSH plugins
288
+
289
+ This plugin does not contend structurally for another plugin's resources:
290
+
291
+ - **One service key, `ctx.researchReport`** — provided by the Service Definition in `src/service.ts`; no second service key is registered.
292
+ - **No waterfall listeners** — the plugin registers no `ctx.on()` listener, so it takes part in no ordering-sensitive event chain; if one is ever added, the allow/passthrough branch MUST call `next()`.
293
+ - **No HTTP routes, no client surface** — no `webServer` prefix and no client slot; it is a pure host plugin (the repo has no `client/`).
294
+ - **The patch layer only inserts its own row** — the bundle patch inserts `dsh-research-report` and never overrides a built-in row's `config`.
295
+ - **Optional siblings are looked up on demand** — `ctx.web` / `ctx.jobs` / `ctx.dataQuality` are resolved with `ctx.get` at call time; when missing, the affected path fails loud with an explicit reason instead of silently taking another route.
296
+ - **Frozen contracts are gated** — `ctx.researchReport.assemble` (`src/service.ts`) and `CitationCheck*` (`src/verify.ts`) are byte-frozen blocks shared with sibling plugins, and `scripts/verify-frozen-contract.mjs` guards drift in CI.
297
+
298
+ ## Compatibility
299
+
300
+ | Surface | Status |
301
+ | --- | --- |
302
+ | Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1` (verified 2026-09-25). npm dev/test line `0.1.7-rc.2`; the compat matrix pins all four declared peer lines. On 0.1.5-alpha.1 (adapted 2026-09-09) the session envelope keeps its ignorable field for stored-log read compatibility only — `Session.append` still cannot stamp it, so audit-gate behavior is unchanged. |
303
+ | Node | `^22.19.0 \|\| >=24.9.0`, ESM only (`"type": "module"`) |
304
+ | Platforms | Anywhere DSH runs (pure host; the network is reached through `ctx.web` only) |
305
+ | Model | Text models fully supported; verification is byte comparison, no extra model capability required |
306
+
307
+ Peer dependencies: `@deepseek-ai/cordis ^4.0.5-alpha.1`, `@deepseek-ai/schemastery ^3.18.5-alpha.1`, plus `@deepseek-ai/dsh-session`, `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-system-prompt`, `@deepseek-ai/dsh-web`, `@deepseek-ai/dsh-jobs` (ranges in `package.json`). Optional siblings (never required): `ctx.web` for capture, `ctx.jobs` for background assembly, `ctx.dataQuality` for dataset citation cross-checks.
308
+
309
+ ## Ecosystem & quality
310
+
311
+ - [Gitee mirror](https://gitee.com/perrylink/dsh-research-report) (sync mirror; GitHub is canonical)
312
+ - [dshfind plugin page](https://dshfind.com/plugins/PerryLink/dsh-research-report) (installs and ranking)
313
+ - [OpenSSF Scorecard report](https://securityscorecards.dev/viewer/?uri=github.com/PerryLink/dsh-research-report) (driven by [.github/workflows/scorecard.yml](.github/workflows/scorecard.yml))
314
+ - [dsh-plugin-doctor verification report](https://github.com/PerryLink/dsh-plugin-doctor#verified-徽章)
315
+ - [DSH Market](https://dsh.market/) (listed)
316
+ - **1024 store channel**: `npm i -g dsh1024` once, then `dsh1024 plugin --profile web add dsh-research-report` (counts toward the [deepseek1024.com](https://deepseek1024.com) install ranking)
317
+ - [Ecosystem knowledge base](https://perrylink.github.io/dsh-plugin-guide/) — measured data, not marketing: plugin development guide · plugin-selection data · maintenance criteria
318
+
319
+ ## Development
320
+
321
+ ```sh
322
+ pnpm install
323
+ pnpm run typecheck && pnpm run typecheck:ci
324
+ pnpm test
325
+ pnpm run build
326
+ pnpm run verify:self-contained && pnpm run verify:artifacts
327
+ pnpm run verify:frozen-contract
328
+ node scripts/check-readme-sync.mjs
329
+ pnpm run check:lockfile
330
+ pnpm pack
331
+ ```
332
+
333
+ - `typecheck` resolves `@deepseek-ai/*` through the installed 0.1.7-rc.2 peers; `typecheck:ci` clears `skipLibCheck` and enables `verbatimModuleSyntax` against the published types. Both must stay green.
334
+ - Tests use the real `Context`/`Session`/`ToolRuntime`/`LocalJobRegistry`/`WebRuntime` from the 0.1.7-rc.2 peers; only network backends are scripted providers registered through the real `ctx.web` registries.
335
+ - Release: `node scripts/release.mjs <x.y.z>` (bumps, stamps CHANGELOG, re-runs the gate, commits + tags; never pushes).
336
+ - README images are generated programmatically by [`scripts/gen-readme-assets.py`](scripts/gen-readme-assets.py) (Python + Pillow): the raster banner is `docs/assets/dsh-research-report-hero-{zh,en}-{light,dark}.webp` (1440×576) and the hand-written structure diagram is `docs/assets/dsh-research-report-flow-v5-{light,dark}.svg` (1100×660), safe to re-run, shared by all five languages.
337
+
338
+ Directory layout:
339
+
340
+ | Path | Contents |
341
+ | --- | --- |
342
+ | `src/index.ts` | Function-plugin contract (`name`/`inject`/`Config`/`apply`, no default export) |
343
+ | `src/service.ts` | `ctx.researchReport` Service Definition + the byte-frozen `assemble` contract block |
344
+ | `src/ledger.ts` | The content-addressed evidence ledger (objects + JSONL journals, re-hash on read) |
345
+ | `src/verify.ts` | The byte-level checker + the frozen `CitationCheck*` bridge types |
346
+ | `src/assemble.ts` | Pure assembly: request validation, `report.md` rendering, deterministic `manifest.json`, seal |
347
+ | `src/gather.ts` | Capture (`ctx.web` / workspace files) and the `gather` candidate round |
348
+ | `src/tools/` | The three consumers: `evidence_add`, `research_report`, `ledger_query` |
349
+ | `test/` | vitest over the real host runtime; only network backends are scripted providers |
350
+ | `fixtures/` | Three local documents covering the evidence → seal → tamper → contradicted flow |
351
+
352
+ Topics: `dsh`, `dsh-plugin`, `deepseek-harness`, `cordis`, `research`, `evidence-ledger`, `verifiable-report`, `audit`, `citation-verification`
353
+
354
+ ## Family & thanks
355
+
356
+ This project is part of the DeepSeek Harness plugin family from [PerryLink](https://github.com/PerryLink) (all Apache-2.0). If it is useful, **a star helps the next person find it** — nothing is gated behind it.
357
+
358
+ - [@PerryLink](https://github.com/PerryLink) — original author and maintainer: plugin architecture, evidence ledger, byte-level verification, sealed reports, five-language documentation, CI and release automation.
359
+
360
+ <details>
361
+ <summary>Expand all plugins</summary>
362
+
363
+ | Plugin | Status |
364
+ |---|---|
365
+ | **[dsh-aqua-input-check](https://github.com/PerryLink/dsh-aqua-input-check)** | |
366
+ | **[dsh-archive-check](https://github.com/PerryLink/dsh-archive-check)** | |
367
+ | **[dsh-auto-review](https://github.com/PerryLink/dsh-auto-review)** | |
368
+ | **[dsh-autotier](https://github.com/PerryLink/dsh-autotier)** | 🧊 FROZEN — see the repo README |
369
+ | **[dsh-bid-ca-precheck](https://github.com/PerryLink/dsh-bid-ca-precheck)** | |
370
+ | **[dsh-bid-qual-check](https://github.com/PerryLink/dsh-bid-qual-check)** | |
371
+ | **[dsh-cert-mcp](https://github.com/PerryLink/dsh-cert-mcp)** | 🧊 FROZEN — see the repo README |
372
+ | **[dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind)** | |
373
+ | **[dsh-click](https://github.com/PerryLink/dsh-click)** | |
374
+ | **[dsh-composer-history](https://github.com/PerryLink/dsh-composer-history)** | |
375
+ | **[dsh-contract-stance](https://github.com/PerryLink/dsh-contract-stance)** | |
376
+ | **[dsh-customs-doc-check](https://github.com/PerryLink/dsh-customs-doc-check)** | |
377
+ | **[dsh-data-quality](https://github.com/PerryLink/dsh-data-quality)** | |
378
+ | **[dsh-demurrage-ledger](https://github.com/PerryLink/dsh-demurrage-ledger)** | |
379
+ | **[dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck)** | |
380
+ | **[dsh-drill-script-check](https://github.com/PerryLink/dsh-drill-script-check)** | |
381
+ | **[dsh-eia-guide-check](https://github.com/PerryLink/dsh-eia-guide-check)** | |
382
+ | **[dsh-emergency-plan](https://github.com/PerryLink/dsh-emergency-plan)** | |
383
+ | **[dsh-essay-rubric-check](https://github.com/PerryLink/dsh-essay-rubric-check)** | |
384
+ | **[dsh-evidence-check](https://github.com/PerryLink/dsh-evidence-check)** | |
385
+ | **[dsh-export-ctl-check](https://github.com/PerryLink/dsh-export-ctl-check)** | |
386
+ | **[dsh-fast](https://github.com/PerryLink/dsh-fast)** | |
387
+ | **[dsh-fmea-table-check](https://github.com/PerryLink/dsh-fmea-table-check)** | |
388
+ | **[dsh-forecast-penalty](https://github.com/PerryLink/dsh-forecast-penalty)** | |
389
+ | **[dsh-fund-research](https://github.com/PerryLink/dsh-fund-research)** | |
390
+ | **[dsh-github](https://github.com/PerryLink/dsh-github)** | |
391
+ | **[dsh-gongwen-flow-check](https://github.com/PerryLink/dsh-gongwen-flow-check)** | |
392
+ | **[dsh-gongwen-word-check](https://github.com/PerryLink/dsh-gongwen-word-check)** | |
393
+ | **[dsh-guard-plan-qc](https://github.com/PerryLink/dsh-guard-plan-qc)** | |
394
+ | **[dsh-hazchem-check](https://github.com/PerryLink/dsh-hazchem-check)** | |
395
+ | **[dsh-hazplan-check](https://github.com/PerryLink/dsh-hazplan-check)** | |
396
+ | **[dsh-hidden-risk-map](https://github.com/PerryLink/dsh-hidden-risk-map)** | |
397
+ | **[dsh-hs-classify](https://github.com/PerryLink/dsh-hs-classify)** | |
398
+ | **[dsh-icd-rule-check](https://github.com/PerryLink/dsh-icd-rule-check)** | |
399
+ | **[dsh-industry-research](https://github.com/PerryLink/dsh-industry-research)** | |
400
+ | **[dsh-lawcite-adapter](https://github.com/PerryLink/dsh-lawcite-adapter)** | |
401
+ | **[dsh-laya](https://github.com/PerryLink/dsh-laya)** | |
402
+ | **[dsh-lc-doc-check](https://github.com/PerryLink/dsh-lc-doc-check)** | |
403
+ | **[dsh-learning-gap-check](https://github.com/PerryLink/dsh-learning-gap-check)** | |
404
+ | **[dsh-library](https://github.com/PerryLink/dsh-library)** | |
405
+ | **[dsh-local-ai](https://github.com/PerryLink/dsh-local-ai)** | |
406
+ | **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** | |
407
+ | **[dsh-mask](https://github.com/PerryLink/dsh-mask)** | |
408
+ | **[dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel)** | |
409
+ | **[dsh-medrec-qc](https://github.com/PerryLink/dsh-medrec-qc)** | |
410
+ | **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | |
411
+ | **[dsh-nsfc-form-check](https://github.com/PerryLink/dsh-nsfc-form-check)** | |
412
+ | **[dsh-nurse-record-check](https://github.com/PerryLink/dsh-nurse-record-check)** | |
413
+ | **[dsh-observe](https://github.com/PerryLink/dsh-observe)** | |
414
+ | **[dsh-origin-rvc-check](https://github.com/PerryLink/dsh-origin-rvc-check)** | |
415
+ | **[dsh-ota-review-check](https://github.com/PerryLink/dsh-ota-review-check)** | |
416
+ | **[dsh-output-styles](https://github.com/PerryLink/dsh-output-styles)** | |
417
+ | **[dsh-paper-doc-adapter](https://github.com/PerryLink/dsh-paper-doc-adapter)** | |
418
+ | **[dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules)** | |
419
+ | **[dsh-permit-report-check](https://github.com/PerryLink/dsh-permit-report-check)** | |
420
+ | **[dsh-pipeline-check](https://github.com/PerryLink/dsh-pipeline-check)** | |
421
+ | **[dsh-pleading-draft](https://github.com/PerryLink/dsh-pleading-draft)** | |
422
+ | **[dsh-plugin-doctor](https://github.com/PerryLink/dsh-plugin-doctor)** | 🚫 RETIRED (repo archived) |
423
+ | **[dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide)** | |
424
+ | **[dsh-plugin-kit](https://github.com/PerryLink/dsh-plugin-kit)** | 🚫 RETIRED (repo archived) |
425
+ | **[dsh-plugin-upgrade](https://github.com/PerryLink/dsh-plugin-upgrade)** | 🚫 RETIRED (repo archived) |
426
+ | **[dsh-policy-brief-draft](https://github.com/PerryLink/dsh-policy-brief-draft)** | |
427
+ | **[dsh-power-loss-split](https://github.com/PerryLink/dsh-power-loss-split)** | |
428
+ | **[dsh-power-ticket-check](https://github.com/PerryLink/dsh-power-ticket-check)** | |
429
+ | **[dsh-ppap-check](https://github.com/PerryLink/dsh-ppap-check)** | |
430
+ | **[dsh-protest-deadline](https://github.com/PerryLink/dsh-protest-deadline)** | |
431
+ | **[dsh-railway-window](https://github.com/PerryLink/dsh-railway-window)** | |
432
+ | **[dsh-repair-order-qc](https://github.com/PerryLink/dsh-repair-order-qc)** | |
433
+ | **[dsh-research-report](https://github.com/PerryLink/dsh-research-report)** | |
434
+ | **[dsh-review-reply-check](https://github.com/PerryLink/dsh-review-reply-check)** | |
435
+ | **[dsh-rulefile-check](https://github.com/PerryLink/dsh-rulefile-check)** | |
436
+ | **[dsh-safety-brief-check](https://github.com/PerryLink/dsh-safety-brief-check)** | |
437
+ | **[dsh-score](https://github.com/PerryLink/dsh-score)** | |
438
+ | **[dsh-session-sync](https://github.com/PerryLink/dsh-session-sync)** | |
439
+ | **[dsh-site-log-check](https://github.com/PerryLink/dsh-site-log-check)** | |
440
+ | **[dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security)** | |
441
+ | **[dsh-soe-decision-check](https://github.com/PerryLink/dsh-soe-decision-check)** | |
442
+ | **[dsh-soilwater-check](https://github.com/PerryLink/dsh-soilwater-check)** | |
443
+ | **[dsh-sop-sync-check](https://github.com/PerryLink/dsh-sop-sync-check)** | |
444
+ | **[dsh-spc-gbt-adapter](https://github.com/PerryLink/dsh-spc-gbt-adapter)** | |
445
+ | **[dsh-talk](https://github.com/PerryLink/dsh-talk)** | |
446
+ | **[dsh-tender-extract](https://github.com/PerryLink/dsh-tender-extract)** | |
447
+ | **[dsh-tender-matrix](https://github.com/PerryLink/dsh-tender-matrix)** | |
448
+ | **[dsh-test-drive](https://github.com/PerryLink/dsh-test-drive)** | |
449
+ | **[dsh-ticktick](https://github.com/PerryLink/dsh-ticktick)** | 🚫 RETIRED (repo archived) |
450
+ | **[dsh-translate](https://github.com/PerryLink/dsh-translate)** | |
451
+ | **[dsh-warranty-calc](https://github.com/PerryLink/dsh-warranty-calc)** | |
452
+ | **[dsh-budget](https://github.com/PerryLink/dsh-budget)** | 🧊 FROZEN — see the repo README |
453
+ | **[dsh-claude-move](https://github.com/PerryLink/dsh-claude-move)** | 🧊 FROZEN — see the repo README |
454
+ | **[dsh-defend](https://github.com/PerryLink/dsh-defend)** | 🧊 FROZEN — see the repo README |
455
+ | **[dsh-draw](https://github.com/PerryLink/dsh-draw)** | 🧊 FROZEN — see the repo README |
456
+ | **[dsh-reach](https://github.com/PerryLink/dsh-reach)** | 🧊 FROZEN — see the repo README |
457
+ | **[dsh-background-agents](https://github.com/PerryLink/dsh-background-agents)** | 🚫 RETIRED (repo archived) |
458
+ | **[dsh-session-pin](https://github.com/PerryLink/dsh-session-pin)** | 🚫 RETIRED (repo archived) |
459
+ | **[dsh-team-rooms](https://github.com/PerryLink/dsh-team-rooms)** | 🚫 RETIRED (repo archived) |
460
+
461
+ </details>
462
+
463
+ ## License
464
+
465
+ [LICENSE](LICENSE) (Apache License 2.0) © 2026 dsh-research-report contributors
466
+
467
+ <p align="center"><sub>Apache-2.0 · Community plugin, not affiliated with DeepSeek.</sub></p>