dsh-ecosystem-panel

给 DSH 实例装一块只读的生态总览面板：插件有没有加载、补丁还在不在、技能 frontmatter 有没有写坏、 依赖有没有升级风险 —— 一屏看完，🟢🟡🔴 三色。

它只诊断，不动手：不装包、不卸包、不升级、不改配置、不写任何被体检对象。

侧边栏底部「设置」齿轮上方会多一个图标按钮，点开就是面板；服务端只暴露一个只读接口：

GET /api/dsh-ecosystem-panel/state

1. 它看什么（六类 + 一个可选类）

设计红线（贯穿全仓）：读不到的东西一律显示「不可探测 + 原因」，绝不显示 0、绝不假装全绿。 面板 meta 里还带一份配置来源自证（每个配置键到底是从 CLI / 环境变量 / 配置文件 / 自动探测 / 默认值 哪一层读到的），换机器排障时先看它。

2. 前置条件

• 一个 DSH 实例（web profile），主包线见 §6 兼容性表
• Node ≥ 18.17（用到了内置 fetch / AbortSignal.timeout）
• YAML 解析器（js-yaml）：由宿主 profile 的依赖链提供（通常随主包自带）。解析不到时 ②④ 两类会显式显示「不可解析」，其它四类不受影响
• 可选的三个/四个外部脚本（解耦检查、档位 CLI、跨表校验器、适配层一致性校验器）——没有也能跑， 对应类目会降级；本仓不附带这些脚本（它们属于你自己的体检体系）

3. 安装三步

# ① 把包放进 profile 的 node_modules（本仓 clone 到任意位置后拷进去，或直接 clone 到该目录）
#    <数据根>/profiles/<profile>/node_modules/dsh-ecosystem-panel/
git clone <本仓地址> "<数据根>/profiles/web/node_modules/dsh-ecosystem-panel"

# ② 注册：profile 的 package.json 里
#      "dependencies": 加一条  "dsh-ecosystem-panel": "0.4.0"
#      "dsh.profile.bundles": 数组里加 "dsh-ecosystem-panel"

# ③ 重启 DSH（本插件没有热加载），然后打开 GUI：侧边栏齿轮上方应出现面板按钮

验证（不依赖 GUI）：

node "<数据根>/profiles/web/node_modules/dsh-ecosystem-panel/scripts/verify-state.mjs"
# 终端里应打印六类结果 + 配置来源自证

本仓只发 Release，不发 npm：把目录放进 profile 即可，不需要 npm install（dependencies 为空）。

4. 配置

优先级（每个键独立）：显式传入（插件 config / 调用参数） > 环境变量 > 配置文件 > 自动探测 > 内置默认。

4.1 环境变量

4.2 配置文件与示例

examples/ 下有五份可直接抄的示例：

用法：

DSH_ECOSYSTEM_PANEL_CONFIG=/path/to/my.config.json   # 指向你抄过去改的那份

4.3 降级语义（重要）

• 没配 ≠ 没有：③ 未配清单时显示「未配置 ⇒ 不可判定」，不会显示"0 个补丁全绿"； ⑥⑦ 与 ⑤ 同理（都带配置指引）。
• 抓不到：宿主首页抓不到 boot 清单时，① 只把"未知"标黄，并把抓取错误原文放进 meta.bootError。
• 停用：确实不需要某一类，就把它写进 disabledGroups —— 面板会显示一条「已按配置停用」的提示项 （比静默消失更清楚，且不计入汇总）。
• 配置解析失败（比如清单 JSON 坏了）不会让面板崩：meta.configErrors 里能看到原因，该键回落默认。

5. 界面

• 六类各占一张标签卡（Tab），Tab 上的小圆点 = 该类最差状态（红 > 黄 > 绿）
• 点「刷新」会重新取数；GET /state?refresh=1 强制重查 npm 最新版（否则 24h 缓存）
• 颜色：🟢 正常 / 🟡 风险或不可判定 / 🔴 异常（比如 patch insert 的实体缺失）
• 面板底部说明与标题可由配置覆盖（text.title / text.note / text.tabs，服务端经 meta.ui 下发）

6. 兼容性

7. 已知限制

1. js-yaml 依赖宿主提供 —— 解析不到时 ②④ 两类显示「不可解析」（不假绿），但也就查不了了。
2. boot 清单靠抓宿主首页的内联 __DSH_BOOT__ 段 —— 宿主若改了这个投影，① 的"加载状态"就变成未知（黄）。
3. ③ 的判定完全取决于你给的清单：本仓不内嵌任何环境的补丁清单，清单写错就会报错。
4. ⑤ 的颜色不来自本面板：它来自你配置的档位 CLI（唯一判定源）。本面板只渲染，绝不猜颜色。
5. ⑥⑦ 依赖外部脚本，本仓不带这些脚本；未配置时对应类目只会显示降级提示。
6. 升级体检会访问 npm registry（registry.npmjs.org），结果缓存 24h；离线时显示"远端查询失败"并继续用缓存。
7. 只读：面板没有任何写操作入口（唯一写文件的是升级体检自己的缓存）。
8. 前端只支持 web platform（dsh.client.inject 为空，不依赖任何 client 包）。
9. 界面文案为中文，可通过 text 配置覆盖；没有内置多语言切换。
10. 未做移动端专门优化（面板宽度自适应，但按钮/触摸交互没专门测过）。

8. 仓结构

lib/index.js          服务端：注册只读 route
lib/state.js          六类聚合逻辑（每个数据源都走配置层 + 显式降级）
lib/upgrade.js        ⑤ 升级体检（本地事实 + npm 缓存 → 外部只读 CLI → 渲染）
lib/config.js         配置层（优先级解析 + 占位符展开 + 来源自证）
lib/host-protocol.js  宿主协议常量（本插件只用 webServer 一个服务名）
lib/client.js         浏览器端：侧边栏按钮 + 面板（零 import）
cordis.patch.yml      bundle patch（把插件挂到宿主）
scripts/verify-source.mjs  发布前静态验证（语法 + 配置层行为 + 脱敏扫描）
scripts/test-fixture.mjs   干净临时路径上的端到端夹具（含缺数据降级断言）
scripts/verify-state.mjs   只读状态验证器（不依赖 GUI）
examples/                  五份配置示例
docs/RELEASING.md          发版规范与检查单

9. 自测

node scripts/verify-source.mjs .    # 语法 + 配置层行为 + 脱敏扫描（发布前必跑）
node scripts/test-fixture.mjs       # 端到端夹具：不需要任何真实安装，全在临时目录里造
node scripts/verify-state.mjs       # 对当前实例只读体检（打印六类 + 配置来源）

test-fixture.mjs 会现场造一个最小数据根（假 profile / 假插件实体 / 假技能 / 四个外部工具 stub）， 断言六类都能跑出结果，并专门验证「缺数据必显式降级」。

10. 相关组件

同属 DSH 生态的伴生组件，各自独立仓、独立版本、许可各自独立；它们都回链到同一份文档仓 ops-handoff-design （Gitee 镜像 https://gitee.com/kira905/ops-handoff-design）：

组件之间没有代码依赖，也不共享运行时 —— 之所以互指，是因为它们回答的是同一类人的同一批问题 （长期在自有机器上跑 agent：装得下、找得到、看得见、查得清）。谁装谁不装，互不影响。

11. 许可

AGPL-3.0-only（见 LICENSE 全文；package.json 的 license 字段同值）。 以 AGPL 发布意味着：你可以自由使用、修改、再分发，但通过网络向他人提供本软件的修改版时， 必须按 AGPL 一并提供对应源码。