dsh-my-guardian 0.3.5 → 0.4.0

package/CHANGELOG.md

@@ -5,14 +5,35 @@ 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.5] - 2026-09-04
+## [0.4.0] - 2026-09-07
+
+### 变更
+
+- feat(observability): #155 插件状态查询聚合——统一 status-query 事件 + /plugin-status API (#170)
+- chore(plugins): #165 清理失效的 dsh.client.inject 声明（13 插件） (#167)
+- feat(guard): #144 启动名册静态预检——startup-issues.json + 面板置顶 + 不阻断启动 (#151)
+
+## [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

@@ -86,6 +86,16 @@ dsh plugin --profile web add link:<仓库路径>/plugins/dsh-my-guardian
 
 失败条目额外带**失败类型徽标**（依赖缺失 / 代码错误 / 其他），依赖缺失时并展示安装建议命令（如 `dsh plugin add dsh-shared`）。
 
+### 启动名册静态预检（issue #144）
+
+候选区只兜住"走候选区"的插件；**直接写进启动名册（`cordis.patch.yml` / profile / bundles）的插件仍由 DSH 启动时 all-or-nothing 加载**。守护在每次启动时对名册做静态预检（不实际加载插件）：
+
+- **包可解析**：名册中 `dsh-*` 插件的包必须在 profile node_modules 中存在
+- **peerDependencies 满足**：复用候选挂载的依赖预检
+- **无重复 entry id**：名册中同一 id 出现多次（加载时 `EntryGroup.update` 会抛 `duplicate loader entry id`）
+
+发现的问题写入 `$DSH_HOME/guardian/startup-issues.json`（原子写，名册健康也写空报告 + 检查时间），面板「最近事件」顶部**置顶**展示启动区问题，每条给出修复命令（`dsh plugin add ...`）与移除提示。**预检失败不阻断启动**——只记录、只告警，最坏情况是为启动失败留下排查记录。
+
 ### 效果截图（真实 DSH 实例验证）
 
 侧边栏"插件守护"诊断面板（独立 3081 端口隔离 DSH 实例实测）：

package/lib/api.js

@@ -191,5 +191,8 @@ function snapshot(shared) {
     staged: stagedList,
     promoted: promotedList,
     events: shared.state.events.slice(-10),
+    // startup-roster pre-check report (issue #144): empty array = healthy
+    startupIssues: Array.isArray(shared.startupIssues) ? shared.startupIssues : [],
+    startupCheckedAt: typeof shared.startupCheckedAt === 'number' ? shared.startupCheckedAt : null,
   }
 }

package/lib/client.js

@@ -122,6 +122,7 @@ const STYLES = `
   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); }
@@ -181,6 +182,33 @@ const STYLES = `
 .dsh-my-guardian-event-message { flex:1; min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap;
   font:var(--dsw-font-xxs-12); color:var(--dsw-alias-label-secondary); }
 .dsh-my-guardian-event-time { flex:none; font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); white-space:nowrap; }
