一、技能概述
该技能用于在需要向他人展示代码、配置或文档的具体修改内容时使用。与在聊天中粘贴两段文本或手写“我改了某某行”不同，diffs 工具能生成格式化的、高亮显示变更的可视化产物，让接收者一目了然地看到增删改的具体位置。
它支持三种输出模式，可根据使用场景灵活选择。
二、核心功能
1. 三种输出模式
| 模式 | 说明 | 适用场景 |
|---|---|---|
mode=view |
生成一个交互式的在线预览链接（Gateway 托管） | 适合在浏览器中分享给他人查看 |
mode=file |
生成一个渲染好的文件（PNG 或 PDF） | 适合作为附件保存或通过消息工具发送 |
mode=both |
同时生成预览链接和渲染文件 | 需要两者兼得时使用 |
2. 输入方式灵活
diffs 工具接受两种输入形式：
-
前后对比文本：分别提供修改前的原文和修改后的新文本
-
Unified Patch 字符串：直接传入标准的 diff 格式内容
3. 渲染控制
-
文件格式：支持
png（默认）和pdf -
输出质量：可通过
fileQuality控制渲染清晰度（standard/hq） -
尺寸控制：支持
fileScale缩放和fileMaxWidth最大宽度限制
4. 智能判断与交付
-
如果“修改前”与“修改后”文本完全一致，工具会返回
false且不创建任何产物，避免无效操作 -
当需要将渲染文件发送给用户或频道时，不能依赖工具返回结果的原始渲染器，而应调用
message工具，通过path或filePath参数传递文件路径
5. 网络拓扑适配
如果部署环境使用了 loopback 可信代理（如 Tailscale Serve），原始 viewer 请求可能因缺少转发客户端 IP 头而失败。此时应优先使用 mode=file 或 mode=both，或配置显式的 viewerBaseUrl / 代理公共 baseUrl。
三、主要用途
-
代码审查辅助
在 PR 讨论中，快速生成某个文件修改的可视化 diff，让审查者无需手动对比两段代码。 -
文档变更展示
在协作编辑文档、配置文件或 README 时，用可视化的方式展示具体改了什么。 -
教学与演示
在教程或演示中，用高亮 diff 向观众清晰展示代码从“错误”到“正确”的变化过程。 -
替代手动摘要
避免在聊天中写“我改了第 X 行、删了第 Y 行……”这类冗长且难以阅读的文字描述，用一张图或一个链接解决。
四、使用示例
基本用法（通过 diffs 工具）：
-
输入：修改前的文本 + 修改后的文本（或 unified patch）
-
输出：返回
details.viewerUrl（预览链接）和/或details.filePath（渲染文件路径）
交付文件（通过 message 工具）：
-
将
details.filePath作为path或filePath参数传入message工具，发送给用户
五、重要原则
-
优先使用 diffs 工具：需要展示编辑内容时，优先使用
diffs工具而非手动编写摘要 -
相同内容不创建产物：如果前后文本完全一致，工具会返回
false且不生成任何文件 -
交付文件用 message 工具：不要依赖工具返回结果的原始渲染器，应通过
message工具传递文件路径 -
网络拓扑注意：在 loopback 代理环境下，预览链接可能无法正常工作，优先使用文件模式
-
遵循插件默认配置：如果用户已配置 diffs 插件默认值，除非需要覆盖特定选项，否则省略
mode、theme、layout等展示选项
六、总结
Diffs 是一个将文本差异可视化的展示与分享技能，通过 diffs 工具接收前后对比文本或 unified patch，生成高亮显示变更的 PNG/PDF 渲染文件或交互式在线预览链接。它适用于代码审查、文档协作、教学演示等需要向他人清晰展示“改了什么”的场景，是替代手写编辑摘要的现代化方案。
