dsh plugin --profile <name> add dsh-plugin-upgrade

📖 Ecosystem knowledge base — measured data, not marketing: plugin development guide · plugin-selection data · maintenance criteria.

Install & uninstall

dsh plugin --profile web add dsh-plugin-upgrade            # from npm
dsh plugin --profile web add github:PerryLink/dsh-plugin-upgrade   # from source
dsh plugin --profile web remove dsh-plugin-upgrade         # uninstall (reversible)

Installing the bundle only registers a skill; removing the row removes the skill. The CLI is a normal npx target and needs no profile at all.

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（95 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

English: part of a 95 plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

What is dsh-plugin-upgrade?

Plugin upgrade skill for DeepSeek Harness — one package, one corridor index, two closed corridors: 0.1.3-alpha.1 → 0.1.5-rc.1 (legAB) and 0.1.5-rc.2 → 0.1.6-alpha.2 (legC).

The scanner routes itself: it reads the target repository's declared dsh band (or takes --span), then applies that corridor's own evidence-bound catalog — legAB's 20 seams (leg A 0.1.3-alpha.1 → 0.1.5-alpha.1 plus leg B 0.1.5-alpha.1 → 0.1.5-rc.1) or legC's 5 seams (E1–E5). One entry point, so a client half that stopped mounting silently is never mistaken for "typecheck is green".

Workflow overview: call → plugin → result. The examples below use the real command surface.

Comparison

40 family repos swept · README §What you get (leg A, 2026-09-09)

Compatibility

What you get

Two halves, one seam catalog per corridor:

• A bundled agent skill (plugin-upgrade) — the corridor cards and a fix-and-verify loop. The body first routes the caller to the corridor that matches its peer band; the model loads it only when a task actually needs it, and the package contributes no system-prompt paragraph and no tool.
• A zero-dependency CLI (dsh-plugin-upgrade-scan) — resolves the corridor and reports file:line facts for that corridor's seams: legAB's twenty (S3, S8, S9, M1, S4, S5, S6, S7, S2, S1, S10, C1, C2, P1, C4, C5, H1, H2, H4, H3) re-read from the harness tag ranges on 2026-09-09 (leg A) and 2026-09-10 (leg B), or legC's five (E1–E5) measured on dsh-v0.1.7-alpha.1 (2026-09-19). Exit 1 on any error-severity hit, so it drops straight into CI.

The point is the failure mode this corridor exists to kill: this span's breakage is mostly silent, from both ends. The type line can be stale, so the repo compiles against the old catalog (seam M1), and the bare conversation client slot was deleted with no alias while ctx.slots.inject() only runs its callback when the declaration exists — so a client half that still targets it stops mounting with no error, no log line and no failed build (seam C1). Three classes of breakage survive typecheck + test:

1. the local gate compiles a stale type line — old paths alias, or dev/test types pinned at 0.1.5-alpha.* (seam M1);
2. a log writer omits the V3 required stream field, so the session imports and then refuses to resume (seam S3);
3. the tests are mocked against the old shape, so they pass while the host drops the contribution (seam C1).

Honest sizing: leg B's workspace sweep found that the family's client halves use only 8 slot keys, all of which survive in rc.1 — for them the rc.1 breakage is latent, not actual. Third-party client plugins that targeted the bare conversation key are the ones that break, and they break quietly. Leg A's sweep found the opposite texture: 40 repos, 11 of them hit M1, and fixing the stale path exposed real TypeScript errors in 3 repos that were previously "green".

Quick start

dsh plugin --profile web add github:PerryLink/dsh-plugin-upgrade

# 1. install the bundle into your profile
dsh plugin --profile web add dsh-plugin-upgrade

# 2. verify the row mounted
dsh --profile web --dump-config | grep -A3 'id: dsh-plugin-upgrade'

# 3. scan the plugin you are upgrading
npx dsh-plugin-upgrade-scan --repo ../my-plugin

Then ask the agent to use the plugin-upgrade skill, or drive the loop yourself with the card that matches your band: skills/plugin-upgrade/references/v0.1.3-alpha.1-to-v0.1.5-rc.1.md (legAB — leg A is §1, leg B is §2, the merged seam index is §3) or skills/plugin-upgrade/references/v0.1.5-rc.2-to-v0.1.6-alpha.2.md (legC). The scanner picks the corridor for you; add --span legC when the declared band is ambiguous.

Examples

These are the plugin's real entry points; install once, then call one.

Detailed example

Command

dsh-plugin-upgrade-scan --repo fixtures/leg-a-bad-repo --seams S3

Output

# scan-0.1.5 · /mnt/d/Projects/dsh/plugins/dsh-plugin-upgrade/fixtures/leg-a-bad-repo
files scanned: 3 · hits: 1

## S3 [error] assistant/message 缺 stream（V3 必填） — 1 hit(s)
   action: 写入会话日志的 assistant/message 必须带 `stream: []`（或真实分片）；缺了导入成功但会话不可续聊（Session.fromRestore 抛 invalid settlement fields）。
   fixtures/leg-a-bad-repo/src/index.ts:30  type: 'assistant/message',

H3 [info] card-only: the rc.1 additive capabilities are listed on the version card and are never auto-detected.

Observed from README.md:159-173 (Surfaces/CLI); test/scan.test.mjs:158; fixtures/leg-a-bad-repo/src/index.ts:30

Failure branch

Input

node scripts/scan-0.1.5.mjs --repo /nonexistent-upgrade-repo

Output

repo not found: /nonexistent-upgrade-repo

Observed from plugins/dsh-plugin-upgrade/lib/scan.mjs:510-514,523; plugins/dsh-plugin-upgrade/README.md:181-192

Brief examples

• plugin-upgrade

Configuration

Every key is optional and lives in the profile patch:

