插件启动/重启与生态的几个问题与建议（附复现步骤）

[Semidia]

背景

在 Windows + 自建 profile 上深度使用 DSH web 时，遇到并定位了几个值得官方关注的问题。每条都附了可复现步骤与根因，欢迎指正。

1. dsh plugin add 会静默丢失 dsh.profile.bundles 中的已有条目（Bug）

• 现象：执行 dsh plugin --profile web add link:D:/xxx 安装新 bundle 后，profiles/web/package.json 的 dsh.profile.bundles 数组中原有条目被移除（实测丢失了 @dsh-polyglot/bundle 和 dsh-web-control），这些插件的路由/UI 静默失效（HTTP 404），无任何告警。
• 复现：备份 package.json → 执行 dsh plugin add <任一 bundle> → 对比 bundles 数组。
• 建议：plugin add 应合并而非整体替换 bundles 列表；写入前先 --dump-config 校验，并把实际变更记录到日志。

2. 适配器路由冲突导致启动即崩，错误信息难以定位

• 现象：第三方路由插件用 ctx.llm.registerAdapter(['deepseek-official'], …) 抢注已由 llm-deepseek 注册的 provider，进程在 boot 阶段直接抛 DUPLICATE_ADAPTER 崩溃，整棵组合起不来。堆栈里能看到 provider 名，但没有指出「谁先注册、谁冲突」。
• 复现：把注册同一 provider 的两个 adapter 插件放入同一组合启动。
• 建议：
  • DUPLICATE_ADAPTER 崩溃信息点名冲突双方（已注册者 + 请求者）；
  • 引导第三方路由插件用 registerConfigurableProviders 或仅注册新路由，而不是抢注既有 provider；
  • 启动预检（--dump-config 或 loader 层）能提前拦截这类冲突，给出可操作提示（如「请移除 X 或改用 Y」）。

3. 「由后端派生的重启脚本杀后端」会连带杀掉自己，重启必然失败

• 现象：把 restart-web.ps1（由 dsh web 进程派生运行）直接 Stop-Process 3080 监听进程，脚本自身也随宿主进程树被终止，永远走不到后面的重新拉起步骤，后端只能靠外部（手动运行启动器）恢复。
• 根因：重启脚本运行在被杀进程的进程树内。
• 修复（已在本机验证）：
  • 重启动作交给「脱离被杀进程树」的执行者：Windows 上用一次性计划任务；Node 侧用 spawn(detached: true) + unref（dsh-service-control 已用该模式，工作正常）。
  • 建议官方在 web 内置健壮的 stop/restart 入口（appExit + detached 重启），避免每个部署自己造轮子踩坑。

4. 启动器「预检 + 恢复菜单 + known-good 快照」设计，值得官方参考

自建启动器（启动 DeepSeek Harness.ps1）目前包含：

• 启动前预检：--dump-config 组合校验 + 每个 bundle 入口语法检查 + 冒烟测试；
• 启动失败时恢复菜单：自动识别出错插件并禁用重试 / 还原 known-good 补丁 / 回滚 / 会话损坏隔离与恢复；
• 每次成功启动后把 cordis.patch.yml 快照为 known-good；
• 错误摘要中文化，完整堆栈只写日志。

这套机制把「组合被改坏」从「死页面 + 只能手动折腾」变成「一键定位/恢复」。若官方 launcher 或 dsh web 能内置类似能力（或提供官方 preflight/recovery 钩子），能显著改善插件生态可用性。

5. 插件开发坑：用 ctx.settings 必须声明 inject: ['settings']

• 现象：插件在 apply() 里 ctx.get('settings') 注册命名空间，但未声明 inject: ['settings']。插件会先于 settings 服务就绪而激活，ctx.get('settings') 返回 undefined，注册被跳过；客户端写该命名空间时报 settings namespace not registered。
• 修复：export const inject = ['settings']（或对可选服务做 undefined 处理）。
• 建议：插件开发文档明确这一点——settings/connection 等 Host 服务作为硬依赖时务必声明 inject。

---

以上均为本人在 Windows + 自建 profile 下的实测。感谢 DSH 团队与社区！

