[Bug Report] profile 中单个无法解析的插件条目导致 dsh web 整体启动失败：fail-fast 无跳过机制，错误信息不指明声明文件与修复路径

[DRAG0NM]

摘要

当用户的 profile（~/.dsh/profiles/<name>/）组合里存在一个无法解析的插件条目（包不存在/已改名/被移除）时，loader 在启动阶段 fail-fast，整个 dsh web 启动中止（plugin tree failed to load），没有任何跳过或降级路径；同时顶层错误链把最深层的"哪个条目、哪个包、从哪个目录导入"信息层层包装成难以定位的 AggregateError，不指明该条目声明在哪个 profile 文件、也不给修复动作。这是 #328 的完整现象：用户安装社区组件后 profile 多了一个 ui-dsh-aionui-panel（@deepseek-ai/dsh-client-ui-aionui-panel，官方 rc.6 包不存在此包），此后 pnpm dsh web 必崩，且错误堆栈几乎无法引导修复。

复现步骤

1. 在用户 profile 的组合文件（如 ~/.dsh/profiles/web/cordis.patch.yml）中加入一条引用不存在包的条目，例如：

   - id: ui-dsh-aionui-panel
     name: '@deepseek-ai/dsh-client-ui-aionui-panel'

2. 运行 dsh web（或源码运行 pnpm dsh web）。
3. 结果：启动失败，报错链为
   plugin tree failed to load → failed to apply loader entry include (cordis:include) → loader entries failed to apply → failed to import loader entry ui-dsh-aionui-panel ... Cannot find package '@deepseek-ai/dsh-client-ui-aionui-panel' imported from C:\Users\...\.dsh\profiles\web\（win10 运行 pnpm dsh web报错，之前正常，安装完dsh-web-ui 后报错。 #328 原文，此链深达 6 层）。
4. 修复只能靠人工：编辑 profile 文件删掉该条目（或安装对应包）——但错误信息没有告诉用户"去哪个文件、删什么"。

根因（源码定位，rc.6）

1. 条目加载 fail-fast，无 optional 语义：loader 对每个 profile 条目的 import 失败直接
   抛错（用户堆栈中的 vendor/loader/src/config/entry.ts:282-287：failed to import loader entry <id>: Cannot find package <pkg> imported from <dir>），EntryGroup.update 整体
   reject（group.ts:80）——一个坏条目 = 整棵插件树失败，没有"跳过缺失条目"的机制。
2. 顶层错误丢上下文：@deepseek-ai/dsh-app-boot/lib/index.js L1164-1174 把 loader
   失败统一包装成 plugin tree failed to load（stage 名），后续的
   failed to apply loader entry include (cordis:include) / loader entries failed to apply 只说明"include 组失败"，不重复携带最内层的条目 id 与包名——用户看到的
   第一屏错误无法定位。
3. 无修复引导：错误链没有任何"删除 profile 中该条目 / 安装该包 / 用其他 profile 启动"
   的提示；而 profile 文件可能在多个位置（用户 profile、bundle 组合、patch 层），
   用户无从知道改哪里。
4. 触发面（非本 bug，但说明常见性）：条目可能来自社区安装器（win10 运行 pnpm dsh web报错，之前正常，安装完dsh-web-ui 后报错。 #328 的 dsh-web-ui）、
   会话中 agent 编辑 patch 文件（安装一个自己开发的图片识别插件，把dsh搞崩了（ 本轮运行失败Invalid schema for function 'vision_query': schema must be a JSON Schema of 'type: "object"', got 'type: null'.） #297 案例）、或官方包改名后的陈旧引用（dsh web fails after global pnpm install: loader cannot resolve ~88 plugin packages #204 族）。

建议修复

方案 A（推荐）· 顶层错误携带条目级上下文与修复指引：在 dsh-app-boot（或 loader
的 include 失败包装层）把最内层的"条目 id + 包名 + 导入目录"上浮到第一屏，并追加
一条可执行建议："entry 'X' 在 <profile 目录> 无法解析——从该 profile 的组合文件中
删除此条目，或安装对应包后重试；也可用 --profile <其他> 启动"。改动小、收益直接。

