dsh-my-guardian 0.3.4 → 0.3.6

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.6] - 2026-09-04
+
+### 变更
+
+- fix(guardian): 事件日志不再访问 entry.id getter——构造期 parent.tree 未就绪会抛错炸掉 DSH 启动（隔离实例复现）
+- fix(guardian): 诊断面板可读性 + entry 标识修复——插件失败时不再"看不懂/兜不住"
+- fix(guardian): #86 发版一致性修复——package.json 0.3.5 + CHANGELOG 0.3.5 段（rebase 冲突还原恢复）
+- chore(release): dsh-my-guardian v0.3.5（#86 依赖预检 + 验证清单）
+- feat(guardian): #86 候选区插件依赖预检 + 失败分类 (#124)
+- docs: #106 安装命令统一加 --trust-lockfile (#113)
+
+## [0.3.5] - 2026-09-04
+
+### 新增
+
+- [#86](https://github.com/baosfeng/my-dsh-plugins/issues/86) 候选区插件依赖预检 + 失败分类：热挂载前校验依赖就绪，失败按类别诊断（缺失依赖/锁定冲突/加载错误），诊断面板展示分类详情
+
+### 变更
+
+- 验证清单与效果图同步（发版前功能级验证归档）
+
 ## [0.3.4] - 2026-09-02
 
 ### 变更

package/README.md

@@ -13,23 +13,24 @@ cordis.patch.yml（核心区：只放稳定插件，守护插件自身）
         ↓ 新插件写进
 cordis.staged.json（候选区）
         ↓ DSH 启动完成后
-守护插件逐个热挂载
+守护插件逐个依赖预检 + 热挂载
         ├─ 成功 → 自动转正（进入持久化清单，每次启动自动恢复）
-        └─ 失败 → 自动隔离（记录次数+错误，连续 3 次冻结）
+        └─ 失败 → 自动隔离（记录次数 + 失败类型/错误，连续 3 次冻结）
 ```
 
 ## 功能
 
 - **两段式加载**：新装/更新插件先进候选区，启动不阻塞、坏插件不拖垮进程。
-- **失败自动隔离**：挂载失败自动记录（尝试次数 + 错误摘要），连续失败 **3 次冻结**，需手动重试。
+- **失败自动隔离**：挂载失败自动记录（尝试次数 + 失败类型 + 错误摘要），连续失败 **3 次冻结**，需手动重试。
+- **挂载前依赖预检**：候选插件挂载前检查 `peerDependencies`——仓库内 `dsh-*` 依赖是否安装、官方依赖版本是否满足；缺失/不满足即标记「依赖缺失」并给出安装建议（如 `dsh plugin add <依赖>`），不进入挂载。
 - **成功自动转正**：挂载成功的插件进入持久化清单（`$DSH_HOME/guardian/state.json`），后续每次启动自动恢复挂载。
 - **安全模式**：一键跳过所有候选/已转正插件，快速恢复被插件搞坏的环境。
-- **诊断面板**：dsh-better-sidebar 侧边栏"插件守护"页签——状态列表 / 重试 / 移除 / 错误详情 / 安全模式开关 / 最近事件。
+- **诊断面板**：dsh-better-sidebar 侧边栏"插件守护"页签——状态列表 / 重试 / 移除 / 错误详情 / 失败分类徽标 / 安全模式开关 / 最近事件。
 - **运行中热挂载**：DSH 运行期间往候选区加条目，自动挂载，无需重启。
 
 ## 安装
 
-> 💡 **npm 安装（普通用户推荐）**：`dsh plugin --profile web add dsh-my-guardian`——无需克隆本仓库；以下 link 方式供本仓库开发者使用。依赖 `dsh-shared`（server 端共享工具包）随 npm 自动安装，无需手动处理。
+> 💡 **npm 安装（普通用户推荐）**：`dsh plugin --profile web add dsh-my-guardian --trust-lockfile`——无需克隆本仓库；以下 link 方式供本仓库开发者使用。依赖 `dsh-shared`（server 端共享工具包）随 npm 自动安装，无需手动处理。
 
 ### 方式一：dsh plugin（推荐）
 
@@ -83,6 +84,8 @@ dsh plugin --profile web add link:<仓库路径>/plugins/dsh-my-guardian
 | 失败 ×N | 挂载失败 N 次          | 重试 / 移除            |
 | 冻结    | 连续失败 3 次          | 重试（解除冻结）/ 移除 |
 
+失败条目额外带**失败类型徽标**（依赖缺失 / 代码错误 / 其他），依赖缺失时并展示安装建议命令（如 `dsh plugin add dsh-shared`）。
+
 ### 效果截图（真实 DSH 实例验证）
 
 侧边栏"插件守护"诊断面板（独立 3081 端口隔离 DSH 实例实测）：
@@ -91,7 +94,7 @@ dsh plugin --profile web add link:<仓库路径>/plugins/dsh-my-guardian
 
 ![失败自动隔离：错误详情可查](https://unpkg.com/dsh-my-guardian/assets/panel-error-detail.png)
 
-> 截图环境：隔离 DSH 验证实例（`/tmp/dsh-3081`，端口 3081）。候选区同时写入 `demo-plugin`（挂载成功 → 自动转正"运行中"）与 `dsh-no-such-plugin-xyz`（包不存在 → 挂载失败自动隔离 ×1，错误详情保留可查）。
+> 截图环境：隔离 DSH 验证实例（`/tmp/dsh-3085`，端口 3085）。候选区写入 `fake-needy`（peer 依赖 `fake-never-installed-dep` 缺失 → 依赖预检拦截，分类徽标「依赖缺失」+ 安装建议 `dsh plugin add fake-never-installed-dep` + 自动隔离冻结）与 `fake-simple`（无依赖 → 热挂载成功自动转正「运行中」）。
 
 ## 配置
 

package/lib/api.js

@@ -155,45 +155,37 @@ async function handleSafemodePost(ctx, shared, request, response) {
   writeJson(response, 200, { ok: true, value: shared.snapshot() })
 }
 
+/** One row for the panel: status + failure-classification fields (issue #86). */
+function entrySnapshot(shared, id, record, isStaged) {
+  const status = shared.mounted.has(id)
+    ? 'running'
+    : record.frozen
+      ? 'frozen'
+      : record.attempts > 0
+        ? 'failed'
+        : 'pending'
+  const item = {
+    id,
+    name: record.name,
+    attempts: record.attempts,
+    frozen: record.frozen,
+    lastError: record.lastError,
+    lastFailedAt: record.lastFailedAt,
+    failureType: record.failureType ?? null,
+    missingDeps: record.missingDeps ?? [],
+    installHint: record.installHint ?? null,
+    status,
+  }
+  if (!isStaged) item.promotedAt = record.promotedAt
+  return item
+}
+
 /** Snapshot for the panel (leaf values only). */
 function snapshot(shared) {
-  const stagedList = []
-  for (const [id, record] of Object.entries(shared.state.staged)) {
-    stagedList.push({
-      id,
-      name: record.name,
-      attempts: record.attempts,
-      frozen: record.frozen,
-      lastError: record.lastError,
-      lastFailedAt: record.lastFailedAt,
-      status: shared.mounted.has(id)
-        ? 'running'
-        : record.frozen
-          ? 'frozen'
-          : record.attempts > 0
-            ? 'failed'
-            : 'pending',
-    })
-  }
-  const promotedList = []
-  for (const [id, record] of Object.entries(shared.state.promoted)) {
-    promotedList.push({
-      id,
-      name: record.name,
-      attempts: record.attempts,
-      frozen: record.frozen,
-      lastError: record.lastError,
-      lastFailedAt: record.lastFailedAt,
-      promotedAt: record.promotedAt,
-      status: shared.mounted.has(id)
-        ? 'running'
-        : record.frozen
-          ? 'frozen'
-          : record.attempts > 0
-            ? 'failed'
-            : 'pending',
-    })
-  }
+  const stagedList = Object.entries(shared.state.staged).map(([id, record]) => entrySnapshot(shared, id, record, true))
+  const promotedList = Object.entries(shared.state.promoted).map(([id, record]) =>
+    entrySnapshot(shared, id, record, false),
+  )
   return {
     safeMode: shared.state.safeMode,
     staged: stagedList,

package/lib/client.js

@@ -107,8 +107,22 @@ const STYLES = `
 .dsh-my-guardian-badge-pending { color:var(--dsw-alias-accent); background:color-mix(in srgb, var(--dsw-alias-accent) 12%, transparent); }
 .dsh-my-guardian-badge-failed { color:var(--dsw-alias-state-error-primary); background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 14%, transparent); }
 .dsh-my-guardian-badge-frozen { color:var(--dsw-alias-state-warn-primary); background:color-mix(in srgb, var(--dsw-alias-state-warn-primary) 16%, transparent); }
