dsh-code-highlight

English | 中文

为报告类文档提供代码语法高亮的 DeepSeek Harness（DSH）插件。注册一个 highlight_code 工具，
把代码片段渲染成带真实语法配色的产物，落到 Markdown / HTML、Word、PowerPoint、PDF 与 LaTeX 里。

特性

• 68 种语言 —— 按语言名、别名或文件扩展名解析；没有给定语言时按内容自动识别，识别不出就老实按纯文本处理。
• 11 种输出 —— html、html-file、sh-html、svg、svg-png、png、latex、latex-minted、markdown、ansi、text。
• codeinword / SyntaxHighlighter HTML 导入 —— 把 codeinword.com 导出的高亮 HTML 直接作为输入，
  转成行内样式 HTML、SVG、PNG、LaTeX 等任意格式（可顺手换主题）；也能反向导出这种标记格式。
• 15 套主题 —— paper-light（文档向）、github-dark、github-light、one-dark、monokai、solarized-light、solarized-dark，
  以及 codeinword.com 所演示的 SyntaxHighlighter 3.0.83 经典八式：
  sh-default、sh-django、sh-eclipse、sh-emacs、sh-fadetogrey、sh-mdultra、sh-midnight、sh-rdark，另有 auto。
• 矢量与位图共用一套几何 —— SVG 与 PNG 由同一个布局模型产出，物理尺寸与逐格位置一致。
• 面向文档的排版参数 —— width_in、dpi、font_size_pt、line_height、show_title，直接产出能贴进 Word 一页宽的图。
• 直接落盘 —— 给出 output_file 就写文件并返回路径，不再把长文回传给模型。
• 不需要浏览器，也不需要 Office —— PNG 由内置的 Pillow 栅格化器绘制，中文与 ASCII 在固定步进网格上对齐。
• 零运行时 npm 依赖 —— 分词器与渲染器全部自带，离线可用。

安装

从 npm 安装（推荐）

dsh plugin --profile desktop add dsh-code-highlight

• npm 安装的是预构建产物，跳过 allowBuilds 构建授权，一条命令装好。
• 固定版本写 dsh plugin --profile desktop add dsh-code-highlight@1.1.0。
• --profile 换成你的 profile 名：DSH Desktop 用 desktop，Web 版通常是 web；Desktop 版请先完全退出应用再执行。
• 包页面：。

从 GitHub 安装（CLI）

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

• --profile 换成你的 profile 名：DSH Desktop 用 desktop，Web 版通常是 web。
• Desktop 版请先完全退出应用再执行——dsh plugin 要独占 profile 的写锁。
• dsh plugin --profile 把参数原样交给 pnpm，所以要固定版本可以直接写
  dsh plugin --profile desktop add github:scientificmaniac/dsh-code-highlight#v1.1.0。

在 DSH 会话里安装

让 Agent 调用 plugin_manager：

action: install_bundle
target: <本仓库的绝对路径>

三种方式都用包内 cordis.patch.yml 插入插件条目；安装后 highlight_code 对该 profile 的所有会话可用。
修改源码后需要重启 DSH 才会加载新模块。

供其他项目直接引用

npm install dsh-code-highlight

或克隆源码自行构建：

git clone https://github.com/scientificmaniac/dsh-code-highlight.git
cd dsh-code-highlight
npm test

index.js 导出 DSH 插件的 apply / inject / name；若只想用渲染能力，可直接引用 src/ 下的模块：

import { resolveLanguage } from 'dsh-code-highlight/src/languages.js';
import { tokenizeLines } from 'dsh-code-highlight/src/tokenize.js';
import { resolveTheme } from 'dsh-code-highlight/src/themes.js';
import { renderHtml } from 'dsh-code-highlight/src/render.js';

用法

格式与落点

各报告格式的落地流程

• codeinword.com 的高亮 HTML —— 直接把它作为 code 传入（默认自动识别，必要时 input_format: "sh-html"）：
  这种标记的颜色依赖外部样式表，直接贴进 Word 不显色；配 format: html 转成内联样式版（Word 可直接粘贴），
  或 svg / png 出插图，theme 可任意换肤。
• Markdown / HTML —— format: html，把返回片段写进报告。
• Word（.docx） —— 两条路：format: svg-png + width_in: 6.3 插入定宽矢量图（或同尺寸 PNG）；
  或 format: html 直接粘贴为 Word 原生彩色文本——行结构是表格、行号独立成列（长行折行不错位）、
  行首缩进用 、title 不进代码格且不可选中；已在 LibreOffice 实测逐行渲染正常，真 Word 未实测。
• PDF —— format: png 直接排版，或 format: latex 由 LaTeX 排版、html-file 打印。
• LaTeX / PDF 论文 —— format: latex（listings）或 format: latex-minted。
• PowerPoint —— format: svg + canvas: "960x540"，再用 univer_compile_svg 编译到幻灯片页。

栅格化：为什么中文能对齐

SVG 与 PNG 共用固定步进网格：一个 ASCII 单元格固定为 0.6 × 字号，CJK 与 emoji 占两个单元格。
排版因此只由几何决定，不依赖浏览器或 Pillow 各自的字体度量。

