@hyzyn/dsh-safe 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hyzyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# dsh-safe · dsh 启动保险丝
+
+中文 | [English](#english)
+
+DeepSeek Harness（DSH）的社区插件与 dsh 运行时不兼容时，`dsh web` 会**整体启动失败**——加载器把所有 patch 层拉平成同一棵加载树，任何一个插件 import 失败、`apply` 抛错、或等不到注入的服务，启动审计就会拒绝整棵树，进程退出。此时只能手动编辑 `cordis.patch.yml` 把坏插件禁用。
+
+**dsh-safe 把这个手动动作自动化了**：包装运行 `dsh`，启动失败时从报错里识别坏插件，在 profile patch 里把对应行置为 `disabled: true`（记录进隔离台账），然后自动重试。坏插件只影响自己，dsh 照常启动。
+
+## 安装
+
+```bash
+npm install -g @hyzyn/dsh-safe
+```
+
+要求 Node >= 20，本机已安装 `dsh` 命令。零运行时依赖。
+
+## 快速开始
+
+把平时的 `dsh` 换成 `dsh-safe` 即可：
+
+```bash
+dsh-safe web          # 等价于 dsh web，带自动隔离
+dsh-safe --profile tui --patch ./extra.yml
+```
+
+输出示例（坏插件被自动隔离后重试）：
+
+```
+Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broken (@smoke/broken-impl): Cannot find package '@smoke/broken-impl' ...
+[dsh-safe] 已禁用 @smoke/broken-impl (id: smoke-broken) → /Users/me/.dsh/profiles/web/cordis.patch.yml
+           原因: Error: failed to import loader entry smoke-broken (@smoke/broken-impl): Cannot find package …
+[dsh-safe] 重试启动…
+```
+
+## 命令
+
+```
+dsh-safe <dsh 参数…>             包装运行 dsh
+dsh-safe list [--profile <名>]    查看隔离名单（缺省列出全部 profile）
+dsh-safe restore --profile <名> (--id <id> | --all) [--dry-run]
+                                  恢复被自动禁用的插件（升级修复后使用）
+dsh-safe help
+```
+
+包装模式选项（必须写在 profile / 子命令之前）：
+
+| 选项 | 说明 |
+| --- | --- |
+| `--dry-run` | 只解析与报告，不修改任何文件 |
+| `--max-retries <n>` | 自动隔离后最多重试启动的次数（默认 2；`0` 表示不隔离只透传） |
+| `--allow-first-party` | 允许自动禁用 `@deepseek-ai/*` 第一方插件（默认跳过，需手动处理） |
+
+## 工作原理
+
+1. **识别失败**：dsh 启动失败时，stderr 里有四类特征（`plugin(s) failed to load: …`、`N entries did not activate` 逐行失败、`failed to apply/import loader entry <id> (<name>)`、外层栈 `…#<entryId>`）。dsh-safe 从中提取坏插件的包名与行 id。
+2. **对照真实行**：扫描 profile patch、`$DSH_HOME/cordis.patch.yml`（home 层）与各 bundle 的 patch，得到「行 id ↔ 插件包名」对照表；只禁用真实存在的行，避免误伤。
+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 热生效）。
+
+## 安全边界
+
+- **第一方保护**：`@deepseek-ai/*` 的行默认跳过（禁用 `dsh-web-app` 这类插件会让 dsh 失去核心能力），需要 `--allow-first-party` 才会动。
+- **只动启动期失败**：模块解析失败 / `apply` 抛错 / 等不到注入服务。运行期的未捕获异常仍由 dsh 自身的 fail-loud 策略处理，不属于启动隔离范围。
+- **可审计**：每次写入都带原因与时间戳；`--dry-run` 可以先看会禁用谁。
+- **原样透传**：识别不出坏插件、超过重试上限、`dsh plugin`（pnpm 转发）等情况，退出码原样透传，不做任何修改。
+
+## 已知限制
+
+- patch 文件本身 YAML 解析错误（如手改坏了）时无法识别插件，只会透传。
+- `--patch` 覆盖层里插入的行不参与对照表（对照表只扫 profile patch、home patch 与 bundle patch）。
+- 为了捕获 stderr，包装器把 dsh 的 stderr 接到管道（内容仍实时回显到终端）；stdout/stdin 直通不受影响。
+- 本项目针对 dsh 0.1.x 的报错格式做匹配；dsh 大版本升级后格式变化时需要同步更新解析器。
+
+## 开发
+
+```bash
+npm test        # node:test 单元测试 + 假 dsh 集成测试
+```
+
+<a name="english"></a>
+## English
+
+**dsh-safe** is a fuse for DeepSeek Harness (DSH) startup: when a community plugin is incompatible with the running dsh version, `dsh web` normally fails to boot entirely — one broken plugin rejects the whole loader tree. dsh-safe wraps any `dsh` invocation, parses the startup-failure diagnostics on stderr, marks the offending patch rows as `disabled: true` inside a managed block in your profile patch file (keeping all user content and comments), records the action in a quarantine ledger, and retries. First-party `@deepseek-ai/*` plugins are protected by default; `dsh-safe restore --profile <name> --all` re-enables quarantined rows after you upgrade the plugin.
+
+```bash
+npm install -g @hyzyn/dsh-safe
+dsh-safe web                 # run dsh web with auto-quarantine
+dsh-safe list                # show quarantined plugins
+dsh-safe restore --profile web --all
+```
+
+## License
+
+[MIT](./LICENSE)

package/bin/dsh-safe.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../lib/cli.js'
+
+process.exitCode = await main(process.argv.slice(2))

package/lib/cli.js

@@ -0,0 +1,186 @@
+/**
+ * @hyzyn/dsh-safe — 命令行入口。
+ *
+ * 用法：
+ *   dsh-safe <dsh 参数…>        包装运行 dsh（dsh-safe 的旗标必须写在最前）
+ *   dsh-safe list [--profile <名>]
+ *   dsh-safe restore --profile <名> (--id <id>… | --all) [--dry-run]
+ *   dsh-safe help | --version
+ */
+import { createRequire } from 'node:module'
+import { loadLedger, restoreQuarantine } from './quarantine.js'
+import { runWrapped } from './wrap.js'
+
+const require = createRequire(import.meta.url)
+const { version } = require('../package.json')
+
+const HELP = `dsh-safe ${version} — dsh 启动保险丝
+
+社区插件与 dsh 运行时不兼容会让 dsh 整体启动失败。dsh-safe 包装运行 dsh：
+启动失败时从报错里识别坏插件，在 profile patch 里把对应行置为 disabled
+（记录进隔离台账），然后自动重试。
+
+用法:
+  dsh-safe <dsh 参数…>             包装运行 dsh，例: dsh-safe web
+  dsh-safe list [--profile <名>]    查看隔离名单（缺省列出全部 profile）
+  dsh-safe restore --profile <名> (--id <id> | --all) [--dry-run]
+                                    恢复被自动禁用的插件（升级修复后使用）
+  dsh-safe help                     显示本帮助
+  dsh-safe --version                显示版本
+
+包装模式选项（必须写在 profile / 子命令之前）:
+  --dry-run                只解析与报告，不修改任何文件
+  --max-retries <n>        自动隔离后最多重试启动的次数（默认 2）
+  --allow-first-party      允许自动禁用 @deepseek-ai/* 第一方插件（默认跳过）
+
+说明:
+  - 行的禁用以 patch 文件末尾的托管区块写入（带标记注释），不改动用户内容；
+    恢复用 dsh-safe restore，或手动删除区块。
+  - 只隔离"启动期"失败（模块解析失败 / apply 抛错 / 等不到注入服务）；
+    运行期的未捕获异常仍由 dsh 自身的 fail-loud 策略处理。
+`
+
+function printHelp() {
+  process.stdout.write(HELP)
+}
+
+function printVersion() {
+  process.stdout.write(`${version}\n`)
+}
+
+/** 解析 `--profile <名>` / `--profile=<名>`，返回 [值, 剩余参数]。 */
+function takeProfile(args) {
+  let profile
+  const rest = []
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--profile') {
+      profile = args[++i]
+    } else if (args[i].startsWith('--profile=')) {
+      profile = args[i].slice('--profile='.length)
+    } else {
+      rest.push(args[i])
+    }
+  }
+  return [profile, rest]
+}
+
+/** 解析可重复的 `--id <id>` / `--id=<id>`。 */
+function takeIds(args) {
+  const ids = []
+  const rest = []
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--id') {
+      const v = args[++i]
+      if (v !== undefined) ids.push(v)
+    } else if (args[i].startsWith('--id=')) {
+      ids.push(args[i].slice('--id='.length))
+    } else {
+      rest.push(args[i])
+    }
+  }
+  return [ids, rest]
+}
+
+function cmdList(args) {
+  const [profile] = takeProfile(args)
+  const ledger = loadLedger()
+  const profiles = profile ? [profile] : Object.keys(ledger.profiles).sort()
+  let found = 0
+  for (const p of profiles) {
+    const entries = ledger.profiles[p] ?? []
+    if (!entries.length) continue
+    process.stdout.write(`${p}:\n`)
+    for (const e of entries) {
+      found++
+      process.stdout.write(`  - ${e.name ?? '(未知包名)'} (id: ${e.id})\n      隔离于 ${e.quarantinedAt}\n      原因: ${e.reason}\n      位置: ${e.file}\n`)
+    }
+  }
+  if (!found) process.stdout.write(profile ? `${profile}: 没有隔离记录\n` : '没有隔离记录\n')
+  return 0
+}
+
+function cmdRestore(args) {
+  const [profile0, rest0] = takeProfile(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('[dsh-safe] restore 需要 --profile <名>\n')
+    return 2
+  }
+  if (!all && ids0.length === 0) {
+    process.stderr.write('[dsh-safe] restore 需要 --id <id>（可重复）或 --all\n')
+    return 2
+  }
+  const { restored, kept } = restoreQuarantine(profile, all ? 'all' : ids0, dryRun)
+  const verb = dryRun ? '（dry-run）将恢复' : '已恢复'
+  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('[dsh-safe] 没有匹配的隔离记录\n')
+  else if (kept.length) process.stdout.write(`[dsh-safe] ${profile} 仍隔离 ${kept.length} 行；重启 dsh 生效。\n`)
+  else process.stdout.write('[dsh-safe] 该 profile 的隔离名单已清空；重启 dsh 生效。\n')
+  return 0
+}
+
+/**
+ * @param {string[]} argv process.argv.slice(2)
+ * @returns {Promise<number>} 退出码
+ */
+export async function main(argv) {
+  if (argv.length === 0) {
+    printHelp()
+    return 0
+  }
+  const [cmd] = argv
+  if (cmd === 'help' || cmd === '-h' || cmd === '--help') {
+    printHelp()
+    return 0
+  }
+  if (cmd === '--version' || cmd === '-V' || cmd === 'version') {
+    printVersion()
+    return 0
+  }
+  if (cmd === 'list') return cmdList(argv.slice(1))
+  if (cmd === 'restore') return cmdRestore(argv.slice(1))
+
+  // 包装模式：剥掉 dsh-safe 自己的旗标（必须出现在第一个位置参数之前），
+  // 其余原样转发给 dsh。
+  const forwardArgs = []
+  let dryRun = false
+  let maxRetries = 2
+  let allowFirstParty = false
+  let i = 0
+  for (; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--dry-run') { dryRun = true; continue }
+    if (a === '--allow-first-party') { allowFirstParty = true; continue }
+    if (a === '--max-retries') {
+      const raw = argv[++i]
+      const v = raw === undefined || raw === '' ? NaN : Number(raw)
+      if (!Number.isFinite(v) || v < 0) {
+        process.stderr.write('[dsh-safe] --max-retries 需要一个非负整数\n')
+        return 2
+      }
+      maxRetries = v
+      continue
+    }
+    if (a.startsWith('--max-retries=')) {
+      const raw = a.slice('--max-retries='.length)
+      const v = raw === '' ? NaN : Number(raw)
+      if (!Number.isFinite(v) || v < 0) {
+        process.stderr.write('[dsh-safe] --max-retries 需要一个非负整数\n')
+        return 2
+      }
+      maxRetries = v
+      continue
+    }
+    break
+  }
+  forwardArgs.push(...argv.slice(i))
+  if (!forwardArgs.length) {
+    printHelp()
+    return 0
+  }
+  if (dryRun) process.stderr.write('[dsh-safe] dry-run：只报告，不修改文件。\n')
+  return runWrapped({ forwardArgs, dryRun, maxRetries, allowFirstParty })
+}

