前言¶
DeepSeek Harness (dsh) 的內置 headless 模式默認只打印最終回覆文本並返回 0/1 退出碼，這適合快速驗證，但在 CI（持續集成）流水線中顯得過於單薄。CI 系統需要機器可讀的詳細報告（如 JSON、JUnit XML）以及更精細的語義化退出碼。
headless- 是一個爲 dsh 設計的插件，它將普通的 session 會話轉化爲第一流的 CI 產物：提供 JSON/NDJSON 會話報告、JUnit XML 測試報告、語義化退出碼、文件資產收集以及隱私脫敏功能。它既是一個 dsh profile bundle，也提供獨立的 CLI 工具。
核心功能¶
該插件通過訂閱 dsh 的 session 事件流，在會話結束或運行時生成結構化數據。
- 會話事件流：訂閱
session/created、session/event、session/disposed等事件，將每一輪交互、工具調用轉化爲結構化事件（包含類型、模型、延遲、Token 統計、錯誤信息等）。 - JSON 輸出：生成事務級別的完整報告，包含會話元數據、事件列表、結果和統計信息。
- JUnit XML 輸出：將工具調用和步驟映射爲測試用例，使 CI 系統能像展示普通測試運行一樣展示 dsh 執行過程。
- 語義化退出碼：區分成功、失敗、超時、阻塞、中斷等狀態，並提供可覆蓋的默認代碼。
- 資產收集：掃描對話中引用的文件路徑，生成包含存在性、大小的清單。
- 隱私開關：支持文本截斷、參數隱藏、密鑰掩碼和路徑相對化，可在掛載時或運行時通過
set_options配置。 - 工具鏈：提供三個 dsh 工具（
output_status、output_events、set_options）以及獨立的 CLI 入口（dsh-headless- render、dsh-headless- exit）。
安裝與啓用¶
使用前需確保已安裝 Node.js >= 18，且 dsh 安裝包含 sessions 服務（任何 base 或 headless profile 均滿足此條件）。
- 添加插件：通過 CLI 將插件作爲 profile bundle 添加到
headlessprofile 中。
dsh plugin --profile headless add github:JohnXu22786/headless-
- 運行測試：在啓用該 profile 的情況下執行命令。
dsh --profile headless "run the test suite"
運行結束後，在 `dsh-output/` 目錄下會生成報告文件。
- CI 集成示例：
- 獲取語義化退出碼：
dsh-headless- exit dsh-output/report.
* 渲染 JUnit XML：
dsh-headless- render dsh-output/report. --format junit --out junit.xml
適用場景與注意¶
- 確定性輸出：相同的會話日誌和相同的選項會產生完全相同的字節流，便於版本控制和調試。
- 無 stdout 干擾：插件不會向標準輸出寫入內容，因此可以與官方 headless runner 混合使用而不會產生輸出衝突。
- 生態背景：DSH 的理念是“一切皆插件”。
headless-是社區項目，與 DeepSeek 或幻方無官方隸屬關係。
總結¶
headless- 通過插件化方式解決了 DSH 在 CI 環境下輸出顆粒度不足的問題。它將 session 事件轉化爲結構化報告，提供了從 JSON 到 JUnit 的多種格式支持，以及語義化退出碼和隱私保護機制，適合需要嚴格自動化評估的智能體開發場景。
- 目錄頁: https://www.skillhub.cn/plugins/JohnXu22786/headless-
- 源碼地址: https://github.com/JohnXu22786/headless-
