@bruc3van/dsh-doctor 0.5.2 → 0.5.4
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/README.en.md
CHANGED
|
@@ -2,243 +2,244 @@
|
|
|
2
2
|
|
|
3
3
|
[中文](README.md) | English
|
|
4
4
|
|
|
5
|
-
DSH Doctor
|
|
5
|
+
DSH Doctor helps an agent diagnose and upgrade DeepSeek Harness plugins: identify API changes between releases, modify code where the migration is known, point out semantic changes that need developer judgment, then rebuild and verify the plugin.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
The current focus is:
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
Node.js `22.19+` or `24+` is required:
|
|
12
|
-
|
|
13
|
-
```sh
|
|
14
|
-
npm install --global @bruc3van/dsh-doctor
|
|
15
|
-
dsh-doctor diagnose
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
Or run without installing:
|
|
19
|
-
|
|
20
|
-
```sh
|
|
21
|
-
npx @bruc3van/dsh-doctor diagnose
|
|
9
|
+
```text
|
|
10
|
+
DSH 0.1.1 → DSH 0.1.2
|
|
22
11
|
```
|
|
23
12
|
|
|
24
|
-
The
|
|
13
|
+
The project also diagnoses DSH profiles and installed plugins, checks for compatible versions, and performs safety checks before quarantine or removal.
|
|
25
14
|
|
|
26
|
-
|
|
15
|
+
> This is a community-maintained third-party project, not an official DeepSeek project. The current catalog uses `dsh-v0.1.1-rc.2` and `dsh-v0.1.2-alpha.2` as the reference points for the 0.1.1-to-0.1.2 changes. An agent should still check actual differences when a plugin uses another patch or prerelease.
|
|
27
16
|
|
|
28
|
-
##
|
|
17
|
+
## Upgrade a plugin with the skill
|
|
29
18
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
Doctor ships a versioned `dsh-v0.1.1-rc.2 → dsh-v0.1.2-alpha.2` migration catalog and exposes three auditable stages:
|
|
19
|
+
Install the repository's [`dsh-plugin-upgrade`](skills/dsh-plugin-upgrade/SKILL.md) skill:
|
|
33
20
|
|
|
34
21
|
```sh
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
--from dsh-v0.1.1-rc.2 \
|
|
38
|
-
--to dsh-v0.1.2-alpha.2 \
|
|
39
|
-
--harness-root /path/to/deepseek-harness
|
|
22
|
+
npx skills add bruc3van/dsh-doctor
|
|
23
|
+
```
|
|
40
24
|
|
|
41
|
-
|
|
42
|
-
dsh-doctor migrate apply /path/to/plugin --safe \
|
|
43
|
-
--harness-root /path/to/deepseek-harness
|
|
44
|
-
dsh-doctor migrate apply /path/to/plugin --safe --yes \
|
|
45
|
-
--harness-root /path/to/deepseek-harness
|
|
25
|
+
Then ask the agent from inside the plugin repository:
|
|
46
26
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
dsh-doctor migrate verify /path/to/plugin --level build --yes \
|
|
51
|
-
--harness-root /path/to/deepseek-harness
|
|
52
|
-
dsh-doctor migrate verify /path/to/plugin --level runtime --yes \
|
|
53
|
-
--harness-root /path/to/deepseek-harness
|
|
27
|
+
```text
|
|
28
|
+
Upgrade this plugin from DSH 0.1.1 to DSH 0.1.2.
|
|
29
|
+
Analyze compatibility first, modify the code, then complete build and runtime verification.
|
|
54
30
|
```
|
|
55
31
|
|
|
56
|
-
|
|
32
|
+
An upgrade request does not itself authorize dropping the old runtime. If the developer has not said, the skill explicitly asks whether the same upgraded plugin release must still support DSH 0.1.1 before any migration write, dependency installation, build, or runtime command. When compatibility must be preserved, the agent designs a dual-version approach first and verifies 0.1.1 and 0.1.2 separately; one successful 0.1.2 run is not dual-version evidence.
|
|
57
33
|
|
|
58
|
-
|
|
34
|
+
The skill reminds the agent to work in this order:
|
|
59
35
|
|
|
60
|
-
|
|
36
|
+
1. inspect the plugin root, Harness checkout, package manager, and available DSH Doctor;
|
|
37
|
+
2. analyze source, type imports, dependencies, manifest, client graph, patches, and build output;
|
|
38
|
+
3. confirm whether the upgraded release targets only 0.1.2 or must remain compatible with 0.1.1;
|
|
39
|
+
4. preview and apply code changes that are known to be equivalent under the selected compatibility strategy;
|
|
40
|
+
5. use the new API owners to handle semantic changes that require understanding the plugin;
|
|
41
|
+
6. rebuild the plugin and run static, build, and isolated runtime verification, covering both versions in dual-version mode;
|
|
42
|
+
7. report the compatibility intent, changed files, remaining work, backups, and the verification level actually reached.
|
|
61
43
|
|
|
62
|
-
|
|
44
|
+
`npx skills add` installs agent instructions only. It does not install DSH Doctor globally. The skill checks the local CLI and npm registry first. If the local version is unsuitable, it uses a pinned `npx` version by default and does not change the global npm installation.
|
|
63
45
|
|
|
64
|
-
|
|
46
|
+
After verification, the agent can follow the plugin repository's existing versioning and release process if requested. The skill itself does not commit or publish anything automatically.
|
|
65
47
|
|
|
66
|
-
|
|
67
|
-
|---|---|
|
|
68
|
-
| `static` | Uses the TypeScript AST to inspect source/imports, manifest, client graph, and build artifacts without running project scripts |
|
|
69
|
-
| `build` | Executes plugin build scripts and verifies the artifact (`build` or `pack:check` must succeed; `test`/`typecheck` alone is insufficient proof of a publishable artifact) |
|
|
70
|
-
| `runtime` | Packs the real plugin tarball, installs it under a temporary `DSH_HOME` via the target CLI into a fresh web profile, verifies CLI version, profile manifest, installed package, activated bundle, effective config, and performs an activation smoke; never touches the normal `~/.dsh` |
|
|
48
|
+
## How it works
|
|
71
49
|
|
|
72
|
-
|
|
50
|
+
DSH Doctor has three parts:
|
|
73
51
|
|
|
74
|
-
|
|
52
|
+
- **Skill**: tells the agent which steps to follow, which actions need confirmation, and what to report;
|
|
53
|
+
- **CLI**: scans the plugin, lists problems, changes deterministic code, and runs verification;
|
|
54
|
+
- **Migration catalog**: records known package, API, Service, configuration, and behavior changes between the two DSH versions.
|
|
75
55
|
|
|
76
|
-
|
|
56
|
+
The workflow is:
|
|
77
57
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
58
|
+
```text
|
|
59
|
+
analyze
|
|
60
|
+
→ change deterministic code
|
|
61
|
+
→ agent handles semantic changes
|
|
62
|
+
→ rebuild
|
|
63
|
+
→ static verification
|
|
64
|
+
→ temporary-profile installation and activation
|
|
65
|
+
→ publish through the plugin's own release process
|
|
66
|
+
```
|
|
86
67
|
|
|
87
|
-
|
|
68
|
+
The CLI only auto-edits migrations marked `exact` by the catalog. Ownership and lifecycle changes involving Session, Workspace, Conversation, and pending interactions are reported as `MIG_SEMANTIC_API_CHANGE`. The agent must handle them in the context of the plugin instead of applying a mechanical replacement.
|
|
88
69
|
|
|
89
|
-
|
|
70
|
+
## Why versioned rules are needed
|
|
90
71
|
|
|
91
|
-
|
|
72
|
+
DSH 0.1.2 changes more than package versions:
|
|
92
73
|
|
|
93
|
-
|
|
74
|
+
- `@deepseek-ai/dsh-client-runtime` was removed and has no single aggregate replacement;
|
|
75
|
+
- store features moved to `dsh-client-store`;
|
|
76
|
+
- Session, Workspace, Conversation, and pending interactions moved to separate controllers or UI packages;
|
|
77
|
+
- `@deepseek-ai/dsh-host-apiproxy` was removed, so browser calls move to the appropriate business Remote;
|
|
78
|
+
- client graph, platform externals, exports, and some profile patch targets also changed.
|
|
94
79
|
|
|
95
|
-
|
|
96
|
-
npx skills add bruc3van/dsh-doctor
|
|
97
|
-
```
|
|
80
|
+
The migration catalog stores source/target tags and Git commits together with package, symbol, Service, and configuration rules. With `--harness-root`, the CLI verifies the commits behind both tags and compares entry ids in the target web profile. This gives the agent concrete version differences instead of making it guess the new API.
|
|
98
81
|
|
|
99
|
-
|
|
82
|
+
## Coverage
|
|
100
83
|
|
|
101
|
-
|
|
84
|
+
| Area | How Doctor and the agent handle it |
|
|
85
|
+
|---|---|
|
|
86
|
+
| JS/TS imports, including type-only, aliased, and mixed imports | Analyzed with the TypeScript AST; symbols with a known equivalent can be rewritten |
|
|
87
|
+
| Removed or added DSH packages | Checked in source and manifest; dependencies are updated only when no remaining reference blocks the change |
|
|
88
|
+
| DSH/Cordis version ranges | Checks dependencies, devDependencies, and peerDependencies; existing peer ranges are not widened automatically |
|
|
89
|
+
| Session, Workspace, Conversation, and other semantic changes | Reports the new owner and reason; the agent modifies the business code |
|
|
90
|
+
| `dsh.client` and client exports | Checks inject, external, platform, immediately, and `exports["./client"]` |
|
|
91
|
+
| Harness patch targets | Compares old and new entries when an exact Harness checkout is available |
|
|
92
|
+
| Build output | Scans `lib`, `dist`, `build`, and `out` for old APIs |
|
|
93
|
+
| Plugin build | Runs existing typecheck, build, test, and pack:check scripts; build or pack:check is required for artifact verification |
|
|
94
|
+
| Installation and activation | Packs the real tarball and installs it into a fresh web profile under a temporary `DSH_HOME` |
|
|
95
|
+
| UI and business behavior | Not decided by Doctor; the agent or developer runs plugin-specific checks |
|
|
102
96
|
|
|
103
|
-
|
|
97
|
+
Source analysis uses the TypeScript AST and is cross-checked against the manifest, client graph, and build output. A bundle without an old string does not prove that source code is compatible, and a successful compile does not prove that the published artifact or runtime is compatible.
|
|
104
98
|
|
|
105
|
-
|
|
99
|
+
## Safety
|
|
106
100
|
|
|
107
|
-
`diagnose`
|
|
101
|
+
- `diagnose`, `migrate analyze`, and static verification are read-only and do not load or execute the inspected plugin;
|
|
102
|
+
- `migrate apply` requires `--safe`; without `--yes`, it only previews changes;
|
|
103
|
+
- only `exact` migrations are auto-edited; semantic changes are not guessed;
|
|
104
|
+
- SHA-256 is checked before writing, so a file changed after preview is rejected;
|
|
105
|
+
- existing files receive timestamped backups and are replaced atomically through a temporary file;
|
|
106
|
+
- build and runtime verification execute plugin scripts and therefore require explicit `--yes`;
|
|
107
|
+
- runtime verification uses a temporary `DSH_HOME`, not the normal `~/.dsh`;
|
|
108
|
+
- JSON, baselines, and recovery snapshots redact plugin configuration and common secret/token/password/key fields;
|
|
109
|
+
- global CLI installation, persistent quarantine, plugin removal, and publishing are never performed automatically by the skill.
|
|
108
110
|
|
|
109
|
-
|
|
110
|
-
bundle layers → profile cordis.patch.yml → home cordis.patch.yml → CLI overlays
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
The JSON report retains `currentDefaultTree`, `currentEffectiveTree`, field-level provenance, replaced sources, and paths removed by whole-`config` replacement. It diagnoses:
|
|
111
|
+
## Use the migration CLI manually
|
|
114
112
|
|
|
115
|
-
|
|
116
|
-
- duplicate entry ids and duplicate plugin mounts;
|
|
117
|
-
- higher-layer disabling, structural replacement, whole group/config overrides;
|
|
118
|
-
- bundle declaration conflicts with profile activation state;
|
|
119
|
-
- plugin versions, artifacts, client contracts, dependencies, and runtime issues.
|
|
113
|
+
Node.js `^22.19.0` or `>=24.0.0` is required.
|
|
120
114
|
|
|
121
|
-
|
|
115
|
+
First confirm that the CLI contains the required migration:
|
|
122
116
|
|
|
123
117
|
```sh
|
|
124
|
-
dsh-doctor
|
|
125
|
-
dsh-doctor
|
|
126
|
-
dsh-doctor diagnose --check-updates
|
|
118
|
+
npx --yes --package=@bruc3van/dsh-doctor@0.5.4 \
|
|
119
|
+
dsh-doctor migrations list
|
|
127
120
|
```
|
|
128
121
|
|
|
129
|
-
|
|
122
|
+
### 1. Analyze
|
|
130
123
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
124
|
+
```sh
|
|
125
|
+
dsh-doctor migrate analyze /path/to/plugin \
|
|
126
|
+
--from dsh-v0.1.1-rc.2 \
|
|
127
|
+
--to dsh-v0.1.2-alpha.2 \
|
|
128
|
+
--harness-root /path/to/deepseek-harness \
|
|
129
|
+
--json
|
|
130
|
+
```
|
|
134
131
|
|
|
135
|
-
|
|
132
|
+
Analysis checks source, dependencies, manifest, client graph, patch targets, and existing build output without executing plugin code.
|
|
136
133
|
|
|
137
|
-
|
|
134
|
+
### 2. Apply
|
|
138
135
|
|
|
139
136
|
```sh
|
|
140
|
-
|
|
141
|
-
dsh-doctor
|
|
142
|
-
|
|
137
|
+
# Preview
|
|
138
|
+
dsh-doctor migrate apply /path/to/plugin --safe \
|
|
139
|
+
--harness-root /path/to/deepseek-harness --json
|
|
140
|
+
|
|
141
|
+
# Write after confirmation
|
|
142
|
+
dsh-doctor migrate apply /path/to/plugin --safe --yes \
|
|
143
|
+
--harness-root /path/to/deepseek-harness --json
|
|
143
144
|
```
|
|
144
145
|
|
|
145
|
-
|
|
146
|
+
Apply can split mixed imports, move exact symbols, leave semantic symbols in place, and update development dependencies when the change is known. Every changed file receives a backup.
|
|
146
147
|
|
|
147
|
-
|
|
148
|
+
### 3. Verify
|
|
148
149
|
|
|
149
150
|
```sh
|
|
150
|
-
dsh-doctor
|
|
151
|
-
|
|
152
|
-
dsh --
|
|
151
|
+
dsh-doctor migrate verify /path/to/plugin --level static \
|
|
152
|
+
--harness-root /path/to/deepseek-harness --json
|
|
153
|
+
dsh-doctor migrate verify /path/to/plugin --level build --yes \
|
|
154
|
+
--harness-root /path/to/deepseek-harness --json
|
|
155
|
+
dsh-doctor migrate verify /path/to/plugin --level runtime --yes \
|
|
156
|
+
--harness-root /path/to/deepseek-harness --json
|
|
153
157
|
```
|
|
154
158
|
|
|
155
|
-
|
|
159
|
+
| Level | What it checks |
|
|
160
|
+
|---|---|
|
|
161
|
+
| `static` | Rechecks source, manifest, client graph, patches, and artifacts |
|
|
162
|
+
| `build` | Runs the plugin's existing build/test scripts and scans the output again |
|
|
163
|
+
| `runtime` | Packs the real tarball and checks the target DSH version, installed package, bundle, and effective configuration in a temporary profile |
|
|
156
164
|
|
|
157
|
-
|
|
165
|
+
Verification states are:
|
|
158
166
|
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
dsh-doctor recover @scope/plugin --action persist-quarantine --verified
|
|
162
|
-
|
|
163
|
-
# Write to profile/cordis.patch.yml after explicit confirmation
|
|
164
|
-
dsh-doctor recover @scope/plugin --action persist-quarantine --verified --yes
|
|
167
|
+
```text
|
|
168
|
+
analyzed → source-migrated → artifact-verified → runtime-verified
|
|
165
169
|
```
|
|
166
170
|
|
|
167
|
-
|
|
171
|
+
`runtime-verified` means that packing, installation, and basic activation passed. It does not replace real UI, Service lifecycle, and business-flow testing.
|
|
168
172
|
|
|
169
|
-
|
|
173
|
+
## Diagnose DSH and installed plugins
|
|
174
|
+
|
|
175
|
+
Global installation:
|
|
170
176
|
|
|
171
177
|
```sh
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
dsh-doctor recover @scope/plugin --action rollback-quarantine \
|
|
175
|
-
--backup /path/to/cordis.patch.yml.dsh-doctor-...bak --yes
|
|
178
|
+
npm install --global @bruc3van/dsh-doctor
|
|
179
|
+
dsh-doctor diagnose
|
|
176
180
|
```
|
|
177
181
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
### Safe removal
|
|
181
|
-
|
|
182
|
-
Removal is always explicit and can never be inferred by legacy `--fix --yes`:
|
|
182
|
+
Temporary use:
|
|
183
183
|
|
|
184
184
|
```sh
|
|
185
|
-
dsh-doctor
|
|
186
|
-
dsh-doctor recover @scope/plugin --action remove --yes
|
|
185
|
+
npx @bruc3van/dsh-doctor diagnose
|
|
187
186
|
```
|
|
188
187
|
|
|
189
|
-
|
|
188
|
+
The default target is `$DSH_HOME/profiles/web`, falling back to `~/.dsh`.
|
|
190
189
|
|
|
191
190
|
```sh
|
|
192
|
-
dsh
|
|
191
|
+
dsh-doctor diagnose
|
|
192
|
+
dsh-doctor diagnose --json
|
|
193
|
+
dsh-doctor diagnose --check-updates
|
|
193
194
|
```
|
|
194
195
|
|
|
195
|
-
|
|
196
|
+
Diagnosis composes configuration in DSH order:
|
|
196
197
|
|
|
197
|
-
|
|
198
|
+
```text
|
|
199
|
+
bundle layers → profile cordis.patch.yml → home cordis.patch.yml → CLI overlays
|
|
200
|
+
```
|
|
198
201
|
|
|
199
|
-
|
|
202
|
+
It checks plugin versions and peers, Node engines, installation and lockfile state, bundles and patches, client contracts, duplicate mounts, higher-layer overrides, and DSH CLI/Harness version drift. Normal diagnosis does not use the network. Only `--check-updates` and recovery operations contact the npm registry.
|
|
200
203
|
|
|
201
|
-
|
|
204
|
+
## Recovery operations
|
|
202
205
|
|
|
203
206
|
```sh
|
|
204
|
-
|
|
205
|
-
dsh-doctor
|
|
207
|
+
# Check and install the highest manifest-declared compatible version
|
|
208
|
+
dsh-doctor recover @scope/plugin --action check-update
|
|
209
|
+
dsh-doctor recover @scope/plugin --action update
|
|
210
|
+
dsh-doctor recover @scope/plugin --action update --yes
|
|
206
211
|
|
|
207
|
-
#
|
|
208
|
-
dsh-doctor
|
|
209
|
-
|
|
210
|
-
```
|
|
212
|
+
# Create a temporary quarantine overlay
|
|
213
|
+
dsh-doctor recover @scope/plugin --action quarantine \
|
|
214
|
+
--output ./plugin-quarantine.yml
|
|
211
215
|
|
|
212
|
-
|
|
216
|
+
# Persist it only after testing the temporary overlay
|
|
217
|
+
dsh-doctor recover @scope/plugin --action persist-quarantine --verified
|
|
218
|
+
dsh-doctor recover @scope/plugin --action persist-quarantine --verified --yes
|
|
213
219
|
|
|
214
|
-
|
|
220
|
+
# Removal is always separate
|
|
221
|
+
dsh-doctor recover @scope/plugin --action remove
|
|
222
|
+
dsh-doctor recover @scope/plugin --action remove --yes
|
|
223
|
+
```
|
|
215
224
|
|
|
216
|
-
|
|
225
|
+
Before quarantine or removal, Doctor checks entry ownership, configuration layers, direct dependencies, core bundles, lockfile state, manual mounts, and known client dependents. Static checks cannot prove dynamic Service dependencies or external data safety, so restart the profile and test its main features afterwards.
|
|
226
|
+
|
|
227
|
+
You can also save and compare a baseline around an upgrade:
|
|
217
228
|
|
|
218
229
|
```sh
|
|
219
|
-
dsh-doctor
|
|
220
|
-
dsh-doctor
|
|
230
|
+
dsh-doctor baseline create
|
|
231
|
+
dsh-doctor baseline compare
|
|
221
232
|
```
|
|
222
233
|
|
|
223
|
-
---
|
|
224
|
-
|
|
225
234
|
## Output and exit codes
|
|
226
235
|
|
|
227
|
-
Text output supports Chinese and English. `--json`
|
|
236
|
+
Text output supports Chinese and English. `--json` uses stable English codes and keeps redacted structured evidence.
|
|
228
237
|
|
|
229
238
|
| Exit code | Meaning |
|
|
230
239
|
|---|---|
|
|
231
|
-
| `0` | No
|
|
232
|
-
| `1` |
|
|
233
|
-
| `2` | Argument, environment, or action
|
|
234
|
-
|
|
235
|
-
## Security boundaries
|
|
236
|
-
|
|
237
|
-
- Does not execute third-party plugins or evaluate `!!js`; diagnosis parses configuration structure but redacts every plugin `config` value plus other common secret fields from JSON, baselines, and recovery snapshots; text reports do not print configuration values.
|
|
238
|
-
- Registry compatibility is declarative only; it does not prove a real startup or UI test.
|
|
239
|
-
- Dynamic Service dependencies, external side effects, real UI behavior, and business workflows require user validation.
|
|
240
|
-
- Precise patch edits only operate on structures Doctor can safely parse and locate; ambiguous cases are refused automatically.
|
|
241
|
-
- After adding, updating, or removing a bundle, a running profile does not automatically change its bundle set — a restart is required.
|
|
240
|
+
| `0` | No blocker remains, or the action completed and passed its verification |
|
|
241
|
+
| `1` | Compatibility issues, semantic migration, or verification work remains |
|
|
242
|
+
| `2` | Argument, environment, or action-execution failure |
|
|
242
243
|
|
|
243
244
|
## Development
|
|
244
245
|
|
|
@@ -248,4 +249,6 @@ npm run check
|
|
|
248
249
|
npm pack --dry-run
|
|
249
250
|
```
|
|
250
251
|
|
|
251
|
-
|
|
252
|
+
Tests cover the CLI, configuration composition, diagnosis, redaction, backups and write protection, AST migration, build gates, isolated runtime verification, and recovery operations. CI tests Node.js `22.19` and `24` on macOS, Ubuntu, and Windows.
|
|
253
|
+
|
|
254
|
+
Local development, the skill, and the CLI never commit, tag, or publish automatically.
|
package/README.md
CHANGED
|
@@ -2,245 +2,246 @@
|
|
|
2
2
|
|
|
3
3
|
中文 | [English](README.en.md)
|
|
4
4
|
|
|
5
|
-
DSH Doctor
|
|
5
|
+
DSH Doctor 帮助 Agent 诊断和升级 DeepSeek Harness 插件：识别新旧版本之间的 API 变化，修改可以确定迁移的代码，提示需要开发者判断的语义变化，重新构建并验证插件。
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
当前主要面向：
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
需要 Node.js `22.19+` 或 `24+`：
|
|
12
|
-
|
|
13
|
-
```sh
|
|
14
|
-
npm install --global @bruc3van/dsh-doctor
|
|
15
|
-
dsh-doctor diagnose
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
也可以临时运行：
|
|
19
|
-
|
|
20
|
-
```sh
|
|
21
|
-
npx @bruc3van/dsh-doctor diagnose
|
|
9
|
+
```text
|
|
10
|
+
DSH 0.1.1 → DSH 0.1.2
|
|
22
11
|
```
|
|
23
12
|
|
|
24
|
-
|
|
13
|
+
项目同时提供 DSH profile 和插件的诊断、兼容版本检查、隔离与删除前检查。
|
|
25
14
|
|
|
26
|
-
|
|
15
|
+
> 这是社区维护的第三方工具，不属于 DeepSeek 官方项目。当前 catalog 以 `dsh-v0.1.1-rc.2` 和 `dsh-v0.1.2-alpha.2` 为基准记录 0.1.1 到 0.1.2 的变化；插件使用其他 patch 或预发布版本时，Agent 仍需核对实际差异。
|
|
27
16
|
|
|
28
|
-
##
|
|
17
|
+
## 使用 Skill 升级插件
|
|
29
18
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
Doctor 内置 `dsh-v0.1.1-rc.2 → dsh-v0.1.2-alpha.2` 的版本化迁移目录，并把升级拆成三个可审计阶段：
|
|
19
|
+
安装仓库中的 [`dsh-plugin-upgrade`](skills/dsh-plugin-upgrade/SKILL.md) Skill：
|
|
33
20
|
|
|
34
21
|
```sh
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
--from dsh-v0.1.1-rc.2 \
|
|
38
|
-
--to dsh-v0.1.2-alpha.2 \
|
|
39
|
-
--harness-root /path/to/deepseek-harness
|
|
22
|
+
npx skills add bruc3van/dsh-doctor
|
|
23
|
+
```
|
|
40
24
|
|
|
41
|
-
|
|
42
|
-
dsh-doctor migrate apply /path/to/plugin --safe \
|
|
43
|
-
--harness-root /path/to/deepseek-harness
|
|
44
|
-
dsh-doctor migrate apply /path/to/plugin --safe --yes \
|
|
45
|
-
--harness-root /path/to/deepseek-harness
|
|
25
|
+
然后在插件仓库中告诉 Agent：
|
|
46
26
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
dsh-doctor migrate verify /path/to/plugin --level build --yes \
|
|
51
|
-
--harness-root /path/to/deepseek-harness
|
|
52
|
-
dsh-doctor migrate verify /path/to/plugin --level runtime --yes \
|
|
53
|
-
--harness-root /path/to/deepseek-harness
|
|
27
|
+
```text
|
|
28
|
+
请把当前插件从 DSH 0.1.1 升级到 DSH 0.1.2。
|
|
29
|
+
先分析兼容问题，再修改代码，最后完成构建和运行时验证。
|
|
54
30
|
```
|
|
55
31
|
|
|
56
|
-
|
|
32
|
+
升级请求本身不代表可以放弃旧版。若开发者没有说明，Skill 会在任何迁移写入、依赖安装、构建或运行时命令前，显式询问升级后的同一插件版本是否还要兼容 DSH 0.1.1。选择保留兼容时，Agent 会先设计双版本适配方式，并分别验证 0.1.1 和 0.1.2；不能用一次 0.1.2 验证代替双版本结论。
|
|
57
33
|
|
|
58
|
-
|
|
34
|
+
Skill 会提醒 Agent 按下面的顺序工作：
|
|
59
35
|
|
|
60
|
-
|
|
36
|
+
1. 检查插件目录、Harness checkout、包管理器和可用的 DSH Doctor；
|
|
37
|
+
2. 分析源码、类型导入、依赖、manifest、client graph、patch 和构建产物；
|
|
38
|
+
3. 确认升级后是仅支持 0.1.2，还是同一版本继续兼容 0.1.1；
|
|
39
|
+
4. 预览并应用可以确定等价、且符合所选兼容策略的代码修改；
|
|
40
|
+
5. 根据新的 API 所有者处理需要理解业务的语义迁移；
|
|
41
|
+
6. 重新构建插件，并依次做静态、构建和隔离运行时验证；双版本模式分别验证两端；
|
|
42
|
+
7. 报告兼容目标、修改内容、剩余问题、备份和实际达到的验证等级。
|
|
61
43
|
|
|
62
|
-
|
|
44
|
+
`npx skills add` 只安装 Agent 指令，不会安装全局 DSH Doctor。Skill 会先检查本地 CLI 和 npm registry；本地版本不合适时，默认使用固定版本的 `npx`，不会自行修改全局 npm 安装。
|
|
63
45
|
|
|
64
|
-
|
|
46
|
+
验证完成后，可以再让 Agent 按插件仓库原有的版本和发布流程提交、打 tag、发布。Skill 本身不会自动提交或发布。
|
|
65
47
|
|
|
66
|
-
|
|
67
|
-
|---|---|
|
|
68
|
-
| `static` | 使用 TypeScript AST 检查源码/import、manifest、client graph 与构建产物，不执行项目脚本 |
|
|
69
|
-
| `build` | 执行插件构建脚本，验证产物（需 `build` 或 `pack:check` 成功；仅有 `test`/`typecheck` 不足以证明发布产物） |
|
|
70
|
-
| `runtime` | 打真实 tarball，在临时 `DSH_HOME` 中通过目标 CLI 安装到全新 web profile，核验 CLI 版本、profile manifest、已安装包、bundle 激活与有效配置，执行激活 smoke；不触碰普通用户的 `~/.dsh` |
|
|
48
|
+
## 工作方式
|
|
71
49
|
|
|
72
|
-
|
|
50
|
+
DSH Doctor 由三部分组成：
|
|
73
51
|
|
|
74
|
-
|
|
52
|
+
- **Skill**：告诉 Agent 升级步骤、哪些操作需要确认，以及最后应该报告什么；
|
|
53
|
+
- **CLI**：扫描插件、生成问题清单、修改确定性代码，并执行分级验证；
|
|
54
|
+
- **Migration catalog**：记录两个 DSH 版本之间已确认的包、API、Service、配置和行为变化。
|
|
75
55
|
|
|
76
|
-
|
|
56
|
+
完整流程是：
|
|
77
57
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
`@deepseek-ai/dsh-host-apiproxy` 也已移除，无兼容替代，浏览器操作改用 API Remotes/API Gateway 原生 Remote 所有者。
|
|
58
|
+
```text
|
|
59
|
+
分析问题
|
|
60
|
+
→ 修改确定性代码
|
|
61
|
+
→ Agent 处理语义变化
|
|
62
|
+
→ 重新构建
|
|
63
|
+
→ 静态验证
|
|
64
|
+
→ 临时 profile 安装与激活验证
|
|
65
|
+
→ 按插件自己的流程发布
|
|
66
|
+
```
|
|
88
67
|
|
|
89
|
-
|
|
68
|
+
CLI 只自动修改 catalog 标记为 `exact` 的迁移。Session、Workspace、Conversation、pending interaction 等所有权和生命周期变化会标记为 `MIG_SEMANTIC_API_CHANGE`，由 Agent 结合插件代码处理，不会机械替换。
|
|
90
69
|
|
|
91
|
-
|
|
70
|
+
## 为什么需要版本化规则
|
|
92
71
|
|
|
93
|
-
|
|
72
|
+
DSH 0.1.2 不只是包版本变化，一些能力被拆分到了新的所有者：
|
|
94
73
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
74
|
+
- `@deepseek-ai/dsh-client-runtime` 已移除，没有一个新的聚合包可以直接替换；
|
|
75
|
+
- store 能力迁移到 `dsh-client-store`；
|
|
76
|
+
- Session、Workspace、Conversation 和 pending interaction 分别由新的 controller 或 UI 包负责；
|
|
77
|
+
- `@deepseek-ai/dsh-host-apiproxy` 已移除，浏览器调用需要迁移到对应业务 Remote；
|
|
78
|
+
- client graph、platform external、exports 和部分 profile patch target 也发生了变化。
|
|
98
79
|
|
|
99
|
-
|
|
80
|
+
Migration catalog 保存 source/target tag 和 Git commit，并记录 package、symbol、Service 和配置规则。提供 `--harness-root` 时，CLI 还会确认两个 tag 对应的 commit，并比较目标 web profile 中的 entry id。这样 Agent 可以基于明确的版本差异修改代码，而不是猜测新 API。
|
|
100
81
|
|
|
101
|
-
|
|
82
|
+
## 覆盖范围
|
|
102
83
|
|
|
103
|
-
|
|
84
|
+
| 检查内容 | Doctor/Agent 如何处理 |
|
|
85
|
+
|---|---|
|
|
86
|
+
| JS/TS import，包括 `import type`、别名和混合 import | 使用 TypeScript AST 分析；确定等价的 symbol 可自动改写 |
|
|
87
|
+
| 移除或新增的 DSH 包 | 检查源码和 manifest；没有残留引用时更新依赖 |
|
|
88
|
+
| DSH/Cordis 版本范围 | 检查 dependencies、devDependencies 和 peerDependencies；不自动扩大已有 peer 范围 |
|
|
89
|
+
| Session、Workspace、Conversation 等语义变化 | 报告新 owner 和变化原因，由 Agent 修改业务代码 |
|
|
90
|
+
| `dsh.client` 和 client export | 检查 inject、external、platform、immediately 和 `exports["./client"]` |
|
|
91
|
+
| Harness patch target | 有精确 Harness checkout 时比较新旧 entry |
|
|
92
|
+
| 构建产物 | 检查 `lib`、`dist`、`build`、`out` 中是否仍包含旧 API |
|
|
93
|
+
| 插件构建 | 运行项目已有的 typecheck、build、test、pack:check；必须有 build 或 pack:check 才算产物已验证 |
|
|
94
|
+
| 安装和激活 | 打包真实 tarball，安装到临时 `DSH_HOME` 的新 web profile 中验证 |
|
|
95
|
+
| UI 和业务行为 | Doctor 不自动判断；需要 Agent 或开发者执行插件自己的测试 |
|
|
104
96
|
|
|
105
|
-
|
|
97
|
+
源码分析使用 TypeScript AST，并同时检查 manifest、client graph 和构建产物。因此，bundle 中没有旧字符串并不代表源码已经兼容，源码编译通过也不代表发布产物和运行时已经兼容。
|
|
106
98
|
|
|
107
|
-
|
|
99
|
+
## 安全性
|
|
108
100
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
101
|
+
- `diagnose`、`migrate analyze` 和静态验证只读，不加载或执行待检查插件；
|
|
102
|
+
- `migrate apply` 必须带 `--safe`，没有 `--yes` 时只展示将要修改的内容；
|
|
103
|
+
- 只有 `exact` 迁移会自动改代码，语义变化不会自动猜测；
|
|
104
|
+
- 写入前检查文件 SHA-256，预览后文件发生变化会拒绝写入；
|
|
105
|
+
- 修改已有文件前创建时间戳备份，并使用临时文件原子替换；
|
|
106
|
+
- build 和 runtime 会执行插件脚本，因此必须显式使用 `--yes`；
|
|
107
|
+
- runtime 使用临时 `DSH_HOME`，不会安装到正常的 `~/.dsh`；
|
|
108
|
+
- JSON、baseline 和恢复快照会脱敏插件配置和常见 secret/token/password/key 字段；
|
|
109
|
+
- 全局 CLI 安装、持久隔离、删除插件和发布都不会由 Skill 自动执行。
|
|
112
110
|
|
|
113
|
-
|
|
111
|
+
## 手动使用迁移 CLI
|
|
114
112
|
|
|
115
|
-
|
|
116
|
-
- 重复 entry id、重复插件 mount；
|
|
117
|
-
- 高层禁用、结构替换、group/config 整体覆盖；
|
|
118
|
-
- bundle 声明与 profile 激活状态冲突；
|
|
119
|
-
- 插件版本、产物、client contract、依赖与运行环境问题。
|
|
113
|
+
需要 Node.js `^22.19.0` 或 `>=24.0.0`。
|
|
120
114
|
|
|
121
|
-
|
|
115
|
+
先确认 CLI 包含需要的迁移：
|
|
122
116
|
|
|
123
117
|
```sh
|
|
124
|
-
dsh-doctor
|
|
125
|
-
dsh-doctor
|
|
126
|
-
dsh-doctor diagnose --check-updates
|
|
118
|
+
npx --yes --package=@bruc3van/dsh-doctor@0.5.4 \
|
|
119
|
+
dsh-doctor migrations list
|
|
127
120
|
```
|
|
128
121
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
---
|
|
122
|
+
### 1. 分析
|
|
132
123
|
|
|
133
|
-
|
|
124
|
+
```sh
|
|
125
|
+
dsh-doctor migrate analyze /path/to/plugin \
|
|
126
|
+
--from dsh-v0.1.1-rc.2 \
|
|
127
|
+
--to dsh-v0.1.2-alpha.2 \
|
|
128
|
+
--harness-root /path/to/deepseek-harness \
|
|
129
|
+
--json
|
|
130
|
+
```
|
|
134
131
|
|
|
135
|
-
|
|
132
|
+
分析会检查源码、依赖、manifest、client graph、patch target 和已有构建产物，不执行插件代码。
|
|
136
133
|
|
|
137
|
-
|
|
134
|
+
### 2. 修改
|
|
138
135
|
|
|
139
136
|
```sh
|
|
140
|
-
|
|
141
|
-
dsh-doctor
|
|
142
|
-
|
|
137
|
+
# 预览
|
|
138
|
+
dsh-doctor migrate apply /path/to/plugin --safe \
|
|
139
|
+
--harness-root /path/to/deepseek-harness --json
|
|
140
|
+
|
|
141
|
+
# 确认后写入
|
|
142
|
+
dsh-doctor migrate apply /path/to/plugin --safe --yes \
|
|
143
|
+
--harness-root /path/to/deepseek-harness --json
|
|
143
144
|
```
|
|
144
145
|
|
|
145
|
-
|
|
146
|
+
Apply 可以拆分混合 import、移动精确 symbol、保留语义 symbol，并更新确定可以调整的开发依赖。每个被修改的文件都会保留备份。
|
|
146
147
|
|
|
147
|
-
|
|
148
|
+
### 3. 验证
|
|
148
149
|
|
|
149
150
|
```sh
|
|
150
|
-
dsh-doctor
|
|
151
|
-
|
|
152
|
-
dsh --
|
|
151
|
+
dsh-doctor migrate verify /path/to/plugin --level static \
|
|
152
|
+
--harness-root /path/to/deepseek-harness --json
|
|
153
|
+
dsh-doctor migrate verify /path/to/plugin --level build --yes \
|
|
154
|
+
--harness-root /path/to/deepseek-harness --json
|
|
155
|
+
dsh-doctor migrate verify /path/to/plugin --level runtime --yes \
|
|
156
|
+
--harness-root /path/to/deepseek-harness --json
|
|
153
157
|
```
|
|
154
158
|
|
|
155
|
-
|
|
159
|
+
| 级别 | 验证内容 |
|
|
160
|
+
|---|---|
|
|
161
|
+
| `static` | 再次检查源码、manifest、client graph、patch 和产物 |
|
|
162
|
+
| `build` | 运行插件已有的构建与测试脚本，并在构建后重新扫描产物 |
|
|
163
|
+
| `runtime` | 打真实 tarball，在临时 profile 中验证目标 DSH 版本、安装包、bundle 和生效配置 |
|
|
156
164
|
|
|
157
|
-
|
|
165
|
+
验证状态依次是：
|
|
158
166
|
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
dsh-doctor recover @scope/plugin --action persist-quarantine --verified
|
|
162
|
-
|
|
163
|
-
# 明确确认后写入 profile/cordis.patch.yml
|
|
164
|
-
dsh-doctor recover @scope/plugin --action persist-quarantine --verified --yes
|
|
167
|
+
```text
|
|
168
|
+
analyzed → source-migrated → artifact-verified → runtime-verified
|
|
165
169
|
```
|
|
166
170
|
|
|
167
|
-
|
|
171
|
+
`runtime-verified` 只表示插件能够完成打包、安装和基本激活，仍不能代替真实 UI、Service 生命周期和业务流程验证。
|
|
172
|
+
|
|
173
|
+
## DSH 和已安装插件诊断
|
|
168
174
|
|
|
169
|
-
|
|
175
|
+
全局安装：
|
|
170
176
|
|
|
171
177
|
```sh
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
dsh-doctor recover @scope/plugin --action rollback-quarantine \
|
|
175
|
-
--backup /path/to/cordis.patch.yml.dsh-doctor-...bak --yes
|
|
178
|
+
npm install --global @bruc3van/dsh-doctor
|
|
179
|
+
dsh-doctor diagnose
|
|
176
180
|
```
|
|
177
181
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
### 安全删除
|
|
181
|
-
|
|
182
|
-
删除是独立动作，永远不会由通用 `--fix --yes` 推断：
|
|
182
|
+
临时运行：
|
|
183
183
|
|
|
184
184
|
```sh
|
|
185
|
-
dsh-doctor
|
|
186
|
-
dsh-doctor recover @scope/plugin --action remove --yes # 显式执行
|
|
185
|
+
npx @bruc3van/dsh-doctor diagnose
|
|
187
186
|
```
|
|
188
187
|
|
|
189
|
-
|
|
188
|
+
默认检查 `$DSH_HOME/profiles/web`；未设置 `DSH_HOME` 时使用 `~/.dsh`。
|
|
190
189
|
|
|
191
190
|
```sh
|
|
192
|
-
dsh
|
|
191
|
+
dsh-doctor diagnose
|
|
192
|
+
dsh-doctor diagnose --json
|
|
193
|
+
dsh-doctor diagnose --check-updates
|
|
193
194
|
```
|
|
194
195
|
|
|
195
|
-
|
|
196
|
+
诊断按 DSH 的顺序组合配置：
|
|
196
197
|
|
|
197
|
-
|
|
198
|
+
```text
|
|
199
|
+
bundle layers → profile cordis.patch.yml → home cordis.patch.yml → CLI overlays
|
|
200
|
+
```
|
|
198
201
|
|
|
199
|
-
|
|
202
|
+
它会检查插件版本和 peer、Node engines、安装与 lockfile、bundle 与 patch、client contract、重复 mount、高层配置覆盖，以及 DSH CLI/Harness 版本漂移。普通诊断不访问网络；只有 `--check-updates` 和 recovery 操作会访问 npm registry。
|
|
200
203
|
|
|
201
|
-
|
|
204
|
+
## 恢复操作
|
|
202
205
|
|
|
203
206
|
```sh
|
|
204
|
-
|
|
205
|
-
dsh-doctor
|
|
207
|
+
# 检查和安装 manifest 声明兼容的最高版本
|
|
208
|
+
dsh-doctor recover @scope/plugin --action check-update
|
|
209
|
+
dsh-doctor recover @scope/plugin --action update
|
|
210
|
+
dsh-doctor recover @scope/plugin --action update --yes
|
|
206
211
|
|
|
207
|
-
#
|
|
208
|
-
dsh-doctor
|
|
209
|
-
|
|
210
|
-
```
|
|
212
|
+
# 生成临时隔离 overlay
|
|
213
|
+
dsh-doctor recover @scope/plugin --action quarantine \
|
|
214
|
+
--output ./plugin-quarantine.yml
|
|
211
215
|
|
|
212
|
-
|
|
216
|
+
# 验证临时 overlay 后持久化
|
|
217
|
+
dsh-doctor recover @scope/plugin --action persist-quarantine --verified
|
|
218
|
+
dsh-doctor recover @scope/plugin --action persist-quarantine --verified --yes
|
|
213
219
|
|
|
214
|
-
|
|
220
|
+
# 删除始终需要单独执行
|
|
221
|
+
dsh-doctor recover @scope/plugin --action remove
|
|
222
|
+
dsh-doctor recover @scope/plugin --action remove --yes
|
|
223
|
+
```
|
|
215
224
|
|
|
216
|
-
|
|
225
|
+
Doctor 会在隔离和删除前检查 entry、配置层、直接依赖、核心 bundle、lockfile、手工 mount 和已知 client dependents。静态检查无法确认动态 Service 依赖和外部数据，操作后仍需重启 profile 并验证主要功能。
|
|
226
|
+
|
|
227
|
+
升级前后也可以保存和比较基线：
|
|
217
228
|
|
|
218
229
|
```sh
|
|
219
|
-
dsh-doctor
|
|
220
|
-
dsh-doctor
|
|
230
|
+
dsh-doctor baseline create
|
|
231
|
+
dsh-doctor baseline compare
|
|
221
232
|
```
|
|
222
233
|
|
|
223
|
-
---
|
|
224
|
-
|
|
225
234
|
## 输出与退出码
|
|
226
235
|
|
|
227
|
-
|
|
236
|
+
文本支持中文和英文，`--json` 使用稳定英文 code 并保留脱敏后的结构化证据。
|
|
228
237
|
|
|
229
238
|
| 退出码 | 含义 |
|
|
230
239
|
|---|---|
|
|
231
|
-
| `0` |
|
|
232
|
-
| `1` |
|
|
233
|
-
| `2` |
|
|
234
|
-
|
|
235
|
-
## 安全边界
|
|
240
|
+
| `0` | 没有阻断错误，或操作完成并通过对应验证 |
|
|
241
|
+
| `1` | 仍有兼容问题、语义迁移或验证未完成 |
|
|
242
|
+
| `2` | 参数、运行环境或操作执行失败 |
|
|
236
243
|
|
|
237
|
-
|
|
238
|
-
- registry 结果只证明 manifest 声明，不证明真实运行兼容；
|
|
239
|
-
- 动态 Service 依赖、外部副作用、真实 UI 和业务流程需要用户验证；
|
|
240
|
-
- patch 精确编辑只处理 Doctor 能安全解析和定位的结构；有歧义时拒绝自动操作；
|
|
241
|
-
- 添加、更新或删除 bundle 后，运行中的 profile 不会自动改变 bundle 集合，必须重启。
|
|
242
|
-
|
|
243
|
-
## 从源码开发
|
|
244
|
+
## 开发
|
|
244
245
|
|
|
245
246
|
```sh
|
|
246
247
|
npm install
|
|
@@ -248,4 +249,6 @@ npm run check
|
|
|
248
249
|
npm pack --dry-run
|
|
249
250
|
```
|
|
250
251
|
|
|
251
|
-
|
|
252
|
+
测试覆盖 CLI、配置组合、诊断、脱敏、备份与写入保护、AST 迁移、构建门控、隔离运行时验证和恢复操作。CI 在 macOS、Ubuntu 和 Windows 上测试 Node.js `22.19` 与 `24`。
|
|
253
|
+
|
|
254
|
+
本地开发、Skill 和 CLI 都不会自动提交代码、创建 tag 或发布版本。
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bruc3van/dsh-doctor",
|
|
3
|
-
"version": "0.5.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.5.4",
|
|
4
|
+
"description": "Help agents diagnose and upgrade DeepSeek Harness plugins from DSH 0.1.1 to 0.1.2",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"repository": {
|
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: dsh-plugin-upgrade
|
|
3
|
-
description:
|
|
3
|
+
description: Help diagnose and upgrade a DeepSeek Harness plugin from DSH 0.1.1 to 0.1.2 with dsh-doctor, while deciding explicitly whether the upgraded release must remain compatible with DSH 0.1.1. Use when a plugin developer asks to assess compatibility, identify changed APIs, replace removed dsh-client-runtime or dsh-host-apiproxy usage, update DSH dependencies, modify plugin code, rebuild artifacts, or verify the plugin before releasing a new version. Apply only catalog-confirmed exact rewrites automatically, guide semantic code changes, and report what still needs developer verification. The current catalog uses dsh-v0.1.1-rc.2 and dsh-v0.1.2-alpha.2 as its reference points.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
# DSH plugin
|
|
6
|
+
# Upgrade a DSH 0.1.1 plugin to 0.1.2
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
8
|
+
Help the developer diagnose and modify one plugin at a time. Treat source migration, artifact verification, runtime activation, and business behavior as separate gates.
|
|
9
|
+
|
|
10
|
+
The current migration knowledge covers the DSH 0.1.1 to 0.1.2 transition. Its CLI catalog records `dsh-v0.1.1-rc.2` and `dsh-v0.1.2-alpha.2` as the exact reference points used to derive and verify known changes. Use those refs in dsh-doctor commands, but first record the plugin's actual DSH ranges and requested target. When another patch or prerelease is involved, use the catalog for known changes only and report that the additional version difference still needs review. Do not claim that the catalog proves an unlisted version combination.
|
|
10
11
|
|
|
11
12
|
## Inputs
|
|
12
13
|
|
|
@@ -14,21 +15,37 @@ Determine:
|
|
|
14
15
|
|
|
15
16
|
- the plugin repository root;
|
|
16
17
|
- the DSH Harness checkout when available;
|
|
18
|
+
- the plugin's actual DSH dependency and peer ranges, and the requested 0.1.2 target;
|
|
19
|
+
- whether the upgraded plugin must keep supporting DSH 0.1.1, target only DSH 0.1.2, or still needs that decision from the developer;
|
|
17
20
|
- whether the developer authorizes writes and project command execution;
|
|
18
21
|
- whether the developer authorizes a global CLI install or update;
|
|
19
22
|
- the plugin's package manager and build scripts.
|
|
20
23
|
|
|
21
|
-
Use these
|
|
24
|
+
Use these catalog reference points in the current CLI commands:
|
|
22
25
|
|
|
23
26
|
- source: `dsh-v0.1.1-rc.2`
|
|
24
27
|
- target: `dsh-v0.1.2-alpha.2`
|
|
25
28
|
|
|
26
|
-
Read [cli-bootstrap.md](references/cli-bootstrap.md) before running any migration command, [migration-map.md](references/migration-map.md) before making semantic changes, and [verification.md](references/verification.md) before build or runtime verification.
|
|
29
|
+
Read [cli-bootstrap.md](references/cli-bootstrap.md) before running any migration command, [compatibility-strategy.md](references/compatibility-strategy.md) before proposing or writing changes, [migration-map.md](references/migration-map.md) before making semantic changes, and [verification.md](references/verification.md) before build or runtime verification.
|
|
27
30
|
|
|
28
31
|
Before touching the plugin, inspect the local CLI and perform the read-only registry update check described in `cli-bootstrap.md`. Select one exact DSH Doctor version, verify it exposes this migration catalog, and keep the same invocation for analyze, apply, and verify. Prefer an exact-version `npx` fallback over changing the developer's global installation. Never globally install or update the CLI without explicit authorization.
|
|
29
32
|
|
|
30
33
|
The examples below use `dsh-doctor` for readability. When bootstrap selected an npx invocation, substitute the complete pinned prefix, `npx --yes --package=@bruc3van/dsh-doctor@<selected-version> dsh-doctor`, in every phase.
|
|
31
34
|
|
|
35
|
+
## Compatibility decision gate
|
|
36
|
+
|
|
37
|
+
An upgrade request does not say whether the developer accepts dropping DSH 0.1.1. Write authorization also does not answer that product decision. Do not infer the answer from the current peer range, the word "upgrade," or the fact that a 0.1.2-only rewrite is simpler.
|
|
38
|
+
|
|
39
|
+
You may inspect files, bootstrap the CLI, and run read-only analysis to collect evidence. Before any `migrate apply` preview, source or manifest edit, dependency install, build, or runtime command:
|
|
40
|
+
|
|
41
|
+
1. record an explicit choice already present in the developer's request; or
|
|
42
|
+
2. ask: **"Should the same upgraded plugin release continue to support DSH 0.1.1, or may it target DSH 0.1.2 only?"**
|
|
43
|
+
|
|
44
|
+
If the answer is unavailable or ambiguous, stop at `analyzed`, identify the compatibility decision as pending, and do not modify the plugin. Follow the selected path in [compatibility-strategy.md](references/compatibility-strategy.md):
|
|
45
|
+
|
|
46
|
+
- **0.1.2-only:** the catalog's exact rewrites may be applied after their normal preview and write confirmation.
|
|
47
|
+
- **dual-version:** treat every 0.1.2 rewrite as a candidate, not an automatically compatible change. Design and review an adapter or conditional entry/build approach before writing. If the same release cannot honestly support both versions, explain the conflict and ask whether separate releases are acceptable; that changes the compatibility intent and must not be presented as same-release dual compatibility.
|
|
48
|
+
|
|
32
49
|
## Phase 1: analyze
|
|
33
50
|
|
|
34
51
|
Run from any directory:
|
|
@@ -54,6 +71,8 @@ Do not infer compatibility from a clean bundled artifact alone. The analyzer int
|
|
|
54
71
|
|
|
55
72
|
## Phase 2: apply exact changes
|
|
56
73
|
|
|
74
|
+
Enter this phase only after the compatibility decision gate is resolved. The commands below are the 0.1.2-target migration path. For dual-version work, first apply the additional constraints in `compatibility-strategy.md`; do not assume a catalog-safe codemod is safe for 0.1.1.
|
|
75
|
+
|
|
57
76
|
Preview first:
|
|
58
77
|
|
|
59
78
|
```sh
|
|
@@ -88,6 +107,12 @@ On failure, preserve and report the temporary directory. On success, the CLI rem
|
|
|
88
107
|
|
|
89
108
|
Runtime activation is not business-behavior proof. Finish with targeted manual or automated checks for visible UI, service lifecycle, event subscriptions, cleanup, configuration, and plugin-specific workflows.
|
|
90
109
|
|
|
110
|
+
For a dual-version result, verify the produced release against both the actual 0.1.1 and 0.1.2 environments. The catalog-driven `migrate verify` commands prove only the configured target side. Use the plugin's own build/test flow and an isolated 0.1.1 Harness profile for the legacy side, and name the evidence from each matrix row. A successful 0.1.2 runtime smoke must never be reported as dual-version compatibility.
|
|
111
|
+
|
|
112
|
+
## Prepare for release when requested
|
|
113
|
+
|
|
114
|
+
Verification prepares the plugin for release but does not publish it. If the developer explicitly asks to release the upgraded plugin, first follow the repository's own release instructions and confirm that required semantic and behavior checks are complete. Then update the plugin version and changelog, inspect the packed artifact, and use the repository's existing commit, tag, publish, and registry-verification workflow. Do not commit, tag, or publish merely because the migration skill was installed or run.
|
|
115
|
+
|
|
91
116
|
## Report the outcome
|
|
92
117
|
|
|
93
118
|
State the highest achieved gate exactly:
|
|
@@ -100,3 +125,5 @@ State the highest achieved gate exactly:
|
|
|
100
125
|
|
|
101
126
|
Do not call the plugin compatible while errors, semantic tasks, stale artifacts, or required behavior checks remain. Include backups and retained temporary directories in the handoff.
|
|
102
127
|
Also report the selected DSH Doctor version and source (`local`, exact-version `npx`, or explicitly authorized global install), the registry version observed at bootstrap, and whether update status was current, outdated, missing, or unknown.
|
|
128
|
+
Report the plugin's actual source/target version evidence separately from the catalog reference refs. State whether the plugin is ready for its normal release process; if a release was explicitly requested and completed, include the commit, tag, registry, and release verification evidence.
|
|
129
|
+
State the compatibility intent as one of `0.1.2-only`, `dual-version`, or `pending developer decision`. For `dual-version`, report build, artifact, runtime, and behavior evidence separately for 0.1.1 and 0.1.2; only call the release dual-compatible when every required row passes.
|
|
@@ -3,10 +3,11 @@
|
|
|
3
3
|
"evals": [
|
|
4
4
|
{
|
|
5
5
|
"id": 1,
|
|
6
|
-
"prompt": "检查这个只有后端 bundle 的 DSH 插件能否从 0.1.1
|
|
7
|
-
"expected_output": "
|
|
6
|
+
"prompt": "检查这个只有后端 bundle 的 DSH 插件能否从 DSH 0.1.1 升级到 0.1.2。它的 peerDependencies 仍是 ^0.1.1，不要改文件。",
|
|
7
|
+
"expected_output": "Records the plugin's actual version ranges, uses the current exact-ref catalog as the analysis baseline, identifies target range mismatch, and does not claim runtime compatibility.",
|
|
8
8
|
"expectations": [
|
|
9
9
|
"Uses migrate analyze before proposing edits",
|
|
10
|
+
"Distinguishes the requested 0.1.1 to 0.1.2 upgrade from the catalog's exact reference refs",
|
|
10
11
|
"Reports the exact verification status as analyzed",
|
|
11
12
|
"Does not write files or execute build scripts"
|
|
12
13
|
]
|
|
@@ -14,9 +15,11 @@
|
|
|
14
15
|
{
|
|
15
16
|
"id": 2,
|
|
16
17
|
"prompt": "把这个前端插件升级到 DSH 0.1.2。源码里有 import type { ClientContext, ISessions } from '@deepseek-ai/dsh-client-runtime/client'，可以安全改的帮我改，其他的列出来。",
|
|
17
|
-
"expected_output": "
|
|
18
|
+
"expected_output": "Recognizes that write authorization does not decide whether 0.1.1 may be dropped, asks the compatibility question, and waits before applying changes; after a 0.1.2-only answer, safely moves ClientContext while leaving ISessions as a semantic task.",
|
|
18
19
|
"expectations": [
|
|
19
20
|
"Detects type-only imports from source rather than relying on the bundle",
|
|
21
|
+
"Explicitly asks whether the same release must preserve DSH 0.1.1 compatibility",
|
|
22
|
+
"Does not preview, apply, edit, install, build, or run the plugin until that decision is answered",
|
|
20
23
|
"Uses migrate apply --safe and requires explicit confirmation for writes",
|
|
21
24
|
"Does not mechanically rewrite the semantic ISessions contract"
|
|
22
25
|
]
|
|
@@ -24,9 +27,10 @@
|
|
|
24
27
|
{
|
|
25
28
|
"id": 3,
|
|
26
29
|
"prompt": "完整升级这个混合前后端插件并验证，Harness 在 /workspace/deepseek-harness。构建失败也要把现场路径告诉我。",
|
|
27
|
-
"expected_output": "
|
|
30
|
+
"expected_output": "Analyzes first, asks whether the same release must retain 0.1.1, and waits before safe apply or executable gates; after the decision, performs the selected migration and verification matrix and reports retained failure state.",
|
|
28
31
|
"expectations": [
|
|
29
32
|
"Uses the exact Harness refs and verifies the catalog commits",
|
|
33
|
+
"Treats legacy compatibility as an explicit product decision rather than inferring it from an upgrade request",
|
|
30
34
|
"Runs static, build, then runtime verification in order",
|
|
31
35
|
"Uses a temporary DSH_HOME and reports retained failure state",
|
|
32
36
|
"Keeps business behavior verification separate from activation smoke"
|
|
@@ -35,13 +39,37 @@
|
|
|
35
39
|
{
|
|
36
40
|
"id": 4,
|
|
37
41
|
"prompt": "帮我升级这个插件，但机器上的 dsh-doctor 是旧版，而且我没有授权修改全局 npm 包。请先检查有没有新版本，再继续迁移。",
|
|
38
|
-
"expected_output": "Checks the registry read-only, selects one exact-version npx CLI with the required catalog, avoids global installation, and reports the selected version and update status.",
|
|
42
|
+
"expected_output": "Checks the registry read-only, selects one exact-version npx CLI with the required catalog, avoids global installation, asks for the unresolved compatibility intent, and reports the selected version and update status without starting writes or executable verification.",
|
|
39
43
|
"expectations": [
|
|
40
44
|
"Checks the local CLI version and exact migration catalog before use",
|
|
41
45
|
"Uses npm view as a read-only registry update check",
|
|
42
46
|
"Pins one resolved npx package version for all migration phases",
|
|
43
47
|
"Does not install or update a global CLI without explicit authorization",
|
|
44
|
-
"Reports local, registry, selected CLI, catalog, and update-status evidence"
|
|
48
|
+
"Reports local, registry, selected CLI, catalog, and update-status evidence",
|
|
49
|
+
"Stops at analyzed until the developer chooses 0.1.2-only or dual-version support"
|
|
50
|
+
]
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
"id": 5,
|
|
54
|
+
"prompt": "升级这个插件到 DSH 0.1.2，但同一个 npm 版本还必须继续支持 0.1.1。可以修改代码并执行测试；如果单一产物做不到，先告诉我冲突和可选方案，不要自行放弃旧版。",
|
|
55
|
+
"expected_output": "Records an explicit dual-version requirement, assesses whether imports, manifests, graph declarations, and artifacts can coexist, selects or proposes an adapter/conditional-build/separate-release strategy, and verifies both version rows before claiming compatibility.",
|
|
56
|
+
"expectations": [
|
|
57
|
+
"Records the compatibility intent as dual-version without asking a redundant question",
|
|
58
|
+
"Treats 0.1.2 safe codemods as candidates that still require 0.1.1 review",
|
|
59
|
+
"Does not widen peer ranges or claim one-artifact support without installation and runtime evidence",
|
|
60
|
+
"Separately verifies build, artifact, runtime, and behavior evidence for DSH 0.1.1 and 0.1.2",
|
|
61
|
+
"Reports an exact incompatibility and asks before switching to separate releases or dropping 0.1.1"
|
|
62
|
+
]
|
|
63
|
+
},
|
|
64
|
+
{
|
|
65
|
+
"id": 6,
|
|
66
|
+
"prompt": "这是一次 breaking release，只需要支持 DSH 0.1.2，不再兼容 0.1.1。先分析再按安全流程修改和验证。",
|
|
67
|
+
"expected_output": "Records the explicit 0.1.2-only intent without asking a redundant compatibility question, then follows analyze, safe preview/apply, semantic migration, and target verification gates.",
|
|
68
|
+
"expectations": [
|
|
69
|
+
"Records the compatibility intent as 0.1.2-only",
|
|
70
|
+
"Does not ask again whether 0.1.1 compatibility must be retained",
|
|
71
|
+
"Still separates write authorization from compatibility intent and follows preview and confirmation safeguards",
|
|
72
|
+
"Reports only the 0.1.2 verification evidence actually achieved"
|
|
45
73
|
]
|
|
46
74
|
}
|
|
47
75
|
]
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Compatibility strategy
|
|
2
|
+
|
|
3
|
+
## Decide before changing the plugin
|
|
4
|
+
|
|
5
|
+
Moving a plugin to 0.1.2 and preserving 0.1.1 are different deliverables. The 0.1.2 catalog describes target migrations; it does not prove that the resulting source, dependency graph, artifact, or manifest still works on 0.1.1.
|
|
6
|
+
|
|
7
|
+
Record one explicit intent:
|
|
8
|
+
|
|
9
|
+
| Intent | Meaning | Write policy |
|
|
10
|
+
| --- | --- | --- |
|
|
11
|
+
| `0.1.2-only` | The next plugin release may drop 0.1.1 | Follow the catalog migration after preview and authorization |
|
|
12
|
+
| `dual-version` | The same release must support both 0.1.1 and 0.1.2 | Design the compatibility mechanism and two-version verification matrix before editing |
|
|
13
|
+
| `pending developer decision` | The developer has not chosen | Read-only analysis only; stop before apply, edits, installs, build, or runtime execution |
|
|
14
|
+
|
|
15
|
+
Do not treat general write authorization as permission to drop an older runtime. If the request does not settle the choice, ask the developer directly.
|
|
16
|
+
|
|
17
|
+
## Assess whether one release can support both
|
|
18
|
+
|
|
19
|
+
For `dual-version`, inventory each migration finding and determine whether the old and new owners coexist:
|
|
20
|
+
|
|
21
|
+
- static imports of packages that exist in only one DSH version;
|
|
22
|
+
- changed Service names, snapshot shapes, lifecycle, or event behavior;
|
|
23
|
+
- client graph `inject`, `external`, platform modules, and client exports;
|
|
24
|
+
- peer, optional peer, development, and bundled dependency ranges;
|
|
25
|
+
- patch targets and profile entries that differ between Harness versions;
|
|
26
|
+
- generated output that may capture version-specific imports.
|
|
27
|
+
|
|
28
|
+
Choose a repository-appropriate same-release mechanism based on evidence, such as a shared compatibility adapter with runtime feature detection or conditional version-specific entry points/builds inside the same package. Do not invent dynamic loading when the bundler or Harness activation model cannot support it. Do not publish a peer range that claims both versions until installation and runtime evidence supports that range.
|
|
29
|
+
|
|
30
|
+
The safe codemod is intentionally target-oriented. In dual-version mode, preview its changes only after the decision is recorded and review each proposed import and dependency edit against 0.1.1 before applying it. Semantic migrations always require the same cross-version review.
|
|
31
|
+
|
|
32
|
+
If the same release cannot load because required packages or static graph declarations are mutually exclusive, report the exact conflict. Ask the developer whether to change scope to separate plugin releases or accept a 0.1.2-only release. Neither alternative satisfies the original same-release `dual-version` intent.
|
|
33
|
+
|
|
34
|
+
## Verify a two-version matrix
|
|
35
|
+
|
|
36
|
+
Use exact Harness versions or checkouts and keep evidence separate:
|
|
37
|
+
|
|
38
|
+
| Gate | DSH 0.1.1 | DSH 0.1.2 |
|
|
39
|
+
| --- | --- | --- |
|
|
40
|
+
| dependency installation and peer resolution | required | required |
|
|
41
|
+
| typecheck/build/test and packed artifact inspection | required | required |
|
|
42
|
+
| isolated profile install and activation smoke | required | required |
|
|
43
|
+
| plugin-specific UI, Service lifecycle, commands, settings, and cleanup | required where applicable | required where applicable |
|
|
44
|
+
|
|
45
|
+
The current migration catalog and `migrate verify` target 0.1.2. They do not independently certify the legacy row. Verify 0.1.1 with the plugin repository's supported scripts and an isolated profile using the actual 0.1.1 Harness CLI. Preserve failure workspaces and report the exact commands, versions, artifacts, logs, or screenshots for each row.
|
|
46
|
+
|
|
47
|
+
Use precise conclusions:
|
|
48
|
+
|
|
49
|
+
- `0.1.2 runtime-verified; 0.1.1 not tested` is not dual-compatible.
|
|
50
|
+
- Passing builds on both versions is not runtime or behavior proof.
|
|
51
|
+
- Claim `dual-version` compatibility only after all required matrix rows pass for the same release artifact or for the explicitly documented version-specific artifact strategy.
|