@hyzyn/dsh-safe 0.7.0 → 0.9.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 [--file <path>]` | interpret a failed-boot stderr with AI (read-only, needs `DSH_SAFE_AI_KEY`) |
+| `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 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 [--file <path>]`**: feed it a failed-boot stderr (stdin or file) and get a plain-language interpretation plus fix suggestions. Strictly read-only.
+- **`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.
 - **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 [--file <路径>]` | 用 AI 解读一段启动失败 stderr（纯只读，需 `DSH_SAFE_AI_KEY`） |
+| `dsh-safe explain [--profile <名> \| --file <路径>]` | 用 AI 解读启动失败：默认解读最近一次失败记录，`--profile` 现场试启并解读，`--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 [--file <路径>]`**：读一段启动失败的 stderr（stdin 或文件），输出人话解读与修复建议。纯只读，不碰任何文件。
+- **`dsh-safe explain [--profile <名> | --file <路径>] [-- <dsh 参数…>]`**：默认解读最近一次启动失败（失败时 stderr 自动持久化到 `$DSH_HOME/dsh-safe/last-failure-<profile>.log`，人也可直接翻阅）；`--profile` 现场试启该 profile 并解读（60 秒超时，`--` 之后可透传 dsh 启动参数，如 `-- --port 3084`）；`--file`/stdin 读任意日志。纯只读，不碰 patch/台账。未知参数严格报错，绝不静默吞。
 - **AI 兜底识别**（`DSH_SAFE_AI_RECOVER=1`）：正则特征识别不出坏插件时（如 dsh 升级换格式），让 AI 从 stderr 里挑元凶——**结果必须仍走同一验证管线**（对照真实 patch 行、第一方保护、dry-run 预览），命中不了照旧透传。仅在启动失败时调用。
 - 隐私：发送前 home 路径脱敏为 `~`；AI 任何失败都静默降级。
 

package/lib/ai.js

@@ -11,8 +11,12 @@
  * 的输出必须由调用方经 matchFailures 对照真实 patch 行后才生效。
  * 发送前脱敏：用户 home 目录路径替换为 ~。
  */
+import { spawnSync } from 'node:child_process'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { getLocale } from './i18n.js'
+import { join } from 'node:path'
+import { dshHome, resolveDshSpawnTarget } from './dshpaths.js'
+import { getLocale, t } from './i18n.js'
 
 export const aiEnabled = () => Boolean(process.env.DSH_SAFE_AI_KEY)
 
@@ -104,3 +108,123 @@ export async function detectFailureWithAI(stderr, knownRows) {
     return []
   }
 }
+
+/** 试启一个 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 ?? '' }
+}
+
+/** $DSH_HOME/dsh-safe/ 下最近修改的 last-failure-*.log。 */
+function findLatestFailureFile() {
+  const dir = join(dshHome(), 'dsh-safe')
+  let best
+  try {
+    for (const name of readdirSync(dir)) {
+      if (!name.startsWith('last-failure-') || !name.endsWith('.log')) continue
+      const path = join(dir, name)
+      const mtime = statSync(path).mtimeMs
+      if (!best || mtime > best.mtime) best = { path, mtime }
+    }
+  } catch {}
+  return best
+}
+
+/**
+ * `dsh-safe explain`：解读启动失败。输入优先级：
+ *   --file <路径> > --profile <名>（现场试启并解读） >
+ *   最近一次失败记录（包装启动失败时自动持久化的 last-failure-*.log） >
+ *   stdin 管道。纯只读——不碰 patch/台账。
+ * @param {string[]} args
+ * @param {{
+ *   spawn?: typeof spawnSync,
+ *   isTTY?: boolean,
+ *   readStdin?: () => string,
+ *   log?: (line: string) => void,
+ *   write?: (line: string) => void,
+ * }} [hooks] 可注入（测试）
+ * @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`),
+  write = (line) => process.stdout.write(`${line}\n`),
+} = {}) {
+  if (args.includes('-h') || args.includes('--help')) {
+    write(t('helpText', {}))
+    return 0
+  }
+  let file
+  let profile
+  const bootArgs = []
+  let passthrough = false
+  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 === '--profile') profile = args[++i]
+    else if (a.startsWith('--profile=')) profile = args[i].slice('--profile='.length)
+    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 = ''
+  if (file !== undefined) {
+    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
+    }
+    input = stderr
+  } else if (!isTTY) {
+    input = readStdin()
+  } else {
+    const latest = findLatestFailureFile()
+    if (!latest) {
+      log(t('explainNoSource'))
+      return 2
+    }
+    log(t('explainUsingLast', { file: latest.path }))
+    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
+}

