dsh-my-guardian 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.1] - 2026-08-27
+
+### 变更
+
+- **npm 包名改为 `dsh-my-guardian`**：`bsfeng-dsh-guardian` → `dsh-my-guardian`，与 `dsh-my-*` 系列（dsh-my-skill-manager / dsh-my-plugin-manager / dsh-my-memory）统一，目录名 = 包名 = tag 名，避免与 npm 上他人同名包（`dsh-guardian`，lss1213）混淆。安装命令变为 `dsh plugin --profile web add dsh-my-guardian`。API 路径（`/guardian/api/*`）、状态文件路径（`$DSH_HOME/guardian/state.json`）、插件行 id（`guardian`）保持兼容。
+
+## [0.3.0] - 2026-08-26
+
+### 变更
+
+- refactor(guardian): 移除 dsh-better-sidebar 第三方依赖（#22）
+- docs+test: 全面审查修复——文档同步补全 + mermaid 测试增强
+
+## [0.2.1] - 2026-08-25
+
+### 变更
+
+- **npm 页面元数据优化**：description 改为中英双语（中文在前）；README 效果截图引用改为绝对 URL（unpkg），npm 包页面可直接显示图片。
+
+## [0.2.0] - 2026-08-25
+
+### 变更
+
+- **npm 包名改为 `bsfeng-dsh-guardian`**：npm 上 `dsh-guardian` 已被他人占用（lss1213 的插件），按用户确认改为 bsfeng 前缀。安装命令变为 `dsh plugin --profile web add link:<仓库路径>/plugins/dsh-guardian`（link 安装 key 同步）。API 路径（`/guardian/api/*`）与状态文件路径（`$DSH_HOME/guardian/state.json`）保持兼容。
+- **Server 端按 P2 模块拆分**：`lib/index.js`（636 行）拆分为 state/fence/events/mount/api 子模块；**Client 端方案 B 拆分**（src 模板 + 5 片段 + build 拼接）。
+- **README 补充真实 DSH 实例效果截图**（assets/panel-main.png + panel-error-detail.png，隔离实例实测）。
+- 行为不变（重构 + 改名）。
+
+## [0.1.0] - 2026-08-23
+
+### Added
+
+- 插件治理（dsh-guardian）首个版本：
+  - **两段式加载**：新插件写入候选区 `cordis.staged.json`（与 `cordis.patch.yml` 同目录），DSH 启动完成后由守护插件逐个热挂载，不阻塞启动。
+  - **失败隔离**：候选插件挂载失败自动记录（尝试次数 + 错误），连续失败 3 次冻结，不再自动重试。
+  - **成功转正**：挂载成功的插件自动进入守护插件的持久化清单（`$DSH_HOME/guardian/state.json`），后续每次启动自动恢复。
+  - **安全模式**：一键跳过所有候选/已转正插件的加载，快速恢复被插件搞坏的环境。
+  - **诊断面板**：dsh-better-sidebar 侧边栏页签（状态列表 / 重试 / 移除 / 错误详情 / 安全模式开关）。
+  - **事件监控**：`hmr/config-update-failed`、`loader/entry-init`、`loader/partial-dispose` 诊断事件记录。
+  - HTTP API `/guardian/api/*`（loopback 信任围栏）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bsfeng
+
+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,122 @@
+# dsh-my-guardian — 插件守护
+
+> DSH（DeepSeek Harness）插件隔离与失败兜底：**新装/刚更新的插件先进候选区，由守护插件在启动完成后逐个热挂载——成功自动转正，失败自动隔离记录，连续失败冻结，一键安全模式**，配套侧边栏诊断面板。
+
+## 为什么需要
+
+DSH 的 Cordis 插件加载是 **all-or-nothing**：启动时任何插件 `import` 失败 / `apply` 抛错 / 依赖缺失，整个 `dsh web` 都会起不来（fail-loud 退出）。装一个新插件把环境搞坏，是插件用户最常踩的坑。
+
+本插件借鉴 VS Code（Extension Host 崩溃自动重启 + 禁用问题扩展）、IntelliJ（Dynamic Plugins 运行时装卸）、systemd（失败计数超限即停）的思路，利用 DSH loader 的**运行时动态挂载 API**（失败可捕获、可回滚），把"新插件"从启动路径挪到启动之后：
+
+```
+cordis.patch.yml（核心区：只放稳定插件，守护插件自身）
+        ↓ 新插件写进
+cordis.staged.json（候选区）
+        ↓ DSH 启动完成后
+守护插件逐个热挂载
+        ├─ 成功 → 自动转正（进入持久化清单，每次启动自动恢复）
+        └─ 失败 → 自动隔离（记录次数+错误，连续 3 次冻结）
+```
+
+## 功能
+
+- **两段式加载**：新装/更新插件先进候选区，启动不阻塞、坏插件不拖垮进程。
+- **失败自动隔离**：挂载失败自动记录（尝试次数 + 错误摘要），连续失败 **3 次冻结**，需手动重试。
+- **成功自动转正**：挂载成功的插件进入持久化清单（`$DSH_HOME/guardian/state.json`），后续每次启动自动恢复挂载。
+- **安全模式**：一键跳过所有候选/已转正插件，快速恢复被插件搞坏的环境。
+- **诊断面板**：dsh-better-sidebar 侧边栏"插件守护"页签——状态列表 / 重试 / 移除 / 错误详情 / 安全模式开关 / 最近事件。
+- **运行中热挂载**：DSH 运行期间往候选区加条目，自动挂载，无需重启。
+
+## 安装
+
+> 💡 **npm 安装（普通用户推荐）**：`dsh plugin --profile web add dsh-my-guardian`——无需克隆本仓库；以下 link 方式供本仓库开发者使用。
+
+
+### 方式一：dsh plugin（推荐）
+
+```sh
+# 1) 克隆本仓库（任意目录）
+git clone https://github.com/baosfeng/my-dsh-plugins.git
+# 2) 以本地 link 方式安装（将 <仓库路径> 替换为上面的克隆目录）
+dsh plugin --profile web add link:<仓库路径>/plugins/dsh-my-guardian
+```
+
+装完**硬刷新浏览器**（Cmd/Ctrl+Shift+R）。
+
+### 方式二：手动
+
+1. 克隆本仓库后，在 `~/.dsh/profiles/web/package.json` 的 dependencies 增加 `"dsh-my-guardian": "link:<仓库路径>/plugins/dsh-my-guardian"`
+2. `cd ~/.dsh/profiles/web && pnpm install`
+3. 在 `~/.dsh/profiles/web/cordis.patch.yml` 的 insert 列表**第一行**加：
+
+```yaml
+- insert:
+    - id: guardian
+      name: 'dsh-my-guardian'
+```
+
+> ⚠️ **守护插件自身必须放在正式核心区第一行**（它自己是"看门狗"：启动时加载，随后才管理候选插件）。
+
+## 使用
+
+### 候选区文件
+
+新建 `~/.dsh/profiles/web/cordis.staged.json`（与 `cordis.patch.yml` 同目录）：
+
+```json
+[
+  { "id": "my-plugin", "name": "dsh-my-plugin", "config": { "option": 1 } }
+]
+```
+
+- `id`：唯一标识（不能与现有插件行 id 冲突）
+- `name`：插件包名（profile node_modules 中可解析）
+- `config`：可选，插件的配置
+
+写入文件后守护插件会自动挂载；挂载成功该条自动从候选文件移除（转正），失败则保留（状态记录在面板中可见）。
+
+### 面板
+
+侧边栏 → "插件守护"页签：
+
+| 状态 | 含义 | 操作 |
+|------|------|------|
+| 运行中 | 已挂载 | 移除 |
+| 待加载 | 尚未处理（安全模式等） | — |
+| 失败 ×N | 挂载失败 N 次 | 重试 / 移除 |
+| 冻结 | 连续失败 3 次 | 重试（解除冻结）/ 移除 |
+
+### 效果截图（真实 DSH 实例验证）
+
+侧边栏"插件守护"诊断面板（独立 3081 端口隔离 DSH 实例实测）：
+
+![插件守护面板：候选失败隔离 + 转正运行中 + 安全模式开关](https://unpkg.com/dsh-my-guardian/assets/panel-main.png)
+
+![失败自动隔离：错误详情可查](https://unpkg.com/dsh-my-guardian/assets/panel-error-detail.png)
+
+> 截图环境：隔离 DSH 验证实例（`/tmp/dsh-3081`，端口 3081）。候选区同时写入 `demo-plugin`（挂载成功 → 自动转正"运行中"）与 `dsh-no-such-plugin-xyz`（包不存在 → 挂载失败自动隔离 ×1，错误详情保留可查）。
+
+## 配置
+
+**无应用层配置项**（`apply(ctx)` 不接收 config 参数，设置页无可视化配置入口；插件激活即生效）。运行时状态与开关：
+
+- **状态文件**：`$DSH_HOME/guardian/state.json`（`~/.dsh/guardian/state.json`）——持久化候选/转正清单、失败次数、安全模式、事件日志。损坏自动降级为空状态，不影响启动。
+- **安全模式**：面板开关（或直接编辑 `state.json` 的 `safeMode: true`）。开启后所有候选/已转正插件不再加载；恢复环境后关闭开关即重新加载。
+
+## 诚实的边界
+
+- 本插件提供的是**加载时序与失败处置的兜底隔离**，不是进程级资源隔离（server 端插件仍在同一 Node 进程，client 端仍在同一浏览器页面）。进程级隔离需要 DSH 框架支持 worker/子进程 + RPC（演进建议见 [docs/插件治理/概述.md](../../docs/插件治理/概述.md)）。
+- **启动阶段的正式核心区（`cordis.patch.yml`）仍遵循 all-or-nothing**。请把一切新插件先放入候选区验证，稳定后再考虑放核心区。
+
+## 依赖
+
+| 依赖 | 用途 | 可选 |
+|---|---|---|
+| `cordis` | 插件运行时 | 是（宿主提供） |
+| `dsh-better-sidebar` | 侧边栏「插件守护」诊断面板（**可选增强，不参与依赖声明**：未安装时自动跳过面板注册，API / 候选区治理不受影响） | 否（可选增强） |
+| `react` | client 端组件 | 是（宿主提供） |
+| `dsh-my-notify` | 失败 / 冻结事件浏览器通知 | 是 |
+
+## 相关文档
+
+→ [插件治理概述](../../docs/插件治理/概述.md) · [需求清单](../../docs/插件治理/需求清单.md)

package/cordis.patch.yml

@@ -0,0 +1,24 @@
+# dsh-my-guardian bundle patch: inserts the guardian row into the profile
+# roster. This MUST be the FIRST row of the profile's own cordis.patch.yml
+# insert list (the guardian itself is a core row: it loads at boot, before
+# any candidate plugin it will stage later).
+#
+# Install with:
+#
+#   git clone https://github.com/baosfeng/my-dsh-plugins.git
+#   dsh plugin --profile web add link:<仓库路径>/plugins/dsh-my-guardian
+#
+# or manually: add the link dependency to the profile package.json, run
+# `pnpm install` in the profile dir, and add this insert row to the FIRST
+# position of the profile's own `cordis.patch.yml`:
+#
+#   - insert:
+#       - id: guardian
+#         name: 'dsh-my-guardian'
+#
+# After the guardian is mounted, new plugins go into the staged file
+# `cordis.staged.json` next to cordis.patch.yml (see README.md) instead of
+# straight into the boot path.
+- insert:
+    - id: guardian
+      name: 'dsh-my-guardian'

package/lib/api.js

@@ -0,0 +1,190 @@
+/**
+ * dsh-my-guardian — /guardian/api HTTP surface: deferred registration (the
+ * webServer service may mount after the guardian; poll ticks retry until it
+ * appears), trust fence, method dispatch and the panel snapshot.
+ */
+import { readStagedFile, writeStagedFile } from './state.js'
+import { isTrustedApiRequest } from './fence.js'
+
+function writeJson(response, status, value) {
+  const payload = JSON.stringify(value)
+  response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-cache' })
+  response.end(payload)
+}
+
+async function readJsonBody(request) {
+  let body = ''
+  for await (const chunk of request) {
+    body += chunk
+    if (body.length > 1_000_000) throw new Error('request body too large')
+  }
+  if (body === '') return {}
+  return JSON.parse(body)
+}
+
+/** Bind the API entry points to one guardian instance's shared state. */
+export function createApi(ctx, shared) {
+  return {
+    ensureApi: () => ensureApi(ctx, shared),
+    snapshot: () => snapshot(shared),
+  }
+}
+
+/**
+ * Register the /guardian/api routes once the webServer service appears
+ * (optional surface; CLI profiles skip it). Retried on every poll tick.
+ */
+function ensureApi(ctx, shared) {
+  if (shared.apiRegistered) return
+  const webServer = ctx.get('webServer')
+  if (webServer === undefined) return
+  const webRuntime = ctx.get('webRuntime')
+  shared.apiRegistered = true
+  try {
+    ctx.effect(() => webServer.register({
+      kind: 'prefix',
+      path: '/guardian/api',
+      handler: (request, response) => handleApiRequest(ctx, shared, webRuntime, request, response),
+    }), 'dsh-my-guardian: /guardian/api routes')
+  } catch (error) {
+    // registration failed: allow a later poll tick to retry
+    shared.apiRegistered = false
+    ctx.logger?.warn(`[dsh-my-guardian] api registration failed: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+/** Unified route handler: fence → method dispatch → 404/error fallback. */
+async function handleApiRequest(ctx, shared, webRuntime, request, response) {
+  if (!isTrustedApiRequest(request, webRuntime?.trustedHosts ?? [])) {
+    writeJson(response, 403, { ok: false, error: { code: 'forbidden', message: 'forbidden' } })
+    return
+  }
+  const url = new URL(request.url ?? '/', 'http://dsh.internal')
+  const method = url.pathname.startsWith('/guardian/api/') ? url.pathname.slice('/guardian/api/'.length) : ''
+  try {
+    await dispatchApiMethod(ctx, shared, method, request, response)
+  } catch (error) {
+    writeJson(response, 400, { ok: false, error: { message: error instanceof Error ? error.message : String(error) } })
+  }
+}
+
+/** Dispatch one API method to its handler; unknown methods get 404. */
+async function dispatchApiMethod(ctx, shared, method, request, response) {
+  if (method === 'state' && request.method === 'GET') {
+    writeJson(response, 200, { ok: true, value: shared.snapshot() })
+    return
+  }
+  if (request.method !== 'POST') {
+    writeJson(response, 404, { ok: false, error: { message: 'unknown guardian API method' } })
+    return
+  }
+  if (method === 'staged') {
+    await handleStagedPost(ctx, shared, request, response)
+    return
+  }
+  if (method === 'retry') {
+    await handleRetryPost(ctx, shared, request, response)
+    return
+  }
+  if (method === 'remove') {
+    await handleRemovePost(ctx, shared, request, response)
+    return
+  }
+  if (method === 'safemode') {
+    await handleSafemodePost(ctx, shared, request, response)
+    return
+  }
+  writeJson(response, 404, { ok: false, error: { message: 'unknown guardian API method' } })
+}
+
+/** POST /guardian/api/staged — add a candidate entry and mount it. */
+async function handleStagedPost(ctx, shared, request, response) {
+  const payload = await readJsonBody(request)
+  const id = typeof payload.id === 'string' ? payload.id : ''
+  const name = typeof payload.name === 'string' ? payload.name : ''
+  if (id === '' || name === '') {
+    writeJson(response, 400, { ok: false, error: { message: 'id and name are required' } })
+    return
+  }
+  if (shared.conflictOf(id) !== null) {
+    writeJson(response, 409, { ok: false, error: { message: `id "${id}" already in use` } })
+    return
+  }
+  const entries = await readStagedFile(shared.stagedFile)
+  if (entries.some((item) => item?.id === id)) {
+    writeJson(response, 409, { ok: false, error: { message: `"${id}" already in the staged file` } })
+    return
+  }
+  entries.push({ id, name, ...(payload.config !== undefined ? { config: payload.config } : {}) })
+  const writeError = await writeStagedFile(shared.stagedFile, entries)
+  if (writeError !== null) throw writeError
+  await shared.scanStaged()
+  writeJson(response, 200, { ok: true, value: shared.snapshot() })
+}
+
+/** POST /guardian/api/retry — manual unfreeze of a staged/promoted entry. */
+async function handleRetryPost(ctx, shared, request, response) {
+  const payload = await readJsonBody(request)
+  const id = typeof payload.id === 'string' ? payload.id : ''
+  const outcome = await shared.retryEntry(id)
+  if (outcome === null) {
+    writeJson(response, 404, { ok: false, error: { message: `no such entry "${id}"` } })
+  } else {
+    writeJson(response, 200, { ok: true, value: { outcome } })
+  }
+}
+
+/** POST /guardian/api/remove — drop an entry everywhere. */
+async function handleRemovePost(ctx, shared, request, response) {
+  const payload = await readJsonBody(request)
+  const id = typeof payload.id === 'string' ? payload.id : ''
+  await shared.removeEntry(id)
+  writeJson(response, 200, { ok: true, value: shared.snapshot() })
+}
+
+/** POST /guardian/api/safemode — toggle safe mode (R5). */
+async function handleSafemodePost(ctx, shared, request, response) {
+  const payload = await readJsonBody(request)
+  const enabled = payload.enabled === true
+  shared.state.safeMode = enabled
+  shared.logEvent('safe-mode', enabled ? 'safe mode enabled' : 'safe mode disabled')
+  if (enabled) {
+    for (const id of [...shared.mounted]) await shared.unmount(id)
+  } else {
+    shared.attempted.clear()
+    await shared.scanStaged()
+    await shared.mountPromoted()
+  }
+  shared.persistSoon()
+  writeJson(response, 200, { ok: true, value: shared.snapshot() })
+}
+
+/** Snapshot for the panel (leaf values only). */
+function snapshot(shared) {
+  const stagedList = []
+  for (const [id, record] of Object.entries(shared.state.staged)) {
+    stagedList.push({
+      id,
+      name: record.name,
+      attempts: record.attempts,
+      frozen: record.frozen,
+      lastError: record.lastError,
+      lastFailedAt: record.lastFailedAt,
+      status: shared.mounted.has(id) ? 'running' : record.frozen ? 'frozen' : record.attempts > 0 ? 'failed' : 'pending',
+    })
+  }
+  const promotedList = []
+  for (const [id, record] of Object.entries(shared.state.promoted)) {
+    promotedList.push({
+      id,
+      name: record.name,
+      attempts: record.attempts,
+      frozen: record.frozen,
+      lastError: record.lastError,
+      lastFailedAt: record.lastFailedAt,
+      promotedAt: record.promotedAt,
+      status: shared.mounted.has(id) ? 'running' : record.frozen ? 'frozen' : record.attempts > 0 ? 'failed' : 'pending',
+    })
+  }
+  return { safeMode: shared.state.safeMode, staged: stagedList, promoted: promotedList, events: shared.state.events.slice(-10) }
+}