dsh-diff-view: DeepSeek Harness 通用 Diff 查看器插件

前言¶

在 DeepSeek Harness (DSH) 插件生態中，客戶端插件往往需要展示文本差異。手寫 Diff 算法、處理行對齊和單詞高亮不僅開發成本高，還容易引入錯誤。dsh-diff-view 提供了一個通用的 Diff 查看器組件，複用了 DSH 原生 Review 的樣式和算法邏輯，供插件開發者直接調用。

這是什麼¶

這是一個由 joao-paulo-santos 維護的 DSH 客戶端插件。它不包含獨立的訪問 UI，而是作爲一個服務注入到 DSH 客戶端中，提供 Diff 視圖渲染能力。

核心功能¶

該插件的核心能力集中在文本差異的計算與展示上：

Diff 組件複用：提供 diffFileComponent，支持從兩個完整文本生成文件差異視圖。
算法支持：基於 LCS (Longest Common Subsequence) 算法進行行級比對。
單詞高亮：支持單詞級別的差異標記。
視圖模式：支持 Split（左右分欄）和 Unified（統一視圖）兩種模式切換。
行號處理：提供真實的行號，且在摺疊上下文時保持行號準確性。
語法高亮：複用平臺的 useCodeHighlighter 和 languageForPath 原語，使 Diff 視圖的配色與原生 Review 保持一致。
樣式獨立：插件自帶 ddv-* 樣式表，用戶無需手動管理 Diff 行的 CSS。

安裝與啓用¶

安裝該插件需要你擁有一個 DSH 的 Checkout 代碼倉庫和一個激活的 Profile（例如 web）。

克隆插件倉庫：

    mkdir -p ~/dsh-plugins && cd ~/dsh-plugins
    git clone https://github.com/joao-paulo-santos/dsh-diff-view.git

將插件添加到 DSH Profile：

    # 假設你的 harness checkout 在當前目錄
    pnpm dsh plugin --profile web add ~/dsh-plugins/dsh-diff-view

驗證配置是否生效：

    pnpm dsh --profile web --dump-config

安裝完成後重啓 Harness。插件會自動注入 diffView 服務。

典型用法¶

注入 diffView 服務後，可以通過以下方式使用：

1. 渲染文件差異組件¶

從兩個完整的文本生成 Diff 組件。組件內部包含 Split/Unified 切換按鈕。

// consumer client half, inject: ['diffView', …]

const Diff = ctx.diffView.diffFileComponent({
  path: 'src/a.ts',        // 可選，用於選擇語法高亮規則
  before: oldText,         // 修改前的文本
  after: newText,          // 修改後的文本
  initialMode: 'split',    // 默認模式: 'split' (默認) | 'unified'
  showToggle: true,        // 顯示 Split/Unified 切換膠囊
  wrap: false,             // true 表示長行換行，false 表示滾動
  wordHighlights: true,    // 啓用單詞級高亮
})

return React.createElement(Diff, {})

2. 使用 Hunks 數據¶

如果你需要更細粒度的控制，可以使用 hunksOf 方法獲取差異塊。

const hunks = ctx.diffView.hunksOf(oldText, newText)
// 返回格式: [{ oldStart, oldLines, newStart, newLines, lines: [' ctx', '-old', '+new'] }]

3. 使用底層渲染引擎¶

對於自定義佈局，可以使用底層的行對齊和單詞跨度計算引擎。

// 1. 獲取對齊的編輯行
const rows = ctx.diffView.engine.alignedEditRowsOf(beforeLines, afterLines)
// rows: [{ kind: 'same'|'replace'|'delete'|'insert', removedLine?, addedLine? }]

// 2. 獲取單詞級別的差異標記
const spans = ctx.diffView.engine.wordSpansOfLinePair(beforeLine, afterLine)
// spans: { removedSpans, addedSpans }: arrays of { text, changed }

適用場景與注意¶

無 UI 訪問：該插件不提供獨立頁面，必須由宿主插件通過注入服務的方式調用。
行號真實性：行號源自 Diff 計算結果，在上下文摺疊之前，因此行號在不同視圖模式下是準確的。
語法高亮依賴：如果未提供 path 或平臺未實現 languageForPath 原語，Diff 行將僅以純文本渲染。
樣式管理：Diff 行的 CSS 由插件的 ddv-* 類名管理，宿主無需編寫 Diff 相關的 CSS。
無持久化：該插件不處理數據持久化，也不與 Approval 流程強耦合。

結尾¶

dsh-diff-view 是一個輕量級、無依賴的 DSH 插件，專注於提供核心的 Diff 視圖能力。無論是構建 Approval 工具、Scratchpad 還是代碼審查插件，都可以直接複用其組件和引擎。