前言¶

在 DeepSeek Harness（DSH）裏看 agent 跑工具時，工具卡里往往是一整段命令、腳本或 API 調用。懂開發的人能順着讀，不熟悉編程的人只能猜「它在改什麼」。會話裏若再疊一層說明面板，又會和代碼塊搶版面、重複解釋同一件事。

下面介紹的 dsh-code-explainer 走另一條路：在工具卡的輸入代碼和輸出區上，用行尾註釋把「這行在做什麼」和必要的「爲什麼這麼寫」寫進同一句中文，不單獨佔一塊教學區域。複製代碼時拿到的仍是原始文本，註釋不參與 DOM 正文。

這是什麼¶

dsh-code-explainer 是 DSH 的客戶端插件，維護者爲 xiaoluoli45。它針對 agent 實際執行的代碼、命令和工具輸出做逐行（或按輸出類型分級）的中文解釋，面向「不想先學語法也想跟上 agent 在幹什麼」的讀者。

插件分兩半：瀏覽器端（client.js）負責在會話 DOM 裏掛註釋、處理輸出區版式；宿主端（index.js）用本地規則先給說明，規則覆蓋不了的行再通過可配置的 LLM 補一句。說明通過 POST /line-notes 等本地 HTTP 接口下發，前綴爲 /dsh-code-explainer/api，僅接受迴環地址。

當前倉庫版本爲 0.4.1（見 package.json），許可證 MIT。

核心功能¶

輸入代碼塊：灰色行尾 // 註釋¶

工具卡里的輸入代碼按行解析（依賴 DSH 代碼塊 DOM：pre > code > span.line）。每一行末尾用 CSS 僞元素掛上中文說明，樣式比代碼略淡，與語法高亮並存。

• 空行、純括號行、純註釋行不強行加說明。
• 同一種寫法在同一代碼塊內只在第一次出現時完整解釋，後續可標「（同上）」。
• 術語首次出現可帶簡短中文對照（例如 await（等待異步完成））。
• 代碼塊標題欄有 「註釋：開 / 註釋：關」 總開關，狀態記在瀏覽器 localStorage；關掉後恢復純代碼視圖。

註釋寫在僞元素裏，不會進入 textContent，因此複製按鈕和手動選中都不會帶上說明。

輸出區：按類型區分¶

輸出若爲代碼，會先去掉類似 1: 的行號再按行說明。總述節點插在宿主 ioSection 外側，避免破壞其兩列 grid 佈局（插件內用 test/output-card.mjs 迴歸這一條）。

解釋覆蓋面¶

本地規則覆蓋命令行、常見工具調用（如 tools.ops_bash）、參數行、賦值與 await、console.log、import / require、fs、path、process.env 等。規則表列不出的複雜行，在 llm 爲 auto 時由模型按行號補一句；llm: off 則只用規則，不調模型。

工具卡仍在 data-state="running" 時，前端只展示規則結果，狀態結束後再異步請求模型補充，避免半截代碼反覆觸發 LLM。

隱私、成本與降級¶

展示、落盤和發給模型前，會對 sk-...、ghp_...、Bearer ... 等憑據樣式做掩碼。模型請求按代碼內容哈希緩存，同一段代碼不重複調用。模型不可用、超時或 JSON 解析失敗時，頁面保留規則說明，不阻塞工具執行，也不改寫用戶當前會話的模型選擇。輔助調用不向會話日誌追加事件。

安裝與啓用¶

環境要求：DSH >= 0.2.0，Node >= 20。

在本地已有倉庫目錄的前提下，用 link 方式裝進 desktop profile（路徑換成你機器上的絕對路徑）：

dsh plugin --profile desktop add "link:<本倉庫目錄的絕對路徑>"

安裝後刷新 DSH 頁面（Ctrl+R）或重啓宿主。package.json 聲明瞭 dsh.bundle.patch，宿主會把 cordis.patch.yml 掛到 profile 層，一般不需要改 DSH 安裝目錄本身。

卸載：

dsh plugin --profile desktop remove dsh-code-explainer

配置（cordis.patch.yml）¶

安裝時也可由 profile 傳入等價片段：

- insert:
    - id: dsh-code-explainer
      name: './index.js'
      config:
        llm: auto
        # provider: deepseek-official
        # model: deepseek-chat

常用配置項：

頁面上的「註釋：開/關」管展示；enabled 管插件是否啓動，兩者不是同一層開關。

典型用法與界面行爲¶

安裝並啓用後，在 DSH 會話裏讓 agent 執行帶代碼的工具卡即可，無需額外命令。插件通過 MutationObserver 跟蹤會話 DOM，React 重渲染後會補回行尾屬性，並每 3 秒兜底掃描一次。

README 中的效果示意：輸入區類似下面結構時，每行行尾會出現中文說明（此處僅作格式參考，實際註釋由插件生成）：

const r = await tools.ops_bash({
  command: "Get-ChildItem -LiteralPath 'D:\\project'",
  description: "List directory contents",
  timeoutMs: 60000
});
console.log(JSON.stringify(r, null, 2));

維護者在 DSH 0.2.1-rc.5 上對 run_code 等路徑做過實測（插件 0.4.0 時段），驗證了動態 import("node:fs") 的解釋、try/catch 表述、長註釋換行不擠代碼、複製不含註釋等行爲。離線冒煙測試見倉庫 node test/smoke.mjs、node test/output-card.mjs。

需要只看規則、零模型成本時，把配置裏的 llm 設爲 off。需要排查插件狀態時，可調用本地 API，例如 GET /dsh-code-explainer/api/health、GET /state。

適用場景與注意¶

適合誰

• 需要向非技術同事演示或共讀 DSH 會話、又不願在代碼外再維護一套說明的人。
• 自己讀 agent 日誌時，希望命令行和常見 Node/API 寫法有即時中文對照的開發者。

邊界與依賴（摘自倉庫「已知邊界」）

• 只處理會話裏工具卡內的代碼塊，不處理 Markdown 正文裏的圍欄代碼。
• 依賴宿主代碼塊 DOM 契約；DSH 前端大改時需同步改選擇器。
• 複雜嵌套表達式、鏈式調用、模板字符串等可能只得到一句通用說明或未識別標記。
• 「註釋：開/關」存在瀏覽器本地，不隨賬號同步。

權限與安全

插件隨當前 DSH 進程運行，宿主端可調用你配置的 LLM 路由處理規則未覆蓋的代碼片段。安裝前應閱讀倉庫源碼與 MIT 許可；社區目錄 SkillHub 插件頁 與 GitHub 倉庫相互獨立，均不等同於 DeepSeek 或幻方的官方應用商店。

結尾¶

dsh-code-explainer 把「agent 寫了什麼」收成工具卡上的行尾中文：規則先出結果，必要時再由模型補洞，並可一鍵關掉註釋或關掉 LLM。若你在 DSH desktop 場景裏需要這種讀代碼方式，可按 link 安裝並在 cordis.patch.yml 裏調 llm 與限額。

• 目錄頁：https://www.skillhub.cn/plugins/xiaoluoli45/dsh-code-explainer
• 源碼與完整說明：https://github.com/xiaoluoli45/dsh-code-explainer