kevinclaw 智能對話系統 — AI Agent 工具應用指南

最後更新：2026-06-27
適用權限：具備 Agent 特權 (Privileged / Admin) 之帳號

本指南旨在詳細介紹系統中已成功部署的各項 AI Agent 工具與 Model Context Protocol (MCP) 外掛服務。閱讀本指南將幫助您理解 AI 如何自動規劃、調用這些工具來替您處理複雜的資料庫查詢、網頁瀏覽、檔案處理、電子郵件發送以及即時通訊回報。

一、什麼是 AI Agent 模式？

當您開啟對話輸入框旁的 「智慧代理模式 (Agent Mode)」 時，AI 將不再只是根據歷史對話回答文字，而是化身為一個自動執行任務的「智慧助理」。

• 規劃 (Planning)：AI 會將您的複雜要求拆解成多個小步驟（例如：先去資料庫查庫存 >> 寫成 Excel 檔 >> 把檔案發到指定 Telegram 群組）。
• 執行與觀察 (Action & Observation)：AI 會在背景依次調用本機或外部的工具，讀取工具回傳的真實數據。
• 自癒與修正 (Self-Healing)：若某個工具執行超時或報錯（例如雲端 OCR API 失敗），AI 會自動嘗試備用方案（如改為寫程式腳本在本地解析），直到任務完成為止。
• 乾淨回寫：系統在背景會自動過濾多步決策中的冗贅快取，只在歷史對話中寫入最乾淨的最終結論。

二、核心內置代理工具 (Built-in Agent Tools)

這些是集成在系統核心的內置工具，主要用於資料庫查詢、瀏覽網頁、在伺服器上執行指令與記憶跨回合變數。

2.1 🗄️ 多資料庫 AutoSQL 工具

AutoSQL 允許 AI 使用自然語言在背景連線至公司的 Microsoft SQL Server (MSSQL)，進行多資料庫別名聯合查詢。

• db_list_tables
  • 用途：列出目標資料庫中的所有資料表名稱。
  • 應用場景：當 AI 不確定某項業務資料（如工單、採購單、BOM）存放在哪個表時，會先用此工具進行庫結構探索。
• db_get_table_schema
  • 用途：獲取特定資料表的欄位結構（Schema）與欄位資料型態。
  • 應用場景：在寫 SQL 查詢前，精確定位欄位名稱（如 po_tranDate、entity），防範語法錯誤。
• db_run_query
  • 用途：執行 SQL SELECT 查詢並回傳 CSV/HTML 表格結果。
  • 安全邊界：系統設有強制的 唯讀安全性攔截器，僅允許執行 SELECT。任何嘗試執行 INSERT、UPDATE、DELETE、DROP 等 DML/DDL 的指令皆會被後台拒絕，防範資料被修改。

2.2 🌐 網頁瀏覽自動化 (Puppeteer)

當 AI 需要讀取外部網頁內容、登入內部 Web 系統或對網頁進行操作時，會自動接管 Puppeteer 瀏覽器。

• puppeteer_readonly_browser (唯讀無頭瀏覽器)
  • 用途：快速下載目標網頁的純文字內容並轉為 Markdown，供 AI 閱讀。
  • 應用場景：分析今日科技新聞、抓取開源專案技術文件。速度快、耗能低。
• puppeteer_browser (互動式瀏覽器)
  • 用途：模擬真人操作，支持 click (點擊)、type (輸入文字)、hover (懸停)、screenshot (截圖)、upload (檔案上傳) 及 submit (表單送出)。
  • 應用場景：自動登入公司的 WordPress 或系統後台、填寫表單、抓取複雜 JavaScript 渲染後的網頁、生成網頁執行截圖提供給用戶查驗。

2.3 💻 沙箱終端執行 (terminal_execution)

• 用途：在伺服器的指定工作目錄（目前為 D:VER12SANDBOX）下執行作業系統指令或運行腳本。
• 安全模式 (Sandbox)：預設僅允許執行白名單指令（如 dir、ls、git status、python --version 等）。在 Admin 特權下可解鎖 Full 模式以調試本機腳本。
• 應用場景：AI 可以自行在沙箱中編寫一個 Python 分析腳本，並使用 terminal_execution 執行它，以處理極為複雜的數據運算或檔案轉換。

2.4 🧠 跨回合會話記憶 (update_session_memory)

• 用途：讓 AI 將多回合對話中取得的中間參數（如：上一步查詢到的 po_id、產生的臨時 CSV 檔案路徑、目標 Telegram 的群組 ID）寫入 Session Memory。
• 應用場景：在長對話中，即使您在提問中省略了參數，AI 也能自動讀取此記憶，無縫接續上一步驟的工作。

2.5 🔍 網路檢索 (web_search)

• 用途：調用 Brave/Bing/Google 搜尋引擎，獲取即時的網際網路網頁摘要。
• 應用場景：查詢最新的匯率、今日天氣、IT 系統警報排查方案，並會自動在 AI 回答中生成 [來源1] 的超連結供點擊。

三、Model Context Protocol (MCP) 工具服務

系統整合了 MCP 插件協議，解鎖了與外部通訊軟體、受控檔案系統、OCR 圖像辨識、GitHub 儲存庫及電子郵件系統的連線能力。

3.1 💬 Telegram MCP 服務

賦予 AI 代表您發送與讀取 Telegram 訊息的能力。

• 關鍵工具：
  • ListDialogs：列出您最近的 Telegram 對話列表（群組、頻道或個人）與未讀數。
  • ListMessages：獲取指定群組或聯絡人的歷史聊天紀錄。
  • GetDialogByName：以關鍵字快速搜尋群組 ID。
  • SendMessage：發送訊息給指定的群組或個人。
