OpenClaw Diffs 插件:为 Agent 构建网关托管的 Diff 查看器与 PNG/PDF 渲染器

原创2026-10-15 11:31:381,953 阅读
文章标签:人工智能大模型LLM 网关AI AgentAPI网关后端CLI浏览器控制插件系统MCP Clients即时通讯语音桌面应用

OpenClaw Diffs 插件:为 Agent 构建网关托管的 Diff 查看器与 PNG/PDF 渲染器

本篇围绕 OpenClaw 仓库中的 @openclaw/diffs 插件展开,完整讲解其 diffs 工具的输入参数、三种输出模式、插件默认配置与安全模型,并结合插件源码剖析从 diff 输入到网关托管查看器 URL、再到 Chromium 截图生成 PNG/PDF 的完整渲染链路。读完你可以掌握:如何在 ~/.openclaw/openclaw.json 中为该插件配置呈现与渲染默认值、如何让 Agent 通过 canvas 展示交互式 diff、以及如何把 diff 渲染成可投递到聊天频道的文件工件。

一、插件定位:Agent 只读 diff 查看器的三种能力

@openclaw/diffs 是 OpenClaw 的一个只读 diff 查看器插件(见 README 与 package.json)。它只注册一个名为 diffs 的工具,该工具具备三项核心能力:

  • 渲染一个由网关托管(gateway-hosted)的 diff 查看器,供 canvas 使用;
  • 将同一份 diff 渲染成本地文件(PNG 或 PDF);
  • 同时接受任意 before/after 文本,或一段 unified patch(统一格式补丁)。

工具结果中的 details 字段是 Agent 后续行动的依据,包括:

字段 含义
details.viewerUrl 可在 canvas 中打开的网关 URL
details.filePath 请求文件渲染时,本地渲染产物的路径
details.fileFormat 渲染文件格式(png 或 pdf)
details.artifactId / details.expiresAt 工件标识与 TTL 元数据
details.context 可用路由元数据:agentId、sessionId、messageChannel、agentAccountId

插件启用时还附带两件事:一是随包提供一个 companion skill(位于 skills/diffs/SKILL.md),二是通过 before_prompt_build 钩子把稳定的工具使用指引前置注入到 system-prompt 空间。从源码看,index.ts 中 api.on("before_prompt_build", ...) 返回 { prependSystemContext: DIFFS_AGENT_GUIDANCE },指引文本定义在 prompt-guidance.ts。由于走的是 prependSystemContext,这段指引不会挤占 user-prompt 空间,但每一轮对话都可用。

这意味着 Agent 可以形成如下工作流:

  • 以 mode=view 调用 diffs,再把 details.viewerUrl 交给 canvas present 打开;
  • 以 mode=file 调用 diffs,随后通过常规 message 工具用 path 或 filePath 发送渲染文件;
  • 需要两种产物时以 mode=both 调用。

插件注册逻辑(注册工具、HTTP 路由、提示词钩子)集中在 index.ts:

api.registerTool((ctx) => createDiffsTool({ api, store, defaults, context: ctx }), {
  name: "diffs",
});
api.registerHttpRoute({
  path: "/plugins/diffs",
  auth: "plugin",
  match: "prefix",
  handler: createDiffsHttpHandler({
    store,
    logger: api.logger,
    allowRemoteViewer: security.allowRemoteViewer,
  }),
});

对应的行为验证见 browser.test.ts 中 “registers the tool, http route, and system-prompt guidance hook” 用例。

二、工具输入:before/after 文本与 unified patch 两种形式

diffs 工具接受两种互斥的输入形式。形式一,提供 before 与 after 文本:

{
  "before": "# Hello\n\nOne",
  "after": "# Hello\n\nTwo",
  "path": "docs/example.md",
  "mode": "view"
}

形式二,直接提供 unified patch:

{
  "patch": "diff --git a/src/example.ts b/src/example.ts\n--- a/src/example.ts\n+++ b/src/example.ts\n@@ -1 +1 @@\n-const x = 1;\n+const x = 2;\n",
  "mode": "both"
}

两种形式不可混用:从 tool.ts 的 normalizeDiffInput 可以看到,如果传入了 patch 同时又带 before/after,会抛出 Provide either patch or before/after input, not both. 的工具输入错误;两者都没有时则抛出 Provide patch or both before and after text.。

