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