dsh-asciinema: DSH 插件：终端输出录制与离线回放

前言¶

在 DSH（DeepSeek Harness）智能体开发流程中，调试与复现终端输出是常见需求。本插件旨在解决终端会话记录与分享的问题，它将 DSH 会话中的终端或工具输出录制为 asciinema v2 格式，并提供自包含的离线播放器进行回放和 HTML 导出。

该插件通过订阅 session/event 中的 tool/result 输出来实现录制，无需依赖外部的终端服务。其语义对齐官方 asciinema CLI 的 rec/play/cat 三种动作，且完全独立实现核心逻辑，不依赖官方 CLI，支持完全离线渲染。

核心功能¶

终端录制：将会话中的终端/工具输出录制为 asciinema v2 (.cast) 文件。
离线回放：提供自带离线渲染器的内嵌播放器，支持 HTML 导出，无外部请求。
语义对齐：支持 term_rec（录制）、term_play（回放）、term_cat（转文本）三个工具动作。
独立性：独立实现 cast-core，不依赖 asciinema CLI；播放器数据内嵌，无 <asciinema-player> 标签或官方依赖。
隐私保护：默认不录制输入，仅录制输出。

安装与启用¶

前置依赖¶

本插件在开发形态下依赖相邻的 dsh-src 源码（通过 link: 依赖），且运行时依赖 Node.js >= 23.6.0。

安装步骤¶

克隆本仓库后，确保同级目录存在 dsh-src（DeepSeek Harness 官方源码）。
在 dsh-src 目录执行构建：pnpm install && pnpm run build。
在本仓库目录执行构建以生成编译产物：pnpm install --offline && pnpm build。
通过 DSH 加载插件：

dsh plugin --profile demo add ./dsh-asciinema

配置挂载¶

插件通过 cordis.yml 进行 bundle patch 插入。需要在宿主配置中添加如下内容：

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

工具用法¶

term_rec — 录制¶

用于控制录制流程，支持会话或命令级别的隔离。

参数：
- action: start | stop | mark | status
- scope: session | command（隔离上下文）
- record_input: 布尔值，是否录制输入
- marker: 录制中插入标记

操作示例：
- term_rec action('start'): 订阅当前会话的 tool/result 输出并缓冲。
- term_rec action('stop'): 停止录制并写入 .casts/<name>.cast 文件。
- term_rec action('mark'): 在录制中插入标记事件。
- term_rec action('status'): 列出活动录制。

term_play — 回放¶

用于生成回放文件或查看文本。

参数：
- path: 必填，.cast 文件路径
- mode: auto | html | text

操作示例：
- term_play path('./my.cast'): 默认生成离线 HTML 文件（带自包含播放器）。
- term_play path('./my.cast') mode('text'): 输出去除控制序列的纯文本。

term_cat — 转文本¶

将 cast 文件转换为纯文本。

参数：
- path: 必填
- raw: 是否保留 ANSI 控制序列原文
- include_input: 是否包含输入事件

行为细节与限制¶

截断策略：当事件数或字节数超过配置上限时，录制会被封存（seal），并标记 truncated。
运行环境：插件以 Node.js 进程运行，需 Node >= 23.6.0（内置 type 擦除支持）。
权限：插件仅订阅 tool/result 输出，无网络请求，无外部服务依赖。
互操作性：目前未与官方 asciinema play/player 做互操作验证，不保证 .cast 文件可被官方工具解析。
分发声明：分发时需携带 NOTICE 文件（声明 MPL-2.0 player 资产）。

总结¶

dsh-asciinema 提供了一套完整的终端输出录制与回放方案，核心价值在于其完全的离线能力与独立的实现。对于需要记录智能体执行过程或调试终端输出的开发者，可直接通过 DSH 插件机制加载使用。