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 种语言支持和离线运行能力，它为技术报告的自动化生产提供了可靠的语法高亮保障。