zhiheng-zhang-Mera/dsh-health-scheduler

dsh-health-scheduler

License
Node
DSH
Plugin type

面向 DeepSeek Harness 的设备/运行时健康监控、重启压力评分、维护调度与动作决策插件 —— 它自己从不重启任何东西。

dsh-health-scheduler 观察一台 DS-Hns 机器，把它能测到的一切归结为一个 0 到 100 的
restart_pressure 数值，判断接下来应该发生什么，然后请别人去做。动作阶梯的第 1、2 级交给
worker-control 适配器；第 3、4 级是投递给独立的
dsh-restart bundle 的请求，重启执行由后者负责。

流水线只有一个方向：

providers -> normalization -> rolling windows -> trend -> pressure -> policy
-> maintenance scheduler -> action adapters (worker control | restart request)

它是什么 / 它不是什么

| 关注点 | 归属 | 本插件的角色 |
| --- | --- | --- |
| 感知设备与运行时健康 | Health Scheduler | 归它。Provider 采样、规范化并保留历史。 |
| 判断状况有多糟 | Health Scheduler | 归它。压力模型与策略引擎都在这里。 |
| 调度维护 | Health Scheduler | 归它。窗口、目标时间、推迟预算、安全点。 |
| 降低负载（THROTTLE、PAUSE_NEW_WORK） | Health Scheduler | 通过 worker-control 适配器请求。 |
| 真正执行重启 | dsh-restart | 不归它。 只发出请求并读取应答。 |
| 重启锁、限流、checkpoint、优雅关闭 | dsh-restart | 不在这里。 |
| 崩溃后拉起、崩溃循环熔断 | Supervisor | 不在这里。 |
| 任务状态、checkpoint、resume | DS-Hns Core | 不在这里。安全点查询只是一个提问，不是存储。 |
| 第二个 Mega Core | 谁都不该有 | 明确不在范围内。 |

上表推出三条承诺，而且它们是承重的：

1. 没有重启执行。 没有 taskkill、没有 reboot、没有杀进程，也没有任何可能触及操作系统
重启路径的 child_process 调用。整个代码库里唯一的 execFile 用来运行用户配置的遥测探测
命令（src/providers/sources.ts）。
2. 没有遥测就是 unknown，绝不是健康。 没有任何数据的维度得分为 null，其名义权重被重新
分配给真正有数据的维度。
3. 单点采样永远不会驱动高风险动作。 每个被打分的指标都要过持续时间门（sustain gate），
每个指标背后都有滚动窗口，而阶梯最高的两级还额外经过防抖、维护窗口门禁与安全点门禁。

安装

dsh plugin --profile   会把剩余参数转发给 profile 目录中的 pnpm，然后
对该 profile 的 bundle 列表做一次对账，因此一个声明了 dsh.bundle 的已安装包会自动加入层栈。

从本仓库的本地检出安装：

Windows PowerShell，在检出目录中执行
dsh plugin --profile web add \dsh-health-scheduler

任意平台，在检出目录中执行（裸 "." 会锚定到你的当前目录）
cd dsh-health-scheduler
dsh plugin --profile web add .

从包名或 tarball 安装：

dsh plugin --profile web add dsh-health-scheduler
dsh plugin --profile web add ./dsh-health-scheduler-0.1.0.tgz

bundle 贡献了什么

cordis.patch.yml 插入一行 id: health-scheduler，它的 config 块以带注释的形式重述了整份
balanced 预设。该层在每个更早的 bundle 之后、你自己的 profile cordis.patch.yml 之前应用，
因此你的覆盖会生效。

patch 会替换目标行的整个 config，它不是深合并。 如果你在 profile patch 里覆盖
providerOptions，请复制你想改的整个嵌套对象，而不是只写那一个叶子。插件自己的配置解析是
在所选预设之上的深合并，所以你直接传给插件的文档行为符合直觉 —— 是 profile patch 这一层在做
替换。

plugin/manifest.json 以机器可读的形式描述同一份契约：id、kind、入口模块、安装命令与 patch
路径、必需与可选服务、设置命名空间、三个工具名、六种事件名、本插件亲自应用的动作与仅作为请求发出
的动作，以及在 dsh-restart 或 worker control 缺席时哪些能力会降级。

启动前先验证

