@hyzyn/dsh-safe 0.3.2 → 0.5.0

package/README.en.md

@@ -44,8 +44,10 @@ Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broke
 | `dsh-safe <dsh args…>` | wrap and run dsh (swap `dsh` for `dsh-safe`) |
 | `dsh-safe -u [update options] [dsh args…]` | upgrade dsh and dsh-safe itself first (skip if latest), then boot in wrap mode; `--update` is an alias |
 | `dsh-safe update [options]` | upgrade only, no boot — options below |
-| `dsh-safe list [--profile <name>]` | show quarantined plugins (defaults to all profiles) |
-| `dsh-safe restore --profile <name> (--id <id> \| --all) [--dry-run]` | re-enable auto-disabled plugins (after a fixed plugin upgrade) |
+| `dsh-safe list [--profile <name>] [--json]` | show quarantined plugins (`--json` outputs structured JSON; defaults to all profiles) |
+| `dsh-safe doctor` | environment check: versions, DSH_HOME, profiles, ledger, patch health |
+| `dsh-safe restore [--profile <name>] (--id <id> \| --all) [--dry-run]` | re-enable auto-disabled plugins (omit `--profile` to cover every profile in the ledger) |
+| `dsh-safe explain [--file <path>]` | interpret a failed-boot stderr with AI (read-only, needs `DSH_SAFE_AI_KEY`) |
 | `dsh-safe help` (`-h` / `--help`) | show help |
 | `dsh-safe --version` (`-V`) | show version |
 