+/* ── startup-roster issues (issue #144): pinned block above the list ────── */
+.dsh-my-guardian-startup-issues { display:flex; flex-direction:column; gap:2px; margin-top:4px; padding:6px 8px; border-radius:8px;
+  border:1px solid color-mix(in srgb, var(--dsw-alias-state-error-primary) 45%, transparent);
+  background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 6%, transparent);
+  animation:dsh-my-guardian-row-in 150ms var(--ds-ease-in-out); }
+.dsh-my-guardian-startup-issues-title { display:flex; align-items:center; gap:5px; padding:0 2px 3px;
+  font:var(--dsw-font-xxs-strong-12); color:var(--dsw-alias-state-error-primary); }
+.dsh-my-guardian-startup-issues-title svg { display:block; flex:none; }
+.dsh-my-guardian-startup-issues-count { display:inline-flex; align-items:center; justify-content:center; min-width:17px; height:17px; padding:0 5px; border-radius:4px;
+  font:var(--dsw-font-xxxs-strong-11); color:var(--dsw-alias-label-primary-foreground); background:var(--dsw-alias-state-error-primary); }
+.dsh-my-guardian-startup-issues-time { flex:1; text-align:right; font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); }
+.dsh-my-guardian-startup-issue { display:flex; flex-direction:column; gap:2px; padding:5px 6px; border-radius:6px;
+  border:1px solid var(--dsw-alias-border-l1); background:transparent; }
+.dsh-my-guardian-startup-issue:hover { background:var(--dsw-alias-interactive-bg-hover); }
+.dsh-my-guardian-startup-issue-head { display:flex; align-items:center; gap:6px; min-width:0; }
+.dsh-my-guardian-startup-issue-name { flex:1; min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap;
+  font:var(--dsw-font-s-strong-14); color:var(--dsw-alias-label-primary); }
+.dsh-my-guardian-startup-issue-badge-unresolvable { color:var(--dsw-alias-state-error-primary); background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 14%, transparent); }
+.dsh-my-guardian-startup-issue-badge-duplicate-id { color:var(--dsw-alias-state-error-primary); background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 14%, transparent); }
+.dsh-my-guardian-startup-issue-badge-dependency { color:var(--dsw-alias-state-warn-primary); background:color-mix(in srgb, var(--dsw-alias-state-warn-primary) 16%, transparent); }
+.dsh-my-guardian-startup-issue-message { font:var(--dsw-font-xxs-12); color:var(--dsw-alias-label-secondary); line-height:1.6; }
+.dsh-my-guardian-startup-issue-line { display:flex; align-items:flex-start; gap:5px; padding:2px 0;
+  font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); line-height:1.6; min-width:0; }
+.dsh-my-guardian-startup-issue-label { flex:none; color:var(--dsw-alias-label-tertiary); }
+.dsh-my-guardian-startup-issue-line 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-startup-issue-remove { min-width:0; word-break:break-all; }
 @keyframes dsh-my-guardian-row-in { from { opacity:0; transform:translateY(1px); } to { opacity:1; transform:none; } }
 @keyframes dsh-my-guardian-spin { to { transform:rotate(360deg); } }
 `
@@ -199,8 +227,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'),
@@ -228,10 +256,21 @@ 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'),
+  // ── startup-roster issues (issue #144) ─────────────────────────────────
+  startupIssues: () => (isZh() ? '启动区问题' : 'Startup roster issues'),
+  startupIssueFix: () => (isZh() ? '修复' : 'Fix'),
+  startupIssueRemove: () => (isZh() ? '移除' : 'Remove'),
+  startupIssueUnresolvable: () => (isZh() ? '包不可解析' : 'Unresolvable'),
+  startupIssueDependency: () => (isZh() ? '依赖缺失' : 'Dependency'),
+  startupIssueDuplicate: () => (isZh() ? '重复 id' : 'Duplicate id'),
 }
 
 // ── api ───────────────────────────────────────────────────────────────
@@ -299,6 +338,7 @@ const EVENT_LABELS = {
   safe: () => (isZh() ? '安全模式' : 'Safe mode'),
   'safe-mode': () => (isZh() ? '安全模式' : 'Safe mode'),
   skip: () => (isZh() ? '跳过' : 'Skipped'),
+  'startup-issue': () => (isZh() ? '启动区问题' : 'Startup issue'),
 }
 
 /** Badge color variant for an event type; unknown types fall back to the
@@ -311,6 +351,7 @@ function eventVariant(type) {
       return 'accent'
     case 'quarantine':
     case 'update-failed':
+    case 'startup-issue':
       return 'danger'
     case 'freeze':
     case 'safe':
@@ -321,6 +362,20 @@ function eventVariant(type) {
   }
 }
 
+/** Startup-issue badge label (issue #144): unresolvable / dependency / dup. */
+function startupIssueLabel(type) {
+  switch (type) {
+    case 'unresolvable':
+      return strings.startupIssueUnresolvable()
+    case 'dependency':
+      return strings.startupIssueDependency()
+    case 'duplicate-id':
+      return strings.startupIssueDuplicate()
+    default:
+      return type
+  }
+}
+
 function eventLabel(type) {
   return (EVENT_LABELS[type] ?? (() => type))()
 }
@@ -784,8 +839,20 @@ 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 !== ''
@@ -803,6 +870,7 @@ 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',
@@ -957,14 +1025,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',
         {
@@ -984,6 +1057,62 @@ function EventList({ events }) {
   )
 }
 
+/** 启动区问题（issue #144）：启动名册静态预检发现的问题条目，置顶展示
+ *  修复命令与移除提示——名册中的坏条目是 all-or-nothing 启动失败的源头。 */
+function StartupIssuesBlock({ issues, checkedAt }) {
+  if (!Array.isArray(issues) || issues.length === 0) return null
+  return createElement(
+    'div',
+    { className: 'dsh-my-guardian-startup-issues' },
+    createElement(
+      'div',
+      { className: 'dsh-my-guardian-startup-issues-title' },
+      icon.alert(14),
+      strings.startupIssues(),
+      createElement('span', { className: 'dsh-my-guardian-startup-issues-count' }, String(issues.length)),
+      typeof checkedAt === 'number' && Number.isFinite(checkedAt)
+        ? createElement('span', { className: 'dsh-my-guardian-startup-issues-time' }, formatTime(checkedAt))
+        : null,
+    ),
+    issues.map((issue, index) =>
+      createElement(
+        'div',
+        { className: 'dsh-my-guardian-startup-issue', key: index },
+        createElement(
+          'div',
+          { className: 'dsh-my-guardian-startup-issue-head' },
+          createElement(
+            'span',
+            {
+              className: `dsh-my-guardian-event-badge dsh-my-guardian-startup-issue-badge-${issue.type}`,
+              title: issue.entryId,
+            },
+            startupIssueLabel(issue.type),
+          ),
+          createElement('span', { className: 'dsh-my-guardian-startup-issue-name' }, issue.name),
+        ),
+        createElement('div', { className: 'dsh-my-guardian-startup-issue-message' }, issue.message),
+        typeof issue.fix === 'string' && issue.fix !== ''
+          ? createElement(
+              'div',
+              { className: 'dsh-my-guardian-startup-issue-line' },
+              createElement('span', { className: 'dsh-my-guardian-startup-issue-label' }, strings.startupIssueFix()),
+              createElement('code', null, issue.fix),
+            )
+          : null,
+        typeof issue.remove === 'string' && issue.remove !== ''
+          ? createElement(
+              'div',
+              { className: 'dsh-my-guardian-startup-issue-line' },
+              createElement('span', { className: 'dsh-my-guardian-startup-issue-label' }, strings.startupIssueRemove()),
+              createElement('span', { className: 'dsh-my-guardian-startup-issue-remove' }, issue.remove),
+            )
+          : null,
+      ),
+    ),
+  )
+}
+
 function GuardianView({ visible }) {
   const { state, loadFailed, reload, onAction, onSafeMode } = useGuardianState(visible)
 
@@ -1005,6 +1134,10 @@ function GuardianView({ visible }) {
     'div',
     { className: 'dsh-my-guardian-root' },
     createElement(SafeModeBar, { safeMode: state.safeMode, onSafeMode }),
+    createElement(StartupIssuesBlock, {
+      issues: state.startupIssues,
+      checkedAt: state.startupCheckedAt,
+    }),
     loadFailed
       ? createElement(
           'div',

package/lib/dep-precheck.js

@@ -14,7 +14,9 @@ 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) {
+// Exported for the startup-roster pre-check (issue #144): resolvability of a
+// roster plugin's own package is verified before peer dependencies.
+export function findModuleDir(nmRoot, packageName) {
   const dir = join(nmRoot, packageName)
   return existsSync(join(dir, 'package.json')) ? dir : null
 }

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/index.js

@@ -37,6 +37,7 @@ import { createPersister, createState } from './state.js'
 import { findRootTree, createMountOps, initialScan } from './mount.js'
 import { createApi } from './api.js'
 import { attachEventListeners, logEvent } from './events.js'
+import { runStartupCheck } from './startup-check.js'
 
 export const name = 'dsh-my-guardian'
 
@@ -69,6 +70,7 @@ function applyInner(ctx) {
   scheduleInitialScan(ctx, shared)
   startWatchers(ctx, shared)
   registerTeardown(ctx, shared)
+  registerStatusQuery(ctx, shared)
 }
 
 /** Mutable per-instance runtime context shared by every sub-module. */
@@ -84,6 +86,9 @@ function createShared({ tree, profileDir }) {
     tree,
     profileDir,
     stagedFile: join(profileDir, 'cordis.staged.json'),
+    // startup-roster pre-check (issue #144): filled by runStartupCheck
+    startupIssues: [],
+    startupCheckedAt: null,
   }
 }
 
@@ -99,7 +104,14 @@ function wireServices(ctx, shared) {
 // ── run after boot settles ──────────────────────────────────────────────
 function scheduleInitialScan(ctx, shared) {
   void Promise.resolve().then(() => {
-    initialScan(shared).catch((error) => {
+    // Startup-roster static pre-check (issue #144): best-effort, MUST never
+    // block or break the boot — a pre-check failure only records a report.
+    void runStartupCheck(ctx, shared).catch((error) => {
+      ctx.logger?.warn(
+        `[dsh-my-guardian] startup pre-check failed (recorded only): ${error instanceof Error ? error.message : String(error)}`,
+      )
+    })
+    void initialScan(shared).catch((error) => {
       // the scan must never take the process down
       ctx.logger?.warn(
         `[dsh-my-guardian] initial scan failed: ${error instanceof Error ? error.message : String(error)}`,
@@ -126,6 +138,28 @@ function startWatchers(ctx, shared) {
   }, POLL_MS)
 }
 
+/** 插件状态查询（#155 聚合层）：返回 guardian 加载状态 + 最近事件。 */
+function registerStatusQuery(ctx, shared) {
+  ctx.on('plugin:status-query', ({ plugin }) => {
+    if (plugin !== 'dsh-my-guardian') return undefined
+    const lastActions = (shared.state.events ?? []).slice(-5).map((e) => ({
+      time: e.time ?? e.timestamp ?? Date.now(),
+      type: e.type ?? 'event',
+      detail: e.message ?? e.detail ?? '',
+    }))
+    return {
+      ok: true,
+      value: {
+        plugin: 'dsh-my-guardian',
+        config: { keys: ['safeMode', 'stagedFile'] },
+        running: shared.ready,
+        stats: { mounted: shared.mounted.size, safeMode: shared.state.safeMode === true },
+        lastActions,
+      },
+    }
+  })
+}
+
 /** teardown: unmount everything the guardian mounted, then persist. */
 function registerTeardown(ctx, shared) {
   ctx.effect(

package/lib/parts/row.part.js

@@ -132,8 +132,20 @@ 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 !== ''
@@ -151,6 +163,7 @@ 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',

package/lib/parts/styles.part.js

@@ -88,6 +88,7 @@ const STYLES = `
   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); }