方案 B · 缺失条目可跳过：给 loader 条目增加 optional: true（或启动参数
--ignore-missing-entries），import 失败时记录 warn 并跳过，而不是整树失败。
需要区分"可选 UI 装饰插件"（跳过无害）与"核心服务插件"（跳过会半残）——建议只对
optional 标记生效，默认仍 fail-fast。

方案 C（诊断工具）· profile 预检：dsh web 启动前（或提供 dsh doctor 子命令）
扫描 profile 组合中每条目的包可解析性，先于 loader 给出"哪个文件哪一行"的清单。
社区已有 dsh-doctor 工具（#432）做类似事，官方内置可根治此体验。

影响

• 任何引入过陈旧/缺失插件条目的用户，dsh web 直接不可启动，且修复靠人工翻
  profile 文件（win10 运行 pnpm dsh web报错，之前正常，安装完dsh-web-ui 后报错。 #328、dsh web fails after global pnpm install: loader cannot resolve ~88 plugin packages #204 族）
• 社区安装器（如 win10 运行 pnpm dsh web报错，之前正常，安装完dsh-web-ui 后报错。 #328 的 dsh-web-ui）与"agent 改 profile"（安装一个自己开发的图片识别插件，把dsh搞崩了（ 本轮运行失败Invalid schema for function 'vision_query': schema must be a JSON Schema of 'type: "object"', got 'type: null'.） #297）都可能制造这种
  坏条目，官方没有兜底
• 错误链 6 层深、无修复指引，对非专家用户几乎是死路

环境

• 源码定位：0.1.0-rc.6（npx 缓存安装包：dsh-app-boot/lib/index.js L1164-1174）
  • 用户堆栈中的 loader entry/group（vendor/loader/src/config/entry.ts:282、
    group.ts:80，rc.6 同构）
• 原报告：win10 运行 pnpm dsh web报错，之前正常，安装完dsh-web-ui 后报错。 #328（Windows 10，源码运行 pnpm dsh web；0 评论，此前无人分析）

验证材料

• win10 运行 pnpm dsh web报错，之前正常，安装完dsh-web-ui 后报错。 #328 原始堆栈即完整复现证据（6 层错误链，最深一层为 ERR_MODULE_NOT_FOUND）
• 已核实：官方 rc.6 包目录中不存在 @deepseek-ai/dsh-client-ui-aionui-panel，
  出厂 profile 也无 aionui 引用 → 条目来自用户侧，但产品对坏条目零兜底
• 修复方向对照：删除该条目后启动恢复正常（win10 运行 pnpm dsh web报错，之前正常，安装完dsh-web-ui 后报错。 #328 现象的自证）

---

First analysis of discussion #328. Happy to open a PR with fix option A.

[boyin111-1]

Same failure class as #1197 — a single unresolvable entry kills the whole tree with an opaque AggregateError. This exact scenario (dangling reference from a removed/renamed package) is what the #1197 root-cause chain covers (loader resolves against the profile dir, no validation, no degradation, --dump-config passes as a false positive).

Two things already exist for this:

1. Fix (implemented, pending external PRs): boot-time diagnostic in packages/boot/app-boot — on plugin tree failed to load, it resolves insert-referenced plugins from the profile dir and appends the failing names + fix hint. Details in dsh web fails to boot: unresolvable plugin reference in profile patch (cordis.patch.yml) #1197 comment (fork: boyin111-1/deepseek-harness, branch feat/boot-dangling-plugin-diagnostics).

2. Offline checker (available now): https://github.com/boyin111-1/dsh-doctor — npx --yes github:boyin111-1/dsh-doctor scans profiles for dangling refs (from the same profile-dir anchor), broken file: links, duplicate ids, dual @deepseek-ai instances. Would have pinpointed the ui-dsh-aionui-panel entry in seconds.

Worth consolidating this into the #1496 guardrails advisory alongside #1197/#1404 — same missing-validation root.