@whyshu/argent-erp 0.2.3 → 0.3.1

package/README.md

@@ -1,9 +1,9 @@
-# @whyshu/argent-erp（v0.2.0）
+# @whyshu/argent-erp（v0.3.1）
 
 **两件东西，一个货**：
 
-1. **DSH 会话视图插件**：会话顶部 Chat / 轨迹 旁加一个「ERP」tab，把 Argent ERP 的
-   办公室现场 / 待办 / 时间线 / 货件 / 聊一聊入口渲染进 dsh，看 ERP 不用离开当前会话；
+1. **左侧栏 ERP 入口 + 主视图面板**：侧栏多一个「ERP」图标，点一下主视图（会话区）整页切到 ERP——
+   办公室现场 / 待办 / 时间线 / 货件 / 聊一聊；点会话行或面板里的「← 会话」即可回到对话；
 2. **「六禾园办公室助理」preset**：让「和办公室聊一聊」变成一个**真正的 dsh 会话**
    （原生 Chat，含轨迹/统计/中断），但**边界写死在 preset 里**——只聊办公室、只读 ERP、无本机能力。
 
@@ -18,31 +18,40 @@ src/data.mjs              数据层：whoami / overview / timeline / flow / ship
 src/office-guard.js       办公室会话的**工具边界**（preset 内挂载：只放行 mcp__argent__erp_*）
 src/vendor/               account-token.mjs + redact.mjs 的**副本**（插件可发布，不能相对 import core/lib）
 presets/argent-office.patch.yml   「六禾园办公室助理」preset 声明行（dsh 0.2.x 行式 preset）
-dist/client.js            客户端 bundle（手写维护）：注册 conversation.view（id=erp）+ 视图实现
+dist/client.js            客户端 bundle（手写维护）：注册 sidebar.panellist（id=erp，图标）+ main（key=erp，面板）
 test/                     客户端 bundle + preset 边界冒烟测试（纯夹具，不启 dsh、不联网）
 ```
 
 `package.json#dsh.bundle.patch` 是**数组**：`[cordis.patch.yml, presets/argent-office.patch.yml]`
 ⇒ 一次 `install_bundle` 同时落「ERP 视图」与「办公室助理 preset」。
 
-## 2. 它是「会话视图」而不是「侧栏面板」
+## 2. 它是「左侧栏入口 + 主视图面板」，不是会话 tab、也不是右侧栏
 
-dsh 0.2.x 的 `conversation.view` 槽 = 对话顶部那排 **Chat / 轨迹 / 统计** 的注册位。
-本插件向该槽注册一项：
+dsh 0.2.x 的两项原生扩展点（`dsh-client-ui-sidebar` / `dsh-client-ui-layout`）：
+
+- `sidebar.panellist`：左侧栏那排**全局面板图标**（插件、定时任务…）；列表条目的 `id` 就是"对应哪个主视图"；
+- `main`（keyed）：主视图区，`activePanelId` 命中哪个 key 就渲染哪个；`null` = 显示对话。
+
+本插件注册两项，**id 与 key 必须相同**：
 
 ```js
-ctx.slots.inject("conversation.view", () => ctx.slots.register({
-  name: "conversation.view",
-  id: "erp",
-  order: 5,                 // Chat=0，本视图=5，轨迹=10
-  label: () => "ERP",
-  inject: () => ({ sessions, workspaceNav, remote }),   // 建会话 / 跳转 / 钉模型
+// ① 左侧栏图标（owner props: { size, active }）
+ctx.slots.inject("sidebar.panellist", () => ctx.slots.register({
+  name: "sidebar.panellist", id: "erp", order: 15, label: () => "ERP",
+}, ErpIcon))
+
+// ② 主视图面板（root 作用域：没有 Session 绑定）
+ctx.slots.inject("main", () => ctx.slots.register({
+  name: "main", key: "erp",
+  inject: () => ({ sessions, workspaceNav, remote, closePanel }),  // 给「聊一聊」建会话 / 返回按钮用
 }, ErpView))
 ```
 
-- 纯 UI 视图**不需要**注册 `ctx.uiConversation.views.register({ target })`
-  —— 那个 registry 是"消费 Session 事件"的 target 才需要的；ERP 视图读的是自己的宿主端点。
-- 视图随会话存在：切会话 → 视图重挂；切 tab 不丢别的 tab 状态。
+- 点击侧栏图标由 sidebar 调 `ctx.layout.selectPanel("erp")`；点任意会话行由 workspace 调
+  `selectPanel(null)` 回到对话；面板内再给一个「← 会话」按钮（同样走 `selectPanel(null)`）。
+- 主视图面板是 **root 作用域**（没有 `sessionId`）："在哪个 workspace 建办公室会话"取
+  `useWorkspaces` 的第 1 个 workspace（有当前会话时优先当前会话所属 workspace）。
+- 面板只在被选中时挂载 ⇒ 轮询/请求随关闭自动停。
 
 ## 3. 视图内容
 
