本页内容
本页内容
工具
差异
diffs 是一个可选插件工具,可将 before/after 文本或统一补丁转换为只读差异工件。它还将简短的代理指导添加到系统提示中,并提供配套技能以提供更完整的说明。
输入:before + after 文本,或一个统一的 patch(二者互斥)。
输出:用于浏览器演示的网关查看器 URL、用于消息传递的渲染 PNG/PDF 文件路径,或两者兼而有之。
Control UI 已经突出显示了没有此插件的内联工具差异和会话差异。当客服人员需要独立查看器链接或其他频道的渲染附件时,请安装 diffs。
快速开始
安装插件
安装自动应用于正在运行的网关;否则下次启动时生效。请参阅 应用更改并检查 。
diffs其语言包作为单独的包提供,而不是与OpenClaw,因此安装需要一个作用域定位器。这clawhub:前缀选择ClawHub的副本@openclaw/diffs。使用npm:@openclaw/diffs安装自npm反而。
启用插件
选择一种模式
看法
浏览器流程:代理使用 mode: "view" 调用 diffs 并在浏览器中打开 details.viewerUrl。
文件
聊天文件传送:座席使用 mode: "file" 呼叫 diffs,并使用 path 或 filePath 发送 details.filePath 和 message。
两个都
组合模式(默认):代理调用 diffs 时使用 mode: "both",一次调用即可同时获取两种产物。
禁用内置系统指导
要保留该工具但去掉前置的系统提示指导,请将 plugins.entries.diffs.hooks.allowPromptInjection 设置为 false:
这会阻止该插件的 before_prompt_build 钩子,同时保留工具和技能可用。要同时禁用指导和工具,请改为禁用该插件。
工具输入参考
除非另有说明,所有字段都是可选的。
beforestring原文。当省略 patch 时,需要使用 after。
afterstring更新了文字。当省略 patch 时,需要使用 before。
patchstring统一 diff 文本。与 before 和 after 互斥。
pathstringbefore/after 模式的显示文件名。
langstringbefore/after 模式的语言覆盖提示。默认查看器设置之外的未知值和语言将回退为纯文本,除非安装了 Diffs 语言包插件。
titlestring查看器标题覆盖。
mode"view" | "file" | "both"输出模式。默认使用插件默认值 defaults.mode(both)。已弃用别名:"image" 的行为与 "file" 完全相同。
theme"light" | "dark"查看器主题。默认使用插件默认值 defaults.theme。
layout"unified" | "split"diff 布局。默认使用插件默认值 defaults.layout。
expandUnchangedboolean当完整上下文可用时展开未更改部分。仅限每次调用的选项(不是插件默认键)。
fileFormat"png" | "pdf"渲染文件格式。默认使用插件默认值 defaults.fileFormat。
fileQuality"standard" | "hq" | "print"PNG/PDF 渲染的质量预设。
fileScalenumber设备缩放覆盖值(1-4)。
fileMaxWidthnumberCSS 像素中的最大渲染宽度(640-2400)。
ttlSecondsnumberdefault: 1800查看器和独立文件输出的 Artifact 存活时间(TTL),单位为秒。最大值 21600。
baseUrlstring查看器 URL 原点覆盖。覆盖插件 viewerBaseUrl。必须是 http 或 https,不是 query/hash.
验证和限制
before/after:每个最大 512 KiB。patch:最大 2 MiB。path:最大 2048 字节。lang:最大 128 字节。title:最大 1024 字节。- 补丁复杂度上限:最多 128 个文件和 120000 行总数。
patch与before/after同时提供将被拒绝。- 渲染文件安全限制(PNG 和 PDF):
fileQuality: "standard":最大 8 MP(8,000,000 个渲染像素)。fileQuality: "hq":最大 14 MP。fileQuality: "print":最大 24 MP。- PDF 也最多限制为 50 页。
语法高亮
内置语言:
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 等)会规范化为这些语言。
安装更多语言的 Diffs 语言包插件(Astro、Vue、Svelte、MDX、GraphQL、Terraform/HCL、Nix、Clojure、Elixir、Haskell、OCaml、Scala、Zig、Solidity、Verilog/VHDL、Fortran、MATLAB、 LaTeX、美人鱼、Sass/Less/SCSS、Nginx、Apache、CSV、dotenv、INI、diff 等):
没有该语言包时,不受支持的语言仍会以可读的纯文本形式渲染。有关上游目录,请参见 Diffs Language Pack 插件 和 Shiki 语言。
输出详情契约
所有成功结果都包括 changed:相同的 before/after 输入返回 false,而不创建工件。渲染结果返回true。
查看器字段(视图和两种模式)
changedartifactIdviewerUrlviewerPathtitleexpiresAtinputKindfileCountmodecontext(在可用时包含agentId、sessionId、messageChannel、agentAccountId)
文件字段(文件和两种模式)
changedartifactIdexpiresAtfilePathpath(与filePath相同的值,用于 message 工具兼容性)fileBytesfileFormatfileQualityfileScalefileMaxWidth
| 模式 | 返回内容 |
|---|---|
"view" |
仅返回查看器字段。 |
"file" |
仅返回文件字段,不返回查看器工件。 |
"both" |
返回查看器字段和文件字段。如果文件渲染失败,查看器仍会返回,并附带 fileError。 |
折叠的未更改部分
查看器显示类似 N unmodified lines 的行。仅当渲染的差异具有可扩展上下文数据(通常用于 before/after 输入)时,扩展控件才会出现。许多统一补丁在其块中省略了上下文主体。然后,该行可以在没有展开控件的情况下出现。这是预期的,不是错误。 expandUnchanged 仅在可扩展上下文存在时适用。
多文件导航
涉及多个文件的补丁从更改文件摘要卡开始。该卡显示:
+N/-N总数- 每个文件计数
- 添加、删除和重命名徽章
- anchor 跳转到每个文件的链接
渲染的 PNG/PDF 文件保留每个文件的标头计数。他们放弃了交互式视图切换,因为这些是静态文件中的死控件。
插件默认值
在 ~/.openclaw/openclaw.json 中设置插件级默认值:
支持的 defaults 键:fontFamily、fontSize、lineSpacing、layout、showLineNumbers、diffIndicators、wordWrap、background、theme、fileFormat、fileQuality、fileScale、fileMaxWidth、mode、ttlSeconds。显式传入的工具调用参数会覆盖这些默认值。
持久化查看器 URL 配置
viewerBaseUrlstring当工具调用未通过 baseUrl 时,插件拥有的后备返回查看器链接。必须是 http 或 https,不是 query/hash.
安全配置
security.allowRemoteViewerbooleandefault: falsefalse:对 viewer 路由的非回环请求将被拒绝。true:如果带 token 的路径有效,则允许远程 viewer。
资源生命周期和存储
- Viewer HTML 和元数据位于 Diffs 插件 blob 命名空间下的共享
state/openclaw.sqlite数据库中。 HTML 采用 gzip 压缩。 SQLite 仅存储随机 URL 令牌的 SHA-256 哈希值,而不是令牌本身。 - 渲染的PNG/PDF文件在
$TMPDIR/openclaw-diffs下保留临时实现,因为通道传送需要文件路径。 SQLite 拥有其到期元数据。 OpenClaw 不写入 JSON sidecar。 - 默认制品 TTL:30 分钟。可接受的最大 TTL:6 小时。
- 清理会在每次 artifact create 调用后机会性运行。首先删除已过期的 SQLite 行,然后删除任何对应的 PNG/PDF 目录。
- 兜底扫描会移除超过 24 小时且没有对应数据库行的临时文件夹。旧版
meta.json、file-meta.json和viewer.html缓存不会被导入或读取。
查看器 URL 和网络行为
查看器路由:/plugins/diffs/view/{artifactId}/{token}
查看器资源:
/plugins/diffs/assets/viewer.js/plugins/diffs/assets/viewer-runtime.js/plugins/diffs-language-pack/assets/viewer.js(仅当 diff 使用语言包语言时)
查看器文档相对于查看器 URL 解析这些资源。因此,可选的 baseUrl 路径前缀也适用于资产请求。
URL 解析顺序:工具调用的 baseUrl(严格验证后)-> 插件的 viewerBaseUrl -> gateway.publicOrigin -> 现有的绑定感知 Gateway 后备值。
baseUrl规则:
- 方案必须是
http://或https://。 - A
baseUrl携带查询字符串或哈希值被拒绝。 - 允许源加上可选的基本路径。
安全模型
观察者硬化
- 默认仅允许回环访问。
- 带令牌的查看器路径,并对 ID 和令牌模式进行严格验证。
- 查看者响应 CSP:
default-src 'none'。脚本和资源仅从自身加载。查看器不发出出站connect-src请求。 - 启用远程访问时远程未命中限制:每 60 秒 40 次失败会触发 60 秒锁定 (
429 Too Many Requests)。
文件渲染强化
- 截图浏览器请求路由采用默认拒绝策略。
- 仅允许来自
http://127.0.0.1/plugins/diffs/assets/*的本地 viewer 资源。 - 外部网络请求被阻止。
文件模式的浏览器要求
mode: "file" 和 mode: "both" 需要 Chromium- 兼容的浏览器。
解析顺序:
配置
OpenClaw 配置中的 browser.executablePath。
环境变量
OPENCLAW_BROWSER_EXECUTABLE_PATHBROWSER_EXECUTABLE_PATHPLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH
平台回退
Chrome、Chromium、Edge 和 Brave 的常见安装路径,以及 PATH 查找。
常见失败信息:Diff PNG/PDF rendering requires a Chromium-compatible browser...。可以通过安装 Chrome、Chromium、Edge 或 Brave,或者设置上述任一可执行文件路径选项来解决。
故障排查
输入验证错误
Provide patch or both before and after text.-- 请同时提供before和after,或者提供patch。Provide either patch or before/after input, not both.-- 不要混合使用输入模式。Invalid baseUrl: ...-- 使用具有可选路径的http(s)原点,无 query/hash.{field} exceeds maximum size (...)-- 减少负载大小。- Large patch rejection -- 减少 patch 文件数量或总行数。
观众可访问性
- 默认情况下,Viewer URL 解析为
127.0.0.1。 - 如需远程访问,请设置
gateway.publicOrigin、设置插件的viewerBaseUrl,或按次调用传入baseUrl。 gateway.trustedProxies可以包括同一主机代理(例如 Tailscale Serve)的环回。然后,没有转发 client-IP 标头的原始环回查看器请求将被设计拒绝。- 对于该代理拓扑,首选
mode: "file"/"both"作为附件。对于可共享的查看器链接,请有意启用security.allowRemoteViewer以及插件viewerBaseUrl/a 代理baseUrl。 - 仅当确实需要外部查看器访问时,才启用
security.allowRemoteViewer。
未找到文物
- 制品因 TTL 过期。
- Token 或路径已更改。
- 清理操作移除了过期数据。
操作指南
- 首选
mode: "view"在浏览器中进行本地交互式评论。 - 需要附件的外部聊天频道中,优先使用
mode: "file"。 - 保持
allowRemoteViewer禁用,除非您的部署需要远程查看器 URL。 - 对于敏感差异,请设置明确且较短的
ttlSeconds。 - 在不需要时,避免在差异输入中发送密钥。
- 如果你的频道会对图片进行强压缩(例如 Telegram 或 WhatsApp),请优先使用 PDF 输出(
fileFormat: "pdf")。
相关内容
- 浏览器
- 插件
- 工具概览
apply_patch— 生成这些编辑的工具