oh-my-dsh avatar

dsh-plugin-upgrade-skill

Safely upgrade DeepSeek Harness plugins with breaking change guides, migration recipes, and real-world examples from community practice

version
0.1.0-alpha.2
GitHub stars
322

Install

/plugin install dsh-plugin-upgrade-skill@dsh-plugin-upgrade-skill

Run it inside Claude Code after adding the marketplace with /plugin marketplace add oh-my-dsh/dsh-plugin-upgrade-skill.

Contents

Discovered from source

Skills 12

从插件仓库提取 dsh 升级考题

把一个真实发生的插件迁移(git 历史里的破坏性变更 commit)变成一道 Harbor 考题:旧形态插件为 fixture(装上必坏,或有隐藏坑),新形态为 oracle 参考解,judge 在容器内真实冷启动判活。产出跟随 ./benchmark/(上文:oh-my-dsh/dsh-plugin-upgrade-skill 的 benchmark 目录)。

上下文锚点:目标套件是 dsh-plugin-upgrade-skill 的 benchmark v2.4(Harbor 格式),host 镜像固定为 node:24-bookworm + 全局 dsh 0.1.2-alpha.2。每条考题 遵循 execution-contract(BENCHMARK-AUTH-v1)与固定评分模型(100 分/题)。

何时使用

  • 用户给一个插件仓库,说"提成考题 / 做成 case / 转 benchmark task"。
  • 用户拿着一条版本走廊或一个迁移 commit,要可执行的评测而不是文档。
  • 现有升级卡(references/v*.md)需要测"AI 会不会照卡修"。

工作原理(一句话)

fixture = 迁移前形态(偶藏误导注释/预置失败),judge = 静态检查 + 容器内真实冷启动信号(pending / plugin tree failed / MISSING_CREDENTIAL / __DSH_BOOT__ 条目),oracle = 参考迁移,判分天然 0~1。

Pipeline

Stage 0 · 选材与走廊定位

先回答三个问题,答不出就退回升级卡形态,不做题:

  1. 迁移方向:仓库 git 历史里哪一个 commit / 哪一段走廊是"host 升级导致的 必需改动"?(例:426e86d whale-girl bundle 转换,走廊 rc.8→rc.1)。 纯自研重构、无 host 侧断裂的 commit 不成题。
  2. 可测性:迁移后形态能否在容器内"装得上 + 冷启动得到确定信号"? 判分信号必须是宿主侧信号(见 Stage 3),不是"输出文本长什么样"。 无浏览器容器 ⇒ client 运行时不可判,只能判 boot 图条目 / HTTP 状态。
  3. 对应卡:这条走廊在 references/ 里有没有卡(或需要先补卡)? 考题与卡是一对多:一道题可以覆盖多张卡,但卡必须已存在或随题新增 (validate.mjs 会校验卡引用存在且链接可解析)。

选材标准(×成立越多越好):迁移真实发生过(有 commit 可考); 断裂面小(1~4 个 touchpoint);装旧形态必有可观察故障(pending / 静默缺行为); 新形态在 alpha.2 上可冷启动验证;最好带隐藏坑(诱导注释 / 看着无辜的面上 藏着致命伤——坑要来自真实迁移的"第二个 commit",不是编的)。

产出:选定的 task id(见 Stage 1 命名)+ 走廊 + 覆盖的卡 ID 清单 + fixture 应模拟的第 N 个 commit 形态(迁移前)。Checkpoint:三者对齐才继续。

Stage 1 · 骨架与命名

任务目录 tasks/<id>/,id 命名:前缀字母 S(静态只读)/ M(迁移可改)/ H(hands-on 陷阱),编号接该系列现有最大值。编号不要凭记忆硬编码—— 动手前先 ls benchmark/tasks/ 并对照 benchmark/README.md 任务表与注册表 校验脚本确认当前集合(当前 52 题:S1–S16 / M1–M14 / H1–H22,下一可用 S17 / M15 / H23),勿跳号。一个任务一个目录:

tasks/<id>/
├── instruction.md        # 给 agent 的 prompt(含 BENCHMARK-AUTH-v1 契约)
├── task.toml             # Harbor 配置(见 assets/task.toml.example)
├── environment/
│   ├── Dockerfile        # node:24-bookworm + git + pnpm + dsh alpha.2 + git 基线
│   └── fixture/          # 旧形态插件(private:true,README 声明 exam material)
├── tests/
│   ├── test.sh           # verifier 入口:跑 judge,score→reward 写 /logs/verifier/
│   ├── judge.mjs         # 判分逻辑(全部在这)
│   └── judge-utils.mjs   # 共享判分库:profile 生命周期、冷启动信号、清理
└── solution/
    ├── solve.sh          # oracle:把参考解拷进 fixture
    ├── SOLUTION.md       # 参考解说明 + The Point + Grading Boundary
    └── plugin/           # 参考迁移后的完整文件

模板在 $_S/assets/:task.toml.example、instruction.md.example、 judge-utils.mjs(整库直接复制)、test.sh.example、Dockerfile.example、 solve.sh.example、judge.mjs.example(骨架)。

装 dsh 的 Dockerfile 必须(与现有任务一致,勿改版本): FROM node:24-bookworm;装 git;npm install -g pnpm@11.24.0 @deepseek-ai/dsh@0.1.2-alpha.2;COPY fixture → /app/fixture;git init + 基线 commit(judge 靠 git status --porcelain -- fixture 判"fixture 是否被改", 只读题 0 分门禁,可变题 0 分门禁的相同实现)。Checkpoint:目录 6 块齐全。

Stage 2 · fixture 构造

按"迁移前第 N 个 commit"的真实形态写 fixture,三个纪律:

  1. 必须私有:package.json "private": true;README 首行 "exam material only, do not publish"。源头切片除外(见 4)。
  2. 坑要用真坑:误导注释要像真话——来自真实迁移决策记录里"当时为什么 这样做/为什么别改"的措辞;预置失败测试要确实预先失败且与升级无关 (测诚实报告,不测静默修复)。
  3. 坏必须可观察:旧形态要么装上 pending / plugin tree failed,要么 静默缺行为但 judge 有对应锚(如 boot 图没有该插件的 client 条目)。 判分锚必须能在容器里拿到,拿不到的 feature 不出现在 judge 里。
  4. 上游切片保留原元数据(Apache-2.0 真实仓库切片如 dsh-web):保留 license/original package.json,读 provenance/ 惯例(见基准 tasks/H9-dsh-web-alpha2/provenance/)。

fixture 放哪、可以留什么:Node half 可留在 .dsh-plugin/ 子目录等 旧布局位置——但这类布局有深坑可挖:host 的 client-modules 从 Node entry 文件向上找最近 package.json 作为包身份(机制见 $_S/references/host-archaeology.md 的"manifest 遮蔽"条目)。设计 fixture 时可利用这类机制布坑:让旧布局残留文件影响包识别,浏览器半静默消失; 判分侧的 boot 图条目检查会自然抓到。具体某道在线题怎么布、参考解怎么收 尾,不在此展开——方法级不讲答案。

Checkpoint:dsh plugin add 旧 fixture 在容器里真的坏 / 有静默缺陷; 新 fixture(参考解)全绿。两态都必须先本地 docker 验证,不许只靠想象。

Stage 3 · judge 设计(判分心法)

固定评分模型:100 分/题,emit(score, reasons) 最后一行输出 {"score":0-100,"max":100,"reasons":[...]},test.sh 归一化到 0~1 写 /logs/verifier/reward.txt。线性叠加 checkpoints,禁止加权魔法。

通用三段式:

段内容分数惯例
GatefixtureChanges():fixture 必须被改(静态题 0 分;可变题 0 分)0 或整体继续
静态manifest 字段 / exports / patch insert 行 / 源码模式(grep)40~70
运行时dsh plugin add + 冷启动信号 + boot 图条目/HTTP30~60

判分锚必须是宿主侧信号(从 judge-utils.mjs 输出获取):

  • NEGATIVE_SIGNAL:plugin tree failed / did not activate / pending (waiting for service: …) / FAILED fiber / ClientPackageCompositionError = 失败带(通常 40 或该 check 0 分)。
  • headless 冷启动:无 API key 时到达 MISSING_CREDENTIAL / no API key / dsh: AUTH = 插件树整体激活,通过。出口码不算——无 key 成功也 exit 1。
  • web 冷启动 + GET /:__DSH_BOOT__.entries 包含 <pkg>/client.js (注意:boot 图 URL 按 exports 的 key 拼 ${pkg}/client.js,与文件 真实路径无关)或该插件的 HTTP 通道 401/200 冒烟。

边界声明:judge 头注释与 SOLUTION.md 的 Grading Boundary 必须写明"容器 内没有浏览器 → client 运行时行为不判,只判宿主宣告的 boot 图条目"这类边界; 未覆盖面同样写进 scoring.md。

分数带设计提醒:给"半对"留带(关键声明完整给满分、缺字段给半分、 完全缺失 0 分);陷阱跟随者给封顶(如误导注释说别改 X,留着 X = 该 check 上限)。判分必须能区分"真迁移"与"看起来绿但绕开了迁移"——绕道 路径 boot 也能绿,要用静态检查(grep 特定字段/模式)封顶才抓得住。

运行纪律:judge 只建 bench-<task> profile 与 /tmp/bench-<task>, finally 里清理(pkill 用 [x] 自逃逸模式防止自杀)。timeout 充足(add 180s / boot 60s / web 150s,真实 workspace 题 verifier 900s)。judge 永远 exit 0, test.sh 解析不了 JSON 时按 0 计。

Stage 4 · oracle(参考解)

solution/plugin/ 是完整迁移后的 fixture;solve.sh 逐文件覆盖进 /app/fixture/,并显式删除该题迁移要求删除的残留文件。 SOLUTION.md 三节必备:

  1. Reference Changes:每条改动对应卡 ID 全名(如 DSH-0.1.1-R1-01, 不要写 R1-01 简写——validate.mjs 校验全 ID 存在)。
  2. The Point (one sentence):这道题真正测的一招。
  3. Grading Boundary:与 Stage 3 的边界一致。
  4. Warning:如果 judge 是 grep 源码模式判"已删除",参考解源码注释里 不得出现被 grep 的字面 token(实战教训:solution 注释复述了被判 "已删除"的旧标识符字面,judge grep 命中注释导致自伤扣分)。

Checkpoint:oracle 在容器里跑出 100/100(reward 1.0,下一步做)。

Stage 5 · 契约与注册表同步(四连)

instruction.md 契约(validate-execution-contract.mjs 用正则逐条匹配, 字面必须命中,双语任选其一):

  • 恰好一处 BENCHMARK-AUTH-v1;契约五子句: no-follow-up("there will be no follow-up user messages")、 proceed-after-plan("continue executing immediately once the plan is formed")、 no-pause("do not pause to wait for confirmation")、 no-modify("must not modify the skill")、 no-stop("do not stop merely because another round of confirmation is missing")。
  • 边界授权句按 mode:可变题 "you may modify /app/fixture/ directly"; 只读题 "/app/fixture/ must remain completely unchanged"; build-artifacts 题 src 零改动 + lib 可清理(照抄现有任务的措辞最稳)。
  • task.toml:execution_contract = "BENCHMARK-AUTH-v1" 恰好一次、 version = "1.1.0"。

四连注册表(全部必须同步,否则校验失败):

  1. benchmark/README.md:任务表加行(Task/Type/What it tests);顶部 "The N plugin-upgrade tasks measure";"The first N are written exams … the last M are hands-on"(按 Type 列计数);# all N tasks 注释; "All N instruction.md files carry";"existing N tasks" 维护者注记。
  2. benchmark/docs/scoring.md:Total <N×100> (N tasks × 100; …); 任务表加行(Checkpoint 卡引用 + Score breakdown 精确到每条)。
  3. benchmark/scripts/validate-execution-contract.mjs:expectedModes Map 加 ['<task-id>', '<mode>'](mode ∈ readonly | mutable | build-artifacts-only)。
  4. benchmark 的卡引用:全 ID + 链接可解析(validate.mjs 会查)。

Stage 6 · 校验与 oracle 自检(门禁)

cd dsh-plugin-upgrade-skill
node scripts/validate.mjs                       # 卡 + 链接 + 引用全绿
node benchmark/scripts/validate-task-registry.mjs    # 任务清单/计数注册表一致
node benchmark/scripts/validate-execution-contract.mjs  # 契约五子句 + mode
# oracle 自检(must be 1.0):
harbor run -p benchmark/tasks/<id> -a oracle
# harbor 不可用时(本机 pip/uv 受限),用 docker 手动走通等价值:
#   docker build -t bench-<id> environment/ && docker run ... 复制 oracle →
#   fixture → node tests/judge.mjs → 断言 {"score":100}
node --check tests/judge.mjs && node --check tests/judge-utils.mjs

Checkpoint:三个校验全绿 + oracle 100/100 + 文件权限(solve.sh / test.sh 755,与现有任务一致)。不绿不交付。

交付

  • tasks/<id>/ 完整任务 + 四连注册表改动,与升级卡(如有)同一 PR 主题。
  • PR 描述声明验证命令与结果(validate × 3 + oracle 1.0)、覆盖的卡、 未覆盖边界、致谢(本次实战致谢脚本 $_S/ 无,按仓库惯例)。

Gotchas(实战教训,新增题前先扫)

  1. 注释会自伤:solution 源码注释不得含 judge 要 grep 的"已删除"字面 token。
  2. manifest 遮蔽:client-modules 从 Node entry 向上找最近 package.json; 残留旧清单(无 dsh.client)让浏览器半静默消失——参考解要删, 这是合法题点不是 bug。
  3. boot URL ≠ 文件路径:__DSH_BOOT__ 条目按 exports key 拼 ${pkg}/client.js;判 boot 图别去匹配真实路径。
  4. 服务名随走廊变:httpServer→webServer(R1-09)、tasks→jobs; fixture 用旧名、参考解用新名之前,先在容器冷启动验证哪个名能解析。
  5. profile 组合:web 冷启动 profile 用 ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'];headless 用 headless 预设。别复用共享 ~/.dsh。
  6. 版本钉死:Dockerfile 的 pnpm/dsh 版本与现有全部任务完全一致 (pnpm@11.24.0 / dsh@0.1.2-alpha.2);改了等于换题。
  7. pkill 自杀:judge 清理命令 pidpattern 用 [x] 括号技巧,否则匹配到 自己执行的 sh -c 会杀自己(本次实测 exit 143)。注意 [x] 只防"模式 文本自身":同一 sh -c 命令行的其他位置若还有明文 profile 名(如 add/boot 命令),pkill 依然自杀——把 pkill 拆成独立 exec。
  8. sh 引号吞内嵌脚本:judge 里用 node --input-type=module -e 'script' 做路由冒烟时,内嵌脚本中的单引号会在 sh 单引号内提前闭合 → node 收残缺 程序 → SyntaxError 伪装成"路由失败"(stderr 只有 node 栈尾)。修法: 内嵌脚本零单引号(断言用 JSON.parse(text).ok === true 而非 text.includes('"ok":true'))。已写进 M14 judge 头注释。
  9. harbor 可用性:本机 harbor CLI 因 uv/pip 沙箱装不上;oracle 验证可用 docker 手动等价路径,README 说明跑法(harbor run -a oracle 为标准式)。
  10. 一个走廊多题:强 case(如 bundle 转换、服务改名)可出多道独立题, 各自 fixture 聚焦不同 touchpoint;不要一道题塞所有。
  11. 判别力验证:交付前不只要 oracle=100,还要跑负例矩阵——未动 fixture 必须 0(gate)、陷阱跟随为该 check 上限、半迁移(如只改服务名 不改事件名)落在预期带。judge 要是"什么都得高分"就没有评测价值。

references(按需读)

  • $_S/references/case-selection.md — 选材判据细节与反例。
  • $_S/references/harbor-task-spec.md — 目录规范、task.toml 字段、 环境镜像、判分信号表(详细版)。
  • $_S/references/contract-clauses.md — 契约五子句与授权句的全量字面 (照抄最稳)。
  • $_S/references/grading-recipe.md — judge 三段式、分数带、caps 设计。
  • $_S/references/host-archaeology.md — 宿主源码考古出的坑与证据 (client-modules 解析、boot URL、服务改名)。
  • $_S/references/registry-sync.md — 四连同步全量清单 + 校验命令。
  • $_S/assets/ — task.toml.example / instruction.md.example / judge-utils.mjs(完整库)/ judge.mjs.example / test.sh.example / Dockerfile.example / solve.sh.example。

校验清单(交付前逐项自查)

  • Stage 0 三问:真实迁移 / 容器可测 / 卡存在或随题新增
  • fixture private: true + "exam material only";旧形态容器实测会坏
  • judge 全部锚是宿主侧信号;gate/静态/运行时三段齐全;边界声明齐全
  • oracle 100/100(harbor 或 docker 手动)
  • solution 注释无 judge grep token;残留清单已删
  • 四连注册表同步(README × 6 计数、scoring Total+行、expectedModes)
  • validate.mjs + validate-task-registry + validate-execution-contract 全绿
  • solve.sh / test.sh 755

