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 插件機制加載使用。