小編精選 - 技術文章翻譯 · 04月04日

日誌診斷 Skill：用 AI + MCP 一鍵解決BUG｜得物技术

日志诊断 Skill：用 AI + MCP 一键解决BUG｜得物技術

一、概述

做後端開發，除錯（BUG 定位）有一個讓人頭疼的固定流程：打開日誌平台，輸入 traceId 或關鍵詞，搜尋日誌；從幾十到上百條日誌裡，找到關鍵的那幾條；把日誌裡的類名、方法名複製出來，去 IDE 裡找對應程式碼；結合程式碼邏輯，判斷哪裡出了問題；如果一次找不準，回去再搜日誌，再翻程式碼……

這個過程相對固定，但非常耗時。每次 BUG 定位，光在日誌平台和 IDE 之間來回切換，就能消耗掉大半的時間。

最開始在去年 Q3 想到這個問題時，腦子裡浮現的第一個方案是：用 Cursor + MCP，把日誌平台接進來，再掛一個程式碼知識庫，讓 AI 幫我查日誌。但這個方案有缺陷 —— 日誌查詢是「動態的」，它依賴環境、應用、時間範圍，沒辦法靜態預置。此外，這樣處理沒有辦法做到比較順暢地讀程式碼、改程式碼。

後來開始用 Claude Code，接觸到了 Skill 的概念：可以在專案裡定義一套自定義命令，描述 AI 應該怎麼執行這個命令的每個步驟，於是整個思路變得清晰了。

日誌平台有 MCP，Claude Code 有 Skill，兩者結合，就能讓 AI 自動完成「查日誌 → 找關鍵資訊 → 掃描程式碼 → 定位問題」這整個閉環。然後在 PM 的幫助下，才有了 /log-diagnosis 這個 Skill。

二、日誌平台 MCP 是什麼

MCP 原理

日誌平台推出了基於 MCP（Model Context Protocol）協議的日誌查詢服務，讓 Claude 可以直接調用日誌平台的能力，無需人工在日誌平台上手動查詢。

MCP 本質上是一種標準化的「工具調用協議」，Claude Code 通過 SSE（Server-Sent Events）長連接與 MCP Server 通訊，實時獲取日誌資料。

MCP 環境對照

核心 MCP 工具

鑑權流程

secretKey（日誌平台後台申請）
    ↓ acquireTokenTool
accessToken（1小時有效，最多同時存在5個）
    ↓ 携帶 accessToken
logsQuery / logSqlQuery / countLogTool ...

secretKey 申請地址：進入日誌管理後台 → 日誌權限 → 我的應用 → 生成密鑰。

三、/log-diagnosis Skill 是什麼

Skill 工作原理

log-diagnosis 是一個運行在 Claude Code 裡的自定義診斷命令。Claude Code 支援通過 .claude/skills/ 目錄定義自定義技能（Skill），以 Markdown 檔描述行為規範，Claude 在收到對應命令時會自動加載並執行。你只需要把 traceId 或告警資訊告訴它，剩下的全部交給 AI。完整執行鏈路如下：

使用者輸入 /log-diagnosis {環境} {程式碼分支} {訴求}
    ↓
Claude 加載 .claude/skills/log-diagnosis/SKILL.md
    ↓
讀取 .diagnosis/config.json 獲取當前環境配置
    ↓
檢查 accessToken 是否過期，過期則自動刷新
    ↓
從 traceId 計算日誌時間範圍（取第9-16位16進制時間戳）
    ↓
調用日誌平台 MCP 分頁拉取全量日誌（最多20頁，不遺漏）
    ↓
切換到指定程式碼分支，結合日誌關鍵詞檢索程式碼
    ↓
綜合分析：上游日誌 + 當前服務日誌 + 程式碼邏輯 → 根因
    ↓
生成診斷報告（飛書文件 or 本地 Markdown）
    ↓
恢復原始程式碼分支

兩種診斷入口

核心能力

Token 自動管理：accessToken 過期自動刷新，無需手動維護；
分頁全量拉取：自動分頁拉完所有日誌，禁止只查第一頁就下結論（最多 20 頁）；
跨服務分析：自動識別上下游服務，拉取關聯服務日誌交叉驗證；
程式碼聯動：日誌裡出現的類名/方法名，直接在程式碼裡精確定位。

queryString 語法規則

# 格式
{field} {操作符} "{值}" {連接符} {field} {操作符} "{值}"
# 操作符
=  : 精確匹配
≈  : 模糊匹配（like）
# 連接符
AND / OR / NOT
# 範例
trace_id = "a1b2c3d4e5f6789012345678abcdef01"
trace_id = "xxx" AND log_level = "ERROR"
endpoint ≈ "/api/your-endpoint" AND log_level = "ERROR"
message ≈ "timeout"