English | 简体中文

dsh-upgrade-audit

Audit every change observable by consumers outside the repository between two DSH versions, and produce the set of reports the user expects. The fixed form of this problem: relative to from, does to contain more changes or reverts? — "more changes" means externally visible breakage (removed exports, renamed wire error codes, data formats refused on read); "revert" means behavior present in from deliberately withdrawn by a revert within the interval. Both need evidence: commit messages and subagent summaries are claims — only conclusions drawn after reading both trees (source files or published packages) count as evidence.

External compatibility = everything observable by consumers outside the repository: the npm package public API (exports, types, signatures, dependency surface), the dsh CLI (commands, flags, profiles, config keys), the wire protocol (SDK JSON-RPC, remote gateway/BFF, ACP, hooks), session data on disk (JSONL logs, SQLite stores and their version guards), the model-visible surface (tool names/schemas, system-prompt output), and the Python SDK's expectations. Internal refactors are background, not findings — aggregate and count them.

Note: report language follows the user's language (see "Output contract" below); the existing sample report under examples/ is in English by historical convention.

Phase 0 — Parse input and choose a mode

Input: two version identifiers (accepts 0.1.2-alpha.2, dsh-v0.1.2-alpha.2, dist-tags alpha/latest/next). Choose the analysis mode by specificity, high to low:

  1. Context path — the user named a deepseek-harness checkout directory in the message. Verify: root package.json + packages/ + AGENTS.md all present.
  2. DSH_SOURCE_PATH environment variable — verify the same way. (Optional DSH_NPM_REGISTRY overrides the npm registry.)
  3. CWD heuristic — the current directory is itself a deepseek-harness checkout (marked the same way).
  4. npm mode — none of the above (the default path for third-party repos): download the published packages of the two versions for analysis.

Source mode audits git tags; npm mode audits published artifacts. The audit core (recon surface, classification, verification, reporting) is shared; only the materialization and some evidence sources differ. Know npm mode's boundaries before choosing it: the npm version set ≠ the git tag set (e.g. 0.1.2-alpha.1 is tagged but was never published — the materialization script exits with the published list, so present the gap to the user instead of silently substituting a version pair); the CLI closure does not include every publishable package (the SQLite persistence backend is not a CLI dependency; the script installs it as a supplement package).

Output contract

Everything lands in one directory: tmp/<fromNorm>-to-<toNorm>/ (normalization: strip dsh-v, strip dots in the prerelease segment — dsh-v0.1.2-alpha.1 → 0.1.2alpha1). Source mode creates it inside the checkout (gitignored); npm mode creates it inside the current project. If the target directory already exists it is most likely a previously hand-made report — stop and ask first; do not overwrite.

ArtifactSource modenpm mode
commits.txt, reverts.txtfrom git; reverts folded into CHANGELOGfrom GitHub compare enrichment (none if private repo)
files.txt, diffstat.txt, full .diffgit tree diffmanifest-diff.txt (per-package manifest diff) + a/, b/ published package trees
CHANGELOG.mdcategorized by type, must have a Reverts sectiongenerated when enrichment exists; otherwise omitted with an explicit note
UPGRADE-ADAPTATION.mdaudit report (same skeleton in both modes)same; header records mode and version provenance

Report language follows the user's language (examples/ existing report is in English, a historical convention — not mandatory).

Phase 1 — Materialize the two trees

Source mode — verify purity first; a merge base that is not from itself means base drift: stop and report, never diff against a moving baseline:

git merge-base <from> <to>   # must equal <from>'s commit
node <skill-dir>/scripts/gen-artifacts.mjs <from> <to> tmp/<pair>

npm mode:

node <skill-dir>/scripts/materialize-npm.mjs <from> <to> tmp/<pair>

The script resolves both versions against the registry (missing → exit 1 with the published list — present the gap to the user), installs the @deepseek-ai/dsh dependency closure plus the SQLite supplement package into a/ and b/ with --ignore-scripts, produces manifest-diff.txt from per-package manifest diffs for every @deepseek-ai/* package, and enriches from the public GitHub repository (commits.txt, reverts.txt) — so revert detection works even without a source checkout.

Size the recon from the stats output: ≤40 non-merge commits → run the recon-surface checklist inline; 40–250 → merge 3–4 facades; more → all six facades. For density comparison, open the previous pair's commits.txt — the immediately preceding pair in chronological order, never just the newest directory in tmp/.

Phase 2 — Establish shared facts first

Run once and feed to every subagent, so they do not each re-derive them:

  • Format guards — source mode reads SESSION_FORMAT_VERSION on both tags (packages/core/session/src/types.ts) and the SQLite SCHEMA_VERSION (packages/session/session-persistence-sqlite/src/schema.ts); npm mode greps the same-named constants from the published lib/*.js of dsh-session and the supplement package. A guard that jumps with no migration path = hard data breakage; put it at the front of the report.
  • Revert list — source mode: git log --grep='[Rr]evert' <from>..<to>; npm mode: the enriched reverts.txt (absent → revert intent is undetectable; say so explicitly and do only the from→to delta audit).
  • Python SDK — source mode: diff python/; npm mode: outside the npm artifact scope, one sentence suffices.

Phase 3 — Parallel facade scans

Dispatch one read-only recon agent per facade in a parallel batch, each carrying the Phase 2 shared facts and the output contract from references/audit-playbook.md: sections REMOVED (first — candidate breakage/reverts), CHANGED (before → after), ADDED, RENAMED; every entry carries package/path, symbol or field, and an impact-surface class (SDK consumers / CLI users / config authors / session data / model-visible / protocol peers / web UI / npm installers); end with a one-line verdict. The per-facade target path lists (per mode) are in the playbook.

Phase 4 — Verify before publishing

Recon output is leads, not findings. Personally re-verify every REMOVED, revert, and wire claim: source mode with git show <tag>:<path> / git ls-tree against both tags; npm mode by reading both published trees (a/node_modules/... vs b/node_modules/...). This step has a real lesson: a recon agent once reported a package that already existed in alpha.1 as "added in alpha.2". Whatever cannot be verified is either marked [INFERENCE] or deleted.

Phase 5 — Write UPGRADE-ADAPTATION.md

Per the references/audit-playbook.md skeleton: header (range, stats, mode & provenance, source-mode purity note), Verdict (answer the comparative question directly), §1 reverts, breaking sections sorted by consumer impact (removals first, each annotating who breaks, with an Adapt: line), Confirmed unchanged (the parts where compatibility holds matter as much as the breaks), the boundary signature table [API surface | from | to | changed?], and a numbered migration checklist. Full worked example at examples/0.1.2alpha1-to-0.1.2alpha2/ (a real source-mode audit). Chat replies follow the user's language.

Guards

  • Read-only: source mode touches nothing outside tmp/<pair>/; npm mode writes only its own tmp/<pair>/ and installs with --ignore-scripts into that directory — never install the dsh package into the host project's node_modules.
  • Prefer tree-level facts (published files, two-tag reads); do not trust narratives inferred from logs.
  • Aggregate internal irrelevant churn (tests, notes, i18n, styles) into a single count; do not itemize it.
  • npm mode records its limitations honestly: no enrichment → no git history; the CLI tarball ships only lib/ (config composition audited via each bundle package's cordis.patch.yml + manifest); Python SDK out of scope.
  • Do not fully fan out a 20-commit range; do not inline a 500-commit range. Misjudging the scale is the main reason audits go stale or shallow.

Relationship to plugin-upgrade

This skill produces evidence of host-version compatibility (report + boundary signature table); plugin-upgrade consumes that evidence (version-change cards) to execute a single plugin's migration. Audit findings can feed a card's "field notes" directly; when adding cards to plugin-upgrade, cite this skill's report directory rather than restating from memory.

Generic Plugin Migration Methodology

A disciplined procedure for moving a plugin across an upstream release that may contain breaking changes. Everything here is framework-agnostic: no product names, no version numbers, no API identifiers. Pair it with the upstream project's own changelog and release notes whenever those exist.

0. Ground rules

  • Never migrate blind. If you have not read the upstream changelog for every version in the corridor (start → target, inclusive), you are guessing.
  • Inventory before edits. A written list of what the plugin touches beats discovering breakage one crash at a time.
  • Change one layer at a time, and keep the old install runnable until the new one is proven (side-by-side installs, separate data directories).

1. Inventory the coupling surface

Before touching code, scan the plugin read-only and record every place it couples to the host. A generic coupling checklist:

  1. Manifest / metadata — declared compatibility ranges, entry points, permissions, capabilities the plugin requests.
  2. Host API imports — every module, symbol, or type imported from the host or its SDK; note which are used at load time vs call time.
  3. Lifecycle & events — activation hooks, event subscriptions, disposal.
  4. Services & RPC — services the plugin consumes or exposes; inter-process or request/response channels and their payload shapes.
  5. UI contributions — commands, views, panels, menus, themes, keybindings.
  6. Persistence — files, databases, or key-value stores the plugin reads or writes, including schema versions and migration code.
  7. Process & I/O seams — spawned subprocesses, sockets, pipes, parsers of host-generated output (logs, CLI text, serialized state).
  8. Configuration — settings keys read/written, defaults the plugin relies on, user-facing documentation of those keys.
  9. Dependencies — packages shared with the host (risk of duplicate instances), peer ranges, runtime version floors.

For each item record: file/line, what exactly is coupled, and how confident you are. "No hit" is only meaningful after you state what you scanned and what you could not rule out.

2. Read the corridor, not just the endpoints

Changes across a release corridor interact. Read every intermediate release's notes and diff, and build a net-state table:

  • A field removed in an intermediate version but restored later has zero net change — do not "migrate" it away.
  • A rename that happened in two steps (A → B → C) is migrated straight A → C.
  • Behavior changes (defaults, ordering, timing) are as breaking as API removals; list them explicitly.

Classify each upstream change as: breaking (must edit), behavioral (must re-verify), additive (optional), or informational.

3. Map, then edit

Map every inventory hit (§1) to a corridor change (§2). Only then edit, in dependency order:

  1. Manifest and compatibility ranges first — the host may refuse to load anything else you fix.
  2. Host API surface: renames, removals, signature changes.
  3. Lifecycle/events/services.
  4. Persistence migrations (never mutate the user's only copy; write-migrate on first run with a backup, or fail closed).
  5. UI and configuration.
  6. Dependency alignment: shared packages must resolve to the host's instance; check for duplicate copies in the installed tree.

4. Verify in layers

Cheap layers first; each layer must pass before the next means anything:

  1. Static: typecheck, lint, the plugin's own unit tests.
  2. Install-time: the host accepts the manifest and loads the plugin without warnings.
  3. Cold start: a real host process boots with the plugin enabled; check logs for deprecation and fallback warnings, not just crashes.
  4. Functional probe: one real end-to-end path per major feature, including the features you did not migrate (silent behavior drift hides there).
  5. Data: migrate a copy of real persisted data; verify round-trip and downgrade behavior.
  6. Rollback rehearsal: prove you can go back — reinstall the old version against the migrated data and confirm it still works or that you have a restore path.

5. Discipline and pitfalls

  • Prefer the host's documented replacement over re-implementing removed behavior yourself.
  • Treat "it typechecks" as the beginning of verification, not the end.
  • Deprecated-but-working is a scheduled failure: record it even if out of scope.
  • If a change's semantics are unclear, read the upstream source at the target tag; do not guess shapes from a one-line changelog entry.
  • Keep a written migration log: what you changed, why, and what you verified. It is the artifact that lets someone else trust the migration.

plugin-fast-adapt

这个技能只做事

把「插件适配到新版 DSH」拆成四步,每步一个脚本,每步都能单独跑;另有两个可选步骤补全「造完即验、升级顺带优化」:

步脚本回答什么
★ 一键全链(推荐入口)scripts/run.mjs环境→定版→指南→扫描→体检→冒烟→typecheck 一条命令跑完,出统一报告并写本地运行日志
0 造骨架(可选)scripts/scaffold.mjs从零造插件:一条命令出五形态可冒烟骨架,生成即验证
1 探测环境scripts/env-doctor.mjs本机装的 DSH 是哪个版本?覆盖层有没有旧包?共享农场有没有悬空软链?两层 patch 都读到了吗?装了哪些插件?插件启用就绪吗?
2 定版本scripts/guide-sync.mjs官方最新版本是什么?本机该不该跟?跟哪个?
3 取差异scripts/guide-sync.mjs --clone本机到目标版本之间,官方列了哪些破坏性变更?
4 查命中scripts/code-scan.mjs本机插件代码踩了其中哪几条?官方给的修法是什么?
★ 接缝查询scripts/seams.mjs某个包/API 符号在官方指南与本机宿主里的双源结论(双源一致才下「已移除」)
5 秒验(可选)scripts/quick-smoke.mjs改完之后插件还能加载、apply、注册工具吗?未声明 inject 的宿主服务访问会被拦吗?
6 体检(可选)scripts/plugin-audit.mjs插件性能、弹性、上下文预算、生命周期得分如何?按新版本该做哪些优化?peer 该怎么改?
★ 日志诊断scripts/log-doctor.mjs~/.dsh/logs/ 里宿主启动失败(端口占用/未声明 inject/客户端入口死链)的根因是什么?
★ 下游同步scripts/sync-skill.mjs独立仓的技能面与下游技能目录有没有漂移?

不依赖任何人工维护的知识卡片。 权威来源只有两处:npm registry 的版本信息,和 deepseek-harness 仓库的 docs/upgrade-guide/。所以上游发新版的那一刻,这个技能就自动跟上了,不存在「卡片滞后」的问题。也不镜像官方全量文档、不建人工维护的问题库——那类知识快照必滞后(上游预发布节奏 1.7-2.8 天一个),且关键判定(某包还在不在)用宿主 node_modules 实测更硬。

怎么用

第一步:看清本机环境

node scripts/env-doctor.mjs <插件目录>

输出 JSON,重点看六段:

  • globalDsh:全局安装的 DSH 版本和位置
  • overlayFindings:profiles 覆盖层里与主安装脱节的包,带 severity 和原因
  • sharedFarmFindings:共享 node_modules 农场(~/.dsh/profiles/node_modules)的悬空软链,带 brokenCount/hostBackedBroken(指向宿主安装树的是「宿主升级后包被移除」那一类,标 critical)
  • runningProcesses:正在跑的 DSH 宿主进程(改 Host 侧代码后必须重启它)
  • target.peerWindows:待查插件自己声明的 peer 版本窗口
  • activation:插件启用就绪度——构建产物在不在、各 profile 挂没挂载、声明的 inject 服务在该 profile 有没有提供方特征(Cordis 静默 pending 风险);目标不是插件形态(package.json 无 dsh 命名空间、无 @deepseek-ai/* 依赖)时记 N/A 不检查——按插件规则跑纯工具仓会把「无 main 入口」误报成 ERROR(2026-10-25 自审实录)。入口解析按 Node 语义(exports['.'] 优先于 main),无 main 但入口写在 exports 的包不会再被误报 ERROR(2026-10-26 实测 @local/dsh-env-sweeper)
  • activation.client:客户端半(dsh.client)三层判定——声明形状(合成器 boot 即 throw)、./client 产物(报 client bundles not found)、inject 目标名册死链(entry 卡 loading,整次 web boot 失败)。web profile 与桌面 APP 共用同一套 platform:web 前端,两端一视同仁。名册证据分强弱:宿主内置/bundles 列名/overlay 挂载行为强证据直过;包在依赖里但无行证据报 info 弱档让人确认(宿主是否自动挂载,静态分析判不了)。2026-10-25 实录:宿主半冒烟全绿、桌面 APP 起不来,真凶就是客户端半死注入

overlayFindings 非空时,先处理覆盖层再谈适配。这是 issue #263 那一类事故:宿主升级后覆盖层里残留旧包,旧包优先解析导致运行时装载冲突,而且只换文件不重启宿主还会复现。上游已移除的包若被 overlay 显式补挂(- insert: 行)则降级 info——那是刻意保留的兼容垫片不是意外残留,直接拆会弄断还 require 它的旧插件(确认全部消费方改净后再清)。

overlayFindings 只看各 profile 自己的覆盖层目录,共享农场是另一层。 ~/.dsh/profiles/node_modules 是指向宿主安装的软链农场(@deepseek-ai/* 加 react-dom/express 等传递依赖),宿主升级后包被移除就留下悬空软链,任何 require 它的插件都以 ERR_MODULE_NOT_FOUND 收场(2026-10-26 实测 209 条,宿主启动日志里 client-runtime/orca-agent-hooks 两行装载失败,而 overlayFindings 报 0 处)。这一层 env-heal 不处理,需手工清。

两层 patch 都要看。 除了各 profile 自己的 cordis.patch.yml,还有全局 ~/.dsh/cordis.patch.yml——dsh --dump-config 显示它拼在每个 profile 的最后一层。只读前者会把它整个漏掉:本机全局层由 Orca 写入 orca-agent-hooks 行,引用的 @deepseek-ai/dsh-hooks-claude-code 没装,每次启动都报 1 entry did not activate,而工具报 0 处(2026-10-26 实测)。installedPlugins[].patchEntries 已把两层合并,registered/disabled 判定对两层都生效。

node scripts/env-heal.mjs           # dry-run,只报告
node scripts/env-heal.mjs --apply   # 真的移动(移到 ~/.dsh/.trash/<日期>/,不删除)

第二步:定目标版本

node scripts/guide-sync.mjs <本机版本>

上游盯梢(--check):node scripts/guide-sync.mjs --check 零参数可直接接 cron/launchd/agent 轮询——自动探测本机宿主版本,退出码语义化(1=上游有新版,0=无需动作,2=判定失败),有新版时顺手把该版官方指南预取进缓存(下次 run.mjs 零等待)。工具不自带定时器,接线方式由用户定。

它读 npm 的 dist-tags(latest / next / alpha),然后判断本机在官方通道里的位置:

判定含义下一步
upgrade-available有通道版本高于本机取 target(官方所有通道的最高版本)继续
up-to-date-on-channel本机已是某通道的最新版无需适配,收工
ahead-of-upstream本机比官方所有通道都新无需适配,收工
unknown-local没检测到本机版本默认跟 latest,但要人工确认

不要盲目取 latest。 本机完全可能跑在 next 线上,比 latest 还新一版;这时候报「建议升级到 latest」是倒退。

有 target 时,取该版本的官方升级指南:

node scripts/guide-sync.mjs <本机版本> --clone

优先复用本机已有的 harness clone(自动发现 ~/Documents/*/deepseek-harness,或用 DSH_HARNESS_CLONE 指定),没有才 sparse clone 到 ~/.cache/dsh-plugin-fast-adapt/。