[denial123789]

I checked items 1, 2, and 5 against master 47f9438. The report identifies useful failure surfaces, with one important distinction for recovery.

For item 1, dsh plugin does not unconditionally replace dsh.profile.bundles. After pnpm succeeds, reconcilePlugins() compares the installed dependencies and their manifests:

• a dependency declaring dsh.bundle.patch is added;
• a dependency that was managed before but is now absent or no longer declares a bundle is removed;
• template bundles that are not dependency-managed are left untouched.

So the strongest reproduction should include the dependency diff, bundle list diff, and the installed manifests for the missing packages. That will show whether pnpm changed the dependency set, a package lost its bundle declaration, or reconciliation removed an entry outside its intended ownership.

For item 2, duplicate provider routes do fail atomically with DUPLICATE_ADAPTER. A provider route must have one runtime adapter owner. registerConfigurableProviders() is advisory settings/catalog metadata and is not an adapter override mechanism, so it cannot resolve a collision by itself. A third-party adapter needs a distinct route, or the original route owner must be removed from the composition.

For item 5, the service lifecycle documentation confirms that a required service belongs in inject. Without it, ctx.get('settings') is an optional lookup and the plugin must handle undefined at every use site. Silently skipping required namespace registration defers the failure to the client.

I turned these boundaries into a reversible operator runbook: preserve the manifest, lockfile, profile patch, and home patch; dump the composition before and after one install; then smoke test and either promote or restore the known-good state.

Visual runbook: https://sandbaseai.github.io/deepseek-harness-handbook/plugin-recovery.html

Canonical source guide: sandbaseai/deepseek-harness-handbook#20

[Semidia]

补充（2026-08-15）：会话存储布局不兼容 → 启动失败且错误归因误导（核心插件被误报）

新遇到一个关联问题，值得补充：

• 现象：sessions 目录下出现 _unknown-event-backup-* 子目录，内含 6 个平铺（flat）session.jsonl.zstd 文件（官方返回 "unsupported flat session artifact inside project directory"）。workspace 后端拒绝读取，启动失败；但错误被归因成核心插件 workspace 报错（"插件 [workspace] 有错误"），恢复菜单因它是核心组件而拒绝自动禁用，用户卡死在恢复菜单里。
• 根因：flat artifact 布局不被 workspace 后端支持（疑似备份/迁移工具产生的平铺产物）；同时启动失败的错误归因没有区分「插件错误」和「存储/数据布局错误」，把后者误报成前者。
• 建议：
  1. workspace 后端对不支持的 flat artifact 给出可操作提示（或优雅跳过 + 日志警告），而不是让启动器把失败归因到插件；
  2. 启动失败归因区分「插件错误」与「数据/存储布局错误」两类，恢复策略也相应区分（数据问题不应尝试禁用核心插件）；
  3. 官方考虑支持或提供迁移/清理这类 flat session artifact 的工具。

[Semidia]

补充 2（2026-08-15）：重启机制「委托交互式恢复流程」在非交互触发下必然失败

第 3 条（重启脚本杀后端会连带自杀）修复过程中又踩到关联坑，值得补充：

• 现象：把重启动作交给「一次性计划任务」，helper 再去运行官方启动器；启动器遇到启动失败（例如会话存储布局问题）时会弹出交互式恢复菜单（Read-Host 等待输入数字选项）。在计划任务 / 无控制台环境里菜单无法被回答，重启进程被终止（任务结果 0xC000013A），后端保持关闭，没有任何自动恢复。
• 根因：启动失败路径依赖「人工交互」；任何自动化 / 非交互触发器（计划任务、CI、远端）遇到失败都会卡死在这条路径上。
• 建议：
  1. 启动器 / CLI 检测到非交互上下文（无控制台、-NonInteractive、stdin 非 TTY）时，恢复菜单自动降级：默认退出并把完整错误与下一步写进日志，而不是挂起等待输入；
  2. 重启 / 自动化入口走「直接拉起 + 就绪轮询」的纯非交互路径（复用 node bin.js web 的参数即可），不依赖交互式恢复；
  3. 失败时把「启动失败原因」与「可执行的恢复命令」写进明确日志，方便自动化或用户一次性处理。