--dump-config 会在不启动的情况下打印组合后的 profile 树。用它确认插件行存在、且配置就是你写的
那份：

dsh --profile web --dump-config

--dump-default-config 打印的是不含用户层、也不含任何 --patch 覆盖的同一棵树，是查看本
插件贡献了什么最快的方式。

启动

dsh --profile web

dsh web 是 --profile web 的硬编码别名。

git 安装的注意事项

由 git 托管的插件在安装时通过 prepare 脚本构建，而 pnpm 会阻止该构建，直到你明确允许。当
dsh plugin ... add git+https://… 失败时，CLI 会打印 pnpm 要求的确切键名；把它加到
/pnpm-workspace.yaml 的 allowBuilds 下，然后重跑同一条命令。

本插件带有 "prepack": "npm run build"，且 lib/ 被 gitignore，因此：

- 从 npm 或 tarball 安装不需要构建许可。 发布的 tarball 里包含由 prepack 钩子构建出的
lib/。
- 从 git URL 安装总是需要那条 allowBuilds 记录，因为检出里没有 lib/，必须先由
prepack 跑 tsc 才能生成它。
- 从本地路径安装在你已经跑过 npm run build 时等同于 tarball，否则需要先构建一次。

快速开始

插件零配置即可工作 —— balanced 预设就是默认值，其中每个叶子都是默认值而非铁律。最小可用的
配置文档只有一行：

// profile package.json -> dsh.profile，或插件的设置命名空间
{ "preset": "balanced" }

一份更接近真实使用的首版配置会打开定时维护窗口，并把硬件 provider 指向一个温度辅助命令：

$DSH_HOME/profiles/web/cordis.patch.yml
- id: health-scheduler
name: dsh-health-scheduler
config:
preset: balanced
maintenance:
enabled: true
targetTime: '04:00'
windowStart: '03:30'
windowEnd: '05:00'
maxDeferMs: 3600000
urgentOverridePressure: 92
safePointRequired: true
providerOptions:
hardware:
helperCommand: ['powershell', '-NoProfile', '-File', 'C:\\dsh\\gpu-temp.ps1']
helperTimeoutMs: 5000
statsFile:
paths: ['C:\\dsh\\telemetry\\metrics.json']
staleAfterMs: 120000

启动后插件会打印

health-scheduler: monitoring started (7 providers, interval 15000 ms, preset balanced)

按需请求时，只读健康报告的开头是这样：

Restart Pressure: 21 / 100
State: THROTTLED
Primary Cause: gpu_usage=95.00 pp scores 89/100, held 1260s
Telemetry coverage: 60%
Unknown dimensions: runtime, worker, computer_use_ui (not scored as healthy)
Maintenance: next window 03:30-05:00
Safe point: no safe-point source registered; readiness unknown
Capabilities: restart=unavailable, worker-control=unavailable

其中每个数字都能追溯到某个指标。输出里不存在任何不由测量支撑的句子 —— “AI 认为应该重启”不是
一个可能的 reason code。

工作原理

1. Provider 采样；别的地方不接触外部世界

所有健康数据都通过 HealthProvider 进入。压力模型与策略引擎被禁止直接触达 NVML、
LibreHardwareMonitor、HWiNFO、Windows API、worker 内部或 Electron 内部。测不到某个指标的
provider 会省略该键；缺席是表达“未知”的唯一方式，而且它刻意不写成 0。

2. 规范化：拒绝、钳制、排序

normalizeSample 把原始样本转换为规范词表。不是有限数字、或越过该指标物理硬边界的读数会被丢弃
并记录为 violation。以百分比形式送来的 ratio（1.0  throttle, 54 -> normal, 56 -> throttle。 |
| 防抖 | 连续 2 次评估 | 单次评估就升级到高风险等级。 |
| 驻留 | 120 秒 | 低于重启等级的任何切换快于驻留时间。 |
| minRepeatActionMs | 10 分钟 | 早于允许间隔重复下发同一动作。 |
| 三个冷却 | 5 / 30 / 60 分钟 | 决策风暴，包括由失败适配器引发的风暴。 |

冷却从适配器真正被调用时开始计时 —— 包括它拒绝或抛异常的情况。
tests/scenarios.test.js 让一台永久危重的机器以 15 秒一拍跑满 30 分钟，且重启适配器一直抛
异常，断言最多只有 3 次尝试抵达适配器，而不是每拍一次。

