dsh-status-plugin

中文 | English

DeepSeek Harness（dsh）的状态插件，一个包内含两个平面：

• Host 平面 — 以 JSON 形式暴露运行中 harness 的运行时健康状态：进程、监听器、API Key 是否存在、内存、磁盘、运行时长，以及实时的插件清单。

• Client 平面 — Web UI（会话右上角）的头部徽标：显示运行时长，点击展开详情面板；当 host 上报过载、内存压力或磁盘告警时弹出提示；另有「状态」设置页可实时调整告警阈值。

• 包名：dsh-status-plugin

• 运行时：host（ESM）+ 浏览器 bundle（CJS factory，按 dsh client-modules 的 __ModuleLoader__ 契约包装），使用 tsc + esbuild 构建到 lib/。

• 语言：TypeScript。

安装

dsh plugin --profile web add dsh-status-plugin

CLI 会自动协调 dsh.profile.bundles：因为 manifest 声明了 dsh.bundle.patch，该包会加入 profile 的 bundle 层栈。停止正在运行的进程并重启 profile 以加载：

dsh web   # 或：dsh --profile <name>

无需启动即可验证插件已加入组合树：

dsh --profile web --dump-config

Client manifest（package.json → dsh.client）声明了浏览器入口；profile 的 client-modules 扫描器会自动拾取并注入 dsh-status-plugin/client.js 到 Web 应用——无需任何 bundle 或 overlay 配置。

用法

插件在 profile 的 web 服务器上注册三个精确路由：

GET /api/status          # 按需获取 JSON 快照
GET /api/status/metrics  # Prometheus 文本暴露格式
GET /api/status/events   # Server-Sent Events 流

GET /api/status

响应示例：

{
  "ok": true,
  "timestamp": "2026-08-14T03:50:00.000Z",
  "host": {
    "hostname": "host",
    "platform": "linux",
    "arch": "x64",
    "nodeVersion": "v22.23.2",
    "pid": 23185,
    "cwd": "/root/.dsh",
    "uptimeSeconds": 3600,
    "loadAvg": [0.1, 0.1, 0.1],
    "cpuPercent": 12.4,
    "eventLoopDelayMs": 2.3,
    "memory": { "rss": 123456, "heapTotal": 654321, "heapUsed": 432100, "external": 12345 },
    "systemMemory": { "total": 17179869184, "free": 4294967296, "used": 12884901888 },
    "disk": { "mount": "/", "total": 107374182400, "free": 64424509440, "avail": 60129542144, "used": 42949672960, "percent": 0.416 },
    "lanAddresses": ["192.168.5.227"]
  },
  "webServer": {
    "host": "0.0.0.0",
    "port": 3080,
    "url": "http://localhost:3080"
  },
  "apiKey": {
    "configured": true,
    "source": "env"
  },
  "plugins": {
    "entries": [
      { "entryId": "llm", "moduleName": "@deepseek-ai/dsh-llm", "enabled": true, "fiberPhase": "active" }
    ]
  }
}

字段说明

字段	来源
host.*	process + node:os（pid、运行时长、进程内存、LAN IPv4 地址）；cpuPercent 是基于 os.cpus() 增量采样得到的 CPU 利用率，全平台可用；eventLoopDelayMs 是自上次采样以来的事件循环平均延迟（perf_hooks）；loadAvg 是 Unix 负载均值——在 Windows 上恒为 [0, 0, 0]；systemMemory.* 是机器级内存（os.totalmem() − os.freemem()）；disk 是工作盘——对 process.cwd() 执行 fs.statfsSync，失败时回退到系统临时目录，即 harness 实际运行所在文件系统（只有所有探测都失败才为 null）；disk.percent 采用 df 惯例 used / (used + avail)，保留块（ext4 为 root 预留的 5%）不会高估使用率
webServer.*	ctx.webServer（绑定 host 与实际监听端口）
apiKey	DEEPSEEK_API_KEY 在 process.env，否则在 cwd/.env 或 $DSH_HOME/.env 中检查（与 dsh CLI 实际加载的层完全一致——~/.env 刻意不检查）——只报告是否存在，绝不报告值；空赋值（如 DEEPSEEK_API_KEY=""）不算已配置
plugins.entries	ctx.pluginInventory.list()（Cordis Loader 条目的实时状态）

API Key 检查只报告 key 是否已配置及其来源；值本身永远不会离开进程。检查结果缓存 60 秒，快照不会反复在事件循环上读 .env 文件。

隐私说明（0.2.1+）： host.lanAddresses 默认为 []。需要 LAN IPv4 地址时请设置 exposeLanAddresses: true。

GET /api/status/events（SSE）

host 向已打开的浏览器流推送——由服务器决定页面何时需要新状态，空闲页面零请求：