package/lib/dshpaths.js

@@ -0,0 +1,78 @@
+/**
+ * @hyzyn/dsh-safe — 路径与调用解析。
+ *
+ * 与 dsh 运行时（@deepseek-ai/dsh-home-paths）保持一致的 home 解析规则：
+ * `DSH_HOME` 环境变量优先（支持 `~` 前缀展开），默认 `~/.dsh`。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { resolve, join } from 'node:path'
+
+/** dsh home 目录：`DSH_HOME` 优先，默认 `~/.dsh`。 */
+export function dshHome() {
+  const raw = process.env.DSH_HOME
+  if (!raw || raw.trim() === '') return join(homedir(), '.dsh')
+  const expanded = raw === '~' || raw.startsWith('~/')
+    ? join(homedir(), raw.slice(1).replace(/^[/\\]/, ''))
+    : raw
+  return resolve(expanded)
+}
+
+export const profileDir = (profile) => join(dshHome(), 'profiles', profile)
+export const profilePatchPath = (profile) => join(profileDir(profile), 'cordis.patch.yml')
+export const profileManifestPath = (profile) => join(profileDir(profile), 'package.json')
+
+/** dsh home 层的公共 patch（对所有 profile 生效）。 */
+export const homePatchPath = () => join(dshHome(), 'cordis.patch.yml')
+
+/** dsh-safe 的隔离台账。 */
+export const ledgerFile = () => join(dshHome(), 'dsh-safe', 'quarantine.json')
+
+/** 读文件，不存在或读不了返回 undefined。 */
+export const readIfExists = (path) => {
+  try {
+    return existsSync(path) ? readFileSync(path, 'utf8') : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 解析转发给 dsh 的启动参数，识别 profile 与模式。
+ *
+ * 与 dsh 启动器一致：launcher 自己的旗标在最前（`--profile <v>`、`--patch <v>`
+ * 各带一个值），第一个无法识别的位置参数起就是内部参数。因此只在"launcher 前缀"
+ * 里找 `--profile`；`plugin` 子命令例外——它的 `--profile` 跟在子命令后面。
+ *
+ * @param {string[]} args 转发参数（已剥掉 dsh-safe 自己的旗标）
+ * @returns {{ mode: 'boot'|'plugin', profile: string|null }}
+ */
+export function detectInvocation(args) {
+  let firstPositional = -1
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (!a.startsWith('-')) { firstPositional = i; break }
+    // 带值的 launcher 旗标：跳过它的值
+    if (a === '--profile' || a === '--patch') i++
+  }
+  const first = firstPositional >= 0 ? args[firstPositional] : undefined
+  if (first === 'plugin') {
+    let profile
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--profile') profile = args[i + 1]
+      else if (args[i].startsWith('--profile=')) profile = args[i].slice('--profile='.length)
+    }
+    return { mode: 'plugin', profile: profile || null }
+  }
+  let profile
+  const launcherEnd = firstPositional < 0 ? args.length : firstPositional
+  for (let i = 0; i < launcherEnd; i++) {
+    if (args[i] === '--profile') profile = args[i + 1]
+    else if (args[i].startsWith('--profile=')) profile = args[i].slice('--profile='.length)
+  }
+  if (!profile && first) {
+    if (first === 'web') profile = 'web'
+    else if (existsSync(profileDir(first))) profile = first
+  }
+  return { mode: 'boot', profile: profile || null }
+}

