在 DeepSeek Harness (DSH) 中构建智能体或研究流程时，脚本、终端输出、图片和半成品文件往往会散落在各个目录。当需要回溯某个决策的依据或重构实验过程时，这种碎片化的状态很难快速定位。Runbook 试图将 DSH 的会话、Git 仓库和观测到的输出，统一投影到一个持久化、Git 版本控制的研究工作面上。
Runbook 是一个为 DeepSeek Harness 设计的插件。它提供了一个类似 Jupyter Notebook 的研究界面，核心是构建一个持久化且基于 Git 的研究工作空间。该界面整合了会话血缘、脚本执行记录和可视化证据，让研究问题、脚本修改和输出结果保持一致。
核心功能¶
Runbook 的设计核心是将研究单元映射为 Git 中的实体，而非单纯的文件系统层级。
- 研究罗盘：位于界面顶部，展示当前的研究问题、决策状态以及下一步判别步骤。其来源是项目中的
README.md和STATUS.md等文档。 - 稳定的脚本尝试单元格：同一脚本对应界面上的一个 Attempt 单元格。重跑脚本不会创建新的页面或目录，而是增加该单元格下的执行历史和 Evidence 生成。
- 会话血缘投影：界面展示当前 DSH 会话及其祖先的执行记录，旁支的会话记录会被保留但默认折叠，确保视线聚焦于当前研究路径。
- 可视化证据与工件：界面会展示最新的图片、PDF 和 HTML 输出。生成这些证据的对话回合旁边也会显示缩略图，避免证据与上下文分离。
- 安全重跑：在执行脚本前，Runbook 会生成清单并展示预览，要求用户确认后才执行，避免误操作。
- Agent 感知的 Git 作者身份：支持区分 Agent 和人类贡献者，Agent 在提交时不会覆盖人类集成者的身份。
安装与启用¶
安装该插件需要使用 DSH 的插件管理命令。
dsh plugin --profile web add zhan-tz/dsh-plugin-runbook
安装完成后，重启选定的 DSH 界面，并在对话中选择 Runbook / 运行本 即可进入工作空间。
典型用法¶
在 Runbook 工作面中，研究者可以按照以下步骤进行操作：
- 打开与定位：在 DSH 对话中打开 Runbook 界面，先阅读顶部的「研究罗盘」，明确当前的研究目标和下一步判别步骤。
- 脚本复用与改进：如果研究问题未变，直接改进现有的 Attempt 单元格脚本以添加历史记录；仅在问题、数据或输出契约真正不同时，才考虑创建新分支。
- 执行与确认：运行支持的入口脚本，在查看执行计划后进行确认。
- 证据对比：确认执行后，在界面中对比新生成的 Evidence 与之前的生成结果，以及对应的对话回合。
- 版本控制：将经过验证的检查点保存到 Git。
适用场景与注意事项¶
适用场景：适合需要长期维护研究脚本、依赖 Git 版本控制、需要清晰追溯实验证据链的研究项目。
注意事项：
* 浏览器请求被绑定在持久化的 DSH 会话上，路径被限制在该会话的工作空间内。
* 内联媒体目前有 6 MiB 的限制，超过限制的文件会显示但需用系统应用打开。
* 重跑操作使用主机的 runner，并需要确认步骤。
* 终端文本仅作为备选观测手段，并非完美的生产者/消费者溯源证据。
* 静态 I/O 检查仅为提示，不能证明任意动态 I/O。
* 插件不暴露任意的浏览器 Shell，也不会执行从文件中剪切的非结构化代码片段。
Runbook 提供了一个聚焦于研究过程本身的结构化视图。它不替代文件浏览器，而是将 DSH 的运行事实、Git 历史和项目文档映射为一个可追溯、可复现的工作面。对于希望在 DSH 中进行 Git 化协作和证据链管理的开发者，这是一个直接可用的工具。