注意：時間範圍只通過 start/end 參數控制，不要寫在 queryString 中。

四、安裝與配置

安裝日誌平台 MCP

Claude Code

在 Claude Code 命令列中執行，按需安裝對應環境：

# 測試環境
claude mcp add --transport sse dw-log-mcp-t1 https://{your-t1-aigw-domain}/api/v1/mcp/log-mcp/sse
# 預發環境
claude mcp add --transport sse dw-log-mcp-pre https://{your-pre-aigw-domain}/api/v1/mcp/log-mcp/sse
# 生產環境
claude mcp add --transport sse dw-log-mcp-prd https://{your-prd-aigw-domain}/api/v1/mcp/log-mcp/sse

安裝後重啟 Claude Code，執行 /mcp 確認連線狀態正常。

Cursor

打開 Cursor Setting；
點擊 Tools & MCP，添加 MCP Server；
添加 URL，MCP Server 名稱任意。

建議按需安裝 MCP Server，避免額外消耗 token，示例配置：

{
  "mcpServers": {
    "dw-log-mcp-t1": {
      "url": "https://{your-t1-aigw-domain}/api/v1/mcp/log-mcp/sse"
    },
    "dw-log-mcp-pre": {
      "url": "https://{your-pre-aigw-domain}/api/v1/mcp/log-mcp/sse"
    },
    "dw-log-mcp-prd": {
      "url": "https://{your-prd-aigw-domain}/api/v1/mcp/log-mcp/sse"
    },
    "dw-log-mcp-oversea-prd": {
      "url": "https://{your-oversea-aigw-domain}/api/v1/mcp/log-mcp/sse"
    }
  }
}

返回設定，就可以看到已經連上。

安裝 /log-diagnosis Skill

將 log-diagnosis 目錄放到專案的對應目錄下：

Claude Code

your-project/
└── .claude/
    └── skills/
        └── log-diagnosis/
            ├── SKILL.md        # 技能行為規範（核心）
            ├── README.md       # 使用說明
            └── reference.md    # 附錄：時間腳本、queryString 範例等

Cursor

your-project/
└── .cursor/
    └── skills/
        └── log-diagnosis/
            ├── SKILL.md        # 技能行為規範（核心）
            ├── README.md       # 使用說明
            └── reference.md    # 附錄：時間腳本、queryString 範例等

配置 .diagnosis/config.json

首次執行會自動引導建立（直接呼叫 /log-diagnosis，Skill 會一步步指示你給出 secret key），也可手動在專案根目錄建立 .diagnosis/config.json。

字段說明：

secretKey：唯一需要人工填寫的字段，在日誌平台後台申請；

accessToken：首次使用時由 AI 自動調用 acquireTokenTool 獲取，過期自動刷新；

accessTokenExpireAt：從 acquireTokenTool 返回值自動填充；

fields：調用 logFields 工具自動獲取。

五、使用方式

命令格式：

/log-diagnosis {環境} {程式碼分支（可選）} {訴求描述}

參數說明：

{環境}：T1 / PRE / PRD（按實際環境標識填寫）；
{程式碼分支}：可選，留空則使用當前分支；
{訴求描述}：包含 traceId 或告警資訊的問題描述，用自然語言書寫即可。

範例：

# 用 traceId 定位介面異常
/log-diagnosis T1 feature/your-branch trace_id: "your-trace" 為什麼最終沒有返回資料
# 用告警資訊分析錯誤原因
/log-diagnosis PRD master 告警詳情：【介面：YourService/yourMethod】【業務碼：10002000】【業務碼消息：系統異常，請稍後重試】幫我分析問題可能性

一行命令，AI 全程接管，幾分鐘內給出根因分析。

六、實戰案例：一個隱蔽的 SQL BUG

背景

某搜尋介面在測試環境回報沒有返回資料。拿到 traceId，直接執行：

/log-diagnosis T1 feature/your-branch trace_id: "your-trace" 為什麼最終沒有返回資料

← 就這一句話，接下來全部交給 AI。

AI 自動拉取日誌

Skill 觸發後，AI 自動完成：

從 traceId 推算出日誌時間範圍（2026-02-27 全天）；
檢查 accessToken 已過期，自動刷新；
調用日誌平台 MCP，分 2 頁拉取完整日誌，共 73 條。

請求入參（從日誌自動提取）：