@@ -147,6 +148,33 @@ const STYLES = `
 .dsh-my-guardian-event-message { flex:1; min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap;
   font:var(--dsw-font-xxs-12); color:var(--dsw-alias-label-secondary); }
 .dsh-my-guardian-event-time { flex:none; font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); white-space:nowrap; }
+/* ── startup-roster issues (issue #144): pinned block above the list ────── */
+.dsh-my-guardian-startup-issues { display:flex; flex-direction:column; gap:2px; margin-top:4px; padding:6px 8px; border-radius:8px;
+  border:1px solid color-mix(in srgb, var(--dsw-alias-state-error-primary) 45%, transparent);
+  background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 6%, transparent);
+  animation:dsh-my-guardian-row-in 150ms var(--ds-ease-in-out); }
+.dsh-my-guardian-startup-issues-title { display:flex; align-items:center; gap:5px; padding:0 2px 3px;
+  font:var(--dsw-font-xxs-strong-12); color:var(--dsw-alias-state-error-primary); }
+.dsh-my-guardian-startup-issues-title svg { display:block; flex:none; }
+.dsh-my-guardian-startup-issues-count { display:inline-flex; align-items:center; justify-content:center; min-width:17px; height:17px; padding:0 5px; border-radius:4px;
+  font:var(--dsw-font-xxxs-strong-11); color:var(--dsw-alias-label-primary-foreground); background:var(--dsw-alias-state-error-primary); }
+.dsh-my-guardian-startup-issues-time { flex:1; text-align:right; font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); }
+.dsh-my-guardian-startup-issue { display:flex; flex-direction:column; gap:2px; padding:5px 6px; border-radius:6px;
+  border:1px solid var(--dsw-alias-border-l1); background:transparent; }
+.dsh-my-guardian-startup-issue:hover { background:var(--dsw-alias-interactive-bg-hover); }
+.dsh-my-guardian-startup-issue-head { display:flex; align-items:center; gap:6px; min-width:0; }
+.dsh-my-guardian-startup-issue-name { flex:1; min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap;
+  font:var(--dsw-font-s-strong-14); color:var(--dsw-alias-label-primary); }
+.dsh-my-guardian-startup-issue-badge-unresolvable { color:var(--dsw-alias-state-error-primary); background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 14%, transparent); }
+.dsh-my-guardian-startup-issue-badge-duplicate-id { color:var(--dsw-alias-state-error-primary); background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 14%, transparent); }
+.dsh-my-guardian-startup-issue-badge-dependency { color:var(--dsw-alias-state-warn-primary); background:color-mix(in srgb, var(--dsw-alias-state-warn-primary) 16%, transparent); }
+.dsh-my-guardian-startup-issue-message { font:var(--dsw-font-xxs-12); color:var(--dsw-alias-label-secondary); line-height:1.6; }
+.dsh-my-guardian-startup-issue-line { display:flex; align-items:flex-start; gap:5px; padding:2px 0;
+  font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); line-height:1.6; min-width:0; }
+.dsh-my-guardian-startup-issue-label { flex:none; color:var(--dsw-alias-label-tertiary); }
+.dsh-my-guardian-startup-issue-line 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-startup-issue-remove { min-width:0; word-break:break-all; }
 @keyframes dsh-my-guardian-row-in { from { opacity:0; transform:translateY(1px); } to { opacity:1; transform:none; } }
 @keyframes dsh-my-guardian-spin { to { transform:rotate(360deg); } }
 `

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,10 +41,21 @@ 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'),
+  // ── startup-roster issues (issue #144) ─────────────────────────────────
+  startupIssues: () => (isZh() ? '启动区问题' : 'Startup roster issues'),
+  startupIssueFix: () => (isZh() ? '修复' : 'Fix'),
+  startupIssueRemove: () => (isZh() ? '移除' : 'Remove'),
+  startupIssueUnresolvable: () => (isZh() ? '包不可解析' : 'Unresolvable'),
+  startupIssueDependency: () => (isZh() ? '依赖缺失' : 'Dependency'),
+  startupIssueDuplicate: () => (isZh() ? '重复 id' : 'Duplicate id'),
 }
 
 // ── api ───────────────────────────────────────────────────────────────
