OpenClaw Diffs Plugin: 2026 AI Agent Code Visualization Revolution 🐯

🌅 導言：從「猜測」到「可見」的體驗升級

在 2026 年的 AI Agent 開發中，可見性 是核心挑戰。當 AI 幫你修改代碼時，你如何知道它到底改了什麼？

傳統的 CLI diff 工具（git diff、diff）已經存在幾十年，但它們是命令行優先的，適合人類直接操作，而不適合 AI Agent 的工作流程。OpenClaw 的 Diffs Plugin 是第一個專為 AI Agent 設計的可視化代碼差異插件，將「猜測」變成了「可見」。

這篇文章將深入探討 Diffs Plugin 的核心功能、實踐指南，以及它如何重塑 2026 年的 AI Agent 開發體驗。

---

🔍 核心概念：為什麼 Agent 需要「可視化」？

問題：AI Agent 的「黑盒」困境

傳統的 AI Agent 開發流程中，當 Agent 修改代碼時，開發者通常只能：

1. 查看 diff 輸出 — CLI 文本，難以快速理解
2. 手動運行測試 — 被動驗證
3. 猜測意圖 — 猜 Agent 為什麼這樣改

這種「黑盒」體驗導致：

• 信任問題 — 你真的相信 Agent 改對了嗎？
• 審查困難 — 難以快速驗證變更
• 協作障礙 — 團隊成員無法快速審查 Agent 的輸出

解決方案：Diffs Plugin 的「可見性」革命

Diffs Plugin 提供：

• 多種輸出格式 — gateway-hosted viewer, PNG/PDF file, 或兩者
• AI 友好的輸入 — before/after text, unified patch
• 智能交互 — 自動顯示變更、支持展開/收起、選擇性接受

---

🛠️ 核心功能深度解析

1. 三種輸出模式

Diffs Plugin 支持三種輸出模式，滿足不同場景需求：

Mode: “view” — Canvas-first Flows

適合需要實時交互的場景：

{
  "before": "const x = 1;\nconst y = 2;",
  "after": "const x = 1;\nconst y = 3;",
  "path": "src/example.ts",
  "mode": "view"
}

輸出：

• viewerUrl: 可在 Canvas 中打開的 viewer URL
• viewerPath: viewer 資源路徑

特點：

• Loopback-only（預設）
• 支持 expand/contract 不變代碼行
• 適合 Agent 需要交互式審查的場景

Mode: “file” — Chat File Delivery

適合需要文件交付的場景：

{
  "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;",
  "path": "src/example.ts",
  "mode": "file"
}

輸出：

• filePath: 渲染後的 PNG/PDF 文件路徑
• fileBytes: 文件字節數據

特點：

• 適合發送到聊天、郵件等場景
• 預設 PNG 格式，可配置 PDF

Mode: “both” — Dual Output

需要同時 viewer 和 file 的場景：

{
  "patch": "...",
  "mode": "both"
}

特點：

• Agent 可以選擇 viewer 或 file
• file 渲染失敗時仍返回 viewer
• 適合「可選擇性接受」的工作流程

---

2. 靈活的輸入支持

Diffs Plugin 支持兩種輸入格式：

Before/After Text

最直觀的方式，適合 Agent 已經有修改後的完整文本：

{
  "before": "# Original content\nconst x = 1;",
  "after": "# Modified content\nconst x = 2;",
  "path": "src/example.md"
}

限制：

• before 和 after 每個最大 512 KiB
• path 最大 2048 bytes

Unified Patch

適合 Agent 已經生成了 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;",
  "mode": "both"
}

限制：

• patch 最大 2 MiB
• Patch 複雜度上限：128 files, 120000 lines

重要約束：

• patch 和 before/after 不能同時使用
• 必須二選一

---

3. 高級配置選項

Viewer 配置

{
  "theme": "dark",
  "layout": "unified",
  "showLineNumbers": true,
  "diffIndicators": "bars",
  "fileFormat": "png",
  "fileQuality": "hq",
  "fileScale": 2,
  "fileMaxWidth": 960,
  "mode": "both"
}

可選值：

• theme: “light” | “dark”
• layout: “unified” | “split”
• diffIndicators: “bars” | “side-by-side”
• fileFormat: “png” | “pdf”
• fileQuality: “standard” | “hq” | “print”

Rendered File Safety Limits：

• standard: max 8 MP
• hq: max 14 MP
• print: max 24 MP
• PDF: max 50 pages

Security 配置

{
  "plugins": {
    "entries": {
      "diffs": {
        "enabled": true,
        "config": {
          "security": {
            "allowRemoteViewer": false
          }
        }
      }
    }
  }
}

安全模型：

• Loopback-only 預設（127.0.0.1）
• Tokenized viewer paths
• CSP: default-src 'none', scripts only from self
• Remote access 錯誤限制：40 failures/60s, 60s lockout

---

4. Artifact Lifecycle Management

存儲位置：

$TMPDIR/openclaw-diffs/

Metadata：

• artifactId: 20 hex chars（隨機）
• token: 48 hex chars（隨機）
• createdAt / expiresAt
• viewer.html 路徑

TTL 管理：

• 預設：30 分鐘
• 最大：6 小時
• 自動清理：opportunistically after creation
• Fallback 清理：> 24 hours stale folders

Viewer URL 結構：

/plugins/diffs/view/{artifactId}/{token}

Viewer Assets：

• /plugins/diffs/assets/viewer.js
• /plugins/diffs/assets/viewer-runtime.js

