@hyzyn/dsh-safe 0.8.0 → 0.9.0

package/README.md

@@ -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 <路径>]`**：默认解读最近一次启动失败（失败时 stderr 自动持久化到 `$DSH_HOME/dsh-safe/last-failure-<profile>.log`，人也可直接翻阅）；`--profile` 现场试启该 profile 并解读（60 秒超时）；`--file`/stdin 读任意日志。纯只读，不碰 patch/台账。
+- **`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

@@ -110,9 +110,9 @@ export async function detectFailureWithAI(stderr, knownRows) {
 }
 
 /** 试启一个 profile 并捕获 stderr（60s 超时；超时留下的部分 stderr 也可解读）。 */
-function bootProfileForExplain(profile, { spawn }) {
+function bootProfileForExplain(profile, extraArgs, { spawn }) {
   const target = resolveDshSpawnTarget('dsh')
-  const { status, stderr } = spawn(target.file, [...target.prefix, '--profile', profile], {
+  const { status, stderr } = spawn(target.file, [...target.prefix, '--profile', profile, ...extraArgs], {
     stdio: ['ignore', 'ignore', 'pipe'],
     env: process.env,
     shell: target.shell,
@@ -165,11 +165,25 @@ export async function cmdExplain(args, {
   }
   let file
   let profile
+  const bootArgs = []
+  let passthrough = false
   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)
-    else if (args[i] === '--profile') profile = args[++i]
-    else if (args[i].startsWith('--profile=')) profile = args[i].slice('--profile='.length)
+    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'))
@@ -185,7 +199,7 @@ export async function cmdExplain(args, {
     }
   } else if (profile !== undefined) {
     log(t('explainBooting', { profile }))
-    const { code, stderr } = bootProfileForExplain(profile, { spawn })
+    const { code, stderr } = bootProfileForExplain(profile, bootArgs, { spawn })
     if (code === 0 || !stderr?.trim()) {
       log(t('explainBootOk', { profile }))
       return 0

package/lib/i18n.js

@@ -111,9 +111,11 @@ const ZH = {
   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}',
@@ -247,9 +249,11 @@ Notes:
   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/package.json

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