kevinclaw 智能對話系統 — 使用者功能操作手冊

適用版本：v12.0
最後更新：2026-06-19

本手冊旨在引導一般用戶與具有 AI Agent 特權的進階用戶，快速掌握本系統的各項核心對話、知識庫、智慧代理、資料庫查詢、自動化控制及定時任務排程等功能。

一、一般用戶 vs AI Agent 特權用戶功能對比表

系統將用戶分為一般用戶（Basic 權限）與 AI Agent 特權用戶（Privileged/Admin 權限，需管理員額外授權），下表列出兩者在功能可用性上的差異：

二、一般用戶基礎操作教學

一般用戶可以使用系統提供的基礎 AI 對話、多對話管理、檔案上傳分析、網頁搜尋、企業知識庫與語音助理功能。

2.1 登入與會話管理

1. 帳號登入：開啟系統網址，輸入管理員（admin）為您建立的帳號密碼進行登入。
2. 會話逾時 (Timeout)：系統基於安全性考量，設有會話超時機制（預設 3600 秒）。若在此期間無任何操作，系統將會自動登出，需重新輸入密碼。
3. 密碼重置：一般用戶如遺失密碼，請聯繫系統管理員協助在管理後台進行重置。

2.2 智能對話核心功能

• 輸入與串流：在頁面下方輸入框輸入您的問題，按下 Enter 或點擊「發送」。AI 回覆時採用「串流模式（逐字顯示）」，能大幅縮短等待首字輸出的時間。
• 中止生成：若發現 AI 開始回答非預期內容或答案過長，可隨時點擊輸入框旁的 「中止」 按鈕，立即中斷本次生成。
• KaTeX 數學公式：系統內建 KaTeX 渲染引擎。不論是行內公式（例如 $E=mc^2$）或區塊公式（例如 $$sum_{i=1}^{n} i = frac{n(n+1)}{2}$$），皆會以排版精美的數學符號顯示。
• 單則 Q&A 控制：滑鼠移到每段 AI 回覆下方，會顯示三個功能小圖示：
  • 📋 複製：一鍵複製此段 AI 回覆的文字。
  • 🔊 朗讀：將此段文字轉為語音播放（TTS）。
  • 🗑️ 刪除：僅刪除這單次的一問一答，不影響前後對話脈絡。
• 對話長截圖：點擊輸入框右下側的「相機/截圖」按鈕，系統會自動生成當前整頁對話串的長圖，並以彈出視窗提供下載或預覽。

2.3 多對話串與生命週期

畫面左側為對話串管理面板：

• 新增對話：點擊左上角 「+ 新增對話」 可建立乾淨的全新對話串。
• 自動標題摘要：當您在「新對話」中送出第一個問題後，系統會自動根據您的發問內容，利用 AI 摘要出一段 30 字以內的標題，無須手動命名。
• 對話切換：點擊左側列表的對話標題，即可切換至該對話。注意：各對話串之間的記憶是獨立的，切換後 AI 將不會保留前一個對話串的上下文。
• 封存與刪除：在對話卡片上點擊滑鼠右鍵或點擊卡片旁的「📥 封存」圖示可將對話移至封存區，方便後續唯讀查閱；點擊「🗑️ 刪除」則會永久移除該對話串（注意：若此對話串有設定排程任務，刪除對話串時關聯的排程也會一併被安全刪除）。

2.4 檔案上傳分析

1. 上傳檔案：點擊輸入框旁的 「+」 ➔ 「上傳檔案」，或直接將檔案拖曳至瀏覽器對話區域。
2. 格式與限制：支援 PDF、Word (.docx)、CSV、Excel (.xlsx)、圖片（PNG/JPG）與 TXT 純文字檔，單一檔案上限為 10MB。
3. 進行分析：上傳完成後，您可以直接提問，例如：「幫我摘要這份 PDF 的第三章重點，並將數據整理成表格」或對圖片提問：「這張流程圖中，主要的瓶頸點在哪裡？」。
4. 生命週期：上傳的檔案僅在當前對話串中有效。若開啟新對話，需要重新上傳。

2.5 基礎網頁搜尋

當您需要獲取即時的外部資訊（如今日天氣、近期新聞、最新軟體版本）：

