When building agents or research workflows in DeepSeek Harness (DSH), scripts, terminal outputs, images, and work-in-progress files often end up scattered across different directories. When you need to trace back the basis for a decision or reconstruct an experimental process, this fragmented state makes it hard to locate context quickly. Runbook attempts to unify DSH sessions, Git repositories, and observed outputs into a persistent, Git-versioned research workspace.

Runbook is a plugin designed for DeepSeek Harness. It provides a Jupyter Notebook-like research interface, whose core is building a persistent, Git-based research workspace. This interface integrates session lineage, script execution records, and visual evidence, keeping research questions, script changes, and outputs consistent.

Core Features

Runbook’s design core is to map research units to Git entities rather than merely to filesystem hierarchies.

  • Research Compass: Located at the top of the interface, it displays the current research question, decision status, and the next decision step. Its sources are project documents such as README.md and STATUS.md.
  • Stable Script Attempt Cells: The same script corresponds to one Attempt cell in the interface. Rerunning the script does not create a new page or directory; instead, it adds execution history and Evidence under that cell.
  • Session Lineage Projection: The interface shows the current DSH session and the execution records of its ancestors. Side-branch session records are retained but collapsed by default, ensuring focus on the current research path.
  • Visual Evidence & Artifacts: The interface displays the latest image, PDF, and HTML outputs. Thumbnails also appear next to the conversational turns that generated the evidence, preventing evidence from being separated from its context.
  • Safe Reruns: Before executing a script, Runbook generates a manifest and shows a preview, requiring user confirmation before execution to avoid accidental operations.
  • Agent-Aware Git Author Identity: Supports distinguishing between Agent and human contributors. When committing, the Agent does not overwrite the identity of human integrators.

Installation and Enablement

To install this plugin, use DSH’s plugin management command.

dsh plugin --profile web add zhan-tz/dsh-plugin-runbook

After installation, restart the selected DSH interface and select Runbook / Run This in the conversation to enter the workspace.

Typical Usage

In the Runbook workspace, researchers can operate as follows:

  1. Open and Orient: Open the Runbook interface in the DSH conversation, first read the top “Research Compass,” and clarify the current research goal and next decision step.
  2. Reuse and Improve Scripts: If the research question has not changed, directly improve the existing Attempt cell scripts to add history; only consider creating a new branch when the question, data, or output contract has truly changed.
  3. Execute and Confirm: Run a supported entry script, and confirm after reviewing the execution plan.
  4. Compare Evidence: After confirmation, compare the newly generated Evidence with previous results and the corresponding conversational turns in the interface.
  5. Version Control: Save validated checkpoints to Git.

Applicable Scenarios and Notes

Applicable Scenarios: Suitable for research projects that require long-term maintenance of research scripts, rely on Git version control, and need clear traceability of experimental evidence chains.

Notes:
* Browser requests are bound to the persisted DSH session, and paths are restricted to that session’s workspace.
* Inline media currently has a 6 MiB limit; files exceeding the limit are displayed but must be opened with a system application.
* Rerun operations use the host runner and require a confirmation step.
* Terminal text is only an alternative observation means and is not perfect producer/consumer trace evidence.
* Static I/O checks are only hints and cannot prove arbitrary dynamic I/O.
* The plugin does not expose an arbitrary browser Shell, nor does it execute unstructured code snippets clipped from files.

Runbook provides a structured view focused on the research process itself. It does not replace a file browser; rather, it maps DSH execution facts, Git history, and project documentation into a traceable and reproducible workspace. For developers who want Git-based collaboration and evidence-chain management in DSH, this is a ready-to-use tool.

GitHub Repository | Community Catalog