+/* failure-classification badge chips (issue #86): dependency / code / other */
+.dsh-my-guardian-category { flex:none; display:inline-flex; align-items:center; justify-content:center; height:17px; padding:0 5px; border-radius:4px;
+  font:var(--dsw-font-xxxs-strong-11); }
+.dsh-my-guardian-category-dependency { color:var(--dsw-alias-state-warn-primary); background:color-mix(in srgb, var(--dsw-alias-state-warn-primary) 16%, transparent); }
+.dsh-my-guardian-category-code { color:var(--dsw-alias-state-error-primary); background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 12%, transparent); }
+.dsh-my-guardian-category-other { color:var(--dsw-alias-label-tertiary); background:var(--dsw-alias-interactive-bg-hover); }
+/* install-suggestion line for dependency failures */
+.dsh-my-guardian-install-hint { display:flex; align-items:center; gap:5px; padding:3px 6px; border-radius:6px;
+  background:color-mix(in srgb, var(--dsw-alias-state-warn-primary) 6%, transparent);
+  font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); }
+.dsh-my-guardian-install-hint-label { flex:none; color:var(--dsw-alias-label-tertiary); }
+.dsh-my-guardian-install-hint code { font-family:ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size:var(--dsw-font-xxxs-11);
+  color:var(--dsw-alias-state-success-primary); word-break:break-all; }
 .dsh-my-guardian-row-meta { display:flex; align-items:center; gap:6px; font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); }
 .dsh-my-guardian-attempts { color:var(--dsw-alias-state-error-primary); }
+.dsh-my-guardian-freeze-hint { font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-state-warn-primary); line-height:1.6; }
 .dsh-my-guardian-link { display:inline-flex; align-items:center; gap:3px; padding:0; border:none; background:transparent; cursor:pointer;
   font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary);
   transition:color var(--ds-transition-duration-slow) var(--ds-ease-in-out); }
@@ -186,8 +200,8 @@ const strings = {
   safeMode: () => (isZh() ? '安全模式' : 'Safe mode'),
   safeModeDesc: () =>
     isZh()
-      ? '开启后所有候选/已转正插件都不再加载，用于快速恢复环境'
-      : 'Skips every staged/promoted plugin mount — fast recovery',
+      ? '开启后所有候选/已转正插件（候选区 cordis.staged.json 中的条目）都不再加载，用于快速恢复环境。注意：安全模式只作用于启动后挂载的候选插件；若插件直接写进启动名册（cordis.patch.yml / profile），DSH 启动时仍是 all-or-nothing——请把新插件先放进候选区。'
+      : 'Skips every staged/promoted plugin mount — fast recovery. Note: this only covers entries mounted after boot (cordis.staged.json); plugins in the boot roster (cordis.patch.yml / profile) are still all-or-nothing — put new plugins in the staged file first.',
   staged: () => (isZh() ? '候选' : 'staged'),
   promoted: () => (isZh() ? '转正' : 'promoted'),
   entries: () => (isZh() ? '插件条目' : 'Plugin entries'),
@@ -215,6 +229,14 @@ const strings = {
   loading: () => (isZh() ? '加载中…' : 'Loading…'),
   events: () => (isZh() ? '最近事件' : 'Recent events'),
   attempts: (n) => (isZh() ? `失败 ${n} 次` : `failed ×${n}`),
+  frozenHint: () =>
+    isZh()
+      ? '已冻结：连续失败停止自动重试——点击刷新按钮手动重试，或移除该条目'
+      : 'Frozen: auto-retry stopped after repeated failures — retry manually or remove the entry',
+  failureDependency: () => (isZh() ? '依赖缺失' : 'Dependency'),
+  failureCode: () => (isZh() ? '代码错误' : 'Code error'),
+  failureOther: () => (isZh() ? '其他' : 'Other'),
+  installHint: () => (isZh() ? '安装建议' : 'Install'),
 }
 
 // ── api ───────────────────────────────────────────────────────────────
@@ -256,6 +278,20 @@ function statusLabel(status) {
   }
 }
 
