dsh-code-highlight: 報告類文檔代碼高亮插件

DSH 生態強調“一切皆插件”。在編寫技術報告或文檔時，代碼塊往往是核心內容，但默認的 Markdown 語法高亮無法直接產出 Word、PPT 或 PDF 可用的矢量/位圖產物。

scientificmaniac/dsh-code-highlight 插件註冊了一個 highlight_code 工具。它通過內置的詞法分析器和渲染器，將代碼片段轉換爲帶真實語法配色的 HTML、SVG、PNG 或 LaTeX 代碼。

核心能力¶

該插件主要服務於報告類文檔場景，具備以下能力：

多語言支持：內置 68 種編程語言與配置文件的詞法定義。支持按語言名、別名或文件擴展名指定，未指定時自動識別。
多格式輸出：提供 10 種輸出格式。包括用於直接嵌入的 HTML，用於矢量插圖的 SVG，用於位圖預覽的 PNG，以及用於 LaTeX 文檔的 listings 和 minted 環境。
主題系統：內置 7 套主題，如 github-dark、paper-light（適合文檔排版）等。
離線可用：分詞器與渲染器均爲內置，不依賴運行時的 npm 包，可離線使用。
文檔排版：支持通過 width_in（英寸）、dpi、font_size_pt 等參數控制輸出尺寸，確保生成的圖片能完美貼合文檔欄寬。

安裝與啓用¶

安裝前請確保 DSH Desktop 應用已完全退出。安裝命令如下：

dsh plugin --profile desktop add github:scientificmaniac/dsh-code-highlight

安裝完成後，highlight_code 工具將在當前 profile 的所有會話中生效。若修改了插件源碼，需要重啓 DSH 才能加載新模塊。

典型用法¶

調用 highlight_code 工具時，需提供 code（必填）與 format 參數。其他參數爲可選項。

基礎渲染¶

{
  "action": "highlight_code",
  "code": "const a = 1;",
  "language": "javascript",
  "format": "html",
  "theme": "github-dark"
}

生成 Word/PPT 插圖¶

生成矢量圖並直接落盤：

{
  "action": "highlight_code",
  "code": "print('Hello')",
  "language": "python",
  "format": "svg",
  "theme": "paper-light",
  "width_in": 6.3,
  "output_file": "./code_snippet.svg"
}

生成 PDF 用的位圖¶

{
  "action": "highlight_code",
  "code": "package main",
  "language": "go",
  "format": "png",
  "theme": "github-dark",
  "dpi": 300,
  "output_file": "./code_snippet.png"
}

LaTeX 輸出¶

生成 LaTeX 源碼，可直接放入 .tex 文件中編譯：

{
  "action": "highlight_code",
  "code": "return true;",
  "language": "javascript",
  "format": "latex",
  "theme": "solarized-light"
}

柵格化與限制¶

該插件使用 Python 3 的 Pillow 庫進行位圖柵格化。其核心機制是使用固定步進網格，將 ASCII 字符映射到等寬字體，將寬字符（如中文）映射到等寬字體，從而保證縮放時佈局不亂。

已知限制：

單次處理：一次只能處理一個代碼片段。
寬度限制：width_in 僅限制輸出寬度，不會將過短的片段拉伸填滿一頁。
HTML 特殊內容：生成的 HTML 中，<script> 和 <style> 標籤內的內容不會被單獨着色。
Markdown 格式：format: markdown 輸出的是無顏色的圍欄代碼塊，着色由下游 Markdown 渲染器完成。
寬字符計算：寬字符（如中文）在柵格化中按兩格計算。
源碼修改：修改插件源碼後必須重啓 DSH 才能生效。

總結¶

dsh-code-highlight 是一個專爲文檔生成場景設計的代碼高亮工具。它解決了智能體在生成報告時，代碼塊樣式不統一、難以直接嵌入 Office 或 LaTeX 文檔的問題。通過內置的 68 種語言支持和離線運行能力，它爲技術報告的自動化生產提供了可靠的語法高亮保障。