8. 先策略，后适配器

策略引擎每拍最多产出一个动作，并且从不触碰进程。第 1、2 级交给 WorkerControlAdapter；第 3、
4 级变成一个交给 RestartAdapter 的 RestartRequest。每个被应用的动作恰好产生一条审计记录，
包含压力、coverage、具名 driver、reason code 以及适配器的应答。

面向模型的工具

当 profile 提供工具运行时时会注册三个工具。三者都是只读的：它们都不会行使任何能力。

health_status

报告 DS-Hns 运行时的当前健康状况。参数：section
（full | pressure | maintenance | providers，可选，默认 full）。

health_status({ "section": "pressure" })

Restart Pressure: 21 / 100
State: THROTTLED
Coverage: 60%
Primary cause: gpu_usage=95.00 pp scores 89/100, held 1260s
[0.3] gpu_usage_critical: gpu_usage=95.00 pp scores 89/100, held 1260s
[0.2] cpu_usage_critical: cpu_usage=90.00 pp scores 71/100, held 1260s
[0.2] gpu_temp_c_critical: gpu_temp_c=88.00 °C scores 71/100, held 1260s

full 是整份报告：压力、状态、主因、coverage、未知维度、维护摘要、安全点摘要、能力状态、
逐维度表格、driver、恶化趋势、provider 状态、内存行、最近五条决策以及本拍的 warnings。
maintenance 与 providers 是同一份快照的单主题视图。

health_history

返回某个规范指标的滚动窗口统计。

| 参数 | 类型 | 必填 | 含义 |
| --- | --- | --- | --- |
| metric | string | 是 | 规范指标名，例如 gpu_temp_c。 |
| window_minutes | number | 否 | 只输出不大于该分钟数的窗口。 |

未知指标名会抛错，错误信息里带完整规范名称列表。

{
"metric": "process_rss_bytes",
"windows": [
{
"window_minutes": 30,
"count": 120,
"mean": 2540000000,
"p95": 2870000000,
"max": 2900000000,
"latest": 2880000000,
"slope_per_hour": 1200000000,
"r_squared": 0.9821,
"consecutive_ms": 0,
"span_ms": 1785000
}
]
}

health_policy

解释决策策略。参数：action（explain | config | decisions，可选，默认 explain）。

health_policy({ "action": "explain" })

Action ladder (enter/exit pressure):
1 THROTTLE              enter >= 55, exit = 70, exit = 80, exit = 95, exit  lib/
npm test                   # npm run build && node --test tests/.test.js
npm run test:only          # node --test tests/.test.js，使用现有 lib/
npm run typecheck          # tsc -p tsconfig.json --noEmit
npm run presets            # 从 lib/ 重新生成 presets/.json
npm run verify:artifacts   # 校验构建产物与预设彼此一致

值得了解的 TypeScript 设置：strict、noUncheckedIndexedAccess、noUnusedLocals、
noUnusedParameters、verbatimModuleSyntax、target: ES2023、module: NodeNext。引擎
（src/core、src/types、src/providers、src/adapters、src/audit）不依赖 harness；
只有 src/dsh/ 知道 Cordis，而且是通过 src/dsh/context.ts 里那些窄结构接口知道的。这正是整个
引擎无需运行时即可测试的原因。

测试套件共 152 个测试、分布在 8 个文件中，按提交状态全部通过：

node --test tests/.test.js
tests 152 / suites 27 / pass 152 / fail 0

node scripts/generate-presets.mjs --check
ok   presets/balanced.json matches PRESETS.balanced
ok   presets/conservative.json matches PRESETS.conservative
ok   presets/aggressive.json matches PRESETS.aggressive
ok   presets/schema.json matches the configuration schema
ok   4 generated files are up to date

常见问题

它会重启我的机器吗？
不会，它做不到。本插件里完全没有重启执行 —— 没有 taskkill、没有 reboot、没有杀进程。第 3、
4 级只产出一个 RestartRequest 对象，交给 context 上的任意 RestartAdapter。没有安装
dsh-restart 时该适配器报告 unavailable，请求被降级为 PAUSE_NEW_WORK。