package/lib/failures.js

@@ -0,0 +1,74 @@
+/**
+ * @hyzyn/dsh-safe — 从 dsh 启动失败的 stderr 里识别坏插件。
+ *
+ * 匹配四类启动失败特征（来自 @deepseek-ai/dsh-app-boot 与
+ * @deepseek-ai/cordis-plugin-loader 的真实输出）：
+ *
+ * 1. assertEntriesLoaded:
+ *    `dsh: plugin(s) failed to load: @a/x, @b/y; Cordis startup failed ...`
+ * 2. assertEntriesActivated:
+ *    `dsh: 2 entries did not activate` 之后每行一条 `@a/x: <错误>` / `@a/x: pending (waiting for service(s): xxx)`
+ * 3. loader entry 更新失败：
+ *    `failed to (apply|import|dispose|rollback) loader entry <id> (<name>): <原因>`
+ * 4. 外层栈（getOuterStack）：
+ *    `    at file:///…/profiles/web/#<entryId>`
+ *
+ * 1–3 给出包名（entry.options.name），4 给出行 id；两者都要在调用方与
+ * patch 行对照后才会生效，所以这里允许宽收集。
+ */
+
+const NAME_CLASS = '[\\w@][\\w@./\\-]*'
+const ID_CLASS = '[\\w:\\-]+'
+
+const isPluginName = (s) => NAME_REGEX.test(s)
+const NAME_REGEX = new RegExp(`^${NAME_CLASS}$`)
+
+/**
+ * @param {string} text dsh 进程捕获到的 stderr
+ * @returns {{ names: Array<[string, string]>, entryIds: Array<[string, string]> }}
+ *          names: [包名, 出现该命中的原始行]；entryIds: [行 id, 原始行]
+ */
+export function parseFailureReport(text) {
+  const names = new Map()
+  const entryIds = new Map()
+  const lines = text.split(/\r?\n/)
+  const reEntry = new RegExp(`failed to (?:apply|import|dispose|rollback) loader entry (${ID_CLASS}) \\(([^)]+)\\)`)
+  const reStackId = new RegExp(`^\\s*at \\S+#(${ID_CLASS})`)
+  const reLoadList = /plugin\(s\) failed to load:\s*([^;\n]+);/
+
+  for (const line of lines) {
+    const entry = reEntry.exec(line)
+    if (entry) {
+      entryIds.set(entry[1], line)
+      if (isPluginName(entry[2])) names.set(entry[2], line)
+    }
+    const stackId = reStackId.exec(line)
+    if (stackId) entryIds.set(stackId[1], line)
+    const list = reLoadList.exec(line)
+    if (list) {
+      for (const raw of list[1].split(/,\s*/)) {
+        const name = raw.trim()
+        if (name && isPluginName(name)) names.set(name, line)
+      }
+    }
+  }
+
+  // "did not activate" 块：头部之后的每一行 `包名: …` 都是一条失败。
+  // 失败行的错误体可能自带多行栈，所以扫到文本末尾，靠调用方的行名对照收窄。
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].includes('did not activate')) continue
+    for (let j = i + 1; j < lines.length; j++) {
+      const m = new RegExp(`^\\s*(${NAME_CLASS}):\\s`).exec(lines[j])
+      if (m && isPluginName(m[1])) names.set(m[1], lines[j])
+    }
+  }
+
+  return { names: [...names], entryIds: [...entryIds] }
+}
+
+/** 压缩一行错误为台账里的 reason（去空白、截断）。 */
+export function summarizeLine(line, max = 160) {
+  if (!line) return 'startup failure'
+  const flat = line.replace(/\s+/g, ' ').trim()
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat
+}