取版锚点(2026-10-25 实测复盘):本机已是官方通道最新版时 resolution.target 为 null,旧实现因此拿不到指南语料、run.mjs 的 scan 阶段静默跳过(扫描走廊 (peerFloor, hostVersion] 明明有内容却报「无指南根或无窗口」)。现在取版锚点退回本机版本(target || localVersion || dist-tags.latest),走廊照常扫。

窗口起点只认宿主包(2026-10-25 dsh-image-gen 实录):起点取插件在宿主包(@deepseek-ai/dsh 及 dsh-* 套件子包)上声明的 peer 下限;同 scope 的 @deepseek-ai/cordis(4.x)、@deepseek-ai/schemastery(3.x)是独立版本线的库,不算宿主包——混入会把起点顶到 3.18.4 一类高位,窗口倒挂后扫描静默跳过。现在倒挂(起点 > 终点)会回退宿主版本并在 window.fallback 留痕、window.source 记起点来源(flag/peer/host),stderr 汇总同步告警,不再静默。

第三步:查插件踩了哪些变更

node scripts/code-scan.mjs <插件目录> <upgrade-guide 目录> <本机版本> <目标版本>

<upgrade-guide 目录> 是官方指南根目录,例如 ~/layerfs-lab/deepseek-harness/docs/upgrade-guide,或者上一步 clone 出来的 ~/.cache/dsh-plugin-fast-adapt/harness-dsh-v<version>/docs/upgrade-guide。

输出三段:

  • findingsByGuide:按官方变更条目分组的命中,每条带 guide、title、migration
  • migration:官方给的修法原文(从该指南的 Migration 段抽出来的相关步骤)
  • findingCount / guidesConsidered:命中数与参考的指南条数

每条命中带出处锚点 guideFile/guideLine(指南内相对路径+标题行号),结论可回溯到官方原文位置,不用在指南目录里再搜标题。

命中分三类并带 severity:package(import 了已移除或已改名的包,critical,装载必炸)、member(调用了已移除的方法或字段,high,运行时炸)、code(字符串里出现已变更的错误码或事件名,medium,最可能撞同名)。findings 先按 severity 排再按文件行号;每条带 evidence(命中行原文)。包名锚点有语义门:只在与移除/改名动词同句时才成为锚点,语境引用不算。

扫描根(2026-10-25 实测复盘):pickScanRoots 取源码根并集——src(client/web 常嵌在 src 内部)与同级的 client/web/ui 一并扫;lib/dist 是构建产物、与 src 同义,只在没有任何源码根时才退回,否则同一处命中会按两份文件重复报。

接缝查询(seams)

node scripts/seams.mjs <包名或符号> [--guide <guide-root>] [--host <版本>]

回答「这个接缝在我的目标宿主还在不在」,双源合成:指南源(锚点表全走廊,哪个版本声称移除/改名了它、原文在哪一行、官方修法)× 宿主源(包看 node_modules 实测,符号看宿主套件源码文本命中——弱证据,如实标注)。裸 dsh-* 名自动归一到 @deepseek-ai/ scope 再查。诚实三态:双源都说没有才下「已移除」;指南说没有但宿主里有,报分歧不替人拍板;双源都无记录时明说「指南未提及不代表 API 不存在」。默认零网络(指南根走缓存)。

一键编排与运行日志(run.mjs)

node scripts/run.mjs <插件目录> [--target <版本>] [--from <版本>] [--no-clone] [--no-smoke] [--no-typecheck] [--no-log] [--real-smoke]

按上面的流程依次跑环境、定版、指南、扫描、体检、冒烟、typecheck(执行插件自有的 typecheck script,与冒烟同信任级),输出一份统一 JSON 报告;扫描窗口自动取「插件在宿主包上声明的 peer 下限 → 宿主版本」的走廊(--from/--target 可覆盖,倒挂自动回退并留痕)。--real-smoke 默认关,显式启用后桥接原仓库 plugin-upgrade 的 verify-runtime.mjs:干净 profile 安装→启动→四类归因(插件代码/依赖解析/profile 配置/宿主运行时),fail 计入退出码 2,脚本不在本机(探测兄弟仓 dsh-plugin-upgrade-skill,或 PFA_VERIFY_RUNTIME 指路径)时诚实跳过给补法,Windows 按 POSIX-only 声明跳过。退出码:0 干净,2 有 critical/high 命中、typecheck 红或真冷启动失败。

每次运行写本地日志(~/.cache/dsh-plugin-fast-adapt/runs/,一次一个自包含 JSON + index.jsonl 一行摘要),记录工具版本与 commit——2026-10-25 实测教训:跑了一份滞后拷贝产出 4 个本已修复的误报,没有日志这类「跑的是哪版工具」完全不可观测。索引摘要带 phases 三态(scan/smoke/typecheck/realSmoke 各 ok|skipped|fail|error)与 toolDirty 星标(工具仓当时有未提交改动,版本号与 commit 可能拆对)——扫描没跑不再与「体检满分」在同一行里混淆(dsh-image-gen 实录:scan skipped、auditScore 照记 100)。运行日志保留 90 天,写入时惰性清理过期文件与对应索引行。

node scripts/run-log.mjs list [--limit 20]              # 最近运行一览(含工具版本@commit)
node scripts/run-log.mjs show <id|--latest>             # 单次全文
node scripts/run-log.mjs sanitize <id|--latest> [--out 文件]   # 脱敏后才可外发
node scripts/run-log.mjs doctor [--logs <目录>]         # 运行日志 × 宿主启动日志交叉核对

doctor 交叉核对(插件报错/装了没生效的第一站):运行日志说代码侧状态(phases/命中/体检),宿主 startup 日志的 failedPlugins/waitingForServices 说装载侧状态,一条命令两边证据并排。三态判定:宿主日志干净 → 状态一致;宿主报了它、最近一次扫描干净 → 嫌疑在装载/挂载/环境侧(转 env-doctor 看 activation 双半);两边都有问题 → 先按 run 的命中清代码。

日志不出本机;对外反馈前必须先 sanitize(home 前缀→~、用户名→、机器名→、邮箱→,目录结构保留)。--offline 跳过 guide-sync(自检零网络用)。

第五步(可选):修完秒验

node scripts/quick-smoke.mjs <插件目录>

纯内存模拟 Cordis 上下文,动态载入插件入口,毫秒到秒级验证:模块能加载、apply 契约能执行、工具能注册。改完代码后先跑它,挂了立刻回改,不用等真宿主冷启动。

边界:冒烟通过 ≠ 宿主兼容。Mock 只覆盖 logger/tools/effect/on 等常见面;输出里的 mockFallbacks 列出了插件摸到但 Mock 没提供的属性(含内建 mixin 里 Mock 未全真实现的面)——这个列表越长,本次结果可信度越低。

契约校验(2026-10-25 实测复盘):此前 Mock 对任何未知属性都返回兜底代理,于是插件访问未声明 inject 的宿主服务(真 Cordis 直接抛 cannot get property "X" without inject,装载即崩)时冒烟静默通过——历史 startup 日志里 failed to register /llm-verifier rpc fallback: cannot get property "webServer" without inject 就是这一类。现在按真契约判:

  • 声明了 inject 的服务 Mock 没提供 → 兜底并披露(Mock 缺口,不是插件的错);
  • 未声明的非内建属性 → 抛 inject_contract 阶段错(与真宿主同形)。

判据取自 cordis/lib/index.js 的 ReflectService 构造与 LoggerService 装配,不是臆造。真冷启动验证仍用原仓库 plugin-upgrade 的 verify-runtime.mjs。

第六步(可选):升级时顺带做性能与架构体检

node scripts/plugin-audit.mjs <插件目录>                                # 纯四维审计
node scripts/plugin-audit.mjs <插件目录> --guide <guide-root> <本机版本> <目标版本>   # 叠加官方指南交叉

四个维度从 100 分扣:性能(同步 I/O、无上限读取)、弹性(强依赖已移除包)、上下文预算(工具 Schema 体积)、生命周期(监听器与定时器清理)。检测走 scanner 状态机,注释和字符串里的同名词不算命中。报告带 targetForm(plugin/tool):目标是不是 DSH 插件看生态信号(package.json 的 dsh 命名空间、@deepseek-ai/* 依赖),工具仓跳过生命周期维度——对普通 Node 脚本建议 ctx.effect 是形态错配的噪音(2026-10-25 自审实录)。三条 INFO 级提示不扣分:import type 引用已移除包(编译期风险非运行时)、peer 窗口按严格 semver 不含目标宿主(本生态 bundle 安装不强制 peer,是声明性约定;建议先经 satisfiesRange 自验证再输出)、工具描述里的宿主路径约定在宿主代码零命中(可能旧版约定已消亡,如 .dsh-filess,需人工确认)。

带 --guide 时与 code-scan 同源交叉:package 命中先经宿主实测核查(包仍在目标宿主 → 降级 info 证伪;确实不存在 → HIGH 扣分附官方修法),命中清零前不建议先做性能优化。新版本引入的接缝(弱依赖 ctx.get() 替代强 import、peer 范围写法)就是「按新依赖做架构调整」的依据。

peer 修补建议:对不含目标宿主的 peer 范围,peerPatch 给「与目标同三元组的 caret 线」替换写法,且每条都先用 satisfiesRange 自验证覆盖目标(验证不过的写法不给)。只对 @deepseek-ai/dsh 及其 dsh-* 套件子包生成——同 scope 的库(@deepseek-ai/schemastery、@deepseek-ai/cordis)有自己的版本线,拿宿主版本套它们的 peer 会给出错到离谱的建议。只生成不自动改包:改用户 package.json 是不可逆写,--peer-patch 打印后人工确认再落。

宿主日志一键诊断(log-doctor)

node scripts/log-doctor.mjs [--logs <目录>] [--limit 5] [--pattern '^startup-']

宿主启动失败(StartupError、端口占用、未声明 inject、客户端入口死链)此前要人工逐个 grep ~/.dsh/logs/startup-*.log,再从 300 多行的 JS 字面量里抠 failedPlugins 与 waitingForServices。本脚本把这条排障路径固化:解析每份 startup 日志的头部元信息与多行 error 块、消息数组(容忍宿主的 [length]: N 伪数组标记),抽取预置信号,汇总成按根因分组的诊断并给可执行动作。

输出:runs(每份日志的 meta/failedPlugins/waitingForServices/signals)、signalSummary(按出现次数排序的信号 + 动作)、verdict(clean/warnings/host-failure)。非 startup 日志(maintain/env-sweeper/web-restart)只按全文扫信号。边界:日志是宿主写的 JS 字面量(非 JSON),只做行级启发式解析,解析不到的字段留 null 不猜;信号是文本命中,动作是「怎么确认/怎么修」的第一步,不替用户拍板。

下游技能同步(sync-skill)

node scripts/sync-skill.mjs --dest <下游技能目录> --check   # 只查漂移(退出码 1 = 有漂移)
node scripts/sync-skill.mjs --dest <下游技能目录>            # 同步

独立仓拆分后,dsh-plugin-upgrade-skill/skills/plugin-fast-adapt 留了一份静态副本;两份都是真文件时下游会静默滞后(2026-10-25 实测:主仓已加客户端半三层判定,下游还缺 lib/client-graph.mjs、SKILL.md 也旧),滞后副本被误跑时查不出新问题。同步面固定为技能读者真正会用的文件:SKILL.md、README.md、README.en.md、references/**、scripts/**(package.json 不入技能面)。--check 报缺失与内容漂移,--dry-run 只打印不落盘。同步完成后打印建议的镜像仓提交命令(只 add 同步路径防夹带、commit 主题带真源短 commit;两侧路径先 realpath,防 macOS /var 软链前缀错位),不自动提交。

造插件:从零开始

第一步用本 skill 的 scaffold 一条命令出可冒烟骨架:

node scripts/scaffold.mjs <namespace>/<name> --form tool|hook|service|config|llm-adapter [--out <目录>] [--harness <版本>] [--no-smoke]

它只做确定性的事,不碰裁量:

  • 五件套生成:package.json(免构建纯 ESM 不变量:type: module、main 与 exports 双指 lib/index.js、files 含挂载层)、按形态的最小可跑入口(tool 用 raw JSON Schema 注册、hook 走 waterfall 并显式 next()、service/config/llm-adapter 用宿主基类形态)、cordis.patch.yml 最小挂载条目(没有它装了不生效,env-doctor 的 activation 查的就是这层)、dsh-plugin.naming.json、README+.gitignore
  • 命名投影:loader id/service/tool/command/skill/event/route 全部按上游 naming-conventions 的 collision-resistant 规则从 coordinate 推导,生成物已过上游 validate-names 的 --strict 校验(0 错误 0 警告)
  • 当场验证:tool/hook 两形态零依赖直接冒烟(生成即验证注册);service/config/llm-adapter 依赖宿主 @deepseek-ai/* 基类,诚实跳过冒烟并标注装包后手动跑;llm-adapter 的基类 import 来源上游文档没有钉死,骨架里是 TODO 占位,生成后必须对照目标宿主 checkout 核名

目标目录非空即拒绝(不动用户文件);非法 coordinate 在写盘前拒绝。骨架只保证结构与命名合规,能力实现仍以真源文档为准:

需求去 where
五形态完整契约(execute 义务、waterfall 语义、Schema 规则、协议义务清单)原仓库 plugin-write skill 的五份 form reference
公共命名规范与注册表冲突检查plugin-write 的 naming-conventions 与 registry-check reference(validate-names / query-registry 两脚本)
Cordis 教程、API、cookbook官方仓库 deepseek-harness/docs/ 的 cordis-tutorial、cordis-api、cookbook
造完之后一条命令过体检门:node scripts/write-gate.mjs <插件目录> —— 冒烟+启用就绪+四维体检+官方指南核查出「出生证」报告(也可拆开单跑:quick-smoke 秒验 → env-doctor 看启用就绪 → plugin-audit 体检 → code-scan 对目标版本核查)

体检门的判定分层(write-gate)

硬门禁只有三条,fail 即退出码 1:入口产物存在、冒烟通过、对官方指南 critical 零命中。其余全部只透传不拍板——audit 四维分数与 MEDIUM 清单、scan 的 high/medium 命中(带 evidence)、mockFallbacks、尚未挂载 profile 的事实,全部进 discretion 区标「人工裁量」,因为 plugin-audit 的诚实保留信号(如宿主契约下同步是唯一合法写法)和 env-doctor 的未决语义 WARN 替用户判「合格」就是把裁量题伪装成判定题。指南自动发现:显式 --guide 优先,否则用本机宿主版本查 guide-sync 缓存(零网络),都没有就诚实跳过并给补法。新插件核查面是全部历史走廊(localVersion=null 窗口放行全部指南):新代码不该 import 任何已被移除的包,不管哪个版本移除的。刚 scaffold 完加 --skip-smoke 免重复冒烟。

批量场景:整批已装插件的宿主升级巡检

本 skill 一次深查一个插件。宿主刚升级、要把整批已装插件全量过一遍时,先用原仓库 plugin-fleet-sweep 做批量筛查,筛出有问题的插件再逐个回到本 skill 的六步流水线深查——批量管广度,本 skill 管深度。

老插件:官方指南覆盖不到时

官方 upgrade-guide 最早只到 dsh-v0.1.7-rc.2。插件更老、目标版本更老,或跨大段历史走廊时,code-scan 会报 guidesConsidered = 0——这时转 老插件迁移 SOP:用原仓库 plugin-upgrade skill 的人工卡片走廊(dsh-v0.1.0-rc.8 起 19 条边 + 跳版卡)当差异来源,按七阶段 checklist 走:定模式 → 只读准备 → 幽灵宿主检查 → 组装走廊 → 七类触点 → 计划确认 → 六层验证。两套工具的分工速查也在 SOP 里:有 guide 的段用本 skill 的 code-scan,没 guide 的段用原版的 plan-migration.mjs 和卡片,运行时验证用原版的 verify-runtime.mjs。

怎么读结果

命中为零不代表没问题,代表「在官方指南覆盖的范围内没踩到」。 指南只记录官方认为需要通知的破坏性变更,不覆盖所有可能性。

命中要多看一眼是不是误报。 这个技能的锚点匹配做了几层降噪(见 references/heuristics.md),但同名符号仍然可能撞车,比如插件里的 path.resolve() 和 guide 里的 runtime.resolve()。判断方法:看命中位置的代码上下文,确认那个符号是不是真的来自宿主 API。

member 命中里,如果符号是 guide 的「迁移目标」就不会出现。 插件用了新 API 说明已经适配过,报了只是噪音。

安全边界

  • 只读为主。env-doctor、code-scan、plugin-audit 完全不写文件。
  • quick-smoke 会执行插件代码(动态 import 入口模块)。它只用于你自己的插件或审过的代码,不要对来路不明的目录跑。执行面限于 Node 进程内,但插件代码理论上能做任何 Node 能做的事。
  • 自愈默认 dry-run。env-heal 不加 --apply 只报告;加了也是「移动」而不是删除,进 ~/.dsh/.trash/<日期>/。
  • 不改 DSH 本体。只读环境信息,不动 ~/.dsh 下的配置和 profile 声明。
  • 不自动改插件代码。只报命中和官方修法,改不改、怎么改由人决定;plugin-audit --peer-patch 也只打印建议不写 package.json。
  • sync-skill 显式写下游目录,只复制固定技能面(SKILL.md/README*/references/scripts),--check/--dry-run 供先确认;改的是下游副本,不动主仓。
  • 网络只在 --clone 时用。npm registry 和 git clone 都有超时,失败会明确报错而不是静默跳过;dist-tags 有 1 小时缓存,网络失败时降级用旧缓存并标 stale。
  • 日志只落本机。run.mjs 的运行日志写在 ~/.cache/dsh-plugin-fast-adapt/runs/,含本地路径与用户名,外发前必须 run-log.mjs sanitize。

