前言¶
在 DSH 里跑智能体或工作流时，模型往往只能看到对话上下文，很难系统性地回答「现在算不算健康」。常见做法是临时 cat 某个状态文件、或让模型自己拼凑 JSON，但读不到和读到了却判错是两回事：前者应明确为「无法判断」，后者需要可重复的判定规则。
下面介绍维护者 laa1991 在 GitHub 仓库 laa1991/dsh-health 发布的 dsh-health-readout（社区目录分类：工作流）。它是一个只读的 DSH 插件：你在配置里声明「从哪里读、什么算健康、异常对应什么结论」，插件组合已有读数（本地文件、JSON 字段、日志尾部、HTTP JSON 等），返回一条总判决及每条读数的明细。它不写入、不持久化状态、也不充当新的真相来源。
这是什么¶
dsh-health-readout（npm 包名 dsh-health-readout，当前版本 0.1.0，MIT 许可证）面向 DeepSeek Harness 用户：把分散的健康信号收成一次工具调用结果，供模型或编排逻辑使用。插件通过 Cordis patch 暴露工具 health_readout，无浏览器端、无设置界面；结论以工具返回值形式进入会话。
三条内置规则¶
README 强调这三条由类型与测试强制，而非约定俗成：
- 「无法得知」绝不能当成正常。 读不到的来源产出
unknown，不会变成ok、0或false；unknown会单独展示并影响总判决。 - 每条判定必须可被证伪。
selftest: true时会对每条声明的 criterion 喂反例；若某条 criterion 始终为绿，会报告为不可证伪的「装饰项」。 - 每条 reading 必须写 blind spot。
blind为必填，说明该读数看不清什么，避免误读为全覆盖。
核心能力¶
声明式 spec¶
在数据目录下的 readings.json（默认可从仓库 examples/readings.example.json 复制后修改）中定义 readings 数组。每条 reading 包含 id、title、source、healthy，以及必填的 blind。
示例结构（与 README 一致）：
{
"readings": [{
"id": "queue-depth",
"title": "Queue depth is under the ceiling",
"source": { "kind": "json-field", "path": "status.json", "field": "queueDepth" },
"healthy": { "op": "lt", "value": 8, "bad": "degraded" },
"blind": "A single sample: a queue that drains and refills between samples looks identical to a quiet one."
}]
}
数据源种类（source kind）¶
| kind | 含义 | 必填字段 |
|---|---|---|
file-age-seconds |
文件距上次写入的秒数 | path |
file-size |
字节数 | path |
file-exists |
路径是否存在（false 表示已知不存在） |
path |
json-field |
JSON 文件内点分路径字段 | path, field |
jsonl-last-field |
JSONL 最后一条可解析行的点分字段（尾部读取） | path, field，可选 maxBytes |
text-count |
文件尾部 maxBytes 内正则匹配次数 |
path, pattern，可选 maxBytes, flags |
dir-count |
目录下文件数，可按后缀过滤 | path，可选 suffix |
http-json-field |
HTTP JSON 端点内的点分字段（带超时） | url, field，可选 timeoutMs |
spec 内相对路径相对于 dataDir 解析；支持 ~ 与 ${dataDir} 展开。
判定运算符与状态¶
healthy.op 支持：lt、lte、gt、gte、eq、neq、between、matches、exists、absent。
不满足 healthy 条件时，healthy.bad 指定该条读数的状态（默认 degraded）。严重度序列为：ok < notice < unknown < degraded < broken；最差的 reading 决定总判决。unknown 故意高于 notice，避免在看不见的部分时仍给出自信的 ok。
工具 health_readout¶
只读调用，可选参数：
only：逗号分隔的 reading id，只评估子集。selftest：为 true 时额外验证每条 criterion 能否变红。
输出列出每条读数的值、判决、原因与 blind spot；读不到的项单独列出（README 原话："Could not read" is not "fine".）。
安装与配置¶
安装¶
配置项解析顺序：插件行内 config: → 环境变量 → 内置默认值。
官方安装方式（README Install 节）：
dsh plugin --profile <name> add dsh-health-readout # npm
dsh plugin --profile <name> add ./dsh-health-readout-0.1.0.tgz
dsh plugin --profile <name> add <git-url> # prebuilt: no build step, no postinstall
包内即为可运行文件，无 build、无 prepare、无运行时依赖；从 git URL 安装时不需要用户授予构建权限。运行环境要求 Node.js >= 18.0.0。
配置项¶
| 含义 | config key | 环境变量 | 默认值 |
|---|---|---|---|
| readings 所在目录 | dataDir |
DSH_HEALTH_READOUT_DATA_DIR |
~/.dsh-health-readout |
| 声明文件 | specFile |
DSH_HEALTH_READOUT_SPEC |
dataDir 下的 readings.json |
| 只评估部分 id | only |
DSH_HEALTH_READOUT_ONLY |
全部 |
注意： dataDir 刻意不是 DSH 平台目录。DSH 升级可能重建自身目录；用户声明的 readings 应放在你完全控制的 path 上，避免被升级清掉。
典型用法¶
- 选定
dataDir（默认可用~/.dsh-health-readout，或通过 config /DSH_HEALTH_READOUT_DATA_DIR指定）。 - 将仓库中
examples/readings.example.json复制为<dataDir>/readings.json，按你的监控对象编辑readings。 - 在 profile 中安装插件并填写上述 config（如需）。
- 在 DSH 会话中调用工具
health_readout；需要抽检 criterion 时传入selftest: true；临时只看几条时传only。
维护者提供的测试命令（无额外测试框架）：
node --test test/criteria.test.mjs test/sources.test.mjs test/spec.test.mjs test/readout.test.mjs
README 写明套件自报用例数（撰写时为 46）；若与文档数字不一致，以套件输出为准。
适用场景与限制¶
适合： 已有状态文件、JSON 快照、日志尾部或只读 HTTP 指标，希望 agent 在一次工具调用里得到统一「ok / notice / unknown / degraded / broken」结论，且不想在插件里再写查询或写库。
不适合或需知：
- 不做跨行聚合：例如「JSONL 里还有多少条未关闭」若需折叠多行，应在产生快照的上游完成，spec 只读已有聚合值。
- 无历史：每次 reading 是当前单点采样；趋势需外部 recorder（写入，超出只读范围）。
- 无
changed-within类算子：与历史比较需要状态。 unknown会拉高判决：缺文件即影响总结论，这是刻意设计。- 信任模型： spec 可读取 dsh 进程能读到的任意路径；谁写 spec，谁对路径负责。
- 权限： 插件以当前 dsh 进程权限运行；安装前请自行审阅 源码与 MIT 许可证。
社区目录 skillhub.cn 上的 laa1991/dsh-health 与 DeepSeek / 幻方无官方从属关系；DSH 生态强调「一切皆插件」，目录是独立站点上的发现入口。
结尾¶
dsh-health-readout 把「读哪里、怎样算健康、失败算什么」写进一份 JSON 声明，通过只读工具 health_readout 输出一条可审计的总判决。若你的工作流已经产出文件或接口型指标，又希望模型别靠猜，可以按 README 安装并在自管目录维护 readings.json。
- 目录页：https://www.skillhub.cn/plugins/laa1991/dsh-health
- GitHub：https://github.com/laa1991/dsh-health
