@hyzyn/dsh-safe 0.2.0 → 0.3.1

package/README.en.md

@@ -16,13 +16,16 @@ Requires Node >= 20 and a local `dsh` command. Zero runtime dependencies.
 
 ## Quick Start
 
-Just replace `dsh` with `dsh-safe`:
+Just swap `dsh` for `dsh-safe` — `-u` (update-and-boot) is recommended: when dsh has a new version it upgrades and restores quarantined plugins first; when dsh is already latest it behaves exactly like a plain start:
 
 ```bash
-dsh-safe web          # same as dsh web, with auto-quarantine
+dsh-safe -u web       # recommended: update then boot (with auto-quarantine)
+dsh-safe web          # no update check, boot with auto-quarantine
 dsh-safe --profile tui --patch ./extra.yml
 ```
 
+`-u` adds one version check per boot (needs network; on check failure it just warns and boots anyway) — offline or scripted environments can use the second line.
+
 Sample output (shown with a zh locale: a broken plugin is quarantined, then startup retries):
 
 ```
@@ -32,17 +35,23 @@ Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broke
 [dsh-safe] 重试启动…
 ```
 
-## Commands
+## Commands & Options
 
-```
-dsh-safe <dsh args…>              wrap and run dsh
-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 help
-```
+### Subcommands
 
-Wrapper-mode options (must come before the profile / subcommand):
+| Command | Description |
+| --- | --- |
+| `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 help` (`-h` / `--help`) | show help |
+| `dsh-safe --version` (`-V`) | show version |
+
+Every short flag has an equivalent long form (`-u` = `--update`, `-y` = `--yes`, `-h` = `--help`, `-V` = `--version`); single letters use `-`, words use `--`.
+
+### Wrapper-mode options (must come before the first positional argument)
 
 | Option | Description |
 | --- | --- |
@@ -50,7 +59,25 @@ Wrapper-mode options (must come before the profile / subcommand):
 | `--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) |
 
-Messages follow `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE` (`zh*` → Chinese, otherwise English); force with `DSH_SAFE_LANG=zh|en`.
+### update / -u options (after `-u` or `update`; wrapper flags before the dsh args still apply)
+
+| Option | Description |
+| --- | --- |
+| `-y` / `--yes` | Skip the upgrade confirmation (required in non-interactive terminals) |
+| `--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 |
+| `--pm <npm\|pnpm>` | Force the package manager (auto-detected by default) |
+
+### Environment variables
+
+| Variable | Description |
+| --- | --- |
+| `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) |
+
+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`).
 
 ## How It Works
 
