@bruc3van/dsh-doctor 0.5.1 → 0.5.3
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,241 @@
|
|
|
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
|
-
dsh-doctor migrate analyze /path/to/plugin \
|
|
37
|
-
--from dsh-v0.1.1-rc.2 \
|
|
38
|
-
--to dsh-v0.1.2-alpha.2 \
|
|
39
|
-
--harness-root /path/to/deepseek-harness
|
|
40
|
-
|
|
41
|
-
# Stage 2: preview exact rewrites; add --yes to write and create timestamped backups
|
|
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
|
|
46
|
-
|
|
47
|
-
# Stage 3: static, build, and isolated runtime verification in order
|
|
48
|
-
dsh-doctor migrate verify /path/to/plugin --level static \
|
|
49
|
-
--harness-root /path/to/deepseek-harness
|
|
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
|
|
22
|
+
npx skills add bruc3van/dsh-doctor
|
|
54
23
|
```
|
|
55
24
|
|
|
56
|
-
|
|
25
|
+
Then ask the agent from inside the plugin repository:
|
|
57
26
|
|
|
58
|
-
|
|
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.
|
|
30
|
+
```
|
|
59
31
|
|
|
60
|
-
|
|
32
|
+
The skill reminds the agent to work in this order:
|
|
61
33
|
|
|
62
|
-
|
|
34
|
+
1. inspect the plugin root, Harness checkout, package manager, and available DSH Doctor;
|
|
35
|
+
2. analyze source, type imports, dependencies, manifest, client graph, patches, and build output;
|
|
36
|
+
3. preview and apply code changes that are known to be equivalent;
|
|
37
|
+
4. use the new API owners to handle semantic changes that require understanding the plugin;
|
|
38
|
+
5. rebuild the plugin and run static, build, and isolated runtime verification;
|
|
39
|
+
6. report the changed files, remaining work, backups, and the verification level actually reached.
|
|
63
40
|
|
|
64
|
-
|
|
41
|
+
`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.
|
|
65
42
|
|
|
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` |
|
|
43
|
+
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.
|
|
71
44
|
|
|
72
|
-
|
|
45
|
+
## How it works
|
|
73
46
|
|
|
74
|
-
|
|
47
|
+
DSH Doctor has three parts:
|
|
75
48
|
|
|
76
|
-
|
|
49
|
+
- **Skill**: tells the agent which steps to follow, which actions need confirmation, and what to report;
|
|
50
|
+
- **CLI**: scans the plugin, lists problems, changes deterministic code, and runs verification;
|
|
51
|
+
- **Migration catalog**: records known package, API, Service, configuration, and behavior changes between the two DSH versions.
|
|
77
52
|
|
|
78
|
-
|
|
79
|
-
|---|---|---|
|
|
80
|
-
| store engine and equality helpers | `dsh-client-store` | exact (catalog-listed symbols) |
|
|
81
|
-
| Cordis client context type | `@deepseek-ai/cordis` `Context` | exact; preserve local aliases |
|
|
82
|
-
| session control / list / commands | `dsh-api-session-controller/client` | semantic (developer judgment required) |
|
|
83
|
-
| workspace state / commands | `dsh-api-workspace-controller/client` | semantic |
|
|
84
|
-
| conversation assembly | `dsh-client-ui-conversation/client` | semantic |
|
|
85
|
-
| pending-interaction state | domain UI packages aggregated by `ui-session` | semantic |
|
|
53
|
+
The workflow is:
|
|
86
54
|
|
|
87
|
-
|
|
55
|
+
```text
|
|
56
|
+
analyze
|
|
57
|
+
→ change deterministic code
|
|
58
|
+
→ agent handles semantic changes
|
|
59
|
+
→ rebuild
|
|
60
|
+
→ static verification
|
|
61
|
+
→ temporary-profile installation and activation
|
|
62
|
+
→ publish through the plugin's own release process
|
|
63
|
+
```
|
|
88
64
|
|
|
89
|
-
|
|
65
|
+
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.
|
|
90
66
|
|
|
91
|
-
|
|
67
|
+
## Why versioned rules are needed
|
|
92
68
|
|
|
93
|
-
|
|
69
|
+
DSH 0.1.2 changes more than package versions:
|
|
94
70
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
71
|
+
- `@deepseek-ai/dsh-client-runtime` was removed and has no single aggregate replacement;
|
|
72
|
+
- store features moved to `dsh-client-store`;
|
|
73
|
+
- Session, Workspace, Conversation, and pending interactions moved to separate controllers or UI packages;
|
|
74
|
+
- `@deepseek-ai/dsh-host-apiproxy` was removed, so browser calls move to the appropriate business Remote;
|
|
75
|
+
- client graph, platform externals, exports, and some profile patch targets also changed.
|
|
98
76
|
|
|
99
|
-
The
|
|
77
|
+
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.
|
|
100
78
|
|
|
101
|
-
|
|
79
|
+
## Coverage
|
|
102
80
|
|
|
103
|
-
|
|
81
|
+
| Area | How Doctor and the agent handle it |
|
|
82
|
+
|---|---|
|
|
83
|
+
| JS/TS imports, including type-only, aliased, and mixed imports | Analyzed with the TypeScript AST; symbols with a known equivalent can be rewritten |
|
|
84
|
+
| Removed or added DSH packages | Checked in source and manifest; dependencies are updated only when no remaining reference blocks the change |
|
|
85
|
+
| DSH/Cordis version ranges | Checks dependencies, devDependencies, and peerDependencies; existing peer ranges are not widened automatically |
|
|
86
|
+
| Session, Workspace, Conversation, and other semantic changes | Reports the new owner and reason; the agent modifies the business code |
|
|
87
|
+
| `dsh.client` and client exports | Checks inject, external, platform, immediately, and `exports["./client"]` |
|
|
88
|
+
| Harness patch targets | Compares old and new entries when an exact Harness checkout is available |
|
|
89
|
+
| Build output | Scans `lib`, `dist`, `build`, and `out` for old APIs |
|
|
90
|
+
| Plugin build | Runs existing typecheck, build, test, and pack:check scripts; build or pack:check is required for artifact verification |
|
|
91
|
+
| Installation and activation | Packs the real tarball and installs it into a fresh web profile under a temporary `DSH_HOME` |
|
|
92
|
+
| UI and business behavior | Not decided by Doctor; the agent or developer runs plugin-specific checks |
|
|
104
93
|
|
|
105
|
-
|
|
94
|
+
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.
|
|
106
95
|
|
|
107
|
-
|
|
96
|
+
## Safety
|
|
108
97
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
98
|
+
- `diagnose`, `migrate analyze`, and static verification are read-only and do not load or execute the inspected plugin;
|
|
99
|
+
- `migrate apply` requires `--safe`; without `--yes`, it only previews changes;
|
|
100
|
+
- only `exact` migrations are auto-edited; semantic changes are not guessed;
|
|
101
|
+
- SHA-256 is checked before writing, so a file changed after preview is rejected;
|
|
102
|
+
- existing files receive timestamped backups and are replaced atomically through a temporary file;
|
|
103
|
+
- build and runtime verification execute plugin scripts and therefore require explicit `--yes`;
|
|
104
|
+
- runtime verification uses a temporary `DSH_HOME`, not the normal `~/.dsh`;
|
|
105
|
+
- JSON, baselines, and recovery snapshots redact plugin configuration and common secret/token/password/key fields;
|
|
106
|
+
- global CLI installation, persistent quarantine, plugin removal, and publishing are never performed automatically by the skill.
|
|
112
107
|
|
|
113
|
-
|
|
108
|
+
## Use the migration CLI manually
|
|
114
109
|
|
|
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.
|
|
110
|
+
Node.js `^22.19.0` or `>=24.0.0` is required.
|
|
120
111
|
|
|
121
|
-
|
|
112
|
+
First confirm that the CLI contains the required migration:
|
|
122
113
|
|
|
123
114
|
```sh
|
|
124
|
-
dsh-doctor
|
|
125
|
-
dsh-doctor
|
|
126
|
-
dsh-doctor diagnose --check-updates
|
|
115
|
+
npx --yes --package=@bruc3van/dsh-doctor@0.5.3 \
|
|
116
|
+
dsh-doctor migrations list
|
|
127
117
|
```
|
|
128
118
|
|
|
129
|
-
|
|
119
|
+
### 1. Analyze
|
|
130
120
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
121
|
+
```sh
|
|
122
|
+
dsh-doctor migrate analyze /path/to/plugin \
|
|
123
|
+
--from dsh-v0.1.1-rc.2 \
|
|
124
|
+
--to dsh-v0.1.2-alpha.2 \
|
|
125
|
+
--harness-root /path/to/deepseek-harness \
|
|
126
|
+
--json
|
|
127
|
+
```
|
|
134
128
|
|
|
135
|
-
|
|
129
|
+
Analysis checks source, dependencies, manifest, client graph, patch targets, and existing build output without executing plugin code.
|
|
136
130
|
|
|
137
|
-
|
|
131
|
+
### 2. Apply
|
|
138
132
|
|
|
139
133
|
```sh
|
|
140
|
-
|
|
141
|
-
dsh-doctor
|
|
142
|
-
|
|
134
|
+
# Preview
|
|
135
|
+
dsh-doctor migrate apply /path/to/plugin --safe \
|
|
136
|
+
--harness-root /path/to/deepseek-harness --json
|
|
137
|
+
|
|
138
|
+
# Write after confirmation
|
|
139
|
+
dsh-doctor migrate apply /path/to/plugin --safe --yes \
|
|
140
|
+
--harness-root /path/to/deepseek-harness --json
|
|
143
141
|
```
|
|
144
142
|
|
|
145
|
-
|
|
143
|
+
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
144
|
|
|
147
|
-
|
|
145
|
+
### 3. Verify
|
|
148
146
|
|
|
149
147
|
```sh
|
|
150
|
-
dsh-doctor
|
|
151
|
-
|
|
152
|
-
dsh --
|
|
148
|
+
dsh-doctor migrate verify /path/to/plugin --level static \
|
|
149
|
+
--harness-root /path/to/deepseek-harness --json
|
|
150
|
+
dsh-doctor migrate verify /path/to/plugin --level build --yes \
|
|
151
|
+
--harness-root /path/to/deepseek-harness --json
|
|
152
|
+
dsh-doctor migrate verify /path/to/plugin --level runtime --yes \
|
|
153
|
+
--harness-root /path/to/deepseek-harness --json
|
|
153
154
|
```
|
|
154
155
|
|
|
155
|
-
|
|
156
|
+
| Level | What it checks |
|
|
157
|
+
|---|---|
|
|
158
|
+
| `static` | Rechecks source, manifest, client graph, patches, and artifacts |
|
|
159
|
+
| `build` | Runs the plugin's existing build/test scripts and scans the output again |
|
|
160
|
+
| `runtime` | Packs the real tarball and checks the target DSH version, installed package, bundle, and effective configuration in a temporary profile |
|
|
156
161
|
|
|
157
|
-
|
|
162
|
+
Verification states are:
|
|
158
163
|
|
|
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
|
|
164
|
+
```text
|
|
165
|
+
analyzed → source-migrated → artifact-verified → runtime-verified
|
|
165
166
|
```
|
|
166
167
|
|
|
167
|
-
|
|
168
|
+
`runtime-verified` means that packing, installation, and basic activation passed. It does not replace real UI, Service lifecycle, and business-flow testing.
|
|
168
169
|
|
|
169
|
-
|
|
170
|
+
## Diagnose DSH and installed plugins
|
|
171
|
+
|
|
172
|
+
Global installation:
|
|
170
173
|
|
|
171
174
|
```sh
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
dsh-doctor recover @scope/plugin --action rollback-quarantine \
|
|
175
|
-
--backup /path/to/cordis.patch.yml.dsh-doctor-...bak --yes
|
|
175
|
+
npm install --global @bruc3van/dsh-doctor
|
|
176
|
+
dsh-doctor diagnose
|
|
176
177
|
```
|
|
177
178
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
### Safe removal
|
|
181
|
-
|
|
182
|
-
Removal is always explicit and can never be inferred by legacy `--fix --yes`:
|
|
179
|
+
Temporary use:
|
|
183
180
|
|
|
184
181
|
```sh
|
|
185
|
-
dsh-doctor
|
|
186
|
-
dsh-doctor recover @scope/plugin --action remove --yes
|
|
182
|
+
npx @bruc3van/dsh-doctor diagnose
|
|
187
183
|
```
|
|
188
184
|
|
|
189
|
-
|
|
185
|
+
The default target is `$DSH_HOME/profiles/web`, falling back to `~/.dsh`.
|
|
190
186
|
|
|
191
187
|
```sh
|
|
192
|
-
dsh
|
|
188
|
+
dsh-doctor diagnose
|
|
189
|
+
dsh-doctor diagnose --json
|
|
190
|
+
dsh-doctor diagnose --check-updates
|
|
193
191
|
```
|
|
194
192
|
|
|
195
|
-
|
|
193
|
+
Diagnosis composes configuration in DSH order:
|
|
196
194
|
|
|
197
|
-
|
|
195
|
+
```text
|
|
196
|
+
bundle layers → profile cordis.patch.yml → home cordis.patch.yml → CLI overlays
|
|
197
|
+
```
|
|
198
198
|
|
|
199
|
-
|
|
199
|
+
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
200
|
|
|
201
|
-
|
|
201
|
+
## Recovery operations
|
|
202
202
|
|
|
203
203
|
```sh
|
|
204
|
-
|
|
205
|
-
dsh-doctor
|
|
204
|
+
# Check and install the highest manifest-declared compatible version
|
|
205
|
+
dsh-doctor recover @scope/plugin --action check-update
|
|
206
|
+
dsh-doctor recover @scope/plugin --action update
|
|
207
|
+
dsh-doctor recover @scope/plugin --action update --yes
|
|
206
208
|
|
|
207
|
-
#
|
|
208
|
-
dsh-doctor
|
|
209
|
-
|
|
210
|
-
```
|
|
209
|
+
# Create a temporary quarantine overlay
|
|
210
|
+
dsh-doctor recover @scope/plugin --action quarantine \
|
|
211
|
+
--output ./plugin-quarantine.yml
|
|
211
212
|
|
|
212
|
-
|
|
213
|
+
# Persist it only after testing the temporary overlay
|
|
214
|
+
dsh-doctor recover @scope/plugin --action persist-quarantine --verified
|
|
215
|
+
dsh-doctor recover @scope/plugin --action persist-quarantine --verified --yes
|
|
213
216
|
|
|
214
|
-
|
|
217
|
+
# Removal is always separate
|
|
218
|
+
dsh-doctor recover @scope/plugin --action remove
|
|
219
|
+
dsh-doctor recover @scope/plugin --action remove --yes
|
|
220
|
+
```
|
|
215
221
|
|
|
216
|
-
|
|
222
|
+
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.
|
|
223
|
+
|
|
224
|
+
You can also save and compare a baseline around an upgrade:
|
|
217
225
|
|
|
218
226
|
```sh
|
|
219
|
-
dsh-doctor
|
|
220
|
-
dsh-doctor
|
|
227
|
+
dsh-doctor baseline create
|
|
228
|
+
dsh-doctor baseline compare
|
|
221
229
|
```
|
|
222
230
|
|
|
223
|
-
---
|
|
224
|
-
|
|
225
231
|
## Output and exit codes
|
|
226
232
|
|
|
227
|
-
Text output supports Chinese and English. `--json`
|
|
233
|
+
Text output supports Chinese and English. `--json` uses stable English codes and keeps redacted structured evidence.
|
|
228
234
|
|
|
229
235
|
| Exit code | Meaning |
|
|
230
236
|
|---|---|
|
|
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.
|
|
237
|
+
| `0` | No blocker remains, or the action completed and passed its verification |
|
|
238
|
+
| `1` | Compatibility issues, semantic migration, or verification work remains |
|
|
239
|
+
| `2` | Argument, environment, or action-execution failure |
|
|
242
240
|
|
|
243
241
|
## Development
|
|
244
242
|
|
|
@@ -248,4 +246,6 @@ npm run check
|
|
|
248
246
|
npm pack --dry-run
|
|
249
247
|
```
|
|
250
248
|
|
|
251
|
-
|
|
249
|
+
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.
|
|
250
|
+
|
|
251
|
+
Local development, the skill, and the CLI never commit, tag, or publish automatically.
|
package/README.md
CHANGED
|
@@ -2,245 +2,243 @@
|
|
|
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
|
-
dsh-doctor migrate analyze /path/to/plugin \
|
|
37
|
-
--from dsh-v0.1.1-rc.2 \
|
|
38
|
-
--to dsh-v0.1.2-alpha.2 \
|
|
39
|
-
--harness-root /path/to/deepseek-harness
|
|
40
|
-
|
|
41
|
-
# 阶段 2：预览精确改写；加 --yes 才写入并创建时间戳备份
|
|
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
|
|
46
|
-
|
|
47
|
-
# 阶段 3：依次完成静态、构建和隔离运行时验证
|
|
48
|
-
dsh-doctor migrate verify /path/to/plugin --level static \
|
|
49
|
-
--harness-root /path/to/deepseek-harness
|
|
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
|
|
22
|
+
npx skills add bruc3van/dsh-doctor
|
|
54
23
|
```
|
|
55
24
|
|
|
56
|
-
|
|
25
|
+
然后在插件仓库中告诉 Agent：
|
|
57
26
|
|
|
58
|
-
|
|
27
|
+
```text
|
|
28
|
+
请把当前插件从 DSH 0.1.1 升级到 DSH 0.1.2。
|
|
29
|
+
先分析兼容问题，再修改代码，最后完成构建和运行时验证。
|
|
30
|
+
```
|
|
59
31
|
|
|
60
|
-
|
|
32
|
+
Skill 会提醒 Agent 按下面的顺序工作：
|
|
61
33
|
|
|
62
|
-
|
|
34
|
+
1. 检查插件目录、Harness checkout、包管理器和可用的 DSH Doctor；
|
|
35
|
+
2. 分析源码、类型导入、依赖、manifest、client graph、patch 和构建产物；
|
|
36
|
+
3. 预览并应用可以确定等价的代码修改；
|
|
37
|
+
4. 根据新的 API 所有者处理需要理解业务的语义迁移；
|
|
38
|
+
5. 重新构建插件，并依次做静态、构建和隔离运行时验证；
|
|
39
|
+
6. 报告修改内容、剩余问题、备份和实际达到的验证等级。
|
|
63
40
|
|
|
64
|
-
|
|
41
|
+
`npx skills add` 只安装 Agent 指令，不会安装全局 DSH Doctor。Skill 会先检查本地 CLI 和 npm registry；本地版本不合适时，默认使用固定版本的 `npx`，不会自行修改全局 npm 安装。
|
|
65
42
|
|
|
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` |
|
|
43
|
+
验证完成后，可以再让 Agent 按插件仓库原有的版本和发布流程提交、打 tag、发布。Skill 本身不会自动提交或发布。
|
|
71
44
|
|
|
72
|
-
|
|
45
|
+
## 工作方式
|
|
73
46
|
|
|
74
|
-
|
|
47
|
+
DSH Doctor 由三部分组成：
|
|
75
48
|
|
|
76
|
-
|
|
49
|
+
- **Skill**：告诉 Agent 升级步骤、哪些操作需要确认，以及最后应该报告什么；
|
|
50
|
+
- **CLI**：扫描插件、生成问题清单、修改确定性代码，并执行分级验证；
|
|
51
|
+
- **Migration catalog**：记录两个 DSH 版本之间已确认的包、API、Service、配置和行为变化。
|
|
77
52
|
|
|
78
|
-
|
|
79
|
-
|---|---|---|
|
|
80
|
-
| store 引擎与 equality helpers | `dsh-client-store` | 精确（catalog 已列举符号） |
|
|
81
|
-
| Cordis 客户端 context 类型 | `@deepseek-ai/cordis` `Context` | 精确；保留本地别名 |
|
|
82
|
-
| session 控制/列表/命令 | `dsh-api-session-controller/client` | 语义（需开发者判断） |
|
|
83
|
-
| workspace 状态/命令 | `dsh-api-workspace-controller/client` | 语义 |
|
|
84
|
-
| conversation 组装 | `dsh-client-ui-conversation/client` | 语义 |
|
|
85
|
-
| pending interaction 状态 | ui-session 聚合的各 UI 包 | 语义 |
|
|
53
|
+
完整流程是：
|
|
86
54
|
|
|
87
|
-
|
|
55
|
+
```text
|
|
56
|
+
分析问题
|
|
57
|
+
→ 修改确定性代码
|
|
58
|
+
→ Agent 处理语义变化
|
|
59
|
+
→ 重新构建
|
|
60
|
+
→ 静态验证
|
|
61
|
+
→ 临时 profile 安装与激活验证
|
|
62
|
+
→ 按插件自己的流程发布
|
|
63
|
+
```
|
|
88
64
|
|
|
89
|
-
|
|
65
|
+
CLI 只自动修改 catalog 标记为 `exact` 的迁移。Session、Workspace、Conversation、pending interaction 等所有权和生命周期变化会标记为 `MIG_SEMANTIC_API_CHANGE`，由 Agent 结合插件代码处理，不会机械替换。
|
|
90
66
|
|
|
91
|
-
|
|
67
|
+
## 为什么需要版本化规则
|
|
92
68
|
|
|
93
|
-
|
|
69
|
+
DSH 0.1.2 不只是包版本变化，一些能力被拆分到了新的所有者：
|
|
94
70
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
71
|
+
- `@deepseek-ai/dsh-client-runtime` 已移除，没有一个新的聚合包可以直接替换；
|
|
72
|
+
- store 能力迁移到 `dsh-client-store`；
|
|
73
|
+
- Session、Workspace、Conversation 和 pending interaction 分别由新的 controller 或 UI 包负责；
|
|
74
|
+
- `@deepseek-ai/dsh-host-apiproxy` 已移除，浏览器调用需要迁移到对应业务 Remote；
|
|
75
|
+
- client graph、platform external、exports 和部分 profile patch target 也发生了变化。
|
|
98
76
|
|
|
99
|
-
|
|
77
|
+
Migration catalog 保存 source/target tag 和 Git commit，并记录 package、symbol、Service 和配置规则。提供 `--harness-root` 时，CLI 还会确认两个 tag 对应的 commit，并比较目标 web profile 中的 entry id。这样 Agent 可以基于明确的版本差异修改代码，而不是猜测新 API。
|
|
100
78
|
|
|
101
|
-
|
|
79
|
+
## 覆盖范围
|
|
102
80
|
|
|
103
|
-
|
|
81
|
+
| 检查内容 | Doctor/Agent 如何处理 |
|
|
82
|
+
|---|---|
|
|
83
|
+
| JS/TS import，包括 `import type`、别名和混合 import | 使用 TypeScript AST 分析；确定等价的 symbol 可自动改写 |
|
|
84
|
+
| 移除或新增的 DSH 包 | 检查源码和 manifest；没有残留引用时更新依赖 |
|
|
85
|
+
| DSH/Cordis 版本范围 | 检查 dependencies、devDependencies 和 peerDependencies；不自动扩大已有 peer 范围 |
|
|
86
|
+
| Session、Workspace、Conversation 等语义变化 | 报告新 owner 和变化原因，由 Agent 修改业务代码 |
|
|
87
|
+
| `dsh.client` 和 client export | 检查 inject、external、platform、immediately 和 `exports["./client"]` |
|
|
88
|
+
| Harness patch target | 有精确 Harness checkout 时比较新旧 entry |
|
|
89
|
+
| 构建产物 | 检查 `lib`、`dist`、`build`、`out` 中是否仍包含旧 API |
|
|
90
|
+
| 插件构建 | 运行项目已有的 typecheck、build、test、pack:check；必须有 build 或 pack:check 才算产物已验证 |
|
|
91
|
+
| 安装和激活 | 打包真实 tarball，安装到临时 `DSH_HOME` 的新 web profile 中验证 |
|
|
92
|
+
| UI 和业务行为 | Doctor 不自动判断；需要 Agent 或开发者执行插件自己的测试 |
|
|
104
93
|
|
|
105
|
-
|
|
94
|
+
源码分析使用 TypeScript AST，并同时检查 manifest、client graph 和构建产物。因此，bundle 中没有旧字符串并不代表源码已经兼容，源码编译通过也不代表发布产物和运行时已经兼容。
|
|
106
95
|
|
|
107
|
-
|
|
96
|
+
## 安全性
|
|
108
97
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
98
|
+
- `diagnose`、`migrate analyze` 和静态验证只读，不加载或执行待检查插件；
|
|
99
|
+
- `migrate apply` 必须带 `--safe`，没有 `--yes` 时只展示将要修改的内容；
|
|
100
|
+
- 只有 `exact` 迁移会自动改代码，语义变化不会自动猜测；
|
|
101
|
+
- 写入前检查文件 SHA-256，预览后文件发生变化会拒绝写入；
|
|
102
|
+
- 修改已有文件前创建时间戳备份，并使用临时文件原子替换；
|
|
103
|
+
- build 和 runtime 会执行插件脚本，因此必须显式使用 `--yes`；
|
|
104
|
+
- runtime 使用临时 `DSH_HOME`，不会安装到正常的 `~/.dsh`；
|
|
105
|
+
- JSON、baseline 和恢复快照会脱敏插件配置和常见 secret/token/password/key 字段；
|
|
106
|
+
- 全局 CLI 安装、持久隔离、删除插件和发布都不会由 Skill 自动执行。
|
|
112
107
|
|
|
113
|
-
|
|
108
|
+
## 手动使用迁移 CLI
|
|
114
109
|
|
|
115
|
-
|
|
116
|
-
- 重复 entry id、重复插件 mount；
|
|
117
|
-
- 高层禁用、结构替换、group/config 整体覆盖；
|
|
118
|
-
- bundle 声明与 profile 激活状态冲突；
|
|
119
|
-
- 插件版本、产物、client contract、依赖与运行环境问题。
|
|
110
|
+
需要 Node.js `^22.19.0` 或 `>=24.0.0`。
|
|
120
111
|
|
|
121
|
-
|
|
112
|
+
先确认 CLI 包含需要的迁移：
|
|
122
113
|
|
|
123
114
|
```sh
|
|
124
|
-
dsh-doctor
|
|
125
|
-
dsh-doctor
|
|
126
|
-
dsh-doctor diagnose --check-updates
|
|
115
|
+
npx --yes --package=@bruc3van/dsh-doctor@0.5.3 \
|
|
116
|
+
dsh-doctor migrations list
|
|
127
117
|
```
|
|
128
118
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
---
|
|
119
|
+
### 1. 分析
|
|
132
120
|
|
|
133
|
-
|
|
121
|
+
```sh
|
|
122
|
+
dsh-doctor migrate analyze /path/to/plugin \
|
|
123
|
+
--from dsh-v0.1.1-rc.2 \
|
|
124
|
+
--to dsh-v0.1.2-alpha.2 \
|
|
125
|
+
--harness-root /path/to/deepseek-harness \
|
|
126
|
+
--json
|
|
127
|
+
```
|
|
134
128
|
|
|
135
|
-
|
|
129
|
+
分析会检查源码、依赖、manifest、client graph、patch target 和已有构建产物，不执行插件代码。
|
|
136
130
|
|
|
137
|
-
|
|
131
|
+
### 2. 修改
|
|
138
132
|
|
|
139
133
|
```sh
|
|
140
|
-
|
|
141
|
-
dsh-doctor
|
|
142
|
-
|
|
134
|
+
# 预览
|
|
135
|
+
dsh-doctor migrate apply /path/to/plugin --safe \
|
|
136
|
+
--harness-root /path/to/deepseek-harness --json
|
|
137
|
+
|
|
138
|
+
# 确认后写入
|
|
139
|
+
dsh-doctor migrate apply /path/to/plugin --safe --yes \
|
|
140
|
+
--harness-root /path/to/deepseek-harness --json
|
|
143
141
|
```
|
|
144
142
|
|
|
145
|
-
|
|
143
|
+
Apply 可以拆分混合 import、移动精确 symbol、保留语义 symbol，并更新确定可以调整的开发依赖。每个被修改的文件都会保留备份。
|
|
146
144
|
|
|
147
|
-
|
|
145
|
+
### 3. 验证
|
|
148
146
|
|
|
149
147
|
```sh
|
|
150
|
-
dsh-doctor
|
|
151
|
-
|
|
152
|
-
dsh --
|
|
148
|
+
dsh-doctor migrate verify /path/to/plugin --level static \
|
|
149
|
+
--harness-root /path/to/deepseek-harness --json
|
|
150
|
+
dsh-doctor migrate verify /path/to/plugin --level build --yes \
|
|
151
|
+
--harness-root /path/to/deepseek-harness --json
|
|
152
|
+
dsh-doctor migrate verify /path/to/plugin --level runtime --yes \
|
|
153
|
+
--harness-root /path/to/deepseek-harness --json
|
|
153
154
|
```
|
|
154
155
|
|
|
155
|
-
|
|
156
|
+
| 级别 | 验证内容 |
|
|
157
|
+
|---|---|
|
|
158
|
+
| `static` | 再次检查源码、manifest、client graph、patch 和产物 |
|
|
159
|
+
| `build` | 运行插件已有的构建与测试脚本，并在构建后重新扫描产物 |
|
|
160
|
+
| `runtime` | 打真实 tarball，在临时 profile 中验证目标 DSH 版本、安装包、bundle 和生效配置 |
|
|
156
161
|
|
|
157
|
-
|
|
162
|
+
验证状态依次是：
|
|
158
163
|
|
|
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
|
|
164
|
+
```text
|
|
165
|
+
analyzed → source-migrated → artifact-verified → runtime-verified
|
|
165
166
|
```
|
|
166
167
|
|
|
167
|
-
|
|
168
|
+
`runtime-verified` 只表示插件能够完成打包、安装和基本激活，仍不能代替真实 UI、Service 生命周期和业务流程验证。
|
|
169
|
+
|
|
170
|
+
## DSH 和已安装插件诊断
|
|
168
171
|
|
|
169
|
-
|
|
172
|
+
全局安装：
|
|
170
173
|
|
|
171
174
|
```sh
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
dsh-doctor recover @scope/plugin --action rollback-quarantine \
|
|
175
|
-
--backup /path/to/cordis.patch.yml.dsh-doctor-...bak --yes
|
|
175
|
+
npm install --global @bruc3van/dsh-doctor
|
|
176
|
+
dsh-doctor diagnose
|
|
176
177
|
```
|
|
177
178
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
### 安全删除
|
|
181
|
-
|
|
182
|
-
删除是独立动作，永远不会由通用 `--fix --yes` 推断：
|
|
179
|
+
临时运行：
|
|
183
180
|
|
|
184
181
|
```sh
|
|
185
|
-
dsh-doctor
|
|
186
|
-
dsh-doctor recover @scope/plugin --action remove --yes # 显式执行
|
|
182
|
+
npx @bruc3van/dsh-doctor diagnose
|
|
187
183
|
```
|
|
188
184
|
|
|
189
|
-
|
|
185
|
+
默认检查 `$DSH_HOME/profiles/web`；未设置 `DSH_HOME` 时使用 `~/.dsh`。
|
|
190
186
|
|
|
191
187
|
```sh
|
|
192
|
-
dsh
|
|
188
|
+
dsh-doctor diagnose
|
|
189
|
+
dsh-doctor diagnose --json
|
|
190
|
+
dsh-doctor diagnose --check-updates
|
|
193
191
|
```
|
|
194
192
|
|
|
195
|
-
|
|
193
|
+
诊断按 DSH 的顺序组合配置：
|
|
196
194
|
|
|
197
|
-
|
|
195
|
+
```text
|
|
196
|
+
bundle layers → profile cordis.patch.yml → home cordis.patch.yml → CLI overlays
|
|
197
|
+
```
|
|
198
198
|
|
|
199
|
-
|
|
199
|
+
它会检查插件版本和 peer、Node engines、安装与 lockfile、bundle 与 patch、client contract、重复 mount、高层配置覆盖，以及 DSH CLI/Harness 版本漂移。普通诊断不访问网络；只有 `--check-updates` 和 recovery 操作会访问 npm registry。
|
|
200
200
|
|
|
201
|
-
|
|
201
|
+
## 恢复操作
|
|
202
202
|
|
|
203
203
|
```sh
|
|
204
|
-
|
|
205
|
-
dsh-doctor
|
|
204
|
+
# 检查和安装 manifest 声明兼容的最高版本
|
|
205
|
+
dsh-doctor recover @scope/plugin --action check-update
|
|
206
|
+
dsh-doctor recover @scope/plugin --action update
|
|
207
|
+
dsh-doctor recover @scope/plugin --action update --yes
|
|
206
208
|
|
|
207
|
-
#
|
|
208
|
-
dsh-doctor
|
|
209
|
-
|
|
210
|
-
```
|
|
209
|
+
# 生成临时隔离 overlay
|
|
210
|
+
dsh-doctor recover @scope/plugin --action quarantine \
|
|
211
|
+
--output ./plugin-quarantine.yml
|
|
211
212
|
|
|
212
|
-
|
|
213
|
+
# 验证临时 overlay 后持久化
|
|
214
|
+
dsh-doctor recover @scope/plugin --action persist-quarantine --verified
|
|
215
|
+
dsh-doctor recover @scope/plugin --action persist-quarantine --verified --yes
|
|
213
216
|
|
|
214
|
-
|
|
217
|
+
# 删除始终需要单独执行
|
|
218
|
+
dsh-doctor recover @scope/plugin --action remove
|
|
219
|
+
dsh-doctor recover @scope/plugin --action remove --yes
|
|
220
|
+
```
|
|
215
221
|
|
|
216
|
-
|
|
222
|
+
Doctor 会在隔离和删除前检查 entry、配置层、直接依赖、核心 bundle、lockfile、手工 mount 和已知 client dependents。静态检查无法确认动态 Service 依赖和外部数据，操作后仍需重启 profile 并验证主要功能。
|
|
223
|
+
|
|
224
|
+
升级前后也可以保存和比较基线：
|
|
217
225
|
|
|
218
226
|
```sh
|
|
219
|
-
dsh-doctor
|
|
220
|
-
dsh-doctor
|
|
227
|
+
dsh-doctor baseline create
|
|
228
|
+
dsh-doctor baseline compare
|
|
221
229
|
```
|
|
222
230
|
|
|
223
|
-
---
|
|
224
|
-
|
|
225
231
|
## 输出与退出码
|
|
226
232
|
|
|
227
|
-
|
|
233
|
+
文本支持中文和英文，`--json` 使用稳定英文 code 并保留脱敏后的结构化证据。
|
|
228
234
|
|
|
229
235
|
| 退出码 | 含义 |
|
|
230
236
|
|---|---|
|
|
231
|
-
| `0` |
|
|
232
|
-
| `1` |
|
|
233
|
-
| `2` |
|
|
234
|
-
|
|
235
|
-
## 安全边界
|
|
237
|
+
| `0` | 没有阻断错误，或操作完成并通过对应验证 |
|
|
238
|
+
| `1` | 仍有兼容问题、语义迁移或验证未完成 |
|
|
239
|
+
| `2` | 参数、运行环境或操作执行失败 |
|
|
236
240
|
|
|
237
|
-
|
|
238
|
-
- registry 结果只证明 manifest 声明，不证明真实运行兼容；
|
|
239
|
-
- 动态 Service 依赖、外部副作用、真实 UI 和业务流程需要用户验证；
|
|
240
|
-
- patch 精确编辑只处理 Doctor 能安全解析和定位的结构；有歧义时拒绝自动操作；
|
|
241
|
-
- 添加、更新或删除 bundle 后，运行中的 profile 不会自动改变 bundle 集合，必须重启。
|
|
242
|
-
|
|
243
|
-
## 从源码开发
|
|
241
|
+
## 开发
|
|
244
242
|
|
|
245
243
|
```sh
|
|
246
244
|
npm install
|
|
@@ -248,4 +246,6 @@ npm run check
|
|
|
248
246
|
npm pack --dry-run
|
|
249
247
|
```
|
|
250
248
|
|
|
251
|
-
|
|
249
|
+
测试覆盖 CLI、配置组合、诊断、脱敏、备份与写入保护、AST 迁移、构建门控、隔离运行时验证和恢复操作。CI 在 macOS、Ubuntu 和 Windows 上测试 Node.js `22.19` 与 `24`。
|
|
250
|
+
|
|
251
|
+
本地开发、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.3",
|
|
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. 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,17 +15,21 @@ 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;
|
|
17
19
|
- whether the developer authorizes writes and project command execution;
|
|
20
|
+
- whether the developer authorizes a global CLI install or update;
|
|
18
21
|
- the plugin's package manager and build scripts.
|
|
19
22
|
|
|
20
|
-
Use these
|
|
23
|
+
Use these catalog reference points in the current CLI commands:
|
|
21
24
|
|
|
22
25
|
- source: `dsh-v0.1.1-rc.2`
|
|
23
26
|
- target: `dsh-v0.1.2-alpha.2`
|
|
24
27
|
|
|
25
|
-
Read [migration-map.md](references/migration-map.md) before making semantic changes
|
|
28
|
+
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
|
+
|
|
30
|
+
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.
|
|
26
31
|
|
|
27
|
-
|
|
32
|
+
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.
|
|
28
33
|
|
|
29
34
|
## Phase 1: analyze
|
|
30
35
|
|
|
@@ -85,6 +90,10 @@ On failure, preserve and report the temporary directory. On success, the CLI rem
|
|
|
85
90
|
|
|
86
91
|
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.
|
|
87
92
|
|
|
93
|
+
## Prepare for release when requested
|
|
94
|
+
|
|
95
|
+
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.
|
|
96
|
+
|
|
88
97
|
## Report the outcome
|
|
89
98
|
|
|
90
99
|
State the highest achieved gate exactly:
|
|
@@ -96,3 +105,5 @@ State the highest achieved gate exactly:
|
|
|
96
105
|
- behavior verified separately with named evidence
|
|
97
106
|
|
|
98
107
|
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.
|
|
108
|
+
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.
|
|
109
|
+
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.
|
|
@@ -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
|
]
|
|
@@ -31,6 +32,18 @@
|
|
|
31
32
|
"Uses a temporary DSH_HOME and reports retained failure state",
|
|
32
33
|
"Keeps business behavior verification separate from activation smoke"
|
|
33
34
|
]
|
|
35
|
+
},
|
|
36
|
+
{
|
|
37
|
+
"id": 4,
|
|
38
|
+
"prompt": "帮我升级这个插件，但机器上的 dsh-doctor 是旧版，而且我没有授权修改全局 npm 包。请先检查有没有新版本，再继续迁移。",
|
|
39
|
+
"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.",
|
|
40
|
+
"expectations": [
|
|
41
|
+
"Checks the local CLI version and exact migration catalog before use",
|
|
42
|
+
"Uses npm view as a read-only registry update check",
|
|
43
|
+
"Pins one resolved npx package version for all migration phases",
|
|
44
|
+
"Does not install or update a global CLI without explicit authorization",
|
|
45
|
+
"Reports local, registry, selected CLI, catalog, and update-status evidence"
|
|
46
|
+
]
|
|
34
47
|
}
|
|
35
48
|
]
|
|
36
49
|
}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# DSH Doctor CLI bootstrap
|
|
2
|
+
|
|
3
|
+
Choose the CLI once before analysis so every migration phase uses the same implementation and catalog.
|
|
4
|
+
|
|
5
|
+
## 1. Inspect the environment
|
|
6
|
+
|
|
7
|
+
Confirm Node.js satisfies the package engine (`^22.19.0` or `>=24.0.0`). When `dsh-doctor` is available, run:
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
dsh-doctor --version
|
|
11
|
+
dsh-doctor migrations list --json
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Record the local version and whether the exact `dsh-v0.1.1-rc.2` to `dsh-v0.1.2-alpha.2` catalog is present. A command that exists but lacks this catalog is not usable for this skill.
|
|
15
|
+
|
|
16
|
+
## 2. Check the registry without changing the machine
|
|
17
|
+
|
|
18
|
+
Query the official registry:
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
npm view @bruc3van/dsh-doctor version --registry=https://registry.npmjs.org
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
This is a read-only update check. If it fails because the registry is unavailable, report update status as `unknown`; do not describe the local CLI as current. An offline local CLI may still be used when it exposes the exact required catalog.
|
|
25
|
+
|
|
26
|
+
## 3. Select and pin one invocation
|
|
27
|
+
|
|
28
|
+
- When the local version equals the registry version and exposes the catalog, use `dsh-doctor` directly.
|
|
29
|
+
- When the local CLI is missing, differs from the registry version, or lacks the catalog, prefer the registry version through exact-version npx. First verify that version exposes the required catalog:
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
npx --yes --package=@bruc3van/dsh-doctor@<registry-version> dsh-doctor migrations list --json
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
- When the registry is unavailable, use the local CLI only if its catalog check passed.
|
|
36
|
+
- When neither candidate exposes the catalog, stop and report the missing prerequisite instead of guessing a compatible CLI.
|
|
37
|
+
- Respect an explicit developer request to use a particular local or development CLI, but still record its version and verify the catalog.
|
|
38
|
+
|
|
39
|
+
After selecting a version, replace `<registry-version>` with the resolved exact version in every npx command. Do not use `@latest` separately in analyze, apply, and verify because the resolved package could change during the migration.
|
|
40
|
+
|
|
41
|
+
## 4. Keep global installation separately authorized
|
|
42
|
+
|
|
43
|
+
The skill installation does not authorize system-wide npm changes. Only after the developer explicitly approves a global install or update may the agent run:
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
npm install --global @bruc3van/dsh-doctor@<selected-version>
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Afterwards, re-run `dsh-doctor --version` and `dsh-doctor migrations list --json`. If either result differs from the selected version or required catalog, stop rather than falling back silently.
|
|
50
|
+
|
|
51
|
+
## 5. Preserve evidence
|
|
52
|
+
|
|
53
|
+
Include these fields in the handoff:
|
|
54
|
+
|
|
55
|
+
- local CLI version or `missing`;
|
|
56
|
+
- registry version or `unknown`;
|
|
57
|
+
- selected exact version and invocation source (`local`, `npx`, or authorized `global-install`);
|
|
58
|
+
- required catalog present or absent;
|
|
59
|
+
- update status: `current`, `outdated`, `missing`, or `unknown`.
|