[moonquake2004]

第 2、5 条我们已做成可离线检测的检查并落地（moonquake2004/dsh-doctor，commit ef6ed30 + 587ff07）：

• P8（profile）：扫描各 bundle 构建产物中的 registerAdapter([...])，检出两个 bundle 抢注同一 provider → 你的第 2 条（boot 时 DUPLICATE_ADAPTER 崩溃）的前置检测，输出冲突双方与修复建议（改用 registerConfigurableProviders 或只注册新路由）
• P9（profile）：ctx.settings / ctx.get('settings') 但 settings 依赖未声明（模块 inject 与 ctx.inject 均不含）→ 你的第 5 条问题模式，输出插件名与修复建议（加 export const inject = ["settings"] 或对可选服务做 undefined 处理）

实测中 P9 修了三轮防误报（sctx.settings 子串误匹配、bundle 里的 client/ 浏览器端产物、bundle 内首个 inject 数组被误当作插件自身的），现在 59/59 测试全绿；对真实 profile 实测干净通过。

两点呼应：

• 你的第 2 条建议"启动预检能提前拦截"正是这类检查的定位——dsh doctor 或本工具跑 --profile 即可在 boot 前看到 P8；
• 你的第 4 条启动器 preflight 若想直接消费诊断结果，我们 0.2.5 的 dsh-doctor/v1 信封输出（💡 Idea: Add 'dsh doctor' CLI command for environment & dependency diagnostics #1719 已与 dsh-plugin-doctor 对齐）可直接被启动器解析，无需再解析文本。

第 1、3 条（plugin add 合并语义、重启脚本进程树）属上游/launcher 层，我们没法从离线侧覆盖，但赞同你的建议方向。

[Semidia]

补充 3（2026-08-15）：实测确认「后端 spawn 的 detached 重启进程也会随后端一起死」

对第 3 条做了一次真机实测（同一 Windows 环境）：

• 现象：dsh-service-control 的「重启服务」按钮用 Node spawn(pwsh, …, { detached: true, stdio: 'ignore' }) + unref() 安排重启，再 appExit(0) 退出。实测：按钮触发后后端退出、页面断连，但重启 helper 没有产生任何启动日志（node 的 stdout/stderr 重定向文件都没有被创建），后端保持关闭 → 只能手动启动。
• 结论（本机 Windows 实测）：由后端进程发起的 spawn(detached: true) 并不保证脱离后端的进程树 / Job——后端一退出，helper 也随之消失，重启必然失败。detached 只脱离进程组 / 控制台，不脱离 Job Object。
• 可用的解法（已验证）：交给真正独立于后端进程树的执行者——Windows 一次性计划任务（Task Scheduler）最可靠；已验证「计划任务 → 直接 node bin.js web 拉起 → HTTP 200 就绪」全程自动化成功。
• 建议：官方文档明确「由后端触发的进程可能随后端一起终止（尤其 Windows Job Object）」，并提供 / 推荐可靠的进程外重启通道。

[Electricitysheep]

插件启动/重启的问题集（每条带复现+根因）——dsh plugin add 静默问题、重启状态等，和第 3 章依赖/挂载坑是同一片区域。

这些根因值得并进第 3 章，方便的话可以整理成 checklist 我来收录：https://github.com/Electricitysheep/dsh-handbook/blob/main/docs/03-profiles.md

[moonquake2004]

@Electricitysheep — Here's the full problem set from this thread, organized as a checklist for 3.5 常见坑 (all eight entries, each attributed to who verified it — I only vouch for the two we have offline detection for; the rest carry their verifier's name so you can decide what to include):

1. dsh plugin add does not unconditionally replace dsh.profile.bundles — verified by sandbaseai against master 47f9438

