dsh-stall-sentinel：DeepSeek Harness 的輕量級長任務卡死檢測插件

DeepSeek Harness (DSH) 理念是“一切皆插件”。在智能體開發中，ctx.subprocess.spawn 生成的長任務（如後臺構建、安裝依賴）如果卡死，往往難以及時發現。現有監控方案要麼依賴複雜的進程表查詢，要麼容易誤殺正在運行的任務。dsh-stall-sentinel 是一個專爲 DSH profile-bundle 設計的輕量級看門狗插件，它接管進程生成邏輯，通過探針採樣提供卡死預警與取證報告，但不干擾任務執行。

插件簡介¶

這是一個純 JS Cordis 插件，零額外運行時依賴（僅使用 Node 內置模塊）。它重寫了 longtask-stall-guard 的思路，針對 DSH 場景從零實現，旨在提供進程卡死的自動檢測與取證，絕不執行 kill、terminate 或重試操作。

核心能力¶

• 零額外運行時依賴：只依賴 node:* 內置模塊，不引入複雜的外部庫。
• 自動監控與接線：默認安裝後自動攔截 ctx.subprocess.spawn，無需手動調用 guard.watch 即可覆蓋 bash 工具、後臺 pwsh 及其啓動的構建任務。
• 保守的判定模型：基於“進度凍結”與“CPU 狀態（空閒或打滿）”的雙信號聚合取證。只有連續兩個採樣窗口滿足條件才判定卡死。
• 僅提醒與取證：處理動作唯一爲“提醒 + 生成取證報告”，絕不執行 kill、terminate 或重試操作。
• 完整日誌記錄：支持 JSONL 事件日誌記錄與輪轉，便於事後分析。

安裝¶

插件以 dsh.bundle.patch 包的形式提供。安裝時需確保其排在基礎包之後。

dsh plugin --profile <profile> add <path-or-link-to-this-dir>

或者在 profile 的 cordis.patch.yml 中直接引用本地路徑：

- insert:
    - id: stall-sentinel
      name: './plugins/dsh-stall-sentinel/lib/index.js'
      config: { enabled: true }

使用方式¶

插件通過 ctx.provide('stall-sentinel', api) 暴露控制接口。你可以手動註冊需要監控的目標：

const guard = ctx.get('stall-sentinel');
const { taskId } = guard.watch({
  taskId: 'my-build',
  label: 'pnpm install',
  pid: child.pid,
  logPath: 'C:\\agent\\install.log',
  marker: 'added'
});
guard.getStatus();
guard.list();
guard.unwatch(taskId);

關鍵點：目標必須提供 logPath（用於進度信號）和 pid。沒有 logPath 的目標會永久處於 unknown 狀態，無法區分慢與卡死。

適用場景與注意¶

• 適用場景：適用於通過 ctx.subprocess.spawn 啓動的長任務（如後臺 pwsh、npm install、構建腳本）。這些任務默認被自動監控。
• 邊界說明：
• 對於 ctx.jobs 中純 job 記錄（無 pid、無輸出暴露），插件僅做存活跟蹤，無法判定是否卡死。
• 對於 ctx.shell 層面，插件通過 subprocess seam 覆蓋，不直接消費輸出。
• 插件在受限沙箱（禁 Node pipe spawn）中通過 stdio: ['ignore', fdOut, fdErr] 仍可工作。
• 可靠性契約：插件絕不殺進程，只讀取探針。採樣失敗會降級爲 unknown。日誌落盤異常會回退到 console.error。