package/lib/knownrows.js

@@ -0,0 +1,86 @@
+/**
+ * @hyzyn/dsh-safe — 收集一个 profile 下"行 id ↔ 插件包名"的对照表。
+ *
+ * 来源（后写的层优先级更高）：
+ * 1. profile 自己的 cordis.patch.yml（写层）
+ * 2. `$DSH_HOME/cordis.patch.yml` home 层（写层：发现的行写回 home patch）
+ * 3. profile package.json `dsh.profile.bundles` 里每个 bundle 的 patch
+ *    （只读对照；禁用行写入 profile 层，它在 bundle 层之后合成，同 id 后写覆盖）
+ */
+import { join } from 'node:path'
+import { scanPatchRows } from './patchfile.js'
+import { homePatchPath, profileDir, profileManifestPath, profilePatchPath, readIfExists } from './dshpaths.js'
+
+const readJsonIfExists = (path) => {
+  const raw = readIfExists(path)
+  if (raw === undefined) return undefined
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * @param {string} profile
+ * @returns {{
+ *   rows: Array<{ id: string, name: string|null, disabled: boolean, source: string, file: string }>,
+ * }}
+ */
+export function collectKnownRows(profile) {
+  const rows = []
+  const profilePatch = profilePatchPath(profile)
+  const homePatch = homePatchPath()
+
+  const profileText = readIfExists(profilePatch)
+  if (profileText !== undefined) {
+    for (const row of scanPatchRows(profileText)) rows.push({ ...row, source: 'profile', file: profilePatch })
+  }
+
+  const homeText = readIfExists(homePatch)
+  if (homeText !== undefined) {
+    for (const row of scanPatchRows(homeText)) rows.push({ ...row, source: 'home', file: homePatch })
+  }
+
+  const manifest = readJsonIfExists(profileManifestPath(profile))
+  const bundles = manifest?.dsh?.profile?.bundles ?? []
+  for (const bundle of bundles) {
+    const bundleDir = join(profileDir(profile), 'node_modules', bundle)
+    const pkg = readJsonIfExists(join(bundleDir, 'package.json'))
+    const patchRel = pkg?.dsh?.bundle?.patch
+    if (typeof patchRel !== 'string') continue
+    const patchText = readIfExists(join(bundleDir, patchRel))
+    if (patchText === undefined) continue
+    for (const row of scanPatchRows(patchText)) rows.push({ ...row, source: bundle, file: profilePatch })
+  }
+
+  return { rows, profilePatch, homePatch }
+}
+
+/**
+ * 把失败报告对照到真实存在的 patch 行。
+ * 包名命中该包的全部行（一个包可能挂多个 id）；行 id 命中对应行。
+ * @param {{ names: Array<[string, string]>, entryIds: Array<[string, string]> }} report
+ * @param {{ rows: Array<{ id: string, name: string|null, disabled: boolean, file: string }> }} known
+ * @returns {Array<{ id: string, name: string|null, disabled: boolean, file: string, line: string }>}
+ */
+export function matchFailures(report, known) {
+  const byId = new Map()
+  const byName = new Map()
+  for (const row of known.rows) {
+    if (!byId.has(row.id)) byId.set(row.id, row)
+    if (row.name) {
+      if (!byName.has(row.name)) byName.set(row.name, [])
+      byName.get(row.name).push(row)
+    }
+  }
+  const hits = new Map()
+  for (const [name, line] of report.names) {
+    for (const row of byName.get(name) ?? []) hits.set(row.id, { ...row, line })
+  }
+  for (const [id, line] of report.entryIds) {
+    const row = byId.get(id)
+    if (row) hits.set(row.id, { ...row, line })
+  }
+  return [...hits.values()]
+}

package/lib/patchfile.js

@@ -0,0 +1,119 @@
+/**
+ * @hyzyn/dsh-safe — cordis.patch.yml 的行扫描与托管区块读写。
+ *
+ * patch 文件带用户注释与 `!!js` 表达式，不能用 YAML 库无损重写；这里只做
+ * 行级扫描（拿 id/name 对照表）与"标记区块"的追加/移除，其余内容原样保留。
+ * 托管区块约定与 dsh-mcp-config 的 managed 区块一致（首尾各一行标记注释）。
+ */
+
+export const MANAGED_START = '# --- dsh-safe managed (auto-generated; do not edit) ---'
+export const MANAGED_END = '# --- end dsh-safe managed ---'
+
+/**
+ * 扫描 patch 文本中的 loader 行，返回 [{ id, name, disabled }]。
+ *
+ * 行的形状：`- id: xxx` 后跟同级缩进的 `name:` / `disabled:` 等键。需要避开
+ * `config:` 子树里恰好也叫 `id`/`name` 的配置项，因此维护一个"已打开的
+ * config: 键缩进"栈：处理每行前先弹出缩进 >= 当前行缩进的 config；只有栈
+ * 为空时的 `- id:` 才算 loader 行。
+ *
+ * @param {string} text patch 文件内容
+ * @returns {Array<{ id: string, name: string|null, disabled: boolean }>}
+ */
+export function scanPatchRows(text) {
+  const rows = []
+  const lines = text.split(/\r?\n/)
+  const openConfigs = [] // 已打开 config: 键的缩进
+  let current = null // { id, name, disabled, keyIndent }
+  const flush = () => {
+    if (current) {
+      rows.push({ id: current.id, name: current.name, disabled: current.disabled })
+      current = null
+    }
+  }
+  for (const line of lines) {
+    const indent = /^\s*/.exec(line)[0].length
+    while (openConfigs.length && openConfigs[openConfigs.length - 1] >= indent) openConfigs.pop()
+    if (openConfigs.length) continue // 在某个 config: 子树里
+    const trimmed = line.trim()
+    const rowM = /^-\s+id:\s*(\S+)$/.exec(trimmed)
+    if (rowM) {
+      flush()
+      current = { id: rowM[1], name: null, disabled: false, keyIndent: indent + 2 }
+      continue
+    }
+    if (!current || indent !== current.keyIndent) continue
+    const nameM = /^name:\s*(.+?)\s*$/.exec(trimmed)
+    if (nameM) { current.name = unquote(nameM[1]); continue }
+    if (/^disabled:\s*true\s*$/.test(trimmed)) { current.disabled = true; continue }
+    if (/^config:(\s|$)/.test(trimmed)) openConfigs.push(indent)
+  }
+  flush()
+  return rows
+}
+
+function unquote(value) {
+  const quoted = /^(['"])(.*?)\1(?:\s|$)/.exec(value)
+  if (quoted) return quoted[2]
+  return value.split(/\s+#/, 1)[0].trim()
+}
+
+/**
+ * 生成托管区块文本（不含尾部换行）。
+ * @param {Array<{ id: string, name?: string|null, reason?: string, quarantinedAt?: string }>} entries
+ */
+export function buildManagedBlock(entries) {
+  const out = [MANAGED_START]
+  out.push('# 由 dsh-safe 自动写入：启动失败的插件被置为 disabled，避免拖垮整个启动。')
+  out.push('# 恢复：dsh-safe restore --profile <name> [--id <id> ... | --all]')
+  for (const e of entries) {
+    out.push(`# ${e.quarantinedAt ?? ''} · ${e.name ?? e.id} · ${e.reason ?? 'startup failure'}`.trimEnd())
+    out.push(`- id: ${e.id}`)
+    if (e.name) out.push(`  name: '${e.name}'`)
+    out.push('  disabled: true')
+  }
+  out.push(MANAGED_END)
+  return out.join('\n')
+}
+
+/** 去掉文本中的所有 dsh-safe 托管区块（含标记行），并规范尾部换行。 */
+export function stripManagedBlocks(text) {
+  const lines = text.split(/\r?\n/)
+  const kept = []
+  let skipping = false
+  for (const line of lines) {
+    if (line.trim() === MANAGED_START) { skipping = true; continue }
+    if (skipping) {
+      if (line.trim() === MANAGED_END) skipping = false
+      continue
+    }
+    kept.push(line)
+  }
+  return kept.join('\n').replace(/\n+$/, '')
+}
+
+/**
+ * 在 patch 文本上应用托管区块：先移除旧区块，再追加新区块（block 为 null 只移除）。
+ *
+ * 追加时若文件还是全新模板（根节点为空的 flow 序列 `[]`），必须去掉 `[]` 行，
+ * 否则 `[]` 之后跟块序列是非法 YAML。
+ * @returns {{ text: string }}
+ */
+export function applyManagedBlock(text, block) {
+  let base = stripManagedBlocks(text)
+  if (block) {
+    base = base
+      .split(/\r?\n/)
+      .filter((l) => l.trim() !== '[]')
+      .join('\n')
+      .replace(/\n+$/, '')
+  }
+  if (!block) {
+    // 摘除后若文档只剩注释/空白，补回 `[]`（dsh 的 parsePatchList 拒绝 null 文档）
+    const hasRows = base.split(/\r?\n/).some((l) => l.trim() && !l.trim().startsWith('#'))
+    if (!hasRows) return { text: base.length ? `${base}\n[]\n` : '' }
+    return { text: base + '\n' }
+  }
+  const next = base.length ? `${base}\n\n${block}\n` : `${block}\n`
+  return { text: next }
+}

package/lib/quarantine.js

@@ -0,0 +1,99 @@
+/**
+ * @hyzyn/dsh-safe — 隔离台账与 patch 文件写入。
+ *
+ * 台账：`$DSH_HOME/dsh-safe/quarantine.json`，按 profile 记录被自动禁用的行
+ * （id/name/reason/时间/所在文件）。patch 文件的改动只体现为末尾的托管区块
+ * （带标记注释，可重复生成、可整体摘除），用户已有内容与注释原样保留。
+ *
+ * 同一个 patch 文件（如 `$DSH_HOME/cordis.patch.yml`）可能被多个 profile 的
+ * 隔离记录共享：托管区块始终按"文件"聚合全部 profile 的台账条目重新生成，
+ * 避免一次写入覆盖另一个 profile 的区块。
+ */
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { applyManagedBlock, buildManagedBlock } from './patchfile.js'
+import { ledgerFile, readIfExists } from './dshpaths.js'
+
+const EMPTY_LEDGER = () => ({ version: 1, profiles: {} })
+
+export function loadLedger() {
+  const raw = readIfExists(ledgerFile())
+  if (raw === undefined) return EMPTY_LEDGER()
+  try {
+    const parsed = JSON.parse(raw)
+    if (parsed && typeof parsed === 'object' && parsed.profiles && typeof parsed.profiles === 'object') {
+      return { version: 1, profiles: parsed.profiles }
+    }
+  } catch {}
+  return EMPTY_LEDGER()
+}
+
+export function saveLedger(ledger) {
+  const file = ledgerFile()
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, `${JSON.stringify(ledger, null, 2)}\n`)
+}
+
+/** 重写指定 patch 文件的托管区块（跨 profile 聚合；extraFiles 兜底清空的文件）。 */
+function rewriteManagedBlocks(ledger, extraFiles = []) {
+  const all = Object.values(ledger.profiles).flat()
+  const files = new Set([...all.map((e) => e.file), ...extraFiles])
+  for (const file of files) {
+    const entries = all.filter((e) => e.file === file)
+    const text = readIfExists(file)
+    if (text === undefined) continue
+    const { text: next } = applyManagedBlock(text, entries.length ? buildManagedBlock(entries) : null)
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, next)
+  }
+}
+
+/**
+ * 把要禁用的行写入对应 patch 文件的托管区块，并更新台账。
+ * @param {string} profile
+ * @param {Array<{ id: string, name: string|null, reason: string, file: string }>} targets
+ * @param {boolean} dryRun
+ * @param {string} now ISO 时间戳
+ * @returns {{ ledger: object }} 更新后的台账
+ */
+export function writeQuarantine(profile, targets, dryRun, now = new Date().toISOString()) {
+  const ledger = loadLedger()
+  const list = (ledger.profiles[profile] ??= [])
+  for (const t of targets) {
+    const existing = list.find((e) => e.id === t.id && e.file === t.file)
+    if (existing) {
+      existing.reason = t.reason
+      existing.quarantinedAt = now
+    } else {
+      list.push({ id: t.id, name: t.name ?? null, reason: t.reason, quarantinedAt: now, file: t.file })
+    }
+  }
+  if (!dryRun) {
+    rewriteManagedBlocks(ledger)
+    saveLedger(ledger)
+  }
+  return { ledger }
+}
+
+/**
+ * 恢复（摘除）被禁用的行：从台账删除并按剩余台账重写托管区块。
+ * @param {string} profile
+ * @param {string[] | 'all'} ids
+ * @param {boolean} dryRun
+ * @returns {{ restored: Array<object>, kept: Array<object> }}
+ */
+export function restoreQuarantine(profile, ids, dryRun) {
+  const ledger = loadLedger()
+  const list = ledger.profiles[profile] ?? []
+  if (!list.length) return { restored: [], kept: [] }
+  const removeSet = ids === 'all' ? new Set(list.map((e) => e.id)) : new Set(ids)
+  const kept = list.filter((e) => !removeSet.has(e.id))
+  const restored = list.filter((e) => removeSet.has(e.id))
+  if (!dryRun) {
+    if (kept.length) ledger.profiles[profile] = kept
+    else delete ledger.profiles[profile]
+    rewriteManagedBlocks(ledger, restored.map((e) => e.file))
+    saveLedger(ledger)
+  }
+  return { restored, kept }
+}

package/lib/wrap.js

@@ -0,0 +1,109 @@
+/**
+ * @hyzyn/dsh-safe — 包装运行 dsh 的主循环。
+ *
+ * 运行 dsh（stderr 进管道并同步回显），进程退出后：
+ *   - 正常退出（0）→ 结束；
+ *   - 失败退出 → 从 stderr 解析坏插件，对照 patch 行后把对应行置为 disabled
+ *     （写入托管区块 + 台账），然后重试；识别不出、超过重试上限、或命中
+ *     第一方插件（@deepseek-ai/*，默认保护）时原样透传退出码。
+ */
+import { spawn } from 'node:child_process'
+import { summarizeLine, parseFailureReport } from './failures.js'
+import { collectKnownRows, matchFailures } from './knownrows.js'
+import { detectInvocation } from './dshpaths.js'
+import { writeQuarantine } from './quarantine.js'
+
+const CAPTURE_LIMIT = 512 * 1024
+const FIRST_PARTY_PREFIX = '@deepseek-ai/'
+
+const isFirstParty = (name) => typeof name === 'string' && name.startsWith(FIRST_PARTY_PREFIX)
+
+/** 运行 dsh：stdin/stdout 直通，stderr 回显并捕获（上限内）。 */
+export function spawnDsh(args, { command = 'dsh' } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      stdio: ['inherit', 'inherit', 'pipe'],
+      env: process.env,
+    })
+    let captured = ''
+    child.stderr?.on('data', (chunk) => {
+      process.stderr.write(chunk)
+      if (captured.length < CAPTURE_LIMIT) captured += chunk
+    })
+    child.on('error', (error) => {
+      process.stderr.write(`[dsh-safe] 无法启动 ${command}: ${error.message}\n`)
+      resolve({ code: 127, stderr: captured })
+    })
+    child.on('close', (code) => resolve({ code: code ?? 1, stderr: captured }))
+  })
+}
+
+/**
+ * @param {{
+ *   forwardArgs: string[],
+ *   dryRun?: boolean,
+ *   maxRetries?: number,
+ *   allowFirstParty?: boolean,
+ *   log?: (...args: any[]) => void,
+ *   spawn?: typeof spawnDsh,
+ * }} options
+ * @returns {Promise<number>} 最终退出码
+ */
+export async function runWrapped(options) {
+  const {
+    forwardArgs,
+    dryRun = false,
+    maxRetries = 2,
+    allowFirstParty = false,
+    log = (line) => process.stderr.write(`${line}\n`),
+    spawn: spawnFn = spawnDsh,
+  } = options
+  const invocation = detectInvocation(forwardArgs)
+  for (let attempt = 0; ; attempt++) {
+    const { code, stderr } = await spawnFn(forwardArgs)
+    if (code === 0) return 0
+    if (invocation.mode === 'plugin') {
+      log('[dsh-safe] `dsh plugin` 为 pnpm 转发，不做隔离，原样透传。')
+      return code
+    }
+    if (!invocation.profile) {
+      log('[dsh-safe] 未能从参数确定 profile（launcher 旗标需在最前，或用 --profile <name>），无法自动隔离，原样透传。')
+      return code
+    }
+    const known = collectKnownRows(invocation.profile)
+    const report = parseFailureReport(stderr)
+    const hits = matchFailures(report, known)
+    const quarantinable = []
+    const firstParty = []
+    for (const hit of hits) {
+      if (hit.disabled) continue // 已经是禁用状态
+      if (isFirstParty(hit.name) && !allowFirstParty) firstParty.push(hit)
+      else quarantinable.push(hit)
+    }
+    for (const hit of firstParty) {
+      log(`[dsh-safe] 跳过第一方插件 ${hit.name} (id: ${hit.id}) —— 默认保护 @deepseek-ai/*，需要手动处理；确认要禁用可加 --allow-first-party。`)
+    }
+    if (!quarantinable.length) {
+      if (!firstParty.length) log('[dsh-safe] 报错里没有识别出可自动隔离的已挂载插件，原样透传。')
+      return code
+    }
+    if (attempt >= maxRetries) {
+      log(`[dsh-safe] 已达最大重试次数（--max-retries ${maxRetries}），不再重试。`)
+      return code
+    }
+    const targets = quarantinable.map((hit) => ({
+      id: hit.id,
+      name: hit.name,
+      reason: summarizeLine(hit.line),
+      file: hit.file,
+    }))
+    writeQuarantine(invocation.profile, targets, dryRun)
+    for (const t of targets) {
+      const verb = dryRun ? '（dry-run）将禁用' : '已禁用'
+      log(`[dsh-safe] ${verb} ${t.name ?? t.id} (id: ${t.id}) → ${t.file}`)
+      log(`           原因: ${t.reason}`)
+    }
+    if (dryRun) return code
+    log('[dsh-safe] 重试启动…')
+  }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@hyzyn/dsh-safe",
+  "version": "0.1.0",
+  "description": "dsh 启动保险丝：社区插件不兼容导致 dsh 启动失败时，自动禁用坏插件并重试",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "dsh-safe": "bin/dsh-safe.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hyzyn/dsh-safe.git"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "quarantine",
+    "boot"
+  ]
+}