@@ -117,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`，按天分组） |
@@ -142,7 +151,7 @@ dsh 设置 → 插件（Plugins）→ 安装 bundle → @whyshu/argent-erp
 ```
 
 - 装完**重启 dsh**（bundle patch 的宿主行与 preset 行在启动时装配）；
-- 之后新建会话的 **preset 选择器**里会出现「六禾园办公室助理」，对话顶部出现「ERP」tab；
+- 之后**左侧栏出现「ERP」图标**（点击切主视图），新建会话的 **preset 选择器**里出现「六禾园办公室助理」；
 - ⚠️ **同机需要 `@whyshu/argent`**（≥0.2.0）：它提供 `mcp__argent__erp_*` 工具与 `whyshu` provider。
   缺它时插件仍能装、视图仍能看（端点会报 no_token），但办公室角色会被 `office-guard` **安全降级为无工具**；
   宿主 `/api/argent-erp/health` 的 `erpTools` 会返回 `0`（= 没有 ERP 工具），`-1` = 读不到 tools 服务。
@@ -159,9 +168,11 @@ curl -s http://127.0.0.1:3080/api/argent-erp/health      # {"ok":true,"version":
 # 3) preset 行是否落了（应含 include:preset-argent-office）
 #    cordis_inspect_query host/Config/listConfigs name='@deepseek-ai/dsh-agent-preset'
 
-# 4) 客户端 tab 是否注册
-#    cordis_inspect_query client/Slots/listSubTree root='conversation.view'
-#    ⇒ occupants 含 { registrant: "argent-erp-client", id: "erp", order: 5, active: true }
+# 4) 客户端两处注册
+#    cordis_inspect_query client/Slots/listSubTree root='sidebar.panellist'
+#    ⇒ occupants 含 { registrant: "argent-erp-client", id: "erp", order: 15, active: true }
+#    cordis_inspect_query client/Slots/listSubTree root='main'
+#    ⇒ occupants 含 { registrant: "argent-erp-client", key: "erp", active: true }
 
 # 5) 单测（15 项，含 preset 边界断言）
 node plugins/argent-erp/test/client-bundle.test.mjs
@@ -171,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/dist/client.js

@@ -1,10 +1,12 @@
 /**
  * argent-erp · 客户端（dsh browser bundle 格式，**手写维护**）
  *
- * 形态：一个 `conversation.view` tab（对话顶部的 Chat / 轨迹 / **ERP** 切换项），
+ * 形态：**左侧栏一个「ERP」图标**（`sidebar.panellist`，id=erp）+ **主视图面板**（`main`，key=erp）——
+ * 点侧栏图标，主视图（会话区）切到 ERP；点会话行或面板里的「← 会话」回到对话。
  * 渲染 ERP 的只读视图：办公室现场 / 待办 / 时间线 / 货件 / 聊一聊。
  *
- * 为什么不是侧栏面板：会话视图与"正在做的那一单"同屏——看 ERP 不用离开会话。
+ * 为什么不是右侧栏：ERP 是"一整页工作台"（KPI/待办/时间线/货件/聊天入口），塞进窄侧栏只能看数字；
+ * 主视图面板能给它完整宽度，同时左侧栏一点就回来，不打断会话。
  *
  * 数据全部来自宿主端点 `/api/argent-erp/*`（token 在宿主侧，浏览器拿不到）。
  * ⛔ 不做写操作；重编辑一律跳 ERP web。
@@ -521,7 +523,7 @@ window.__ModuleLoader__.load({
       const [tenant, setTenant] = React.useState("")
       const [detail, setDetail] = React.useState(null) // { kind:'flow'|'shipment', id }
       const [nonce, setNonce] = React.useState(0)     // 刷新时让各自取数的面板重挂
-      // 渲染信标：只有切到 ERP tab 才会打 ⇒ /health 的 viewPingAt 能证明"真的渲染了"
+      // 渲染信标：只有打开 ERP 面板才会打 ⇒ /health 的 viewPingAt 能证明"真的渲染了"
       React.useEffect(() => { try { fetch(API + "/ping?from=view") } catch { /* noop */ } }, [])
       const who = useApi("/whoami")
       const health = useApi("/health")
