Introduction

In the DSH (DeepSeek Harness) agent development workflow, debugging and reproducing terminal output is a common requirement. This plugin is designed to address the recording and sharing of terminal sessions. It records terminal or tool output from DSH sessions into asciinema v2 format and provides a self-contained offline player for playback and HTML export.

The plugin implements recording by subscribing to tool/result output in session/event, without relying on external terminal services. Its semantics align with the rec, play, and cat actions of the official asciinema CLI, and it independently implements the core logic without depending on the official CLI, supporting fully offline rendering.

Core Features

  • Terminal Recording: Records terminal/tool output from sessions into asciinema v2 (.cast) files.
  • Offline Playback: Provides an embedded player with a built-in offline renderer, supporting HTML export and no external requests.
  • Semantic Alignment: Supports the term_rec (record), term_play (playback), and term_cat (to text) tool actions.
  • Independence: Independently implements cast-core without depending on asciinema CLI; player data is embedded, with no <asciinema-player> tag or official dependencies.
  • Privacy Protection: Does not record input by default; only records output.

Installation and Activation

Prerequisites

This plugin depends on the adjacent dsh-src source code in its development form (via a link: dependency) and requires Node.js >= 23.6.0 at runtime.

Installation Steps

  1. After cloning this repository, ensure that dsh-src (the official DeepSeek Harness source code) exists in a sibling directory.
  2. Run the build in the dsh-src directory: pnpm install && pnpm run build.
  3. Run the build in this repository directory to generate build artifacts: pnpm install --offline && pnpm build.
  4. Load the plugin through DSH:
dsh plugin --profile demo add ./dsh-asciinema

Configuration Mounting

The plugin is inserted via bundle patch through cordis.yml. Add the following to the host configuration:

- insert:
    - id: asciinema
      name: dsh-asciinema
      config:
        width: 100          # 录制几何宽
        height: 40          # 录制几何高
        maxEvents: 5000     # 事件条数上限
        maxBytes: 1048576   # 数据字节上限
        recordInput: false  # 默认不录输入
        castsDir: '.casts'  # 落盘目录

Tool Usage

term_rec — Recording

Used to control the recording process, with session- or command-level isolation supported.

Parameters:
- action: start | stop | mark | status
- scope: session | command (isolation context)
- record_input: Boolean; whether to record input
- marker: Insert a marker during recording

Examples:
- term_rec action('start'): Subscribes to the current session’s tool/result output and buffers it.
- term_rec action('stop'): Stops recording and writes a .casts/<name>.cast file.
- term_rec action('mark'): Inserts a marker event during recording.
- term_rec action('status'): Lists active recordings.

term_play — Playback

Used to generate a playback file or view text.

Parameters:
- path: Required; path to the .cast file
- mode: auto | html | text

Examples:
- term_play path('./my.cast'): By default, generates an offline HTML file (with a self-contained player).
- term_play path('./my.cast') mode('text'): Outputs plain text with control sequences removed.

term_cat — Convert to Text

Converts a cast file to plain text.

Parameters:
- path: Required
- raw: Whether to preserve the raw ANSI control sequences
- include_input: Whether to include input events

Behavior Details and Limitations

  • Truncation Strategy: When the event count or byte count exceeds the configured limit, the recording is sealed and marked truncated.
  • Runtime Environment: The plugin runs as a Node.js process and requires Node >= 23.6.0 (with built-in type stripping support).
  • Permissions: The plugin only subscribes to tool/result output, makes no network requests, and has no external service dependencies.
  • Interoperability: No interoperability validation has been performed with the official asciinema play/player yet, and .cast files are not guaranteed to be parseable by official tools.
  • Distribution Notice: When distributing, include a NOTICE file (declaring MPL-2.0 player assets).

Summary

dsh-asciinema provides a complete solution for recording and replaying terminal output. Its core value lies in its fully offline capability and independent implementation. Developers who need to record agent execution processes or debug terminal output can load and use it directly through the DSH plugin mechanism.