@hyzyn/dsh-safe 0.4.0 → 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)
 
@@ -77,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`).
 
@@ -87,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.

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` 之后；其前的包装旗标照常生效）
 
@@ -77,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`）。
 
@@ -87,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` 才会动。

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] [--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）将恢复',
@@ -100,6 +102,26 @@ const ZH = {
   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 = {
@@ -114,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] [--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
 
@@ -145,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',
@@ -200,6 +224,26 @@ Notes:
   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/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.4.0",
+  "version": "0.5.0",
   "description": "dsh 启动保险丝：社区插件不兼容导致 dsh 启动失败时，自动禁用坏插件并重试",
   "type": "module",
   "license": "MIT",