Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

dsh-plugin-adapt

plugin-fast-adapt 的升级适配车道。查 DeepSeek 官方最新版本,取该版本官方 upgrade-guide,扫描插件代码匹配破坏性变更锚点,报出踩了哪几条并给官方修法;seams 查包名或 API 符号在指南与本机宿主里的双源结论;改完秒验并做四维性能架构体检;官方指南覆盖不到的老版本转七阶段迁移 SOP。宿主环境本身有问题(覆盖层残留、悬空软链、插件装了没生效)不走这里,转 dsh-plugin-diagnose。触发词:适配 DSH 插件、升级插件、插件不兼容、dsh 升级后报错、插件用了废弃 API、接缝查询、这个 API 还在不在、扫描窗口、破坏性变更、老版本 DSH 适配、历史走廊迁移、插件性能审计、peer 修补。

taxueseek · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add taxueseek/plugin-fast-adapt --skill dsh-plugin-adapt

About this skill


name: dsh-plugin-adapt description: plugin-fast-adapt 的升级适配车道。查 DeepSeek 官方最新版本,取该版本官方 upgrade-guide,扫描插件代码匹配破坏性变更锚点,报出踩了哪几条并给官方修法;seams 查包名或 API 符号在指南与本机宿主里的双源结论;改完秒验并做四维性能架构体检;官方指南覆盖不到的老版本转七阶段迁移 SOP。宿主环境本身有问题(覆盖层残留、悬空软链、插件装了没生效)不走这里,转 dsh-plugin-diagnose。触发词:适配 DSH 插件、升级插件、插件不兼容、dsh 升级后报错、插件用了废弃 API、接缝查询、这个 API 还在不在、扫描窗口、破坏性变更、老版本 DSH 适配、历史走廊迁移、插件性能审计、peer 修补。

适配升级车道

把「插件适配到新版 DSH」拆成四步,每步一个脚本,每步都能单独跑;另有两个可选步骤补全「修完即验、升级顺带优化」。以下命令都相对工具根目录执行,工具根即本文件真实路径往上两级、含 scripts/ 的那一层。脚本用自身文件的绝对路径定位,不必先 cd,从任何目录直接 node <工具根>/scripts/<脚本>.mjs 同样可行。本目录常以软链别名加载,shell 的 cd ../.. 会按软链走错地方,确实要 cd 时用 cd "$(realpath <本文件所在目录>)/../.."。<插件目录> 指被查插件的仓库根。

环境本身有问题(覆盖层旧包、悬空软链、客户端半死链)先转 ../diagnose/SKILL.md,别在坏环境上做适配判断。

第一步:看清本机环境

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

--brief 只影响输出体积(本机实测 80.5KB → 4.5KB,约省 2.1 万 token):installedPlugins 的 patch 行原文换成计数、进程命令截断到 120 字符。要查具体挂载行时去掉 --brief 拿全量。

本车道只取四段:

  • globalDsh:全局安装的 DSH 版本和位置,后面定目标版本要用
  • target.peerWindows:待查插件自己声明的 peer 版本窗口,决定扫描走廊起点
  • ghostHost:磁盘代码已换新、宿主进程还在跑旧代码时判 stale(进程启动时间早于磁盘变更超过 120 秒)。先重启宿主再做适配判断,否则改完也验不到;ok / no-running-host / unknown 看 reason,不猜
  • falseGreen:tsconfig 的 paths 指向不存在的 checkout(M1)。此时 TypeScript 静默回落到 node_modules 的已发布类型,本地 typecheck 可能全绿而实际类型是旧的;findings 非空先修路径或删 alias,再信 typecheck 结果

overlayFindings、sharedFarmFindings、activation 非空,或 ghostHost.verdict 为 stale,说明环境本身要修,转 ../diagnose/SKILL.md。

第二步:定目标版本

node scripts/guide-sync.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」是倒退。

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