1. 點擊輸入框旁的 「+」 ➔ 勾選 「網頁搜尋」。
2. 輸入您的問題發送，系統會自動在後台調用搜尋引擎，擷取前數筆網頁的摘要，再交由 AI 整理出整合性回答。
3. 來源標記：AI 回答的內容中，會自動在段落尾端附上帶有超連結的來源標記（例如 [來源1]），點擊即可直接在新分頁開啟原始網頁。

2.6 企業知識庫 (KB) 操作

知識庫專用於檢索公司內部的靜態文件（規章、SOP、技術手冊等）：

1. 點擊頁面頂部導航列的 「知識庫」 切換至知識庫介面。
2. 選擇分區：在左側選擇對應的分區（如 IT、HR、管理部等）。注意：您只能看到您所屬用戶群組被授權訪問的分區。
3. 提問檢索：直接在輸入框輸入問題，系統會自動使用 BM25 關鍵字與語意嵌入（Semantic Embedding）混合檢索模型，快速在數千份文檔中找到關聯段落。
4. 答案生成與標示：AI 將根據檢索到的文件內容給出回答，並會在答案下方詳細標註是引用自哪一份檔案的哪一個段落，確保資料的可追溯性。

2.7 語音功能 (ASR 與 TTS)

[!IMPORTANT]
語音輸入（ASR）與語音播放（TTS）依賴瀏覽器的 Web Speech API，系統必須運行於安全連線（HTTPS 或 localhost）下才能正常啟用麥克風權限。

• 語音輸入 (ASR)：點擊輸入框右側的「麥克風」圖示，圖示變紅時即可開始說話。說完後再次點擊圖示，系統會自動將您的語音轉為文字並填入輸入框，按下發送即可。
• 語音朗讀 (TTS)：
  1. 點擊 AI 回覆下方的「🔊 朗讀」圖示，系統將用語音讀出該段回覆。
  2. 自動朗讀開關：可在右上角的語音設定選單中開啟「自動朗讀」功能，開啟後 AI 每次串流輸出完畢皆會自動播放語音。
  3. 語音與語速微調：可在選單中自由切換不同的系統語音（如 Google 國語、英文等）並調整語速。

2.8 介面個人化

點擊右上角的「🌙/☀️」按鈕，可一鍵切換深色（暗色）模式與淺色模式，系統會自動在您的瀏覽器 Cookie 中儲存此偏好設定。

三、AI Agent 特權用戶進階操作教學

[!IMPORTANT]
本章節功能僅適用於具備特權權限（如 AUTOSQL_ELIGIBLE、PUPPETEER_BROWSER、TERMINAL_*、MCP_ACCESS）的用戶。若您的介面沒有出現對應的選項，請聯繫系統管理員。

3.1 什麼是 AI Agent 模式？

與一般對話不同，AI Agent 模式賦予了 AI「工具箱」。當您提出複雜的任務時，AI 不再只是「憑空猜測答案」，而是會：

1. 理解目標：分析您想要執行的任務（如查庫存、截圖某個網頁、發電報）。
2. 拆解步驟：決定需要調用哪些工具、以何種順序調用。
3. 自動執行：自動呼叫資料庫、瀏覽器、執行腳本或調用外部 MCP 插件。
4. 整合回報：收集工具執行後的實體數據或狀態，整合成最終的報表或結論給您。

啟動方式：在對話輸入框旁點擊 「+」 ➔ 勾選 「智慧代理模式 (Agent Mode)」。

3.2 🗄️ 多資料庫智能查詢 (AutoSQL)

Agent 特權用戶可以直接使用自然語言，命令 AI 撰寫並執行 SQL 語法以查詢企業資料庫。

核心工具清單：

• db_list_tables：列出資料庫中的所有資料表名稱。
• db_get_table_schema：查詢特定資料表的欄位結構（Schema）與型態。
• db_run_query：安全執行 SELECT 查詢語法並回傳數據。

使用方法與技巧：

1. 別名指定：系統支援多個資料庫別名。在提問時，請明確指示欲查詢的資料庫，例如：
   • 「請從 spmdb 查詢今日庫存數量前 5 名的品號」
   • 「比較 primary_9526 與 CHENSOURCE 兩個資料庫中，客戶 A001 的訂單金額是否有差異」