• snapshot — 完整状态快照，连接时立即发送，之后每 heartbeatMs（默认 30 秒）一次。每个快照卡片分解为 host.* 中的 cpuPercent、eventLoopDelayMs、loadAvg、systemMemory 与进程内存字段，供告警驱动的 UI 使用。
• alert — 指标进入或离开告警区间时发送。进入需要 value > threshold；激活中的告警只有在值回落到 threshold × (1 − hysteresis) 以下才解除，因此徘徊在阈值附近的值不会反复翻转。告警原因：cpu、memory（Linux 内存压力改用 /proc/meminfo 的 MemAvailable，不再用裸 freemem()——page cache 不再造成误报）、eventLoop（事件循环平均延迟，毫秒）、disk（工作盘使用率，df 口径）。每次状态转换都发送，并在连接时重新同步，因此中途打开的页面也能得知正在进行的告警：

event: snapshot
data: {"ok":true,"timestamp":"...","host":{...},"plugins":{...}}

event: alert
data: {"active":true,"reason":"cpu","value":0.87,"threshold":0.8}

默认阈值（可通过 profile 的 cordis.yml 中插件配置覆盖）：

配置	默认值	含义
cpuWarning	0.8	CPU 利用率超过该值时触发 CPU 过载告警
memoryWarning	0.85	系统内存压力超过该值时触发内存告警
diskWarning	0.9	工作盘使用率超过该值时触发磁盘告警
eventLoopWarning	100	事件循环平均延迟（毫秒）超过该值时触发阻塞告警
hysteresis	0.1	恢复余量：告警只在值低于 threshold × (1 − hysteresis) 时解除
heartbeatMs	30000	快照推送间隔
checkIntervalMs	5000	告警监控采样间隔
authToken	''	三个路由都要求的共享密钥；留空禁用鉴权。见鉴权
allowedOrigins	[]	允许调用路由的精确 Origin 值；留空禁用 Origin 校验。见鉴权
exposeLanAddresses	false	快照中包含 host.lanAddresses（默认关闭以保护隐私）
rateLimitPerMinute	300	每个客户端 IP 在所有路由上的每分钟请求上限；0 禁用
maxSubscribers	32	SSE 订阅者上限；超限的新连接收到错误响应
maxBufferedBytes	65536	每个订阅者的写缓冲高水位；超过的慢消费者会被丢弃
webhookUrl	''	每次告警转换时通知的 webhook 地址；留空禁用。见Webhook 通知
webhookTimeoutMs	5000	webhook 请求超时（毫秒）

运行时设置（设置页）

自 0.4.0 起插件注册了一个 dsh-status 设置命名空间（@deepseek-ai/dsh-settings）。当 profile 挂载了设置服务时，Web UI 设置面板会出现一个「状态」设置页（贡献到 settings.section 槽位），以下字段可实时调整——写入后无需重启 harness 立即生效：

字段	默认	生效时机
cpuWarning、memoryWarning、diskWarning、eventLoopWarning	同上	实时——告警监控器在下一个采样周期按新阈值判定
hysteresis	0.1	实时
heartbeatMs、checkIntervalMs	同上	实时——定时器重新挂载
exposeLanAddresses	false	实时——下一个快照即生效
rateLimitPerMinute	300	实时——限流器容量被替换

安全边界。 设置页刻意只编辑这个子集。authToken（密钥）、allowedOrigins、webhookUrl/webhookTimeoutMs（通知端点）、maxSubscribers/maxBufferedBytes（hub 容量）都留在 cordis.yml——密钥与端点绝不暴露到浏览器表面。没有设置服务时，插件完全按 entry 配置运行，与之前一致。

设置传输仅限 loopback（与 SSE 鉴权约束同类）：远程机器上的浏览器无法读写该命名空间，页面会显示不可用状态。每个字段旁的「重置」按钮可清除用户覆盖，使该字段重新继承 cordis.yml 的 entry 值。

鉴权

设置 authToken 后，三个路由都要求携带该令牌，可通过任一通道：

• GET /api/status 与 GET /api/status/metrics — Authorization: Bearer <token> 请求头，或 ?token=<token>。
• GET /api/status/events — ?token=<token> 查询参数，或在客户端使用 fetch 流订阅器时携带 Authorization 请求头（见下文）；原生 EventSource 无法设置自定义请求头。

被拒绝的请求返回 401 与 { "ok": false, "error": "unauthorized" }。比较是恒时间的（crypto.timingSafeEqual），错误的令牌不会泄漏长度。由于查询参数可能出现在日志和历史记录中，请优先使用请求头鉴权，SSE 流请尽量放在仅 loopback 的 web 服务器上。

Origin 策略。 设置 allowedOrigins 为精确 Origin 列表（如 ["https://dsh.example.com"]），可在 web 服务器超出 loopback 可达时拒绝跨域浏览器读取。不带 Origin 头的请求（curl、服务器、同源导航）始终放行。空列表（默认）接受所有 Origin。

速率限制。 每个路由按客户端 IP 限制为 rateLimitPerMinute 次请求（默认 300，0 禁用）。超限返回 429 与 { "ok": false, "error": "rate limited" }。

支持请求头鉴权的 SSE 客户端。 内置徽标没有接收 host 令牌的通道，因此启用 authToken 会使徽标的状态视图不可用。自定义 UI 可调用导出的 createSseClient(url, headers, onEvent, onConnectionChange) 订阅——传入 { Authorization: 'Bearer <token>' } 即可获得带请求头鉴权的 SSE，并自带指数退避自动重连。