- insert:
    - id: dsh-plugin-upgrade
      name: dsh-plugin-upgrade
      config:
        skillName: plugin-upgrade

The plugin mounts loud: a missing SKILL.md, an empty body, or a frontmatter without name fails the mount instead of registering an empty skill.

Surfaces

Skill — plugin-upgrade (model- and user-invocable by default). Body: leg routing table, the 8 hard rules and the 6-step loop. References: the merged corridor card. Scripts: the detector, shipped inside the skill directory so relative paths resolve.

CLI — dsh-plugin-upgrade-scan:

dsh-plugin-upgrade-scan [--repo <path>] [--span legAB|legC|<span>] [--json <out.json>] [--seams S3,C1,P1] [--quiet]

Exit codes: 0 no error-severity hit · 1 at least one error-severity hit · 2 usage or scan failure. A clean scan is necessary but not sufficient — the exit criterion is a real-host smoke, plus a resume round-trip for log writers (leg A) and a real browser assertion for the client half (leg B).

The twenty legAB seams

Order follows the catalog in lib/scan.mjs (leg A first, then leg B), which is also the order test/card.test.mjs pins the card to.

S7, S2, S1, S10, C4, C5, H1, H2 and H4 are deliberately advisory: they have legitimate matches (a repo that already uses the new API, a documentation snapshot, a plugin's own model-id table, a Node ChildProcess.pid), so the scanner reports them as leads for manual review rather than failures. M1 and P1 are structured checks — they resolve package.json and tsconfig*.json instead of matching text — and H3 is card-only: documented, id-parity checked, and deliberately without a detector (CARD_ONLY = ['H3']).

The five legC seams (0.1.5-rc.2 → 0.1.6-alpha.2)

Order follows the catalog in lib/scan-0.1.6.mjs, which is also the order test/card.test.mjs pins the legC card to. Every seam here is error and every one is detected (CARD_ONLY = []).

The same discipline applies as for legAB: a clean scan is necessary, not sufficient. legC breakage is silent or runtime-only (the published type line hides the deletions), so the exit criterion stays a real-host smoke on a temp DSH_HOME, plus the log-writer round-trip and the real-browser assertion where they apply.

What this does not cover

• A hop past every corridor here. legAB ends at 0.1.5-rc.1 by construction: the harness hop 0.1.5-rc.1 → 0.1.5-rc.2 added no plugin-facing seam (this package's own dev/test pin now runs on the 0.1.7-rc.2 line, so the catalog is verified against those published types; the compat workflow's probe still anchors 0.1.6-alpha.2), and legC covers 0.1.5-rc.2 → 0.1.6-alpha.2. A later hop that adds a seam is not covered: a corridor is closed, and widening a card is worse than adding one. It gets a new card and a new index row — not a new package.
• The 0.1.1 → 0.1.2 hop. Use the community convergence skill.
• Restating across legs. Leg A owns the session-format seams (assistant/message.stream, SessionHandleReadResult, EpochHeader.system, ctx.agent, Inbox, SystemPrompt.persona, the V3 log generation) and leg B does not restate them — the whole packages/core/session/src diff in leg B's range is two added event-type literals and one comment line. Each leg's card section keeps its own scope statement.
• The DSH user-facing upgrade path. This package upgrades plugin source code, not a user's harness installation.
• Theme tokens. docs/web-styling.md has zero changes in leg B's range.
• Proof. A clean scan is a hypothesis. The exit criterion is a real-host smoke (temp DSH_HOME, target CLI, plugin add <tarball>, --dump-config) plus a resume round-trip for session-log writers (leg A) and a real browser assertion for every client-side hit (leg B).

Security boundaries

• Read-only scan. The CLI never writes inside the scanned repository; --json writes only to the path you pass.
• No network, no shell. The scanner imports nothing beyond Node's standard library and never spawns a process.
• No secrets. Nothing in the package reads credentials, environment tokens, or session data.
• Sandboxed smoke recipe. The card's real-host check uses a mkdtemp DSH_HOME; it never touches your real ~/.dsh.

Development

npm install                        # or: pnpm install (the repo ships a pnpm-lock.yaml)
npm test                           # node --test: scanner, card<->catalog parity, real Cordis + SkillRegistry
npm run verify:self-contained      # every import resolves inside the package
npm run verify:artifacts           # the packed tarball carries the skill, CLI and patch, and excludes tests
npm run check:readmes              # five-language README consistency
npm pack

The scanner has a synthetic fixture pair per legAB leg: fixtures/leg-a-bad-repo (leg A's session/config seams, every error seam present on purpose) with fixtures/leg-a-good-repo (adapted), and fixtures/bad-repo (leg B's client-slot seams) with fixtures/good-repo (adapted) — plus a live negative on a family repository already pinned to 0.1.5-rc.1, so a regression in the catalog fails the suite rather than a downstream user. test/card.test.mjs asserts that each card's index and its own catalog (lib/scan.mjs for legAB, lib/scan-0.1.6.mjs for legC) name exactly the same seam ids with the same severities, that legAB's CARD_ONLY is exactly ['H3'] while legC's is empty, and that the two catalogs share no seam id — the evidence-binding rule as a machine gate, per corridor.

Topics

dsh, dsh-plugin, deepseek-harness, deepseek, cordis, plugin-upgrade, migration, skill, version-card, scanner, client-slots (mirror package.json keywords; dsh-plugin is the ecosystem's visibility channel).

PerryLink DSH Plugin Family

This project is part of the DeepSeek Harness plugin family from PerryLink. The roster stays collapsed below so every README keeps a short first screen; expand it to see every row and its status.

License

Apache-2.0 — see LICENSE. Install-time dependencies and their licenses are listed in THIRD_PARTY_NOTICES.md; nothing is bundled.