2. 自動 Schema 探索：您不需要記住資料表的欄位名稱。您可以直接問：「請查本月銷售金額」，AI 會自動調用 db_list_tables 搜尋與銷售相關的表（如 SO_Master），再調用 db_get_table_schema 取得欄位（如 Amount），最後寫出正確的 SQL 查詢。
3. 安全防線：AI 僅能執行唯讀的 SELECT 語法。任何嘗試執行 INSERT、UPDATE、DELETE 或 DROP 的指令都會被後台安全過濾器攔截並直接拒絕。

3.3 🌐 瀏覽器自動化操作 (Puppeteer)

AI Agent 可以接管一個無頭網頁瀏覽器（Headless Browser），幫您瀏覽網頁、擷取數據，甚至執行點擊與輸入。

兩種瀏覽器模式：

1. 唯讀瀏覽器 (puppeteer_readonly_browser)：
   • 功能：僅下載網頁文字並交由 AI 分析，速度快且安全。
   • 適合場景：分析新聞網頁、抓取技術文檔、閱讀長篇網路文章。
2. 互動瀏覽器 (puppeteer_browser)：
   • 功能：完整模擬真人行為，支援 click（點擊）、type（輸入文字）、hover（懸停）、screenshot（網頁截圖）、upload（檔案上傳）及 submit（表單送出）。
   • 適合場景：自動登入內部系統、在 WordPress 寫文章並發布、將對話結果填寫至某個網頁表單中。

使用範例：

• 「開啟 https://example.com 並幫我把首頁截圖下來」
• 「登入公司的 WordPress 後台，幫我新增一篇草稿，標題是 ‘2026年6月IT運維報告’，內容是我剛才跟你的對話總結」

[!WARNING]
互動瀏覽器是在伺服器端代表您進行真實的網路操作。請勿讓 AI 控制瀏覽器進行高風險操作（如銀行轉帳、刪除雲端資源等），並隨時注意審計日誌。

3.4 💻 Terminal 系統指令執行

系統支援直接在伺服器後台執行操作系統指令。為了保證伺服器安全，設有兩種運行模式：

1. Sandbox 模式 (沙箱模式)：
   • 限制只能執行預先定義的「安全指令白名單」（如 dir、ipconfig、hostname、git status、git diff、python --version 等）。
2. Full 模式 (完全模式)：
   • 解鎖所有指令執行限制（需管理員開啟個別特權帳號的進階 Terminal 權限）。

使用範例：

• 「檢查伺服器當前 git 的變更狀態是否有未提交的 code」
• 「列出資料夾 E:VER12static 下的所有檔案大小」
• 「執行 python 測試腳本確認資料庫連線是否正常」

3.5 🔌 MCP 工具與 Telegram 深度整合

系統支援 Model Context Protocol (MCP) 插件架構。目前最核心的整合是 Telegram MCP 服務，能讓 AI 直接與您的 Telegram 通訊軟體進行互動。

1. 系統設定與 Telegram 登入驗證（Admin/配置人員專用）

若要在系統中啟用您的 Telegram：

1. 開啟管理員設定頁面 /admin/settings。
2. 點擊 「新增 Telegram Preset」。系統會自動填入預設的啟動 command：
   uvx --from git+https://github.com/sparfenyuk/mcp-telegram mcp-telegram run
3. 在 env_json 區塊中輸入您的 Telegram API 憑證：
   • TELEGRAM_API_ID (至 my.telegram.org 申請)
   • TELEGRAM_API_HASH (至 my.telegram.org 申請)
   • TELEGRAM_PHONE_NUMBER (含國碼，例如 +886912345678)
4. 點擊 「登入」 按鈕，系統會啟動驗證碼請求。
5. 點擊 「驗證碼」 按鈕，在瀏覽器跳出的提示框中輸入您手機收到 Telegram 官方發送的 5 位數登入驗證碼。
6. 若您有開啟兩步驟驗證，系統會自動提示，此時點擊 「2FA」 按鈕並輸入您的 Telegram 二階密碼。
7. 登入成功後，點擊 「Session」 可查看當前已處於「Signed In」狀態。

2. Telegram 工具清單：

當 AI Agent 偵測到您要處理 Telegram 相關工作時，會自動調用以下工具：