• 進階特性 (防破裂語意切片)：
  • 由於 Telegram 官方有單次發送 4096 字元的上限，當 AI 產生長篇大論的報表或代碼時，系統會自動在後台進行語意切片 (Splitting) 分批發送，並確保代碼塊等 Markdown 格式不會碎裂。
• 應用場景：「去查 spmdb 資料庫的庫存警報，把結果整理好後發送到 Telegram 的 ‘DCC文管中心’ 群組中。」

3.2 📁 Filesystem 本機受控檔案系統

允許 AI 在安全授權的白名單目錄下（目前為 E:VER12SANDBOX 與 D:chensource）進行檔案讀寫。

• 關鍵工具：read_file、write_file、list_directory、move_file、get_file_info。
• 安全隔離：AI 無法讀寫白名單以外的目錄（如系統 C 槽或 Windows 目錄），防止誤操作導致伺服器崩潰。
• 應用場景：「在 D:chensource 中建立一個 Python 備份日誌腳本，將結果儲存為 csv 檔案。」

3.3 🌐 Fetch 網頁擷取

• 關鍵工具：fetch
• 用途：透過 HTTP 協議快速對外部網頁或 API 進行靜態文字下載，並自動將 HTML 清洗為 Markdown 格式。
• 優點：速度極快，在不涉及複雜 JavaScript 渲染或點擊按鈕的場景下，是 Puppeteer 瀏覽器的理想高效替代方案。

3.4 🖼️ PaddleOCR 圖像與文件結構化

整合了 PaddleOCR 推理引擎，專門用來將圖片、掃描 PDF 與 Office 文件（Word/Excel/PPT）轉換為可讀的 Markdown 文本或表格。

• 關鍵工具：
  • extract_text_from_file：提取本地圖片或掃描 PDF 中的中文與英文文字。
  • extract_table_from_file：辨識圖片中的實體表格，自動排版成標準 Markdown Table。
  • convert_office_to_markdown：快速將 .docx、.xlsx、.pptx 轉換為結構化的 Markdown。
• 備援機制：優先呼叫高精度的雲端 API。若雲端斷線，系統會自動降級 (Fallback) 至本地已加載的 PaddleOCR 本地模型進行推理，保證 100% 離線可用。
• 應用場景：「幫我讀取 D:invoice.png 內的發票明細，並將表格呈現給我。」

3.5 🐙 GitHub MCP 服務

• 用途：允許 AI 代表您存取與管理 GitHub 儲存庫。
• 關鍵工具：search_code、create_issue、create_pull_request、get_file_contents。
• 安全配置：可設定為唯讀模式，防止 AI 在您未授權的情況下向倉庫寫入程式碼。

3.6 📧 Email 郵件管理服務

直連公司的 SMTP 與 IMAP 伺服器，讓 AI 可以自動替您處理郵件。

• 關鍵工具：
  • check_unread_emails：檢查未讀郵件。
  • search_emails：以關鍵字、寄件人或時間範圍篩選郵件。
  • send_email：發送電子郵件。
  • reply_to_email：對特定郵件進行回覆。
• 應用場景：「檢查信箱中有沒有主旨包含 ‘採購單異常’ 的未讀郵件，摘要內容後發送到我的 Telegram。」

四、實務提問 Prompts 指南與組合技

AI Agent 的最大價值在於「工具組合 (Chaining)」。以下提供三個經典的實務提問範例：

💡 組合技 1：AutoSQL 資料庫分析 >> Email 發送 (結合資料庫與郵件)

• 適用場景：每週五下班前，查詢本週異常的 ERP 出貨單，整理成報告後寄送給部門主管。
• Prompt 範例：

  [智慧代理模式]
  請從 spmdb 資料庫查詢本週內（2026-06-21 到今日）出貨單狀態為 'Pending_Approval' 的單據。
  請先探索相關的 dbo.NS_SalesOrder_Line 或出貨表結構，然後寫一個 SELECT SQL 進行查詢。
  將查詢出的數據整理成 Markdown 表格，並寫一封主旨為「本週 ERP 待審核出貨單週報」的電子郵件。
  收件人設為 manager@chensource.com，信件內文使用剛才整理的表格，並直接呼叫 Email 工具將信件發送出去。

💡 組合技 2：本機 Excel 分析 >> 自動自癒腳本 >> Telegram 群發 (結合檔案、沙箱與通訊)

• 適用場景：讀取存放在伺服器本地的網路交換器備份清單 Excel，分析警報後發送到 Telegram 群組。
• Prompt 範例：

  [智慧代理模式]
  請在 D:chensource 目錄下尋找名為「2F機房.xlsx」的檔案。
  請使用 Python 的 openpyxl 庫（如果 ocr 工具不可用，請在沙箱中自行撰寫 parse.py 腳本並執行）來讀取「設備連線」Sheet。
  篩選出其中 Status 欄位為 'Offline' 的所有設備。
  將這些離線設備的 IP 與名稱整理成一則警告訊息，並呼叫 telegram/SendMessage 工具，將警報發送到 'IT_Alert_Group' 群組。

💡 組合技 3：網頁數據抓取 >> 圖片 OCR >> 檔案寫入 (結合網頁、OCR 與檔案)

• 適用場景：監控某個外部公開網站的報表截圖，辨識後存檔。
• Prompt 範例：

  [智慧代理模式]
  第一步：使用互動瀏覽器工具（puppeteer_browser）前往網址 https://example.com/status-board。
  第二步：等待頁面加載完成後，將當前網頁進行截圖，儲存為 D:chensourceboard_screenshot.png。
  第三步：呼叫 paddle-ocr 工具，讀取剛才這張截圖中的表格文字，並將其辨識結果整理成 Markdown Table。
  第四步：將這個 Markdown Table 的內容寫入 E:VER12SANDBOXboard_report.md 檔案中。