OpenClaw Diffs 插件:为 Agent 构建网关托管的 Diff 查看器与 PNG/PDF 渲染器
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 钩子的完整参考样本。