前言¶
在 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