+/** Failure-classification badge label (issue #86): dependency / code / other. */
+function failureTypeLabel(type) {
+  switch (type) {
+    case 'dependency':
+      return strings.failureDependency()
+    case 'code':
+      return strings.failureCode()
+    case 'other':
+      return strings.failureOther()
+    default:
+      return type
+  }
+}
+
 // ── event log ─────────────────────────────────────────────────────────
 // Event type → badge label + color variant (mirrors the dfa-op chip style).
 const EVENT_LABELS = {
@@ -442,6 +478,27 @@ const icon = {
       ],
       size,
     ),
+  // 下载（issue #85 新增）：箭头入托盘，图表导出按钮（dsh-mermaid-render
+  // 卡片下载 PNG/SVG），stroke=currentColor 风格与其余图标一致。
+  download: (size = 16) =>
+    iconSvg(
+      [
+        createElement('path', { d: 'M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4' }),
+        createElement('polyline', { points: '7 10 12 15 17 10' }),
+        createElement('line', { x1: 12, y1: 15, x2: 12, y2: 3 }),
+      ],
+      size,
+    ),
+  // 复制（issue #85 新增）：双层矩形，复制源码按钮（dsh-mermaid-render
+  // 卡片复制代码），stroke=currentColor 风格与其余图标一致。
+  copy: (size = 16) =>
+    iconSvg(
+      [
+        createElement('rect', { x: 9, y: 9, width: 13, height: 13, rx: 2 }),
+        createElement('path', { d: 'M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1' }),
+      ],
+      size,
+    ),
 }
 
 // Common-language / file-type badges (issue #24): brand fill + contrast
@@ -599,7 +656,7 @@ const fileIconByExt = (ext, size = 14) => {
 }
 
     // ── row ────────────────────────────────────────────────────────────────
-/** Row head: source chip + name + status badge. */
+/** Row head: source chip + name + status badge + failure-category badge. */
 function RowHead({ entry, source }) {
   return createElement(
     'div',
@@ -615,6 +672,16 @@ function RowHead({ entry, source }) {
       { className: `dsh-my-guardian-badge dsh-my-guardian-badge-${entry.status}` },
       statusLabel(entry.status),
     ),
+    typeof entry.failureType === 'string' && entry.failureType !== ''
+      ? createElement(
+          'span',
+          {
+            className: `dsh-my-guardian-category dsh-my-guardian-category-${entry.failureType}`,
+            title: entry.failureType,
+          },
+          failureTypeLabel(entry.failureType),
+        )
+      : null,
   )
 }
 
@@ -722,11 +789,26 @@ function RowActions({ entry, busy, onRetry, onRemove }) {
   )
 }
 
