@hyzyn/dsh-safe 0.9.0 → 0.10.0

package/README.en.md

@@ -47,7 +47,7 @@ Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broke
 | `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 [--profile <name> \| --file <path>]` | interpret a boot failure with AI: defaults to the last failure record, `--profile` boots the profile live, `--file`/stdin read any log (needs `DSH_SAFE_AI_KEY`) |
+| `dsh-safe explain [id] [--profile <name> \| --file <path>]` | interpret failure info with AI: an `id` interprets that quarantine record (with repair advice); defaults to the last failure log, falling back to the ledger; `--file`/stdin read any log (needs `DSH_SAFE_AI_KEY`) |
 | `dsh-safe repair [id] [--profile <name>] [--to <version>] [-y] [--dry-run]` | reinstall/upgrade a quarantined plugin and auto-restore it (module-resolution failures only; installs via `dsh plugin`'s pnpm channel) |
 | `dsh-safe help` (`-h` / `--help`) | show help |
 | `dsh-safe --version` (`-V`) | show version |
@@ -99,7 +99,7 @@ How upgrading works: `dsh-safe update` auto-detects the dsh package name and ins
 
 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 [--profile <name> | --file <path>]`**: interprets the most recent boot failure by default (stderr is persisted to `$DSH_HOME/dsh-safe/last-failure-<profile>.log` on every failed wrapped boot, for humans too); `--profile` boots that profile live and interprets (60s timeout); `--file`/stdin read any log. Strictly read-only — never touches the patch or ledger.
+- **`dsh-safe explain [id] [--profile <name> | --file <path>]`**: interprets the failure info dsh-safe knows — an `id` interprets that quarantine record and suggests `repair`; by default it interprets the most recent boot failure (stderr persisted to `$DSH_HOME/dsh-safe/last-failure-<profile>.log`), falling back to the ledger; `--file`/stdin read any log. Strictly read-only — never touches the patch or ledger.
 - **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.
 

package/README.md

@@ -47,7 +47,7 @@ Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broke
 | `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 [--profile <名> \| --file <路径>]` | 用 AI 解读启动失败：默认解读最近一次失败记录，`--profile` 现场试启并解读，`--file`/stdin 读任意日志（需 `DSH_SAFE_AI_KEY`） |
+| `dsh-safe explain [id] [--profile <名> \| --file <路径>]` | 用 AI 解读失败信息：指定 `id` 解读该条隔离记录（给 repair 建议）；默认解读最近一次失败日志，无日志则解读隔离台账；`--file`/stdin 读任意日志（需 `DSH_SAFE_AI_KEY`） |
 | `dsh-safe repair [id] [--profile <名>] [--to <版本>] [-y] [--dry-run]` | 重装/升级被隔离的插件并自动恢复（限模块解析失败类；经 `dsh plugin` 的 pnpm 通道安装） |
 | `dsh-safe help`（`-h` / `--help`） | 显示帮助 |
 | `dsh-safe --version`（`-V`） | 显示版本 |
@@ -99,7 +99,7 @@ Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broke
 
 设置 `DSH_SAFE_AI_KEY` 后启用（默认对接 DeepSeek，OpenAI 兼容接口，可用 `DSH_SAFE_AI_BASE_URL` / `DSH_SAFE_AI_MODEL` 换任何兼容服务）：
 
-- **`dsh-safe explain [--profile <名> | --file <路径>] [-- <dsh 参数…>]`**：默认解读最近一次启动失败（失败时 stderr 自动持久化到 `$DSH_HOME/dsh-safe/last-failure-<profile>.log`，人也可直接翻阅）；`--profile` 现场试启该 profile 并解读（60 秒超时，`--` 之后可透传 dsh 启动参数，如 `-- --port 3084`）；`--file`/stdin 读任意日志。纯只读，不碰 patch/台账。未知参数严格报错，绝不静默吞。
+- **`dsh-safe explain [id] [--profile <名> | --file <路径>]`**：解读 dsh-safe 所知的失败信息——指定 `id` 时解读该条隔离记录并给出 `repair` 建议；默认解读最近一次启动失败（stderr 自动持久化到 `$DSH_HOME/dsh-safe/last-failure-<profile>.log`）；无日志时解读隔离台账；`--file`/stdin 读任意日志。纯只读，不碰 patch/台账。
 - **AI 兜底识别**（`DSH_SAFE_AI_RECOVER=1`）：正则特征识别不出坏插件时（如 dsh 升级换格式），让 AI 从 stderr 里挑元凶——**结果必须仍走同一验证管线**（对照真实 patch 行、第一方保护、dry-run 预览），命中不了照旧透传。仅在启动失败时调用。
 - 隐私：发送前 home 路径脱敏为 `~`；AI 任何失败都静默降级。
 

package/lib/ai.js

@@ -16,6 +16,7 @@ import { readFileSync, readdirSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { dshHome, resolveDshSpawnTarget } from './dshpaths.js'
+import { loadLedger } from './quarantine.js'
 import { getLocale, t } from './i18n.js'
 
 export const aiEnabled = () => Boolean(process.env.DSH_SAFE_AI_KEY)
@@ -57,14 +58,14 @@ async function chat(messages, { timeoutMs = 30_000 } = {}) {
  * @returns {Promise<string | null>}
  */
 export async function explainFailure(stderr) {
-  const lang = getLocale() === 'zh' ? '中文' : 'English'
+  const zh = getLocale() === 'zh'
   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.'}`,
+    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) ${zh ? '一句话说明最可能的失败原因；' : 'One sentence on the most likely cause;'}`,
+    `2) ${zh ? '指出可疑的插件包名或配置项；' : 'Point out the suspicious plugin package or config;'}`,
+    `3) ${zh ? '给出 1-3 条具体修复建议（命令或配置修改）。不要编造不存在的插件。' : 'Give 1-3 concrete fixes (commands or config changes). Do not invent plugins that are not present.'}`,
     '',
     '--- stderr ---',
     redact(stderr),
@@ -109,17 +110,23 @@ export async function detectFailureWithAI(stderr, knownRows) {
   }
 }
 
-/** 试启一个 profile 并捕获 stderr（60s 超时；超时留下的部分 stderr 也可解读）。 */
-function bootProfileForExplain(profile, extraArgs, { spawn }) {
-  const target = resolveDshSpawnTarget('dsh')
-  const { status, stderr } = spawn(target.file, [...target.prefix, '--profile', profile, ...extraArgs], {
-    stdio: ['ignore', 'ignore', 'pipe'],
-    env: process.env,
-    shell: target.shell,
-    timeout: 60_000,
-    encoding: 'utf8',
-  })
-  return { code: status ?? 'timeout', stderr: stderr ?? '' }
+/** 解读被隔离插件记录（单条或多条）：失败原因分析 + 现在该怎么办的建议。 */
+async function interpretLedgerEntries(entries) {
+  const zh = getLocale() === 'zh'
+  const rows = entries.map(
+    (e) => `- id: ${e.id}  ${zh ? '包名' : 'package'}: ${e.name ?? '-'}  ${zh ? '隔离于' : 'quarantined at'}: ${e.quarantinedAt ?? '-'}  ${zh ? '原因' : 'reason'}: ${redact(e.reason ?? '-')}`,
+  )
+  const prompt = [
+    zh
+      ? '以下是 dsh-safe（DeepSeek Harness 的启动保险丝）自动隔离的插件记录：启动失败时对应 patch 行被自动禁用。请用中文回答，控制在 200 字内：'
+      : 'The following plugins were auto-quarantined by dsh-safe (a startup fuse for DeepSeek Harness): their patch rows were auto-disabled after boot failures. Answer in English, within 200 words:',
+    `1) ${zh ? '逐条说明当时最可能的失败原因（模块解析失败 / 配置或代码错误 / 依赖等待）；' : 'Per record, the most likely cause of failure (module resolution / config or code error / dependency wait);'}`,
+    `2) ${zh ? '给出当前建议：用 dsh-safe repair <id> 重装修复、升级 dsh 后重试、还是保持禁用。不要编造记录里没有的信息。' : 'Advise what to do now: dsh-safe repair <id> reinstall, retry after an upgrade, or keep disabled. Do not invent facts beyond the records.'}`,
+    '',
+    zh ? '--- 隔离记录 ---' : '--- quarantine records ---',
+    ...rows,
+  ].join('\n')
+  return chat([{ role: 'user', content: prompt }])
 }
 
 /** $DSH_HOME/dsh-safe/ 下最近修改的 last-failure-*.log。 */
@@ -138,13 +145,13 @@ function findLatestFailureFile() {
 }
 
 /**
- * `dsh-safe explain`：解读启动失败。输入优先级：
- *   --file <路径> > --profile <名>（现场试启并解读） >
- *   最近一次失败记录（包装启动失败时自动持久化的 last-failure-*.log） >
- *   stdin 管道。纯只读——不碰 patch/台账。
+ * `dsh-safe explain [id]`：AI 解读 dsh-safe 所知的失败信息。
+ *   - 指定 <id>：解读该条隔离记录（台账 reason + 上下文，给出 repair 建议）；
+ *   - 默认（无 id）：优先解读最近一次启动失败（last-failure-*.log），
+ *     没有日志时解读隔离台账；--profile/--file/stdin 另见参数。
+ * 纯只读——不碰 patch/台账。
  * @param {string[]} args
  * @param {{
- *   spawn?: typeof spawnSync,
  *   isTTY?: boolean,
  *   readStdin?: () => string,
  *   log?: (line: string) => void,
@@ -153,7 +160,6 @@ function findLatestFailureFile() {
  * @returns {Promise<number>} 退出码
  */
 export async function cmdExplain(args, {
-  spawn = spawnSync,
   isTTY = process.stdin.isTTY,
   readStdin = () => readFileSync(0, 'utf8'),
   log = (line) => process.stderr.write(`${line}\n`),
@@ -165,62 +171,117 @@ export async function cmdExplain(args, {
   }
   let file
   let profile
-  const bootArgs = []
-  let passthrough = false
+  let id
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
-    if (passthrough) { bootArgs.push(a); continue }
-    if (a === '--') { passthrough = true; continue }
     if (a === '--file') file = args[++i]
-    else if (a.startsWith('--file=')) file = args[i].slice('--file='.length)
+    else if (a.startsWith('--file=')) file = a.slice('--file='.length)
     else if (a === '--profile') profile = args[++i]
-    else if (a.startsWith('--profile=')) profile = args[i].slice('--profile='.length)
+    else if (a.startsWith('--profile=')) profile = a.slice('--profile='.length)
+    else if (!a.startsWith('-') && id === undefined) id = a
     else {
-      // 严格解析：未知参数绝不静默吞（否则用户传给 dsh 的意图会被丢弃）
+      // 严格解析：未知旗标/多余位置参数绝不静默吞
       log(t('explainUnknownArg', { arg: a }))
       return 2
     }
   }
-  if (bootArgs.length && profile === undefined) {
-    log(t('explainArgsNeedProfile'))
-    return 2
-  }
   if (!aiEnabled()) {
     log(t('aiDisabled'))
     return 1
   }
-  let input = ''
+
+  // ① 指定隔离记录：解读台账条目（给出 repair 建议）
+  if (id !== undefined) {
+    const matches = []
+    for (const [p, entries] of Object.entries(loadLedger().profiles)) {
+      if (profile && p !== profile) continue
+      for (const entry of entries ?? []) {
+        if (entry.id === id) matches.push({ profile: p, entry })
+      }
+    }
+    if (!matches.length) {
+      log(t('repairEntryMissing', { id }))
+      return 1
+    }
+    if (matches.length > 1) {
+      log(t('repairAmbiguous', { id, profiles: matches.map((m) => m.profile).join(', ') }))
+      return 2
+    }
+    log(t('explainEntry', { id, profile: matches[0].profile }))
+    const answer = await interpretLedgerEntries([matches[0].entry])
+    if (!answer) {
+      log(t('aiExplainFailed'))
+      return 1
+    }
+    write(answer)
+    return 0
+  }
+
+  // ② 指定日志文件
   if (file !== undefined) {
+    let input
     try {
       input = readFileSync(file, 'utf8')
     } catch {
       log(t('aiFileUnreadable', { file }))
       return 2
     }
-  } else if (profile !== undefined) {
-    log(t('explainBooting', { profile }))
-    const { code, stderr } = bootProfileForExplain(profile, bootArgs, { spawn })
-    if (code === 0 || !stderr?.trim()) {
-      log(t('explainBootOk', { profile }))
-      return 0
+    if (!input.trim()) {
+      log(t('aiNoInput'))
+      return 2
+    }
+    const answer = await explainFailure(input)
+    if (!answer) {
+      log(t('aiExplainFailed'))
+      return 1
     }
-    input = stderr
-  } else if (!isTTY) {
-    input = readStdin()
-  } else {
-    const latest = findLatestFailureFile()
-    if (!latest) {
-      log(t('explainNoSource'))
+    write(answer)
+    return 0
+  }
+
+  // ③ 管道输入
+  if (!isTTY) {
+    const input = readStdin()
+    if (!input.trim()) {
+      log(t('aiNoInput'))
       return 2
     }
+    const answer = await explainFailure(input)
+    if (!answer) {
+      log(t('aiExplainFailed'))
+      return 1
+    }
+    write(answer)
+    return 0
+  }
+
+  // ④ 默认（交互终端）：最近一次失败日志 → 隔离台账
+  const latest = findLatestFailureFile()
+  if (latest) {
     log(t('explainUsingLast', { file: latest.path }))
-    input = readFileSync(latest.path, 'utf8')
+    const input = readFileSync(latest.path, 'utf8')
+    if (!input.trim()) {
+      log(t('aiNoInput'))
+      return 2
+    }
+    const answer = await explainFailure(input)
+    if (!answer) {
+      log(t('aiExplainFailed'))
+      return 1
+    }
+    write(answer)
+    return 0
   }
-  if (!input.trim()) {
-    log(t('aiNoInput'))
+
+  const entries = Object.entries(loadLedger().profiles)
+    .filter(([p]) => !profile || p === profile)
+    .flatMap(([, list]) => list ?? [])
+  if (!entries.length) {
+    log(t('explainNoSource'))
     return 2
   }
-  const answer = await explainFailure(input)
+  log(t('explainLedger', { count: entries.length }))
+  const answer = await interpretLedgerEntries(entries)
   if (!answer) {
     log(t('aiExplainFailed'))
     return 1

package/lib/i18n.js

@@ -24,7 +24,7 @@ const ZH = {
                                     恢复被自动禁用的插件（升级修复后使用）
   dsh-safe update [-y] [--to <版本>] [--self] [--no-restore] [--no-verify] [--pm npm|pnpm]
                                     升级 dsh 与 dsh-safe 自身，并自动恢复被隔离的插件
-  dsh-safe explain [--profile <名> | --file <路径>]  用 AI 解读启动失败（默认解读最近一次失败）
+  dsh-safe explain [id] [--profile <名> | --file <路径>]  用 AI 解读：最近失败日志 / 隔离台账 / 任意日志
   dsh-safe repair [id] [--profile <名>] [--to <版本>] [-y] [--dry-run]
                                     重装/升级被隔离的插件并自动恢复（限模块解析失败类；省略 id 时只有一条记录则直接修）
   dsh-safe help                     显示本帮助
@@ -110,12 +110,11 @@ const ZH = {
   aiFileUnreadable: '[dsh-safe] 无法读取文件: {file}',
   aiRecovered: '[dsh-safe] AI 兜底识别出 {count} 个可疑坏插件（结果仍走同一隔离管线）',
   explainHint: '[dsh-safe] 可运行 dsh-safe explain 解读这次失败',
-  explainBooting: '[dsh-safe] 正在试启 profile {profile}（60 秒超时；不修改任何文件）…',
-  explainArgsNeedProfile: '[dsh-safe] 透传的启动参数需要与 --profile 一起使用。',
-  explainBootOk: '[dsh-safe] profile {profile} 当前能正常启动，没有失败可解读。',
   explainUsingLast: '[dsh-safe] 解读最近一次失败记录: {file}',
   explainNoSource: '[dsh-safe] 没有可解读的内容。用法：dsh-safe explain [--profile <名> | --file <路径>]，或从 stdin 管道输入。\n           包装启动失败时 stderr 会自动存到 $DSH_HOME/dsh-safe/last-failure-<profile>.log。',
-  explainUnknownArg: '[dsh-safe] explain 无法识别的参数: {arg}（透传给 dsh 的启动参数请放在 -- 之后，如 -- --port 3084）',
+  explainLedger: '[dsh-safe] 解读隔离台账（{count} 条）…',
+  explainEntry: '[dsh-safe] 解读隔离记录 {id}（profile: {profile}）…',
+  explainUnknownArg: '[dsh-safe] explain 无法识别的参数: {arg}',
   excludedByList: '[dsh-safe] 按豁免名单跳过 {label}（不自动禁用）',
   doctorSelf: 'dsh-safe   {version}',
   doctorDsh: 'dsh        {name} {version}',
@@ -159,7 +158,7 @@ Usage:
                                     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 [--profile <name> | --file <path>]  interpret the last boot failure with AI
+  dsh-safe explain [id] [--profile <name> | --file <path>]  interpret with AI: last failure log / ledger / any log
   dsh-safe repair [id] [--profile <name>] [--to <ver>] [-y] [--dry-run]
                                     reinstall/upgrade a quarantined plugin and auto-restore it (module-resolution failures only; omit id when there is exactly one record)
   dsh-safe help                     show this help
@@ -248,12 +247,11 @@ Notes:
   aiFileUnreadable: '[dsh-safe] cannot read file: {file}',
   aiRecovered: '[dsh-safe] AI fallback identified {count} suspected broken plugin(s); the same quarantine pipeline applies',
   explainHint: '[dsh-safe] run dsh-safe explain to interpret this failure',
-  explainBooting: '[dsh-safe] booting profile {profile} (60s timeout; no files are modified)…',
-  explainArgsNeedProfile: '[dsh-safe] passthrough boot args require --profile.',
-  explainBootOk: '[dsh-safe] profile {profile} boots fine right now — nothing failed to interpret.',
   explainUsingLast: '[dsh-safe] interpreting the last failure record: {file}',
   explainNoSource: '[dsh-safe] nothing to interpret. Usage: dsh-safe explain [--profile <name> | --file <path>], or pipe via stdin.\n           On wrapped-boot failures stderr is saved to $DSH_HOME/dsh-safe/last-failure-<profile>.log automatically.',
-  explainUnknownArg: '[dsh-safe] unrecognized argument for explain: {arg} (put dsh boot args after --, e.g. -- --port 3084)',
+  explainLedger: '[dsh-safe] interpreting the quarantine ledger ({count} record(s))…',
+  explainEntry: '[dsh-safe] interpreting quarantine record {id} (profile: {profile})…',
+  explainUnknownArg: '[dsh-safe] unrecognized argument for explain: {arg}',
   excludedByList: '[dsh-safe] skipped {label} per the exclusion list (never auto-disabled)',
   doctorSelf: 'dsh-safe   {version}',
   doctorDsh: 'dsh        {name} {version}',

package/package.json

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