{
  "assembleByOrg": true,
  "channelType": "MANUAL",
  "orderNo": "your-order-no",
  "status": 1,
  "ticketNo": "your-ticket-no"
}

AI 還原完整調用鏈路

AI 自動識別出關鍵節點：resultList is empty，SQL 查詢返回了空結果。問題在 DB 層，而不在業務邏輯層。

AI 提取組裝後的查詢 DTO

從日誌中提取到 toSearchDTO 組裝結果：

{
  "channelType": "MANUAL",
  "customerTag": 1,
  "deliveryMode": "某配送方式",
  "orderStatus": "8010",
  "orderType": "0",
  "productCategoryIds": [29],
  "status": 1,
  "ticketSource": 67,
  "ticketTypeId": 5802
}

AI 從日誌中提取實際執行的 SQL 發現根因

ORM 框架在日誌中打印了實際執行的 SQL，AI 直接讀取並分析：

SELECT a.id, a.pid, a.name, a.mode, a.status, a.org_id, a.org_ids,
       a.ticket_group_id, a.tenant_id, a.is_del, a.channel_types
FROM your_type_table a
LEFT JOIN your_relation_table b
    ON b.tenant_id = 1 AND a.id = b.type_id AND b.type = 3 AND b.is_del = 0
WHERE a.tenant_id = 1 AND a.mode = 2 AND a.is_del = 0
  AND a.status = 1
  AND (a.channel_types IS NULL OR a.channel_types = '' OR FIND_IN_SET('MANUAL', a.channel_types) > 0)
  AND (b.root_id is null or b.root_id in (29))
  AND (a.order_types IS NULL OR a.order_types = '' OR FIND_IN_SET('0', a.order_types) > 0)
  AND (a.order_statuses IS NULL OR a.order_statuses = '' OR FIND_IN_SET('8010', a.order_statuses) > 0)
  AND (a.delivery_modes IS NULL OR a.delivery_modes = '' OR FIND_IN_SET('某配送方式', a.delivery_modes) > 0)
  AND (a.ticket_sources IS NULL OR a.ticket_sources = '' OR FIND_IN_SET(67, a.ticket_sources) > 0)
  AND (a.customer_tag IS NULL OR a.customer_tag = 1)   ← BUG 在此

AI 發現：其他欄位都處理了 IS NULL 和 = ''（空字串代表「不限制」）兩種情況，唯獨 customer_tag 只判斷了 IS NULL，遺漏了空字串 '' 的情況。

SQL 語義對比：

-- 其他欄位（正確）：IS NULL 和 '' 都處理了
AND (a.order_types IS NULL OR a.order_types = '' OR FIND_IN_SET('0', a.order_types) > 0)
AND (a.delivery_modes IS NULL OR a.delivery_modes = '' OR FIND_IN_SET('某配送方式', a.delivery_modes) > 0)
AND (a.ticket_sources IS NULL OR a.ticket_sources = '' OR FIND_IN_SET(67, a.ticket_sources) > 0)
-- customer_tag（遺漏了 = '' 的判斷）← BUG
AND (a.customer_tag IS NULL OR a.customer_tag = 1)

DB 中現有的資料，customer_tag 欄位都存的是空字串（未配置），按業務語義本應匹配所有請求，卻因為這個遺漏被全部過濾掉了。

AI 定位程式碼，給出修復方案

AI 在程式碼中直接找到對應的 MyBatis Mapper XML：

if test="customerTag != null">
    and (a.customer_tag IS NULL OR a.customer_tag = #{customerTag})
</if>

if test="customerTag != null">
    and (a.customer_tag IS NULL OR a.customer_tag = '' OR a.customer_tag = #{customerTag})
</if>

（第二段為修復後的寫法，補上了對空字串的判斷）

效率對比

這個 BUG 的隱蔽性在於：SQL 語法正確，邏輯上也「看起來」沒問題——只有對比了其他欄位的寫法，才能發現 customer_tag 獨自遺漏了空字串的處理。這類細節差異，人工排查很容易忽略，AI 反而很擅長。

七、診斷效率關鍵點

有 traceId 時優先用 traceId 拉日誌，可精準獲取單次請求的完整鏈路，比關鍵詞搜尋精確得多；
關注關鍵日誌節點：toSearchDTO finished / search begins / resultList is empty / search finished 等，快速判斷資料在哪一層丟失；
SQL 列印日誌（ORM 框架輸出）是黃金線索，直接反映最終執行的查詢條件，AI 能從中發現肉眼難以察覺的差異；
分頁必須拉完：日誌平台一次只返回部分資料，AI 會嚴格執行分頁直到取完，確保不遺漏關鍵日誌。