@whyshu/argent-erp 0.3.0 → 0.3.1

package/README.md

@@ -1,4 +1,4 @@
-# @whyshu/argent-erp（v0.3.0）
+# @whyshu/argent-erp（v0.3.1）
 
 **两件东西，一个货**：
 
@@ -126,7 +126,7 @@ ERP 网页里那个「办公室聊一聊」**保持原样**（服务端 SSE +
 
 | 路径 | 作用 |
 |---|---|
-| `/api/argent-erp/health` | 存活 + 版本 + `erpTools`（ERP 工具数；0=缺 @whyshu/argent）+ `officePreset` + `clientPingAt`（bundle 加载）/ `viewPingAt`（面板打开/渲染）|
+| `/api/argent-erp/health` | 存活 + 版本 + `dsh`（识别到的宿主版本）+ `supportedDshRange` + `erpTools`（ERP 工具数；0=缺 @whyshu/argent）+ `officePreset` + `clientPingAt`（bundle 加载）/ `viewPingAt`（面板打开/渲染）|
 | `/api/argent-erp/whoami` | 账号 + 租户列表 + 默认租户 |
 | `/api/argent-erp/overview?tenant=` | 办公室现场（KPI/在岗/执行机/待办 20/动态 10，脱敏） |
 | `/api/argent-erp/timeline?tenant=&days=` | 时间线（`/sku-flows`，按天分组） |
@@ -182,6 +182,24 @@ node plugins/argent/test/office-preset-default.test.mjs   # 机器执行器 pres
 - 宿主侧改动**需要用户手动重启 dsh**（⛔ agent 不重启）；客户端 bundle 改动只需浏览器硬刷新。
 - 回滚：`plugin_manager remove_bundle @whyshu/argent-erp` 后重启（视图与办公室 preset 一起下线）。
 