有 target 时取目标版本的官方升级指南:

node scripts/guide-sync.mjs <本机版本> --target <扫描目标> --clone

指南来源按优先级:本机已有 harness clone(只读,自动发现 ~/Documents/*/deepseek-harness 或 DSH_HARNESS_CLONE)→ 默认分支的受管快照(~/.cache/dsh-plugin-fast-adapt/harness-guides-branch/,按 1 小时 TTL 刷新;冷拉约 4.8 秒,刷新约 1 秒)→ 发版 tag 缓存/clone(标 frozen)。tag 是冻结切片,官方会在发版后把同版本指南补全到默认分支,实测 dsh-v0.2.1-rc.3 tag 里 v0.2.1-rc.2 只有 1 条变更,默认分支同一目录 23 条。

--target 必须传扫描窗口终点,不要留空跟官方最新:npm 发版常早于上游打 tag(实测 rc.4 上 npm 23 小时仍无 tag),跟着最新会去拉一个不存在的 tag,整段扫描跳过,而本机明明有覆盖到目标版本的指南。

覆盖度(scan.coverage):coveredUpTo 是本轮指南实际覆盖到的最高版本,complete=false 表示目标版本的变更还没有官方文档。run.mjs 会在屏幕上明说「只覆盖到 X,不能当查干净」;--strict 把它当失败(退出码 2)。指南来自 tag 冻结快照时另标 guides.frozen,提示命中数可能偏低。

取版锚点(2026-10-25 实测复盘):本机已是官方通道最新版时 resolution.target 为 null,旧实现因此拿不到指南语料、run.mjs 的 scan 阶段静默跳过(扫描走廊 (peerFloor, hostVersion] 明明有内容却报「无指南根或无窗口」)。现在取版锚点按 --target || resolution.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 同义,只在没有任何源码根时才退回,否则同一处命中会按两份文件重复报。

接缝查询

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

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

宿主实测的路径解析(scripts/lib/host-scope.mjs,与 code-scan 的宿主核查共用):套件子包的真实位置是宿主主包内部的 node_modules/@deepseek-ai/dsh-*,不是全局 node_modules 的下一级。两个候选作用域都探(主包内部优先,全局 @deepseek-ai 兜住平铺安装形态),checkedWhere 记实际解析到的位置——结论可回溯到磁盘。包名收裸名与 @scope/name 全写两种写法,全写会先剥掉 scope 前缀再拼路径。

一键编排与运行日志

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

按上面四步依次跑环境、定版、指南、扫描、体检、冒烟、typecheck(执行插件自有的 typecheck script,与冒烟同信任级),输出一份统一 JSON 报告;扫描窗口自动取「插件在宿主包上声明的 peer 下限 → 宿主版本」的走廊(--from/--target 可覆盖,倒挂自动回退并留痕)。指南步骤会把窗口终点作为 --target 传给 guide-sync,按分支快照取语料,不再跟官方最新版本走。

typecheck 的两种跳过要分清:工具链缺失(runner 不在 PATH,按 PATH 预检判定)与形态不适用(目标不含 tsconfig.json,安装副本常见——package.json 的 files 白名单不含 tsconfig,tsc -p tsconfig.json 必报 TS5058)。两者都判 skipped 并给补法,都不算构建失败;只有 runner 在 PATH 上且构建确实失败才判 fail(退出码 2)。判据是纯机械的,不匹配错误文本。

scan.coverage 记本轮指南实际覆盖到哪一版(coveredUpTo / complete)。没扫或覆盖不全时屏幕明说「不能当查干净」,不再只打「命中 0 处」;--strict 让这两种未知态退出 2,供 CI 用,默认退出码语义不变。未知开关会直接报错(--no-smoek 这类拼写错误不再静默照跑)。

--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 红、真冷启动失败,或 --strict 下扫描未知。

每次运行写本地日志(`~/

Read the complete source ↗