自检

npm test

130 项断言,覆盖扫描器不误报(注释和字符串里的同名词不算命中)、不漏报、真实 semver 范围判定(prerelease tuple 规则,本轮与宿主自带 semver 对拍的 30 例锚点回归)、扫描窗口计算(宿主包 peer 精确匹配、cordis/schemastery 版本线不混入、倒挂守卫回退留痕)、目标形态判定(dsh 命名空间/生态依赖证据、非插件 N/A、工具仓跳过 Cordis 生命周期)、import type 区分、宿主实测核查分级、描述漂移检测、指南出处锚点(guideFile/guideLine 落盘往返)、接缝查询双源结论(一致已移除/宿主仍在报分歧/无记录如实说/探不到宿主不伪造)、运行日志×宿主日志交叉核对、--real-smoke 桥接档位(fail→退出码 2、tail 归因透传、失败指路)、一键编排与运行日志(写入/索引/脱敏往返、phases 三态、dirty 标记、90 天保留清理)、上游盯梢退出码(upgrade-available→1 其余→0)、同步提交命令建议(git 仓给只 add 同步路径的命令、非 git 静默跳过)、版本启发式、替换对识别、端到端命中、SOP 引用完整性、dist-tags 缓存三态、冒烟验证(含未声明 inject 契约拦截与 Mock 缺口披露)、四维审计(含 peer 修补建议)、启用诊断(宿主半 Silent Pending+客户端半三层判定:声明/产物/注入名册死链)、环境层盲区三处(共享 node_modules 农场悬空软链的 critical/info 分级、全局 patch 层对所有 profile 生效且 disabled 也参与判定、入口解析按 exports 优先于 main 防无 main 包被误报 ERROR)、创作脚手架(五形态生成与冒烟闭环、命名投影语法、挂载层可识别、非法输入与非空目录拒绝)、创作体检门(硬门禁拦截、软指标不越权判红、跳过语义、scaffold 衔接)、日志诊断(startup 头部/失败插件/等待服务/信号/跨文件汇总)、下游同步漂移检查+真机零漂移拦截、self-test 体积门禁(超 2200 行即红)、跨平台模拟(Windows 根探测与缓存隔离)、文档断言数防漂移、扫描性能回归门。零网络、零外部依赖,任何机器上都能跑(Windows 分支已做模拟验证,真机待验)。

提交前门禁:git config core.hooksPath .githooks(一次性)启用 pre-commit 钩子,commit 时自动跑本自检——改完真源忘了 sync-skill 在这一刻被拦,不用等有人跑 npm test。

脚本清单

脚本职责
scripts/run.mjs一键编排全流程 + 写本地运行日志
scripts/run-log.mjs运行日志查看(list/show)与脱敏导出(sanitize)
scripts/env-doctor.mjs探测本机 DSH 环境(版本、覆盖层、共享农场悬空软链、两层 patch、插件、进程、宿主半+客户端半启用就绪度)
scripts/env-heal.mjs覆盖层旧包自愈(默认 dry-run)
scripts/guide-sync.mjs定目标版本 + 取官方升级指南(dist-tags 带 1 小时缓存,失败降级旧缓存)
scripts/code-scan.mjs扫描插件代码,匹配官方变更锚点(findings 带指南文件+行号出处)
scripts/seams.mjs接缝查询:一个包名/API 符号在指南锚点表与本机宿主里的双源结论
scripts/quick-smoke.mjs修完秒验(内存级 Cordis 冒烟,含 Mock 兜底披露)
scripts/plugin-audit.mjs四维性能架构体检,可叠加官方指南交叉;--peer-patch 打印已验证的 peer 修补建议
scripts/log-doctor.mjs一键解析 ~/.dsh/logs/ 的宿主故障(startup 头部/失败插件/等待服务/信号汇总)
scripts/sync-skill.mjs把技能面同步到下游技能目录,--check 查漂移
scripts/self-test.mjs自检
scripts/lib/scanner.mjs词法扫描器与版本比较(零依赖)
scripts/lib/guide-parser.mjs官方指南解析与锚点抽取(含移除动词语义门)
scripts/lib/runlog.mjs运行日志写入、索引与脱敏
scripts/lib/client-graph.mjs客户端半三层判定:dsh.client 声明校验、./client 产物解析、注入名册死链(强弱证据分档)
references/legacy-migration-sop.md老插件迁移 SOP(官方指南覆盖不到时的对照手册)
references/ci-snippet.md插件仓 CI 门禁模板(把「升级后插件报错」提前到提交时:冒烟/typecheck 硬门+体检软门)

Sweep a Plugin Fleet Across a DSH Host Upgrade

A host upgrade changes the contracts every plugin rides on at once. The unit of work is not one plugin: it is the fleet, swept in a fixed order, with one verdict per plugin and one release loop per broken plugin. The sweep runs against the REAL upgraded host - sources and Node-based tests passing prove nothing about browser-engine and runtime-surface changes.