+## 7.1 dsh 版本门禁（双层，0.3.1 起）
+
+- **第一层（宿主侧，首选）**：`package.json#engines.dsh = ">=0.2.0-0 <0.3.0-0"`。
+  dsh 0.2.x 在**导入插件代码之前**按 manifest 判兼容：不匹配的 bundle 被 skip、entry 被 disable，
+  只打一行原因、**不阻断 boot**（语义与 `@whyshu/argent` 同一套：下界 `-0` 让 rc 预发布算进来，
+  上界 `-0` 把 0.3.0 的所有预发布都挡在外面）。
+- **第二层（插件侧兜底）**：`src/index.js` 的 `apply()` 顶部自查版本（`src/vendor/compat.mjs` 与
+  `plugins/argent/src/compat.mjs` 逐字节同源，由 `scripts/tests/argent-erp-compat-guard.test.mjs` 守着）：
+  - 版本不支持 ⇒ 打一行 `[@whyshu/argent-erp] 插件已自我禁用（dsh x.y.z 未适配）` 后 **return**：
+    **零宿主调用、不抛**；dsh 照常启动，升级到适配版本后自动恢复；
+  - 支持版本 ⇒ 用 `ctx.inject(['webServer'], …)` 等宿主服务就绪再注册端点（**不声明 `inject`**：
+    否则在缺该服务的宿主上会永远 pending，连"自我禁用"日志都打不出来）；
+  - 所有宿主调用（`ctx.inject` / `ctx.webServer.register` / `ctx.effect`）都经 `safeStep()`：
+    缺失或抛错 ⇒ no-op + 同一原因**只告警一次**；`apply` 整体 try/catch，**永不抛**。
+- 自检：`/api/argent-erp/health` 里 `dsh` + `supportedDshRange`；不兼容时端点不存在（插件已自禁）。
+- 注意：`package.json#engines.dsh` 在插件侧检查不可用（老宿主/手工 patch 挂载）；
+  开发机可用 `ARGENT_DSH_VERSION=0.3.0-rc.1` 显式模拟未适配宿主。
+
 ## 8. 已知限制
 
 - 只读：写操作（派单/开票执行/聊天写动作）仍走 ERP web；

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whyshu/argent-erp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Argent ERP 左侧栏入口 + 主视图面板（dsh sidebar.panellist/main）+ 六禾园办公室助理 preset + 办公室聊一聊",
   "keywords": [
@@ -19,7 +19,8 @@
     "directory": "plugins/argent-erp"
   },
   "engines": {
-    "node": ">=24.2.0"
+    "node": ">=24.2.0",
+    "dsh": ">=0.2.0-0 <0.3.0-0"
   },
   "main": "src/index.js",
   "exports": {

package/src/index.js

@@ -1,11 +1,20 @@
 /**
- * argent-erp · 宿主侧插件（v0.2.3）
+ * argent-erp · 宿主侧插件（v0.3.1）
  *
  * 职责只有两件：
  *  1. 注册本地只读端点 `/api/argent-erp/*`（带账号 token 去 whyshu.com，**token 不下发前端**）；
- *  2. 由 bundle 的客户端部分（dist/client.js）在对话顶部注册一个 `conversation.view` tab。
+ *  2. 由 bundle 的客户端部分（dist/client.js）在左侧栏注册「ERP」入口 + 主视图面板。
  *
  * 红线：只读；不重启宿主；不改任何核心配置项；ERP 不可达时**降级为错误卡片**，不阻塞 dsh。
+ *
+ * ## dsh 版本门禁（双层，2026-11-08）
+ *  - 第一层：`package.json#engines.dsh = ">=0.2.0-0 <0.3.0-0"` —— dsh 0.2.x 在**导入插件代码之前**
+ *    就按 manifest 判兼容，不匹配则 skip/disable 并只打一行原因，不阻断 boot；
+ *  - 第二层：本文件 `apply()` 顶部再自查一次（更老宿主 / 手工 patch 挂载 / 已授豁免时宿主不认 manifest）
+ *    ⇒ 不支持就只打一行「插件已自我禁用」后 return，**零宿主 API 调用、不抛**。
+ *
+ * 所有宿主调用（`ctx.inject` / `ctx.webServer.register` / `ctx.effect`）都经 `safeStep()` 包裹：
+ * 缺失或抛错 ⇒ no-op + 同一原因只告警一次。**apply 永不抛出**（入口整体 try/catch）。
  */
 import { readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
@@ -15,8 +24,14 @@ import {
   whoami, overview, shipments, shipmentDetail, caseDetail, timeline, flowDetail, badge,
   chatSessions, chatSession, ErpError,
 } from './data.mjs'
+// ⚠️ 用 src/vendor 的副本（不许相对 import 别的插件）：插件是**可发布产物**，安装到 profile 后
+// 跨包相对路径不存在。漂移由 scripts/tests/argent-erp-compat-guard.test.mjs 逐字节拦截。
+import { SUPPORTED_DSH_RANGE, readDshVersion, evaluateCompatibility } from './vendor/compat.mjs'
 
-/** 每次都读盘：ESM 模块缓存会让"重装后 version 还显示旧值"，健康检查必须反映当前磁盘版本 */
+const NAME = 'argent-erp'
+const LOG_PREFIX = '[@whyshu/argent-erp]'
+
+/** 每次读盘：ESM 模块缓存会让"重装后 version 还显示旧值"，健康检查必须反映当前磁盘版本 */
 function pkgVersion() {
   try {
     return JSON.parse(readFileSync(join(dirname(dirname(fileURLToPath(import.meta.url))), 'package.json'), 'utf8')).version || '0.0.0'
@@ -26,9 +41,42 @@ function pkgVersion() {
 /** apply 时注入的宿主 ctx（只用于健康检查里数 ERP 工具，不缓存业务数据） */
 let HOST_CTX = null
 
+/** apply 成功后拿到的 webServer scope（诊断用；异常路径保持 null） */
+let SERVER_SCOPE = null
+
+/** 已告警过原因的键（同一原因只告警一次，避免宿主契约变化时刷屏） */
+const WARNED = new Set()
+
+/** 同一原因只告警一次；日志本身失败也绝不影响宿主。 */
+function warnOnce(key, message, error) {
+  if (WARNED.has(key)) return
+  WARNED.add(key)
+  try {
+    const detail = error ? `：${String((error && error.message) || error).slice(0, 200)}` : ''
+    console.warn(`${LOG_PREFIX} ${message}${detail}`)
+  } catch { /* noop */ }
+}
+
+/**
+ * 把"取宿主服务 / 调宿主 API"包成 no-op：缺失或抛错 ⇒ 告警一次并返回 undefined。
+ * @template T
+ * @param {string} key - 告警去重键
+ * @param {string} label - 人话描述（进日志）
+ * @param {() => T} fn - 真正的宿主调用
+ * @returns {T|undefined}
+ */
+function safeStep(key, label, fn) {
+  try {
+    return fn()
+  } catch (error) {
+    warnOnce(key, `${label} 不可用/调用失败，已降级为 no-op`, error)
+    return undefined
+  }
+}
+
 /**
  * 当前可见的 ERP 只读工具数（= 0 说明没装 @whyshu/argent / MCP 没起；-1 = 读不到 tools 服务）
- * ⚠️ 用 ctx.get('tools') 而不是 ctx.tools：本插件只 inject webServer，直接取 ctx.tools 会抛。
+ * ⚠️ 用 ctx.get('tools') 而不是 ctx.tools：本插件没有 inject tools，直接取会抛。
  */
 function erpToolCount() {
   try {
@@ -39,17 +87,24 @@ function erpToolCount() {
   } catch { return -1 }
 }
 
-export const name = 'argent-erp'
-export const inject = ['webServer']
+export const name = NAME
+/**
+ * ⛔ 刻意**不声明** inject：版本闸必须在任何宿主上先跑一次（声明 webServer 会让本插件在
+ * 缺该服务的宿主上永远 pending、连"自我禁用"那行日志都打不出来）。webServer 改为
+ * apply 内用 `ctx.inject(['webServer'], …)` 等它就绪（Cordis 标准写法；缺失只告警一次）。
+ */
+export const inject = []
 
 /** 客户端 bundle 是否真的被加载过（区分"bundle 没加载" vs "加载了但没显示"） */
 const CLIENT_PING = { at: null, ua: '' }
-/** 视图是否真的**渲染**过（只有切到 ERP tab 才会打；用于区分"加载了但没选这个 tab"） */
+/** 面板是否真的**渲染**过（只有打开 ERP 主视图才会打） */
 const VIEW_PING = { at: null, ua: '' }
 
 const json = (res, code, body) => {
-  res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' })
-  res.end(JSON.stringify(body))
+  try {
+    res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' })
+    res.end(JSON.stringify(body))
+  } catch { /* 连接已断：吞掉，绝不让异常冒到宿主 */ }
 }
 
 async function handle(req, res) {
@@ -62,6 +117,8 @@ async function handle(req, res) {
       const erpTools = erpToolCount()
       return json(res, 200, {
         ok: true, version: pkgVersion(),
+        dsh: safeStep('health-version', '健康检查读取 dsh 版本', () => readDshVersion()) || null,
+        supportedDshRange: SUPPORTED_DSH_RANGE,
         erpTools,                                   // 0 ⇒ 只装了本插件、没装 @whyshu/argent
         officePreset: 'argent-office',              // 本插件声明的办公室角色 preset id
         clientPingAt: CLIENT_PING.at, clientUa: CLIENT_PING.ua,
@@ -107,17 +164,66 @@ async function handle(req, res) {
   }
 }
 
+/** 版本闸（导出给用例）：不传 version 时读当前宿主；任何异常都按"不支持"处理。 */
+export function evaluateHostCompat({ version } = {}) {
+  try {
+    const v = version === undefined ? readDshVersion() : version
+    return evaluateCompatibility(v)
+  } catch {
+    return { supported: false, version: null, range: SUPPORTED_DSH_RANGE, reason: '版本评估异常（按未适配处理）' }
+  }
+}
+
+/** 打印「插件已自我禁用」并返回（零宿主调用路径）。 */
+function selfDisable(compat, version) {
+  const shown = (compat && compat.version) || version || '未知版本'
+  const reason = (compat && compat.reason) || `不在支持范围 ${SUPPORTED_DSH_RANGE} 内`
+  try {
+    console.warn(`${LOG_PREFIX} 插件已自我禁用（dsh ${shown} 未适配）：${reason}。`
+      + `要求 ${SUPPORTED_DSH_RANGE}；dsh 可继续启动，升级 @whyshu/argent-erp 到适配版本后自动恢复。`)
+  } catch { /* noop */ }
+}
+
 export function apply(ctx) {
-  // ⛔ 永不抛出：插件激活失败会让整个 web boot 报 "entry did not activate"（2026-11-04 实测）。
+  // ⛔ 入口整体 try/catch：apply 抛错会让宿主把插件的激活失败升级成启动问题。
   try {
-    HOST_CTX = ctx
-    if (!ctx || !ctx.webServer || typeof ctx.webServer.register !== 'function') {
-      console.error('[argent-erp] 未拿到 webServer 服务，跳过端点注册（视图会显示 404，但 dsh 正常启动）')
+    // ── ① 版本闸（第一层在 manifest#engines.dsh；这里是兜底）────────────────
+    // 不支持：只打一行日志后 return —— **不碰 ctx 的任何属性/方法**（有用例断言调用次数为 0）。
+    const version = safeStep('detect-version', '读取 dsh 版本', () => readDshVersion()) ?? null
+    const compat = evaluateHostCompat({ version })
+    if (!compat.supported) {
+      selfDisable(compat, version)
       return
     }
-    ctx.effect(() => ctx.webServer.register({ kind: 'prefix', path: '/api/argent-erp', handler: handle }), 'argent-erp: read-only endpoints')
-    console.log(`[argent-erp] 已注册 /api/argent-erp/*（v${pkgVersion()}，只读，账号 token 仅在宿主侧使用）`)
-  } catch (e) {
-    console.error('[argent-erp] 端点注册失败（不影响 dsh 其他功能）:', e?.message || e)
+
+    // ── ② 等宿主 webServer 就绪再注册端点（未 inject：见上方 inject 注释）────
+    safeStep('webServer-wait', '等待宿主 webServer 服务', () => {
+      if (!ctx || typeof ctx.inject !== 'function') throw new Error('ctx.inject 不可用')
+      ctx.inject(['webServer'], (scope) => {
+        safeStep('webServer-register', '注册 /api/argent-erp/* 端点', () => {
+          if (!scope || !scope.webServer || typeof scope.webServer.register !== 'function') {
+            throw new Error('webServer.register 不可用')
+          }
+          const route = () => scope.webServer.register({ kind: 'prefix', path: '/api/argent-erp', handler: handle })
+          // ⛔ ctx.effect 缺失时退化为直接注册（都失败只告警一次）
+          if (typeof scope.effect === 'function') scope.effect(route, 'argent-erp: read-only endpoints')
+          else route()
+          SERVER_SCOPE = scope
+          HOST_CTX = scope
+          try { console.log(`${LOG_PREFIX} 已注册 /api/argent-erp/*（v${pkgVersion()}，dsh ${compat.version}，只读）`) } catch { /* noop */ }
+        })
+      })
+    })
+  } catch (error) {
+    warnOnce('apply', '插件初始化异常已兜住（dsh 可继续启动）', error)
   }
 }
+
+/** 仅测试用：清空"只告警一次"状态 + 读内部诊断。⛔ 不属于插件对外契约。 */
+export const __test__ = {
+  resetWarnings() { WARNED.clear() },
+  warnedKeys() { return [...WARNED] },
+  pkgVersion,
+  supportedRange: SUPPORTED_DSH_RANGE,
+  serverScope() { return SERVER_SCOPE },
+}

package/src/vendor/compat.mjs

@@ -0,0 +1,332 @@
+/**
+ * dsh 宿主兼容闸（0.2.13，2026-11-08）
+ *
+ * 用户诉求：**dsh 升级到未适配版本时，插件自己降级/关闭，但绝不能让 dsh web 启动失败或卡住。**
+ *
+ * 背景：插件用到的宿主能力（`ctx.webServer.register` / `ctx.plugin(dsh-mcp-client)` /
+ * `ctx.on('dispose')` / 客户端 `ctx.slots`）属于 dsh 内部契约，主/次版本一升就可能变。
+ * 2026-11-08 遇到过 boot 卡死（真因是 MCP 网关注册时 `office-guard` 重入；表现却是
+ * 「端口已 bound、HTTP 永远不响应」）⇒ 这类风险必须在插件侧自己兜住。
+ *
+ * 双层防线（本文件是第二层，第一层在 package.json#engines.dsh）：
+ *   ① **宿主侧（首选）**：`package.json#engines.dsh` 声明支持范围。dsh（0.2.x 起）在**导入插件代码之前**
+ *      就用 `evaluatePluginCompatibility()` 检查 manifest：不匹配的 bundle 被 skip、不匹配的 entry 被
+ *      disable，只在 stderr 打一行原因，**不阻断 boot**（已核对 dsh 0.2.2-rc.1 的 dsh-app-boot 实现）。
+ *      ⇒ 宿主升级到未适配版本时，插件根本不会被加载。
+ *   ② **插件侧（本文件，兜底）**：宿主不认 manifest 门禁（更老版本 / 手工 patch 挂载 / 已授豁免）时，
+ *      `apply()` 顶部自行评估版本：不支持 ⇒ 只打一条明确日志后 return，**不注册任何宿主 API**。
+ *
+ * 纯函数边界：本文件**不 import 任何宿主模块**（`@deepseek-ai/*`、`cordis`、`dsh-*`）；
+ * 只用 node 内置模块（fs/module/path/url）做只读探测，且所有解析失败都返回 null、绝不抛。
+ *
+ * ⚠️ 范围语义与 dsh 自己的门禁保持一致：dsh 用
+ * `semver.satisfies(runtimeVersion, range, { includePrerelease: true })`
+ * （见 `@deepseek-ai/dsh-app-boot` 的 `plugin-compatibility`）。dsh 日常发的是 rc 预发布
+ * （本机 0.2.2-rc.1、客户机 0.2.0-rc.2 / 0.2.1-rc.2），所以下界写成 `0.2.0-0` 才能把
+ * `0.2.0-rc.2` 算进来（严格 `>=0.2.0` 会把 0.2.0-rc.2 判为不支持，那是**错的**）；
+ * 上界写成 `0.3.0-0` 则把 0.3.0 的所有预发布也挡在外面（次版本升级按未适配处理，保守优先）。
+ */
+import { readFileSync, realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join, resolve as resolvePath } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** 支持范围（唯一真源；package.json#engines.dsh 必须与它逐字一致，有用例守着）。 */
+export const SUPPORTED_DSH_RANGE = '>=0.2.0-0 <0.3.0-0'
+/** 下界（含）。`-0` 是"该版本线最早的预发布"哨兵，不是笔误。 */
+export const SUPPORTED_DSH_MIN = '0.2.0-0'
+/** 上界（不含）。`-0` 让 0.3.0-rc.x 也算"高于上界" ⇒ 未适配。 */
+export const SUPPORTED_DSH_MAX = '0.3.0-0'
+
+/** 可显式覆盖版本探测的环境变量（排障/离线验证/宿主未暴露版本时用；顺序即优先级）。 */
+export const DSH_VERSION_ENV_KEYS = ['ARGENT_DSH_VERSION', 'DSH_VERSION']
+
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
+const NUMERIC_RE = /^\d+$/
+
+/**
+ * 解析 dsh 版本号（semver；允许 `v` 前缀与 `+build` 元数据）。
+ * @param {unknown} value
+ * @returns {{raw:string, version:string, major:number, minor:number, patch:number, prerelease:string[]}|null}
+ *   解析不了返回 null（**绝不抛** —— 未知版本必须走"降级"而不是炸 boot）。
+ */
+export function parseDshVersion(value) {
+  if (typeof value !== 'string') return null
+  const raw = value.trim()
+  if (!raw) return null
+  const m = SEMVER_RE.exec(raw)
+  if (!m) return null
+  const major = Number(m[1])
+  const minor = Number(m[2])
+  const patch = Number(m[3])
+  if (![major, minor, patch].every(Number.isSafeInteger)) return null
+  const prerelease = m[4] ? m[4].split('.') : []
+  return {
+    raw,
+    version: `${major}.${minor}.${patch}${m[4] ? `-${m[4]}` : ''}`,
+    major,
+    minor,
+    patch,
+    prerelease,
+  }
+}
+
+/** semver 预发布段比较（数字段 < 非数字段；数字按数值比；前缀短的小）。 */
+function comparePrerelease(a, b) {
+  if (a.length === 0 && b.length === 0) return 0
+  if (a.length === 0) return 1   // 正式版 > 预发布
+  if (b.length === 0) return -1
+  const n = Math.max(a.length, b.length)
+  for (let i = 0; i < n; i += 1) {
+    if (i >= a.length) return -1
+    if (i >= b.length) return 1
+    const x = a[i]
+    const y = b[i]
+    const xn = NUMERIC_RE.test(x)
+    const yn = NUMERIC_RE.test(y)
+    if (xn && yn) {
+      const d = Number(x) - Number(y)
+      if (d !== 0) return d < 0 ? -1 : 1
+      continue
+    }
+    if (xn) return -1
+    if (yn) return 1
+    if (x !== y) return x < y ? -1 : 1
+  }
+  return 0
+}
+
+/** 两个已解析版本的 semver 优先级比较（build 元数据不参与）。 */
+function compareParsed(a, b) {
+  for (const key of ['major', 'minor', 'patch']) {
+    if (a[key] !== b[key]) return a[key] < b[key] ? -1 : 1
+  }
+  return comparePrerelease(a.prerelease, b.prerelease)
+}
+
+/**
+ * semver 优先级比较（导出给用例/排障用）。
+ * @returns {number|null} -1 / 0 / 1；任一侧无法解析返回 null（不抛）
+ */
+export function compareDshVersions(a, b) {
+  const x = parseDshVersion(a)
+  const y = parseDshVersion(b)
+  if (!x || !y) return null
+  return compareParsed(x, y)
+}
+
+const MIN_BOUND = parseDshVersion(SUPPORTED_DSH_MIN)
+const MAX_BOUND = parseDshVersion(SUPPORTED_DSH_MAX)
+
+/** 版本是否落在支持范围内（等价于 `evaluateCompatibility(version).supported`）。 */
+export function isVersionSupported(version) {
+  const parsed = parseDshVersion(typeof version === 'string' ? version : '')
+  if (!parsed) return false
+  return compareParsed(parsed, MIN_BOUND) >= 0 && compareParsed(parsed, MAX_BOUND) < 0
+}
+
+/** 日志里的版本串截断（防御超长 env 值刷屏）。 */
+const show = (v) => {
+  const s = String(v == null ? '' : v).trim()
+  return s.length > 40 ? `${s.slice(0, 39)}…` : s
+}
+
+/**
+ * 评估宿主兼容性。**永不抛**：任何拿不准的情况都按 `supported:false`（降级）处理。
+ * @param {unknown} version dsh 版本号；null/''/无法解析 = 未知 = 不支持
+ * @returns {{supported:boolean, version:string|null, range:string, severity:'ok'|'warn', reason?:string}}
+ */
+export function evaluateCompatibility(version) {
+  const input = version == null ? '' : String(version).trim()
+  if (!input) {
+    return {
+      supported: false,
+      version: null,
+      range: SUPPORTED_DSH_RANGE,
+      severity: 'warn',
+      reason: '未能识别 dsh 版本（视为未适配，插件自动禁用）',
+    }
+  }
+  const parsed = parseDshVersion(input)
+  if (!parsed) {
+    return {
+      supported: false,
+      version: input,
+      range: SUPPORTED_DSH_RANGE,
+      severity: 'warn',
+      reason: `dsh 版本号无法解析（${show(input)}），视为未适配，插件自动禁用`,
+    }
+  }
+  if (compareParsed(parsed, MIN_BOUND) < 0) {
+    return {
+      supported: false,
+      version: parsed.raw,
+      range: SUPPORTED_DSH_RANGE,
+      severity: 'warn',
+      reason: `dsh ${parsed.raw} 低于适配下限（要求 ${SUPPORTED_DSH_RANGE}）`,
+    }
+  }
+  if (compareParsed(parsed, MAX_BOUND) >= 0) {
+    return {
+      supported: false,
+      version: parsed.raw,
+      range: SUPPORTED_DSH_RANGE,
+      severity: 'warn',
+      reason: `dsh ${parsed.raw} 高于适配上限（要求 ${SUPPORTED_DSH_RANGE}）`,
+    }
+  }
+  return { supported: true, version: parsed.raw, range: SUPPORTED_DSH_RANGE, severity: 'ok' }
+}
+
+/** 读 package.json 的 version；读不到/不是字符串返回 ''。 */
+function readPackageVersion(packageJsonPath) {
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
+    return typeof pkg?.version === 'string' ? pkg.version.trim() : ''
+  } catch {
+    return ''
+  }
+}
+
+/** 安全 realpath（路径可能不存在/是虚拟路径）。 */
+function safeRealpath(p) {
+  try { return realpathSync(p) } catch { return '' }
+}
+
+/**
+ * 直接从"路径里含 `node_modules/@deepseek-ai/dsh/`"的位置推出包目录并读 package.json。
+ *
+ * 为什么需要这条：`require.resolve('@deepseek-ai/dsh/package.json')` 依赖包的 `exports`
+ * 是否导出 `./package.json`。dsh 0.2.x 导出了，但**更老/更新的 dsh 布局不保证**——
+ * 而版本探测失败会退化成"未知 ⇒ 自动禁用"，在支持版本上那是**假降级**。
+ * 直接看路径不依赖 exports：npx 缓存 / 全局安装 / 工作区 checkout 三种布局都能命中。
+ * @returns {string} 版本号；不是 dsh 路径或读不到返回 ''
+ */
+function versionFromNodeModulesPath(p) {
+  if (typeof p !== 'string' || !p) return ''
+  for (const marker of ['/node_modules/@deepseek-ai/dsh/', '/node_modules/@deepseek-ai/dsh-app-boot/']) {
+    const at = p.indexOf(marker)
+    if (at < 0) continue
+    const dir = p.slice(0, at + marker.length - 1)   // 含 .../@deepseek-ai/dsh
+    const version = readPackageVersion(join(dir, 'package.json'))
+    if (version) return version
+  }
+  return ''
+}
+
+/**
+ * 默认的"从已安装包解析 dsh 版本"实现。
+ *
+ * 候选锚点（按顺序，全部 try/catch）：
+ *   ① `process.argv` 里的脚本路径 —— `npx @deepseek-ai/dsh web` 时 argv[1] 是
+ *      `.../_npx/<hash>/node_modules/.bin/dsh`，从它做 node 模块解析能找到
+ *      `<npx根>/node_modules/@deepseek-ai/dsh/package.json`；
+ *   ② 本插件模块自身的路径（profile 依赖树有时把宿主 peer 装在相邻位置）；
+ *   ③ 当前工作目录。
+ * 每个锚点两条路：`require.resolve('<包>/package.json')`（依赖 exports）
+ * + 路径直推（不依赖 exports，见 versionFromNodeModulesPath）。
+ * 另外兼容 `@deepseek-ai/dsh-app-boot`：dsh 自己的 `getDshRuntimeVersion()` 读的就是 app-boot 的
+ * package.json（两者 lockstep 发布），所以 dsh 主包解析不到时用它兜底。
+ *
+ * @returns {string} 版本号；解析不到返回 ''
+ */
+function resolveDshPackageVersion({ argv = process.argv, cwd = process.cwd() } = {}) {
+  const candidates = []
+  for (const a of Array.isArray(argv) ? argv : []) {
+    if (typeof a !== 'string' || !a.trim()) continue
+    if (a === process.execPath) continue
+    if (a.startsWith('-')) continue
+    // 只认"看起来像路径"的参数：绝对路径、相对路径、带分隔符；`web`/`--profile` 之类跳过。
+    if (!(a.startsWith('/') || a.startsWith('.') || a.includes('/') || a.includes('\\'))) continue
+    try {
+      candidates.push(a.startsWith('/') ? a : resolvePath(a))
+    } catch { /* 非法路径跳过 */ }
+  }
+  candidates.push(fileURLToPath(import.meta.url), join(cwd, 'package.json'))
+
+  for (const base of candidates) {
+    for (const name of ['@deepseek-ai/dsh/package.json', '@deepseek-ai/dsh-app-boot/package.json']) {
+      try {
+        const req = createRequire(base)
+        const version = readPackageVersion(req.resolve(name))
+        if (version) return version
+      } catch { /* 下一个锚点/包名 */ }
+    }
+    for (const p of [base, safeRealpath(base)]) {
+      const version = versionFromNodeModulesPath(p)
+      if (version) return version
+    }
+  }
+  return ''
+}
+
+/**
+ * 尽力识别当前 dsh 版本。**永不抛**，失败返回 null。
+ *
+ * 优先级：
+ *   ① env `ARGENT_DSH_VERSION` / `DSH_VERSION`（显式覆盖；离线验证/宿主未暴露版本时用）；
+ *   ② env `npm_package_name === '@deepseek-ai/dsh'` 时的 `npm_package_version`；
+ *   ③ argv 里字面出现的 `@deepseek-ai/dsh@x.y.z`（`npm exec` 形态会留下）；
+ *   ④ 包解析（见 resolveDshPackageVersion）。
+ *
+ * @param {{env?:Record<string,string|undefined>, argv?:string[], resolvePackageVersion?:Function}} [options]
+ *   仅供测试注入；生产调用不传参。
+ * @returns {string|null}
+ */
+export function readDshVersion(options = {}) {
+  try {
+    const env = (options.env && typeof options.env === 'object') ? options.env : process.env
+    const argv = Array.isArray(options.argv) ? options.argv : process.argv
+
+    for (const key of DSH_VERSION_ENV_KEYS) {
+      const v = env && typeof env[key] === 'string' ? env[key].trim() : ''
+      if (v) return v
+    }
+
+    if (env && env.npm_package_name === '@deepseek-ai/dsh' && typeof env.npm_package_version === 'string') {
+      const v = env.npm_package_version.trim()
+      if (v) return v
+    }
+
+    const literal = /@deepseek-ai\/dsh@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/
+    for (const a of argv) {
+      if (typeof a !== 'string') continue
+      const m = literal.exec(a)
+      if (m) return m[1]
+    }
+
+    const resolvePackageVersion = typeof options.resolvePackageVersion === 'function'
+      ? options.resolvePackageVersion
+      : resolveDshPackageVersion
+    const resolved = resolvePackageVersion({ argv })
+    if (typeof resolved === 'string' && resolved.trim()) return resolved.trim()
+    return null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 兼容闸的降级动作：**只打日志，不碰任何宿主 API**（不注册端点、不监听事件、不加载子插件）。
+ *
+ * 为什么这么克制：用户要的是"插件不能用就别拖累 dsh"。降级路径越简单，越不可能成为新的 boot 风险；
+ * 排障信息走 `[argent]` 日志即可（dsh web 的 stderr 用户能看到）。
+ *
+ * @param {object|null} ctx 宿主 context；当前刻意不使用（保留给将来"最小诊断注册"；
+ *   降级路径零宿主 API 调用这一点有用例断言）
+ * @param {{version?:string|null, reason?:string, log?:Console}} [options]
+ * @returns {{supported:false, degraded:true, version:string|null, reason:string}}
+ */
+export function installCompatGuard(ctx, { version = null, reason = '', log = console } = {}) {
+  const shown = version ? show(version) : '未知版本'
+  const detail = String(reason || '').trim() || `不在支持范围 ${SUPPORTED_DSH_RANGE} 内`
+  const line = `[argent] 插件已自我禁用（dsh ${shown} 未适配）：${detail}。`
+    + 'dsh 可继续启动；升级 @whyshu/argent 到适配版本后会自动恢复。'
+    + `（排障：可设 ${DSH_VERSION_ENV_KEYS[0]} 显式指定宿主版本）`
+  try {
+    if (log && typeof log.warn === 'function') log.warn(line)
+    else if (typeof log === 'function') log(line)
+    else console.warn(line)
+  } catch { /* 日志本身失败也绝不能影响宿主启动 */ }
+  return { supported: false, degraded: true, version: version || null, reason: detail }
+}