PNG 绘制时按字符选字体：ASCII 走等宽字体（默认 Consolas），宽字符走 CJK 字体（默认微软雅黑），
两者落在同一网格起点上——这就是「Consolas 画 ASCII + 中文字体画中文」而不让缩进走样的做法。
字体可用 mono_font / cjk_font 覆盖。

栅格化依赖 Python 3 + Pillow。脚本以 stdio: ignore 启动、诊断经临时文件回传，
因此在禁止捕获管道的受限环境里同样可用。解释器按 python、py、python3 依次尝试，
也可用环境变量 DSH_CODE_HIGHLIGHT_PYTHON 指定。

架构

flowchart TD
invoke(["highlight_code 调用code · language · format · output_file"])
entry["index.js参数解析 · 格式分派 · 落盘"]
detect["src/detect.js特征打分"]
langs["src/languages.js68 种语言的词法定义"]
tokenize["src/tokenize.js通用分词器 + 专用扫描模式"]
themes["src/themes.js15 套主题"]
render["src/render.js渲染器 + blockGeometry 共用几何"]
raster["py/rasterize.pyPillow 栅格化器"]

invoke --> entry
entry -->|"language 省略时"| detect
detect --> langs
entry --> langs
langs --> tokenize
tokenize -->|"每行 token"| render
themes --> render
entry --> render
render --> f1["html · html-file · sh-html"]
render --> f2["svg"]
render --> f3["latex · latex-minted"]
render --> f4["ansi · markdown · text"]
render -->|"宽高与缩放"| raster
f1 --> d1["Markdown / HTML 报告"]
f2 --> d2["Word / PPT / PDF 插图"]
f3 --> d3["LaTeX 论文"]
raster --> d4["记录 DPI 的位图"]

SVG 与 PNG 是同一份几何的两个出口：render.js 算出逻辑宽高与缩放系数，
交给 rasterize.py 画位图，两者因此物理尺寸一致。

项目结构

flowchart TB
repo["dsh-code-highlight/"]

repo --> index["index.js插件入口"]
repo --> src["src/"]
repo --> py["py/rasterize.pyPillow 栅格化器"]
repo --> tests["tests/"]
repo --> scripts["scripts/示例生成脚本"]
repo --> examples["examples/示例产物"]
repo --> manifest["package.json · cordis.patch.ymllocale/ · icon.svg"]
repo --> docs["README.md · README.en.mdCONTRIBUTING.md · CHANGELOG.md · LICENSE"]

src --> languages["languages.js68 种语言"]
src --> detect["detect.js语言识别"]
src --> tokenize["tokenize.js分词器"]
src --> themes["themes.js15 套主题"]
src --> render["render.js渲染器 + 共用几何"]

tests --> encoding["encoding.mjs编码守卫"]
tests --> smoke["smoke.mjs112 项断言"]
tests --> raster["rasterize.mjs19 项断言"]

开发

npm test                                  # 编码守卫 + 冒烟测试（无需 Python）
npm run test:raster                       # PNG 链路测试（需要 Python 3 + Pillow）
node scripts/make-doc-figure.mjs          # 生成配对的 SVG + PNG 文档插图

npm test 覆盖分词往返不变式（68 种语言 × 压力样本，输出拼回必须等于输入）、
渲染矩阵（语言 × 主题 × 格式）、语言自动识别、画布与英寸排版、show_title 去重与 CJK 双格宽度。
详细报告写入 smoke-report.txt。

语言一览

通用编程语言：JavaScript、TypeScript、Python、Java、Kotlin、Scala、Groovy、C、C++、C#、Go、Rust、Swift、
Ruby、PHP、Perl、Lua、R、MATLAB、Julia、Dart、Elixir、Erlang、Haskell、Clojure、Lisp、F#、Visual Basic、
Pascal、Fortran、Assembly、COBOL、Solidity、Verilog、GLSL、GDScript、Apex、Zig、Nim、OCaml、PowerShell、
Shell、Fish、Batch、Vim Script、AWK。

配置与数据：JSON、YAML、TOML、INI / properties / dotenv、XML、HTML、CSS / SCSS / LESS、Markdown、
Dockerfile、Makefile / CMake、Nginx、HTTP、Protocol Buffers、GraphQL、Terraform / HCL、Nix、Mermaid、
CSV / TSV、Diff / Patch、LaTeX、纯文本。

已知限制

• 一次处理一个代码片段；不做整篇报告的批量扫描。
• width_in 只把图缩到栏宽以内，不会把短片段放大到正好一页宽。
• HTML 中内嵌的 / 内容不单独着色。
• 宽字符一律按两格计算；个别终端 emoji 的实际宽度可能略有出入。
• format: markdown 输出的是围栏块，着色由下游 Markdown 渲染器完成，与本插件的配色无关。
• 修改插件源码后，运行中的会话仍使用已加载的模块；新代码在 DSH 重启后生效。

贡献

欢迎提 Issue 与 PR，详见 CONTRIBUTING.md。

许可证

MIT。