@@ -58,6 +60,7 @@ Every short flag has an equivalent long form (`-u` = `--update`, `-y` = `--yes`,
 | `--dry-run` | Parse and report only; no files are modified |
 | `--max-retries <n>` | Max startup retries after an auto-quarantine (default 2; `0` means pass through without quarantining) |
 | `--allow-first-party` | Allow auto-disabling first-party `@deepseek-ai/*` plugins (skipped by default; handle manually) |
+| `--exclude <id-or-pkg>` | Quarantine exclusion list (repeatable) — matched rows are never auto-disabled; can also live in `config.json` |
 
 ### update / -u options (after `-u` or `update`; wrapper flags before the dsh args still apply)
 
@@ -67,6 +70,7 @@ Every short flag has an equivalent long form (`-u` = `--update`, `-y` = `--yes`,
 | `--to <version>` | Target dsh version, also how you roll back (explicit downgrades allowed); dsh-safe itself always upgrades to the latest |
 | `--self` | Update dsh-safe itself only; dsh and quarantine state untouched |
 | `--no-restore` | Do not auto-restore quarantined plugins after upgrading dsh |
+| `--no-verify` | Skip the post-upgrade parser self-check (boots the new dsh with a throwaway profile to confirm error recognition still works) |
 | `--pm <npm\|pnpm>` | Force the package manager (auto-detected by default) |
 
 ### Environment variables
@@ -76,6 +80,10 @@ Every short flag has an equivalent long form (`-u` = `--update`, `-y` = `--yes`,
 | `DSH_SAFE_LANG=zh\|en` | Force message language (defaults to `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE`) |
 | `DSH_SAFE_NO_UPDATE_CHECK=1` | Disable the at-most-daily dsh-safe new-version notice on boot |
 | `DSH_HOME` | dsh home directory (dsh's own variable; the quarantine ledger and patch paths follow it) |
+| `DSH_SAFE_AI_KEY` | AI feature key (unset = AI disabled entirely); defaults to DeepSeek |
+| `DSH_SAFE_AI_BASE_URL` | AI endpoint (OpenAI-compatible), default `https://api.deepseek.com` |
+| `DSH_SAFE_AI_MODEL` | AI model, default `deepseek-chat` |
+| `DSH_SAFE_AI_RECOVER=1` | enable AI fallback when regex signatures can't identify the broken plugin (results go through the same quarantine pipeline) |
 
 How upgrading works: `dsh-safe update` auto-detects the dsh package name and install method (npm / pnpm global installs), compares against the latest version and runs the upgrade for you, then automatically restores all quarantined plugins — any still incompatible under the new dsh will be auto-quarantined again on the next start. For daily use, just make `dsh-safe -u web` your start command: boots immediately when dsh is already latest (one version check), upgrades + restores first when an update is available, and only warns (still boots) if the update check itself fails. `-u` accepts update options (e.g. `-u -y web`) and wrapper flags (e.g. `-u --max-retries 0 web`).
 
@@ -86,6 +94,14 @@ How upgrading works: `dsh-safe update` auto-detects the dsh package name and ins
 3. **Managed block writing**: it appends a marker-commented managed block at the end of the matching patch file (same convention as `dsh-mcp-config managed`), setting matched rows to `disabled: true`. Existing user content and comments are preserved; a fresh profile's `[]` template is correctly replaced with a block sequence.
 4. **Ledger & restore**: quarantine records live in `$DSH_HOME/dsh-safe/quarantine.json`. Once a plugin upgrade fixes the issue, `dsh-safe restore --profile web --all` removes the managed block and re-mounts the plugin (hot-applied for profiles with `patchReload: live`).
 
+### AI Capabilities (optional)
+
+Enabled by setting `DSH_SAFE_AI_KEY` (defaults to DeepSeek; OpenAI-compatible — swap providers via `DSH_SAFE_AI_BASE_URL` / `DSH_SAFE_AI_MODEL`):
+
+- **`dsh-safe explain [--file <path>]`**: feed it a failed-boot stderr (stdin or file) and get a plain-language interpretation plus fix suggestions. Strictly read-only.
+- **AI fallback identification** (`DSH_SAFE_AI_RECOVER=1`): when the regex signatures can't identify the broken plugin (e.g. after a dsh upgrade changes formats), the AI picks the culprit from the stderr — **its output must pass the exact same validation pipeline** (match against real patch rows, first-party protection, dry-run preview); unmatched picks are passed through as before. Only invoked on startup failure.
+- Privacy: home paths are redacted to `~` before sending; any AI failure degrades silently.
+
 ## Safety Boundaries
 
 - **First-party protection**: rows of `@deepseek-ai/*` plugins are skipped by default (disabling plugins like `dsh-web-app` would strip dsh of its core capabilities); pass `--allow-first-party` to touch them.
@@ -98,7 +114,7 @@ How upgrading works: `dsh-safe update` auto-detects the dsh package name and ins
 - If the patch file itself fails YAML parsing (e.g. broken by hand-editing), plugins cannot be identified and the failure is passed through.
 - Rows inserted via `--patch` overlay layers are not part of the mapping (only the profile patch, the home patch and bundle patches are scanned).
 - To capture stderr, the wrapper pipes dsh's stderr (content is still echoed to the terminal in real time); stdout/stdin pass through unaffected.
-- Match patterns target the dsh 0.1.x error formats; a major dsh upgrade that changes them requires updating the parser.
+- Match patterns target the dsh 0.1.x error formats; a major dsh upgrade that changes them requires updating the parser. Mitigation: after update/-u upgrades dsh it runs a parser self-check — boots the new dsh with a throwaway profile and confirms failures are still recognized, warning right away on mismatch (`--no-verify` skips it).
 - Windows is best-effort: update / --self / list / restore are adapted (.cmd shim parsing, shelled npm/pnpm invocations); the wrapped boot resolves the node entry embedded in dsh's .cmd/.ps1 shim on PATH and spawns `node <entry>` directly (.exe runs as-is, unparseable shims fall back to a shelled spawn), sidestepping Node's ban on spawning .cmd files. Not yet verified end-to-end on a real Windows machine — feedback welcome.
 
 ## Development

package/README.md

@@ -44,8 +44,10 @@ Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broke
 | `dsh-safe <dsh 参数…>` | 包装运行 dsh（把平时的 `dsh` 换成 `dsh-safe`） |
 | `dsh-safe -u [update 选项] [dsh 参数…]` | 先升级 dsh 与 dsh-safe 自身（已最新则跳过），再按包装模式启动；`--update` 等价 |
 | `dsh-safe update [选项]` | 只升级不启动，选项见下 |
-| `dsh-safe list [--profile <名>]` | 查看隔离名单（缺省列出全部 profile） |
-| `dsh-safe restore --profile <名> (--id <id> \| --all) [--dry-run]` | 恢复被自动禁用的插件（升级修复后使用） |
+| `dsh-safe list [--profile <名>] [--json]` | 查看隔离名单（`--json` 输出结构化 JSON，缺省全部 profile） |
+| `dsh-safe doctor` | 环境体检：版本、DSH_HOME、profiles、台账、各 patch 健康度 |
+| `dsh-safe restore [--profile <名>] (--id <id> \| --all) [--dry-run]` | 恢复被自动禁用的插件（省略 `--profile` 时遍历台账全部 profile） |
+| `dsh-safe explain [--file <路径>]` | 用 AI 解读一段启动失败 stderr（纯只读，需 `DSH_SAFE_AI_KEY`） |
 | `dsh-safe help`（`-h` / `--help`） | 显示帮助 |
 | `dsh-safe --version`（`-V`） | 显示版本 |
 
@@ -58,6 +60,7 @@ Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broke
 | `--dry-run` | 只解析与报告，不修改任何文件 |
 | `--max-retries <n>` | 自动隔离后最多重试启动的次数（默认 2；`0` 表示不隔离只透传） |
 | `--allow-first-party` | 允许自动禁用 `@deepseek-ai/*` 第一方插件（默认跳过，需手动处理） |
+| `--exclude <id或包名>` | 隔离豁免名单（可重复），命中的行永不自动禁用；也可写进 `config.json` |
 
 ### update / -u 选项（写在 `-u` 或 `update` 之后；其前的包装旗标照常生效）
 
@@ -67,6 +70,7 @@ Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broke
 | `--to <版本>` | 指定 dsh 的目标版本，也是回滚方式（显式允许降级）；dsh-safe 自身始终升到最新 |
 | `--self` | 只更新 dsh-safe 自身，不动 dsh 与隔离状态 |
 | `--no-restore` | 升级 dsh 后不自动恢复被隔离的插件 |
+| `--no-verify` | 跳过升级后的解析器自校验（临时 profile 试启新版 dsh，验证报错识别仍有效） |
 | `--pm <npm\|pnpm>` | 强制指定包管理器（缺省自动探测） |
 
 ### 环境变量
@@ -76,6 +80,10 @@ Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broke
 | `DSH_SAFE_LANG=zh\|en` | 强制提示信息语言（缺省跟随 `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE`） |
 | `DSH_SAFE_NO_UPDATE_CHECK=1` | 关闭启动时每天最多一次的 dsh-safe 新版提示 |
 | `DSH_HOME` | dsh 的 home 目录（dsh 自己的环境变量；隔离台账与各 patch 路径随之） |
+| `DSH_SAFE_AI_KEY` | AI 功能 key（未设置 = AI 整体禁用）；默认对接 DeepSeek |
+| `DSH_SAFE_AI_BASE_URL` | AI 接口地址（OpenAI 兼容），默认 `https://api.deepseek.com` |
+| `DSH_SAFE_AI_MODEL` | AI 模型，默认 `deepseek-chat` |
+| `DSH_SAFE_AI_RECOVER=1` | 正则识别不出坏插件时启用 AI 兜底（结果仍走同一隔离管线） |
 
 升级行为：`dsh-safe update` 自动探测 dsh 的包名与安装方式（npm / pnpm 全局安装）、对比最新版本后代跑升级，完成后自动恢复所有被隔离的插件——新 dsh 下仍不兼容的会在下次启动时再次被自动隔离。日常把 `dsh-safe -u web` 当启动命令即可：dsh 已是最新时直接启动（仅一次版本检查），有更新时先升级并恢复隔离再启动，更新检查失败只告警、照常启动。`-u` 后可接 update 的选项（如 `-u -y web`）与包装旗标（如 `-u --max-retries 0 web`）。
 
@@ -86,6 +94,14 @@ Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broke
 3. **写入托管区块**：在对应 patch 文件末尾追加带标记注释的区块（与 `dsh-mcp-config managed` 同款约定），把命中的行置为 `disabled: true`。用户已有内容与注释原样保留；全新 profile 的 `[]` 模板会被正确替换成块序列。
 4. **台账与恢复**：隔离记录存 `$DSH_HOME/dsh-safe/quarantine.json`。插件升级修复后用 `dsh-safe restore --profile web --all` 摘除区块恢复挂载（`patchReload: live` 的 profile 热生效）。
 
+### AI 能力（可选）
+
+设置 `DSH_SAFE_AI_KEY` 后启用（默认对接 DeepSeek，OpenAI 兼容接口，可用 `DSH_SAFE_AI_BASE_URL` / `DSH_SAFE_AI_MODEL` 换任何兼容服务）：
+
+- **`dsh-safe explain [--file <路径>]`**：读一段启动失败的 stderr（stdin 或文件），输出人话解读与修复建议。纯只读，不碰任何文件。
+- **AI 兜底识别**（`DSH_SAFE_AI_RECOVER=1`）：正则特征识别不出坏插件时（如 dsh 升级换格式），让 AI 从 stderr 里挑元凶——**结果必须仍走同一验证管线**（对照真实 patch 行、第一方保护、dry-run 预览），命中不了照旧透传。仅在启动失败时调用。
+- 隐私：发送前 home 路径脱敏为 `~`；AI 任何失败都静默降级。
+
 ## 安全边界
 
 - **第一方保护**：`@deepseek-ai/*` 的行默认跳过（禁用 `dsh-web-app` 这类插件会让 dsh 失去核心能力），需要 `--allow-first-party` 才会动。
@@ -98,7 +114,7 @@ Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broke
 - patch 文件本身 YAML 解析错误（如手改坏了）时无法识别插件，只会透传。
 - `--patch` 覆盖层里插入的行不参与对照表（对照表只扫 profile patch、home patch 与 bundle patch）。
 - 为了捕获 stderr，包装器把 dsh 的 stderr 接到管道（内容仍实时回显到终端）；stdout/stdin 直通不受影响。
-- 本项目针对 dsh 0.1.x 的报错格式做匹配；dsh 大版本升级后格式变化时需要同步更新解析器。
+- 本项目针对 dsh 0.1.x 的报错格式做匹配；dsh 大版本升级后格式变化时需要同步更新解析器。缓解：update/-u 升级 dsh 后会自动做解析器自校验——临时 profile 试启新版 dsh 并确认报错仍可识别，失配当场告警（`--no-verify` 跳过）。
 - Windows 为尽力支持：update / --self / list / restore 已适配（.cmd shim 解析、shell 方式调用 npm/pnpm）；包装启动会把 PATH 上 dsh 的 .cmd/.ps1 shim 解析出内嵌的 node 入口、改为 `node <入口>` 直接启动（.exe 直接运行，shim 解析失败退回 shell 方式），绕开 Node 禁止 spawn .cmd 的限制。尚未在真实 Windows 上端到端验证，欢迎反馈。
 
 ## 开发

package/lib/ai.js

@@ -0,0 +1,106 @@
+/**
+ * @hyzyn/dsh-safe — AI 能力（可选，零依赖，Node 20 全局 fetch）。
+ *
+ * 走 OpenAI 兼容的 chat completions 接口，默认指向 DeepSeek：
+ *   DSH_SAFE_AI_KEY        API key（未设置 = AI 能力整体禁用）
+ *   DSH_SAFE_AI_BASE_URL   默认 https://api.deepseek.com
+ *   DSH_SAFE_AI_MODEL      默认 deepseek-chat
+ *
+ * 原则：任何失败（无 key / 网络 / 超时 / 响应异常）都静默返回 null，绝不
+ * 影响主流程；模型只是"多一个识别器/解释器"，不获得任何写权限——兜底识别
+ * 的输出必须由调用方经 matchFailures 对照真实 patch 行后才生效。
+ * 发送前脱敏：用户 home 目录路径替换为 ~。
+ */
+import { homedir } from 'node:os'
+import { getLocale } from './i18n.js'
+
+export const aiEnabled = () => Boolean(process.env.DSH_SAFE_AI_KEY)
+
+/** 发送前脱敏：home 绝对路径 → ~。 */
+export function redact(text) {
+  return String(text ?? '').split(homedir()).join('~')
+}
+
+/** OpenAI 兼容 chat completions；任何失败返回 null。 */
+async function chat(messages, { timeoutMs = 30_000 } = {}) {
+  const key = process.env.DSH_SAFE_AI_KEY
+  if (!key) return null
+  const base = (process.env.DSH_SAFE_AI_BASE_URL ?? 'https://api.deepseek.com').replace(/\/+$/, '')
+  const model = process.env.DSH_SAFE_AI_MODEL ?? 'deepseek-chat'
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const res = await fetch(`${base}/chat/completions`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+      body: JSON.stringify({ model, messages, temperature: 0, stream: false }),
+      signal: controller.signal,
+    })
+    if (!res.ok) return null
+    const data = await res.json()
+    const content = data?.choices?.[0]?.message?.content
+    return typeof content === 'string' && content.trim() ? content.trim() : null
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * 解释一段启动失败的 stderr：失败原因 + 可疑插件 + 修复建议（纯文本）。
+ * @param {string} stderr
+ * @returns {Promise<string | null>}
+ */
+export async function explainFailure(stderr) {
+  const lang = getLocale() === 'zh' ? '中文' : 'English'
+  const prompt = [
+    getLocale() === 'zh'
+      ? `以下是一段 dsh（DeepSeek Harness）启动失败时捕获的 stderr。请用中文回答，控制在 200 字内：`
+      : `The following stderr was captured from a failed dsh (DeepSeek Harness) boot. Answer in English, within 200 words:`,
+    `1) ${getLocale() === 'zh' ? '一句话说明最可能的失败原因；' : 'One sentence on the most likely cause;'}`,
+    `2) ${getLocale() === 'zh' ? '指出可疑的插件包名或配置项；' : 'Point out the suspicious plugin package or config;'}`,
+    `3) ${getLocale() === 'zh' ? '给出 1-3 条具体修复建议（命令或配置修改）。不要编造不存在的插件。' : 'Give 1-3 concrete fixes (commands or config changes). Do not invent plugins that are not present.'}`,
+    '',
+    '--- stderr ---',
+    redact(stderr),
+  ].join('\n')
+  return chat([{ role: 'user', content: prompt }])
+}
+
+/**
+ * AI 兜底识别：正则特征匹配不到坏插件时，让模型从 stderr 里挑出元凶。
+ * 只允许在 knownRows（行 id ↔ 包名对照）里选择，降低幻觉；返回结构化
+ * 候选 [{ packageName?, entryId?, reason? }]，由调用方经 matchFailures
+ * 对照真实行后才生效。
+ * @param {string} stderr
+ * @param {Array<{ id: string, name: string | null }>} knownRows
+ * @returns {Promise<Array<{ packageName?: string, entryId?: string, reason?: string }> | null>}
+ *          null = AI 不可用或调用失败（调用方照旧透传）
+ */
+export async function detectFailureWithAI(stderr, knownRows) {
+  const choices = knownRows.filter((r) => r.name || r.id).map((r) => ({ id: r.id, name: r.name ?? undefined }))
+  if (!choices.length) return []
+  const prompt = [
+    'The following stderr is from a failed dsh (DeepSeek Harness) boot. Regex signatures failed to identify the broken plugin.',
+    'From the allowed list below, pick the plugin row(s) most likely responsible. Reply with ONLY a JSON array like [{"packageName":"@scope/name","entryId":"row-id","reason":"short why"}]. Use values from the allowed list verbatim; return [] if none plausibly match.',
+    'Allowed rows (id ↔ name):',
+    JSON.stringify(choices),
+    '',
+    '--- stderr ---',
+    redact(stderr),
+  ].join('\n')
+  const content = await chat([{ role: 'user', content: prompt }])
+  if (!content) return null
+  const m = /\[[\s\S]*\]/.exec(content)
+  if (!m) return []
+  try {
+    const arr = JSON.parse(m[0])
+    if (!Array.isArray(arr)) return []
+    return arr.filter(
+      (x) => x && typeof x === 'object' && (typeof x.packageName === 'string' || typeof x.entryId === 'string'),
+    )
+  } catch {
+    return []
+  }
+}

package/lib/cli.js

@@ -8,9 +8,12 @@
  *   dsh-safe help | --version
  */
 import { createRequire } from 'node:module'
+import { readFileSync } from 'node:fs'
 import { loadLedger, restoreQuarantine } from './quarantine.js'
 import { runWrapped } from './wrap.js'
 import { cmdUpdate, cmdUpdateAndBoot, maybeNotifySelfUpdate } from './update.js'
+import { printDoctor } from './doctor.js'
+import { aiEnabled, explainFailure } from './ai.js'
 import { t } from './i18n.js'
 
 const require = createRequire(import.meta.url)
@@ -24,6 +27,53 @@ function printVersion() {
   process.stdout.write(`${version}\n`)
 }
 
+/**
+ * `dsh-safe explain [--file <path>]`：AI 解读一段启动失败的 stderr。
+ * 纯只读——不写任何文件；未配置 DSH_SAFE_AI_KEY 时给出启用指引。
+ */
+async function cmdExplain(args) {
+  if (args.includes('-h') || args.includes('--help')) {
+    printHelp()
+    return 0
+  }
+  let file
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--file') file = args[++i]
+    else if (args[i].startsWith('--file=')) file = args[i].slice('--file='.length)
+  }
+  if (!aiEnabled()) {
+    process.stderr.write(`${t('aiDisabled')}\n`)
+    return 1
+  }
+  let input = ''
+  if (file !== undefined) {
+    try {
+      input = readFileSync(file, 'utf8')
+    } catch {
+      process.stderr.write(`${t('aiFileUnreadable', { file })}\n`)
+      return 2
+    }
+  } else {
+    if (process.stdin.isTTY) process.stderr.write(`${t('explainStdinHint')}\n`)
+    try {
+      input = readFileSync(0, 'utf8')
+    } catch {
+      input = ''
+    }
+  }
+  if (!input.trim()) {
+    process.stderr.write(`${t('aiNoInput')}\n`)
+    return 2
+  }
+  const answer = await explainFailure(input)
+  if (!answer) {
+    process.stderr.write(`${t('aiExplainFailed')}\n`)
+    return 1
+  }
+  process.stdout.write(`${answer}\n`)
+  return 0
+}
+
 /** 解析 `--profile <名>` / `--profile=<名>`，返回 [值, 剩余参数]。 */
 function takeProfile(args) {
   let profile
@@ -58,8 +108,13 @@ function takeIds(args) {
 }
 
 function cmdList(args) {
-  const [profile] = takeProfile(args)
+  const [profile, rest] = takeProfile(args)
   const ledger = loadLedger()
+  if (rest.includes('--json')) {
+    const profiles = profile ? { [profile]: ledger.profiles[profile] ?? [] } : ledger.profiles
+    process.stdout.write(`${JSON.stringify({ version: ledger.version ?? 1, profiles }, null, 2)}\n`)
+    return 0
+  }
   const profiles = profile ? [profile] : Object.keys(ledger.profiles).sort()
   let found = 0
   for (const p of profiles) {
@@ -82,21 +137,27 @@ function cmdRestore(args) {
   const [ids0, rest1] = takeIds(rest0)
   const dryRun = rest1.includes('--dry-run')
   const all = rest1.includes('--all')
-  const profile = profile0
-  if (!profile) {
-    process.stderr.write(`${t('restoreNeedsProfile')}\n`)
-    return 2
-  }
   if (!all && ids0.length === 0) {
     process.stderr.write(`${t('restoreNeedsId')}\n`)
     return 2
   }
-  const { restored, kept } = restoreQuarantine(profile, all ? 'all' : ids0, dryRun)
+  // 省略 --profile 时遍历台账里所有有记录的 profile（与 update 的恢复对齐）
+  const ledger = loadLedger()
+  const profiles = profile0
+    ? [profile0]
+    : Object.keys(ledger.profiles).filter((p) => (ledger.profiles[p] ?? []).length)
   const verb = t(dryRun ? 'restoredDry' : 'restored')
-  for (const e of restored) process.stdout.write(`[dsh-safe] ${verb} ${e.name ?? e.id} (id: ${e.id})\n`)
-  if (!restored.length) process.stdout.write(`${t('noMatching')}\n`)
-  else if (kept.length) process.stdout.write(`${t('stillQuarantined', { profile, count: kept.length })}\n`)
-  else process.stdout.write(`${t('ledgerCleared')}\n`)
+  let anyRestored = false
+  for (const p of profiles) {
+    const { restored, kept } = restoreQuarantine(p, all ? 'all' : ids0, dryRun)
+    for (const e of restored) process.stdout.write(`[dsh-safe] ${verb} ${e.name ?? e.id} (id: ${e.id})\n`)
+    if (restored.length) {
+      anyRestored = true
+      if (kept.length) process.stdout.write(`${t('stillQuarantined', { profile: p, count: kept.length })}\n`)
+      else process.stdout.write(`${t('ledgerCleared')}\n`)
+    }
+  }
+  if (!anyRestored) process.stdout.write(`${t('noMatching')}\n`)
   return 0
 }
 
@@ -121,6 +182,11 @@ export async function main(argv) {
   if (cmd === 'list') return cmdList(argv.slice(1))
   if (cmd === 'restore') return cmdRestore(argv.slice(1))
   if (cmd === 'update') return cmdUpdate(argv.slice(1))
+  if (cmd === 'explain') return cmdExplain(argv.slice(1))
+  if (cmd === 'doctor') {
+    printDoctor()
+    return 0
+  }
   if (cmd === '-u' || cmd === '--update') return cmdUpdateAndBoot(argv.slice(1), { boot: runWrapperMode })
 
   // 包装模式：剥掉 dsh-safe 自己的旗标（必须出现在第一个位置参数之前），
@@ -132,6 +198,7 @@ export async function main(argv) {
 async function runWrapperMode(argv) {
   maybeNotifySelfUpdate()
   const forwardArgs = []
+  const excludeArgs = []
   let dryRun = false
   let maxRetries = 2
   let allowFirstParty = false
@@ -140,6 +207,8 @@ async function runWrapperMode(argv) {
     const a = argv[i]
     if (a === '--dry-run') { dryRun = true; continue }
     if (a === '--allow-first-party') { allowFirstParty = true; continue }
+    if (a === '--exclude') { const v = argv[++i]; if (v !== undefined) excludeArgs.push(v); continue }
+    if (a.startsWith('--exclude=')) { excludeArgs.push(a.slice('--exclude='.length)); continue }
     if (a === '--max-retries') {
       const raw = argv[++i]
       const v = raw === undefined || raw === '' ? NaN : Number(raw)
@@ -168,5 +237,5 @@ async function runWrapperMode(argv) {
     return 0
   }
   if (dryRun) process.stderr.write(`${t('dryRunNotice')}\n`)
-  return runWrapped({ forwardArgs, dryRun, maxRetries, allowFirstParty })
+  return runWrapped({ forwardArgs, dryRun, maxRetries, allowFirstParty, exclude: excludeArgs })
 }

package/lib/config.js

@@ -0,0 +1,31 @@
+/**
+ * @hyzyn/dsh-safe — 用户配置：$DSH_HOME/dsh-safe/config.json（JSON）。
+ *
+ * 目前只有 exclude（隔离豁免名单：行 id 或插件包名，命中的行永不自动禁用，
+ * 适合自己开发中、或明知兼容但偶发报错的插件）。文件损坏时按空配置处理，
+ * 绝不影响主流程。
+ */
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { dshHome, readIfExists } from './dshpaths.js'
+
+export const configPath = () => join(dshHome(), 'dsh-safe', 'config.json')
+
+/** @returns {{ exclude: string[] }} */
+export function loadConfig() {
+  const raw = readIfExists(configPath())
+  if (raw === undefined) return { exclude: [] }
+  try {
+    const parsed = JSON.parse(raw)
+    if (parsed && typeof parsed === 'object' && Array.isArray(parsed.exclude)) {
+      return { exclude: parsed.exclude.filter((x) => typeof x === 'string') }
+    }
+  } catch {}
+  return { exclude: [] }
+}
+
+export function saveConfig(config) {
+  const file = configPath()
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`)
+}

package/lib/doctor.js

@@ -0,0 +1,62 @@
+/**
+ * @hyzyn/dsh-safe — `dsh-safe doctor`：环境体检。
+ *
+ * 汇总 self/dsh 版本、DSH_HOME、profiles、隔离台账、各 patch 文件的行数与
+ * 托管区块状态、AI 开关、更新检查时间。纯只读，不改任何文件。
+ */
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { dshHome, homePatchPath, profileDir, readIfExists, updateCheckFile } from './dshpaths.js'
+import { loadLedger } from './quarantine.js'
+import { MANAGED_START, scanPatchRows } from './patchfile.js'
+import { resolveDshPackage, resolveSelfPackage } from './update.js'
+import { aiEnabled } from './ai.js'
+import { t } from './i18n.js'
+
+export function printDoctor({ log = (line) => process.stdout.write(`${line}\n`) } = {}) {
+  const self = resolveSelfPackage()
+  log(t('doctorSelf', { version: self?.version ?? '?' }))
+  const dsh = resolveDshPackage()
+  log(dsh ? t('doctorDsh', { name: dsh.name, version: dsh.version }) : t('doctorDshMissing'))
+  log(t('doctorHome', { home: dshHome() }))
+
+  const profilesRoot = join(dshHome(), 'profiles')
+  let profiles = []
+  try {
+    if (existsSync(profilesRoot)) {
+      profiles = readdirSync(profilesRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort()
+    }
+  } catch {}
+  log(t('doctorProfiles', { profiles: profiles.join(', ') || '-' }))
+
+  const ledger = loadLedger()
+  const entries = Object.values(ledger.profiles).flat()
+  if (entries.length) {
+    const oldest = entries.map((e) => e.quarantinedAt).filter(Boolean).sort()[0] ?? '-'
+    log(t('doctorLedger', { count: entries.length, oldest, profiles: Object.keys(ledger.profiles).join(', ') }))
+  } else {
+    log(t('doctorLedgerEmpty'))
+  }
+
+  for (const p of profiles) reportPatch(join(profileDir(p), 'cordis.patch.yml'), log)
+  reportPatch(homePatchPath(), log)
+
+  log(aiEnabled() ? t('doctorAIOn', { model: process.env.DSH_SAFE_AI_MODEL ?? 'deepseek-chat' }) : t('doctorAIOff'))
+
+  let lastCheckAt
+  try {
+    lastCheckAt = JSON.parse(readIfExists(updateCheckFile()) ?? '{}')?.lastCheckAt
+  } catch {}
+  log(lastCheckAt ? t('doctorCheckLast', { time: lastCheckAt }) : t('doctorCheckNever'))
+}
+
+function reportPatch(path, log) {
+  const text = readIfExists(path)
+  if (text === undefined) {
+    log(t('doctorPatchMissing', { file: path }))
+    return
+  }
+  const rows = scanPatchRows(text)
+  const managed = text.includes(MANAGED_START) ? '✓' : '—'
+  log(t('doctorPatchOk', { file: path, rows: rows.length, managed }))
+}

package/lib/i18n.js

@@ -17,11 +17,14 @@ const ZH = {
 用法:
   dsh-safe <dsh 参数…>             包装运行 dsh，例: dsh-safe web
   dsh-safe -u [<dsh 参数…>]         先升级 dsh（已最新则跳过），再启动
-  dsh-safe list [--profile <名>]    查看隔离名单（缺省列出全部 profile）
+  dsh-safe list [--profile <名>] [--json]
+                                    查看隔离名单（--json 输出 JSON）
+  dsh-safe doctor                   环境体检（版本 / 台账 / patch 健康）
   dsh-safe restore --profile <名> (--id <id> | --all) [--dry-run]
                                     恢复被自动禁用的插件（升级修复后使用）
-  dsh-safe update [-y] [--to <版本>] [--self] [--no-restore] [--pm npm|pnpm]
+  dsh-safe update [-y] [--to <版本>] [--self] [--no-restore] [--no-verify] [--pm npm|pnpm]
                                     升级 dsh 与 dsh-safe 自身，并自动恢复被隔离的插件
+  dsh-safe explain [--file <路径>]  用 AI 解读一段启动失败的 stderr（需 DSH_SAFE_AI_KEY）
   dsh-safe help                     显示本帮助
   dsh-safe --version                显示版本
 
@@ -46,7 +49,6 @@ const ZH = {
   locationLine: '      位置: {file}',
   noRecordsProfile: '{profile}: 没有隔离记录',
   noRecords: '没有隔离记录',
-  restoreNeedsProfile: '[dsh-safe] restore 需要 --profile <名>',
   restoreNeedsId: '[dsh-safe] restore 需要 --id <id>（可重复）或 --all',
   restored: '已恢复',
   restoredDry: '（dry-run）将恢复',
@@ -89,12 +91,37 @@ const ZH = {
   updateRestoreSkipped: '[dsh-safe] 已按 --no-restore 跳过恢复；可稍后用 dsh-safe restore --profile <名> --all 恢复。',
   updateVerifyHint: '[dsh-safe] 请启动 dsh 验证；仍不兼容的插件会自动再次隔离。',
   updateRollbackHint: '[dsh-safe] 如需回滚: dsh-safe update --to {version}',
+  verifyRunning: '[dsh-safe] 正在自校验解析器：用临时 profile 试启新版 dsh（预期失败）…',
+  verifyPassed: '[dsh-safe] 解析器自校验通过：新版 dsh 的报错能被识别，自动隔离可用。',
+  verifyFailNoHit: '[dsh-safe] 警告：解析器自校验未通过——无法从新版 dsh 的报错里识别坏插件，自动隔离可能失效；建议回滚（dsh-safe update --to {version}）并反馈给 dsh-safe。',
+  verifyFailBoot: '[dsh-safe] 警告：解析器自校验未通过——坏插件试启意外成功，未触发报错，自动隔离未验证。',
+  verifyFailTimeout: '[dsh-safe] 警告：解析器自校验未完成（试启超时或无法启动），自动隔离未验证。',
   selfUpdateLagHint: '[dsh-safe] dsh-safe 已更新: {old} → {new}（本次运行仍是旧版，下次启动生效）',
   updateNotify: '[dsh-safe] 提示: dsh-safe 有新版本 {new}（当前 {old}）',
   updateNotifyHow: '           升级: npm i -g {name} 或 dsh-safe update --self',
   updateUnknownFlag: '[dsh-safe] update 无法识别的参数: {arg}',
   updatePmInvalid: '[dsh-safe] --pm 只支持 npm 或 pnpm。',
   updateToInvalid: '[dsh-safe] --to 需要合法的版本号（如 1.2.3 或 1.2.3-rc.1）。',
+  aiDisabled: '[dsh-safe] AI 功能未启用：设置环境变量 DSH_SAFE_AI_KEY 后可用（默认对接 DeepSeek，见 README 环境变量表）。',
+  aiNoInput: '[dsh-safe] 没有读到任何 stderr 内容：用 --file <路径>，或从 stdin 粘贴后按 Ctrl-D 结束。',
+  aiExplainFailed: '[dsh-safe] AI 解读失败（网络或接口异常）；未修改任何文件。',
+  aiFileUnreadable: '[dsh-safe] 无法读取文件: {file}',
+  explainStdinHint: '[dsh-safe] 正在从 stdin 读取：粘贴 stderr 后按 Ctrl-D（EOF）结束；也可以改用 --file <路径>。',
+  aiRecovered: '[dsh-safe] AI 兜底识别出 {count} 个可疑坏插件（结果仍走同一隔离管线）',
+  excludedByList: '[dsh-safe] 按豁免名单跳过 {label}（不自动禁用）',
+  doctorSelf: 'dsh-safe   {version}',
+  doctorDsh: 'dsh        {name} {version}',
+  doctorDshMissing: 'dsh        未在 PATH 上找到',
+  doctorHome: 'DSH_HOME   {home}',
+  doctorProfiles: 'profiles   {profiles}',
+  doctorLedger: '隔离台账    {count} 条（最早 {oldest}；profile: {profiles}）',
+  doctorLedgerEmpty: '隔离台账    无记录',
+  doctorPatchOk: 'patch      {file}（{rows} 行；托管区块 {managed}）',
+  doctorPatchMissing: 'patch      {file}（不存在）',
+  doctorAIOn: 'AI         已启用（模型 {model}）',
+  doctorAIOff: 'AI         未启用（DSH_SAFE_AI_KEY 未设置）',
+  doctorCheckLast: '更新检查    上次 {time}',
+  doctorCheckNever: '更新检查    从未执行',
 }
 
 const EN = {
@@ -109,11 +136,14 @@ ledger), and retries automatically.
 Usage:
   dsh-safe <dsh args…>             wrap and run dsh, e.g. dsh-safe web
   dsh-safe -u [<dsh args…>]         upgrade dsh first (skip if latest), then boot
-  dsh-safe list [--profile <name>] show quarantined plugins (defaults to all profiles)
+  dsh-safe list [--profile <name>] [--json]
+                                    show quarantined plugins (--json outputs JSON)
+  dsh-safe doctor                   environment check (versions / ledger / patch health)
   dsh-safe restore --profile <name> (--id <id> | --all) [--dry-run]
                                     re-enable auto-disabled plugins (after a fixed plugin upgrade)
-  dsh-safe update [-y] [--to <ver>] [--self] [--no-restore] [--pm npm|pnpm]
+  dsh-safe update [-y] [--to <ver>] [--self] [--no-restore] [--no-verify] [--pm npm|pnpm]
                                     upgrade dsh and dsh-safe itself, auto-restore quarantined plugins
+  dsh-safe explain [--file <path>]  interpret a failed-boot stderr with AI (needs DSH_SAFE_AI_KEY)
   dsh-safe help                     show this help
   dsh-safe --version                show version
 
@@ -140,7 +170,6 @@ Notes:
   locationLine: '      location: {file}',
   noRecordsProfile: '{profile}: no quarantine records',
   noRecords: 'no quarantine records',
-  restoreNeedsProfile: '[dsh-safe] restore requires --profile <name>',
   restoreNeedsId: '[dsh-safe] restore requires --id <id> (repeatable) or --all',
   restored: 'restored',
   restoredDry: '(dry-run) would restore',
@@ -184,12 +213,37 @@ Notes:
   updateRestoreSkipped: '[dsh-safe] restore skipped due to --no-restore; restore later with dsh-safe restore --profile <name> --all.',
   updateVerifyHint: '[dsh-safe] start dsh to verify; plugins still incompatible will be auto-quarantined again.',
   updateRollbackHint: '[dsh-safe] to roll back: dsh-safe update --to {version}',
+  verifyRunning: '[dsh-safe] verifying the parser: booting the new dsh with a throwaway profile (expected to fail)…',
+  verifyPassed: '[dsh-safe] parser self-check passed: failures from the new dsh are recognized, auto-quarantine is available.',
+  verifyFailNoHit: '[dsh-safe] warning: parser self-check failed — the broken plugin could not be recognized in the new dsh errors; auto-quarantine may be broken. Consider rolling back (dsh-safe update --to {version}) and reporting it to dsh-safe.',
+  verifyFailBoot: '[dsh-safe] warning: parser self-check failed — the deliberately broken profile booted unexpectedly, no error was triggered; auto-quarantine unverified.',
+  verifyFailTimeout: '[dsh-safe] warning: parser self-check did not finish (boot timed out or could not start); auto-quarantine unverified.',
   selfUpdateLagHint: '[dsh-safe] dsh-safe updated: {old} → {new} (this run still uses the old version; takes effect on the next run)',
   updateNotify: '[dsh-safe] notice: a new dsh-safe version is available: {new} (current {old})',
   updateNotifyHow: '           to upgrade: npm i -g {name} or dsh-safe update --self',
   updateUnknownFlag: '[dsh-safe] unrecognized argument for update: {arg}',
   updatePmInvalid: '[dsh-safe] --pm only accepts npm or pnpm.',
   updateToInvalid: '[dsh-safe] --to requires a valid version (e.g. 1.2.3 or 1.2.3-rc.1).',
+  aiDisabled: '[dsh-safe] AI is not enabled: set the DSH_SAFE_AI_KEY environment variable (defaults to DeepSeek, see the env table in the README).',
+  aiNoInput: '[dsh-safe] no stderr content was read: use --file <path>, or paste to stdin and press Ctrl-D.',
+  aiExplainFailed: '[dsh-safe] AI interpretation failed (network or API error); no files were modified.',
+  aiFileUnreadable: '[dsh-safe] cannot read file: {file}',
+  explainStdinHint: '[dsh-safe] reading from stdin: paste the stderr and press Ctrl-D (EOF) to finish, or use --file <path>.',
+  aiRecovered: '[dsh-safe] AI fallback identified {count} suspected broken plugin(s); the same quarantine pipeline applies',
+  excludedByList: '[dsh-safe] skipped {label} per the exclusion list (never auto-disabled)',
+  doctorSelf: 'dsh-safe   {version}',
+  doctorDsh: 'dsh        {name} {version}',
+  doctorDshMissing: 'dsh        not found on PATH',
+  doctorHome: 'DSH_HOME   {home}',
+  doctorProfiles: 'profiles   {profiles}',
+  doctorLedger: 'ledger     {count} quarantined (oldest {oldest}; profiles: {profiles})',
+  doctorLedgerEmpty: 'ledger     empty',
+  doctorPatchOk: 'patch      {file} ({rows} rows; managed block {managed})',
+  doctorPatchMissing: 'patch      {file} (missing)',
+  doctorAIOn: 'AI         enabled (model {model})',
+  doctorAIOff: 'AI         disabled (DSH_SAFE_AI_KEY not set)',
+  doctorCheckLast: 'update-check last ran at {time}',
+  doctorCheckNever: 'update-check never ran',
 }
 
 const CATALOG = { zh: ZH, en: EN }

package/lib/update.js

@@ -13,6 +13,7 @@ import { createInterface } from 'node:readline/promises'
 import { delimiter, dirname, join } from 'node:path'
 import { loadLedger, restoreQuarantine } from './quarantine.js'
 import { readIfExists, updateCheckFile } from './dshpaths.js'
+import { verifyParser } from './verify.js'
 import { t } from './i18n.js'
 
 const err = (line) => process.stderr.write(`${line}\n`)
@@ -235,11 +236,12 @@ export async function cmdUpdateAndBoot(args, { boot } = {}) {
 /**
  * 更新主体；bootArgs 非空时更新成功（或已最新/检查失败）后继续启动。
  * 默认同时检查 dsh 与 dsh-safe 自身，谁旧升谁（一条安装命令）；--self 只更新自身。
- * @param {{ to?: string, yes?: boolean, restore?: boolean, pm?: string, selfOnly?: boolean }} opts
+ * dsh 更新成功后默认跑解析器自校验（--no-verify 跳过）。
+ * @param {{ to?: string, yes?: boolean, restore?: boolean, pm?: string, selfOnly?: boolean, noVerify?: boolean }} opts
  * @param {string[] | null} bootArgs
- * @param {{ boot?: (args: string[]) => Promise<number> }} hooks
+ * @param {{ boot?: (args: string[]) => Promise<number>, verify?: typeof verifyParser }} hooks
  */
-async function updateAndMaybeBoot(opts, bootArgs, { boot } = {}) {
+async function updateAndMaybeBoot(opts, bootArgs, { boot, verify = verifyParser } = {}) {
   const dshPkg = opts.selfOnly ? null : resolveDshPackage()
   const selfPkg = resolveSelfPackage()
   if (!dshPkg && !selfPkg) {
@@ -317,6 +319,9 @@ async function updateAndMaybeBoot(opts, bootArgs, { boot } = {}) {
       err(t('selfUpdateLagHint', { old: p.pkg.version, new: p.target }))
     }
   }
+  if (dshUpdated && !opts.noVerify) {
+    await verify({ rollbackVersion: plans.find((p) => p.pkg === dshPkg)?.pkg.version, log: err })
+  }
 
   if (opts.restore && dshUpdated) {
     const ledger = loadLedger()
@@ -343,12 +348,13 @@ async function updateAndMaybeBoot(opts, bootArgs, { boot } = {}) {
 
 /** 解析 update 子命令参数；出错返回 { error: { key, params? } } 供 i18n。 */
 function parseUpdateArgs(args) {
-  const opts = { to: undefined, yes: false, restore: true, pm: undefined, selfOnly: false }
+  const opts = { to: undefined, yes: false, restore: true, pm: undefined, selfOnly: false, noVerify: false }
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
     if (a === '-y' || a === '--yes') opts.yes = true
     else if (a === '--no-restore') opts.restore = false
     else if (a === '--self') opts.selfOnly = true
+    else if (a === '--no-verify') opts.noVerify = true
     else if (a === '--to') {
       const v = args[++i]
       if (v === undefined) return { error: { key: 'updateUnknownFlag', params: { arg: '--to' } } }
@@ -375,13 +381,14 @@ function parseUpdateArgs(args) {
  * dsh 启动参数（宽松处理——不像子命令那样对未知参数报错）。
  */
 function parseLeadingUpdateArgs(args) {
-  const opts = { to: undefined, yes: false, restore: true, pm: undefined, selfOnly: false }
+  const opts = { to: undefined, yes: false, restore: true, pm: undefined, selfOnly: false, noVerify: false }
   let i = 0
   for (; i < args.length; i++) {
     const a = args[i]
     if (a === '-y' || a === '--yes') opts.yes = true
     else if (a === '--no-restore') opts.restore = false
     else if (a === '--self') opts.selfOnly = true
+    else if (a === '--no-verify') opts.noVerify = true
     else if (a === '--to' && args[i + 1] !== undefined) opts.to = args[++i]
     else if (a.startsWith('--to=')) opts.to = a.slice('--to='.length)
     else if (a === '--pm' && args[i + 1] !== undefined) opts.pm = args[++i]

package/lib/verify.js

@@ -0,0 +1,78 @@
+/**
+ * @hyzyn/dsh-safe — 升级 dsh 后的解析器自校验。
+ *
+ * 风险背景：报错解析器与 dsh 的 stderr 格式耦合，dsh 升级可能让特征失配，
+ * 保险丝静默失效。自校验在临时 DSH_HOME 里搭一次性 profile（引用现场生成
+ * 的坏插件），用 PATH 上新装的 dsh 试启——预期启动失败，再确认解析器能从
+ * 报错里识别出坏插件。识别失败只告警（附回滚命令），不阻断后续启动。
+ */
+import { spawnSync } from 'node:child_process'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { parseFailureReport } from './failures.js'
+import { matchFailures } from './knownrows.js'
+import { resolveDshSpawnTarget } from './dshpaths.js'
+import { t } from './i18n.js'
+
+const BAD_ID = 'dsh-safe-verify'
+const BAD_NAME = '@dsh-safe-verify/broken'
+
+/**
+ * @param {{
+ *   rollbackVersion?: string,
+ *   log?: (line: string) => void,
+ *   timeoutMs?: number,
+ *   spawn?: typeof spawnSync,
+ * }} [options]
+ * @returns {Promise<boolean>} 自校验是否通过
+ */
+export async function verifyParser({ rollbackVersion, log = (line) => process.stderr.write(`${line}\n`), timeoutMs = 60_000, spawn = spawnSync } = {}) {
+  log(t('verifyRunning'))
+  const home = mkdtempSync(join(tmpdir(), 'dsh-safe-verify-'))
+  try {
+    // 一次性 profile：patch 行引用现场生成的坏插件（模块级 throw → import 失败）
+    const profileDir = join(home, 'profiles', 'verify')
+    const modDir = join(profileDir, 'node_modules', BAD_NAME)
+    mkdirSync(join(modDir, 'lib'), { recursive: true })
+    writeFileSync(join(profileDir, 'package.json'), JSON.stringify({ name: 'dsh-profile-verify', private: true }))
+    const patchPath = join(profileDir, 'cordis.patch.yml')
+    writeFileSync(patchPath, `- id: ${BAD_ID}\n  name: '${BAD_NAME}'\n`)
+    writeFileSync(
+      join(modDir, 'package.json'),
+      JSON.stringify({ name: BAD_NAME, version: '0.0.1', type: 'module', main: 'lib/index.js' }),
+    )
+    writeFileSync(join(modDir, 'lib', 'index.js'), `throw new Error('dsh-safe parser self-check')\n`)
+
+    const target = resolveDshSpawnTarget('dsh')
+    const { status, stderr } = spawn(target.file, [...target.prefix, '--profile', 'verify'], {
+      env: { ...process.env, DSH_HOME: home },
+      stdio: ['ignore', 'ignore', 'pipe'],
+      timeout: timeoutMs,
+      shell: target.shell,
+      encoding: 'utf8',
+    })
+
+    if (status === 0) {
+      log(t('verifyFailBoot'))
+      return false
+    }
+    if (status === null) {
+      // 超时被杀或无法启动试启进程
+      log(t('verifyFailTimeout'))
+      return false
+    }
+    const report = parseFailureReport(stderr ?? '')
+    const hits = matchFailures(report, {
+      rows: [{ id: BAD_ID, name: BAD_NAME, disabled: false, file: patchPath }],
+    })
+    if (hits.length) {
+      log(t('verifyPassed'))
+      return true
+    }
+    log(t('verifyFailNoHit', { version: rollbackVersion ?? '' }))
+    return false
+  } finally {
+    rmSync(home, { recursive: true, force: true })
+  }
+}

package/lib/wrap.js

@@ -15,6 +15,8 @@ import { summarizeLine, parseFailureReport } from './failures.js'
 import { collectKnownRows, matchFailures } from './knownrows.js'
 import { detectInvocation, resolveDshSpawnTarget } from './dshpaths.js'
 import { writeQuarantine } from './quarantine.js'
+import { loadConfig } from './config.js'
+import { aiEnabled, detectFailureWithAI } from './ai.js'
 import { t } from './i18n.js'
 
 const CAPTURE_LIMIT = 512 * 1024
@@ -22,6 +24,26 @@ const FIRST_PARTY_PREFIX = '@deepseek-ai/'
 
 const isFirstParty = (name) => typeof name === 'string' && name.startsWith(FIRST_PARTY_PREFIX)
 
+const aiRecoverEnabled = () => process.env.DSH_SAFE_AI_RECOVER === '1' && aiEnabled()
+
+/**
+ * AI 兜底默认实现：让模型从 stderr 里挑元凶，输出被转换成一份"报告"再走
+ * matchFailures——与正则识别完全相同的对照管线（真实行校验、第一方保护、
+ * disabled 跳过），命中不了就照旧透传，模型没有任何写权限。
+ */
+function picksToHits(picks, known, stderr, log) {
+  if (!picks?.length) return []
+  const fallbackReason = summarizeLine(stderr)
+  const names = picks.filter((p) => p.packageName).map((p) => [p.packageName, p.reason ?? fallbackReason])
+  const entryIds = picks.filter((p) => p.entryId).map((p) => [p.entryId, p.reason ?? fallbackReason])
+  const hits = matchFailures({ names, entryIds }, known)
+  if (hits.length) log(t('aiRecovered', { count: hits.length }))
+  return hits
+}
+
+const defaultDetect = (stderr, known) =>
+  detectFailureWithAI(stderr, known.rows.map(({ id, name }) => ({ id, name })))
+
 /** shell 方式兜底时给含空白的参数补引号（正常路径不走 shell，不受影响）。 */
 const quoteShellArg = (a) => (/\s/.test(a) && !/^".*"$/.test(a) ? `"${a}"` : a)
 
@@ -55,6 +77,7 @@ export function spawnDsh(args, { command = 'dsh' } = {}) {
  *   allowFirstParty?: boolean,
  *   log?: (...args: any[]) => void,
  *   spawn?: typeof spawnDsh,
+ *   detect?: (stderr: string, known: object, log: (line: string) => void) => Promise<Array<{ packageName?: string, entryId?: string, reason?: string }>>,
  * }} options
  * @returns {Promise<number>} 最终退出码
  */
@@ -64,8 +87,10 @@ export async function runWrapped(options) {
     dryRun = false,
     maxRetries = 2,
     allowFirstParty = false,
+    exclude = [],
     log = (line) => process.stderr.write(`${line}\n`),
     spawn: spawnFn = spawnDsh,
+    detect = null,
   } = options
   const invocation = detectInvocation(forwardArgs)
   for (let attempt = 0; ; attempt++) {
@@ -81,12 +106,22 @@ export async function runWrapped(options) {
     }
     const known = collectKnownRows(invocation.profile)
     const report = parseFailureReport(stderr)
-    const hits = matchFailures(report, known)
+    let hits = matchFailures(report, known)
+    const detectFn = detect ?? (aiRecoverEnabled() ? defaultDetect : null)
+    if (!hits.length && detectFn) {
+      // detect 返回 AI 候选（picks），一律经 picksToHits 对照真实行后才成为 hits
+      const picks = await detectFn(stderr, known, log)
+      hits = picksToHits(picks, known, stderr, log)
+    }
     const quarantinable = []
     const firstParty = []
+    // 豁免名单：config.json 的 exclude + 包装旗标 --exclude（行 id 或包名），永不自动禁用
+    const excluded = new Set([...loadConfig().exclude, ...exclude])
+    const isExcluded = (hit) => excluded.has(hit.id) || (hit.name != null && excluded.has(hit.name))
     for (const hit of hits) {
       if (hit.disabled) continue // 已经是禁用状态
       if (isFirstParty(hit.name) && !allowFirstParty) firstParty.push(hit)
+      else if (isExcluded(hit)) log(t('excludedByList', { label: hit.name ?? hit.id }))
       else quarantinable.push(hit)
     }
     for (const hit of firstParty) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyzyn/dsh-safe",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "dsh 启动保险丝：社区插件不兼容导致 dsh 启动失败时，自动禁用坏插件并重试",
   "type": "module",
   "license": "MIT",