• Root cause: after pnpm succeeds, reconcilePlugins() diffs installed dependencies vs manifests: a dep declaring dsh.bundle.patch is added; a previously-managed dep that is now absent or no longer declares a bundle is removed; template bundles not dependency-managed are left untouched.
• Repro (strongest form): capture the dependency diff + bundle-list diff + installed manifests for the missing packages — that shows whether pnpm changed the dep set, a package lost its bundle declaration, or reconciliation removed an entry outside its intended ownership.
• Runbook: sandbaseai published a reversible operator runbook (preserve manifest/lockfile/patches → dump composition before/after one install → smoke test → promote or restore): visual / source.

2. Duplicate adapter registration → boot-time DUPLICATE_ADAPTER crash — sandbaseai (master check) + our P8 (offline detection)

• Root cause: a provider route must have exactly one runtime adapter owner; registerConfigurableProviders() is advisory settings/catalog metadata, not an adapter override mechanism.
• Detection: our P8 scans each bundle's build output for registerAdapter([...]) and flags two bundles claiming the same provider, before boot (dsh-doctor --profile, since 0.2.6) — this generalizes the Session resume fails: Host Cordis inspect provider "Service" is already registered (process-singleton registry collides between preset mounts) #1415/`tool-cordis` inspect-provider registration breaks mounting the shipped `cordis` agent preset (default) #1827 tool-cordis callout already in your 3.5 into a detectable rule.
• Fix: third-party adapter registers a distinct route, or the original route owner is removed from the composition.

3. Restart path can kill the backend it was spawned from — OP's real-machine tests (Windows)

• Root cause: spawn(..., { detached: true }) from the backend only escapes the process group/console — it does not escape the Windows Job Object; when the backend exits, the restart helper dies with it (verified: no helper logs produced, backend stays off).
• Verified working alternative: Windows one-shot Task Scheduler → node bin.js web → HTTP-200 readiness poll.
• Fix direction: out-of-process restart channel + docs clarifying backend-triggered processes may die with the backend.

4. Interactive recovery menu hangs in non-interactive contexts — OP

• Root cause: startup failure path prompts a Read-Host menu; under a scheduled task / CI / no-TTY it can't be answered, the process is terminated (0xC000013A), backend stays off with no auto-recovery.
• Fix direction: detect non-interactive context (no console / -NonInteractive / stdin non-TTY) → degrade to "exit + log full error and next steps"; automation should use direct launch + readiness polling.

5. Startup failure misattributed to the core workspace plugin — OP

• Root cause: flat session artifacts (_unknown-event-backup-* with flat session.jsonl.zstd, "unsupported flat session artifact inside project directory") are refused by the workspace backend, but the launcher reports it as a plugin error and the recovery menu won't disable a core component → user is stuck.
• Fix direction: distinguish "plugin error" from "data/storage layout error" in attribution and recovery; backend gives an actionable hint or gracefully skips + logs; official tooling to migrate/clean flat artifacts.

6. ctx.settings used without declaring the dependency — sandbaseai (master check) + our P9 (offline detection)

• Root cause: a required service belongs in inject; without it ctx.get('settings') is an optional lookup and the plugin must handle undefined at every use site — silently skipping registration defers the failure to the client.
• Detection: our P9 flags ctx.settings / ctx.get('settings') reads whose module inject and ctx.inject lack "settings" (hardened through three false-positive rounds: sctx.settings substring, browser-side client/ bundles, first-inject-array confusion; current fixture corpus 87 tests), dsh-doctor --profile.
• Fix: export const inject = ["settings"], or treat the service as optional and handle undefined.

7. Launcher preflight can consume diagnostics directly — our lane

• If a startup preflight wants to consume diagnostic results, the dsh-doctor/v1 envelope ({ok, checks:[{name,status,detail}]}, lowercase status, exit 0/1/2) is machine-parseable — no text scraping needed; aligned with dsh-plugin-doctor and dsh-diagnose (💡 Idea: Add 'dsh doctor' CLI command for environment & dependency diagnostics #1719).

8. --env-side gap (offline probes don't cover runtime internals) — worth a note, not a failure: sandbox denials / approval policy have no direct offline probe today; check commands honestly read session logs / config instead.

Want this as a PR to docs/03-profiles.md (I'd fit 1–6 into 3.5 with per-row 帖号, 7 as a pointer under the launcher/auto-recovery discussion), or is the inline checklist enough?