@@ -72,6 +99,7 @@ Messages follow `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE` (`zh*` → Chines
 - 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.
+- Windows is best-effort: update / --self / list / restore are adapted (.cmd shim parsing, shelled npm/pnpm invocations), but the wrapped dsh boot's child-process spawn is unverified on Windows.
 
 ## Development
 

package/README.md

@@ -16,13 +16,16 @@ npm install -g @hyzyn/dsh-safe
 
 ## 快速开始
 
-把平时的 `dsh` 换成 `dsh-safe` 即可：
+把平时的 `dsh` 换成 `dsh-safe` 即可，推荐直接用 `-u`（更新并启动）：dsh 有新版本时先升级并恢复被隔离的插件再启动，已最新时和普通启动完全一样：
 
 ```bash
-dsh-safe web          # 等价于 dsh web，带自动隔离
+dsh-safe -u web       # 推荐：更新并启动（含自动隔离）
+dsh-safe web          # 不检查更新，直接带自动隔离启动
 dsh-safe --profile tui --patch ./extra.yml
 ```
 
+`-u` 每次启动多做一次版本检查（需要联网，检查失败只告警、照常启动）；离线或脚本环境用第二行即可。
+
 输出示例（坏插件被自动隔离后重试）：
 
 ```
@@ -32,17 +35,23 @@ Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broke
 [dsh-safe] 重试启动…
 ```
 
-## 命令
+## 命令与参数
 
-```
-dsh-safe <dsh 参数…>             包装运行 dsh
-dsh-safe list [--profile <名>]    查看隔离名单（缺省列出全部 profile）
-dsh-safe restore --profile <名> (--id <id> | --all) [--dry-run]
-                                  恢复被自动禁用的插件（升级修复后使用）
-dsh-safe help
-```
+### 子命令
 
-包装模式选项（必须写在 profile / 子命令之前）：
+| 命令 | 说明 |
+| --- | --- |
+| `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 help`（`-h` / `--help`） | 显示帮助 |
+| `dsh-safe --version`（`-V`） | 显示版本 |
+
+短选项都有等价的长形式（`-u` = `--update`、`-y` = `--yes`、`-h` = `--help`、`-V` = `--version`）；单字母用 `-`，多字母用 `--`。
+
+### 包装模式选项（必须写在第一个位置参数之前）
 
 | 选项 | 说明 |
 | --- | --- |
@@ -50,7 +59,25 @@ dsh-safe help
 | `--max-retries <n>` | 自动隔离后最多重试启动的次数（默认 2；`0` 表示不隔离只透传） |
 | `--allow-first-party` | 允许自动禁用 `@deepseek-ai/*` 第一方插件（默认跳过，需手动处理） |
 
-提示信息语言跟随 `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE`（`zh*` 为中文，其余英文），也可用环境变量 `DSH_SAFE_LANG=zh|en` 强制指定。
+### update / -u 选项（写在 `-u` 或 `update` 之后；其前的包装旗标照常生效）
+
+| 选项 | 说明 |
+| --- | --- |
+| `-y` / `--yes` | 跳过升级确认（非交互终端必须显式加 `-y`） |
+| `--to <版本>` | 指定 dsh 的目标版本，也是回滚方式（显式允许降级）；dsh-safe 自身始终升到最新 |
+| `--self` | 只更新 dsh-safe 自身，不动 dsh 与隔离状态 |
+| `--no-restore` | 升级 dsh 后不自动恢复被隔离的插件 |
+| `--pm <npm\|pnpm>` | 强制指定包管理器（缺省自动探测） |
+
+### 环境变量
+
+| 变量 | 说明 |
+| --- | --- |
+| `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 update` 自动探测 dsh 的包名与安装方式（npm / pnpm 全局安装）、对比最新版本后代跑升级，完成后自动恢复所有被隔离的插件——新 dsh 下仍不兼容的会在下次启动时再次被自动隔离。日常把 `dsh-safe -u web` 当启动命令即可：dsh 已是最新时直接启动（仅一次版本检查），有更新时先升级并恢复隔离再启动，更新检查失败只告警、照常启动。`-u` 后可接 update 的选项（如 `-u -y web`）与包装旗标（如 `-u --max-retries 0 web`）。
 
 ## 工作原理
 
@@ -72,6 +99,7 @@ dsh-safe help
 - `--patch` 覆盖层里插入的行不参与对照表（对照表只扫 profile patch、home patch 与 bundle patch）。
 - 为了捕获 stderr，包装器把 dsh 的 stderr 接到管道（内容仍实时回显到终端）；stdout/stdin 直通不受影响。
 - 本项目针对 dsh 0.1.x 的报错格式做匹配；dsh 大版本升级后格式变化时需要同步更新解析器。
+- Windows 为尽力支持：update / --self / list / restore 已适配（.cmd shim 解析、shell 方式调用 npm/pnpm），包装启动 dsh 的子进程方式未在 Windows 验证。
 
 ## 开发
 

package/lib/cli.js

@@ -10,6 +10,7 @@
 import { createRequire } from 'node:module'
 import { loadLedger, restoreQuarantine } from './quarantine.js'
 import { runWrapped } from './wrap.js'
+import { cmdUpdate, cmdUpdateAndBoot, maybeNotifySelfUpdate } from './update.js'
 import { t } from './i18n.js'
 
 const require = createRequire(import.meta.url)
@@ -119,9 +120,17 @@ 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 === '-u' || cmd === '--update') return cmdUpdateAndBoot(argv.slice(1), { boot: runWrapperMode })
 
   // 包装模式：剥掉 dsh-safe 自己的旗标（必须出现在第一个位置参数之前），
   // 其余原样转发给 dsh。