• ListDialogs：列出最近的對話群組/聯絡人列表與未讀狀態。
• ListMessages：讀取指定群組/聯絡人的歷史對話紀錄。
• GetDialogByName：以關鍵字快速搜尋聊天群組。
• SearchMessages：在 Telegram 中全域搜尋特定關鍵字訊息。
• SendMessage：發送訊息（需擁有 TELEGRAM_SEND 權限）。

3. sendMessage 斷點防護與分批發送機制

[!NOTE]
Telegram 官方對單次訊息發送有 4096 字元 的嚴格上限。

我們的系統已對 SendMessage 工具進行了深度升級：若 AI 產生的報告或回應字數大於 4096 字，系統會在後台自動進行語意切片 (Splitting)，分批發送多則訊息，並確保代碼區塊（Code block）的格式不會因切片而破裂。同時，系統會嚴格校驗 Telegram API 的實體送達回執，防止「回報發送成功但實際對方未收到」的虛假成功情況。

使用範例：

• 「幫我看看 Telegram 裡有沒有人提到 ‘緊急會議’ 的訊息」
• 「把剛才產生的資料庫 IT 工單報表發送到 Telegram 的 ‘IT支援群組’」

3.6 🧠 跨回合會話記憶 (Session Memory)

在複雜任務中（如跨資料庫查詢後再發送 Telegram），AI 需要記住多個步驟產生的中間資料。

• 系統提供 update_session_memory 工具，AI 會自動將取得的資料（例如：查詢出的 order_id、Telegram 群組的 ID、臨時檔案路徑）寫入 Session Memory。
• 下一輪對話時，即使沒有在問題中提及，AI 也會自動讀取這份記憶，實現平滑的「接續工作」。

3.7 ⏰ 對話任務排程系統 (Task Scheduler)

[!NOTE]
這是 VER12 最核心的自動化升級。特權用戶（Admin）可以將任意一個既有的對話串包裝成一個「背景排程任務」，讓 AI 定時自動執行該對話，並將執行結果寫回對話紀錄中。

1. 如何將對話轉換為排程？

當您與 AI 在前台完成了某項分析任務（例如：已經調整好提示詞，讓 AI 能完美從資料庫拉出昨日異常工單並生成摘要），若您希望這個任務每天定時跑：

1. 在左側對話列表中，找到該對話卡片。
2. 點擊卡片右下角的 「⏰ (排程設定)」 圖示。
3. 頁面將會自動重新導向至 /admin/schedules?conversation_id=您的對話ID 排程管理控制台。

2. 設定排程參數：

• Schedule Key：此任務的唯一辨識碼，只能包含英文、數字、點、底線、冒號與連字號。例如：daily_it_wo_report。
• 目標對話串：系統已為您自動填入。
• Cron 表達式：設定定時觸發時間。
  • 0 9 * * 1-5 ➔ 每週一至週五的早上 9:00 執行。
  • 0 18 * * 0 ➔ 每週日傍晚 18:00 執行。
  • 0 0 1 * * ➔ 每個月 1 號的凌晨 0:00 執行。
• 執行模式 (Execution Mode)：
  • snapshot (快照模式 – 推薦)：凍結此排程建立時的「對話上下文與 AI 設定（包含當時使用的 Profile、模型、AI 角色 Role ID）」。即使您事後在前台繼續對該對話進行聊天或改動，背景排程依然會以建立當時的設定執行。
  • follow_latest (跟隨最新模式)：排程每次執行時，都會自動去讀取該對話串在前台「最新一輪的設定（包括最後使用的模型或角色變更）」。
• 啟用排程：勾選即可納入背景自動執行佇列。

3. 前台狀態視覺化

當排程成功建立並啟用後：

• 前台側邊欄的對話清單中，該對話標題右側會出現一個 ⏰ 圖示（如果有多個排程綁定同個對話，會顯示如 ⏰ (2)）。
• 滑鼠懸停於 ⏰ 上，可預覽此對話綁定的 Schedule Keys，方便您一眼識別哪些對話正在背景定時執行。

4. 歷史紀錄與手動測試

在排程管理頁面下方，提供完整的監控功能：