package/lib/cli.js

@@ -8,13 +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 { cmdRepair } from './repair.js'
 import { printDoctor } from './doctor.js'
-import { aiEnabled, explainFailure } from './ai.js'
+import { cmdExplain } from './ai.js'
 import { t } from './i18n.js'
 
 const require = createRequire(import.meta.url)
@@ -28,53 +27,6 @@ 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

package/lib/dshpaths.js

@@ -28,6 +28,9 @@ export const homePatchPath = () => join(dshHome(), 'cordis.patch.yml')
 /** dsh-safe 的隔离台账。 */
 export const ledgerFile = () => join(dshHome(), 'dsh-safe', 'quarantine.json')
 
+/** 启动失败 stderr 的持久化文件（按 profile 一份，供 explain 默认解读）。 */
+export const lastFailureFile = (profile) => join(dshHome(), 'dsh-safe', `last-failure-${profile}.log`)
+
 /** dsh-safe 的更新检查时间戳缓存（每天最多提示一次新版）。 */
 export const updateCheckFile = () => join(dshHome(), 'dsh-safe', 'update-check.json')
 

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 [--file <路径>]  用 AI 解读一段启动失败的 stderr（需 DSH_SAFE_AI_KEY）
+  dsh-safe explain [--profile <名> | --file <路径>]  用 AI 解读启动失败（默认解读最近一次失败）
   dsh-safe repair [id] [--profile <名>] [--to <版本>] [-y] [--dry-run]
                                     重装/升级被隔离的插件并自动恢复（限模块解析失败类；省略 id 时只有一条记录则直接修）
   dsh-safe help                     显示本帮助
@@ -108,8 +108,14 @@ const ZH = {
   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} 个可疑坏插件（结果仍走同一隔离管线）',
+  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）',
   excludedByList: '[dsh-safe] 按豁免名单跳过 {label}（不自动禁用）',
   doctorSelf: 'dsh-safe   {version}',
   doctorDsh: 'dsh        {name} {version}',
@@ -153,7 +159,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 [--file <path>]  interpret a failed-boot stderr with AI (needs DSH_SAFE_AI_KEY)
+  dsh-safe explain [--profile <name> | --file <path>]  interpret the last boot failure with AI
   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
@@ -240,8 +246,14 @@ Notes:
   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',
+  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)',
   excludedByList: '[dsh-safe] skipped {label} per the exclusion list (never auto-disabled)',
   doctorSelf: 'dsh-safe   {version}',
   doctorDsh: 'dsh        {name} {version}',

package/lib/wrap.js

@@ -11,9 +11,11 @@
  * 再启动（见 dshpaths.js），其余平台原样 spawn。
  */
 import { spawn } from 'node:child_process'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
 import { summarizeLine, parseFailureReport } from './failures.js'
 import { collectKnownRows, matchFailures } from './knownrows.js'
-import { detectInvocation, resolveDshSpawnTarget } from './dshpaths.js'
+import { detectInvocation, lastFailureFile, resolveDshSpawnTarget } from './dshpaths.js'
 import { writeQuarantine } from './quarantine.js'
 import { loadConfig } from './config.js'
 import { aiEnabled, detectFailureWithAI } from './ai.js'
@@ -24,6 +26,16 @@ const FIRST_PARTY_PREFIX = '@deepseek-ai/'
 
 const isFirstParty = (name) => typeof name === 'string' && name.startsWith(FIRST_PARTY_PREFIX)
 
+/** 启动失败时把捕获的 stderr 存到 last-failure-<profile>.log（供 explain 默认解读与人工翻阅）。 */
+function persistFailure(profile, stderr) {
+  try {
+    if (!stderr?.trim()) return
+    const file = lastFailureFile(profile)
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, stderr)
+  } catch {}
+}
+
 const aiRecoverEnabled = () => process.env.DSH_SAFE_AI_RECOVER === '1' && aiEnabled()
 
 /**
@@ -104,6 +116,7 @@ export async function runWrapped(options) {
       log(t('noProfile'))
       return code
     }
+    if (!dryRun) persistFailure(invocation.profile, stderr)
     const known = collectKnownRows(invocation.profile)
     const report = parseFailureReport(stderr)
     let hits = matchFailures(report, known)
@@ -128,7 +141,10 @@ export async function runWrapped(options) {
       log(t('skipFirstParty', { name: hit.name, id: hit.id }))
     }
     if (!quarantinable.length) {
-      if (!firstParty.length) log(t('nothingFound'))
+      if (!firstParty.length) {
+        log(t('nothingFound'))
+        log(t('explainHint'))
+      }
       return code
     }
     if (attempt >= maxRetries) {

package/package.json

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