dsh-health-readout
DSH 的声明式健康状态读取：声明从哪里读取、什么算作健康，以及每次读取对应哪种判定结果。只读——它组合读取结果，但不会成为新的事实来源。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:laa1991/dsh-health#bc28cbd1607d49f4ac903e59b615342f0db1fc85Health Readout 以 dsh-health-readout 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Declare where to read, what counts as healthy, and what each failure means — get one verdict.
A read-only dsh plugin. It composes readings that already exist (files, JSON endpoints, log tails) and returns a single verdict with per-reading detail. It never writes anything, never keeps state, and never becomes a source of truth.
{
"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."
}]
}
These are not style preferences. Each one is a bug we shipped somewhere before it became a rule, and here they are enforced by the type shapes and by tests rather than by good intentions:
unknown — never ok,
never 0, never false. unknown is always printed, and it moves the verdict on its own.selftest: true feeds each declared criterion its own
counter-example and reports any criterion that stayed green — a criterion nobody can falsify is
decoration, and it is reported as such.blind is required. A reading whose limits are unstated
reads like a reading whose limits do not exist.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
The package ships exactly the files that run (no build, no prepare script, no runtime
dependencies), so a git install needs no build permission from the user.
Every value resolves in this order: the plugin row's config: block → environment variable →
built-in default.
| setting | config key | environment variable | default |
|---|---|---|---|
| where readings live | dataDir | DSH_HEALTH_READOUT_DATA_DIR | ~/.dsh-health-readout |
| the declarations | specFile | DSH_HEALTH_READOUT_SPEC | readings.json (inside dataDir) |
| evaluate only some ids | only | DSH_HEALTH_READOUT_ONLY | all |
The data directory is deliberately not a dsh platform directory. dsh may rebuild its own directories on upgrade; a user's readings must not be inside something that can be rebuilt out from under them. Point
dataDiranywhere you control.
Relative paths inside the spec resolve against dataDir. ~ and ${dataDir} are expanded.
Copy examples/readings.example.json to <dataDir>/readings.json and edit it.
Source kinds
| kind | reads | required fields |
|---|---|---|
file-age-seconds | seconds since a file was written | path |
file-size | bytes | path |
file-exists | whether a path exists (false is knowledge, not ignorance) | path |
json-field | a dotted path inside a JSON file | path, field |
jsonl-last-field | a dotted path in the last parseable JSONL line (tail-read) | path, field, maxBytes? |
text-count | regex matches in the last maxBytes of a file | path, pattern, maxBytes?, flags? |
dir-count | files in a directory, optionally by suffix | path, suffix? |
http-json-field | a dotted path in a JSON endpoint (always timed out) | url, field, timeoutMs? |
Operators (healthy.op): lt lte gt gte eq neq between matches exists absent.
States (healthy.bad, default degraded), ordered by severity —
the worst reading decides the verdict:
ok < notice < unknown < degraded < broken
unknown sits above notice on purpose: a readout that cannot see part of the world must not
report a confident ok.
health_readout — one read-only call, two optional arguments:
only — comma-separated reading ids to evaluate.selftest — also prove every declared criterion can go red.The rendered output lists each reading with its value, its verdict, its reason and its blind spot,
and prints the unreadable ones separately ("Could not read" is not "fine".).
node --test test/criteria.test.mjs test/sources.test.mjs test/spec.test.mjs test/readout.test.mjs
43 tests, no test framework and no fixtures on disk. The two arms worth knowing about: deleting a
watched file must move the verdict to unknown (never leaving it at ok), and a deliberately
unfalsifiable criterion (matches: ".*") must be reported as such by selftest.
changed-within operator. Comparing to a previous value requires state; see above.unknown is noisy by design. A missing file moves the verdict. That is the intended trade:
silence about a blind spot is more expensive than a loud report about one.MIT.