dsh-composition-doctor 0.2.2 → 0.4.0
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 +47 -28
- package/README.md +179 -74
- package/README.zh.md +179 -74
- package/dist/cli/main.js +199 -5
- package/dist/client/report-view.js +186 -1
- package/dist/client.js +211 -2
- package/dist/core/bundle-inventory.js +9 -6
- package/dist/core/composition-provenance.js +211 -0
- package/dist/core/dsh-dump-parser.js +5 -2
- package/dist/core/failure-explainer.js +205 -0
- package/dist/core/failure-profile.js +110 -0
- package/dist/core/package-provenance.js +4 -0
- package/dist/core/preflight/npm-artifact.js +18 -2
- package/dist/core/rules.js +24 -4
- package/dist/core/snapshot.js +1 -1
- package/dist/reports/failure.js +23 -0
- package/dist/reports/markdown.js +3 -1
- package/dist/reports/schema.js +67 -0
- package/package.json +5 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,28 +1,47 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
## 0.
|
|
4
|
-
|
|
5
|
-
-
|
|
6
|
-
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.4.0 — Failure Explainer (unreleased RC)
|
|
4
|
+
|
|
5
|
+
- Add `diagnose` and the small `check` alias: human-first explanations connect supported symptoms to entities, independent source paths, evidence boundaries and manual next steps.
|
|
6
|
+
- Add a pure failure matcher/explainer shared with additive report/Web data. Default diagnosis inspects selected static metadata without running DSH, importing plugins or accessing the network. Public composed evidence remains opt-in.
|
|
7
|
+
- Support duplicate loader declarations, unavailable bundles, missing/invalid patches, unmatched targets, DSH-family peer/version mismatches and config replacement/override explanations. Normal updates and patch provenance chains are never treated as duplicate insertions.
|
|
8
|
+
- Accept bounded, untrusted file/stdin error logs; never store raw lines or treat log-reported versions as trusted runtime facts. Refuse secret/workspace/session/chat files and profile-mutating report destinations.
|
|
9
|
+
- Add minimized public failure regressions, synchronized bilingual onboarding, two demos, release/discussion drafts and a 25-second terminal recording script.
|
|
10
|
+
- Recheck the current npm DSH release (`0.2.0-rc.2`) with the public composition harness. Extend CI to Windows/Ubuntu and Node 20/22/24, including packed fresh-install smoke. Runtime execution remains not-run.
|
|
11
|
+
- Correct snapshot producer version metadata and preserve graph identities for same-layer duplicate declarations.
|
|
12
|
+
- Fix the installed Unix CLI launcher and an identical-artifact concurrent cache publication race exposed by Windows RC verification.
|
|
13
|
+
|
|
14
|
+
No npm publish, tag, GitHub Release or Discussion has been created.
|
|
15
|
+
|
|
16
|
+
## 0.3.0
|
|
17
|
+
|
|
18
|
+
- Add read-only `why row` and bounded `impact bundle` explanations using shared, versioned composition facts.
|
|
19
|
+
- Extend reports and Web Settings with a redacted bundle/source/layer/row provenance graph; older reports remain readable without the graph.
|
|
20
|
+
- Keep field ownership, removed config keys, route/slot ownership, runtime hook ownership, arbitrary dependencies, and possible dependents unknown unless directly observed.
|
|
21
|
+
|
|
22
|
+
## 0.2.2
|
|
23
|
+
|
|
24
|
+
- Fixed the packaged `dsh-doctor` CLI entrypoint when pnpm's Windows shim supplies a non-canonical path.
|
|
25
|
+
- Added a built-entrypoint regression test covering `--version` and `--help`.
|
|
26
|
+
|
|
27
|
+
## 0.2.1
|
|
28
|
+
|
|
29
|
+
- Fixed clean-checkout CI coverage by tracking the report schema and committed fixture packages that were previously hidden by broad ignore rules.
|
|
30
|
+
- Fixed cross-platform Snapshot v2 path normalization for Windows-style paths on Linux CI.
|
|
31
|
+
- Added the dsh-plugin.org listing badge to the bilingual README files.
|
|
32
|
+
|
|
33
|
+
## 0.2.0
|
|
34
|
+
|
|
35
|
+
- Release the verified 0.2.0 package without changing the established diagnostic architecture or evidence boundaries.
|
|
36
|
+
|
|
37
|
+
## 0.1.3
|
|
38
|
+
|
|
39
|
+
- Hardened the release package contract with the `dsh-doctor` binary entry.
|
|
40
|
+
- Added packed-package verification coverage and documented scan exit-code thresholds.
|
|
41
|
+
- Hardened npm artifact cache writes with integrity metadata and atomic temporary-file publication.
|
|
42
|
+
- Reject unsafe tar paths and link entries before reading package metadata.
|
|
43
|
+
- Kept DSH compatibility verified only for `0.1.5-rc.1` and `0.1.5-rc.2`; `0.1.6-alpha.1` remains expected-compatible only.
|
|
44
|
+
- Runtime smoke remains `not-run` unless a trusted OS-level isolation backend is available.
|
|
45
|
+
- Two Windows symlink regressions may remain `skipped` when the test process cannot create file symlinks; this is not a compatibility PASS.
|
|
46
|
+
- `0.1.6-alpha.1` is experimental/expected-compatible and is not part of the verified release range.
|
|
47
|
+
- A temporary directory is not a security sandbox; no runtime safety claim is made from temporary-directory execution.
|
package/README.md
CHANGED
|
@@ -1,74 +1,179 @@
|
|
|
1
|
-
# dsh-composition-doctor
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/dsh-composition-doctor)
|
|
4
|
-
[](https://github.com/lemonxiny55/dsh-composition-doctor/actions/workflows/ci.yml)
|
|
5
|
-
[](https://dsh-plugin.org/plugins/lemonxiny55/dsh-composition-doctor)
|
|
6
|
-
|
|
7
|
-
English | [中文](README.zh.md)
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
dsh-doctor
|
|
49
|
-
dsh-doctor
|
|
50
|
-
dsh-doctor
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
1
|
+
# dsh-composition-doctor
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/dsh-composition-doctor)
|
|
4
|
+
[](https://github.com/lemonxiny55/dsh-composition-doctor/actions/workflows/ci.yml)
|
|
5
|
+
[](https://dsh-plugin.org/plugins/lemonxiny55/dsh-composition-doctor)
|
|
6
|
+
|
|
7
|
+
English | [中文](README.zh.md)
|
|
8
|
+
|
|
9
|
+
> **DSH failed after installing or upgrading a plugin?**
|
|
10
|
+
>
|
|
11
|
+
> Find which bundle, profile layer, or override is involved—and what the evidence actually proves.
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
dsh-doctor diagnose --profile ./web --log dsh-error.log
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
Duplicate loader entry id: session-cleaner
|
|
19
|
+
reported-by-log; evidence: static
|
|
20
|
+
|
|
21
|
+
Cause: session-cleaner is introduced by 2 separate loader declarations.
|
|
22
|
+
|
|
23
|
+
Path 1: bundle session-cleaner → <PROFILE>/node_modules/session-cleaner/cordis.patch.yml
|
|
24
|
+
layer: dsh.profile.bundles[0]: session-cleaner → row: session-cleaner
|
|
25
|
+
Path 2: cordis.patch.yml
|
|
26
|
+
layer: cordis.patch.yml → row: session-cleaner
|
|
27
|
+
|
|
28
|
+
Unknown: runtime not observed / not-run; final composition unknown.
|
|
29
|
+
Doctor did not modify your profile.
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Excerpt from a minimized [public duplicate-loading case](https://github.com/deepseek-ai/deepseek-harness/discussions/2889). Static declarations expose the conflicting paths; they do not prove a runtime crash. [Full demos and sources](docs/failure-cases.md) · [25-second terminal demo](scripts/failure-demo.mjs)
|
|
33
|
+
|
|
34
|
+
**Explain failures · Trace composition provenance · Preview upgrade risks**
|
|
35
|
+
|
|
36
|
+
**Read-only · Offline by default · No automatic fixes or installs**
|
|
37
|
+
|
|
38
|
+
For [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`). One command connects a supported failure to its entity, observable source paths and a manual next step. Missing evidence stays unknown.
|
|
39
|
+
|
|
40
|
+
## Quick start
|
|
41
|
+
|
|
42
|
+
**0.4.0 is a local release candidate, not yet published.** The public 0.3.0 package does not have `diagnose`. Build this checkout and install the reviewed tarball locally:
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
pnpm install --frozen-lockfile
|
|
46
|
+
pnpm build
|
|
47
|
+
pnpm pack
|
|
48
|
+
pnpm add -g ./dsh-composition-doctor-0.4.0.tgz --ignore-scripts
|
|
49
|
+
dsh-doctor check --profile ./web
|
|
50
|
+
dsh-doctor diagnose --profile ./web --log dsh-error.log
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
`--profile` is an explicit directory, not a DSH profile nickname. For the standard Web profile, use `~/.dsh/profiles/web` (PowerShell: `$HOME/.dsh/profiles/web`). CLI use needs no running Web UI or plugin installation. To use the Web Explorer, add the reviewed local tarball through DSH's plugin command, then opt in to publishing reports to its configured Doctor report directory.
|
|
54
|
+
|
|
55
|
+
Pipes and structured output work too:
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
dsh web 2>&1 | dsh-doctor diagnose --profile ./web
|
|
59
|
+
dsh-doctor diagnose --profile ./web --log - --format json
|
|
60
|
+
dsh-doctor diagnose --profile ./web --format markdown
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Default `diagnose`/`check` inspect static metadata without starting DSH, importing plugin code, running lifecycle scripts or accessing the network. `check` is a small alias for the same reader and requires the same explicit profile. JSON returns the versioned explanation result; `--output <dir>` or `--report-dir <dir>` writes a compatible analysis report with `failureExplanation` and `compositionFacts` plus Markdown. Output directories must be outside the profile. No report is written by default.
|
|
64
|
+
|
|
65
|
+
Then inspect a specific source:
|
|
66
|
+
|
|
67
|
+
```powershell
|
|
68
|
+
dsh-doctor why row tool-bash --profile C:\path\to\profile
|
|
69
|
+
dsh-doctor impact bundle @example/dsh-bundle --profile C:\path\to\profile
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
`why` explains one observed row and its source chain. `impact bundle` lists rows and diagnostics directly associated with that bundle source.
|
|
73
|
+
|
|
74
|
+
```mermaid
|
|
75
|
+
flowchart LR
|
|
76
|
+
B["Bundle<br/>direct association"] --> S["Source"]
|
|
77
|
+
S -->|"introduced / patched-by"| R["Row"]
|
|
78
|
+
L["Layer"] -->|"contains"| R
|
|
79
|
+
R -->|"diagnosed-by"| D["Diagnostic"]
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
These links appear only when the report has supporting facts; missing ownership is left unknown.
|
|
83
|
+
|
|
84
|
+
## Real failure examples
|
|
85
|
+
|
|
86
|
+
1. **A bundle plus a hand-written insertion.** [DSH Discussion #2889](https://github.com/deepseek-ai/deepseek-harness/discussions/2889) reports a plugin-management change that promotes dependencies into the bundle list while manual rows remain. Doctor's minimized regression connects `session-cleaner` to both insertion paths. Review the bundle declaration and manual patch together; a patch update is never counted as a second insertion.
|
|
87
|
+
2. **A package without its declared patch file.** [DSH Discussion #6539](https://github.com/deepseek-ai/deepseek-harness/discussions/6539) includes a report of the published `dsh-cad` package lacking its YAML overlay. The minimized fixture produces:
|
|
88
|
+
|
|
89
|
+
```text
|
|
90
|
+
Bundle patch is unavailable: dsh-cad
|
|
91
|
+
reported-by-log; evidence: static
|
|
92
|
+
|
|
93
|
+
Path 1: bundle dsh-cad → <PROFILE>/node_modules/dsh-cad/package.json
|
|
94
|
+
|
|
95
|
+
Next: Review the bundle manifest → dsh.bundle.patch and packaged YAML file.
|
|
96
|
+
Doctor did not modify your profile.
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
These are sanitized reconstructions of public failure patterns, not copies of users' profiles or a replay of their runtime. The suite also verifies that the same logs with no matching metadata remain `unknown`.
|
|
100
|
+
|
|
101
|
+
## Supported explanations
|
|
102
|
+
|
|
103
|
+
| Pattern | Observable basis | Boundary |
|
|
104
|
+
|---|---|---|
|
|
105
|
+
| Duplicate loader id | Separate `insert`/base-row declarations, or duplicate composed rows | A normal update or patched source chain is not another insertion; no runtime rejection is inferred. |
|
|
106
|
+
| Bundle unavailable | Declared bundle plus bounded local resolution finding | Built-in installation bundles and external links may resolve elsewhere. |
|
|
107
|
+
| Missing/invalid bundle patch | Manifest plus missing, invalid or disallowed declared YAML metadata | No file or command suggested by a log is followed. |
|
|
108
|
+
| Patch target missing | Target declaration with no local insertion, or a public dump finding | Home/CLI/built-in layers may still supply it. |
|
|
109
|
+
| Peer/version mismatch | Installed DSH-family peer range and independently selected `--dsh-version <exact>`; Node engine uses the actual Doctor process | Log-reported versions are not runtime facts; no compatible release is guessed. |
|
|
110
|
+
| Config replacement / override | Config patch declaration or composed provenance/replacement fact | Removed effective keys and field ownership stay unknown unless observed. |
|
|
111
|
+
|
|
112
|
+
Upgrade ownership changes use existing `snapshot`/`diff` and `preflight`; arbitrary route/slot/hook root causes are outside this version's failure patterns. `diagnose --composed` opts in to the existing isolated public dump adapter; it never installs packages, starts plugin runtime, or upgrades static declarations to composed evidence. Copied-profile/provider coverage can be incomplete, and runtime remains `not-observed`.
|
|
113
|
+
|
|
114
|
+
Logs are limited to 1 MiB; explicit files must be `.log`, `.txt` or `.out`. Secret, workspace, session and chat paths are refused. At most 32 log signatures and 50 metadata explanations are retained; truncation is indicated in JSON. Human output shows the first three explanations. Exit 0 means a report was produced (including `unknown`/`no-match`), not that DSH is healthy; operational failures return 1 and invalid arguments return 2.
|
|
115
|
+
|
|
116
|
+
[Commands](#what-it-explains) · [Evidence boundaries](#reports-and-evidence-boundaries) · [Safety & privacy](#safety-and-privacy) · [Compatibility](#support-and-limitations) · [Development](#development)
|
|
117
|
+
|
|
118
|
+
## What it explains
|
|
119
|
+
|
|
120
|
+
| Command | Purpose |
|
|
121
|
+
|---|---|
|
|
122
|
+
| `dsh-doctor diagnose` | Explain supported failures from selected metadata, optionally focused by an untrusted error log. Human-readable by default; JSON/Markdown are available. |
|
|
123
|
+
| `dsh-doctor check` | Inspect the explicitly selected profile with the same bounded reader and show how to diagnose a symptom. |
|
|
124
|
+
| `dsh-doctor scan` | Detect duplicate Cordis rows, hook-order risks, UI slot/route ownership conflicts, bundle overrides, peer/platform mismatches, and profile drift. |
|
|
125
|
+
| `dsh-doctor snapshot` | Create a redacted, comparable profile snapshot with lockfile hashes. |
|
|
126
|
+
| `dsh-doctor diff` | Summarize added/removed/upgraded plugins, rows, hooks, UI claims, peers, and platforms. |
|
|
127
|
+
| `dsh-doctor preflight` | Rehearse a target DSH upgrade in an isolated temporary profile. |
|
|
128
|
+
| `dsh-doctor why row <id>` | Explain one row from an explicitly selected profile using observed source/layer facts. |
|
|
129
|
+
| `dsh-doctor impact bundle <name>` | List rows and diagnostics directly associated with an observed bundle source. |
|
|
130
|
+
|
|
131
|
+
The `why` and `impact` commands require `--profile <dir>`. Reports include an optional, versioned, redacted `compositionFacts` section shared by these commands and the Web Composition Explorer. The Web Settings page remains display/export only: it reads the latest local report, shows diagnostic and composition graphs, and exports JSON/Markdown. It has no repair, install, or uninstall action.
|
|
132
|
+
|
|
133
|
+
Composition facts describe the structure returned by the public `--dump-config` command or static declarations when that is unavailable. `introduced` and `patched-by` edges describe the source chain recorded by DSH; they do not prove per-field ownership. If earlier config keys are not available, removed keys and field owners remain unknown. Route/slot ownership, runtime hook ownership, arbitrary dependencies, and possible dependents are reported as not observed/not modelled.
|
|
134
|
+
|
|
135
|
+
## Reports and evidence boundaries
|
|
136
|
+
|
|
137
|
+
`scan --output <dir>` writes only to the requested directory. To make the same report visible to the read-only Settings page, opt in explicitly: `--publish` copies it to the default plugin directory `.dsh-composition-doctor/reports`, while `--report-dir <dir>` publishes to a configured plugin directory. Use `--format both` so the Web route has `report.json` and Markdown remains exportable. Do not use a profile directory, `.env` location, or any directory containing keys, tokens, or other secrets as a report directory.
|
|
138
|
+
|
|
139
|
+
Reports declare `evidenceMode`: `static` means allow-listed manifest/patch/package metadata only; `composed` means a public `dsh --profile <name> --dump-config` command returned a composition result; `runtime-observed` is reserved for a successful isolated runtime observation backend; and `mixed` is reserved for an adapter that supplies both. `dump-config` never proves runtime execution, including when a `!!js` or other runtime-dependent value is present. Static findings and bounded metadata coverage are not proof of the final runtime composition. If no compatible public DSH CLI is available, scan falls back to static and records a warning. Reports written before evidence schema 2 may still be read as legacy `resolved`, but new reports never emit that label.
|
|
140
|
+
|
|
141
|
+
`preflight --candidate package@version` records a validated exact reference in an isolated temporary `package.json`. Target artifact discovery is local-first (`--dsh-bin`, package directory, tarball, installed `dsh`, `--package-manager-cache`, then Doctor-owned cache); registry access is allowed only with explicit `--online`. Online resolution downloads exact registry tarballs into Doctor-owned cache, records source/version/integrity/hash, and never installs or runs lifecycle scripts. `--allow-build` does not grant permission to execute third-party runtime code.
|
|
142
|
+
|
|
143
|
+
`scan --fail-on never|info|warning|error` controls the scan exit code. The default is `never`: warnings and errors remain in the report without changing the exit code. `info` fails on any diagnostic, `warning` fails on warnings or errors, and `error` fails only on errors. Malformed arguments return exit code 2; operational failures return 1.
|
|
144
|
+
|
|
145
|
+
After changing a profile, restart the Web UI (`npx @deepseek-ai/dsh web`) before scanning it again.
|
|
146
|
+
|
|
147
|
+
Each finding is `info`, `warning`, or `error` and includes evidence, explanation, and the smallest remediation. `runtimeSmoke.status=not-run` is not a runtime PASS; `artifact-unavailable` is not `incompatible`; and a warning is not a confirmed failure.
|
|
148
|
+
|
|
149
|
+
## More commands
|
|
150
|
+
|
|
151
|
+
```powershell
|
|
152
|
+
dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\profile --publish
|
|
153
|
+
dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\archive --report-dir C:\safe\doctor-reports
|
|
154
|
+
dsh-doctor snapshot --profile C:\path\to\profile --output .\reports\before.json
|
|
155
|
+
dsh-doctor diff --before .\reports\before.json --after .\reports\after.json --format both
|
|
156
|
+
dsh-doctor preflight --profile C:\path\to\profile --target-dsh 0.1.5-rc.2
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## Safety and privacy
|
|
160
|
+
|
|
161
|
+
Default operations are read-only or isolated under the OS temporary directory. The plugin does not modify profiles, install/remove plugins, migrate configuration, escalate permissions, or perform network I/O by default. It never reads `.env`, profile secrets, session bodies, or workspace file contents, and does not collect or persist arbitrary environment-variable values. Public CLI execution receives only the minimal process-routing variables required by the host platform.
|
|
162
|
+
|
|
163
|
+
## Support and limitations
|
|
164
|
+
|
|
165
|
+
On 2026-10-03 the npm `latest` release was checked as `@deepseek-ai/dsh@0.2.0-rc.2`; its public `--version`/`--dump-config` harness was rerun on Windows and Ubuntu 24.04 (WSL) + Node.js 24.19.0. Doctor's full RC gates and packed fresh-install smoke passed locally on Windows/Node 24 and Ubuntu/Node 20.19.5 and 24.19.0. On 2026-10-04, [Hosted CI passed all six Windows/Ubuntu × Node 20/22/24 jobs](https://github.com/lemonxiny55/dsh-composition-doctor/actions/runs/37187050083), including packed fresh-install smoke; the current DSH public harness passed on both Node 24 jobs. Older `0.1.5-rc.1`/`rc.2` goldens are historical evidence; their real-artifact tests skip when artifacts are unavailable. `0.2.1-alpha.1` is expected-compatible/experimental, not verified. Doctor supports Node.js `>=20`. This does not claim that every third-party plugin works, or that plugin runtime/UI registration was observed. [Compatibility detail](docs/compatibility.md) · [RC verification record](docs/release-evidence/0.4.0.md).
|
|
166
|
+
|
|
167
|
+
## Development
|
|
168
|
+
|
|
169
|
+
```powershell
|
|
170
|
+
pnpm test
|
|
171
|
+
pnpm typecheck
|
|
172
|
+
pnpm build
|
|
173
|
+
pnpm pack
|
|
174
|
+
pnpm smoke:pack ./dsh-composition-doctor-0.4.0.tgz
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
For checkout-only development, run the CLI with `node dist/cli/main.js` after building.
|
|
178
|
+
|
|
179
|
+
See [`README.zh.md`](README.zh.md), [`docs/compatibility.md`](docs/compatibility.md), and [`docs/examples/scan-report.md`](docs/examples/scan-report.md). MIT licensed.
|
package/README.zh.md
CHANGED
|
@@ -1,74 +1,179 @@
|
|
|
1
|
-
# dsh-composition-doctor（中文）
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/dsh-composition-doctor)
|
|
4
|
-
[](https://github.com/lemonxiny55/dsh-composition-doctor/actions/workflows/ci.yml)
|
|
5
|
-
[](https://dsh-plugin.org/plugins/lemonxiny55/dsh-composition-doctor)
|
|
6
|
-
|
|
7
|
-
[English](README.md) | 中文
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
dsh-doctor
|
|
49
|
-
dsh-doctor
|
|
50
|
-
dsh-doctor
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
1
|
+
# dsh-composition-doctor（中文）
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/dsh-composition-doctor)
|
|
4
|
+
[](https://github.com/lemonxiny55/dsh-composition-doctor/actions/workflows/ci.yml)
|
|
5
|
+
[](https://dsh-plugin.org/plugins/lemonxiny55/dsh-composition-doctor)
|
|
6
|
+
|
|
7
|
+
[English](README.md) | 中文
|
|
8
|
+
|
|
9
|
+
> **安装或升级插件后，DSH 启动失败了？**
|
|
10
|
+
>
|
|
11
|
+
> 找出涉及哪个 bundle、profile layer 或 override，并看清现有证据究竟能证明什么。
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
dsh-doctor diagnose --profile ./web --log dsh-error.log
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
```text
|
|
18
|
+
Duplicate loader entry id: session-cleaner
|
|
19
|
+
reported-by-log; evidence: static
|
|
20
|
+
|
|
21
|
+
Cause: session-cleaner is introduced by 2 separate loader declarations.
|
|
22
|
+
|
|
23
|
+
Path 1: bundle session-cleaner → <PROFILE>/node_modules/session-cleaner/cordis.patch.yml
|
|
24
|
+
layer: dsh.profile.bundles[0]: session-cleaner → row: session-cleaner
|
|
25
|
+
Path 2: cordis.patch.yml
|
|
26
|
+
layer: cordis.patch.yml → row: session-cleaner
|
|
27
|
+
|
|
28
|
+
Unknown: runtime not observed / not-run; final composition unknown.
|
|
29
|
+
Doctor did not modify your profile.
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
来自最小化的[公开重复加载案例](https://github.com/deepseek-ai/deepseek-harness/discussions/2889)的输出摘录。静态声明能指出冲突路径，不能证明 runtime 已崩溃。[完整 Demo 与来源](docs/failure-cases.md) · [25 秒终端 Demo](scripts/failure-demo.mjs)
|
|
33
|
+
|
|
34
|
+
**解释故障 · 追踪组合来源 · 预检升级风险**
|
|
35
|
+
|
|
36
|
+
**只读 · 默认离线 · 不自动修复或安装**
|
|
37
|
+
|
|
38
|
+
面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）。一条命令把已支持的故障关联到实体、可观察的来源路径和人工下一步；没有证据的部分保留 unknown。
|
|
39
|
+
|
|
40
|
+
## 快速开始
|
|
41
|
+
|
|
42
|
+
**0.4.0 目前为本地 RC，尚未发布。** 公开的 0.3.0 没有 `diagnose`。请从本 checkout 构建，并安装审查后的本地 tarball：
|
|
43
|
+
|
|
44
|
+
```sh
|
|
45
|
+
pnpm install --frozen-lockfile
|
|
46
|
+
pnpm build
|
|
47
|
+
pnpm pack
|
|
48
|
+
pnpm add -g ./dsh-composition-doctor-0.4.0.tgz --ignore-scripts
|
|
49
|
+
dsh-doctor check --profile ./web
|
|
50
|
+
dsh-doctor diagnose --profile ./web --log dsh-error.log
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
`--profile` 接受明确的目录，而不是 DSH profile 昵称。标准 Web profile 可使用 `~/.dsh/profiles/web`，PowerShell 中使用 `$HOME/.dsh/profiles/web`。CLI 不需要 Web UI 正常启动，也不需要安装 host 插件。需要 Web Explorer 时，通过 DSH plugin 命令添加审查后的本地 tarball，再显式导出到插件配置的 Doctor 报告目录。
|
|
54
|
+
|
|
55
|
+
支持管道和结构化输出：
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
dsh web 2>&1 | dsh-doctor diagnose --profile ./web
|
|
59
|
+
dsh-doctor diagnose --profile ./web --log - --format json
|
|
60
|
+
dsh-doctor diagnose --profile ./web --format markdown
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
默认 `diagnose`/`check` 只读取静态元数据，不启动 DSH、不导入插件代码、不执行 lifecycle script、不访问网络。`check` 是复用相同 reader 的极简别名，同样需要明确指定 profile。JSON 返回版本化的 explanation；`--output <目录>` 或 `--report-dir <目录>` 写入含 `failureExplanation` 和 `compositionFacts` 的兼容分析报告及 Markdown。输出目录必须位于 profile 外；默认不写报告。
|
|
64
|
+
|
|
65
|
+
继续追踪具体来源：
|
|
66
|
+
|
|
67
|
+
```powershell
|
|
68
|
+
dsh-doctor why row tool-bash --profile C:\path\to\profile
|
|
69
|
+
dsh-doctor impact bundle @example/dsh-bundle --profile C:\path\to\profile
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
`why` 解释一个可观察 row 的来源链；`impact bundle` 列出有直接 source 关联证据的 rows 和 diagnostics。
|
|
73
|
+
|
|
74
|
+
```mermaid
|
|
75
|
+
flowchart LR
|
|
76
|
+
B["Bundle<br/>直接关联"] --> S["Source"]
|
|
77
|
+
S -->|"introduced / patched-by"| R["Row"]
|
|
78
|
+
L["Layer"] -->|"contains"| R
|
|
79
|
+
R -->|"diagnosed-by"| D["Diagnostic"]
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
只有报告中存在支持 facts 时才展示这些关系；没有 ownership 证据的部分仍标为 unknown。
|
|
83
|
+
|
|
84
|
+
## 真实故障案例
|
|
85
|
+
|
|
86
|
+
1. **bundle 与手写 insert 重复加载。** [DSH Discussion #2889](https://github.com/deepseek-ai/deepseek-harness/discussions/2889) 报告了插件管理把依赖加入 bundle 列表，而旧手写 row 仍然存在的情况。最小化回归把 `session-cleaner` 关联到两条 insert 路径。应一起检查 bundle 声明和手写 patch；普通 patch update 不会被算成第二次引入。
|
|
87
|
+
2. **已安装包缺少它声明的 patch。** [DSH Discussion #6539](https://github.com/deepseek-ai/deepseek-harness/discussions/6539) 的评论报告了 npm `dsh-cad` 缺少 YAML overlay。最小化 fixture 的输出摘录：
|
|
88
|
+
|
|
89
|
+
```text
|
|
90
|
+
Bundle patch is unavailable: dsh-cad
|
|
91
|
+
reported-by-log; evidence: static
|
|
92
|
+
|
|
93
|
+
Path 1: bundle dsh-cad → <PROFILE>/node_modules/dsh-cad/package.json
|
|
94
|
+
|
|
95
|
+
Next: Review the bundle manifest → dsh.bundle.patch and packaged YAML file.
|
|
96
|
+
Doctor did not modify your profile.
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
这些是公开故障模式的脱敏结构重建，不是用户 profile 原件，也不声称重放了现场 runtime。同一日志缺少匹配元数据时，测试要求返回 `unknown`。
|
|
100
|
+
|
|
101
|
+
## 支持的解释
|
|
102
|
+
|
|
103
|
+
| 模式 | 可观察依据 | 边界 |
|
|
104
|
+
|---|---|---|
|
|
105
|
+
| duplicate loader id | 独立 insert/base-row 声明，或 composed tree 中重复 row | 普通 update、patched source chain 不算第二次插入，不推断 runtime 已拒绝。 |
|
|
106
|
+
| bundle 不可解析 | profile 声明及有边界的本地解析 finding | 安装级内置 bundle、外部 link 可能在其他位置可解析。 |
|
|
107
|
+
| bundle patch 缺失/无效 | manifest 与缺失、无效或不允许读取的 YAML | 不跟随日志建议的文件或命令。 |
|
|
108
|
+
| patch target 缺失 | patch target 没有本地 insert，或公开 dump finding | home/CLI/内置 layer 可能仍提供该 row。 |
|
|
109
|
+
| peer/version 不兼容 | 已安装 DSH-family peer range 与独立指定的 `--dsh-version <精确版本>`；Node engine 使用 Doctor 当前进程版本 | 日志中的版本不是 runtime fact，不猜测可用插件版本。 |
|
|
110
|
+
| config replacement/override | config patch 声明、composed provenance/replacement fact | 未观察到的有效键丢失、字段 owner 保持 unknown。 |
|
|
111
|
+
|
|
112
|
+
升级后的 ownership 变化继续通过 `snapshot`/`diff`、`preflight` 检查；任意 route/slot/hook 根因不进入本版 pattern。`diagnose --composed` 显式启用既有的隔离公开 dump adapter，不安装包、不启动插件 runtime、不把静态声明升级为 composed evidence。复制 profile/provider 的覆盖可能不完整，runtime 仍是 `not-observed`。
|
|
113
|
+
|
|
114
|
+
日志限制 1 MiB；显式文件只接受 `.log`、`.txt`、`.out`，拒绝 secret、workspace、session、chat 路径。最多保留 32 个日志 signature 和 50 条元数据解释；JSON 标明截断，人类输出默认显示前三条。退出 0 表示生成了报告，包括 `unknown`/`no-match`，不表示 DSH 健康；执行失败返回 1，参数错误返回 2。
|
|
115
|
+
|
|
116
|
+
[命令能力](#模型可解释什么) · [证据边界](#报告与证据边界) · [安全与隐私](#安全与隐私) · [兼容范围](#支持范围与限制) · [开发](#开发)
|
|
117
|
+
|
|
118
|
+
## 模型可解释什么
|
|
119
|
+
|
|
120
|
+
| 命令 | 作用 |
|
|
121
|
+
|---|---|
|
|
122
|
+
| `dsh-doctor diagnose` | 从明确选择的元数据解释支持的故障，可用不可信日志聚焦。默认人类可读，支持 JSON/Markdown。 |
|
|
123
|
+
| `dsh-doctor check` | 使用同一有边界的 reader 检查明确指定的 profile，并提示如何进一步 diagnose。 |
|
|
124
|
+
| `dsh-doctor scan` | 检测重复 Cordis row、hook 顺序风险、UI slot/route 所有权冲突、bundle 覆盖、peer/platform 不匹配和 profile 漂移。 |
|
|
125
|
+
| `dsh-doctor snapshot` | 生成脱敏、可比较的 profile 快照及 lockfile 哈希。 |
|
|
126
|
+
| `dsh-doctor diff` | 汇总新增、删除或升级的插件，以及 rows、hooks、UI 声明、peer 和平台变化。 |
|
|
127
|
+
| `dsh-doctor preflight` | 在独立临时 profile 中演练目标 DSH 升级。 |
|
|
128
|
+
| `dsh-doctor why row <id>` | 基于明确指定的 profile 中可观察的来源和 layer 信息解释一个 row。 |
|
|
129
|
+
| `dsh-doctor impact bundle <name>` | 列出有直接来源关联证据的 bundle rows 和 diagnostics。 |
|
|
130
|
+
|
|
131
|
+
`why` 和 `impact` 都需要 `--profile <目录>`。报告新增可选、版本化且脱敏的 `compositionFacts`，由这两个命令和 Web Composition Explorer 共用。Web Settings 仍然只读：它读取最新本地报告，展示诊断图和 composition 图，并导出 JSON/Markdown；不提供修复、安装或卸载操作。
|
|
132
|
+
|
|
133
|
+
Composition facts 描述公开 `--dump-config` 返回的结构；无法取得时仅描述静态声明。`introduced` 和 `patched-by` 表示 DSH 输出中记录的来源链，不证明逐字段 owner。若未观察到前层 config key，移除的键和字段 owner 必须是 unknown。route/slot ownership、runtime hook ownership、任意依赖和可能的 dependents 会标记为未观察/未建模。
|
|
134
|
+
|
|
135
|
+
## 报告与证据边界
|
|
136
|
+
|
|
137
|
+
`scan --output <目录>` 只写入显式指定的目录。要让只读 Settings 页面看到同一份报告，必须显式选择 `--publish`，它会复制到默认插件目录 `.dsh-composition-doctor/reports`；也可以使用 `--report-dir <目录>` 发布到配置的插件报告目录。请使用 `--format both`，使 Web route 能读取 `report.json`，同时保留 Markdown 导出。报告目录不能是 profile、`.env` 所在位置，或任何含密钥、token 或其他敏感信息的目录。
|
|
138
|
+
|
|
139
|
+
报告中的 `evidenceMode` 标明证据来源：`static` 仅表示 allow-list 中的 manifest、patch、package metadata 等静态证据；`composed` 表示公开 `dsh --profile <name> --dump-config` 返回了 composition 结果；`runtime-observed` 只允许真正启动隔离 runtime 并观察到注册/行为的后端使用；`mixed` 预留给同时提供多类来源的适配器。`dump-config` 即使成功，也不代表 runtime 已验证；存在 `!!js` 等运行时依赖时尤其如此。找不到兼容的公开 DSH CLI 时会回退到 static，并明确报告 warning。旧的 evidence schema 2 之前报告仍可按 legacy `resolved` 读取，但新报告不会再输出该标签。
|
|
140
|
+
|
|
141
|
+
`preflight --candidate package@version` 只会把通过校验的精确引用记录到隔离临时 `package.json`。目标 artifact 默认按本地优先顺序查找：`--dsh-bin`、本地 package directory、本地 tarball、已安装 `dsh`、`--package-manager-cache`、Doctor 自己的 cache；只有显式 `--online` 才允许访问 registry。在线解析会把精确 tarball 写入 Doctor 自己的 cache，记录来源、版本、integrity 和 hash，并且不会安装或执行 lifecycle script。`--allow-build` 不等于允许执行第三方 runtime code。
|
|
142
|
+
|
|
143
|
+
`scan --fail-on never|info|warning|error` 控制 scan 的退出码。默认是 `never`：warning 和 error 会写入报告，但不改变退出码；`info` 遇到任意诊断时退出 1，`warning` 遇到 warning 或 error 时退出 1，`error` 只在 error 时退出 1。参数错误退出 2，执行失败退出 1。
|
|
144
|
+
|
|
145
|
+
更改 profile 后重启 Web UI（`npx @deepseek-ai/dsh web`），再重新扫描。
|
|
146
|
+
|
|
147
|
+
每条诊断均为 `info`、`warning` 或 `error`，并附带 evidence、explanation 和最小 remediation。`runtimeSmoke.status=not-run` 不等于 runtime PASS；`artifact-unavailable` 不等于 `incompatible`；warning 也不等于已确认失败。
|
|
148
|
+
|
|
149
|
+
## 更多命令
|
|
150
|
+
|
|
151
|
+
```powershell
|
|
152
|
+
dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\profile --publish
|
|
153
|
+
dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\archive --report-dir C:\safe\doctor-reports
|
|
154
|
+
dsh-doctor snapshot --profile C:\path\to\profile --output .\reports\before.json
|
|
155
|
+
dsh-doctor diff --before .\reports\before.json --after .\reports\after.json --format both
|
|
156
|
+
dsh-doctor preflight --profile C:\path\to\profile --target-dsh 0.1.5-rc.2
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## 安全与隐私
|
|
160
|
+
|
|
161
|
+
默认操作只读，或仅在操作系统临时目录中隔离运行。插件不会修改 profile、安装或删除插件、迁移配置、扩大权限，默认也不会执行网络 I/O。它不会读取 `.env`、profile 密钥、会话正文或工作区源文件内容，也不会收集或持久化任意环境变量值；启动公开 CLI 时只传递平台所需的最小进程路由变量。
|
|
162
|
+
|
|
163
|
+
## 支持范围与限制
|
|
164
|
+
|
|
165
|
+
2026-10-03 核对的 npm `latest` 为 `@deepseek-ai/dsh@0.2.0-rc.2`，已在 Windows 和 Ubuntu 24.04（WSL）+ Node.js 24.19.0 重新运行公开 `--version`/`--dump-config` harness。Doctor 的完整 RC 门槛与 packed fresh-install smoke 已在本地 Windows/Node 24、Ubuntu/Node 20.19.5 和 24.19.0 通过。2026-10-04，[Hosted CI 的 Windows/Ubuntu × Node 20/22/24 共六个作业全部通过](https://github.com/lemonxiny55/dsh-composition-doctor/actions/runs/37187050083)，包含 packed fresh-install smoke；两个 Node 24 作业均通过当前 DSH 公开 harness。`0.1.5-rc.1`/`rc.2` golden 仅作历史证据，没有 artifact 的测试会 skip。`0.2.1-alpha.1` 属于 expected-compatible/experimental，未验证。Doctor 支持 Node.js `>=20`。此声明不代表任意第三方插件可用，也不代表观察过插件 runtime/UI 注册。[兼容性细节](docs/compatibility.md) · [RC 验证记录](docs/release-evidence/0.4.0.md)。
|
|
166
|
+
|
|
167
|
+
## 开发
|
|
168
|
+
|
|
169
|
+
```powershell
|
|
170
|
+
pnpm test
|
|
171
|
+
pnpm typecheck
|
|
172
|
+
pnpm build
|
|
173
|
+
pnpm pack
|
|
174
|
+
pnpm smoke:pack ./dsh-composition-doctor-0.4.0.tgz
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
仅在 checkout 开发时，构建完成后使用 `node dist/cli/main.js` 运行 CLI。
|
|
178
|
+
|
|
179
|
+
参阅 [`README.md`](README.md)、[`docs/compatibility.md`](docs/compatibility.md) 和 [`docs/examples/scan-report.md`](docs/examples/scan-report.md)。MIT 许可。
|