完整参数说明(结合 tool.ts 中 TypeBox 定义的 DiffsToolSchema):

  • mode:view、file 或 both。已废弃别名 image 仍被接受并等价于 file,保持向后兼容(types.ts 中 DIFF_MODES 包含 image,tool.ts 的 isArtifactOnlyMode 将 image 与 file 同等对待);
  • layout:unified 或 split;
  • theme:light 或 dark(默认 dark);
  • fileFormat:png 或 pdf(默认 png);
  • fileQuality:standard、hq 或 print;
  • fileScale:设备像素比覆盖(1-4);
  • fileMaxWidth:最大宽度覆盖,单位 CSS 像素(640-2400);
  • expandUnchanged:展开未变更区段。注意这是仅按调用生效的选项,不是插件默认配置键(配置 schema 中没有该字段);
  • path:before/after 输入用于展示的显示名(显示为 diff 文件名);
  • title:显式查看器标题;
  • ttlSeconds:工件生命周期。schema 中标注默认 1800 秒、上限 21600 秒(见 tool.ts);
  • baseUrl:覆盖返回 viewer 链接所用的网关 base URL。只接受 origin 或 origin+basePath,不允许 query/hash(校验逻辑在 url.ts 的 normalizeViewerBaseUrl)。

源码中还有若干 README 未逐一列出的细节参数:lang(before/after 输入的语言覆盖,上限 128 字节)以及一组向后兼容别名 format/imageFormat/imageQuality/imageScale/imageMaxWidth,在 tool.ts 中按 fileFormat ?? imageFormat ?? format 的优先级归并,对应的行为由 tool.test.ts 中 “accepts image* tool options for backward compatibility” 与 “accepts deprecated format alias for fileFormat” 两个用例守护。

输入安全上限(源码常量见 tool.ts):

  • before 与 after:各最大 512 KiB;
  • patch:最大 2 MiB;
  • patch 渲染上限:最多 128 个文件 / 120,000 行(常量 MAX_PATCH_FILE_COUNT、MAX_PATCH_TOTAL_LINES 定义在 render.ts)。

超限输入会以工具输入错误被拒绝,测试用例 “rejects oversized patch payloads” 与 “rejects oversized before/after payloads”(tool.test.ts)验证了这一点。

三种模式下的结果与降级行为

  • mode=view:创建工件、返回 details.viewerUrl,文本消息为 Diff viewer ready.\n<url>;
  • mode=file(或 image):不走查看器工件,而是创建一个“独立文件工件”(standalone file artifact),直接输出 details.filePath;
  • mode=both:两者都要。值得注意的是降级路径——从 tool.ts 的 catch 分支可见,若 both 模式下文件渲染失败,工具不会整体报错,而是仍返回可用的 viewerUrl,并在 details.fileError/details.imageError 中记录渲染失败原因。测试用例 “falls back to view output when both mode cannot render an image” 专门覆盖了这一行为。

三、插件默认配置:~/.openclaw/openclaw.json 中的 defaults

在 ~/.openclaw/openclaw.json 中设置插件级默认值(README 示例):

{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
        config: {
          defaults: {
            fontFamily: "Fira Code",
            fontSize: 15,
            lineSpacing: 1.6,
            layout: "unified",
            showLineNumbers: true,
            diffIndicators: "bars",
            wordWrap: true,
            background: true,
            theme: "dark",
            fileFormat: "png",
            fileQuality: "standard",
            fileScale: 2,
            fileMaxWidth: 960,
            mode: "both",
          },
        },
      },
    },
  },
}

显式传入的工具参数始终优先于这些默认值——README 明确 “Explicit tool parameters still win over these defaults”,tool.test.ts 中 “uses configured defaults when tool params omit them” 与 “prefers explicit tool params over configured defaults” 两个用例分别验证了两侧。

内置默认值与合法取值范围由 config.ts 的 DEFAULT_DIFFS_TOOL_DEFAULTS 与 openclaw.plugin.json 中的 configSchema 共同定义,两者在测试中要求保持同步(“keeps the runtime json schema in sync with the manifest config schema”):

配置键 类型 / 范围 默认值 说明
fontFamily string Fira Code diff 内容与标题的首选字体族
fontSize number, 10–24 15 基础字号(像素),越界值会被钳制
lineSpacing number, 1–3 1.6 行高乘数
layout unified | split unified 查看器初始布局
showLineNumbers boolean true 是否显示行号
diffIndicators bars | classic | none bars 增删标记样式
wordWrap boolean true 长行自动换行
background boolean true 增删行背景高亮
theme light | dark dark 查看器主题
fileFormat png | pdf png 文件渲染格式(别名 format)
fileQuality standard | hq | print standard 渲染质量预设
fileScale number, 1–4 2 设备像素比
fileMaxWidth number, 640–2400 960 最大渲染宽度(CSS 像素)
mode view | image | file | both both 省略 mode 时的默认输出模式

