前言¶
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 目錄頁。