温度传感器缺失会怎样？
该指标直接不出现在样本里。cpu_temp_c 与 gpu_temp_c 从不原生测量，所以在默认安装上除非你配置
辅助命令或 stats 文件，它们永远缺席。此时热维度只对它有数据的东西打分（cpu_usage，以及辅助
程序提供的任何值）；如果一个都没有，它就是 unknown，coverage 下降，报告把它列在
Unknown dimensions: … (not scored as healthy) 之下。它永远不会被打成 0。

为什么我的压力是 0，状态却是 DEGRADED？
因为它们回答的是不同的问题。压力高于节流退出带时 restart_pressure 可以是 0 —— 状态机把
这种情形叫 DEGRADED 而不是 HEALTHY。反过来，pressure: null（什么都测不到）同样刻意给出
DEGRADED：未知不是健康。决策记录上的理由列表会指出是哪个门禁拦住了它。

怎么把它关掉？
三种方式，越来越彻底。在插件配置里设 enabled: false —— 它仍然加载、仍然注册命名空间与工具，
但不采集、不启动循环。或者用 disabledProviders: ["hardware"] 关掉个别 provider。或者用
dsh plugin --profile web remove dsh-health-scheduler 从 profile 里彻底移除，这也会把它从
profile 的 bundle 列表里去掉。卸载不影响 DS-Hns。

它占用多少磁盘？
几乎不占，而且是有界的。决策日志是 /health-scheduler（或 storage.directory）下的
一个 decisions.jsonl，超过 storage.maxLogBytes 时按重命名轮转 —— 默认 4 MiB，所以最坏情况
是连同旁边一个 .bak 约 8 MiB。别的什么都不写：滚动历史在内存里，受 windows.rawMs 与
windows.aggregateRetentionMs 约束。storage.enabled: false 会让插件变成纯内存模式。

怎么加自定义传感器？
写进 stats 文件，或暴露为命令探测。两者都使用规范指标词表，非规范键会被报告而不是被静默丢弃。
如果你的传感器确实是新的，就必须扩展规范注册表 —— provider 只能上报存在于
src/types/metrics.ts 中的名字。见
docs/configuration.zh.md。

它会和 dsh-restart 打架吗？
打不起来，因为它无法行动。它投递一个带调用方自选 requestId 的 RestartRequest，并读回
accepted / rejected 以及重启侧的生命周期状态。锁、限流、checkpoint token 与崩溃循环熔断都
属于 dsh-restart；本插件的冷却只约束它自己的请求，而且被拒绝会启动冷却而不是立刻重试。
卸载 dsh-restart 后监控与节流仍然完整可用。

需要管理员权限吗？
不需要。它读取 os.cpus()、os.totalmem()、os.freemem()、process.memoryUsage()、
process.uptime() 以及（可用时的）process.getActiveResourcesInfo()，读取并 stat 文件，
以及可选地运行你配置的辅助命令。你把它指向需要特权的辅助程序时，它继承的是你的权限 —— 那是
你的选择，而不是插件的要求；插件自己从不提权。

为什么 coverage 只有 60%？
因为六个维度里只有四个有遥测。coverage 是被真实测量支撑的名义权重占比。没有集成时，除 uptime
以外的 runtime 指标、所有 worker 指标、所有 computer_use_ui 指标都没有来源，因此在
hardware 与 memory 在上报时 coverage 就在 0.6 附近。这正是功能在正常工作：60% coverage 的压力
被如实标注，而不是假装成满置信读数。

它会让我的机器变慢吗？
默认每 15 秒一拍，而且每拍都很便宜：几次 os 调用、最多每 2 秒一次的 stats 文件读取，以及每个
已配置探测最多一次辅助命令。滚动内存由构造方式保证有界，所以不会有任何东西随 uptime 增长。它能
做的最重的事情是你配置的辅助命令，它在你设定的超时下运行（helperTimeoutMs，默认 5 秒）。

许可证

MIT © 2026 dsh-health-scheduler contributors。见 LICENSE。

这是一个社区插件。它与 DeepSeek 无隶属关系，也未获得 DeepSeek 的赞助或背书。
“DeepSeek Harness”与“DS-Hns”仅用于描述它所集成的对象。

安装插件意味着以你的权限运行第三方代码 —— 本插件也不例外。在把它装进一个能触达生产凭据或
无人值守机器的 profile 之前，请先阅读 SECURITY.md。