质量预设不只是标签,它在 config.ts 的 DEFAULT_IMAGE_QUALITY_PROFILES 中映射到具体的渲染参数:

预设 scale maxWidth maxPixels
standard 2 960 8,000,000
hq 2.5 1200 14,000,000
print 3 1400 24,000,000

从源码结构看,质量预设与 fileScale/fileMaxWidth 存在联动:在 resolveDiffImageRenderOptions(config.ts)中,如果显式指定了质量预设而未指定 scale/width,则回退到该预设的 scale/maxWidth;反之显式值优先且会被钳制到合法范围。该逻辑由 config.test.ts 中 “derives file defaults from quality preset and clamps explicit overrides” 用例验证。

配置解析对非法值采取“钳制 + 回退”策略而非直接报错:fontSize 取整后限制在 10–24,lineSpacing 限制在 1–3,非法的 layout/theme/fileFormat 回退到内置默认值,mode 的合法集合包含兼容值 image。安全子配置则单独解析:

{
  plugins: {
    entries: {
      diffs: {
        config: {
          security: {
            allowRemoteViewer: false, // 默认 false
          },
        },
      },
    },
  },
}

四、安全模型:loopback 默认、令牌 URL 与远程限流

查看器 URL 的安全性是这个插件设计上的重点,README “Notes” 与源码共同说明了四层防线:

1. 默认仅 loopback 可访问。 HTTP 处理函数(http.ts)对每个请求判定 localRequest:仅当 remoteAddress 为 127.0.0.1/::1 且请求不含代理转发头(x-forwarded-for、x-real-ip、forwarded 等,见 hasProxyForwardingHints)时才视为本地请求;非本地请求在 security.allowRemoteViewer !== true 时直接返回 404 Diff not found。

2. 不可猜测的令牌路径。 查看器路径形如 /plugins/diffs/view/<id>/<token>(前缀常量见 store.ts)。id 为 10 字节随机数的 hex(20 位),token 为 24 字节随机数的 hex(48 位),格式由 types.ts 的两个正则锚定;HTTP 层在读取磁盘前就先做格式校验,畸形 id/token 直接 404(测试 “rejects malformed artifact ids before reading from disk”)。

3. 远程失败限流。 README 提到 “Remote viewer misses are throttled to reduce token-guess abuse”。具体参数见 http.ts:每个远程客户端 60 秒窗口内累计 40 次失败即锁定 60 秒,锁定期间返回 429 Too Many Requests 并携带 Retry-After 头;成功访问会清零该客户端计数。限流器 key 数上限 2048,超出时先剪枝、再整体清空防止内存膨胀。

4. 响应头与内容安全策略。 查看器页面响应携带严格 CSP(default-src 'none'、connect-src 'none'、frame-ancestors 'self' 等,见 http.ts),共享头包含 cache-control: no-store、x-content-type-options: nosniff、referrer-policy: no-referrer。

存储层还有一道防路径穿越的护栏:store.ts 的 assertWithinRoot 确保所有工件路径(meta.json 中记录的 htmlPath、filePath)都落在 store 根目录之内,任何试图逃逸的路径(包括被篡改的元数据)都会抛错。对应测试 “rejects file paths that escape the store root” 与 “rejects tampered html metadata paths outside the store root”(store.test.ts)。

五、渲染管线:从 diff 输入到 HTML,再到 PNG/PDF

5.1 HTML 预渲染(SSR)

diff 计算与预渲染由依赖 @pierre/diffs(package.json 锁定为 1.1.5)完成,README 也注明 “Diff rendering is powered by Diffs”。render.ts 的 renderDiffDocument 会同时产出两份 HTML 文档:

  • html:交互式查看器文档(runtimeMode="viewer"),托管在网关上;
  • imageHtml:面向截图的图片变体文档(runtimeMode="image")。从 buildImageRenderOptions 可以看到,图片变体强制 fontSize 不低于 16px,保证截图后的文字清晰度。

before/after 输入通过 preloadMultiFileDiff 预渲染成单个 diff 卡片;patch 输入先经 parsePatchFiles 解析,逐文件 preloadFileDiff 预渲染后按文件顺序拼接。若 SSR 预渲染因 JSON import 属性问题失败(shouldFallbackToClientHydration),会降级为客户端水合(空 prerenderedHTML),由查看器运行时在浏览器端完成渲染。

每份 HTML 卡片内嵌 <script type="application/json" data-openclaw-diff-payload> 携带完整 payload(含 prerenderedHTML、选项与语言列表),并注入一段 unsafeCSS 应用字体族、字号与行高(行高按 fontSize × lineSpacing 计算,最小 20px,见 render.ts)。