+/** 冻结行提示（连败停止自动重试，需手动操作）。 */
+function FrozenHint({ status }) {
+  if (status !== 'frozen') return null
+  return createElement('div', { className: 'dsh-my-guardian-freeze-hint' }, strings.frozenHint())
+}
+
 function EntryRow({ entry, source, onAction }) {
-  const [expanded, setExpanded] = useState(false)
+  // 失败/冻结行默认展开错误详情（用户之前必须手动点开才看得到真正报错）。
+  const [expanded, setExpanded] = useState(
+    () =>
+      typeof entry.lastError === 'string' &&
+      entry.lastError !== '' &&
+      (entry.status === 'failed' || entry.status === 'frozen'),
+  )
   const [confirming, setConfirming] = useState(false)
   const [busy, setBusy] = useState(false)
   const hasError = typeof entry.lastError === 'string' && entry.lastError !== ''
+  const isDepFailure = entry.failureType === 'dependency'
+  const installHint =
+    isDepFailure && typeof entry.installHint === 'string' && entry.installHint !== '' ? entry.installHint : null
 
   const run = (kind) => {
     setBusy(true)
@@ -738,6 +820,15 @@ function EntryRow({ entry, source, onAction }) {
     { className: 'dsh-my-guardian-row' },
     createElement(RowHead, { entry, source }),
     createElement(RowMeta, { entry }),
+    createElement(FrozenHint, { status: entry.status }),
+    installHint
+      ? createElement(
+          'div',
+          { className: 'dsh-my-guardian-install-hint' },
+          createElement('span', { className: 'dsh-my-guardian-install-hint-label' }, strings.installHint()),
+          createElement('code', null, installHint),
+        )
+      : null,
     hasError ? createElement(ErrorToggle, { expanded, onToggle: () => setExpanded(!expanded) }) : null,
     expanded && hasError ? createElement('pre', { className: 'dsh-my-guardian-error-detail' }, entry.lastError) : null,
     confirming
@@ -884,14 +975,19 @@ function EntryList({ rows, onAction }) {
   )
 }
 
-/** Recent guardian event log: badge + key info + time per entry. */
+/** 高频噪音事件：每次启动/热重载都会大量产生，挤掉真正重要的诊断信息。 */
+const EVENT_NOISE = new Set(['entry-init', 'entry-dispose'])
+
+/** Recent guardian event log: badge + key info + time per entry.
+ *  过滤 entry-init/entry-dispose 噪音，优先展示隔离/冻结/更新失败等关键事件。 */
 function EventList({ events }) {
-  if (events.length === 0) return null
+  const important = events.filter((event) => !EVENT_NOISE.has(event.type))
+  if (important.length === 0) return null
   return createElement(
     'div',
     { className: 'dsh-my-guardian-events' },
     createElement('div', { className: 'dsh-my-guardian-events-title' }, icon.clock(14), strings.events()),
-    events.map((event, index) =>
+    important.map((event, index) =>
       createElement(
         'div',
         {

package/lib/dep-precheck.js

@@ -0,0 +1,132 @@
+/**
+ * dsh-my-guardian — dependency pre-check for the candidate mount pipeline.
+ *
+ * Reads a candidate plugin's package.json peerDependencies (from the profile
+ * node_modules) and verifies each dependency is installed and version-satisfying
+ * BEFORE the plugin is mounted. A hard-missing dependency is reported as a
+ * pre-check failure (failureType 'dependency') with an install suggestion, and
+ * the mount is skipped — the plugin never enters the runtime load path with a
+ * hole in its dependency graph (issue #72: dsh-shared was not published).
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { satisfies } from './dep-version.js'
+
+// Locate a package directory below a node_modules root, following symlinks
+// (pnpm store / npm link both expose package.json through the mirrored dir).
+function findModuleDir(nmRoot, packageName) {
+  const dir = join(nmRoot, packageName)
+  return existsSync(join(dir, 'package.json')) ? dir : null
+}
+
+// Resolve a dependency from the plugin's nested node_modules or the profile
+// node_modules (hoisted installs). Returns the dir or null when absent.
+function resolveDependencyDir(profileDir, pluginDir, dep) {
+  const nested = pluginDir === null ? null : findModuleDir(join(pluginDir, 'node_modules'), dep)
+  if (nested !== null) return nested
+  return findModuleDir(join(profileDir, 'node_modules'), dep)
+}
+
+function readPackageJson(dir) {
+  if (dir === null) return null
+  try {
+    return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function installedVersion(dir) {
+  const pkg = readPackageJson(dir)
+  return pkg !== null && typeof pkg.version === 'string' ? pkg.version : null
+}
+
+// Inspect a single peer dependency and classify the outcome.
+function examinePeer(dep, range, optional, pluginDir, profileDir) {
+  const depDir = resolveDependencyDir(profileDir, pluginDir, dep)
+  if (depDir === null) {
+    if (optional) return { kind: 'warn', message: `可选依赖 ${dep} 缺失（未安装）` }
+    return { kind: 'missing', name: dep }
+  }
+  const version = installedVersion(depDir)
+  if (version !== null && typeof range === 'string' && range.trim() !== '' && !satisfies(version, range)) {
+    const issue = { name: dep, expected: range, found: version }
+    if (optional) return { kind: 'warn', message: `可选依赖 ${dep} 版本不满足：${range}（当前 ${version}）` }
+    return { kind: 'mismatch', issue }
+  }
+  return { kind: 'ok' }
+}
+
+function buildSuggestions(missing, mismatched) {
+  const suggestions = missing.map((dep) => `dsh plugin add ${dep}`)
+  for (const item of mismatched) suggestions.push(`dsh plugin add ${item.name}@${item.expected}`)
+  return suggestions
+}
+
+function objectOrEmpty(value) {
+  return value ?? {}
+}
+
+// Group every peer into missing / mismatched / warning buckets.
+function classifyPeers(peers, meta, pluginDir, profileDir) {
+  const missing = []
+  const mismatched = []
+  const warnings = []
+  for (const [dep, range] of Object.entries(peers)) {
+    const result = examinePeer(dep, range, meta[dep]?.optional === true, pluginDir, profileDir)
+    if (result.kind === 'missing') missing.push(result.name)
+    else if (result.kind === 'mismatch') mismatched.push(result.issue)
+    else if (result.kind === 'warn') warnings.push(result.message)
+  }
+  return { missing, mismatched, warnings }
+}
+
+function skippedResult(reason) {
+  return { ok: true, missing: [], mismatched: [], suggestions: [], warnings: [`跳过依赖预检：${reason}`] }
+}
+
+/**
+ * Pre-check the peer dependencies of a candidate plugin. Returns:
+ *   { ok, missing, mismatched, suggestions, warnings }
+ *  - missing: deps required (not optional) but absent from node_modules
+ *  - mismatched: deps present at a version outside the declared range
+ *  - suggestions: `dsh plugin add ...` repair commands
+ *  - warnings: non-blocking notes (plugin unreadable / optional peers missing)
+ * When the plugin or its package.json cannot be located the check is skipped
+ * (ok: true) so an unusual install layout is never a false block.
+ */
+export function checkPeerDependencies({ profileDir, pluginName }) {
+  const pluginDir = findModuleDir(join(profileDir, 'node_modules'), pluginName)
+  if (pluginDir === null)
+    return skippedResult(`无法定位插件 ${pluginName}（未在 profile node_modules 找到 package.json）`)
+  const pkg = readPackageJson(pluginDir)
+  if (pkg === null) return skippedResult(`无法解析 ${pluginName} 的 package.json`)
+  const { missing, mismatched, warnings } = classifyPeers(
+    objectOrEmpty(pkg.peerDependencies),
+    objectOrEmpty(pkg.peerDependenciesMeta),
+    pluginDir,
+    profileDir,
+  )
+  return {
+    ok: missing.length === 0 && mismatched.length === 0,
+    missing,
+    mismatched,
+    suggestions: buildSuggestions(missing, mismatched),
+    warnings,
+  }
+}
+
+/** Build the "缺少依赖 X（请先安装）" message recorded for a failed pre-check. */
+export function buildDependencyMessage(result) {
+  const names = [...result.missing, ...result.mismatched.map((item) => item.name)]
+  if (names.length === 0) return '依赖预检失败'
+  return names.map((name) => `缺少依赖 ${name}（请先安装）`).join('；')
+}
+
+/** Classify a mount failure for the isolation record (issue #86). */
+export function classifyFailure(error) {
+  const message = error instanceof Error ? error.message : String(error)
+  if (/Cannot find module|MODULE_NOT_FOUND|Cannot resolve/i.test(message)) return 'dependency'
+  if (/already exists|already in use|conflict/i.test(message)) return 'other'
+  return 'code'
+}

package/lib/dep-version.js

@@ -0,0 +1,188 @@
+/**
+ * dsh-my-guardian — minimal semver helpers for the dependency pre-check.
+ *
+ * Only the subset needed to validate peerDependency ranges is implemented:
+ * parse a version, compare two versions (with prerelease precedence), and test
+ * whether a version satisfies a range (`^`, `~`, comparator operators,
+ * wildcards, `||` and whitespace-AND). Build metadata (`+build`) is ignored for
+ * precedence. Everything is pure and dependency-free.
+ */
+
+// Parse a version string into { major, minor, patch, prerelease }.
+// Returns null for input that is not a usable version.
+function parseVersion(input) {
+  if (typeof input !== 'string') return null
+  const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(input.trim())
+  if (match === null) return null
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2] ?? 0),
+    patch: Number(match[3] ?? 0),
+    prerelease: match[4] === undefined ? [] : match[4].split('.'),
+  }
+}
+
+// Numeric identifiers have lower precedence than alphanumeric ones.
+function compareIdentifiers(a, b) {
+  const aNum = /^\d+$/.test(a)
+  const bNum = /^\d+$/.test(b)
+  if (aNum && bNum) return Number(a) - Number(b)
+  if (aNum !== bNum) return aNum ? -1 : 1
+  return a < b ? -1 : a > b ? 1 : 0
+}
+
+// Compare two prerelease arrays (a shorter list has lower precedence).
+function comparePrerelease(ap, bp) {
+  if (ap.length === 0 && bp.length === 0) return 0
+  if (ap.length === 0) return 1
+  if (bp.length === 0) return -1
+  const len = Math.max(ap.length, bp.length)
+  for (let i = 0; i < len; i++) {
+    const ai = ap[i]
+    const bi = bp[i]
+    if (ai === undefined) return -1
+    if (bi === undefined) return 1
+    const diff = compareIdentifiers(ai, bi)
+    if (diff !== 0) return diff
+  }
+  return 0
+}
+
+// Compare two parsed version tuples (major/minor/patch/prerelease).
+// Returns negative/zero/positive like Array#sort.
+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)
+}
+
+// Parse a range version spec that may contain wildcards (`x`/`*`) and a
+// trailing prerelease (`1.2.3-rc.8`). Missing/padded components are null.
+function parseRangeVersion(spec) {
+  const match = /^v?(\d+|[xX*])(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(?:-([0-9A-Za-z.-]+))?$/.exec(spec.trim())
+  if (match === null) return null
+  const toNum = (value) => (value !== undefined && /^\d+$/.test(value) ? Number(value) : null)
+  return {
+    major: toNum(match[1]),
+    minor: match[2] === undefined ? null : toNum(match[2]),
+    patch: match[3] === undefined ? null : toNum(match[3]),
+    prerelease: match[4] === undefined ? [] : match[4].split('.'),
+  }
+}
+
+// Lower bound tuple for a caret/tilde range base (wildcards → 0).
+function lowerBound(base) {
+  return {
+    major: base.major ?? 0,
+    minor: base.minor ?? 0,
+    patch: base.patch ?? 0,
+    prerelease: base.prerelease,
+  }
+}
+
+// Upper bound for a caret range: bump the first non-zero component.
+function caretUpper(lo) {
+  if (lo.major > 0) return { major: lo.major + 1, minor: 0, patch: 0, prerelease: ['0'] }
+  if (lo.minor > 0) return { major: 0, minor: lo.minor + 1, patch: 0, prerelease: ['0'] }
+  if (lo.patch > 0) return { major: 0, minor: 0, patch: lo.patch + 1, prerelease: ['0'] }
+  return { major: 0, minor: 1, patch: 0, prerelease: ['0'] }
+}
+
+function satisfiesCaret(version, spec) {
+  const base = parseRangeVersion(spec)
+  const parsed = parseVersion(version)
+  if (base === null || parsed === null) return false
+  const lo = lowerBound(base)
+  if (compareParsed(parsed, lo) < 0) return false
+  return compareParsed(parsed, caretUpper(lo)) < 0
+}
+
+function satisfiesTilde(version, spec) {
+  const base = parseRangeVersion(spec)
+  const parsed = parseVersion(version)
+  if (base === null || parsed === null) return false
+  const lo = lowerBound(base)
+  if (compareParsed(parsed, lo) < 0) return false
+  const upper =
+    base.minor === null
+      ? { major: lo.major + 1, minor: 0, patch: 0, prerelease: ['0'] }
+      : { major: lo.major, minor: lo.minor + 1, patch: 0, prerelease: ['0'] }
+  return compareParsed(parsed, upper) < 0
+}
+
+// Compare a single range component against the version; wildcard (null) skips.
+function compareComponent(parsed, base, key) {
+  if (base[key] === null) return 0
+  if (parsed[key] === base[key]) return 0
+  return parsed[key] < base[key] ? -1 : 1
+}
+
+// Compare a version against a range spec, only over the components that are
+// concrete numbers. Returns null when either side is not a usable version.
+function compareRangeToVersion(version, spec) {
+  const base = parseRangeVersion(spec)
+  const parsed = parseVersion(version)
+  if (base === null || parsed === null) return null
+  for (const key of ['major', 'minor', 'patch']) {
+    const diff = compareComponent(parsed, base, key)
+    if (diff !== 0) return diff
+  }
+  return 0
+}
+
+function satisfiesComparator(version, token) {
+  const match = /^(>=|<=|>|<|=|==)?\s*(.+)$/.exec(token.trim())
+  if (match === null) return false
+  const op = match[1] ?? '='
+  const diff = compareRangeToVersion(version, match[2].trim())
+  if (diff === null) return false
+  if (op === '>') return diff > 0
+  if (op === '<') return diff < 0
+  if (op === '>=') return diff >= 0
+  if (op === '<=') return diff <= 0
+  return diff === 0
+}
+
+function satisfiesExactOrWildcard(version, token) {
+  const base = parseRangeVersion(token)
+  const parsed = parseVersion(version)
+  if (base === null || parsed === null) return false
+  return compareRangeToVersion(version, token) === 0
+}
+
+function satisfiesToken(version, token) {
+  if (token === '' || token === '*' || token === 'x' || token === 'X') return true
+  if (token.startsWith('^')) return satisfiesCaret(version, token.slice(1))
+  if (token.startsWith('~')) return satisfiesTilde(version, token.slice(1))
+  if (/^(>=|<=|>|<|=|==)/.test(token)) return satisfiesComparator(version, token)
+  return satisfiesExactOrWildcard(version, token)
+}
+
+// A single alternative group: whitespace-AND of tokens, minus hyphen ranges.
+function satisfiesAll(version, alt) {
+  if (alt === '') return true
+  const hyphen = alt.split(/\s+-\s+/)
+  if (hyphen.length === 2) {
+    return satisfies(version, `>=${hyphen[0].trim()}`) && satisfies(version, `<=${hyphen[1].trim()}`)
+  }
+  return alt
+    .split(/\s+/)
+    .filter(Boolean)
+    .every((token) => satisfiesToken(version, token))
+}
+
+/**
+ * Test whether `version` satisfies `range` (supports `||`, whitespace-AND and
+ * the common comparators). An empty or `*` range matches anything. A prerelease
+ * version only matches when the range itself mentions a prerelease — mirroring
+ * the semver rule that prereleases are opt-in.
+ */
+export function satisfies(version, range) {
+  if (typeof version !== 'string' || typeof range !== 'string') return false
+  const trimmed = range.trim()
+  if (trimmed === '' || trimmed === '*') return true
+  const parsed = parseVersion(version)
+  if (parsed !== null && parsed.prerelease.length > 0 && !range.includes('-')) return false
+  return trimmed.split('||').some((alt) => satisfiesAll(version, alt.trim()))
+}

package/lib/events.js

@@ -17,10 +17,10 @@ export function logEvent(shared, type, message) {
 /** Register the loader/HMR diagnostic listeners (R9/R10). */
 export function attachEventListeners(ctx, shared) {
   ctx.on('loader/entry-init', (entry) => {
-    logEvent(shared, 'entry-init', `entry ${entry?.options?.id ?? '?'} initialized`)
+    logEvent(shared, 'entry-init', `entry ${entryLabelOf(entry)} initialized`)
   })
   ctx.on('loader/partial-dispose', (entry) => {
-    logEvent(shared, 'entry-dispose', `entry ${entry?.options?.id ?? '?'} disposed`)
+    logEvent(shared, 'entry-dispose', `entry ${entryLabelOf(entry)} disposed`)
   })
   ctx.on('hmr/config-update-failed', (filename, error) => {
     logEvent(shared, 'update-failed', `${filename}: ${error instanceof Error ? error.message : String(error)}`)
@@ -28,3 +28,22 @@ export function attachEventListeners(ctx, shared) {
     shared.persistSoon()
   })
 }
+
+/**
+ * entry 可读标识——⚠️ 只读 options 字段，绝不访问 `entry.id` getter：
+ * loader 在 Entry **构造函数中** emit `loader/entry-init`，此时
+ * `parent.tree` 尚未就绪，访问 getter 会抛 "Cannot read properties of
+ * undefined (reading 'tree')" —— 这个异常发生在启动阶段，会让整个
+ * DSH 服务起不来（守护插件自己炸启动，实锤隔离实例复现）。
+ * （此前读 `entry?.options?.id` 安全但恒为空显示 '?'；本次改为
+ *  options.id → options.name → '?' 的回退，全部属性访问都可安全兜底。）
+ */
+function entryLabelOf(entry) {
+  if (entry === null || typeof entry !== 'object') return '?'
+  const options = entry.options
+  if (options !== null && typeof options === 'object') {
+    if (options.id !== undefined && options.id !== null) return String(options.id)
+    if (typeof options.name === 'string' && options.name !== '') return options.name
+  }
+  return '?'
+}

package/lib/mount.js

@@ -9,6 +9,7 @@
 import { dirname } from 'node:path'
 import { FREEZE_LIMIT, errorSnip, loadState, readStagedFile, writeStagedFile } from './state.js'
 import { logEvent } from './events.js'
+import { checkPeerDependencies, buildDependencyMessage, classifyFailure } from './dep-precheck.js'
 
 /**
  * Find the root Include tree of the profile. The loader tree's entries carry
@@ -91,16 +92,40 @@ async function mountWithState(shared, kind, id, entry) {
   const record = shared.state[recordKey][id] ?? {}
   if (record.frozen) return 'skipped'
   const name = typeof entry?.name === 'string' ? entry.name : id
+  // Dependency pre-check (issue #86): a plugin whose peer deps are missing or
+  // out of range must not enter the runtime load path with a hole in its
+  // dependency graph. A failed pre-check is recorded as a 'dependency' failure
+  // with the missing deps + an install suggestion, and the mount is skipped.
+  const precheck = precheckEntry(shared, name)
+  if (precheck !== null) {
+    recordFailure(shared, recordKey, id, name, entry, record, {
+      failureType: 'dependency',
+      message: buildDependencyMessage(precheck),
+      missingDeps: [...precheck.missing, ...precheck.mismatched.map((item) => item.name)],
+      installHint: precheck.suggestions[0] ?? null,
+    })
+    return 'failed'
+  }
   try {
     await mount(shared, id, entry)
     await promote(shared, recordKey, id, name, entry, record)
     return 'mounted'
   } catch (error) {
-    recordFailure(shared, recordKey, id, name, entry, record, error)
+    recordFailure(shared, recordKey, id, name, entry, record, {
+      failureType: classifyFailure(error),
+      message: error instanceof Error ? error.message : String(error),
+    })
     return 'failed'
   }
 }
 
+/** Run the dependency pre-check; null means it passed (or was skipped). */
+function precheckEntry(shared, name) {
+  if (typeof name !== 'string' || name === '') return null
+  const result = checkPeerDependencies({ profileDir: shared.profileDir, pluginName: name })
+  return result.ok ? null : result
+}
+
 /** Success path: staged moves into the persisted promoted list (R2). */
 async function promote(shared, recordKey, id, name, entry, record) {
   if (recordKey === 'staged') {
@@ -111,6 +136,9 @@ async function promote(shared, recordKey, id, name, entry, record) {
       lastError: null,
       lastFailedAt: null,
       frozen: false,
+      failureType: null,
+      missingDeps: [],
+      installHint: null,
       promotedAt: Date.now(),
     }
     delete shared.state.staged[id]
@@ -125,6 +153,9 @@ async function promote(shared, recordKey, id, name, entry, record) {
       lastError: null,
       lastFailedAt: null,
       frozen: false,
+      failureType: null,
+      missingDeps: [],
+      installHint: null,
     }
   }
   logEvent(shared, 'promote', `mounted ${name} (${id})`)
@@ -132,19 +163,23 @@ async function promote(shared, recordKey, id, name, entry, record) {
 }
 
 /** Failure path: attempts counter + error recorded; freeze at the limit. */
-function recordFailure(shared, recordKey, id, name, entry, record, error) {
+function recordFailure(shared, recordKey, id, name, entry, record, info) {
   const attempts = (record.attempts ?? 0) + 1
   const frozen = attempts >= FREEZE_LIMIT
+  const message = typeof info.message === 'string' ? info.message : String(info.message ?? info)
   shared.state[recordKey][id] = {
     name,
     config: entry.config ?? undefined,
     attempts,
-    lastError: errorSnip(error),
+    lastError: errorSnip(message),
     lastFailedAt: Date.now(),
     frozen,
+    failureType: info.failureType ?? 'code',
+    missingDeps: info.missingDeps ?? [],
+    installHint: info.installHint ?? null,
     ...(recordKey === 'promoted' ? { promotedAt: record.promotedAt } : {}),
   }
-  logEvent(shared, frozen ? 'freeze' : 'quarantine', `${name} (${id}) failed ${attempts}x: ${error.message ?? error}`)
+  logEvent(shared, frozen ? 'freeze' : 'quarantine', `${name} (${id}) failed ${attempts}x: ${message}`)
   shared.persistSoon()
 }
 
@@ -211,6 +246,9 @@ async function retryEntry(shared, id) {
       lastError: null,
       lastFailedAt: null,
       frozen: false,
+      failureType: null,
+      missingDeps: [],
+      installHint: null,
     }
     shared.persistSoon()
     if (shared.state.safeMode) return 'safe'

package/lib/parts/row.part.js

@@ -1,5 +1,5 @@
 // ── row ────────────────────────────────────────────────────────────────
-/** Row head: source chip + name + status badge. */
+/** Row head: source chip + name + status badge + failure-category badge. */
 function RowHead({ entry, source }) {
   return createElement(
     'div',
@@ -15,6 +15,16 @@ function RowHead({ entry, source }) {
       { className: `dsh-my-guardian-badge dsh-my-guardian-badge-${entry.status}` },
       statusLabel(entry.status),
     ),
+    typeof entry.failureType === 'string' && entry.failureType !== ''
+      ? createElement(
+          'span',
+          {
+            className: `dsh-my-guardian-category dsh-my-guardian-category-${entry.failureType}`,
+            title: entry.failureType,
+          },
+          failureTypeLabel(entry.failureType),
+        )
+      : null,
   )
 }
 
@@ -122,11 +132,26 @@ function RowActions({ entry, busy, onRetry, onRemove }) {
   )
 }
 
+/** 冻结行提示（连败停止自动重试，需手动操作）。 */
+function FrozenHint({ status }) {
+  if (status !== 'frozen') return null
+  return createElement('div', { className: 'dsh-my-guardian-freeze-hint' }, strings.frozenHint())
+}
+
 function EntryRow({ entry, source, onAction }) {
-  const [expanded, setExpanded] = useState(false)
+  // 失败/冻结行默认展开错误详情（用户之前必须手动点开才看得到真正报错）。
+  const [expanded, setExpanded] = useState(
+    () =>
+      typeof entry.lastError === 'string' &&
+      entry.lastError !== '' &&
+      (entry.status === 'failed' || entry.status === 'frozen'),
+  )
   const [confirming, setConfirming] = useState(false)
   const [busy, setBusy] = useState(false)
   const hasError = typeof entry.lastError === 'string' && entry.lastError !== ''
+  const isDepFailure = entry.failureType === 'dependency'
+  const installHint =
+    isDepFailure && typeof entry.installHint === 'string' && entry.installHint !== '' ? entry.installHint : null
 
   const run = (kind) => {
     setBusy(true)
@@ -138,6 +163,15 @@ function EntryRow({ entry, source, onAction }) {
     { className: 'dsh-my-guardian-row' },
     createElement(RowHead, { entry, source }),
     createElement(RowMeta, { entry }),
+    createElement(FrozenHint, { status: entry.status }),
+    installHint
+      ? createElement(
+          'div',
+          { className: 'dsh-my-guardian-install-hint' },
+          createElement('span', { className: 'dsh-my-guardian-install-hint-label' }, strings.installHint()),
+          createElement('code', null, installHint),
+        )
+      : null,
     hasError ? createElement(ErrorToggle, { expanded, onToggle: () => setExpanded(!expanded) }) : null,
     expanded && hasError ? createElement('pre', { className: 'dsh-my-guardian-error-detail' }, entry.lastError) : null,
     confirming

package/lib/parts/styles.part.js

@@ -73,8 +73,22 @@ const STYLES = `
 .dsh-my-guardian-badge-pending { color:var(--dsw-alias-accent); background:color-mix(in srgb, var(--dsw-alias-accent) 12%, transparent); }
 .dsh-my-guardian-badge-failed { color:var(--dsw-alias-state-error-primary); background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 14%, transparent); }
 .dsh-my-guardian-badge-frozen { color:var(--dsw-alias-state-warn-primary); background:color-mix(in srgb, var(--dsw-alias-state-warn-primary) 16%, transparent); }
+/* failure-classification badge chips (issue #86): dependency / code / other */
+.dsh-my-guardian-category { flex:none; display:inline-flex; align-items:center; justify-content:center; height:17px; padding:0 5px; border-radius:4px;
+  font:var(--dsw-font-xxxs-strong-11); }
+.dsh-my-guardian-category-dependency { color:var(--dsw-alias-state-warn-primary); background:color-mix(in srgb, var(--dsw-alias-state-warn-primary) 16%, transparent); }
+.dsh-my-guardian-category-code { color:var(--dsw-alias-state-error-primary); background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 12%, transparent); }
+.dsh-my-guardian-category-other { color:var(--dsw-alias-label-tertiary); background:var(--dsw-alias-interactive-bg-hover); }
+/* install-suggestion line for dependency failures */
+.dsh-my-guardian-install-hint { display:flex; align-items:center; gap:5px; padding:3px 6px; border-radius:6px;
+  background:color-mix(in srgb, var(--dsw-alias-state-warn-primary) 6%, transparent);
+  font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); }
+.dsh-my-guardian-install-hint-label { flex:none; color:var(--dsw-alias-label-tertiary); }
+.dsh-my-guardian-install-hint code { font-family:ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size:var(--dsw-font-xxxs-11);
+  color:var(--dsw-alias-state-success-primary); word-break:break-all; }
 .dsh-my-guardian-row-meta { display:flex; align-items:center; gap:6px; font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); }
 .dsh-my-guardian-attempts { color:var(--dsw-alias-state-error-primary); }
+.dsh-my-guardian-freeze-hint { font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-state-warn-primary); line-height:1.6; }
 .dsh-my-guardian-link { display:inline-flex; align-items:center; gap:3px; padding:0; border:none; background:transparent; cursor:pointer;
   font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary);
   transition:color var(--ds-transition-duration-slow) var(--ds-ease-in-out); }

package/lib/parts/util.part.js

@@ -12,8 +12,8 @@ const strings = {
   safeMode: () => (isZh() ? '安全模式' : 'Safe mode'),
   safeModeDesc: () =>
     isZh()
-      ? '开启后所有候选/已转正插件都不再加载，用于快速恢复环境'
-      : 'Skips every staged/promoted plugin mount — fast recovery',
+      ? '开启后所有候选/已转正插件（候选区 cordis.staged.json 中的条目）都不再加载，用于快速恢复环境。注意：安全模式只作用于启动后挂载的候选插件；若插件直接写进启动名册（cordis.patch.yml / profile），DSH 启动时仍是 all-or-nothing——请把新插件先放进候选区。'
+      : 'Skips every staged/promoted plugin mount — fast recovery. Note: this only covers entries mounted after boot (cordis.staged.json); plugins in the boot roster (cordis.patch.yml / profile) are still all-or-nothing — put new plugins in the staged file first.',
   staged: () => (isZh() ? '候选' : 'staged'),
   promoted: () => (isZh() ? '转正' : 'promoted'),
   entries: () => (isZh() ? '插件条目' : 'Plugin entries'),
@@ -41,6 +41,14 @@ const strings = {
   loading: () => (isZh() ? '加载中…' : 'Loading…'),
   events: () => (isZh() ? '最近事件' : 'Recent events'),
   attempts: (n) => (isZh() ? `失败 ${n} 次` : `failed ×${n}`),
+  frozenHint: () =>
+    isZh()
+      ? '已冻结：连续失败停止自动重试——点击刷新按钮手动重试，或移除该条目'
+      : 'Frozen: auto-retry stopped after repeated failures — retry manually or remove the entry',
+  failureDependency: () => (isZh() ? '依赖缺失' : 'Dependency'),
+  failureCode: () => (isZh() ? '代码错误' : 'Code error'),
+  failureOther: () => (isZh() ? '其他' : 'Other'),
+  installHint: () => (isZh() ? '安装建议' : 'Install'),
 }
 
 // ── api ───────────────────────────────────────────────────────────────
@@ -82,6 +90,20 @@ function statusLabel(status) {
   }
 }
 
+/** Failure-classification badge label (issue #86): dependency / code / other. */
+function failureTypeLabel(type) {
+  switch (type) {
+    case 'dependency':
+      return strings.failureDependency()
+    case 'code':
+      return strings.failureCode()
+    case 'other':
+      return strings.failureOther()
+    default:
+      return type
+  }
+}
+
 // ── event log ─────────────────────────────────────────────────────────
 // Event type → badge label + color variant (mirrors the dfa-op chip style).
 const EVENT_LABELS = {

package/lib/parts/view.part.js

@@ -123,14 +123,19 @@ function EntryList({ rows, onAction }) {
   )
 }
 
-/** Recent guardian event log: badge + key info + time per entry. */
+/** 高频噪音事件：每次启动/热重载都会大量产生，挤掉真正重要的诊断信息。 */
+const EVENT_NOISE = new Set(['entry-init', 'entry-dispose'])
+
+/** Recent guardian event log: badge + key info + time per entry.
+ *  过滤 entry-init/entry-dispose 噪音，优先展示隔离/冻结/更新失败等关键事件。 */
 function EventList({ events }) {
-  if (events.length === 0) return null
+  const important = events.filter((event) => !EVENT_NOISE.has(event.type))
+  if (important.length === 0) return null
   return createElement(
     'div',
     { className: 'dsh-my-guardian-events' },
     createElement('div', { className: 'dsh-my-guardian-events-title' }, icon.clock(14), strings.events()),
-    events.map((event, index) =>
+    important.map((event, index) =>
       createElement(
         'div',
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-my-guardian",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "DSH 插件治理守护：新装/更新插件先进候选区，启动后热挂载——成功转正、失败自动禁用、连续失败冻结，一键安全模式，侧边栏诊断面板。DSH web plugin: staged plugin loading with auto-disable on failure, freeze, safe mode and a sidebar panel.",
   "type": "module",
   "main": "lib/index.js",