@@ -112,6 +123,7 @@ const EVENT_LABELS = {
   safe: () => (isZh() ? '安全模式' : 'Safe mode'),
   'safe-mode': () => (isZh() ? '安全模式' : 'Safe mode'),
   skip: () => (isZh() ? '跳过' : 'Skipped'),
+  'startup-issue': () => (isZh() ? '启动区问题' : 'Startup issue'),
 }
 
 /** Badge color variant for an event type; unknown types fall back to the
@@ -124,6 +136,7 @@ function eventVariant(type) {
       return 'accent'
     case 'quarantine':
     case 'update-failed':
+    case 'startup-issue':
       return 'danger'
     case 'freeze':
     case 'safe':
@@ -134,6 +147,20 @@ function eventVariant(type) {
   }
 }
 
+/** Startup-issue badge label (issue #144): unresolvable / dependency / dup. */
+function startupIssueLabel(type) {
+  switch (type) {
+    case 'unresolvable':
+      return strings.startupIssueUnresolvable()
+    case 'dependency':
+      return strings.startupIssueDependency()
+    case 'duplicate-id':
+      return strings.startupIssueDuplicate()
+    default:
+      return type
+  }
+}
+
 function eventLabel(type) {
   return (EVENT_LABELS[type] ?? (() => type))()
 }

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',
         {
@@ -150,6 +155,62 @@ function EventList({ events }) {
   )
 }
 