@@ -556,6 +558,12 @@ window.__ModuleLoader__.load({
 
       return h("div", { className: "aerp-root" },
         h("div", { className: "aerp-head" },
+          props && typeof props.closePanel === "function"
+            ? h("button", {
+                type: "button", className: "aerp-btn", title: "回到会话",
+                onClick: () => { try { props.closePanel() } catch { /* noop */ } },
+              }, "← 会话")
+            : null,
           h("span", { className: "aerp-title" }, "Argent ERP"),
           tenants.length > 1
             ? h("select", {
@@ -581,26 +589,60 @@ window.__ModuleLoader__.load({
     const name = "argent-erp-client"
     const inject = ["slots"]
 
+    /** 侧栏入口 id 与主视图面板 key 必须一致（sidebar 用 id 去 main 槽取面板） */
+    const PANEL_ID = "erp"
+
+    /** 左侧栏「ERP」图标（owner props: { size, active }；用 currentColor，跟随主题） */
+    function ErpIcon(props) {
+      const size = (props && props.size) || 16
+      const active = Boolean(props && props.active)
+      const color = active ? "var(--dsw-alias-brand-primary)" : "currentColor"
+      return h("svg", {
+        width: size, height: size, viewBox: "0 0 24 24", fill: "none",
+        stroke: color, strokeWidth: 1.6, strokeLinecap: "round", strokeLinejoin: "round",
+        style: { display: "block" }, "aria-hidden": "true", focusable: "false",
+      },
+      h("path", { d: "M3.6 9.6 5.3 4.3h13.4l1.7 5.3" }),
+      h("path", { d: "M4.3 9.6h15.4v9.1a1.3 1.3 0 0 1-1.3 1.3H5.6a1.3 1.3 0 0 1-1.3-1.3V9.6Z" }),
+      h("path", { d: "M9.4 20v-4.7h5.2V20" }))
+    }
+
+    /** 取服务；没有/未注入时返回 undefined（动态插件 ctx 的白名单可能不含某个服务） */
+    const getService = (ctx, name) => { try { return ctx.get(name) } catch { return undefined } }
+
     function apply(ctx) {
       injectCss()
       // 自检信标：宿主 /health 会回报 clientPingAt ⇒ 能区分"bundle 没加载"与"加载了但没显示"
       try { fetch(API + "/ping?from=client").catch(() => {}) } catch { /* noop */ }
 
-      // ⛔ 永不抛出：注册失败只影响这个 tab，不能让 web boot 报 "entry did not activate"
+      // ⛔ 永不抛出：注册失败只影响 ERP 入口，不能让 web boot 报 "entry did not activate"
+
+      // ① 左侧栏入口（图标按钮）：点击后 sidebar 调 ctx.layout.selectPanel('erp') 切主视图
       try {
-        ctx.slots.inject("conversation.view", () => ctx.slots.register({
-          name: "conversation.view",
-          id: "erp",
-          order: 5,
+        ctx.slots.inject("sidebar.panellist", () => ctx.slots.register({
+          name: "sidebar.panellist",
+          id: PANEL_ID,
+          order: 15,
           label: () => "ERP",
+        }, ErpIcon))
+      } catch (e) {
+        console.warn("[argent-erp] 侧栏入口注册失败（不影响 dsh）:", (e && e.message) || e)
+      }
+
+      // ② 主视图面板：key 与侧栏 id 相同；root 作用域（没有 Session 绑定）
+      try {
+        ctx.slots.inject("main", () => ctx.slots.register({
+          name: "main",
+          key: PANEL_ID,
           inject: () => ({
-            sessions: (() => { try { return ctx.get("sessions") } catch { return undefined } })(),
-            workspaceNav: (() => { try { return ctx.get("uiWorkspace") } catch { return undefined } })(),
-            remote: (() => { try { return ctx.get("remote") } catch { return undefined } })(),
+            sessions: getService(ctx, "sessions"),
+            workspaceNav: getService(ctx, "uiWorkspace"),
+            remote: getService(ctx, "remote"),
+            closePanel: () => { try { getService(ctx, "layout")?.selectPanel?.(null) } catch { /* noop */ } },
           }),
         }, ErpView))
       } catch (e) {
-        console.warn("[argent-erp] conversation.view 注册失败（不影响 dsh）:", (e && e.message) || e)
+        console.warn("[argent-erp] 主视图面板注册失败（不影响 dsh）:", (e && e.message) || e)
       }
     }
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@whyshu/argent-erp",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "type": "module",
-  "description": "Argent ERP 会话视图（dsh conversation.view）+ 六禾园办公室助理 preset（只聊办公室、只读 ERP）+ 办公室聊一聊入口",
+  "description": "Argent ERP 左侧栏入口 + 主视图面板（dsh sidebar.panellist/main）+ 六禾园办公室助理 preset + 办公室聊一聊",
   "keywords": [
     "dsh",
     "deepseek-harness",
@@ -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 }
+}