5.2 浏览器截图:共享 Chromium 实例

PNG/PDF 渲染由 browser.ts 的 PlaywrightDiffScreenshotter 完成(基于 playwright-core)。几个值得注意的工程细节:

  • 浏览器可执行文件探测链:browser.executablePath 配置 → 环境变量 OPENCLAW_BROWSER_EXECUTABLE_PATH / BROWSER_EXECUTABLE_PATH / PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH → 各平台 PATH 中的常见命令(chromium、google-chrome、msedge、brave 等)→ 平台常见安装路径。探测结果按“配置+环境变量+PATH”做 key 缓存(browser.ts)。
  • 共享浏览器实例:acquireSharedBrowser 维护一个按引用计数的共享 Chromium 进程,空闲 30 秒后自动关闭(DEFAULT_BROWSER_IDLE_MS),避免每次渲染都冷启动浏览器;测试 “reuses the same browser across renders and closes it after the idle window”(browser.test.ts)验证了复用与空闲回收。
  • 离线资源路由:截图页面注入 <base href="http://127.0.0.1/">,并通过 page.route 拦截所有请求,仅放行 about:blank、data: 及本插件查看器资产路径(从 getServedViewerAsset 本地供给),其余一律 abort——渲染过程不依赖外网。
  • PNG 尺寸保护:截图前估算裁剪区域的物理像素数(CSS 尺寸 × dpr²),超过 maxPixels 时先尝试自动降低 deviceScaleFactor 重试(最多 2 次),仍超限则抛出 Diff frame did not render within image size limits.。裁剪坐标会对齐设备像素网格以避免亚像素裁切导致的文字发虚(见 browser.ts)。
  • PDF 输出:PDF 路径先按参考页高 1056px 估算页数,超过 50 页(MAX_PDF_PAGES)或超过 maxPixels 时快速失败;随后清除页面背景/边距、printBackground: true 输出精确尺寸的 PDF(browser.ts)。测试 “fails fast when PDF render exceeds size limits” 覆盖了该路径。
  • 失败信息可操作:任何渲染异常都会被包装为 Diff PNG/PDF rendering requires a Chromium-compatible browser. Set browser.executablePath or install Chrome/Chromium. <原因>,直接告诉运维如何修复。

六、网关托管的查看器:URL 构造与资产服务