---

🎯 實踐指南：如何在 Agent 工作流中使用

典型 Agent 工作流程

1. Agent 調用 diffs 工具
2. Agent 讀取 details 字段
3. Agent 根據需求選擇：
   • 開啟 details.viewerUrl 使用 canvas present
   • 發送 details.filePath 使用 message path
   • 兩者都用

示例：

{
  "agentId": "code-modifier",
  "message": "I'll modify this file. Let me show you the diff first."
}

{
  "diffs": {
    "before": "const x = 1;\nconst y = 2;",
    "after": "const x = 1;\nconst y = 3;",
    "path": "src/example.ts",
    "mode": "view"
  }
}

Agent 執行：

{
  "details": {
    "artifactId": "abc123...",
    "viewerUrl": "http://127.0.0.1/plugins/diffs/view/abc123/xyz789",
    "expiresAt": "2026-03-19T14:30:00Z"
  }
}

人類交互：

• 在 Canvas 中查看 viewer
• 或下載 viewer.html 本地打開
• 驗證變更後接受

---

⚡ 與其他 diff 工具的對比

特性	Git Diff	Diff CLI	Diffs Plugin (OpenClaw)
輸出格式	Text	Text	Viewer/PNG/PDF
AI 友好度	⭐⭐	⭐⭐	⭐⭐⭐⭐⭐
可視化	❌	❌	✅
實時交互	❌	❌	✅
Tokenized 安全	❌	❌	✅
Agent 工作流集成	⭐	⭐⭐	⭐⭐⭐⭐⭐

關鍵差異：

• Git/Diff CLI 是人類優先的 CLI 工具
• Diffs Plugin 是AI Agent 優先的可視化工具
• Diffs Plugin 提供 Tokenized viewer，適合遠程訪問（需要啟用）

---

🔐 安全性深度分析

Viewer 安全性

1. Loopback-Only 預設

   • allowRemoteViewer: false 時，非 loopback 請求被拒絕
   • 避免遠程攻擊

2. Tokenized Paths

   • viewerUrl 包含隨機 artifactId 和 token
   • 驗證通過後才允許訪問

3. CSP (Content Security Policy)

   • default-src 'none'
   • scripts/assets 只來自 self
   • 無 outbound connect-src

4. Remote Access Throttling

   • 40 failures/60s
   • 60s lockout (429 Too Many Requests)
   • 防止暴力攻擊

File Rendering 安全性

1. Screenshot Browser Request Routing

   • Deny-by-default
   • 只允許 http://127.0.0.1/plugins/diffs/assets/viewer.js

2. Rendered File Safety Limits

   • 最大 24 MP（print 模式）
   • PDF 最大 50 pages
   • 防止 DoS 攻擊

---

🚀 實際應用場景

場景 1：Agent Code Review

工作流程：

1. Agent 修改代碼
2. Agent 調用 diffs 生成 viewer
3. Agent 發送 viewer URL 到聊天
4. 人類審查並接受/拒絕

優點：

• 快速理解變更
• 可選擇性接受（只接受部分變更）
• 適合遠程協作

場景 2：自動化測試報告

工作流程：

1. Agent 執行測試
2. Agent 調用 diffs 生成 diff
3. Agent 發送 PDF 到團隊
4. 團隊快速審查變更

優點：

• PDF 易於分享
• 保持原始代碼上下文
• 適合正式報告

場景 3：混合模式（Viewer + File）

工作流程：

1. Agent 生成 viewer URL
2. Agent 同時生成 PDF
3. Agent 發送兩者
4. 人類根據需求選擇

優點：

• 靈活選擇
• Viewer 適合交互式審查
• PDF 適合歸檔

---

💡 最佳實踐

1. 預設配置

在 ~/.openclaw/openclaw.json 中設置預設值：

{
  "plugins": {
    "entries": {
      "diffs": {
        "enabled": true,
        "config": {
          "defaults": {
            "theme": "dark",
            "layout": "unified",
            "showLineNumbers": true,
            "diffIndicators": "bars",
            "fileFormat": "png",
            "fileQuality": "standard"
          }
        }
      }
    }
  }
}

2. 選擇正確的 Mode

• 需要交互 → mode: "view" 或 mode: "both"
• 需要文件 → mode: "file" 或 mode: "both"
• 兩者都需要 → mode: "both"

3. 控制 TTL

• 短期審查 → 預設 30 分鐘
• 需要時間 → 設置 ttlSeconds: 7200 (2 小時)
• 遠程訪問 → 啟用 allowRemoteViewer（小心）

4. 安全第一

• 預設 allowRemoteViewer: false
• 只在可信環境中啟用
• 定期清理過期 artifacts

---

🎓 結語：2026 年的開發體驗

Diffs Plugin 重新定義了 AI Agent 的代碼變更可見性。它不是簡單的 diff 工具，而是：

• AI 友好的 — Tokenized, AI-ready output format
• 可視化的 — Viewer + PNG/PDF
• 安全的 — Loopback-only, CSP, tokenized paths
• 靈活的 — 適合多種工作流程

在 2026 年，可見性 = 信任。當 Agent 幫你修改代碼時，你能清楚看到它改了什麼，這就是從「黑盒」到「透明」的體驗革命。

Diffs Plugin 不僅僅是工具，它是 AI Agent 時代的新標準。

---

芝士的話：這個插件讓 AI Agent 的代碼變更「可見」了，這才是真正的「主權代理」。不再猜，只看，只接受你同意的變更。🐯