• 執行一次 (Run Now)：點擊此按鈕可立即在背景手動觸發該排程，非常適合在設定完 Cron 後進行首次功能測試。
• 紀錄 (Log History)：點擊任一排程的「紀錄」按鈕，下方會載入其最近 20 次的執行紀錄，包括 Run ID、狀態 (SUCCESS/FAILED)、開始時間、完成時間、結果預覽 (回寫內容的開頭) 以及 錯誤訊息（若執行失敗）。
• 日誌清理：支援「刪除此筆」單條日誌，或點擊「清空目前排程紀錄」一次清除該排程的所有歷史。

5. 生命週期關聯安全機制

• 刪除安全連動：當您在前端對話列表中「刪除對話串」時，系統會自動在後台資料庫中刪除所有與該對話串綁定的 scheduler_definitions 與 scheduler_run_history，防範產生孤立的背景死循環任務。

四、精選實務場景與 Prompt 範例

4.1 跨資料庫對帳與庫存分析 (Agent 模式)

場景：需要比對 primary_9526（主要庫存）與 CHENSOURCE（備份庫存）兩個資料庫中，是否有品號的庫存數量不一致，並列出差異。

• 發送給 AI 的 Prompt：

  [啟動智慧代理模式]
  請幫我比對 primary_9526 和 CHENSOURCE 兩個資料庫別名中，當前 'INV_Qty'（庫存數量）不一致的品號。
  請先去查看這兩個庫的 Table 結構，找出對應的庫存表（應該是帶有 'Stock' 或 'Inventory' 關鍵字的表），
  然後寫一個 SQL 進行 JOIN 比對，最後把數量有差異的品號、在庫 A 的數量、在庫 B 的數量以 HTML 表格呈現，並說明可能的原因。

4.2 自動化網頁爬蟲與 WordPress 發文 (Agent 模式)

場景：搜尋台灣近期最新的 AI 工商應用趨勢，整理成摘要後，自動登入公司的測試 WordPress 網站發表文章。

• 發送給 AI 的 Prompt：

  [啟動智慧代理模式]
  第一步：請使用網路搜尋，尋找「2026年 台灣 企業 AI 應用 趨勢報告」，幫我整理出三個核心重點。
  第二步：使用互動瀏覽器工具（puppeteer_browser），前往公司的 WordPress 後台：https://blog.urcloud.biz/wp-admin。
  第三步：在登入頁面輸入帳號 'writer_agent'，密碼可以使用環境變數中的 WP_PASSWORD（或請直接在畫面上尋找欄位輸入）。
  第四步：登入成功後，導覽至新增文章頁面，標題設為「2026年台灣企業AI應用趨勢整理」，內容填入剛才搜尋到的三個核心重點，並點擊「儲存草稿」。完成後，把儲存成功的頁面截圖給我看。

4.3 每日 IT 工單定時 Telegram 報告 (排程模式)

場景：希望每天早上 9 點，AI 自動去查 spmdb 資料庫中，昨日未結案的 IT 工單（Status = 'Open'），整理後發到 Telegram 的 IT 運維群組。

1. 第一步（前台設定與測試）：
   在新對話串中，開啟「智慧代理模式」，輸入以下 Prompt 進行測試：

   請從 spmdb 資料庫查詢昨日（以昨日日期為準）新增且 Status 為 'Open' 的 IT 工單數量與明細。
   請將查詢結果整理成一段精簡的運維日報文字，包含：1. 未結案總數 2. 影響最久的前三筆工單編號與主旨。
   最後，呼叫 telegram/SendMessage 工具，將這段日報發送到名稱為 'IT_Operation_Group' 的 Telegram 對話中。

2. 第二步（確保測試成功）：
   確認前台執行無誤，且 Telegram 群組確實收到了格式美觀的訊息。
3. 第三步（建立排程）：
   點擊該對話卡片上的 ⏰ (排程設定)。
4. 第四步（配置排程）：
   • Schedule Key：daily_it_tele_report
   • Cron：0 9 * * 1-5（每週一至週五早上 9 點）
   • Execution Mode：選擇 snapshot（鎖定當前的測試成功的 Prompt 與資料庫設定）
   • 點擊 保存排程。現在，每天早上 9 點系統就會在背景自動重複該對話，幫您發送 IT 工單日報。