浏览器侧通过基于 fetch 的 SSE 读取器订阅（指数退避自动重连，尊重服务器下发的 retry: 帧），并渲染：

• 会话头部的一个紧凑徽标（状态圆点 + 运行时长，点击展开）；
• 详情面板（0.5.0 起改为 Tab 分区）：概览页签——告警横幅、四个关键资源卡片（CPU/内存/磁盘/事件循环延迟）与最近 60 个快照的 CPU/内存趋势图；详情页签——完整的进程/资源/磁盘/服务/插件分区；底部显示最近更新时间；
• 会话视图环中的整页「状态」页签（0.5.1 起）：整个会话主区切换为监控视图——更大的统计卡片、宽幅趋势图与全部分区。通过会话页签条切换（面板内有一行提示指引）；徽标无法编程式切换视图——shell 将 per-session 的 chat store 留在内部，视图切换由用户点击页签完成；
• 每次告警转换弹出 toast（6 秒自动消失），告警激活期间徽标脉冲闪烁；
• 流断开且 90 秒未收到快照时圆点变灰——监控组件在失联时必须显示"未知"，而不是继续显示"健康"。首个连接尚未建立时圆点同样是灰色，徽标在有数据之前绝不宣称健康。

Webhook 通知

设置 webhookUrl 可在每次告警转换（进入与恢复）时收到 JSON POST。载荷：

{
  "event": "alert",
  "active": true,
  "reason": "cpu",
  "value": 0.87,
  "threshold": 0.8,
  "timestamp": "2026-08-14T03:50:00.000Z",
  "hostname": "host",
  "pid": 23185
}

投递是 fire-and-forget：失败或超时的请求只记日志，绝不干扰告警管线，因此即使通知通道不可用，harness 也会继续监控。可对接任意支持 webhook 的服务（Slack、钉钉、企业微信、ntfy 等）。

Prometheus 指标

GET /api/status/metrics 以 Prometheus 文本暴露格式（text/plain; version=0.0.4）提供快照，供现有监控栈抓取：

dsh_status_up 1
dsh_status_uptime_seconds 3600
dsh_status_cpu_percent 12.4
dsh_status_event_loop_delay_ms 2.3
dsh_status_loadavg_1 0.5
dsh_status_process_rss_bytes 123456
dsh_status_system_memory_used_bytes 12884901888
dsh_status_disk_total_bytes{mount="/"} 107374182400
dsh_status_disk_free_bytes{mount="/"} 64424509440
dsh_status_disk_avail_bytes{mount="/"} 60129542144
dsh_status_disk_used_bytes{mount="/"} 42949672960
dsh_status_disk_percent{mount="/"} 0.416
dsh_status_api_key_configured 1
dsh_status_plugins_total 42
dsh_status_plugins_active 40

该端点与其他路由一样受 authToken、allowedOrigins 与 rateLimitPerMinute 约束。

失败行为

• 处理器内收集错误返回 500，带 { "ok": false, "error": "internal error" } ——已脱敏，不泄漏内部信息或堆栈；真实错误信息进入 host 日志。
• pluginInventory 可选：服务缺失时 plugins.entries 返回 [] 而不是报错。
• 响应处理器与两个周期定时器（heartbeat 与告警采样）都做了异常隔离：收集抛错只记日志，绝不作为 uncaughtException 传播出去导致被监控的 harness 崩溃。
• 响应携带 cache-control: no-store（运行时数据不可缓存）；SSE 流使用 text/event-stream 并带 x-accel-buffering: no。
• SSE 流有界：最多 maxSubscribers 个并发订阅者；写缓冲超过 maxBufferedBytes（或 socket 写入停滞）的订阅者会被丢弃，慢消费者无法拖死进程。插件卸载会结束所有打开的流。

环境要求

• 带 web bundle（@deepseek-ai/dsh-web-app）的 dsh profile——提供 ctx.webServer 和 ctx.pluginInventory。
• Node ^22.19 || >=24。
• 浏览器入口渲染在会话头部（conversation.session.header.utilities 槽位）；空白/首页不显示。
• 设置页（0.4.0+）需要 web 组合里包含设置面（@deepseek-ai/dsh-client-ui-settings 与设置 shell）——标准 bundle 自带。缺省时徽标与面板照常工作，只是没有设置页。
• 面板中的负载均值行是 Unix 概念：Windows 上恒为 0.00。CPU 利用率与内存指标全平台可用。

开发

pnpm install
pnpm run build          # host tsc + client 类型检查 + esbuild bundle
pnpm test               # vitest 单元测试
pnpm run lint           # biome lint（不自动改格式）
npm pack --dry-run      # 验证 tarball 内容（prepack 会自动执行构建）
node scripts/check-pack.mjs  # 验证 tarball 包含 lib/ 引用的每个模块

发布

本包是一个 dsh bundle：npm tarball 携带 cordis.patch.yml，manifest 的 dsh.bundle.patch 指向它，因此把包安装到任意 dsh profile 即自动挂载插件层。为便于在 dsh plugin topic 中被发现，请给仓库打 dsh-plugin 标签。

License

MIT