從零到一：WordPress 輕量級 AI 自主客服助理外掛的架構設計與實作全紀錄
傳統的網站客服系統通常分為兩大類：一種是基於固定選單與關鍵字匹配的「機器人」，回答生硬且無法處理複雜問題；另一種是直接串接外部大語言模型（LLM）的對話框，雖然對答流暢，但卻對網站內部的資料庫（如文章、公告、產品列表）一無所知，容易產生「幻覺」並胡亂編造回答。
為了解決這個痛點，我們為 KEVINCLAW 智慧代理系統 開發了一款專屬的 WordPress 輕量化 AI 客服助理外掛。本篇文章將由淺入深地為您剖析，我們是如何在不洩漏主機安全的前提下，讓 AI 自主翻找網站資料庫、自動格式化網頁排版，並將所有對話無縫同步回後台管理系統中進行稽核。
🏗️ 系統架構：前後端解耦的智慧協作
整個客服系統採用了前後端解耦的架構，分為 WordPress 端的「輕量級前端外掛」與 KEVINCLAW 平台的「後端 AI 代理伺服器」：
graph TD
subgraph WordPress 站台 (https://blog.urcloud.biz)
A[訪客對話視窗 Frontend] <-->|AJAX + Nonce 安全驗證| B[WordPress 核心 PHP Proxy]
end
subgraph VER12 後端平台 (http://localhost:5566)
B <-->|Bearer Token 安全通訊| C[受限的 Flask Customer API]
C <-->|1. 獲取 LLM 決策| D[OpenRouter / Gemini 2.5]
C <-->|2. 自主工具執行| E[Python 受限沙盒 Sandbox]
E <-->|唯讀 SELECT 檢索| F[(blogdb / WordPress MySQL)]
E <-->|原生 HTTP 請求| G[wttr.in 天氣服務]
C <-->|3. 同步寫入稽核| H[(SQLite chat_history.db)]
end
1. WordPress 端（前端外掛）
負責與訪客直接互動。前端使用 Vanilla CSS / JS，引入現代的 Glassmorphism 玻璃擬真 視覺風格，支持深淺色模式切換，並具備優雅的打字等待動畫。為了解決複雜表格在手機端的易讀性，我們設計了可展開至近乎全螢幕的「最大化」模式，以及外層包裹 overflow-x: auto 的 RWD 水平滾動機制。
2. KevinClaw 平台端（後端 API 伺服器）
不寫死任何 SQL，而是建立一個受限的 AI Agent 自主循環（Agent Loop）。接收到用戶訊息後，由 LLM 自主決定調用工具（Tool Calls）來探索資料庫結構並取得資料，最後在平台資料庫中建立稽核對話串。
🛠️ 技術亮点由淺入深剖析
第一階段：極致視覺與 RWD 行動體驗的打磨
大多數網頁客服對話框在手機上的排版極其糟糕，特別是當 AI 輸出帶有連結的「推薦文章表格」時。我們在此處做了幾項關鍵優化：
- 表格動態 HTML 渲染器：我們在前端 JS 實作了專屬的 Markdown 表格解析器，會自動將 AI 輸出的 Markdown 表格轉換成帶有 HSL 邊框、表頭淡紫色漸層背景的 HTML
<table>。 - 動態表頭 Nowrap 偵測：為了防止日期格式被擠壓折行，JS 渲染器會動態掃描表頭名稱。僅有「序號、日期、時間、發布、項目」等欄位會被套用
white-space: nowrap;，其他如文章摘要或點評則能大方換行，維持完美的視覺比例。 - 手機端 100% 氣泡拓寬與滾動：當檢測到訊息包含表格時，JS 會為該氣泡加上
.ver12-msg-has-table類別，在手機端自動將氣泡最大寬度擴展至100%，並在 450px 最小寬度的表格外包裹滾動條，讓使用者能流暢地左右滑動閱讀，文字絕不變形。
第二階段：AI Agent 自主翻找與 SQL 防禦
與一般的硬編碼（Hardcoded）SQL 搜尋不同，我們拒絕使用死板的關鍵字模糊比對，而是賦予 LLM 自主工具鏈：
- 第一步 (db_list_tables)：AI 收到使用者的搜尋意圖時，主動呼叫此工具，發現
blogdb中存在wp_posts等資料表。 - 第二步 (db_get_table_schema)：AI 進一步讀取
wp_posts表的欄位，得知 ID、post_title、post_content、post_date、post_status、post_type 的存在。 - 第三步 (db_run_query)：AI 自動撰寫並執行安全的 SELECT SQL（例如加入
post_status='publish'的篩選），將獲取的結果與動態 WordPress 網址（如/?p=ID）組合成精美的超連結表格。
[!IMPORTANT]
如何防止 Prompt Injection（提示詞注入攻擊）與越權？
為了防堵惡意使用者試圖引導 AI 刪除資料或執行命令，我們在後端 Python 中實施了強制的程式級沙盒限制：
- 剝奪 Terminal 執行權限：AI 的工具名單中絕不提供通用 command 工具。
- 別名強制改寫 (Latching
blogdb)：不論 AI 回傳的 tool arguments 寫的是什麼 db_alias，後端 Python 程式碼會將其強制覆寫為"blogdb"，完全無法存取其他內部系統庫。- 唯讀 SQL 驗證：所有查詢均通過唯讀檢驗，拒絕任何
INSERT、UPDATE、DROP或預存程序執行。
第三階段：安全性與專屬天氣技能的完美共存
許多 AI 客服需要查詢天氣。在 KevinClaw系統中，查詢天氣原本是一項被定義為調用 terminal_execution 執行 curl "wttr.in/...?" 的「技能」。
但因為客服端點禁止使用 Terminal 工具，我們如何在不開啟 Terminal 權限的安全前提下，讓 AI 查天氣？
我們採取了專屬天氣工具隔離策略：我們為 AI 封裝了一個專屬的 get_weather(city) 工具。當 AI 想要查天氣時，它會呼叫此工具，而在 Python 後端：
def safe_get_weather(city: str) -> str:
# 不調用任何 command / cmd.exe，純粹在 Python 使用 requests 發送 RESTful 請求
url = f"https://wttr.in/{city}?format=3"
resp = requests.get(url, timeout=10)
...這種「將危險命令封裝為安全 Python 接口」的設計，既滿足了功能性，又保證了前端客服系統的防禦力。
第四階段：與 KevinClaw 主控台無縫對接的會話審計
訪客在官網上諮詢，管理員要如何知道誰問了什麼、AI 答了什麼？如果不能稽核，客服就無法持續優化。
我們利用 SQLite 共享資料庫 與 對話執行緒註冊機制 實現了這個需求：
當外部訪客在 WordPress 前端提問並由 AI 回覆後，後端 API 除了在 SQLite 記錄聊天歷程，還會同步向 conversations 資料表插入/更新一筆會話記錄（將其綁定至 user_id=1 的 Admin 管理員帳戶）。
這會產生一個神奇的效果：
管理員登入 KevinClaw 平台主畫面（https://localhost:5566）後，左側的對話側邊欄將會即時、動態地出現「官網客服 – [問題摘要]…」的對話串。點擊後即可直接在平台內回溯、審計整個會話！
📈 逾時防禦與日期格式細節打磨
在實際導入過程中，我們克服了兩個不易察覺的排版與連線細節問題：
1. 超長 Agent Loop 的逾時防禦 (Timeout Fix)
因為 AI 執行「查表名 -> 查欄位 -> 查 SQL -> 總結回答」需要 4 回合的 OpenRouter 請求，後端累計處理時間有時會達到 90-100 秒。而 WordPress 預設的 cURL 逾時為 90 秒，會拋出 cURL error 28 異常。
- 解決方案：我們在外掛 AJAX 處理器開頭加入了
@set_time_limit(240);，並將wp_remote_post的'timeout'參數提升至240秒，完美解決了複雜提問被逾時阻斷的問題。
2. 雙重日期清洗 (防範後台介面折行破版)
平台的對話回溯介面因為有它自己的 CSS 樣式，容易因為日期包含時分秒與空格（如 2026-02-17 13:51:36）而折成三行。
- 解決方案：除了修改平台的
chat-markdown.css之外，我們在後端db_run_query資料回傳給 LLM 之前，直接用 Python 正則表達式將所有時間戳清洗為YYYY-MM-DD（僅保留年月日）。這讓 AI 從源頭就無法取得時分秒，從而輸出最緊湊的短日期，徹底杜絕了折行破版。
💡 總結與未來展望
這套 WordPress 客服外掛與 KevinClaw AI Agent 的整合方案，展示了現代 AI 落地應用中的核心原則：自主性與安全性的完美平衡。
我們給予 AI 足夠的工具去進行思考與資料探索，使其能夠處理任何主題的諮詢；同時又在 Python 程式級、通訊逾時級、資料庫別名級建立了堅固的沙盒，防止安全漏洞。這款外掛的誕生，無疑為企業官方網站提供了一位既聰明、又安全、且便於管理的 24 小時 AI 客服大師！