@kira905/dsh-ecosystem-panel 0.0.0-stage → 0.4.4

package/README.en.md

@@ -0,0 +1,220 @@
+# dsh-ecosystem-panel
+
+> **Status**: published on npm as `@kira905/dsh-ecosystem-panel` (repository Releases remain available)
+> **Repository**: <https://github.com/kira905/dsh-ecosystem-panel> ｜ <https://gitee.com/kira905/dsh-ecosystem-panel>
+> **License**: AGPL-3.0-only — see [`LICENSE`](./LICENSE)
+> **中文**: [README.md](./README.md)
+
+> A **read-only** ecosystem overview panel for a DSH instance: did the plugins load, are the patches
+> still in place, is any skill frontmatter broken, do the dependencies carry an upgrade risk — all on
+> one screen, in three colours (green / yellow / red).
+>
+> It **only diagnoses, it never acts**: it installs nothing, removes nothing, upgrades nothing,
+> changes no configuration, and writes to none of the objects it inspects.
+
+A new icon button appears in the sidebar above the settings gear; clicking it opens the panel.
+The server side exposes exactly one read-only endpoint:
+
+```
+GET /api/dsh-ecosystem-panel/state
+```
+
+## Design basis
+
+This component is one implementation of the operational system described in
+[ops-handoff-design](https://github.com/kira905/ops-handoff-design), with the design basis
+(the fixed four questions that documentation repository defines):
+
+- **Why it exists and where its boundary is** → see *Design Discipline for a Read-Only Monitoring Panel* **§1 the questions the panel must answer**, **§2 display discipline (not probeable + reason)**; this component's six checks are one landing of that discipline
+- **Its compatibility window with the host** → see *Multi-machine Handoff and Cloud Relay* **§4.5 "compatibility requirements"** (see also §6 "Compatibility" in this README)
+- **This component's own pitfalls and measurements** → the "Known limitations" section of this README; see also *Design Discipline for a Read-Only Monitoring Panel* **§7 summary of design lessons** (where the three cases of "silently not reporting" came from)
+- **Documentation repository** → Gitee (mirror) <https://gitee.com/kira905/ops-handoff-design>
+  ｜ GitHub (primary) <https://github.com/kira905/ops-handoff-design>
+  (the documentation repository's component index points back to this repository; the two repositories link to each other and version independently)
+
+> Design documents carry no concrete repository addresses (a hard-coded address becomes a dead link);
+> the implementation list is kept in the documentation repository's component index — this repository
+> only links back to the sections.
+
+---
+
+## 1. What it looks at (six classes plus one optional one)
+
+| Class | Data source | Judgement | When data is missing |
+|---|---|---|---|
+| ① **bundle plugins** | the profile's `package.json` (`dsh.profile.bundles` + `dependencies`) + each package entity's `package.json` + the boot manifest of the host home page | whether the entity exists / whether the declared version drifts from the entity version / client capability declared but not loaded in boot = red | boot cannot be fetched ⇒ shows "load state unknown" (yellow), **not treated as loaded** |
+| ② **patch insert plugins** | the `insert` entries in the profile's `cordis.patch.yml` | whether the entity directory can be resolved (profile layer → shared fallback layer); entries under `disabled` are marked yellow | the YAML parser is unavailable ⇒ says "not parseable" explicitly instead of treating it as an empty list |
+| ③ **patch health** | **the patch manifest you supply** (an external JSON) | a marker-string scan, entry by entry: a missing `contains` = a customisation was overwritten (yellow); the target file is gone = red; a `notContains` hit = leftovers | the manifest is not configured ⇒ shows "not configured ⇒ cannot be judged" (yellow), **never "0 patches"** |
+| ④ **skills** | the frontmatter of `skills/*/SKILL.md` under the data root | missing `name` / `description`, frontmatter parse failure | the directory does not exist ⇒ reports `skillsDirOk=false` |
+| ⑤ **upgrade check** | local entity versions + the latest npm registry version (24 h file cache) + the wording of your rule table | the colour is decided by an **external read-only CLI**; this panel only renders it (when that is unavailable it shows "tier unavailable" + the reason, and **never guesses a colour**) | no CLI configured ⇒ `unknown` on every row + the reason |
+| ⑥ **decoupling health** | **the external check script you supply** (reused by dynamic `import` of its exported function — the judgement is not copied) | R1 static import of a host symbol = red; dynamic import / dependencies not driven to zero = yellow | no script configured ⇒ one yellow row + configuration guidance |
+| ⑦ **cross-table admission consistency** (optional) | **the external validator you supply** | three states, explicitly enumerated: `ok / fail / unavailable`; a missing `asOf` is judged `unavailable` | not configured ⇒ `unavailable` (**not** a green 0/0/0) |
+
+**Design red line (throughout the repository)**: anything that cannot be read is shown as "not probeable + reason" — **never 0, never a pretend all-green**.
+The panel meta also carries a **self-attestation of configuration provenance** (which layer each configuration key was actually read from: CLI / environment variable / config file / auto-detection / built-in default). Look at it first when troubleshooting on a different machine.
+
+## 2. Prerequisites
+
+- A DSH instance (web profile); for the host package line see the compatibility table in §6
+- Node ≥ 18.17 (it uses the built-in `fetch` / `AbortSignal.timeout`)
+- **A YAML parser (`js-yaml`)**: provided by the host profile's dependency chain (normally shipped with the host package). When it cannot be resolved, classes ② and ④ say "not parseable" explicitly; the other four are unaffected
+- The optional three or four external scripts (decoupling check, tier CLI, cross-table validator, adapter-layer consistency checker) — **it runs without them**; the corresponding classes degrade. This repository does not ship these scripts (they belong to your own check system)
+
+## 3. Installing in three steps
+
+```bash
+# 1. Install it into the profile (npm package name: @kira905/dsh-ecosystem-panel)
+npm install @kira905/dsh-ecosystem-panel --prefix "<data root>/profiles/web"
+#   offline / editing the source: clone this repository to
+#   "<data root>/profiles/web/node_modules/@kira905/dsh-ecosystem-panel"
+
+# 2. Register it in the profile's package.json:
+#      "dependencies": add  "@kira905/dsh-ecosystem-panel": "0.4.4"
+#      "dsh.profile.bundles": add "@kira905/dsh-ecosystem-panel" to the array
+
+# 3. Restart DSH (this plugin has no hot reload), then open the GUI: the panel button should appear
+#    above the settings gear in the sidebar
+```
+
+Verification (no GUI needed):
+
+```bash
+node "<data root>/profiles/web/node_modules/@kira905/dsh-ecosystem-panel/scripts/verify-state.mjs"
+# the terminal should print the six classes plus the configuration-provenance self-attestation
+```
+
+> The package is published on npm (`@kira905/dsh-ecosystem-panel`): `npm install` only fetches the
+> package itself (`dependencies` is empty; `js-yaml` comes from the host profile). Earlier releases
+> shipped Releases only; this version (`0.4.4`) is the first to ship under the scoped npm name.
+
+## 4. Configuration
+
+Precedence (**per key, independently**): `explicit input (plugin config / call argument)` > `environment variable` > `config file` > `auto-detection` > `built-in default`.
+
+### 4.1 Environment variables
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `DSH_ECOSYSTEM_PANEL_HOME` | DSH data root | `os.homedir()/.dsh` (`DSH_HOME` has the same effect, at lower precedence) |
+| `DSH_ECOSYSTEM_PANEL_PROFILE` | profile name | `web` |
+| `DSH_ECOSYSTEM_PANEL_WEB_URL` | base URL of this instance (used to fetch the boot manifest) | `DSH_WEB_URL`, otherwise `http://127.0.0.1:3080` |
+| `DSH_ECOSYSTEM_PANEL_TOOLS_DIR` | external tools directory (**never auto-detected**) | empty ⇒ the classes that depend on it degrade |
+| `DSH_ECOSYSTEM_PANEL_MAIN_NM` | host package `node_modules` | detected from the global npm layout; unusable when detection fails |
+| `DSH_ECOSYSTEM_PANEL_CONFIG` | path to the JSON configuration file | empty |
+| `DSH_ECOSYSTEM_PANEL_CACHE_FILE` | upgrade-check cache file | `<data root>/ecosystem-panel-upgrade-cache.json` |
+| `DSH_ECOSYSTEM_PANEL_DECOUPLING_SCRIPT` | decoupling check script | `<toolsDir>/check-decoupling.mjs` |
+| `DSH_ECOSYSTEM_PANEL_TRIAGE_CLI` | read-only upgrade tier CLI | `<toolsDir>/upgrade-triage-cli.mjs` |
+| `DSH_ECOSYSTEM_PANEL_REGISTRY_AUDIT_LIB` | cross-table admission validator | `<toolsDir>/registry-audit.mjs` |
+| `DSH_ECOSYSTEM_PANEL_HOST_ADAPTER_SYNC` | adapter-layer consistency checker (optional) | `<toolsDir>/sync-host-adapter.mjs` |
+| `DSH_ECOSYSTEM_PANEL_PATCH_MANIFEST_FILE` | patch manifest JSON | empty ⇒ ③ shows "not configured" |
+| `DSH_ECOSYSTEM_PANEL_UPGRADE_RULES_FILE` | upgrade rule table JSON | empty |
+| `DSH_ECOSYSTEM_PANEL_BREAKING_SYMBOLS_FILE` | breaking-symbol table JSON | empty |
+| `DSH_ECOSYSTEM_PANEL_LABELS_FILE` | package name → one-line description, JSON | empty (an unregistered package simply has no description) |
+| `DSH_ECOSYSTEM_PANEL_DISABLED_GROUPS` | classes disabled as a whole (comma-separated) | all enabled |
+| `DSH_ECOSYSTEM_PANEL_WEBSERVER_SERVICE` | host web server service name | `webServer` |
+
+### 4.2 Configuration file and examples
+
+`examples/` holds five samples you can copy directly:
+
+| File | Configuration it covers |
+|---|---|
+| `ecosystem-panel.config.example.json` | overview (where each key lives and what shape it takes) |
+| `patch-manifest.example.json` | ③ patch manifest (all three shapes — `checks` / `special` / `retired` — have examples; `${HOME}` can be used as a placeholder inside strings) |
+| `upgrade-rules.example.json` | ⑤ rule-table wording (`verdict` is only a wording category, it does not decide the colour) |
+| `breaking-symbols.example.json` | reference table of breaking symbols in the host package |
+| `labels.example.json` | package name → one-line description |
+
+Usage:
+
+```bash
+DSH_ECOSYSTEM_PANEL_CONFIG=/path/to/my.config.json   # points at the copy you edited
+```
+
+### 4.3 Degradation semantics (important)
+
+- **Not configured ≠ absent**: with no manifest configured, ③ shows "not configured ⇒ cannot be judged" and never "0 patches, all green"; ⑥⑦ and ⑤ work the same way (each carries configuration guidance).
+- **Cannot be fetched**: when the boot manifest cannot be fetched from the host home page, ① marks only the "unknown" as yellow and puts the raw fetch error into `meta.bootError`.
+- **Disabled**: if a class is genuinely not needed, put it into `disabledGroups` — the panel then shows a "disabled by configuration" notice (clearer than silently disappearing, and not counted in the summary).
+- A configuration parse failure (a broken manifest JSON, say) does not crash the panel: `meta.configErrors` carries the reason and that key falls back to its default.
+
+## 5. Interface
+
+- Each of the six classes has its own tab; the small dot on a tab = the worst state of that class (red > yellow > green)
+- Clicking "refresh" fetches the data again; `GET /state?refresh=1` forces a fresh lookup of the npm latest version (otherwise the 24 h cache is used)
+- Colours: green = healthy / yellow = at risk or not judgeable / red = abnormal (a missing patch insert entity, for instance)
+- The panel's title and footer note can be overridden by configuration (`text.title` / `text.note` / `text.tabs`, delivered by the server through `meta.ui`)
+
+## 6. Compatibility
+
+| Host package line | Status | Basis |
+|---|---|---|
+| **`0.2.0-rc.2`** | ✅ **Measured end-to-end (2026-10-16)** | **The baseline of the range this version declares in `peerDependencies`**: installed and exercised for real on an isolated instance (separate data root + port 3090) — `scripts/verify-state.mjs` (read-only, six check classes) **completed with rc=0**, reading that instance's data root and configuration provenance; the client half `client.js` appears in the plugin resource list of the instance's startup HTML |
+| later `0.2.x` | ⚠️ **Not measured; no promise** (declared upper bound `<0.3.0`) | — |
+| the `0.1.1-rc.2` / `0.1.5` lines | ⚠️ Historical static check (**this version no longer declares a 0.1.x range**) | see this section in `v0.4.3` and earlier |
+| the **readings** of the upgrade-check / decoupling-health cards | ⚠️ **Not calibrated on a 0.2.0 instance** | Since 0.1.5, client resources use a "roster + merged URL" scheme; whether these two cards read it completely is unverified — **the most likely symptom is conservative readings, not a crash** |
+| other | Unknown | self-test required |
+
+## 7. Known limitations
+
+1. **`js-yaml` is provided by the host** — when it cannot be resolved, classes ② and ④ show "not parseable" (no false green), but that also means they cannot be checked.
+2. **The boot manifest is fetched from the host home page**, from the inline `__DSH_BOOT__` block — if the host changes that projection, ①'s "load state" becomes unknown (yellow).
+3. **③'s verdict depends entirely on the manifest you supply**: this repository **embeds no patch manifest** for any environment, so a wrong manifest produces wrong reports.
+4. **⑤'s colour does not come from this panel**: it comes from the tier CLI you configure (the single source of judgement). The panel only renders it and never guesses a colour.
+5. **⑥⑦ depend on external scripts**, which this repository does not ship; when they are not configured the corresponding classes only show a degradation notice.
+6. **The upgrade check reaches the npm registry** (`registry.npmjs.org`) and caches its result for 24 h; when offline it shows "remote lookup failed" and keeps using the cache.
+7. **Read-only**: the panel has no write entry point at all (the only file it writes is the upgrade check's own cache).
+8. **The front end supports the web platform only** (`dsh.client.inject` is empty; it depends on no client package).
+9. **The interface copy is Chinese**, overridable through the `text` configuration; there is no built-in language switch.
+10. **No dedicated mobile optimisation** (the panel width adapts, but buttons and touch interaction have not been tested specifically).
+
+## 8. Repository layout
+
+```
+lib/index.js          server side: registers the read-only route
+lib/state.js          the six-class aggregation logic (every data source goes through the config layer and degrades explicitly)
+lib/upgrade.js        ⑤ the upgrade check (local facts + npm cache → external read-only CLI → rendering)
+lib/config.js         the config layer (precedence resolution + placeholder expansion + provenance self-attestation)
+lib/host-protocol.js  host protocol constants (this plugin uses only the single service name webServer)
+lib/client.js         browser side: sidebar button + panel (zero imports)
+cordis.patch.yml      bundle patch (mounts the plugin into the host)
+scripts/verify-source.mjs   pre-release static verification (syntax + config-layer behaviour + sanitization scan)
+scripts/test-fixture.mjs    end-to-end fixture on a clean temporary path (with assertions for degradation on missing data)
+scripts/verify-state.mjs    read-only state verifier (no GUI needed)
+examples/                   five configuration examples
+docs/RELEASING.md           release conventions and checklist
+```
+
+## 9. Self-checks
+
+```bash
+node scripts/verify-source.mjs .    # syntax + config-layer behaviour + sanitization scan (must be run before a release)
+node scripts/test-fixture.mjs       # end-to-end fixture: needs no real installation, everything is built in a temporary directory
+node scripts/verify-state.mjs       # read-only health check of the current instance (prints the six classes + configuration provenance)
+```
+
+`test-fixture.mjs` builds a minimal data root on the spot (a fake profile / fake plugin entities / fake skills / four external tool stubs), asserts that all six classes produce a result, and specifically verifies that "missing data always degrades explicitly".
+
+## 10. Related components
+
+Sibling components in the same DSH ecosystem — separate repositories, separate versions and separate licenses. They all link back to the same documentation repository,
+[`ops-handoff-design`](https://github.com/kira905/ops-handoff-design)
+(Gitee mirror: <https://gitee.com/kira905/ops-handoff-design>):
+
+| Repository | What it does | How it relates to this one |
+|---|---|---|
+| `dsh-ecosystem-panel` | Read-only ecosystem overview panel | **this repo** |
+| [`dsh-butler-archive`](https://github.com/kira905/dsh-butler-archive) | Session archiving (list / preview / restore / delete, plus optional auto-archive) | It is **one of the objects class ③ observes**: it registers through an `insert` in `cordis.patch.yml`, and this panel reports red when its entity is missing |
+| [`dsh-session-title-live`](https://github.com/kira905/dsh-session-title-live) | Session titles that track the conversation live | It also registers through an `insert` in `cordis.patch.yml` (no client half); "did the plugin actually load" is answered by class ① of this panel |
+| [`dsh-diagnostic-tools`](https://github.com/kira905/dsh-diagnostic-tools) | Diagnostic forensics toolkit: dependency-closure check + session image attachment reconciliation | Complementary division of labour: this panel answers **"how is it today"** (continuous, read-only, three colours) while that one answers **"what exactly is broken, and how do I fix it"** (offline, re-runnable, with fixes and a rollback list) — both only diagnose |
+| [`dsh-task-board-local`](https://github.com/kira905/dsh-task-board-local) | Self-maintained task board (a card = a real session + a human acceptance gate) | It is a **typical subject of classes ① / ③**: built in-house and registered through an `insert` in `cordis.patch.yml` — the two silent failure modes, plugin load state and patch health, are visible at a glance on this panel |
+| [`dsh-firstaid`](https://github.com/kira905/dsh-firstaid) | Zero-dependency incident toolkit: will not start / hangs / a change to undo / deleted data — four on-site scenarios behind one entry point | The contingency plan: **this panel may itself be the broken one** (if the panel will not start, or cannot fetch its data, you cannot use it to diagnose itself), and that is when the other one takes over |
+
+> There are **no code dependencies** between the components and they share no runtime — they point at each other because they answer the same class of question for the same kind of person (running an agent on your own machine over the long term: install it, find it, see it, diagnose it). Installing one does not affect the others.
+
+## 11. License
+
+**AGPL-3.0-only plus a commercial license** (dual licensing; see the full text in `LICENSE`; the `license` field in `package.json` carries `AGPL-3.0-only`).
+
+- ⚠️ **The AGPL does not forbid commercial use by itself**: you may use, modify and redistribute it freely (commercial use included), but **if you make a modified version available to others over a network, you must offer the corresponding source under the AGPL as well**;
+- "+ a commercial license" = **dual licensing**: obtain a **commercial license** if you need it in a **closed-source** or **commercial** setting (where AGPL's copyleft obligations do not apply) — there is no public contact address yet, so **please reach out by opening an issue**.

package/README.md

@@ -1,3 +1,216 @@
-# Temporary Holding Version
+# dsh-ecosystem-panel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **English**: [README.en.md](./README.en.md)
+
+> 给 DSH 实例装一块**只读**的生态总览面板：插件有没有加载、补丁还在不在、技能 frontmatter 有没有写坏、
+> 依赖有没有升级风险 —— 一屏看完，🟢🟡🔴 三色。
+>
+> 它**只诊断，不动手**：不装包、不卸包、不升级、不改配置、不写任何被体检对象。
+
+侧边栏底部「设置」齿轮上方会多一个图标按钮，点开就是面板；服务端只暴露一个只读接口：
+
+```
+GET /api/dsh-ecosystem-panel/state
+```
+
+## 设计依据
+
+本组件是「[ops-handoff-design](https://github.com/kira905/ops-handoff-design)」所述运维体系的一个实现，
+设计依据（对应文档仓约定的固定四问）：
+
+- **它为什么存在、边界在哪** → 见《只读监控面板的设计纪律》**§1 面板要回答的问题**、**§2 显示纪律（不可探测 + 原因）**；本组件的六类体检正是那份纪律的一次落地
+- **它与宿主版本的兼容区间** → 见《多机交接与云中继》**§4.5「兼容性要求」**（另见本 README 第 6 节「兼容性」）
+- **本组件特有的坑与实测** → 见本 README「已知限制」一节；另见《只读监控面板的设计纪律》**§7 设计教训汇总**（三次"静默不报"的来历）
+- **文档仓地址** → Gitee（镜像）<https://gitee.com/kira905/ops-handoff-design>
+  ｜ GitHub（主）<https://github.com/kira905/ops-handoff-design>
+  （文档仓的组件索引表回指本仓；两仓互链、版本各自独立）
+
+> 设计稿里不写具体仓库地址（写死即死链），实现清单统一收在文档仓的组件索引表里——本仓只负责回链章节。
+
+---
+
+## 1. 它看什么（六类 + 一个可选类）
+
+| 类目 | 数据来源 | 判定 | 数据缺失时 |
+|---|---|---|---|
+| ① **bundle 插件** | profile 的 `package.json`（`dsh.profile.bundles` + `dependencies`）+ 各包实体 `package.json` + 宿主首页的 boot 清单 | 实体在不在 / 声明版本与实体版本是否漂移 / 声明了 client 能力但 boot 里没加载 = 🔴 | boot 抓不到 ⇒ 显示「加载状态未知」（黄），**不当作已加载** |
+| ② **patch insert 插件** | profile 的 `cordis.patch.yml` 里的 `insert` 条目 | 实体目录能否解析到（profile 层 → 共享 fallback 层）；被 `disabled` 的标黄 | YAML 解析器不可用 ⇒ 明说「不可解析」，不当成空清单 |
+| ③ **补丁健康** | **你提供的补丁清单**（外置 JSON） | 逐条做特征串扫描：`contains` 缺一个 = 定制被冲掉（黄）；目标文件没了 = 🔴；`notContains` 命中 = 残留 | 清单没配 ⇒ 显示「未配置 ⇒ 不可判定」（黄），**不显示"0 个补丁"** |
+| ④ **技能** | 数据根下 `skills/*/SKILL.md` 的 frontmatter | 缺 `name` / `description`、frontmatter 解析失败 | 目录不存在 ⇒ 报 `skillsDirOk=false` |
+| ⑤ **升级体检** | 本地实体版本 + npm registry 最新版（24h 文件缓存）+ 你的规则表文案 | 颜色由**外部只读 CLI** 判定；本面板只渲染（拿不到就显示「档位不可用」+ 原因，**绝不猜颜色**） | 没配 CLI ⇒ 每行 `unknown` + 原因 |
+| ⑥ **解耦健康** | **你提供的外部检查脚本**（动态 import 复用其导出函数，不复制判定） | R1 静态 import 宿主符号 = 🔴；动态导入/依赖未归零 = 🟡 | 没配脚本 ⇒ 一条 🟡 + 配置指引 |
+| ⑦ **跨表准入一致性**（可选） | **你提供的外部校验器** | 三态显式枚举 `ok / fail / unavailable`；`asOf` 缺失即判 `unavailable` | 没配 ⇒ `unavailable`（**不是** 0/0/0 绿） |
+
+**设计红线（贯穿全仓）**：读不到的东西一律显示「不可探测 + 原因」，**绝不显示 0、绝不假装全绿**。
+面板 meta 里还带一份**配置来源自证**（每个配置键到底是从 CLI / 环境变量 / 配置文件 / 自动探测 / 默认值
+哪一层读到的），换机器排障时先看它。
+
+## 2. 前置条件
+
+- 一个 DSH 实例（web profile），主包线见 §6 兼容性表
+- Node ≥ 18.17（用到了内置 `fetch` / `AbortSignal.timeout`）
+- **YAML 解析器（`js-yaml`）**：由宿主 profile 的依赖链提供（通常随主包自带）。解析不到时 ②④
+  两类会显式显示「不可解析」，其它四类不受影响
+- 可选的三个/四个外部脚本（解耦检查、档位 CLI、跨表校验器、适配层一致性校验器）——**没有也能跑**，
+  对应类目会降级；本仓不附带这些脚本（它们属于你自己的体检体系）
+
+## 3. 安装三步
+
+```bash
+# ① 装进 profile（npm 包名：@kira905/dsh-ecosystem-panel）
+npm install @kira905/dsh-ecosystem-panel --prefix "<数据根>/profiles/web"
+#   离线 / 要改源码时：把本仓 clone 到
+#   "<数据根>/profiles/web/node_modules/@kira905/dsh-ecosystem-panel"
+
+# ② 注册：profile 的 package.json 里
+#      "dependencies": 加一条  "@kira905/dsh-ecosystem-panel": "0.4.4"
+#      "dsh.profile.bundles": 数组里加 "@kira905/dsh-ecosystem-panel"
+
+# ③ 重启 DSH（本插件没有热加载），然后打开 GUI：侧边栏齿轮上方应出现面板按钮
+```
+
+验证（不依赖 GUI）：
+
+```bash
+node "<数据根>/profiles/web/node_modules/@kira905/dsh-ecosystem-panel/scripts/verify-state.mjs"
+# 终端里应打印六类结果 + 配置来源自证
+```
+
+> 包已发布到 npm（`@kira905/dsh-ecosystem-panel`）：`npm install` 只装它自己（`dependencies` 为空，
+> `js-yaml` 由宿主 profile 提供）。早期版本只发 Release、不进 npm；本版（`0.4.4`）起以 scope 包名发布。
+
+## 4. 配置
+
+优先级（**每个键独立**）：`显式传入（插件 config / 调用参数）` > `环境变量` > `配置文件` > `自动探测` > `内置默认`。
+
+### 4.1 环境变量
+
+| 变量 | 作用 | 默认 |
+|---|---|---|
+| `DSH_ECOSYSTEM_PANEL_HOME` | DSH 数据根 | `os.homedir()/.dsh`（`DSH_HOME` 同效、优先级更低） |
+| `DSH_ECOSYSTEM_PANEL_PROFILE` | profile 名 | `web` |
+| `DSH_ECOSYSTEM_PANEL_WEB_URL` | 本实例基址（抓 boot 清单用） | `DSH_WEB_URL`，否则 `http://127.0.0.1:3080` |
+| `DSH_ECOSYSTEM_PANEL_TOOLS_DIR` | 外部工具目录（**不自动探测**） | 空 ⇒ 依赖它的类目降级 |
+| `DSH_ECOSYSTEM_PANEL_MAIN_NM` | 宿主主包 node_modules | 按全局 npm 布局探测；探测不到即判不可用 |
+| `DSH_ECOSYSTEM_PANEL_CONFIG` | 配置文件 JSON 路径 | 空 |
+| `DSH_ECOSYSTEM_PANEL_CACHE_FILE` | 升级体检缓存文件 | `<数据根>/ecosystem-panel-upgrade-cache.json` |
+| `DSH_ECOSYSTEM_PANEL_DECOUPLING_SCRIPT` | 解耦检查脚本 | `<toolsDir>/check-decoupling.mjs` |
+| `DSH_ECOSYSTEM_PANEL_TRIAGE_CLI` | 升级档位只读 CLI | `<toolsDir>/upgrade-triage-cli.mjs` |
+| `DSH_ECOSYSTEM_PANEL_REGISTRY_AUDIT_LIB` | 跨表准入校验器 | `<toolsDir>/registry-audit.mjs` |
+| `DSH_ECOSYSTEM_PANEL_HOST_ADAPTER_SYNC` | 适配层一致性校验器（可选） | `<toolsDir>/sync-host-adapter.mjs` |
+| `DSH_ECOSYSTEM_PANEL_PATCH_MANIFEST_FILE` | 补丁清单 JSON | 空 ⇒ ③ 显示「未配置」 |
+| `DSH_ECOSYSTEM_PANEL_UPGRADE_RULES_FILE` | 升级规则表 JSON | 空 |
+| `DSH_ECOSYSTEM_PANEL_BREAKING_SYMBOLS_FILE` | 断裂符号表 JSON | 空 |
+| `DSH_ECOSYSTEM_PANEL_LABELS_FILE` | 包名 → 一句话简介 JSON | 空（没登记的包只是没有简介） |
+| `DSH_ECOSYSTEM_PANEL_DISABLED_GROUPS` | 整组停用的类目（逗号分隔） | 全开 |
+| `DSH_ECOSYSTEM_PANEL_WEBSERVER_SERVICE` | 宿主 web server 服务名 | `webServer` |
+
+### 4.2 配置文件与示例
+
+`examples/` 下有五份可直接抄的示例：
+
+| 文件 | 对应配置 |
+|---|---|
+| `ecosystem-panel.config.example.json` | 总览（各键的位置与形态） |
+| `patch-manifest.example.json` | ③ 补丁清单（`checks` / `special` / `retired` 三种形态都有例子，字符串里可用 `${HOME}` 占位符） |
+| `upgrade-rules.example.json` | ⑤ 规则表文案（`verdict` 只是文案分类，不决定颜色） |
+| `breaking-symbols.example.json` | 宿主主包断裂符号参考底表 |
+| `labels.example.json` | 包名 → 一句话简介 |
+
+用法：
+
+```bash
+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. 兼容性
+
+| 宿主主包线 | 状态 | 依据 |
+|---|---|---|
+| **`0.2.0-rc.2`** | ✅ **已端到端实测（2026-10-16）** | **本版 `peerDependencies` 声明的区间基线**：在隔离实例（独立数据根 + 端口 3090）上真装真跑 —— 本仓 `scripts/verify-state.mjs`（只读六类体检）**rc=0 跑通**，读到了该实例的数据根与配置来源；客户端半 `client.js` 出现在实例启动 HTML 的插件资源清单里 |
+| `0.2.x` 后续版本 | ⚠️ **未实测，不作承诺**（区间上界 `<0.3.0`） | — |
+| `0.1.1-rc.2` / `0.1.5` 线 | ⚠️ 历史静态核对（**本版起 `peerDependencies` 不再声明 0.1.x**） | 见 `v0.4.3` 及之前的本节 |
+| ⚠️ 升级体检 / 解耦健康 两卡的**读数** | ⚠️ **未在 0.2.0 实例上校准** | 0.1.5 起客户端资源改成"名册制 + 合并 URL"，两卡是否读全未验证 —— **最可能的表现是读数偏保守，不是崩溃** |
+| 其它 | ❓ 未知 | 需自测 |
+
+## 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. 自测
+
+```bash
+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`](https://github.com/kira905/ops-handoff-design)
+（Gitee 镜像 <https://gitee.com/kira905/ops-handoff-design>）：
+
+| 组件仓 | 做什么 | 与本组件的关系 |
+|---|---|---|
+| `dsh-ecosystem-panel` | 只读生态总览面板 | **本仓** |
+| [`dsh-butler-archive`](https://github.com/kira905/dsh-butler-archive) | 会话归档管理（列表 / 预览 / 恢复 / 删除 + 可选自动归档） | 它是**本面板第 ③ 类的观察对象之一**：靠 `cordis.patch.yml` 的 insert 注册，实体缺失时本面板报 🔴 |
+| [`dsh-session-title-live`](https://github.com/kira905/dsh-session-title-live) | 会话标题跟着对话实时更新 | 同样靠 `cordis.patch.yml` 的 insert 注册（无 client 半）；「插件到底加载上了没有」由本面板第 ① 类回答 |
+| [`dsh-diagnostic-tools`](https://github.com/kira905/dsh-diagnostic-tools) | 诊断取证工具组：依赖闭包体检 + 会话图片附件对账 | 分工互补：本面板回答**「今天怎么样」**（持续、只读、三色），它回答**「具体坏在哪、怎么修」**（离线、可复跑、带修法与回滚清单）——两者都只诊断 |
+| [`dsh-task-board-local`](https://github.com/kira905/dsh-task-board-local) | 自维护任务看板（卡片 = 一次真实会话 + 人工验收闸） | 它是本面板**第 ① / ③ 类体检对象的典型**：自研 + 靠 `cordis.patch.yml` 的 insert 注册——插件装载状态与补丁健康这两类静默故障，在本面板上一眼看得到 |
+| [`dsh-firstaid`](https://github.com/kira905/dsh-firstaid) | 零依赖急救台：起不来 / 假死 / 要撤销改动 / 数据被删四类现场压成一个入口 | 应急预案：**本面板自己也可能是坏掉的那个**（面板要起不来或者数据取不到，你没法用它诊断它），那时换它出场 |
+
+> 组件之间**没有代码依赖**，也不共享运行时 —— 之所以互指，是因为它们回答的是同一类人的同一批问题
+> （长期在自有机器上跑 agent：装得下、找得到、看得见、查得清）。谁装谁不装，互不影响。
+
+## 11. 许可
+
+**AGPL-3.0-only + 商业授权**（双许可；见 `LICENSE` 全文；`package.json` 的 `license` 字段为 `AGPL-3.0-only`）。
+
+- ⚠️ **AGPL 本身不禁商用**：你可以自由使用、修改、再分发（含商用），但**通过网络向他人提供本软件的修改版时，必须按 AGPL 一并提供对应源码**；
+- 「+ 商业授权」= **双许可**：若需在**闭源**或**商业场景**中使用（AGPL 的传染条款不适用），可另行取得**商业授权** —— 本仓暂无公开联系邮箱，**请通过本仓 Issue 联系**。

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh-ecosystem-panel bundle patch: mounts the read-only ecosystem overview
+# (plugin / patch / skill health). The node half (exports ".") serves
+# GET /api/dsh-ecosystem-panel/state; the `dsh.client` declaration makes the
+# browser half (exports "./client") load in the web GUI sidebar.
+- insert:
+    - id: ecosystem-panel
+      name: '@kira905/dsh-ecosystem-panel'

package/docs/RELEASING.md

@@ -0,0 +1,68 @@
+# 发版与发布规范（RELEASING）
+
+本仓只发 **Release**（clone 手工装），**不发 npm**。
+
+## 1. 版本号怎么定（SemVer）
+
+判据是**使用者可见的行为**，不是代码改动量。
+
+| 改动类型 | 版本位 | 例子 |
+|---|---|---|
+| 六类体检的判定口径变化、接口字段增删、必需的新配置项、环境变量改名 | **major** | 把「未配置」从 🟡 改成 🟢（判定语义变了） |
+| 新增类目 / 新增可选配置项 / 新增脚本 / 新增面板元素 | **minor** | 加一类体检、加 `disabledGroups` |
+| 修 bug、文案、注释、内部重构、性能 | **patch** | boot 抓不到时的颜色修正 |
+
+配置层**新增键**永远是向后兼容的（不设就走默认），可以走 minor。
+
+## 2. 变更记录规范
+
+- 一律写进 `CHANGELOG.md`，按 `Added / Changed / Fixed / Breaking / Security` 分组（没内容的分组不写）。
+- 涉及使用者动作的（要改配置、要重命名、要重装）必须在 `Breaking` 里写清**迁移动作**。
+- 每条尽量写"为什么"，而不是"改了哪个函数"。
+
+## 3. 发布前检查单（逐条打勾）
+
+1. `node scripts/verify-source.mjs .` → `ALL CHECKS PASSED`（含语法 + 配置层断言 + 脱敏扫描）
+2. 脱敏扫描**必须带全注入变量**再跑一遍（未注入时是空判）：
+   ```
+   DSH 侧示例（发布环境自己给值，别把真实值写进仓）：
+     BUILD_MACHINE_NAMES=<主机名列表>
+     BUILD_USER_NAMES=<用户名列表>
+     BUILD_LAYOUT_ROOTS=<本机关键目录名列表>
+     BUILD_SYNC_PRODUCTS=<同步/备份产品目录名列表>
+     BUILD_INTERNAL_TERMS=<内部项目代号 / 体系名列表>   ← 形态上枚举不出，只能注入
+     BUILD_PERSONAL_TERMS=<私人称呼列表>                 ← 扫描器源码里一个字都不许有
+   ```
+   注入值为 0 时脚本会明确提示"仅通用形态规则生效"——**不要**把这种运行当成通过。
+   ⚠️ 脚本自身的规则表里**不许**出现私人称呼或内部专有名（它会进公开仓）；本脚本末尾有
+   自检段：把**注入规则**再跑一遍脚本自身，命中数必须为 0。
+3. `node scripts/test-fixture.mjs` → `FIXTURE PASSED`（含「缺数据必显式降级」断言）
+4. 在一个**隔离实例**上跑一次 `node scripts/verify-state.mjs --home <隔离数据根> --tools <工具目录>`，
+   确认六类都能出结果、降级项都带原因
+5. 与上一个版本的判定做等价性比对（同一数据根、同一清单）：**逐条 status 必须零差异**；
+   有差异就说明判定逻辑被动过，要么补进 CHANGELOG 的 `Breaking`，要么退回去查
+6. `package.json` 的 `version` 与 `CHANGELOG.md` 顶部条目一致；`license` 三处一致
+   （`LICENSE` 文件 / `package.json` / `README` §10）
+7. `README.md` 的配置表与 `lib/config.js` 里的 `ENV_PREFIX` 键**逐个对照**（加了键必须补表）
+8. `examples/` 下所有 JSON 能被 `JSON.parse`（`npm test` 里不含这条，发布前手工过一遍）
+9. 公开仓里没有 `node_modules/`、没有生成物、没有日志；`.gitignore` 覆盖这些
+10. 提交信息用中性身份（不要带本机用户名与邮箱）
+
+## 4. 发布步骤
+
+1. 打出干净的发布目录（`package.json` 的 `files` 白名单已在位：`lib/` + `cordis.patch.yml` +
+   `scripts/` + `examples/` + `docs/` + 三个文档）
+2. 建 tag（`vX.Y.Z`）并从该 tag 生成 Release，正文 = `CHANGELOG.md` 对应条目
+3. Release 附件里附上本仓目录的归档（若发布渠道支持），或明确写"clone 后按 README §3 装入"
+4. 发布后在本机/隔离实例各装一次，跑 `scripts/verify-state.mjs` 复核一次
+
+## 5. 兼容性回归纪律
+
+本插件与宿主只有**一个**耦合点：宿主 web server 的服务名（`lib/host-protocol.js`）。
+
+- 升级宿主主包后，若面板按钮不出现（插件未激活），第一件事看这个服务名是否被改名；
+  改名**不用改代码**：设 `DSH_ECOSYSTEM_PANEL_WEBSERVER_SERVICE=<新名>` 即可。
+- 其余所有外部依赖（解耦脚本 / 档位 CLI / 跨表校验器 / 适配层一致性校验器）都在**进程边界之外**，
+  宿主升级不会连带改变它们的判定；它们各自不可用时本插件只降级、不崩。
+- **纪律**：任何一次"升级宿主后判定变化"的排查结论，都要写进 `CHANGELOG.md` 的 `Changed`（口径面）
+  或本文件 §3 第 5 条（回归面），别只留在会话里。

package/examples/breaking-symbols.example.json

@@ -0,0 +1,9 @@
+{
+  "_comment": "已知断裂符号表示例：宿主主包某条线移除了哪些导出（插件若仍静态 import 就会在升级后启动崩）。本面板只把它作为**参考底表**展示，不做任何自动判定。默认表为空。",
+  "@scope/some-host-package": {
+    "removed": ["oldExportName", "anotherOldExport"],
+    "since": "x.y.z",
+    "replacement": "hostApi.doTheThing(...)",
+    "affected": ["example-plugin"]
+  }
+}

package/examples/ecosystem-panel.config.example.json

@@ -0,0 +1,28 @@
+{
+  "_comment": "dsh-ecosystem-panel 配置示例。用法：拷成自己的路径，然后设 DSH_ECOSYSTEM_PANEL_CONFIG=<该路径>；同样的键也可以直接用环境变量给（见 README 配置表）。所有键都是可选的 —— 不设就走自动探测 / 内置默认。",
+  "home": "<DSH 数据根。默认 os.homedir()/.dsh；环境变量 DSH_ECOSYSTEM_PANEL_HOME 或 DSH_HOME 同效>",
+  "profile": "web",
+  "webUrl": "http://127.0.0.1:3080",
+  "toolsDir": "<外部工具目录（本面板要复用的体检脚本所在目录）。不设时，依赖它的三类体检会显式降级为「不可判定」，不会假绿>",
+  "mainNm": "<宿主主包 node_modules 路径。默认按全局 npm 布局自动探测；探测不到即判「不可用」>",
+  "cacheFile": "<升级体检的本地缓存文件。默认 <home>/ecosystem-panel-upgrade-cache.json>",
+  "scripts": {
+    "decoupling": "<解耦检查脚本。默认 <toolsDir>/check-decoupling.mjs>",
+    "triageCli": "<升级档位判定只读 CLI。默认 <toolsDir>/upgrade-triage-cli.mjs>；不设时所有插件行的档位显示「不可用」，不猜颜色>",
+    "registryAudit": "<跨表准入校验器（可选类目）。默认 <toolsDir>/registry-audit.mjs>",
+    "hostAdapterSync": "<适配层一致性校验器（可选项）。默认 <toolsDir>/sync-host-adapter.mjs>"
+  },
+  "patchManifest": "<也可以直接内联补丁清单（数组），形状见 patch-manifest.example.json；默认空 = 该组显示「未配置」而不是 0 个补丁>",
+  "patchManifestFile": "<或者给一个 JSON 文件路径，效果相同>",
+  "upgradeRulesFile": "<升级规则表 JSON 路径，形状见 upgrade-rules.example.json>",
+  "breakingSymbolsFile": "<已知断裂符号表 JSON 路径，形状见 breaking-symbols.example.json>",
+  "labelsFile": "<包名 → 一句话简介 的 JSON 路径，形状见 labels.example.json>",
+  "disabledGroups": [],
+  "text": {
+    "title": "插件 · 技能生态状态",
+    "note": "<面板底部说明文案；不设则用内置中性文案>",
+    "tabs": {
+      "patches": "补丁健康"
+    }
+  }
+}

package/examples/labels.example.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "包名 → 一句话简介 示例：面板列表里显示的说明文字。键 = 包名（bundle / patch insert / 升级体检行都用同一张表）。默认表为空 —— 没登记的包照常参与判定，只是没有简介。",
+  "example-plugin": "一句话说明这个包是干什么的（面板行里会显示这行字）",
+  "@deepseek-ai/dsh-base": "宿主核心框架底座（随主包发行）",
+  "@deepseek-ai/dsh-web-app": "宿主 Web 界面主应用（随主包发行）"
+}

package/examples/patch-manifest.example.json

@@ -0,0 +1,53 @@
+[
+  {
+    "id": "example-client-patch",
+    "title": "示例插件：某个客户端补丁",
+    "script": "patch-example-client.mjs",
+    "checks": [
+      { "pkg": "example-plugin", "rel": "lib/client.js", "contains": ["__PATCH_MARKER__"], "notContains": ["legacy-poll"] }
+    ]
+  },
+  {
+    "id": "example-global-target",
+    "title": "宿主主包内的补丁（target=global 时在宿主主包 node_modules 里找）",
+    "script": "patch-host-package.mjs",
+    "checks": [
+      { "target": "global", "pkg": "@deepseek-ai/dsh-subprocess-local", "rel": "lib/index.js", "contains": ["windowsHide: true"] }
+    ]
+  },
+  {
+    "id": "example-dir-file",
+    "title": "随包二进制存在性（special: 目录内必须有某后缀文件）",
+    "script": "patch-put-binary.mjs",
+    "special": {
+      "kind": "dir-has-file",
+      "pkg": "example-plugin",
+      "dir": "desktop",
+      "suffix": ".dll",
+      "label": "例：随包二进制文件"
+    }
+  },
+  {
+    "id": "example-no-sidecar",
+    "title": "数据目录不许有 -wal/-shm 残留（special: no-sidecar-files）",
+    "script": "patch-journal-mode.mjs",
+    "checks": [
+      { "pkg": "example-plugin", "rel": "lib/index.js", "contains": ["journal_mode = DELETE"] }
+    ],
+    "special": {
+      "kind": "no-sidecar-files",
+      "dir": "${HOME}/data",
+      "suffix": [".db-wal", ".db-shm"],
+      "label": "数据目录无 -wal/-shm 残留（字符串里可用 ${HOME} / ${PROFILE_NM} / ${MAIN_NM} 占位符）"
+    }
+  },
+  {
+    "id": "example-retired",
+    "title": "已退役条目：带 retired 的条目不参与体检（避免长期假红）",
+    "script": "patch-old-thing.mjs",
+    "retired": "示例：目标包已 fork 为自建，原补丁不再适用",
+    "checks": [
+      { "pkg": "example-plugin", "rel": "lib/index.js", "contains": ["something"] }
+    ]
+  }
+]