Standing rules

  1. Verify on the target host, not in sources. A plugin "loads" when its client bundle is served, its CSS style[data-plugin] tag exists, and zero slot entry crashed / activation-failure records appear. A plugin "works" only when its surface marker is in the DOM and its expected requests fire. Record which of the two you have proven.
  2. One static sweep first, cheaply. Grep every plugin source for the APIs the new host renamed or removed (from the target version's corridor cards in plugin-upgrade/references/) before touching a browser. Static hits are already verdicts: broken-until-fixed.
  3. Absence of errors is weak evidence. A surface whose UI is interaction-gated (appears only after a paste, a file operation, a focus event) shows nothing in a idle sweep. For each plugin, know its trigger and either simulate it or mark the verdict "loaded, interaction path not exercised" instead of claiming success.
  4. Fix and release per plugin, never as a fleet commit. Each broken plugin gets its own branch-or-main commit, version bump, changelog row, tag, and mirror push (the repositories' own mirror flow; sync-mirrors.mjs is specific to the author's plugin repositories - use whatever the target repository documents, or skip mirrors if it has none). Mixed fleet commits make per-plugin rollbacks impossible.
  5. Compatibility builds over host-locked builds when the plugin must span host generations: resolve renamed host exports at runtime through a fallback chain (old name → new variants) instead of static named imports, and extend unit-test module mocks with every fallback name (strict mocks throw on undefined-export access and mask the real failure).

Workflow

  1. Read the target host version's corridor cards (plugin-upgrade/references/v<target>.md) and derive the static sweep patterns from them - the cards name the renamed/removed surfaces.
  2. Static sweep: grep every fleet repository for those patterns; record hits as broken-until-fixed with file:line.
  3. Live sweep: load the real GUI in a driven headless browser against the upgraded host and per plugin assert (a) the client CSS/style tag present, (b) zero slot entry crashed console records, (c) the surface's DOM marker present, (d) the expected requests fired. Method: references/fleet-sweep-checklist.md (includes the authenticated-GUI access and instrumentation discipline from plugin-runtime-debug/references/browser-forensics.md).
  4. Re-verify interaction-gated surfaces with their trigger simulated (paste, file write, keyboard chord) or downgrade the verdict explicitly.
  5. For each broken plugin: diagnose against the host source (plugin-runtime-debug standing rule), fix with a host-generation-compatible approach when the fleet spans host versions, run the plugin's typecheck/tests/build, then release: version bump, changelog/compatibility-table row naming the host version range, commit, tag, mirrors.
  6. Re-run the live sweep after releases and record the final per-plugin verdict table (plugin, host versions supported, evidence).

Report

End with a per-plugin table: verdict (working / fixed+released / interaction-path-unexercised / broken), the host versions covered, and the evidence (which assertion passed where). Note any host bug found (report upstream with the minimal repro) and any hot-fix living in the install tree that the next host upgrade will overwrite - list the reapplication material.

Add Heavy Dependencies to a Lightweight DSH Web Plugin

A lightweight Web plugin (small client bundle, no build farm) can still ship a multi-megabyte renderer — if the heavy code never loads until it is needed and degrades gracefully when it cannot load. This skill is the integration checklist; every item below was earned from a real mermaid integration.

1. Decide lazy vs inline

If the dependency would multiply the client bundle several-fold and only one feature needs it (a fence renderer, an editor opened on demand), do NOT inline it into the client bundle. Split it into a separate chunk file the client imports dynamically only when the feature actually renders.

2. Bundle the chunk as ONE file

Bundle the dependency into a single self-contained ESM file with code-splitting disabled. A general-purpose bundler left on default settings splits the library's internal dynamic imports into sibling chunk files with content-hashed names — the browser then resolves them as relative imports against the chunk's URL, and every sibling must also be served, named exactly, and MIME-correct. One file, one import, no relative-resolution class of bugs.

3. Serve it from a host route scoped to your own lib

Register a prefix route on webServer that serves files from the plugin's own lib directory only:

  • Resolve the lib directory from the host bundle itself (import.meta.url), never from process.cwd().
  • Restrict to a whitelist of extensions (your chunk is .js/.mjs — nothing else should ever be served).
  • Containment guard: verify the requested path stays inside the lib dir. Two hard-won rules:
    • Compare with path.relative, not startsWith: a prefix compare is wrong the moment the filesystem normalizes differently than your base string.
    • Windows drive letters change case: realpathSync may return e:\… where your base says E:\…; a case-sensitive compare then misjudges a perfectly contained path as an escape and answers 403. path.relative (plus an isAbsolute check on the result for cross-drive) is robust.
  • Serve with a JavaScript MIME (application/javascript) — a wrong MIME makes the browser reject the dynamic import.

Remember: the host route only exists after a dsh restart; a hard refresh alone does not register new host code. A 404 on a freshly added route almost always means "not restarted yet" or "the installed copy predates the route".

4. Import lazily, cache verdicts, fall back

  • import() the chunk URL on first render of the feature; cache the successful module so repeated fences do not re-import.
  • Do not cache failures the same way — or a transient failure sticks for the page lifetime; let the next attempt retry, but throttle (a failing import in a loop is its own console spam).
  • Always render a fallback (e.g. the original code block) when the import or the render throws; reading must never break because a diagram could not load. Tag the fallback with a state attribute and log the failure reason to the console — "it fell back" without a reason is undebuggable.

5. Untrusted markup: sanitize before innerHTML

A renderer fed untrusted text (markdown, model output) emits markup you must treat as hostile before dangerouslySetInnerHTML:

  • Configure the renderer to its strict mode and to emit real SVG text rather than HTML labels (HTML labels ride inside <foreignObject> — the one channel that carries raw HTML inside an SVG).
  • Suppress the library's global error side effects (some renderers dump a giant error SVG into document.body before rejecting).
  • Then re-sanitize the emitted SVG yourself with a zero-dependency whitelist pass: parse as XML (image/svg+xml; a parse failure rejects the whole string), accept only an <svg> root, strip foreignObject/script and foreign-HTML elements case-insensitively, strip on*/@* attributes, and strip all href/xlink:href (static diagrams gain nothing from links; a hostile href can navigate the GUI). Defense in depth, not defense instead.

6. Interaction ownership under a modal

A fullscreen zoom/pan modal over the plugin's panels must own ALL wheel events while open — including Ctrl+wheel, if the underlying pane already binds Ctrl+wheel (font sizing). Guard the pane-level handler with a modal presence check; otherwise both behaviors fire on one gesture. Modal zoom: wheel anchored at the cursor, drag to pan, keyboard shortcuts, Esc/overlay click to close.

7. Ship it

  • Commit the built chunk to the package (the plugin ships lib/); declare it in files so published payloads stay closed.
  • Document the restart requirement (host route) vs refresh-only (client) in the release notes — users hit 404s otherwise.
  • A regression test per pitfall: the fallback path (chunk import fails → original rendering), the sanitizer (strips the hostile channels), and — for the host route — a containment test that a case-differing but contained path is served, not refused.

English | 简体中文

plugin-release

Ship developed, tested plugins safely. Publishing is a one-way outbound action — show a plan and obtain confirmation before any actual publish or tag push; this skill does not decide version numbers for you, and it never bumps versions automatically.

Step 0: confirm the target version and release track

Release trackApplies toKey facts
GitHub direct installdsh plugin --profile <p> add github:owner/repoConsumers resolve the default-branch HEAD; publishing = pushing to main — run the full gate before pushing
npm registrynpm publishOfficial release line only; alpha/rc-prefixed @deepseek-ai/* versions are not guaranteed on npm — verify with npm view <pkg> versions before publishing
hub listingregister in the hub catalogRegistration is a separate action and does not replace packaging validation
collectionmember plugins vendored into a pack artifactFollow the owning collection repository's own process

The unpublished cohort (for example a cohort version that was never published to npm — alpha.1 was GitHub-only; alpha.2 through alpha.4 are published under the alpha dist-tag) goes through the overrides flow in references/publish-playbook.md. Do not look for versions that do not exist on npm, and do not switch package managers because of it.

Step 1: pack and validate the artifact

  1. Use the repository's single package manager and lockfile (package-lock.json → npm, pnpm-lock.yaml → pnpm);
  2. Run the full gate (see Step 3), then npm pack / pnpm pack;
  3. Unpack and validate: files covers every runtime relative import and asset; no .ts leftovers in the artifact; the manifest files such as cordis.patch.yml / dsh.plugin.json / SKILL.md are all present;
  4. Install the tarball into an isolated profile for consumption validation (the plugin's row appears in dsh --profile compat --dump-config → the tool is genuinely registered and executes).

Step 2: version dependency baseline (alpha era)

  • devDependencies use the npm release line (currently 0.1.1-rc.2) as the type baseline, so a public repository typechecks after npm install on any machine;
  • peer ranges use a wide range (such as <0.2.0) to cover unpublished alphas/rcs;
  • when code must stay compatible with both the local harness (GitHub tag) and the npm release line, use the dual-compatibility pattern: keep the shape that the npm release line's types require, while the alpha runtime semantics remain unchanged (see the "dual-compatibility pattern" section of the playbook);
  • never write local absolute paths (junction/file:) into a committed package.json.

Step 3: release gate (layer by layer; a lower layer must pass before the next one)

  1. Dependency resolution: the lockfile changes only as expected; no mixed cohorts;
  2. Static: typecheck + plugin tests + build;
  3. Real mount: cold-boot the target host on an isolated profile pinned to an exact DSH tag (never let a mutable master/main masquerade as acceptance), with the entry active and no service left pending. Web Client plugins must additionally verify: the host-advertised resources (the bundle entry from the boot manifest/boot list) are reachable, the bundle registers successfully, the DOM mount completes, and there are no page errors — looking at --dump-config alone does not complete this layer;
  4. Behavior: one core path actually executes (for tool plugins: one message → tool → response; or an equivalent dedicated flow);
  5. Wrapper: verify exit codes and stdout/stderr attribution.

Step 4: release semantic gate (stop publishing if any check fails)

  1. The GitHub Release tag must equal v${package.json.version};
  2. Whether the version carries a prerelease suffix (the segment after -, before the + build metadata) must match the GitHub Release's prerelease status;
  3. Prereleases may only go to a project-declared non-latest dist-tag (the name is chosen by the project, such as next or alpha — the skill does not hard-code a specific name); only stable versions without a suffix go to latest;
  4. Before a stable publish, query the current latest (npm view <pkg> dist-tags.latest) and refuse to publish when the semver is lower than the existing latest, to prevent moving latest backwards to a lower version.

Step 5: publish and rollback

  • Before publishing: clean commit + tag; record the lockfile and composition baseline hashes;
  • After publishing: reinstall once as a consumer and smoke-test;
  • Rollback: prefer reverting the release (delete the tag / re-point at the old commit); do not publish a "works on both sides" patch to paper over the problem;
  • For unpublished-cohort CI, see the "CI and release gates" section of the playbook (cohort store caching, the NPM_PUBLISH_ENABLED switch).

Safety boundaries

  • Show a plan and obtain confirmation before any publish / tag push / hub registration write; never bump versions automatically;
  • Never publish artifacts containing credentials, .npmrc contents, session logs, or private paths;
  • Do not switch package managers or rewrite a different lockfile; on failure, roll back only the paths owned by this run and report residue.

References

FileContents
references/publish-playbook.mdUnpublished-cohort installation, dual-compatibility pattern, CI/release gates, real pitfall list, and rollback recipes
references/profile-dependency-management.mdProfile install/update recipes: github dependency lock caching, three-place sync on package rename, junction cleanup, and host-upgrade linkage

Debug DSH Web Plugin Runtime Behavior

External Web plugins call host client APIs whose contracts live in the DSH source tree, not in the plugin's own types. When behavior diverges from intent at runtime, the failure is almost always a misread contract — and the diagnosis must come from the host source, never from the API's name.

The standing rule: read the verb's contract in the host source first

Before changing any call into a host API, open the implementing package in the DSH source checkout (~/.dsh/source/current, or the vendored copy) and read the actual method — its doc comment, its guards, and the types it compares against. Repeat for every value the plugin passes. Four questions cover most incidents:

  1. Which text does an offset count into? When a verb takes a span or an offset, find out what string those numbers index. Published snapshot fields and internal editor projections are not always the same string; a plugin that feeds one representation's offsets into a verb whose guard compares against another representation fails silently — the call returns false or no-ops, nothing throws.
  2. What does one "unit" weigh in each representation? If the document contains opaque inline units (chips, tokens, attachments), check whether a unit occupies the same width in the published field as in the projection the verb guards. When widths differ, offsets are only correct while no unit exists — verify what the first call succeeding and every later call failing tells you.
  3. When the verb declines, who notices? A boolean-returning verb that fails silently turns into a downstream state bug: the caller deletes its own bookkeeping anyway, and the UI renders a "missing/unavailable" placeholder next to an object that never went away. Audit every call site for the "fire, ignore the result, clean up state anyway" shape.
  4. Which engine evaluates this line? Web-platform behavior that tests run under Node never exercise can differ in the user's browser, because older engines predate the current standard. The known family: URL parsing of non-special schemes — the WHATWG URL Standard requires new URL('dsh-resource://file/…').hostname to be "file", which Node and current Chromium return, but Chromium before its standards-compliant non-special URL parsing change returned "", so an older Chromium-based Edge build returns "", silently. Record the exact browser version when you see this. Any host or plugin code that routes by URL.hostname/.pathname on a custom scheme works in every Node-based test and fails only in affected real browsers. Before trusting a URL property on a custom scheme, assert it in the actual browser engine (see references/browser-forensics.md), or parse the string by hand.

Symptom families and where they point

  • First interaction works, every subsequent one errors — state written by the earlier call changed the mapping between what the plugin computes and what the verb expects. Compare the two representations before and after one insertion; derive the correction from the unit widths in the host source, then apply the same derivation at every call site that passes offsets, not just the crashing one.

  • A removal button leaves the row behind with a placeholder label — the removal verb declined (see question 3) while bookkeeping was already dropped. Confirm with the verb's return value, and only retire the bookkeeping after the removal actually applied.

  • Derived UI shows stale or phantom entries — find the authoritative source of the fact and derive the view from it. A plugin-side cache with a subscription that retires entries on any transient snapshot (an empty moment during reconcile/remount) will drop live entries; prefer reading the live published state at decision time and treat the cache as an accelerator only.

  • Update/version chips report a wrong "latest" — remote tag and raw-file endpoints are CDN-cached and lag minutes behind a real push. Never present a fetched remote value as ground truth when it can be older than the running build; decide "current vs update" against the running version and display the newer of the two.

  • A built-in surface shows its generic "service unavailable" fallback in the user's browser while registration, composition, and module activation all verify clean — stop auditing registration and start auditing what the failing code reads from its platform. Real case (0.1.6-alpha.2, 2026-09): the right-sidebar document preview showed 「文件资源服务不可用。」 for every file; the file resource provider WAS registered, __DSH_BOOT__ was complete, and zero activation failures existed — the provider router had asked new URL(address) .hostname for the protocol of a dsh-resource:// address and gotten "" on the user's Edge, so lookup always missed and no request was ever sent. The placeholder copy names the feature, not the failure layer; only instrumenting the router produced the decisive line (parsedHost=""). When a fallback string is all the user can report, reproduce with instrumented bundles in a driven browser (see references/browser-forensics.md) before concluding anything about registration state — an earlier misdiagnosis of this exact incident blamed "provider silently unregistered".

  • A whole slot's UI silently vanishes after a release — a throwing expression inside a slot component (classically a dangling identifier: another component's state variable referenced out of scope) is caught by the framework's slot-level error boundary, which unmounts the entire entry; the error is console-only, so users just report "the chips/panel are gone". Two latency mechanisms hide it from the author: an || short-circuit keeps the expression unevaluated until the left operand is false, and components that early-return on the empty state never evaluate it until real data renders. Do not blame the newest diff by default — bisect by rollback or a minimal render mount with data present, check whether the throwing line shipped earlier, and fix by removing the reference (scope any such state locally). Cheap hardening for slot components: defensive reads (x?.items ?? []) and optional-chained DOM access (target.closest?.()) — inside an error boundary any throw costs the whole slot.

  • Repo edits never reach the GUI / EBUSY under the profile's node_modules — first determine the install mode: Get-Item <profile>/node_modules/<pkg> | Select LinkType, Target (or the link:<path> marker in cordis.patch.yml). A Junction/link install means the repo working tree IS the installed copy — no copy step exists or is needed, and Copy-Item into node_modules is a no-op at best. The EBUSY holder is the running dsh host process (closing the browser does not release it), and the browser can still serve a cached client bundle after the host restarts. Activation for a link-installed lib-only plugin: fully stop the host, restart dsh web, hard-refresh, then verify the loaded version marker. Never rename-aside files under an unresolved path: through a junction "two" directories are one, and the rename moves the only copy. A source-launched host (pnpm dsh web in the harness checkout) adds two constraints: the client bundle combo is assembled once at boot (no HMR rebuilds it — every plugin edit needs a full host restart), and on Windows the listener port stays bound by the dying tree unless you stop the whole process tree (taskkill /PID <pid> /T /F), or the next boot dies on EADDRINUSE.

  • One plugin with raw ESM in its client bundle takes every plugin down, and the error names an innocent entry — the host concatenates all client bundles into one classic <script> combo; a single top-level import anywhere makes the whole multi-megabyte combo fail to compile, zero plugins register, and the browser surfaces failed to import loader entry <first-entry> — the first awaited entry (often dsh-typert-registry, itself perfectly fine), not the culprit. Do not chase the named entry: bisect the profile's insert rows (or point the suspect bundle through node --check) until the combo loads again. The client half is not a bare ESM module — it must register through window.__ModuleLoader__.load({ id, factory }), pull react inside the factory via require("react"), and export inject/apply.

  • Phantom pixels at the right edges of a terminal sprite (outline, Z symbols, hearts), and ghost pixels surviving frame switches — two half-block ANSI rendering defects, both invisible in the frame data: (a) a half-filled cell (upper-half block with only one half colored) sets the foreground but leaves the SGR background from the PREVIOUS cell set — SGR persists across cells, so the stale background paints a phantom pixel into the empty half; reset it explicitly (ESC[49m on every half-filled cell). (b) rows trimmed at their trailing transparent cells let a NARROWER frame leave the previous frame's pixels to the right of the trim — paint every row across the full sprite width (transparent cells as plain spaces) and close with an erase-to-EOL (ESC[K). And pin the frame data itself: hand-ported sprite frames drift from the source art a few cells at a time (a regression over an excerpt misses it) — digest every frame against the source and assert the digests.

  • A head/UI process hangs for minutes (or until the CI timeout) after its work is done — a rescheduling timer chain (an animation planner that re-arms setTimeout forever while mounted) keeps the event loop alive on hosts that mount the component without ever unmounting it (probe and test hosts; a GitHub job defaults to a 6h timeout). The interactive TUI stays alive on its TTY/stdin handles regardless — so unref the chain (timer.unref()): the probes drain and exit, real sessions lose nothing. Suspect this whenever enabling a feature flips previously-finishing jobs into timeouts.

Workflow

  1. Reproduce once and capture the exact user-visible strings (toast text, chip labels, console output) — they are the contract of the bug report.
  2. Map each string to the code path that emitted it; identify the host verb at the boundary.
  3. Open the host source for that verb; answer the four standing questions.
  4. State the mismatch precisely (which representation, which guard, which call sites) before writing any fix; if you cannot state it, you have not read enough source.
  5. When the mismatch is not visible in any console output — generic fallback copy, silent no-op, or a divergence only the user's browser shows — reproduce it in a driven browser with temporarily instrumented bundles (backup, patch with one decisive log line, verify, revert), following references/browser-forensics.md. A user-pasted DevTools screenshot is evidence of the symptom, never of the cause.
  6. Fix every call site that passes representation-dependent values, not only the reported symptom; the same mismatch usually breaks two features through two different verbs.
  7. Prove the fix with the interaction sequence that failed: repeat the action twice in a row and assert both attempts behave identically, and assert the removal path clears every view of the object.
  8. For lib-only plugin bundles (no build step): keep hand-inlined version constants in sync with package.json, syntax-check the bundle (node --check), and verify in the browser after a hard refresh — the served artifact is the file you edited.

Test DeepSeek Harness Plugins

Select the smallest set of test levels that proves the change is correct. Do not run the full suite by default or repeat checks that have already passed.

Test Harness Version Migrations

When adapting an existing plugin to a new DSH host version:

  1. Read references/version-migration-testing.md, build a migration ledger for the exact from/to versions, and scan all seven touchpoint classes.
  2. Add a targeted regression test for every applicable breaking or behavior change. A change-level test proves only that migration mapping; it does not prove the whole plugin is valid.
  3. Cold-start the exact target version through the real product entry point and complete a full user turn. Typechecking, config parsing, Loader smoke tests, and mock Contexts cannot replace this runtime proof.
  4. Report unavailable credentials, providers, operating systems, browsers, PTYs, and destructive-migration boundaries honestly. Do not claim comprehensive compatibility when any remain unverified.

The commands and repository paths below use test-level names from the official Harness monorepo. For external plugins, use equivalent scripts and paths from their own repositories. Do not add nonexistent Harness root commands or impose the monorepo layout on them.

Run a Docker Release Smoke Test

For a pre-release external plugin check, read references/docker-release-smoke.md and use the included runner on the packaged artifact. Pin one exact DSH version and a non-latest Node image, install the artifact into an isolated Profile, cold-start the real DSH entry, and add one argv-based functional probe when startup alone does not exercise the changed behavior.

Treat the generated JSON and Markdown as narrow evidence for that artifact and target. Report skipped providers, browsers, operating systems, security checks, and additional versions as unverified; a passing Docker smoke test does not expand its own coverage. Keep generated reports, raw logs, temporary Profiles, and Docker cache outside the Skill directory.

Test Levels

LevelCommandWhat it proves
Unit testspnpm run testRuns vitest cases under each package's tests/** and script tests under repository scripts/**/*.spec.ts. Cover edge cases, error paths, event ordering, concurrency races, and contract regressions. Every registry needs an HMR-safety test: dispose the fiber that contributed the registration and assert that the resource is removed.
Coverage gatepnpm run test:coverageIn the Harness monorepo, every file under packages/*/*/src must reach 100% coverage. In an external plugin, follow the coverage threshold declared by its repository. Coverage proves only that lines executed, not that the published feature actually works.
Real-API end-to-end testspnpm run test:e2eValidates behavior against real provider APIs, including DeepSeek models and provider smoke tests gated by their own credentials such as EXA_API_KEY and PERPLEXITY_API_KEY. Each suite skips itself when its credential is absent so credential-free CI remains green.
Snapshot testspnpm run test:snapshotValidates expected credential-free output, pinning transport contracts and presentation while using persisted logs to fix the assembled backend behavior.
Web browser snapshotspnpm run test:webCompares Chromium replay output with apps/web/tests/snapshots/. This is a required Linux PR gate. CI forces read-only DSH_SNAPSHOT=replay and never writes expected output. Record or refresh snapshots only locally and review every difference.

When provider credentials are available and real-API execution is authorized, run the corresponding end-to-end tests. Do not skip them merely to save inference spend. Credential-free tests prove only that the pipeline is connected; only credentialed runs prove that the Agent can work with a real model. Based on the change, cover file-writing prompts, multi-turn sessions, tool use, and cancellation during streaming output. The highest-value smoke test starts a real example, sends one prompt, and verifies the outcome from outside the Agent. Automatic skipping keeps credential-free CI unblocked. Record every skipped provider boundary, and never request, expose, or persist credentials merely to make tests pass.

Select Levels from the Change Surface

  • Pure logic or internal helpers → run unit tests only.
  • New or modified package source → run the repository's coverage gate. Apply the per-file 100% rule only when the Harness monorepo explicitly defines it.
  • Model-visible behavior such as prompts, tool Schemas, tool output, or Skill directories → add a credential-free snapshot to the owning example suite, then add a real-composition test.
  • Protocol-visible behavior such as ACP, JSON-RPC, or wire transport → add a credential-free snapshot to the owning example suite.
  • User-visible behavior such as CLI transcripts, interactive terminals, or GUI flows → in the Harness monorepo, use apps/cli/tests/snapshots/ or apps/web/tests/snapshots/; in an external plugin, use the product-entry test suite owned by that repository.
  • Provider behavior such as a new adapter or real provider feature → run real-API end-to-end tests when credentials are available and execution is authorized.
  • A plugin that users will actually run → execute a non-unit real-composition test as described below. Never test only a manually assembled ctx.plugin(...).

When Snapshot Tests Are Mandatory

Every nontrivial model-visible, protocol-visible, or user-visible change must add or update a credential-free scenario through a runnable composition owned by the repository. Package tests, end-to-end assertions, test-only mock compositions, and PR descriptions cannot replace the complete assembled record. In the Harness monorepo, ACP snapshots live under examples/<name>/tests/snapshots/, headless JSONL snapshots live under examples/headless-agent, terminal flows live under apps/cli/tests/snapshots/, and browser flows live under apps/web/tests/snapshots/. Use the record or refresh command provided by the exact target checkout and review every generated difference. External plugins should use their own snapshot framework. If they have none, add a minimal composition that runs through the real Loader.

Test the Real Entry Path

  • User-visible plugins need a real-composition test. Start a test-only cordis.yml through the Loader and application or process entry point. Mock only external services or nondeterministic inputs. Assert the model-visible request or log, persisted state, or user-visible output. Do not add test options to published defaults.
  • A guard test is useful only if the regression truly makes it fail. When the exact target contract requires a bundled or composition module without inject to use named exports, add explicit expect('default' in mod).toBe(false) and unwrapExports round-trip assertions. Prove that the test turns red when the regression is introduced and green after the fix. Do not apply this guard to default plugin objects or Service classes supported by the target version. Validate those forms through their actual Loader contract.
  • The "real entry path" means the published artifact. A package bin must run its built entry under native Node to expose issues that tsx may hide, including shutdown races, module resolution, and swallowed load failures. Apply the same rule to runtime entries outside the default index and singleton modules shared across bundle compositions. In the Harness monorepo, keep its built-artifact smoke tests green, such as packages/examples/*/tests/built-bin.e2e.ts and packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts when they exist in the target version. In an external plugin, smoke-test its packaged entry. Assert that the process exits nonzero when required configuration is truly missing.
  • In the Harness monorepo, normal tests resolve through the configured source plane, while only explicit built-entry smoke tests consume build artifacts. In an external plugin, follow its resolver but still add one explicit packaged-artifact consumer so source aliases cannot hide a missing export or a second runtime singleton.
  • For subprocess startup in the Harness monorepo, CI and built-test channels must use the shared launcher from the target checkout to run every example or Cordis config subprocess from built lib/. Never hand-write --import tsx for those subprocesses. Protocol and operating-system fixtures that do not load Cordis follow the current Node/TypeScript convention of the target repository. External plugins follow their own launcher but must cover the packaged artifact. Choose src only when source-path resolution itself is the test subject, and document that contract in the test.

Keep Tests Effective

  • Prefer real implementations over mocks. Mock only expensive or nondeterministic boundaries such as LLM adapters, networks, and clocks, while keeping everything downstream real. A handwritten fake proves only that a bridge moved bytes; it does not prove that the published tool delivers its claimed behavior. Tests for bridged tool calls should use a scripted mock model while keeping the tool and executor real.
  • Verify the external world instead of trusting the Agent's report. End-to-end assertions should rerun commands or reread files outside the Agent. Checking only keywords in Agent output lets a cheating Agent pass. Assert that untouched files remain byte-for-byte identical.
  • End-to-end tests must own their resources. Create the Harness inside the test and dispose it in afterEach, including after failure, retry, or timeout. Put shared fixtures in a normal tests/harness.ts, never another *.e2e.ts; importing a test file registers its describe again and duplicates real-API calls.
  • Recovery tests must separate failures before and after each chunk boundary and prove that a failed chunk derives no messages or tool side effects. Cover exhaustion, cancellation, policy composition, persistence, state, wire counts, transport-close idle timeouts, and the production Loader composition.

Commands

In the Harness monorepo, use commands that actually exist in the target checkout, such as pnpm run test, test:coverage, test:e2e, test:snapshot, and test:web. Confirm each script exists instead of assuming a historical command list is still valid. In an external plugin, use its own scripts, package the artifact, install it into an isolated Profile running the exact target version, and execute a cold-start plus core-path smoke test through the product entry. Run the smallest set that covers the changed surface only once. CI proves only the gates it actually defines.

See references/README.md for the reference index.

English | 简体中文

plugin-upgrade

Safely handle three task types: read-only update inspection, installed-plugin upgrades, and DSH host version compatibility migration. If user intent is unclear, confirm the mode first; never let "help me check for updates" slide into installing or changing code.

Note: the version cards and reference docs under references/ are in English; card IDs and cited commands are language-neutral.

Step 0: choose a mode

ModeUser intentDefault allowed action
A · inspectCheck for updates or assess impact from a DSH releaseRead-only investigation and report; then stop
B · updateUpgrade an installed plugin to an explicit versionPlan and confirm before changing composition or dependencies
C · author-migrateUpgrade a plugin author's source repository for a newer DSH hostBaseline, build the version corridor and touchpoint inventory, then implement the approved migration

This skill does not handle "upgrade DSH core only and leave the plugins alone," and it must not modify DSH core to conceal plugin incompatibility.

Global DSH host upgrades (agent discipline)

Upgrading the dsh host itself (npm install -g @deepseek-ai/dsh@…) is not Mode B/C plugin work — and when the requesting agent runs INSIDE a dsh session it is structurally fatal: the session IS the host process, npm removes/replaces the very package tree it executes from, the host dies mid-install (the tool call never returns), and the interrupted install leaves package content present WITHOUT regenerated shims — the dsh command itself is gone until an external pinned re-install repairs it. Never execute the global host upgrade from inside a session on that host; hand the user the external procedure:

  1. fully stop every dsh process (a running host holds native-module file locks → EBUSY; a browser refresh is not a host stop);
  2. from an EXTERNAL terminal, run the pinned install npm install -g @deepseek-ai/dsh@<exact-version> (a bare package name resolves to the latest dist-tag and can silently downgrade to an older line);
  3. restart dsh web, hard-refresh the browser, verify version markers and plugins.

Because the host is fully stopped before npm runs, nothing crashes mid-install — a crash during the upgrade is a signature of doing it wrong, not a risk to tolerate. If an install was already interrupted: repair from an external shell by re-running the pinned formal install (never hand-copy package directories or hand-write shims).

Shared read-only preparation

  1. Read the target repository's rules such as AGENTS.md / CLAUDE.md; check branch, HEAD, working tree, and submodules. Stop and report unfamiliar changes or untracked files; never auto-stash, reset, clean, or checkout.
  2. Record source identity and installation identity separately: registry package, Git checkout, workspace/junction, or copied install; record the source repository/URL, Git SHA, actual package name, the plugin's own version, the declared/resolved DSH dependency cohort, and current DSH/Node versions. A plugin release version (for example 0.6.4 → 0.7.0-alpha.0) is not the DSH host corridor (0.1.0-rc.6 → 0.1.2-alpha.4). GitHub owner/repo and registry scope/package are independent coordinates — do not derive or rewrite one from the other.
  3. Preserve file ownership boundaries:
    • package.json / lockfile: package and dependencies;
    • dsh-plugin.json: community-standard manifest (if adopted);
    • cordis.patch.yml / agent.cordis.yml / legacy cordis.yml: profile composition;
    • resolved config: runtime composition result, used for verification only; never write the whole object back.
  4. Verify the target version's source, tag/package name, compatibility range, release notes, install scripts, and known breaking changes. Never read, print, or commit tokens, .npmrc contents, credentials, or session logs.
  5. Record the rollback baseline: current HEAD/package version, lockfile, and hashes/paths for configuration that may change. Describe recovery only for the explicit paths owned by this task; do not promise rollback of arbitrary third-party script side effects.

Mode A · inspect (read-only)

Report: current/available versions, source, compatibility range, breaking changes, recommended target, risks, and a validation plan. Do not edit files, install dependencies, run lifecycle scripts, git pull, or switch versions. If the user decides to proceed, enter Mode B or C with separate confirmation.

Mode B · update (upgrade an installed plugin)

  1. Choose the single update mechanism that matches the resolved package identity and installation track; when a lockfile exists, use only its package manager — do not mix npm/pnpm/bun, and do not rewrite a registry package name to match a GitHub owner.
  2. Produce a change plan: exact target version, commands to run, files that will change, lifecycle scripts that may run, configuration migration, and rollback steps.
  3. Obtain explicit user confirmation before any write or install, even when no breaking change is known.
  4. Make minimal changes in a dedicated branch/worktree; patch configuration by path and preserve unknown fields. For Git sources, fetch and compare an explicit tag or commit first; never git pull a dirty worktree.
  5. Successful dependency installation does not mean DSH has enabled the plugin; verify the target profile's composition actually resolves to the target package, remove old source lines owned by this upgrade if any exist, and confirm the runtime entry is active.
  6. Run "Validation and reporting"; on failure, restore only the paths owned by this task and report residual side effects.

Mode C · author-migrate (migrate a plugin source repository with a DSH upgrade)

  1. Run the baseline first: in the repository's own dependency state (no target pin, no target env) run the mechanical suite (build / typecheck / tests; these run package scripts, so first show the commands to be executed per the safety boundaries and obtain confirmation), and record pre-existing failures as an exemption list (see R-06 in references/rollup-0.1.2.md; later corridors follow the same pattern). The migration must not add or worsen failures; pre-existing failures are exempted per the baseline.
  2. Confirm exact from/to tags; connect version corridors by the from → to metadata in references/README.md — never by filename lexicographic order. If the source is older than the earliest card, mark that segment as an unsupported gap and derive it from exact-tag source, packed declarations, and reproducible tests; do not pretend a later card covers it.
  3. Read the full corridor first and compute the final net state. When a field is removed in an intermediate version and restored in the target, do not delete and re-add it.
  4. Scan the seven touchpoint classes per pre-flight.md: source patches, events, services/Remote, host filesystem, UI/commands/tools, custom channels, subprocess/output. You may first run the read-only migration planner to generate paths/line numbers and candidate cards, but its results remain heuristic; zero hits still require checking dependencies/imports and running build plus a real mount.
  5. Keep only cards that intersect the hit touchpoints and the actual face (Host / Web Client / ordinary plugin). Cards are a curated list, not a complete API diff; when corridor edges or API coordinates are missing, mark them unsupported/pending instead of changing things from memory.
  6. Produce a source-migration plan grouped by Host/Web Client seam, listing hit files, cards, target behavior, and tests; obtain confirmation before implementing in a dedicated branch/worktree. Keep the DSH cohort exact and coherent in package.json and the lockfile; a successful install with mixed old/new peers is not a migration. If a selector or callback unexpectedly becomes any, run one diagnostic typecheck with skipLibCheck: false and declare the packages that own the consumed declarations directly. capability cards are suggestions only — never adopt them automatically.
  7. After compatibility changes pass, choose and apply the plugin's own SemVer bump separately. Verify the packed filename and packed manifest both carry that plugin version; never use the DSH host version as the plugin release version by accident. For the removed dsh-client-runtime, keyed chat snapshots, command execution signature, or Workspace navigation (connectWorkspace / pickDirectory), use the alpha.2 API ledger and DSH-0.1.2-A1-32.

Safety boundaries

  • Show the plan and obtain confirmation before any file write, install, version fetch/switch, or package script run;
  • Never auto-stash/reset/clean/force-update, and never overwrite user or other agents' work;
  • Never expose credentials; diagnostics may report only whether something is configured and non-sensitive versions/sources;
  • Do not retry unknown gateway/internal or other failures by default; retry only when the error is retryable, the operation is idempotent, and policy allows;
  • When a migration approach cannot be determined with high confidence from primary sources or reproducible behavior, stop automatic changes and mark it "pending review";
  • When local observation conflicts with a primary source, record both, reproduce, and report — do not silently pick one side.

Validation and reporting

Validate at least the applicable layers:

  1. Dependency resolution: the package manager, lockfile, and dependency graph change only as expected; scan the full lockfile for the old DSH cohort and removed packages, not only top-level dependencies;
  2. Enablement resolution: the target profile's composition points to the expected package identity, with no old source or duplicate rows;
  3. Static: build, typecheck, and plugin tests; for the alpha.2 corridor, close out references/precision-checklist.md, keeping type declarations separate from runtime module/service activation and preserving existing channel protocols when applying the Connection auth gate;
  4. Runtime: cold-start a real DSH profile; verify entry activation and that required/provided Cordis services do not remain pending — verify-runtime.mjs runs this layer end-to-end in an isolated profile and reports failure attribution (plugin-code / dependency-resolution / profile-config / dsh-runtime). For a Web Client plugin, exchange the printed token URL for its cookie, read the host boot manifest, request the advertised client artifact, and prove registration/mount rather than accepting a bare HTTP 200;
  5. Behavior: execute one core plugin path; host migrations must complete at least one message → tool → response flow, or an equivalent dedicated flow;
  6. Wrapper: verify exit code, stdout, stderr, cancellation, and teardown.

Structure the report as:

  • pre-existing (Mode C with the baseline run; other modes note "not collected"): the list of failures from the baseline (untouched, not attributed to this migration);
  • Completed: versions, files, cards, and validation;
  • Skipped: non-hits or inapplicable items with evidence;
  • Pending/residual risk: missing sources, untested platforms, lifecycle-script side effects;
  • Rollback: recorded baseline and recoverable paths;
  • Recommendations: optional capabilities and follow-up work migrating to public seams.

References

FilePurpose
references/README.mdVersion corridors, card schema, and maintenance rules
references/pre-flight.mdSeven-class touchpoint self-check and summary template
references/troubleshooting.mdPost-migration symptom → root cause → card lookup
references/v0.1.1-rc.1.mdrc.8→rc.1 draft cards: repository-plugins mechanism removal, dshClient→dsh.client manifest merge, client-modules scan → bundle dsh.client, strict injection + weak ctx.get, session event contract, self-rendering client session aggregation, tasks.peek removal, 0812 service renames (vlln plugin migrations; corridor is the closest published-tag alignment for the internal 0810–0812 snapshot window)
references/v0.1.1-rc.2.mdrc.1→rc.2 reviewed cards (3, DSH-0.1.1-R2)
references/v0.1.2-alpha.1.mdrc.2→alpha.1 curated cards
references/v0.1.2-alpha.2.mdalpha.1→alpha.2 curated cards
references/v0.1.2-alpha.3.mdalpha.2→alpha.3 curated cards (2): optional SQLite Session-persistence provider removed (opt-in databases need an older build to export, DSH-0.1.2-A3-02) and additive settings.plugin.item keyed-slot settings card capability (DSH-0.1.2-A3-01); carries the verification record
references/v0.1.2-alpha.4.mdalpha.3→alpha.4 curated cards (6): report tool package removed in favour of send_message, Python code-runtime package renamed, Session.events replaced by seq/eventAt/snapshotEvents, branded SessionSeq/SessionLogOffset + seedLength→isSeeded, PTC preset drops workflow, base bundle enables web_fetch; carries a three-host verification record
references/v0.1.2-alpha.5.mdalpha.4→alpha.5 curated cards (3): storage domains gain optional compatibleVersions read tolerance and invalidRecords: 'backup-and-skip' salvage; host fix for rc.2/alpha.3-era homes that refused to boot or dropped session titles on alpha.4; carries a storage-layer reproduction record
references/v0.1.2-rc.1.mdalpha.5→rc.1, the first release candidate of the 0.1.2 series (zero cards: pure version bump, no plugin-facing changes; verification record plus a release-notes coverage matrix mapping the rc.1 summary onto the corridor cards, with backfill candidates)
references/v0.1.3-alpha.1.md0.1.2-rc.1→0.1.3-alpha.1 cards (8): A1-01/A1-02 session-log corridor measured on the release-tarball build 0.1.3-alpha.1-9523542 (the v0→v1 session migrator refuses 0.1.2-alpha.x-writer logs — top-level replayState.kind/version: 1, all pre-alpha.4-writer history unloadable, fail-closed with the source artifact untouched; cross-version resume reports cursor behind the last applied entry, tag alignment pending); A1-03 Windows install fails on the fs-ext native build without MSVC; pnpm-patch recipe, single-host field report; A1-04…A1-06 git-tag anchored: outbound HTTP(S)/ALL_PROXY bootstrap install (dsh-http-proxy, $DSH_HOME/.env home layer), session persistence SessionHandle + async agentLoop.create() + per-session lock, Session log format v2 + released migration catalog; A1-07/A1-08 unpublished-cohort source-launch recipe + composer/read_image runtime re-verification
references/v0.1.3-alpha.2.md0.1.3-alpha.1→0.1.3-alpha.2 curated cards (5): persona splits into prefix + suffix (text/persona keys and PERSONA_SECTION removed), SubprocessHandle.pid removed, base bundle drops the tool-str-replace-editor default row, launcher runCli()/import.meta.main gate, pi-ai ^0.84.2→^0.85.1; first 0.1.3 build on npm (alpha.1 items debut for npm upgrades)
references/v0.1.5-alpha.1.md0.1.3-alpha.2→0.1.5-alpha.1 curated cards (20, version-jump edge): Session log format V3 (session-format-v2-to-v3, EpochHeader.system removed, no downgrade read), ctx.agent removal + explicit AgentSetup(agentCtx, agent)/parentAgent, Inbox type interface at agent.inbox, tighter session-event payload validation, PTC vocabulary rename, token-meter export removal + contextBreakdown stateVersion 4, system prompts in message history, forwarded scoped Remote events must carry the Agent, CLI rejects --profile desktop, --from-default-profile/loadProfileDirectory(), workspaceFiles/readByteRange//api/file file surface + file-address helpers, goal/activation-changed + paused-goal resume refusal, fs-ext→node-addon-system packaging, Web Client details→rightbar rework, injection-surface signature changes, right-sidebar/resource extension points, sidebar file opening, tool-subagent scoped-preset requirement, host SSH/directory-picker/instruction-discovery seams; A1-20 (real-host verified): an in-place npm-global upgrade can serve a client combo that omits newly-added bundle modules — one dropped module fails every client plugin's registration, and a host restart self-heals the roster/combo mismatch
references/v0.1.5-alpha.2.md0.1.5-alpha.1→0.1.5-alpha.2 curated cards (24): workspaceFiles drops the Agent first parameter for a Typert workspaceFileScope (client resource type, reload/restat, absolute scope authorization), file reads leave the workspace root with a maxFileBytes cap and readAll/readRelated, the conversation slot moves under root-scoped main with sidebar.panellist, minimal profiles become persistent-shell-only, two non-ignorable session events (deliverables/presented, subagent/catalog), dsh-llm-pi-ai config/type changes, scope-aware tool guidance, present/reveal delivery surface, document previews + ui-sidebar-textpreview→ui-sidebar-documentpreview, new chunked-list/tool-present packages, MCP pagination-cursor rejection, session-format-status doc; client/packaging cards: rightbar root scope + rightbar.session and the layout service/store rewrite (selectPanel, beginNavigation, usePanelInfo), client-resources drops reload, ui-primitives FileTypeIcon/classifyFileType, ui-dockkit contract drift, ui-message-feedback injected surface, ui-workspace openSession/openWorkspace/forkSession, ChatFileMentions.forClosing(owner, sessionId) + deliverables turn tail, browser-only deps → devDependencies, ctx.documentPreviews registry, ActionSpec commands, command-feedback subpaths + sessionFeedback Host Remote, lazy sidebar default pages/close rules; on npm since 2026-09-09
references/v0.1.5-rc.1.md0.1.5-alpha.2→0.1.5-rc.1 curated cards (5): the base bundle's default agent model id moves to deepseek-flash; deepseek-flash (V41 Flash) joins the adapter catalog with image input, systemPromptUpdate: 'in-history' and no gateway probe; document renderers gain a required scrollportRef; sidebar guide entries gain an optional description; negative evidence plus a 17-repository fleet verification record. This edge is 17 commits
references/v0.1.5-rc.2.md0.1.5-rc.1→0.1.5-rc.2 draft cards (6): the feedback surface's injected contract loses toggle/acknowledge, openDialog gains a required rating and MessageFeedbackToggleResult leaves the exports (supersedes the injected half of the alpha.2 feedback card, which is still in an open pull request); both ratings now confirm in the dialog and a failed submission becomes a 6s warning toast; FileTypeIcon's 48 code-category icons move to the injected design-export artwork with per-instance dsh-code-icon-* ids; the completed-turn footer and file-section spacing become a 20/16/20px contract; service-stability is re-labelled in both languages; and the edge carries negative evidence that no Host-plane package changed (272 of its 334 files are version strings). Note: npm latest still resolves to 0.1.5-rc.1 — rc.2 sits on next
references/v0.1.6-alpha.1.md0.1.5-rc.2→0.1.6-alpha.1 draft cards (38, the widest edge carded here: 800 commits / 4015 files). Host: agent/session-start deleted and agent/created becomes serial + awaited, auditStartupEntries replaces the assertEntries* pair, session event reads deprecated, registerMessageProjection() with a refusal when no pure interpreter is registered, session-log-deepseek uploads by default. Runtime: codeRuntime→ptcRuntime with a resolve/run split, async SandboxProvider.confine and ShellExecutor.start, subprocess terminalEnvironment() + optional control channel, workflow-ptc replaces the worker-thread provider, MCP 2.0 SDK, new ctx.mcpResources and ctx.ssh capabilities. LLM: adapters report IMAGE_OFFLOAD_REQUIRED instead of projecting images, deepseek-official defaults to the Anthropic Messages protocol, images move to the v41 token grid, projection stateVersion 5, AssistantProvenance→AssistantProviderMetadata. Web Client: producer/provider renames, required CommandClaim.name, new conversation.input.permission and keyed guide-entry slots, ConnectionIndicator.reconnectLabel removed, context-aware diffs, ?fixture mode replaced by the assembly tier. Composition/packaging: base swaps workflow-worker-thread for ptc-runtime + workflow-ptc, mounts image-offload (required-on-read image/offload) and mcp-resources, disables tool-ralph by default, the Web bundle drops the code-runtime row, a +22/−7 package ledger, headless --session-id/--json, public package manifest rebuild, experimental publication flipped to a denylist, node-addon-require-builtin floor ^0.1.4→^0.1.6; negative evidence that SESSION_FORMAT_VERSION (3), the engine floor and the launcher CLI grammar did not move
references/v0.1.6-alpha.2.md0.1.6-alpha.1→0.1.6-alpha.2 draft cards (4): SessionListState.current is removed with multi-instance Session references — resolve the main Session through ctx.uiSession.adapter.current.getSnapshot() (works on both tags) or the retainedBy.mainView marker; GlobalStandardProps swaps useSessionPendingInteraction for useSessionStatus + useSessionRetainInfo while useSessions stays; the new plugin-manager service manages profile bundles (dsh.profile.bundles + pnpm) and writes row toggles into the profile cordis.patch.yml, with first-hand evidence that link-installed plugins stay outside its bundle management; npm publish lags the GitHub release (E404 window). Read the 0.1.6-alpha.1 cards first
references/v0.1.7-alpha.1.md0.1.6-alpha.2→0.1.7-alpha.1 draft cards (10): the client primitives icon set drops every *16 export for *Medium/*Regular variants (a missing export vanishes the whole slot entry via React #130), workspaceFiles reads unify on readBytes, settings move into the current Profile's plugin configuration with a one-time settings.yaml import, bundle-declared agent presets, session log V4 with a batch migration tool, the official DeepSeek adapter is Messages-API only, ordered multi-patch bundles and no-reload config fields, tolerant Profile loading, locale-aware plugin metadata, and custom-event attachments no longer auto-read. The preceding edge 0.1.6-alpha.1→0.1.6-alpha.2 is carded separately
references/v0.1.7-alpha.2.md0.1.7-alpha.1→0.1.7-alpha.2 draft cards (4): spill-policy maxInlineBytes becomes maxInlineTokens with a shared head/tail token budget, vendored dependency auto-updates pin to same-minor patches, the first plugin install auto-selects the most responsive npm registry, and client bundles are cached at host boot (an install-tree client edit needs a host restart) while Web pages reconnect after a server restart
references/v0.1.7-rc.1.md0.1.7-alpha.2→0.1.7-rc.1 draft cards (5): DSH peer ranges are enforced at install and startup with exact-version exemptions in <profile>/compatibility.json — with the host's semver ^7.8.5 (caret change since 7.8.3) and includePrerelease, ^0.1.7/~0.1.7/>=0.1.7 refuse 0.1.7-rc.1, and --dump-config still lists a denied row; tool.call.toolview owners become a preparing/start/result phase union with argsRaw only on started calls; Conversation Definitions accept transient starts; the work-detail setting gains four modes (default standard); Plugin Manager bounds silent pnpm runs and prechecks GitHub reachability
references/v0.2.0-rc.1.md0.1.7-rc.2→0.2.0-rc.1 draft cards (6): host packages cross to 0.2.0-rc.1, so every ^0.1.x-floored DSH peer is refused and ^0.2.0 does not admit 0.2.0-rc.1 either (use ^0.1.0 || ^0.2.0-rc.1 or ^0.2.0-rc.1); Web work-details default detailed with an optional transcriptView; Schedule rows move to @deepseek-ai/dsh-experimental-schedule-bundle; telemetry rows join the bundle composition; fork gains onCreated; Explorer path-opening spawns visible. The preceding 0.1.7-rc.1→0.1.7-rc.2 edge is not yet carded (corridor gap)
references/v0.2.0-rc.2.md0.2.0-rc.1→0.2.0-rc.2 draft cards (3): Desktop runner surface, first-hand on a real Desktop 0.2.0-rc.2 install — the Electron shell forwards renderer requests through dsh-app://app after deleting host/origin/cookie/sec-fetch-site and rewrites the WS origin, so plugin fences requiring an affirmative browser marker 403 every route (realign with the platform fence trust semantics); the two former field notes are folded in as cards (Desktop ctx.sessions registry empty — upstream discussion linked; minimal subprocess PATH on Windows); unattributed field note: readSession seeded-session replay validation
references/v0.2.1-alpha.1.md0.2.0-rc.2→0.2.1-alpha.1 draft cards (8): runtime invariant plugins and ./invariant exports removed, composer stats split into activity/usage, subpath plugins export display text and icons, Schedule in the default Web composition, owner-tracked style injection, installs report the actual version, dependency-mapping lifecycle, HMR manifest refresh
references/v0.2.1-alpha.2.md0.2.1-alpha.1→0.2.1-alpha.2 draft cards (11): tool presentation both mode removed, managed subagent activations, Agent Team direct inbox delivery, dshHome key removed, Python PTC needs sandbox/sandboxPolicy, {{cwd}} prompt variable removed, the Web profile drops webRuntime for webStartup, and more
references/v0.2.1-alpha.3.md0.2.1-alpha.2→0.2.1-alpha.3 draft cards (5): Azure provider renamed azure, API-key priority splits by surface, plugin updates hot-apply, --from-default-profile replaces an existing config wholesale
references/v0.2.1-alpha.4.md0.2.1-alpha.3→0.2.1-alpha.4 draft cards (3): compatibility prefers engines.dsh (evaluated with includePrerelease), custom plugin index sources
references/v0.2.1-alpha.5.md0.2.1-alpha.4→0.2.1-alpha.5 draft cards (2): new single-owner conversation.input.model.label slot, /-menu refresh on plugin toggles and other fixes
references/jump-0.2.0-rc.2-to-0.2.1-alpha.5.md0.2.0-rc.2⇒0.2.1-alpha.5 jump cards (20): not a corridor edge, but a merged net-change view for a deployment jumping from 0.2.0-rc.2 straight to 0.2.1-alpha.5 (~1900 commits): engines.dsh first with peers→requirements, invariants retired, webRuntime→webStartup, {{cwd}} removed, the subagent delegation rework, the config-key removal band, client API removals, protocol-peer breakages, a Windows fleet-mechanics card; the per-edge cards are A1–A5
references/v0.2.1-rc.1.md0.2.1-alpha.5→0.2.1-rc.1 draft cards (3): dependency sync across the plugin lifecycle, five experimental plugin seats, capability round-up
references/v0.2.1-rc.3.md0.2.1-rc.1→0.2.1-rc.3 draft cards (3): rc.2 + rc.3 as one edge: V4.1-Flash-1017 adapter and opt-in DeepSeek Search/Fetch, plugin discovery menus, New Session reuses blank Sessions again (reverses DSH-0.2.1-A2-07)
references/v0.2.1-rc.4.md0.2.1-rc.3→0.2.1-rc.4 draft cards (1): synchronization release: byte-identical CLI lib/, only an ACP stdout diagnostics fix
references/v0.2.1-rc.5.md0.2.1-rc.4→0.2.1-rc.5 draft cards (1): conversation.chat.reasoning.body text becomes display-ready text, raw output moves to a new rawText
references/v0.2.2-alpha.2.md0.2.1-rc.4→0.2.2-alpha.2 draft cards (3): start of the 0.2.2 line (diverges from rc.5): Plugin Manager third-party updates, Web Client mobile overhaul, six-plugin contract sweep; 34 upstream upgrade guides not yet carded (incl. breaking ones such as the Node.js 24.9 floor), listed at the end of the file
references/jump-0.2.1-alpha.5-to-0.2.2-alpha.2.md0.2.1-alpha.5⇒0.2.2-alpha.2 jump cards (6): not a corridor edge, but a merged view for a deployment jumping from 0.2.1-alpha.5 straight to 0.2.2-alpha.2: the compatibility-ledger gate, the dependency-aware plugin lifecycle, model and web surfaces, README detail pages, the new Web Client, the fleet verification record; shares the per-edge file's gap of 34 uncarded upstream guides
references/jump-0.1.5-rc.2-to-0.1.7-rc.1.md0.1.5-rc.2→0.1.7-rc.1 version-jump curated cards (34, DSH-0.1.7-J1): host/runtime plane — DSH peer-compatibility enforcement at install and startup with exact-version exemptions, PTC runtime rename (codeRuntime→ptcRuntime, Node engine in a separate process), declarative agent presets (dsh-agent-presets split), settings into the profile plugin Config (settings.register removed), Session log V4 + session-format-v3-to-v4 + attachment-carrier narrowing, Remote duplex/binary + readBytes, async Agent lifecycle (agent/session-start removed, agent/created gains source), the Message role union + createSystemMessage(text), Messages-only DeepSeek adapter (/anthropic), subagent Config/depth, E2B removal + POSIX SSH providers, Ralph off, token-budgeted spill-policy, read-only tool-cordis, bundle ordered patch lists, the package-rename ledger, new CLI/headless surfaces, Agent Team single bundle, experimental speech/browser/computer-use, bundled LibreOffice + packaged-app Node requirement, MCP resources, session-log privacy default; Web Client plane — toolview preparing phase, chat-node/turnTail reshape, presentation-policy channel, *16→*Regular/*Medium icon renames, settingsScope→configForms, right-sidebar tab contract, new sidebar packages, component factories, plugin-manager page + pluginManager Remote, ModelDirectory.select results, ui-cordis @pluginId removal, session-row action slots, and two new settings-page seats (settings.launcher, settings.models.sign-in). The per-edge 0.1.6/0.1.7 card files cover the same window edge by edge; this file is the jump view, not a corridor edge, and is not read by plan-migration.mjs
references/api-migration-0.1.2-alpha.2.mdExact rc.2→alpha.2 interface ledger; read when API, Remote, Settings, events, Headless, packaging, or composition surfaces are hit; includes the removed client runtime and keyed chat snapshots (API-10)
references/rollup-0.1.2.md0.1.1 → 0.1.2 corridor (rollup): cross-cohort coexistence, unpublished-cohort installation, RemoteResult error flow, pre-migration baseline attribution, bounded retry for boot race, base-only preset precondition, type-surface export drift, host-self safety boundary, install-channel pitfalls (mirror lag, pnpm 11 supply-chain rules, peer-floor prerelease semantics), and the layered validation checklist; based on rc.1 and subject to final-release review
references/precision-checklist.mdAlpha.2 static-migration precision checklist: peer floors, runtime module composition versus type declarations, locale pairing, channel authentication with protocol preservation, landing discipline and citations; pair with scripts/inject-lint.mjs for residue/peer checks and manual route-review candidates
scripts/README.mdExecutable helper scripts: plan-migration (read-only migration planner), verify-runtime (offline runtime contract checker), and ghost-host-check (ghost-host classifier for pre-flight step 1.5)
examples/legacy-plugin/Static fixture for the seven touchpoint classes (never execute)
examples/08-real-web-client-alpha2-migration.mdReal Host + Web Client source migration from an older unsupported corridor segment

Normative background: dsh-community-standard owns manifests, contract coordinates, and negotiation conventions; this skill handles practical upgrades of existing plugins, reusing that classification without redefining it. The official call for contributions is deepseek-harness discussion #5120.

Coordinate the DSH Plugin Lifecycle

Act as the workflow controller. Let the user choose outcomes and optional proof before execution, route each selected stage to its owning Skill, preserve one phase ledger, and return one evidence-backed report. Do not copy the detailed rules of an owning Skill into this Skill.

Show the pre-run menu first

When the user has not explicitly selected a workflow, present the workflow and capability tables below before running any phase. Match the user's language, mark health-check as the recommended first-run choice, and wait for a selection. A recommendation is not a selection: do not silently default to health-check, start discovery, or execute a capability.

Accept a workflow number, workflow ID, or unambiguous natural-language outcome. Let the user add or remove capabilities in the same reply, for example 3 + docker-smoke + browser-check. Briefly identify which selected capabilities are read-only and which will later cross a confirmation boundary.

The bundled planner renders the same deterministic menu and remains read-only:

node <plugin-workflow-skill>/scripts/plan-workflow.mjs
# Equivalent explicit form:
node <plugin-workflow-skill>/scripts/plan-workflow.mjs --menu

If the user already selected an outcome and supplied enough context, preserve that choice and continue without showing the menu again.

Continue with read-only discovery

Inspect only enough context to make the choices concrete:

  1. Read repository instructions and inspect Git status without changing it.
  2. Identify whether the target is the DSH monorepo, an external plugin source repository, an installed plugin, or a packed artifact.
  3. Record the plugin source identity, current DSH version, requested target version, package manager, available scripts, plugin surfaces, and existing naming declaration.
  4. Mark missing inputs as unknown. Do not install dependencies, run package scripts, start containers, edit files, or query a remote registry during discovery.

Choose one workflow

WorkflowOutcomeDefault stages
health-checkRead-only plugin and upgrade-risk reportdiscovery, optional DSH audit, seven-touchpoint scan
upgrade-targetUpgrade an installed plugin to an explicit versiondiscovery, upgrade, static checks, rollback record
compatibility-migrationAdapt plugin source to an exact DSH targetdiscovery, DSH audit, seven-touchpoint migration, static and runtime tests
test-onlyValidate an existing source tree or artifactdiscovery, selected test levels, report
naming-registryValidate identifiers and check reviewed cloud registrations; optionally register an IDdiscovery, offline naming, registry query; optional registration
package-releasePrepare and optionally publish a releasediscovery, required test gates, pack, consumer smoke, optional publication
full-lifecycleMigrate, validate, name, package, and optionally publishall applicable stages in dependency order
runtime-debugDiagnose and fix Web Client runtime behaviorruntime diagnosis/fix, static, functional and browser proof, rollback
heavy-dependencyIntegrate a lazy-loaded Web Client dependencyintegration, static, functional and browser proof, rollback, package inspection
fleet-sweepSweep the whole installed plugin fleet against an upgraded hoststatic and live fleet sweep, per-plugin fix and release loop

runtime-debug and heavy-dependency require the web-client surface. They can also be added as capabilities to a migration. fleet-sweep has no surface gate because a fleet mixes Web Client and logic-only plugins; it crosses all three confirmation boundaries because it runs the upgraded host and then commits, tags and pushes each fixed plugin. Use health-check for a read-only investigation; a request to diagnose a symptom does not by itself select a fix workflow.

Then let the user include or exclude these capabilities. Recommend the smallest set that proves their stated outcome and state which recommended items are still unselected.

CapabilityChoiceDefault
DSH version compatibility auditdsh-auditOn for compatibility migration; otherwise off
Seven-touchpoint plugin scantouchpoint-scanOn for health checks and migrations
Typecheck, unit tests, and buildstatic-testsOn after source changes and before packaging
Exact-version Docker cold startdocker-smokeOn for migrations and release candidates when Docker is available
One real functional pathfunctional-probeOn for migrations and releases
Browser validationbrowser-checkOn only for Web Client or UI surfaces
Offline naming declaration validationnaming-localOn for naming-registry and new external plugins; otherwise opt-in
Central cloud registry lookupregistry-queryOn for naming-registry; otherwise opt-in and read-only
Central cloud ID registrationregistry-registerOff; local entry preparation writes the registry checkout, and PR submission is external publication
Rollback rehearsal or reciperollbackRecipe on for every write workflow; rehearsal is opt-in
Build and inspect a package artifactpackage-artifactOn for package/release and full lifecycle workflows
Publish an artifact or releasereleaseOff unless external release intent is explicit
Diagnose and fix Web Client runtime behaviorruntime-debugOff unless selected; requires static, functional and browser proof plus rollback
Integrate a heavy browser dependencyheavy-dependencyOff unless selected; requires the same proof plus package inspection
Sweep the installed plugin fleet after a host upgradefleet-sweepOff unless selected; requires repository-write, runtime and external-publication confirmation

After the user chooses, normalize the selection with the bundled read-only planner. Read references/workflow-selection.schema.json when another tool needs to produce the input JSON.

node <plugin-workflow-skill>/scripts/plan-workflow.mjs \
  --workflow compatibility-migration \
  --include registry-query \
  --exclude browser-check \
  --surface ordinary-plugin

Use --format json for automation, or --selection <selection.json> for a persisted input that follows the schema. Calling the planner without a selection prints the menu instead of creating a default plan. The planner validates conflicts and required dependencies, emits deterministic phase IDs and confirmation boundaries, and never executes the selected phases. Treat its output as the initial ledger, not as user approval.

The naming-registry defaults stop after the read-only registry-query; registry-register is never implied and retains separate repository-write and external-publication boundaries. A user may explicitly exclude registry-query for an offline-only run. Do not treat a query as a reservation or registration as required for local plugin use. A local plugin and the central registry may share a display name; only concrete identifiers on the same runtime surface can conflict, and the naming owner must report those exact matches plus the index SHA-256 when the query completes.

Build the phase ledger

Create one row per selected or dependency-required stage before execution:

PhaseCapabilityOwnerStatusEvidence or blocker
P01discoveryplugin-workflowselectedtarget and source identity

Use only these status values:

  • selected: chosen and not yet completed;
  • completed: finished with evidence;
  • blocked: attempted or required but unable to proceed;
  • skipped: applicable but deliberately not run;
  • not_applicable: irrelevant to the detected plugin surface or workflow.

Never turn an unavailable or unselected check into completed. When a phase is blocked, mark dependent phases blocked or skipped with the dependency reason and continue only with independent, authorized phases.

Route each stage to its owner

Before executing a stage, load and follow its owning Skill. If the owner is unavailable, mark the phase blocked; do not recreate its implementation from memory.

StageOwning SkillBoundary
Installed update or source compatibility migration$plugin-upgradeInspect first; check authorization for config, dependency, or source changes
New plugin code, offline naming, or registry query$plugin-writeFollow the exact target Harness and registry contracts
Static, runtime, Docker, functional, or browser validation$plugin-testSelect the minimum sufficient levels and preserve evidence
Package, release gates, publication, and release rollback$plugin-releaseCheck the publication destination and authorization
DSH host version-to-version evidence$dsh-upgrade-auditKeep generated evidence separate from plugin source changes
Web Client runtime diagnosis and repair$plugin-runtime-debugEstablish the exact host contract and reproduce the failing interaction
Lazy-loaded browser dependency integration$plugin-heavy-depOwn chunk loading, host route, fallback and markup handling
Whole-fleet sweep and per-plugin release loop after a host upgrade$plugin-fleet-sweepVerify on the upgraded host; fix and release one plugin at a time, never as a fleet commit

Keep one owner per phase. When runtime debugging and dependency integration overlap, record the diagnosed contract and let the integration owner consume it instead of starting a competing rewrite. Reuse the selected target version and source identity across owners. If a later owner changes source, dependencies or the package artifact, invalidate the earlier verification that depended on those inputs and rerun it.

Run stages in dependency order:

  1. discovery and source identity;
  2. DSH audit when selected;
  3. upgrade or implementation changes, then selected runtime repair or dependency integration;
  4. offline naming and the selected registry query (default for naming-registry);
  5. static tests;
  6. Docker, functional, and browser proof;
  7. release preparation and artifact inspection;
  8. external registration or publication.

Skip stages that are not selected unless an owning Skill makes them a hard gate for a later selected stage. In that case, add the gate to the ledger, explain why it is required, and obtain any needed confirmation before running it.

Preserve authorization across three boundaries

Group planned actions by boundary and check each against the user's request and higher-priority instructions. Existing explicit authorization applies to the same scope when handing off to another Skill; do not ask again merely because the owner changed. A generated plan grants no authorization, and authorization for source edits does not implicitly authorize publication. Ask only when a required action is outside the authorization already supplied.

  1. Repository writes: show exact files, intended changes, and rollback scope before editing source, configuration, manifests, or lockfiles.
  2. Dependency and runtime execution: show package-manager commands, lifecycle-script risk, containers, services, browsers, credentials, and expected generated outputs before installs or nontrivial runtime tests. Ordinary read-only Git and file inspection does not need confirmation.
  3. External publication: identify the exact destination and payload for commits, tags, registry PRs, npm artifacts, or hub/collection changes, and confirm that this action is within the user's authorization.

If a selected phase crosses more than one boundary, check each boundary when it becomes actionable. Never request or expose secrets merely to complete a phase.

Maintain and report evidence

Update the ledger after every phase, including failures and explicit skips. Keep exact versions, source SHAs, commands, exit codes, report paths, and uncovered boundaries. Before finishing, verify that every selected capability has a terminal status.

Return one report containing:

  1. workflow and capability selection;
  2. source and target identities;
  3. final phase ledger;
  4. changes made and commits created;
  5. test and registry evidence;
  6. blocked, skipped, and unverified boundaries;
  7. rollback instructions limited to paths owned by this workflow;
  8. publication state, clearly distinguishing local validation, no reviewed registry match, reviewed registration, and released artifacts.

Do not summarize a partial cold start as functional compatibility, a registry no-match as a reserved ID, or a prepared artifact as published.

Write DeepSeek Harness Plugins

Create a plugin package. First classify the repository mode and plugin form, then read the matching reference files, and finally validate the published entry with the smallest set of gates that covers the change.

Select the Repository Mode First

TargetRules to apply
A package inside the official deepseek-harness monorepoUse the in-repository package, tsconfig, documentation, and root-gate rules below.
An externally installable DSH pluginPreserve that repository's package layout and scripts. Use only packages and exports published by the exact target DSH version. Do not copy private, workspace versions, root tsconfig registration, or monorepo-only README gates.
An existing plugin being adapted to a new DSH hostRead references/version-adaptation.md, build the complete version corridor, and run the seven-class touchpoint preflight. If a change is breaking and the user has not yet authorized implementation, present the migration plan and wait for confirmation. After authorization, complete the version adaptation before using this Skill's form references. Form examples must never override target source, type declarations, or release notes.

Derive Cordis, Schemastery, and DSH package names and version ranges from the manifest of the exact target version. Current examples use scoped @deepseek-ai/* identifiers. Older targets may differ and must follow their own published contracts.

For every new external plugin, read references/naming-conventions.md before choosing public identifiers. Create dsh-plugin.naming.json at the plugin repository root and run the bundled read-only validator before final package validation. Treat compatibility errors as target-contract failures and prefix warnings as community recommendations; use --strict only when the plugin adopts the collision-resistant profile. This is not an official Harness manifest or a global reservation. For an existing external plugin, report naming deviations but preserve published names unless the user explicitly authorizes a compatibility-breaking rename. Packages inside the official monorepo follow the exact target checkout instead of this external naming profile.

After the offline declaration passes, read references/registry-check.md and run the separate central lookup when public network access is available. Supply the exact target Harness version and preserve the reported index SHA-256 with the source URL as evidence. Treat a completed no-match result only as “no reviewed match”; treat timeout, malformed data, unsupported contract, oversized input, or network failure as “unknown/not checked.” Never let the online lookup modify the local manifest, automatically rename a published surface, or turn an automated discovery candidate into a reservation. When central registration is explicitly selected, prepare the full v2 entry and run the central repository's check and verify-source commands before copying it into registry/entries. Validation does not authorize submitting a PR; a formal reservation exists only after a source-backed entry is reviewed and merged in the central registry.

Then Classify the Plugin Form

Required capabilityFormReference
Model-callable tools for reading files, running commands, or searching the WebTool pluginreferences/tool-plugin.md
A new model providerLLM adapter pluginreferences/llm-adapter-plugin.md
Request, tool, or turn interception for permissions, policy, metrics, or telemetryHook pluginreferences/hook-plugin.md
A capability consumed by other plugins through ctxService pluginreferences/service-plugin.md
User-configurable behavior supplied through cordis.ymlConfig pluginreferences/config-plugin.md

A plugin may combine forms freely, such as a configurable tool plugin or a service that also registers tools. Every included form still has to satisfy its own contract. When a requirement does not match one of the five forms above, map it to an existing extension point and write a plugin that registers there. Never modify the Agent loop directly.

GoalMechanism
Add a model-callable capabilityRegister it on ctx.tools
Add a model providerRegister an adapter on ctx.llm
Provide a different capability set for one sessionAssemble it in an Agent preset
Add Shell executionImplement and register a ctx.bash backend
Add persistent terminal executionRegister a ctx.pty backend and load dsh-tool-pty
Add human commandsRegister them on ctx.commands
Add background tasksRegister them on ctx.tasks
Add filesystem access or policyImplement a ctx.fs provider or listen for fs/* policy events
Constrain launched processesUse a ctx.sandbox backend
Intercept requests, tools, or turnsUse agent/* or tools/* events; agent/turn-stopping is the turn-stopping event
Add model-visible contextCall agent.inject()
Add UI or editor integrationDrive ctx.agents and render from session/event
Add Web-client conversation nodesRegister a ConversationNodeDefinition and keyed renderers
Add persistent session stateExtend SessionEventMap, then render and replay from the log
Fork a live sessionCall ctx.sessions.fork(source, boundary?, childSessionId?)
Scope registrations to one AgentUse that Agent's agent.ctx

Package Checklist

  1. Create an in-repository package — Only in the official monorepo, create packages/<group>/<pkg>/ with package.json, tsconfig.json, src/index.ts, and README.md. Copy packages/core/tools/package.json from the target checkout, then adjust its name, description, and dependencies. Preserve target-version invariants: private: true; the root package version; type: module; main: "lib/index.js"; types: "lib/types/index.d.ts"; both types and default in exports["."] pointing to lib; the same target Cordis range in peer and development dependencies; every DSH peer dependency mirrored in development dependencies; the target Schemastery package declared in dependencies; and the target files layout plus package-specific runtime artifacts. CLI application packages must include the built bin. Do not publish undeclared source or stale artifacts. Follow relative-import conventions from the target checkout. Prefer an existing group with the matching role. A new group is only a container, and the package must sit exactly one level below it.

  2. Register an in-repository package — Only in the official monorepo, add the package to the Host or Client aggregate exactly as required by the development guide in the target checkout. A normal package belongs to one aggregate only. Do not copy historical exceptions or file lists without checking the target version. External plugins must never modify Harness root configuration.

  3. Create an external package — Preserve the existing package manager and build system. For a new plugin, apply the external naming policy and include a validated dsh-plugin.naming.json; for an existing plugin, do not silently rename public surfaces. Keep main, types, exports, files, optional bin, packaged-composition or Profile metadata, and the packed tarball consistent. Declare every runtime dependency explicitly and mirror the DSH peer dependencies needed for compilation in development dependencies. Do not make a publishable external plugin private or give it workspace version ranges merely because an in-repository template does so.

  4. Choose the package topology — For a replaceable capability, split service definition, provider, and consumer into separate packages only when they will evolve independently. Keep a single-purpose plugin in one package.

  5. Write the in-repository package README — Only when required by the target monorepo, put package-specific service APIs, configuration, events, extension points, and design notes first. End the README with the canonical "Model Experience" ordering and "Known Limitations" section from the target checkout. Describe each direct, conditional, capped, lifecycle, or auxiliary-model surface in its own H3 with the following three H4 sections, each containing a prose paragraph. Quote stable text owned by the package. For a tool Schema surface, describe only differences not already present in the generated tool catalog. Under "KV Cache Impact," distinguish append-only growth, stable repeated prefixes, replacement of earlier request tokens, and independent model requests. Then list the package changes that invalidate reuse.

    ## Model Experience
    
    ### Request Surface and Activation Conditions
    
    #### What the Model Sees
    
    Name the exact data-dependent field, link to the generated catalog with an anchor, or introduce the verbatim text below.
    
    ##### Place the Verbatim Field Text Here When Needed
    
    ```markdown
    Copy any stable system-prompt body or other long nongenerated literal exactly from source.
    ```
    
    #### Token Impact
    
    State whether the impact is fixed, conditional, retained, replaced, capped, or has zero direct token impact.
    
    #### KV Cache Impact
    
    Describe append-only, prefix-stable, replacement, or independent behavior, including exact conditions that may invalidate reuse.
    
    ## Known Limitations and Deferred Work
    
    - **Consumer-visible gap** — State the exact missing operation or condition, its consequence, and any maintainer constraint.
    
  6. Validate — For a new external plugin, first run node <plugin-write-skill>/scripts/validate-names.mjs --manifest ./dsh-plugin.naming.json; add --strict only for the collision-resistant community profile. After it passes, run node <plugin-write-skill>/scripts/query-registry.mjs --manifest ./dsh-plugin.naming.json --harness-version <exact-semver> when network access is available, and report an unavailable query as unknown rather than available. If proxy variables are present and Node's built-in fetch cannot reach the index, follow references/registry-check.md; do not imply that Node 20-23 automatically honor those variables. Then run the applicable validation block below, focused checks, and coverage gate required by the changed behavior.

Rules While Writing

  • Treat every registration as an effect. Register through ctx helpers or ctx.effect() with a disposer, and make plugin unload clean up every event listener, tool, timer, and other resource.
  • Add new behavior at documented extension points. Do not modify agent-loop.
  • Give public service methods and typed events JSDoc with @param and @returns. Define typed events through declaration merging on the target Cordis Events interface, and document the dispatch mode with @mode.
  • Do not hard-code tunable values. Any value that may differ across deployments must be a validated Config field changeable through cordis.yml.
  • Everything the model sees must be reconstructible from the session log.
  • Fail explicitly on configuration errors. Never silently skip a missing referenced object. Validate at parser, configuration, wiring, and process boundaries instead of trusting an in-process typed caller.

Validation

For packages inside the official Harness monorepo, use current root commands from the target checkout. The names below are examples only; confirm they exist before running them:

pnpm install            # Register the workspace
pnpm run doc-sync
pnpm run constraints && pnpm run typecheck && pnpm run lint
pnpm run build && pnpm run hygiene

For an external plugin, use its own install, typecheck, test, static-check, and build commands. Pack the publishable artifact, inspect its contents, and load it into an isolated Profile running the exact target DSH. For an upgrade, cold-start it and complete one message → tool → reply flow or an equivalent core flow. Report every provider, operating-system, UI, or credential boundary that remains uncovered.

Select tests from the changed surface: unit-test logic; run the repository's coverage gate; run real-API end-to-end tests when provider credentials are available and execution is authorized; use credential-free snapshots for model-, protocol-, or user-visible behavior; and use a real-composition test for user-visible plugins. A package bin entry also needs a built-artifact smoke test under native Node. Complete the minimum sufficient test set under these rules without loading another Skill.

See references/README.md for the reference index.

Sponsors

Details

Marketplace
oh-my-dsh/dsh-plugin-upgrade-skill
Source
oh-my-dsh/dsh-plugin-upgrade-skill
Category
Community
License
MIT
Keywords
deepseek-harness, dsh, plugin, migration, upgrade, breaking-changes