OpenClaw diffs-language-pack 插件指南为 Diff 查看器扩展 Shiki 语法高亮语言支持【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw导读diffs-language-packDiff Viewer Language Pack是 OpenClaw 生态中为diffs插件补齐语法高亮覆盖的扩展包。本文以其官方插件参考文档docs/plugins/reference/diffs-language-pack.md为核心骨架结合extensions/diffs-language-pack与extensions/diffs的真实源码与测试讲解它的分发安装方式、新增语言清单、零配置启用方式、静态资源服务的底层实现以及它与主diffs插件的协同发现机制。读完本文你将清楚知道什么场景需要安装它、如何安装、它装了什么、以及为什么卸载后 Diff 仍能以纯文本正常阅读。一、插件定位主 Diffs 查看器的“语言包”外挂OpenClaw 的diffs插件是一个可选插件工具把 agent 生成的 before/after 文本或 unified patch 渲染成只读的 diff 查看器浏览器 viewer URL或 PNG/PDF 附件。其内置的语法高亮只覆盖一组“常见语言”详见 docs/tools/diffs.md。diffs-language-pack插件的定位非常单一为 Diffs 查看器提供默认语言集之外的语法高亮。它的官方插件清单extensions/diffs-language-pack/openclaw.plugin.json中写着id:diffs-language-packname:Diff Viewer Language PackrequiresPlugins:[diffs]——即它必须在diffs插件基础上工作单独安装没有意义activation.onStartup:true——随 Gateway 启动时自动激活从插件形态看它属于 OpenClaw 三类扩展面plugin/agent/skill中的plugin且不注册任何独立的 agent 工具其 README 明确说明“The language pack contributes static viewer assets; it does not register a separate agent tool”见 extensions/diffs-language-pack/README.md。它的职责只有一条向 Gateway 提供额外的静态 viewer 资源供diffs渲染管线按需加载。二、分发与安装npm 与 ClawHub 双通道按插件参考文档的 Distribution 一节本插件的分发信息为维度值npm 包名openclaw/diffs-language-packClawHub 安装标识clawhub:openclaw/diffs-language-pack默认安装源npm见 extensions/diffs-language-pack/package.json 中install.defaultChoice: npm最低宿主版本2026.5.27install.minHostVersionPlugin API 兼容要求2026.8.1compat.pluginApi安装步骤先安装并启用主插件diffs再安装语言包# 1) 先安装主 diffs 插件其中 modes/view/file/both、主题、布局等能力都来自它 openclaw plugins install diffs # 2) 再安装语言扩展包npm 源 openclaw plugins install openclaw/diffs-language-pack # 或者使用 ClawHub 源与 npm 等价二者取一即可 openclaw plugins install clawhub:openclaw/diffs-language-pack安装或更新插件后需要重启 Gateway才会生效README 原话Restart the Gateway after installing or updating the plugin.。因为语言包随宿主一起决定 viewer 静态资源是否可用diffs插件的“语言包探测”发生在插件初始化阶段见下文第五节热更新不一定触发重新探测重启是最稳妥的做法。主diffs插件的官方文档也把语言包作为高亮扩展的推荐通道docs/tools/diffs.mdopenclaw plugins install clawhub:openclaw/diffs-language-pack三、新增语言默认集之外到底多了哪些高亮diffs插件内置的高亮语言集是固定的 29 种摘自 docs/tools/diffs.md 的 Syntax highlighting 一节javascript、typescript、tsx、jsx、json、markdown、yaml、css、html、sh、python、go、rust、java、c、cpp、csharp、php、sql、docker、ruby、swift、kotlin、r、dart、lua、powershell、xml、toml常见别名js、ts、bash、md、yml、c、dockerfile、rb、kt、ps1等会被归一化到上述语言。这些是默认集不装语言包就已可用。语言包则补上默认集之外的 Shiki 支持语言插件参考文档列出的示例包括本文按领域归组以便查阅领域新增高亮语言前端框架/模板Astro、Vue、Svelte、MDX数据查询/结构化GraphQL、CSV、dotenv、INI、TOML 之外的文件类型基础设施即代码Terraform/HCL、Nginx、Apache函数式/系统编程Clojure、Elixir、Haskell、OCaml、Scala、Zig合约/硬件描述Solidity、Verilog/VHDL科学计算/排版Fortran、MATLAB、LaTeX图表/样式/脚本Mermaid、Sass/Less/SCSS包管理/文本类Nix、diff 文件说明这些语言最终都来自 Shiki 的上游语言与别名目录Shiki languages 目录为上游权威来源参考文档中以链接形式给出。也就是说语言包并不是 OpenClaw 自造语法定义而是把更大范围的 Shiki grammar 打包进 viewer runtime让 Gateway 无需外部网络即可本地完成高亮渲染。装了之后的效果lang 参数与回退行为语言包不仅影响“按内容自动识别”还直接改变diffs工具lang参数的行为。主插件文档对lang参数的定义是Language override hint for before/after mode. Unknown values and languages outside the default viewer set fall back to plain text unless the Diff Viewer Language Pack plugin is installed.即before/after模式下可用lang显式指定高亮语言。当语言包未安装时默认集之外的语言名会被当作未知值、高亮回退为纯文本当语言包已安装时更大的语言集合会被接受为有效 hint。反过来即使完全不安装语言包也不影响 Diff 功能的可用性——参考文档明确说明“If the pack is not installed, those files still render as readable plain text.” 也就是说语言包是纯增量增强多装只会让更多语言从“可读的纯文本”升级为“彩色高亮”卸载也只会优雅降级不会导致渲染失败。四、零配置启用没有 configSchema 的插件一个容易让人意外的设计是语言包本身没有任何配置项。它的openclaw.plugin.json中configSchema: { type: object, additionalProperties: false, properties: {} }properties为空对象、additionalProperties为false意味着宿主在启动时会校验任何传给该插件的多余配置都会被拒绝。所以安装即用、无需在~/.openclaw/openclaw.json的plugins.entries里写配置。若你的全局配置恰好需要显式声明条目形式与主 diffs 插件一致{ plugins: { entries: { diffs: { enabled: true, // 渲染主题、布局、字号、输出格式等默认值都配置在这里主 diffs 插件 config: { /* ... */ }, }, // diffs-language-pack 无需 config安装并被宿主识别即可生效 }, }, }所有影响视觉表现的默认值fontFamily、fontSize、lineSpacing、layout、showLineNumbers、theme、fileFormat、fileQuality、mode、ttlSeconds等都归属于主diffs插件的config.defaults而不是本语言包。五、底层原理静态资源服务与两段式 viewer 加载语言包虽小但它的实现细节完整覆盖了“安全地提供静态资源”这一典型插件需求。核心代码集中在两个文件extensions/diffs-language-pack/src/plugin.ts —— HTTP 路由注册与响应处理extensions/diffs-language-pack/src/viewer-assets.ts —— viewer 资源定位、缓存与 loader 生成1) HTTP 路由前缀匹配 plugin 级鉴权registerDiffsLanguagePackPlugin向插件 API 注册一条路由plugin.ts 第 8-15 行api.registerHttpRoute({ path: /plugins/diffs-language-pack, auth: plugin, match: prefix, handler: createDiffsLanguagePackHttpHandler(), });path为/plugins/diffs-language-packmatch: prefix表示前缀下所有路径都进入该 handlerauth: plugin说明该路由纳入 Gateway 的插件级鉴权体系与主 diffs 查看器的 token 化访问策略协同viewer 主文档、token 均由 diffs 插件管理。handler 内部只放行指向 viewer 资源前缀VIEWER_ASSET_PREFIX /plugins/diffs-language-pack/assets/的请求且只接受GET/HEAD其余方法一律返回405 Method not allowedplugin.ts 第 17-26 行。2) 两个关键静态文件loader 与 runtimeviewer-assets.ts 定义了资源前缀与两个固定路径const VIEWER_LOADER_PATH /plugins/diffs-language-pack/assets/viewer.js; export const VIEWER_RUNTIME_PATH /plugins/diffs-language-pack/assets/viewer-runtime.js;这与主 diffs 文档中列出的 viewer 资源路径完全对应docs/tools/diffs.md 的 Viewer URL and network behavior 一节/plugins/diffs/assets/viewer.js/plugins/diffs/assets/viewer-runtime.js/plugins/diffs-language-pack/assets/viewer.js——只有 diff 使用了语言包覆盖的语言时才会被引用两个文件的分工很有意思viewer-runtime.js是真正的“重量级”产物内含扩展语言集的 Shiki grammar 与高亮逻辑。它由构建脚本生成package.json中assetScripts.build指向scripts/build-diffs-viewer-runtime.mts full属于被 git 忽略的生成产物——plugin.test.ts在干净检出环境会先调用该构建命令生成测试 fixture 再启动服务第 24-48 行。viewer.js是一个动态生成的极薄 loader内容仅为一行带版本指纹的 importviewer-assets.ts 第 88 行loaderBody: import ${VIEWER_RUNTIME_RELATIVE_IMPORT_PATH}?v${hash};\n其中hash是 runtime 内容 sha1 的前 12 位十六进制。这个“loader 指纹 runtime”的组合让浏览器在 runtime 内容变化时能自动绕过缓存cache busting而 loader 本身保持路径稳定。3) 缓存与安全响应头资源响应的细节也值得注意plugin.ts 第 34-47 行、70-78 行viewer-runtime.js使用不可变缓存Cache-Control: public, max-age31536000, immutable一年因为它带版本指纹、内容不可变适合长缓存其它资源默认no-store, max-age0统一附加X-Content-Type-Options: nosniff与Referrer-Policy: no-referrer配合主 diffs 的 viewer CSPdefault-src none、仅 self 脚本共同加固每个响应显式设置Content-Length保证GET/HEAD头一致注释中引用了 RFC 9110 §8.6。runtime 文件的读取有 mtime 级内存缓存viewer-assets.ts 第 75-90 行只有当磁盘 mtime 变化时才重新读文件、重算指纹避免每次请求都做磁盘 I/O。六、与主插件的协同语言包“可用性发现”语言包如何被 diffs 识别是实现上最有意思的部分。主 diffs 插件通过探测兄弟扩展目录来判断语言包是否可用而不是运行时去注册表查询。extensions/diffs/src/plugin.ts中定义了DIFFS_LANGUAGE_PACK_PLUGIN_ID diffs-language-pack随后定位与 diffs 扩展同级的diffs-language-pack目录检查该目录下是否存在openclaw.plugin.json且存在生成的 viewer 产物候选路径包括assets/viewer-runtime.js与dist/assets/viewer-runtime.js命中则把languagePackAvailable: true传入渲染与语言归一化逻辑。这一判断也被单元测试覆盖extensions/diffs/src/plugin.test.ts 中 “diffs plugin language-pack discovery” 用例在临时目录模拟了diffs-language-pack目录与assets/viewer-runtime.js断言探测结果在“有/无 runtime 产物”两种情况下分别为languagePackAvailable: true/false。在语言 hint 归一化层extensions/diffs/src/language-hints.tslanguagePackAvailable标志直接决定对非常见语言名的接受度标志为true时才会把 Abap、Astro 这类语言视为受支持 hint否则回退到纯文本对应language-hints.test.ts中{ languagePackAvailable: true }与false两组断言。最终的 viewer 资源选择在渲染层完成extensions/diffs/src/render.test.ts中有两个对照用例——语言包不可用时渲染 HTML不包含diffs-language-pack引用可用且 diff 语言属于扩展集时viewerRuntime被标记为language-pack即 viewer 文档会在必要时加载/plugins/diffs-language-pack/assets/viewer.js这一 loader再由它按指纹引入扩展 runtime。语言包自身的 HTTP 行为测试extensions/diffs-language-pack/src/plugin.test.ts使用openclaw/plugin-sdk的withServer测试环境直接对注册的 handler 发起真实请求验证对viewer-runtime.js发GET与HEAD两者均返回200且HEAD的Content-Length与GET的字节数精确一致HEAD 不返回 body对不存在的资源路径发HEAD返回404Content-Length精确等于错误文案字节数。这两条用例专门守护第六节第 3 点提到的 GET/HEAD 响应一致性约定。七、何时需要它选型与最佳实践综合主插件文档、语言包参考文档与源码可以得到如下实践建议需求判定当你的 agent 会话主要处理 JS/TS/Python/Go/Rust/Java/Kotlin 等主流语言 diff默认 29 种语言集已够用不必安装语言包当 diff 频繁涉及 Vue/Svelte/Astro、GraphQL、Terraform/HCL、LaTeX、Mermaid、Solidity 等冷门或专业语言时再安装它换取彩色高亮。不装也安全语言包是纯增强项。缺失时这些文件“仍以可读纯文本渲染”不会破坏view浏览器查看或filePNG/PDF 附件两条输出链路。跟随主 diffs 配置生效外观类偏好主题、字体、布局、缩放、质量预设等配置在主diffs插件的config.defaults语言包只决定“哪些语言能上色”。版本约束宿主版本需2026.5.27插件 API 需2026.8.1与当前仓库 extensions/diffs-language-pack/package.json 中的version: 2026.8.1对应安装或更新后重启 Gateway。安全边界viewer 默认仅回环访问语言包静态资源同样受 Gateway 插件级路由鉴权与安全头保护若需要远程分享 viewer 链接仍应遵循主 diffs 插件的security.allowRemoteViewer、viewerBaseUrl/baseUrl配置与访问控制建议而不是绕过到资源层。延伸阅读插件参考文档docs/plugins/reference/diffs-language-pack.md主插件使用指南含工具参数、插件默认值、安全模型、产物生命周期docs/tools/diffs.md语言包实现源码extensions/diffs-language-pack/src/plugin.ts、extensions/diffs-language-pack/src/viewer-assets.ts语言包安装与构建元数据extensions/diffs-language-pack/package.json、extensions/diffs-language-pack/openclaw.plugin.json、extensions/diffs-language-pack/README.md语言包 HTTP 服务测试extensions/diffs-language-pack/src/plugin.test.ts主 diffs 侧的探测、语言归一化与渲染测试extensions/diffs/src/plugin.ts、extensions/diffs/src/language-hints.ts、extensions/diffs/src/render.test.ts【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考