前言¶
DeepSeek Harness（DSH）把能力都做成插件；宿主一升级，老插件经常直接起不来。常见做法是维护「升级卡片」：按版本区间记录破坏性变更和修法。卡片会滞后于上游大版本跃迁，占满上下文后还会拖累弱模型答题，而每次改完再用真宿主冷启动验证，成本也很高。
下面介绍社区客户端插件 plugin-fast-adapt（维护者 taxueseek）：不维护静态知识库，而是直连 DeepSeek 官方 docs/upgrade-guide/ 与 npm dist-tags，扫描插件代码命中哪些破坏性变更，并给出官方 Migration 修法；同时提供五形态脚手架、环境/启动诊断，以及整机插件集群巡检。项目零 npm 外部依赖（Node 内置模块加本机 git/npm 命令），可作为 Agent Skill 或 DSH 原生插件使用；仓库 MIT 许可，GitHub 约 12 stars。
这是什么¶
plugin-fast-adapt 面向 DSH 插件作者与维护多插件工作区的开发者。README 写明已深度适配 DSH 0.2.2 系列（含 0.2.2-alpha.2），版本探测覆盖自 v0.1.7-rc.2 起的区间。
设计取舍是：破坏性变更的权威描述在官方仓库，格式固定（## Change / ## Migration）；本工具只维护「如何取指南、如何扫代码、如何验证」的流程。默认定版收敛到本机已安装的 DSH 宿主（方案 B，零网络请求）；需要核对上游时再显式加 --check-upstream。
主入口 SKILL.md 只做路由，四条子技能各管一类意图：
| 路径 | 用途 |
|---|---|
sub-skills/adapt/SKILL.md |
定版 → 取指南 → 扫描 → 接缝 → 冒烟 → 体检 |
sub-skills/build/SKILL.md |
scaffold.mjs 五形态插件 + write-gate.mjs |
sub-skills/diagnose/SKILL.md |
env-doctor、log-doctor、env-heal |
sub-skills/review/SKILL.md |
P0–P3 分级审查与子 Agent 委派 |
scripts/ 为共用工具箱；references/ 存放降噪规则、迁移 SOP 等。可选把 build / diagnose / review 子目录软链到 ~/.agents/skills/，让独立触发词不必挤进主技能 1024 字符的 description 上限。
核心功能¶
以下能力均来自仓库 README 与 package.json（当前包版本 0.3.0，要求 Node >= 22.13）。
升级适配与扫描¶
- 从官方升级指南目录拉取版本窗口内的
guide.md，用code-scan.mjs查插件踩了哪些变更；seams.mjs可对单个包/API 做「指南 × 宿主 node_modules」双源接缝查询。 - 扫描侧做了四层降噪与常量词边界匹配，README 称同一真实插件上误报从 12 处降到 0；虚拟 Release 指南与官方指南去重。
- 未构建的 TypeScript 插件若缺少
lib/index.js等入口会硬拦截；Bundle Resolution Shadow、冷启动SIGTERM（退出码 143）等边界在工具里有专门处理。
验证与诊断¶
- 便宜验证：
quick-smoke.mjs做内存级 Cordis 冒烟（毫秒到秒级）；需要真宿主证据时用run.mjs --real-smoke走干净 profile 真装真启。 - 静默失败判据（只报不替用户下结论）：
ghostHost比对进程启动时间与磁盘变更；falseGreen检测tsconfig的paths指向不存在 checkout。 - 启动故障：
log-doctor.mjs针对 StartupError、端口占用、未声明 inject 等；run-log.mjs doctor可交叉核对运行日志与宿主启动日志。 - 覆盖层残留：
env-heal.mjs默认 dry-run，--apply将旧包移到~/.dsh/.trash/<日期>/。
造插件与集群治理¶
scaffold.mjs一条命令生成五形态可运行插件并做真基类装载验证；write-gate.mjs输出「出生证」式体检。fleet-sweep.mjs扫描整机 Web / APP 插件、工作区源码与运行中服务，输出多维生命周期看板；支持--apply-compat批量修补package.json（示例目标版本0.2.2-alpha.2）。
质量与平台¶
- 206 项离线自检（
npm test→self-test.mjs）；CI 在 push/PR 上跑 ubuntu/macOS/Windows。 - 跨 macOS、Linux 标准路径、Termux、容器；支持
DSH_HOST_PATH/DSH_LOCATION与 XDG 缓存规范。
README 明确：冒烟通过不等于宿主完全兼容，相关说明会写在工具输出里。
安装与启用¶
推荐用 skills CLI 装到支持的 agent：
npx skills add taxueseek/plugin-fast-adapt
Claude Code marketplace：
/plugin marketplace add taxueseek/plugin-fast-adapt
/plugin install plugin-fast-adapt
需要命令行入口时（转发到一键编排）：
npx plugin-fast-adapt <插件目录>
Cursor 用户可将仓库中 skill 文件复制到 .cursor/skills/plugin-fast-adapt/（README 手动安装一节说明以 SKILL.md 所在目录接入 agent）。安装前请自行阅读源码与 MIT 许可证；插件在与当前 DSH 进程相同的权限下运行。
典型用法¶
单插件全流程（推荐）¶
run.mjs 串起环境、定版、指南、扫描、构建核验、体检、冒烟与 typecheck，并写本地运行日志：
node scripts/run.mjs <插件目录>
node scripts/run.mjs <插件目录> --check-upstream
node scripts/run.mjs <插件目录> --real-smoke
node scripts/run.mjs <插件目录> --offline
node scripts/run.mjs <插件目录> --strict
回看与诊断：
node scripts/run-log.mjs list
node scripts/run-log.mjs doctor
node scripts/run-log.mjs sanitize --latest --out share.json
npm run release-check
集群巡检¶
node scripts/fleet-sweep.mjs
node scripts/fleet-sweep.mjs --running
node scripts/fleet-sweep.mjs --target 0.2.2-alpha.2 --apply-compat
分步执行（与 run.mjs 同源脚本）¶
先看本机 DSH 版本、插件就绪度与 ghostHost/falseGreen：
node scripts/env-doctor.mjs <插件目录> --brief
定版并拉指南后扫描：
node scripts/guide-sync.mjs <本机版本> --target <扫描目标> --clone
node scripts/code-scan.mjs <插件目录> <upgrade-guide 目录> <本机版本> <目标版本>
秒验与升级顺带体检：
node scripts/quick-smoke.mjs <插件目录>
node scripts/plugin-audit.mjs <插件目录>
node scripts/log-doctor.mjs --pattern '^startup-' --limit 5
更细的 SOP 见仓库 references/user-guide.md。
适用场景与注意¶
适合：宿主升级到 0.2.x 前后需要对照官方破坏性变更改插件；维护多个 DSH 插件或整机多安装源；希望用脚手架快速产出可装载的五形态插件；启动失败或「本地全绿但 paths 指错目录」类环境问题。
注意：
- 工具依赖本机已安装的 DSH 与可选的
git/npm；默认不联网定版，与上游不一致时需--check-upstream或guide-sync.mjs --check。 --strict适合 CI：扫描未跑或指南未覆盖目标版本时退出码 2。- 社区目录 skillhub.cn 插件页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系；星标与版本以仓库当时状态为准。
结尾¶
plugin-fast-adapt 把 DSH 升级适配从「维护过期卡片」改成「按官方源取指南 + 可复现扫描与分层验证」，并补上脚手架、诊断与集群看板。需要进一步了解实现与命令全集，可直接打开 GitHub：taxueseek/plugin-fast-adapt 与上述 skillhub 目录页。