查看器由网关本地托管在 /plugins/diffs/... 路径下(README Notes)。URL 构造逻辑在 url.ts:

  • 默认使用 loopback:http(s)://127.0.0.1:<port>,端口取 gateway.port,缺省 18789,gateway.tls.enabled 时升级为 https。注释解释了原因——viewer 链接由本地 canvas/客户端使用,loopback 可避开容器/桥接网卡上经常不可达的接口;
  • 若配置 gateway.bind=custom 且设置了 gateway.customBindHost,则使用 http(s)://<customBindHost>:<port>;
  • 工具入参 baseUrl 可覆盖以上规则(必须是合法 http/https URL 且不带 query/hash),basePath 会被正确拼接(例如 https://gateway.example.com/base 会产出 .../base/plugins/diffs/view/<id>/<token>)。

config.test.ts 中 “defaults to loopback for lan/tailnet bind modes”、“uses custom bind host when provided”、“rejects base URLs with query/hash” 三个用例锁定了这些行为。

查看器前端资产(viewer-assets.ts)采用“稳定 loader + 哈希版 runtime”的缓存策略:/plugins/diffs/assets/viewer.js 是动态生成的一行 import,指向 /plugins/diffs/assets/viewer-runtime.js?v=<sha1前12位>;runtime 本体是 viewer-client.ts 经 bun build 打包到 assets/viewer-runtime.js 的产物(构建脚本见 package.json 的 build:viewer),按 mtime 做内存缓存。这样 runtime 更新后无需清理客户端缓存即可生效。

七、工件生命周期:临时目录、TTL 与清理

工件是临时性的(ephemeral),存储在插件临时子目录 $TMPDIR/openclaw-diffs——index.ts 中 store 根目录为 path.join(resolvePreferredOpenClawTmpDir(), "openclaw-diffs")。每个工件一个以 id 命名的目录,内含:

  • viewer.html:交互式查看器文档(仅 view/both 模式创建);
  • meta.json:查看器工件元数据(id、token、createdAt、expiresAt、viewerPath、htmlPath、context、可选 filePath);
  • preview.png / preview.pdf:文件渲染产物;
  • file-meta.json:file 模式独立工件的元数据(结构见 store.ts)。

生命周期参数(store.ts):

  • 默认 TTL 30 分钟(DEFAULT_TTL_MS),上限 6 小时(MAX_TTL_MS,对应工具入参 ttlSeconds 的最大值 21600);
  • 清理节流:默认每 5 分钟最多一次扫描(DEFAULT_CLEANUP_INTERVAL_MS),到期工件连同目录删除;
  • 兜底:无元数据可读的孤儿目录按 mtime 超过 24 小时(SWEEP_FALLBACK_AGE_MS)清理。

过期判定发生在读时与扫描时:getArtifact 校验 id+token 均匹配且未过期,过期即删并返回 null(HTTP 层对外统一为 Diff not found or expired),测试 “expires artifacts after the ttl” 验证了 TTL 行为,both 模式下 details.expiresAt 也来自这里。

八、实战:四类 Agent 提示词

README 给出了四类可直接复用的提示词。canvas 展示:

Use the `diffs` tool in `view` mode for this before and after content, then open the returned viewer URL in the canvas.

Path: docs/example.md

Before:
# Hello

This is version one.

After:
# Hello

This is version two.

渲染文件(PNG 或 PDF):

Use the `diffs` tool in `file` mode for this before and after input. After it returns `details.filePath`, use the `message` tool with `path` or `filePath` to send me the rendered diff file.

Path: README.md

Before:
OpenClaw supports plugins.

After:
OpenClaw supports plugins and hosted diff views.

两者都要:

Use the `diffs` tool in `both` mode for this diff. Open the viewer in the canvas and then send the rendered file by passing `details.filePath` to the `message` tool.

Path: src/demo.ts

Before:
const status = "old";

After:
const status = "new";

patch 输入:

Use the `diffs` tool with this unified patch in `view` mode. After it returns the viewer URL, present it in the canvas.

diff --git a/src/example.ts b/src/example.ts
--- a/src/example.ts
+++ b/src/example.ts
@@ -1,3 +1,3 @@
 export function add(a: number, b: number) {
-  return a + b;
+  return a + b + 1;
 }

companion skill 的文本(SKILL.md)与系统提示注入的指引(prompt-guidance.ts)还强调了两点实践:投递渲染文件时不要依赖工具结果自带的渲染器,而应显式调用 message 工具并传 details.filePath;若用户已配置插件默认值,除非要针对本次 diff 覆盖,否则应省略 mode、theme、layout 等呈现参数。

九、运维与使用注意事项

汇总 README “Notes” 一节并结合源码,部署与使用时的关键约束:

  • 查看器由网关本地托管在 /plugins/diffs/... 下(HTTP 路由以 auth: "plugin" 前缀匹配注册);
  • 工件是临时的,存放于插件临时子目录($TMPDIR/openclaw-diffs),依赖 TTL 自动回收,不要把它当作持久存储;
  • 默认 viewer URL 使用 loopback(127.0.0.1),除非设置了 baseUrl 入参,或配置了 gateway.bind=custom + gateway.customBindHost;
  • 远程 viewer 未命中会被限流,用于降低 token 猜测攻击面(60 秒窗口 40 次失败锁定 60 秒);
  • PNG/PDF 渲染依赖 Chromium 兼容浏览器;自动探测不够时设置 browser.executablePath(探测顺序:配置 → 三个环境变量 → PATH → 平台常见路径);
  • 若投递频道会重度压缩图片(如 Telegram、WhatsApp),优先使用 fileFormat: "pdf" 以保持可读性;
  • patch 输入下 N unmodified lines 折叠行不一定带展开控件,因为许多 patch hunk 不携带完整的可展开上下文数据——这与 expandUnchanged 仅按调用生效、patch 输入缺少完整文件上下文的事实一致;
  • diff 渲染由 Diffs 库驱动(对应依赖 @pierre/diffs,含 SSR 预渲染接口)。

十、小结

@openclaw/diffs 用单一 diffs 工具同时覆盖了“给人看”(网关托管交互查看器 + canvas)与“给频道发”(PNG/PDF 文件工件)两类 diff 展示需求。从源码结构看,它的可靠性来自几个可验证的约束:输入侧的字节数与 patch 规模上限、配置侧的钳制式默认值解析、安全侧的 loopback 默认 + 168 位随机令牌 + 远程失败限流 + CSP 响应头、渲染侧的像素预算与浏览器空闲回收,以及存储侧的 TTL 工件生命周期与路径逃逸防护。相关实现与测试集中在 extensions/diffs/ 目录,可作为插件如何同时注册 agent tool、HTTP 路由与 system-prompt 钩子的完整参考样本。

登录后查看全文
openclaw-zero-token