+/** 启动区问题（issue #144）：启动名册静态预检发现的问题条目，置顶展示
+ *  修复命令与移除提示——名册中的坏条目是 all-or-nothing 启动失败的源头。 */
+function StartupIssuesBlock({ issues, checkedAt }) {
+  if (!Array.isArray(issues) || issues.length === 0) return null
+  return createElement(
+    'div',
+    { className: 'dsh-my-guardian-startup-issues' },
+    createElement(
+      'div',
+      { className: 'dsh-my-guardian-startup-issues-title' },
+      icon.alert(14),
+      strings.startupIssues(),
+      createElement('span', { className: 'dsh-my-guardian-startup-issues-count' }, String(issues.length)),
+      typeof checkedAt === 'number' && Number.isFinite(checkedAt)
+        ? createElement('span', { className: 'dsh-my-guardian-startup-issues-time' }, formatTime(checkedAt))
+        : null,
+    ),
+    issues.map((issue, index) =>
+      createElement(
+        'div',
+        { className: 'dsh-my-guardian-startup-issue', key: index },
+        createElement(
+          'div',
+          { className: 'dsh-my-guardian-startup-issue-head' },
+          createElement(
+            'span',
+            {
+              className: `dsh-my-guardian-event-badge dsh-my-guardian-startup-issue-badge-${issue.type}`,
+              title: issue.entryId,
+            },
+            startupIssueLabel(issue.type),
+          ),
+          createElement('span', { className: 'dsh-my-guardian-startup-issue-name' }, issue.name),
+        ),
+        createElement('div', { className: 'dsh-my-guardian-startup-issue-message' }, issue.message),
+        typeof issue.fix === 'string' && issue.fix !== ''
+          ? createElement(
+              'div',
+              { className: 'dsh-my-guardian-startup-issue-line' },
+              createElement('span', { className: 'dsh-my-guardian-startup-issue-label' }, strings.startupIssueFix()),
+              createElement('code', null, issue.fix),
+            )
+          : null,
+        typeof issue.remove === 'string' && issue.remove !== ''
+          ? createElement(
+              'div',
+              { className: 'dsh-my-guardian-startup-issue-line' },
+              createElement('span', { className: 'dsh-my-guardian-startup-issue-label' }, strings.startupIssueRemove()),
+              createElement('span', { className: 'dsh-my-guardian-startup-issue-remove' }, issue.remove),
+            )
+          : null,
+      ),
+    ),
+  )
+}
+
 function GuardianView({ visible }) {
   const { state, loadFailed, reload, onAction, onSafeMode } = useGuardianState(visible)
 
@@ -171,6 +232,10 @@ function GuardianView({ visible }) {
     'div',
     { className: 'dsh-my-guardian-root' },
     createElement(SafeModeBar, { safeMode: state.safeMode, onSafeMode }),
+    createElement(StartupIssuesBlock, {
+      issues: state.startupIssues,
+      checkedAt: state.startupCheckedAt,
+    }),
     loadFailed
       ? createElement(
           'div',

package/lib/startup-check.js

@@ -0,0 +1,228 @@
+/**
+ * dsh-my-guardian — startup-roster static pre-check (issue #144).
+ *
+ * DSH boots its plugin roster all-or-nothing: any roster row (cordis.patch.yml /
+ * profile / bundles — everything merged into the loader's include tree) that
+ * fails to import, throws during apply, or stays pending takes the whole
+ * `dsh web` process down, and the guardian (itself a roster row) has no
+ * chance to quarantine anything after the fact. This module closes that gap
+ * with a STATIC, best-effort pre-flight that runs right after the guardian's
+ * own apply:
+ *
+ *   - package resolvability: every dsh-* roster entry's package must exist
+ *     under the profile node_modules — an unresolvable package always fails
+ *     the import stage (assertEntriesLoaded throws in dsh-app-boot)
+ *   - peer dependencies: reuse the staged-mount pre-check (dep-precheck.js)
+ *     — missing/out-of-range peers surface at boot as module-resolution
+ *     failures, so they are flagged before the next restart hits them
+ *   - duplicate entry ids: EntryGroup.update in cordis-plugin-loader throws
+ *     "duplicate loader entry id" when a group config lists the same id
+ *     twice — a guaranteed boot failure worth flagging up front
+ *
+ * The report is written to $DSH_HOME/guardian/startup-issues.json so it
+ * survives a broken boot: applies run in parallel with roster imports, so the
+ * guardian can usually record the report before assertEntriesActivated
+ * rejects the boot.
+ *
+ * Guardrails (watchdog self-protection, R15): the pre-check itself NEVER
+ * fails the boot — every step is wrapped, failures only log; a broken loader
+ * tree simply yields no roster and an empty report.
+ */
+import { join } from 'node:path'
+import { findModuleDir, checkPeerDependencies, buildDependencyMessage } from './dep-precheck.js'
+import { writeStartupIssuesFile } from './state.js'
+import { logEvent } from './events.js'
+
+/** Profile-node_modules root used for roster resolvability checks. */
+function profileNodeModules(profileDir) {
+  return join(profileDir, 'node_modules')
+}
+
+/** Collect every entry of a tree, tolerantly: entries() when present (real
+ *  IncludeTree includes nested subtrees), otherwise a plain store walk
+ *  (mocked trees in tests). Never throws — a broken tree yields []. */
+export function collectTreeEntries(tree) {
+  if (tree === null || typeof tree !== 'object') return []
+  if (typeof tree.entries === 'function') {
+    try {
+      const out = []
+      for (const entry of tree.entries()) {
+        if (entry !== null && typeof entry === 'object') out.push(entry)
+      }
+      return out
+    } catch {
+      // fall through to the store walk
+    }
+  }
+  const store = tree.store
+  if (store === null || typeof store !== 'object') return []
+  return Object.values(store).filter((entry) => entry !== null && typeof entry === 'object')
+}
+
+/** Read one string field from an entry's options (tolerant of odd shapes). */
+function readOptionString(options, key) {
+  return options !== null && typeof options === 'object' && typeof options[key] === 'string' && options[key] !== ''
+    ? options[key]
+    : ''
+}
+
+/** Extract { id, name } from an entry, with safe fallbacks (entry.id getter
+ *  may throw on partially-constructed entries — never let it break the boot). */
+export function entryLabels(entry) {
+  const options = entry !== null && typeof entry === 'object' ? entry.options : null
+  let id = readOptionString(options, 'id')
+  if (id === '') id = entryIdGetterOf(entry)
+  const name = readOptionString(options, 'name')
+  return { id, name: name !== '' ? name : id !== '' ? id : '?' }
+}
+
+/** entry.id getter fallback (wrapped: it may throw on partial entries). */
+function entryIdGetterOf(entry) {
+  try {
+    const entryId = entry?.id
+    return typeof entryId === 'string' && entryId !== '' ? entryId : ''
+  } catch {
+    return ''
+  }
+}
+
+/** True when an entry is disabled (explicit row or via options) — disabled
+ *  rows are exempt from the boot audits and from this pre-check. */
+export function isDisabledEntry(entry) {
+  if (entry === null || typeof entry !== 'object') return false
+  if (entry.disabled === true) return true
+  const options = entry.options
+  return options !== null && typeof options === 'object' && options.disabled === true
+}
+
+/** Removal hint shared by every issue kind (guardian never rewrites YAML). */
+const REMOVE_HINT = '从启动名册（cordis.patch.yml / profile）中删除该条目行，或标记 disabled: true 暂缓加载'
+
+/** Build an unresolvable-package issue (import stage would fail). */
+function unresolvedIssue(id, name) {
+  return {
+    type: 'unresolvable',
+    entryId: id,
+    name,
+    message: `插件包 ${name} 无法解析（profile node_modules 中不存在），启动 import 将失败`,
+    fix: `dsh plugin add ${name}`,
+    remove: REMOVE_HINT,
+  }
+}
+
+/** Build a dependency issue reusing the staged-mount pre-check result. */
+function dependencyIssue(id, name, precheck) {
+  return {
+    type: 'dependency',
+    entryId: id,
+    name,
+    message: buildDependencyMessage(precheck),
+    missingDeps: [...precheck.missing, ...precheck.mismatched.map((item) => item.name)],
+    installHint: precheck.suggestions[0] ?? null,
+    fix: precheck.suggestions[0] ?? `dsh plugin add ${name}`,
+    remove: REMOVE_HINT,
+  }
+}
+
+/** Build a duplicate-id issue for one id seen more than once. */
+function duplicateIssue(id, names) {
+  return {
+    type: 'duplicate-id',
+    entryId: id,
+    name: names[0] ?? id,
+    message: `名册存在重复条目 id "${id}"（${names.length} 处：${names.join('、')}），加载时将抛 duplicate loader entry id`,
+    fix: null,
+    remove: '从名册中删除重复的条目行（每个 id 保留一条）',
+  }
+}
+
+/** Record an entry under its id for the duplicate-id sweep. */
+function addSeen(map, id, item) {
+  const group = map.get(id)
+  if (group === undefined) map.set(id, [item])
+  else group.push(item)
+}
+
+/** Static checks for one roster row: resolvability + peers (dsh-* only). */
+function checkPluginItem(issues, item, nmRoot, profileDir) {
+  const id = typeof item.id === 'string' ? item.id : ''
+  const name = typeof item.name === 'string' ? item.name : ''
+  const label = name !== '' ? name : id
+  if (label === '' || !label.startsWith('dsh-')) return
+  const pluginDir = findModuleDir(nmRoot, label)
+  if (pluginDir === null) {
+    issues.push(unresolvedIssue(id, label))
+    return
+  }
+  const precheck = checkPeerDependencies({ profileDir, pluginName: label })
+  if (!precheck.ok) issues.push(dependencyIssue(id, label, precheck))
+}
+
+/** Append one duplicate-id issue per id seen in more than one roster row. */
+function collectDuplicateIssues(issues, byId) {
+  for (const [id, group] of byId) {
+    if (group.length < 2) continue
+    issues.push(
+      duplicateIssue(
+        id,
+        group.map((item) => item.name ?? item.id ?? '?'),
+      ),
+    )
+  }
+}
+
+/**
+ * Core static pre-check over one roster's normalized entries.
+ * entries: [{ id, name, disabled }] (see normalizeRoster). Checks dsh-*
+ * plugins for package resolvability + peer deps, and the whole roster for
+ * duplicate ids. Never throws — returns { issues }.
+ */
+export function checkStartupRoster({ entries, profileDir }) {
+  const issues = []
+  const roster = Array.isArray(entries) ? entries : []
+  const nmRoot = profileNodeModules(profileDir)
+  const byId = new Map()
+  for (const item of roster) {
+    if (item === null || typeof item !== 'object') continue
+    const id = typeof item.id === 'string' ? item.id : ''
+    if (id !== '') addSeen(byId, id, item)
+    checkPluginItem(issues, item, nmRoot, profileDir)
+  }
+  collectDuplicateIssues(issues, byId)
+  return { issues }
+}
+
+/** Normalize raw tree entries into { id, name, disabled } roster rows. */
+export function normalizeRoster(entries) {
+  return entries.map((entry) => {
+    const labels = entryLabels(entry)
+    return { id: labels.id, name: labels.name, disabled: isDisabledEntry(entry) }
+  })
+}
+
+/**
+ * Full startup pre-flight for one guardian instance: collect the roster from
+ * the include tree, statically check it, persist the report and log an event.
+ * Never throws — every failure degrades to a warn log (boot must continue).
+ */
+export async function runStartupCheck(ctx, shared) {
+  const entries = collectTreeEntries(shared.tree)
+  const roster = normalizeRoster(entries).filter((item) => !item.disabled)
+  const { issues } = checkStartupRoster({ entries: roster, profileDir: shared.profileDir })
+  const checkedAt = Date.now()
+  await writeStartupIssuesFile({ version: 1, checkedAt, profileDir: shared.profileDir, issues })
+  shared.startupIssues = issues
+  shared.startupCheckedAt = checkedAt
+  if (issues.length > 0) {
+    const names = [...new Set(issues.map((issue) => issue.name))].slice(0, 3).join('、')
+    logEvent(
+      shared,
+      'startup-issue',
+      `启动名册静态预检发现 ${issues.length} 个问题（${names}…）— 详见 guardian/startup-issues.json`,
+    )
+    shared.persistSoon()
+    ctx.logger?.warn(
+      `[dsh-my-guardian] startup roster pre-check: ${issues.length} issue(s) — see $DSH_HOME/guardian/startup-issues.json`,
+    )
+  }
+}

package/lib/state.js

@@ -32,6 +32,26 @@ function guardianDir() {
   return join(homedir(), '.dsh', 'guardian')
 }
 
+/**
+ * Persist the startup-roster pre-check report (issue #144) atomically at
+ * $DSH_HOME/guardian/startup-issues.json. The report is written even when
+ * the roster is healthy (empty issues + checkedAt) so the file doubles as a
+ * "last checked" marker; missing/corrupt file only means "never written".
+ * Never throws to callers — the guardian must not take the process down.
+ */
+export async function writeStartupIssuesFile(payload) {
+  const dir = guardianDir()
+  const file = join(dir, 'startup-issues.json')
+  const tmp = `${file}.tmp-${uniqueSuffix()}`
+  try {
+    await mkdir(dir, { recursive: true })
+    await writeFile(tmp, JSON.stringify(payload), 'utf8')
+    await rename(tmp, file)
+  } catch {
+    // the report is diagnostic-only: a write failure must not break boot
+  }
+}
+
 /** Empty state document. */
 export function createState() {
   return { version: 1, safeMode: false, staged: {}, promoted: {}, events: [] }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-my-guardian",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "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",
@@ -36,10 +36,7 @@
       "patch": "./cordis.patch.yml"
     },
     "client": {
-      "platform": "web",
-      "inject": [
-        "@deepseek-ai/dsh-client-runtime"
-      ]
+      "platform": "web"
     }
   },
   "peerDependencies": {