+  return runWrapperMode(argv)
+}
+
+/** 包装模式：剥离 dsh-safe 的旗标后运行 dsh；-u 升级完成后的启动也走这里。 */
+async function runWrapperMode(argv) {
+  maybeNotifySelfUpdate()
   const forwardArgs = []
   let dryRun = false
   let maxRetries = 2

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')
 
+/** dsh-safe 的更新检查时间戳缓存（每天最多提示一次新版）。 */
+export const updateCheckFile = () => join(dshHome(), 'dsh-safe', 'update-check.json')
+
 /** 读文件，不存在或读不了返回 undefined。 */
 export const readIfExists = (path) => {
   try {

package/lib/i18n.js

@@ -16,9 +16,12 @@ const ZH = {
 
 用法:
   dsh-safe <dsh 参数…>             包装运行 dsh，例: dsh-safe web
+  dsh-safe -u [<dsh 参数…>]         先升级 dsh（已最新则跳过），再启动
   dsh-safe list [--profile <名>]    查看隔离名单（缺省列出全部 profile）
   dsh-safe restore --profile <名> (--id <id> | --all) [--dry-run]
                                     恢复被自动禁用的插件（升级修复后使用）
+  dsh-safe update [-y] [--to <版本>] [--self] [--no-restore] [--pm npm|pnpm]
+                                    升级 dsh 与 dsh-safe 自身，并自动恢复被隔离的插件
   dsh-safe help                     显示本帮助
   dsh-safe --version                显示版本
 
@@ -32,6 +35,8 @@ const ZH = {
     恢复用 dsh-safe restore，或手动删除区块。
   - 只隔离"启动期"失败（模块解析失败 / apply 抛错 / 等不到注入服务）；
     运行期的未捕获异常仍由 dsh 自身的 fail-loud 策略处理。
+  - update/-u 会同时检查 dsh 与 dsh-safe 自身；--self 只更新 dsh-safe。
+  - 启动时每天最多提示一次 dsh-safe 新版；DSH_SAFE_NO_UPDATE_CHECK=1 关闭。
   - 输出语言跟随 LC_ALL / LC_MESSAGES / LANG / LANGUAGE（zh* 中文，其余英文）；
     可用环境变量 DSH_SAFE_LANG=zh|en 强制指定。
 `,
@@ -64,6 +69,32 @@ const ZH = {
   willDisable: '（dry-run）将禁用',
   reasonIndent: '           原因: {reason}',
   retrying: '[dsh-safe] 重试启动…',
+
+  // ---- update.js ----
+  updateDshNotFound: '[dsh-safe] 在 PATH 上找不到 dsh 命令，无法升级。',
+  updatePlan: '[dsh-safe] {label} {name} {old} → {target} ({pm})',
+  updateInstallCmd: '[dsh-safe] 即将执行: {command}',
+  updateConfirm: '继续? [y/N] ',
+  updateNonInteractive: '[dsh-safe] 当前不是交互终端，无法确认；加 -y 跳过确认后重试。',
+  updateAborted: '[dsh-safe] 已取消。',
+  updateInstalling: '[dsh-safe] 正在升级 dsh…',
+  updateInstallFail: '[dsh-safe] 升级失败（退出码 {code}），未恢复任何隔离插件。',
+  updateLatestFetchFail: '[dsh-safe] 无法获取 {name} 的最新版本（{pm} view 失败）；可用 --to <版本> 指定目标版本。',
+  updateSkipCheckWarn: '[dsh-safe] 无法检查 dsh 更新（{pm} view 失败），跳过升级直接启动。',
+  updateAlreadyLatest: '[dsh-safe] 已是最新，无需更新（dsh {dsh} / dsh-safe {self}）。',
+  updateDone: '[dsh-safe] dsh 已更新: {old} → {new}',
+  updateVerifyWarn: '[dsh-safe] 警告：升级后无法重新解析 dsh 版本，请自行确认。',
+  updateNothingToRestore: '[dsh-safe] 没有需要恢复的隔离记录。',
+  updateRestoredProfile: '[dsh-safe] 已恢复 {count} 个被隔离的插件 (profile: {profile})',
+  updateRestoreSkipped: '[dsh-safe] 已按 --no-restore 跳过恢复；可稍后用 dsh-safe restore --profile <名> --all 恢复。',
+  updateVerifyHint: '[dsh-safe] 请启动 dsh 验证；仍不兼容的插件会自动再次隔离。',
+  updateRollbackHint: '[dsh-safe] 如需回滚: dsh-safe update --to {version}',
+  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）。',
 }
 
 const EN = {
@@ -77,9 +108,12 @@ 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 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]
+                                    upgrade dsh and dsh-safe itself, auto-restore quarantined plugins
   dsh-safe help                     show this help
   dsh-safe --version                show version
 
@@ -94,6 +128,9 @@ Notes:
   - Only startup-phase failures are quarantined (module resolution / apply throw /
     missing injected service); runtime uncaught exceptions stay under dsh's own
     fail-loud policy.
+  - update/-u checks both dsh and dsh-safe itself; --self updates dsh-safe only.
+  - A new-version notice for dsh-safe is shown at most once a day on boot;
+    disable it with DSH_SAFE_NO_UPDATE_CHECK=1.
   - Output language follows LC_ALL / LC_MESSAGES / LANG / LANGUAGE (zh* → Chinese,
     otherwise English); force it with DSH_SAFE_LANG=zh|en.
 `,
@@ -127,6 +164,32 @@ Notes:
   willDisable: '(dry-run) would disable',
   reasonIndent: '           reason: {reason}',
   retrying: '[dsh-safe] retrying…',
+
+  // ---- update.js ----
+  updateDshNotFound: '[dsh-safe] could not find the `dsh` command on PATH; nothing to upgrade.',
+  updatePlan: '[dsh-safe] {label} {name} {old} → {target} ({pm})',
+  updateInstallCmd: '[dsh-safe] about to run: {command}',
+  updateConfirm: 'continue? [y/N] ',
+  updateNonInteractive: '[dsh-safe] not an interactive terminal; re-run with -y to skip the confirmation.',
+  updateAborted: '[dsh-safe] cancelled.',
+  updateInstalling: '[dsh-safe] upgrading dsh…',
+  updateInstallFail: '[dsh-safe] upgrade failed (exit code {code}); no quarantined plugins were restored.',
+  updateLatestFetchFail: '[dsh-safe] could not fetch the latest version of {name} ({pm} view failed); specify a target with --to <version>.',
+  updateSkipCheckWarn: '[dsh-safe] could not check for dsh updates ({pm} view failed); starting without upgrading.',
+  updateAlreadyLatest: '[dsh-safe] already up to date (dsh {dsh} / dsh-safe {self}); nothing to update.',
+  updateDone: '[dsh-safe] dsh updated: {old} → {new}',
+  updateVerifyWarn: '[dsh-safe] warning: could not re-resolve the dsh version after the upgrade; please verify manually.',
+  updateNothingToRestore: '[dsh-safe] no quarantine records to restore.',
+  updateRestoredProfile: '[dsh-safe] restored {count} quarantined plugin(s) (profile: {profile})',
+  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}',
+  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).',
 }
 
 const CATALOG = { zh: ZH, en: EN }

package/lib/update.js

@@ -0,0 +1,423 @@
+/**
+ * @hyzyn/dsh-safe — `dsh-safe update`：升级 dsh 并自动恢复被隔离的插件。
+ *
+ * 自动探测：PATH 上的 dsh 可执行文件 realpath → 向上找最近的 package.json
+ * 得到包名与当前版本；包管理器按 realpath 是否落在 pnpm 全局根下判定
+ * （PATH 上有 pnpm 时探测，否则默认 npm），--pm 可强制指定。
+ * 升级完成后遍历台账恢复全部被隔离的插件（新 dsh 下仍不兼容的会在
+ * 下次启动时再次被自动隔离），并提示回滚方式。
+ */
+import { accessSync, constants, mkdirSync, realpathSync, writeFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+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 { t } from './i18n.js'
+
+const err = (line) => process.stderr.write(`${line}\n`)
+const out = (line) => process.stdout.write(`${line}\n`)
+
+const WIN32 = process.platform === 'win32'
+
+/**
+ * 运行包管理器命令并捕获输出（view / pnpm root -g）。
+ * Windows 上 npm/pnpm 是 .cmd 批处理，Node 禁止无 shell 地 spawn（EINVAL），
+ * 必须走 cmd.exe；传参只含已校验的包名与版本号（--to 有 ^[\w.+-]+$ 校验）。
+ */
+function spawnPmCapture(bin, args) {
+  return WIN32
+    ? spawnSync(bin, args, { encoding: 'utf8', shell: true })
+    : spawnSync(bin, args, { encoding: 'utf8' })
+}
+
+/** 运行包管理器命令并透传 stdio（install）。Windows 处理同上。 */
+function spawnPmInherit(bin, args) {
+  return WIN32
+    ? spawnSync(bin, args, { shell: true, stdio: 'inherit' })
+    : spawnSync(bin, args, { stdio: 'inherit' })
+}
+
+/** Windows 上全局 bin 的可执行是 .cmd/.exe 拷贝而非 symlink，候选名不同。 */
+function binCandidates(name) {
+  return WIN32 ? [`${name}.cmd`, `${name}.exe`, `${name}.ps1`, name] : [name]
+}
+
+const readJsonIfExists = (path) => {
+  const raw = readIfExists(path)
+  if (raw === undefined) return undefined
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return undefined
+  }
+}
+
+/** 在 PATH 上找可执行文件（Windows 展开为 .cmd/.exe/.ps1/裸名多候选），返回绝对路径或 null。 */
+function whichCmd(name) {
+  for (const dir of (process.env.PATH ?? '').split(delimiter)) {
+    if (!dir) continue
+    for (const candidate of binCandidates(name).map((n) => join(dir, n))) {
+      try {
+        accessSync(candidate, constants.X_OK)
+        return candidate
+      } catch {}
+    }
+  }
+  return null
+}
+
+/** 从某个目录向上找最近的 package.json，返回 { name, version, pkgDir }。 */
+function resolvePackageFromDir(dir) {
+  for (;;) {
+    const pkg = readJsonIfExists(join(dir, 'package.json'))
+    if (pkg && typeof pkg.name === 'string' && pkg.name) {
+      return { name: pkg.name, version: typeof pkg.version === 'string' ? pkg.version : '0.0.0', pkgDir: dir }
+    }
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/**
+ * 从可执行文件解析所属包：symlink → realpath 后向上找 package.json（macOS/Linux
+ * 的 npm/pnpm 全局 bin 都是链接）；独立 shim 文件（Windows 的 .cmd/sh 拷贝）→
+ * 解析其内容里内嵌的 node_modules 入口路径。
+ */
+function resolvePackageFromBinFile(file) {
+  let real
+  try {
+    real = realpathSync(file)
+  } catch {
+    return null
+  }
+  const viaWalkUp = resolvePackageFromDir(dirname(real))
+  if (viaWalkUp) return viaWalkUp
+  return resolvePackageFromShim(file)
+}
+
+/** 解析 npm/pnpm 的 cmd/ps1/sh shim：内容里都内嵌 node_modules/<pkg> 的入口路径。 */
+export function resolvePackageFromShim(shimPath) {
+  const content = readIfExists(shimPath)
+  if (!content) return null
+  const m = /node_modules[\\\/]((?:@[^\\\/"'`\s]+[\\\/])?[^\\\/"'`\s]+)/.exec(content)
+  if (!m) return null
+  const name = m[1].replace(/[\\\/]/g, '/')
+  // 候选 pkgDir：npm 全局布局（shim 同级的 node_modules）与 pnpm 全局根
+  const candidates = [join(dirname(shimPath), 'node_modules', ...name.split('/'))]
+  const pnpmBin = whichCmd('pnpm')
+  if (pnpmBin) {
+    const { status, stdout } = spawnPmCapture(pnpmBin, ['root', '-g'])
+    const root = status === 0 ? (stdout ?? '').trim() : ''
+    if (root) candidates.push(join(root, ...name.split('/')))
+  }
+  for (const dir of candidates) {
+    const pkg = readJsonIfExists(join(dir, 'package.json'))
+    if (pkg?.name === name) {
+      return { name, version: typeof pkg.version === 'string' ? pkg.version : '0.0.0', pkgDir: dir }
+    }
+  }
+  return null
+}
+
+/**
+ * 解析 PATH 上的 dsh。
+ * @returns {{ name: string, version: string, pkgDir: string } | null}
+ */
+export function resolveDshPackage() {
+  const bin = whichCmd('dsh')
+  if (!bin) return null
+  return resolvePackageFromBinFile(bin)
+}
+
+/**
+ * 解析正在运行的 dsh-safe 自身（argv[1]，npm/pnpm 全局 bin symlink 或仓库内直跑均适用）。
+ * @returns {{ name: string, version: string, pkgDir: string } | null}
+ */
+export function resolveSelfPackage() {
+  const entry = process.argv[1]
+  if (!entry) return null
+  return resolvePackageFromBinFile(entry)
+}
+
+/** 判断 dsh 的安装方式：落在 pnpm 全局根下则为 pnpm，否则 npm。 */
+export function detectPm(pkgDir) {
+  const pnpmBin = whichCmd('pnpm')
+  if (!pnpmBin) return 'npm'
+  const { status, stdout } = spawnPmCapture(pnpmBin, ['root', '-g'])
+  const root = status === 0 ? (stdout ?? '').trim() : ''
+  if (root && (pkgDir === root || pkgDir.startsWith(`${root}/`) || pkgDir.startsWith(`${root}\\`))) return 'pnpm'
+  return 'npm'
+}
+
+/** npm view 查最新版本（只查 registry，与安装方式无关），失败返回 null。 */
+function fetchLatestVersion(name) {
+  const { status, stdout } = spawnPmCapture(whichCmd('npm') ?? 'npm', ['view', name, 'version'])
+  const version = status === 0 ? (stdout ?? '').trim() : ''
+  return /^[\w.+-]+$/.test(version) ? version : null
+}
+
+/**
+ * 比较 semver 风格版本：a > b 返回 true（零依赖的够用版）。
+ * 核心段按数字逐段比较；核心相同时正式版 > 预发布，预发布逐段比较（数字段按数值）。
+ * 自动检查用它避免"registry 落后于本地开发版"时的自降级；--to 显式指定不走这里，允许降级回滚。
+ */
+export function isNewerVersion(a, b) {
+  if (a === b) return false
+  const [aCore, aPre] = String(a).split('-', 2)
+  const [bCore, bPre] = String(b).split('-', 2)
+  const pa = aCore.split('.').map((n) => parseInt(n, 10) || 0)
+  const pb = bCore.split('.').map((n) => parseInt(n, 10) || 0)
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] ?? 0
+    const y = pb[i] ?? 0
+    if (x !== y) return x > y
+  }
+  if (aPre && !bPre) return false
+  if (!aPre && bPre) return true
+  const qa = (aPre ?? '').split('.')
+  const qb = (bPre ?? '').split('.')
+  for (let i = 0; i < Math.max(qa.length, qb.length); i++) {
+    const x = qa[i]
+    const y = qb[i]
+    if (x === undefined) return false
+    if (y === undefined) return true
+    const numericX = /^\d+$/.test(x)
+    const numericY = /^\d+$/.test(y)
+    if (numericX && numericY) {
+      const d = Number(x) - Number(y)
+      if (d) return d > 0
+    } else if (x !== y) {
+      return x > y
+    }
+  }
+  return false
+}
+
+/**
+ * @param {string[]} args update 子命令参数
+ * @returns {Promise<number>} 退出码
+ */
+export async function cmdUpdate(args) {
+  if (args.includes('-h') || args.includes('--help')) {
+    out(t('helpText', {}))
+    return 0
+  }
+  const { opts, error } = parseUpdateArgs(args)
+  if (error) {
+    err(t(error.key, error.params))
+    return 2
+  }
+  return updateAndMaybeBoot(opts, null, {})
+}
+
+/**
+ * `-u`/`--update` 模式：前缀解析 update 选项（-y/--to/--pm/--no-restore），
+ * 第一个不属于 update 的参数起就是 dsh 启动参数（可再带包装旗标）。
+ * 启动优先：更新检查失败只告警并照常启动；升级失败/用户取消则不启动。
+ * @param {string[]} args
+ * @param {{ boot?: (args: string[]) => Promise<number> }} hooks cli 传入的包装启动
+ */
+export async function cmdUpdateAndBoot(args, { boot } = {}) {
+  if (args.includes('-h') || args.includes('--help')) {
+    out(t('helpText', {}))
+    return 0
+  }
+  const { opts, rest, error } = parseLeadingUpdateArgs(args)
+  if (error) {
+    err(t(error.key, error.params))
+    return 2
+  }
+  return updateAndMaybeBoot(opts, rest.length ? rest : null, { boot })
+}
+
+/**
+ * 更新主体；bootArgs 非空时更新成功（或已最新/检查失败）后继续启动。
+ * 默认同时检查 dsh 与 dsh-safe 自身，谁旧升谁（一条安装命令）；--self 只更新自身。
+ * @param {{ to?: string, yes?: boolean, restore?: boolean, pm?: string, selfOnly?: boolean }} opts
+ * @param {string[] | null} bootArgs
+ * @param {{ boot?: (args: string[]) => Promise<number> }} hooks
+ */
+async function updateAndMaybeBoot(opts, bootArgs, { boot } = {}) {
+  const dshPkg = opts.selfOnly ? null : resolveDshPackage()
+  const selfPkg = resolveSelfPackage()
+  if (!dshPkg && !selfPkg) {
+    err(t('updateDshNotFound'))
+    return 1
+  }
+  const pm = opts.pm ?? (dshPkg ? detectPm(dshPkg.pkgDir) : detectPm(selfPkg.pkgDir))
+
+  // 组装更新计划：[{ pkg, target }]
+  const plans = []
+  if (dshPkg) {
+    if (opts.to) {
+      if (opts.to !== dshPkg.version) plans.push({ pkg: dshPkg, target: opts.to })
+    } else {
+      const latest = fetchLatestVersion(dshPkg.name)
+      if (!latest) {
+        if (bootArgs) {
+          err(t('updateSkipCheckWarn', { pm }))
+          return boot(bootArgs)
+        }
+        err(t('updateLatestFetchFail', { name: dshPkg.name, pm }))
+        return 1
+      }
+      if (isNewerVersion(latest, dshPkg.version)) plans.push({ pkg: dshPkg, target: latest })
+    }
+  }
+  if (selfPkg && !opts.to) {
+    const selfLatest = fetchLatestVersion(selfPkg.name)
+    if (selfLatest && isNewerVersion(selfLatest, selfPkg.version)) plans.push({ pkg: selfPkg, target: selfLatest })
+  }
+
+  if (!plans.length) {
+    if (bootArgs) return boot(bootArgs)
+    err(t('updateAlreadyLatest', { dsh: dshPkg?.version ?? '未安装', self: selfPkg?.version ?? '未知' }))
+    return 0
+  }
+
+  const installCmd = pm === 'pnpm' ? 'pnpm' : 'npm'
+  const specs = plans.map((p) => `${p.pkg.name}@${p.target}`)
+  const installArgs =
+    pm === 'pnpm' ? ['add', '-g', ...specs] : ['install', '-g', ...specs]
+  for (const p of plans) {
+    err(t('updatePlan', { label: p.pkg === dshPkg ? 'dsh' : 'dsh-safe', name: p.pkg.name, old: p.pkg.version, target: p.target, pm }))
+  }
+  err(t('updateInstallCmd', { command: `${installCmd} ${installArgs.join(' ')}` }))
+  if (!opts.yes) {
+    if (!process.stdin.isTTY) {
+      err(t('updateNonInteractive'))
+      return 1
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stderr })
+    const answer = (await rl.question(t('updateConfirm'))).trim().toLowerCase()
+    rl.close()
+    if (answer !== 'y' && answer !== 'yes') {
+      err(t('updateAborted'))
+      return 0
+    }
+  }
+
+  err(t('updateInstalling'))
+  const { status } = spawnPmInherit(whichCmd(installCmd) ?? installCmd, installArgs)
+  if (status !== 0) {
+    err(t('updateInstallFail', { code: status ?? '?' }))
+    return status ?? 1
+  }
+
+  let dshUpdated = false
+  for (const p of plans) {
+    if (p.pkg === dshPkg) {
+      dshUpdated = true
+      const fresh = resolveDshPackage()
+      if (!fresh?.version) err(t('updateVerifyWarn'))
+      else err(t('updateDone', { old: p.pkg.version, new: fresh.version }))
+    } else {
+      err(t('selfUpdateLagHint', { old: p.pkg.version, new: p.target }))
+    }
+  }
+
+  if (opts.restore && dshUpdated) {
+    const ledger = loadLedger()
+    const profiles = Object.keys(ledger.profiles).filter((p) => (ledger.profiles[p] ?? []).length)
+    if (!profiles.length) {
+      out(t('updateNothingToRestore'))
+    } else {
+      for (const profile of profiles) {
+        const { restored } = restoreQuarantine(profile, 'all', false)
+        if (restored.length) out(t('updateRestoredProfile', { profile, count: restored.length }))
+      }
+      err(t('updateVerifyHint'))
+    }
+  } else if (dshUpdated && !opts.restore) {
+    err(t('updateRestoreSkipped'))
+  }
+  if (dshUpdated) {
+    const oldDsh = plans.find((p) => p.pkg === dshPkg)?.pkg.version
+    if (oldDsh) err(t('updateRollbackHint', { version: oldDsh }))
+  }
+  if (bootArgs) return boot(bootArgs)
+  return 0
+}
+
+/** 解析 update 子命令参数；出错返回 { error: { key, params? } } 供 i18n。 */
+function parseUpdateArgs(args) {
+  const opts = { to: undefined, yes: false, restore: true, pm: undefined, selfOnly: 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 === '--to') {
+      const v = args[++i]
+      if (v === undefined) return { error: { key: 'updateUnknownFlag', params: { arg: '--to' } } }
+      opts.to = v
+    } else if (a.startsWith('--to=')) opts.to = a.slice('--to='.length)
+    else if (a === '--pm') {
+      const v = args[++i]
+      if (v === undefined) return { error: { key: 'updateUnknownFlag', params: { arg: '--pm' } } }
+      opts.pm = v
+    } else if (a.startsWith('--pm=')) opts.pm = a.slice('--pm='.length)
+    else return { error: { key: 'updateUnknownFlag', params: { arg: a } } }
+  }
+  if (opts.pm !== undefined && opts.pm !== 'npm' && opts.pm !== 'pnpm') {
+    return { error: { key: 'updatePmInvalid' } }
+  }
+  if (opts.to !== undefined && !/^[\w.+-]+$/.test(opts.to)) {
+    return { error: { key: 'updateToInvalid' } }
+  }
+  return { opts }
+}
+
+/**
+ * `-u` 模式的前缀解析：从头吃掉 update 选项，第一个不认识的参数起就是
+ * dsh 启动参数（宽松处理——不像子命令那样对未知参数报错）。
+ */
+function parseLeadingUpdateArgs(args) {
+  const opts = { to: undefined, yes: false, restore: true, pm: undefined, selfOnly: 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 === '--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]
+    else if (a.startsWith('--pm=')) opts.pm = a.slice('--pm='.length)
+    else break
+  }
+  const rest = args.slice(i)
+  if (opts.pm !== undefined && opts.pm !== 'npm' && opts.pm !== 'pnpm') {
+    return { error: { key: 'updatePmInvalid' } }
+  }
+  if (opts.to !== undefined && !/^[\w.+-]+$/.test(opts.to)) {
+    return { error: { key: 'updateToInvalid' } }
+  }
+  return { opts, rest }
+}
+
+/**
+ * 每日一次的 dsh-safe 新版提示（只在包装启动路径调用；update/-u 有自己的检查）。
+ * 时间戳缓存于 $DSH_HOME/dsh-safe/update-check.json；任何失败都完全静默。
+ */
+export function maybeNotifySelfUpdate() {
+  try {
+    if (process.env.DSH_SAFE_NO_UPDATE_CHECK === '1') return
+    const selfPkg = resolveSelfPackage()
+    if (!selfPkg) return
+    const file = updateCheckFile()
+    const last = readJsonIfExists(file)
+    if (last?.lastCheckAt && Date.now() - Date.parse(last.lastCheckAt) < 24 * 60 * 60 * 1000) return
+    try {
+      mkdirSync(dirname(file), { recursive: true })
+      writeFileSync(file, `${JSON.stringify({ lastCheckAt: new Date().toISOString() }, null, 2)}\n`)
+    } catch {}
+    const latest = fetchLatestVersion(selfPkg.name)
+    if (latest && isNewerVersion(latest, selfPkg.version)) {
+      err(t('updateNotify', { new: latest, old: selfPkg.version }))
+      err(t('updateNotifyHow', { name: selfPkg.name }))
+    }
+  } catch {}
+}

package/package.json

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