前言¶
DeepSeek Harness（DSH）从 v0.1.7-rc.1 起会在插件安装和启动时检查版本兼容性；v0.2.1-alpha.4 起明确第三方插件的版本兼容性优先按 engines.dsh 判断。实际机器上的社区插件里，很多既没有声明 engines.dsh，也没有 @deepseek-ai/dsh* 的 peerDependencies——DSH 不会因此拒绝安装，升级后也难判断谁还在用已改名或弃用的 API。
dsh-adaptive（目录名 dingchenhui0618-arch/dsh-adaptive，中文标题「版本自适应」）是维护者 dingchenhui0618-arch 发布的只读诊断插件，分类为 admin-security。它读取当前 DSH 运行时版本，用与 DSH 一致的规则扫描当前 Profile 里已装插件的兼容性，并对源码做启发式扫描，标出仍可能命中 v0.1.6 到 v0.2.1 区间破坏性变更的位置。不联网、不修改其他插件状态。
这是什么¶
一句话：版本自适应插件——自检运行时、复刻 DSH 兼容判定、给出迁移提示，面板与 HTTP/agent 工具只读输出。
维护者：dingchenhui0618-arch。仓库：https://github.com/dingchenhui0618-arch/dsh-adaptive。社区目录页：https://www.skillhub.cn/plugins/dingchenhui0618-arch/dsh-adaptive。许可证 MIT；package.json 版本 0.2.0，engines.dsh 为 >=0.2.1-rc.2 <0.3.0（README 写明仅在本机 0.2.1-rc.2 上实测）。
核心功能¶
下面按 README 归纳的四块能力说明；判定逻辑来源为 DSH packages/boot/app-boot/src/plugin-compatibility.ts，本插件复刻而非直接调用内部函数。
识别运行时版本¶
优先从 pluginManager.listBundles() 里 installation 来源的 @deepseek-ai/dsh-base 版本读取；读不到则解析 @deepseek-ai/dsh-app-boot/package.json（与 DSH 的 getDshRuntimeVersion() 一致）。
定位 Profile¶
宿主进程不一定带有 shell 注入的 DSH_PROFILE_DIR。按可信度依次尝试：插件配置 profileDir → 环境变量 DSH_PROFILE_DIR → profileContext.packageManager.env → $DSH_HOME/profiles/* 中已安装本插件的目录。多个候选时取 cordis.patch.yml 最近修改的一个，并在面板与报告中注明来源。
兼容矩阵¶
逐个读取 Profile package.json 依赖，解析真实包目录（link: 落到真实路径），给出状态之一：兼容 / 不兼容 / 已授权例外 / 未声明版本约束 / 清单无法判定 / 读不到。
规则要点（与 DSH 一致）：
- 清单有
engines.dsh时由它单独决定，peerDependencies 被忽略； - 否则检查每一个
@deepseek-ai/dsh/@deepseek-ai/dsh-*的 peer 范围，全部满足才算兼容； - peer 为
workspace:^/workspace:~/workspace:*时视为当前运行时版本； - 预发布版本参与比较（
includePrerelease）； - 例外按
pluginManager.listVersionExemptions()的name@version→ 允许运行时列表匹配； engines.dsh为空串判为不满足；畸形清单在 DSH 会抛错，本插件降级为「清单无法判定」并说明原因。
迁移提示¶
对插件包源码做启发式静态扫描，对照内置的 release notes 规则表（v0.1.6-alpha.1 → v0.2.1-rc.2 破坏性变更快照），输出 文件:行号 与建议。命中只表示源码中出现相关符号，不等于一定运行时失败；未命中也不保证无风险。扫描跳过 node_modules、test、dist 等目录，扩展名限于 .js/.mjs/.cjs/.ts/.tsx/.jsx/.yml/.yaml。
规则示例（完整表见仓库 README）：
| id | 自版本起 | 检测的旧接口 |
|---|---|---|
agent-session-start |
0.1.6-alpha.1 | 'agent/session-start'（改为 agent/created） |
session-sync-history |
0.1.6-alpha.1 | .snapshotEvents(、.eventAt(、.ownEvents( |
settings-yaml |
0.1.7-alpha.1 | settings.yaml |
workspace-read-text |
0.1.7-alpha.1 | .readText(（改为 readBytes） |
界面与入口¶
会话视图右侧标签页「版本自适应」（conversation.view，order 55）。面板展示运行时版本与来源、Profile、依赖总数与各状态计数、可展开的逐插件表格（版本约束、未满足项、迁移提示、link: 本地插件的「适配到当前版本」派发入口）、版本内容折叠区；右上角支持「重新扫描」与「复制 Markdown」。README 中的实机截图基于 desktop Profile、运行时 0.2.1-rc.2、18 个依赖。
安装与启用¶
官方 README 的安装方式是让 DSH 把本地目录当作 bundle 安装，不要手改 Profile 的 package.json / cordis.patch.yml：
# 在 DSH 里：插件管理页 → 安装 → 选择本地目录 D:\Projects\dsh-adaptive
安装后插件管理页显示中文标题「版本自适应」与描述。本插件以当前 DSH 进程权限运行；安装前请自行审阅仓库源码与 MIT 许可证。
典型用法¶
面板操作¶
打开「版本自适应」标签页查看扫描结果；需要强制重扫时使用面板上的「重新扫描」。
HTTP（面板内部同样使用）¶
GET /dsh-adaptive/state
GET /dsh-adaptive/state?refresh=1
POST /dsh-adaptive/scan
GET /dsh-adaptive/report.md
?refresh=1 表示强制重新扫描。
Agent 工具¶
工具名 adaptive_report，参数包括 refresh、format: json|markdown、includeHints；format=markdown 时附带完整 Markdown 报告。
派发「适配到当前版本」¶
面板只做诊断，不改代码。点行尾「适配到当前版本」会把任务投进该插件自己的会话（由那边 agent 改代码、测、提交），不新建会话、也不在当前对话里改。
GET /dsh-adaptive/sessions?dir=<插件目录>&name=<包名>
POST /dsh-adaptive/dispatch?name=<包名>[&session=<会话 id>]
找会话顺序：工作目录等于插件仓库 → 会话标题匹配包名 → 上级工作目录；无精确匹配时列出候选（ECHOOSE），选择可记在浏览器 localStorage。任务经宿主 sessionController.prompt（mode: 'queue'）投入目标会话 inbox。
适用场景与注意¶
适合：本地 Profile 里混装大量第三方或 link: 自研插件、准备升级 DSH 或核对 engines.dsh / peer 声明、需要按文件行号排查旧 API 的维护者。
务必注意：
- 只读：本插件不安装、不卸载、不改插件状态、不写文件；派发仅投递消息，改动发生在目标会话及其 agent 权限下。
- 不联网：版本内容为内置快照，DSH 发新版后需更新插件内的快照。
- 启发式迁移提示不能替代阅读官方 release notes。
- 兼容判定是复刻；DSH 改判据时本插件需同步维护。
0.2.1-rc.2起使用ctx.inject等待webServer/tools就绪再注册，避免面板与工具静默消失；面板页脚可查看self.toolRegistered与self.registration。
开发自测（仓库内）：
cd D:\Projects\dsh-adaptive
node --test test/*.test.mjs
结尾¶
dsh-adaptive 把「谁声明了什么、运行时是否满足、是否仍像旧版 API」摊在面板和报告里，便于升级 DSH 前做只读盘点；需要动手改某个插件时，用「适配到当前版本」把任务交给该插件自己的会话即可。
- 社区目录：https://www.skillhub.cn/plugins/dingchenhui0618-arch/dsh-adaptive
- GitHub：https://github.com/dingchenhui0618-arch/dsh-adaptive
SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系；插件生态遵循 DSH「一切皆插件」的思路，具体能力以仓库 README 与源码为准。
