kevinclaw 智能對話系統 — 完整技術文件

版本：8.0 ／ 最後更新：2026-06-19

目錄

1. 版本開發歷史
2. 系統功能對比表（一般用戶 vs AI Agent 特權用戶）
3. 一般用戶使用說明書
4. AI Agent 特權用戶使用說明書
5. 未來發展藍圖

版本開發歷史

起源（2025-07-25 ~ 2025-07-30）：Flask 基礎版

V9 風格重整（2025-07-31 ~ 2025-08-02）：前端現代化

AutoSQL 與自然語言查詢（2025-08-04 ~ 2025-08-09）

知識庫（KB RAG）建置（2025-08-20 ~ 2025-09-05）

認證授權系統（2025-09-06）：企業多用戶管理

推理模型與語音（2025-09-07 ~ 2025-10-06）

多模型 Fallback 與對話串（2025-12 ~ 2026-02）

AI Agent 核心架構（2026-06-07 ~ 2026-06-14）：最重要里程碑

AI Agent 工具擴充（2026-06-14 ~ 2026-06-16）

Terminal、Puppeteer Full Mode、MCP（2026-06-17 ~ 2026-06-19）

功能對比表

一般用戶使用說明書

登入

1. 開啟系統網址（需聯絡管理員取得帳號）
2. 輸入帳號密碼，點擊「登入」
3. 閒置超過 Session Timeout 會自動登出（預設 3600 秒）

忘記密碼：聯絡系統管理員（uradmin）重置

基本對話

開始新對話

• 在畫面下方輸入框輸入問題，按 Enter 或「發送」按鈕
• AI 回覆採用串流顯示（逐字出現）
• 回覆過程中可按「中止」按鈕停止回覆

對話功能列（每段回覆下方）

• 📋 複製 — 複製此段 AI 回覆文字
• 🔊 朗讀 — 語音播放此段回覆
• 🗑️ 刪除 — 刪除此則問答

截圖

• 按輸入框旁的截圖按鈕，自動截取當前對話畫面

多對話串

畫面左側為對話串列表：

注意：切換對話串後，AI 不會記得前一個對話串的內容

檔案上傳分析

1. 點擊輸入框旁的 「+」 → 上傳檔案
2. 支援格式：PDF、Word、CSV、圖片（JPG/PNG）、純文字
3. 上傳後直接提問，例如：「幫我摘要這份報告」
4. 檔案在當前對話串有效，切換對話串後需重新上傳

檔案大小上限：10 MB（預設）

網頁搜尋

1. 點擊輸入框旁的 「+」 → 網頁搜尋
2. 輸入搜尋關鍵字
3. 系統自動抓取前幾筆搜尋結果摘要，再由 AI 整合回答
4. 回覆中會附上來源網址超連結

知識庫（KB）查詢

1. 點擊頂部導航列「知識庫」
2. 選擇分區（IT/HR/Finance 等，依你的群組權限顯示）
3. 直接輸入問題，系統從已上傳的文件中檢索相關內容
4. AI 根據檢索結果給出回答，並標示來源文件

AutoSQL 自然語言查詢

適用群組：Privileged 及以上

輸入自然語言問題，系統自動轉換為 SQL 查詢：

結果以表格顯示，AI 自動附上分析說明。

語音功能

需求：HTTPS 連線（本機 http://localhost 可能無法使用）

語音輸入（ASR）

1. 點擊輸入框旁的麥克風圖示
2. 對著麥克風說話
3. 語音自動轉成文字，按 Enter 發送

語音朗讀（TTS）

• 每段 AI 回覆下方有朗讀按鈕
• 可在語音選單選擇語言/聲音（中文繁體/英文等）
• 「自動朗讀」開關：開啟後每次回覆自動播放

暗色模式

右上角點擊🌙切換暗色/亮色模式，設定自動記憶。

AI Agent 特權用戶使用說明書

本節為有 AI Agent 權限用戶專用（需管理員開啟 AUTOSQL_ELIGIBLE、PUPPETEER_BROWSER、TERMINAL 等相應群組權限）

AI Agent 是什麼

AI Agent 是具有「工具呼叫」能力的 AI 模式。當你提出需要查資料庫、搜尋網路、控制瀏覽器或執行程式的需求時，AI 不只回答文字，還會自動決策呼叫對應工具，取得結果後再整合成完整回答。

啟動方式：在輸入框旁點擊 「+」→「智慧代理模式」

工具一覽

🗄️ 資料庫工具

多資料庫查詢
系統支援多個 MSSQL 別名並行查詢。詢問時說明要查哪個資料庫：

• 「查詢 primary_9526 別名中的銷售訂單」
• 「從 spmdb 查本月製令數量」
• 「同時查 CHENSOURCE 和 spm_ns 的庫存差異」

安全機制：AI 只能執行 SELECT 查詢，不能修改資料

🔍 網路搜尋工具

web_search — Brave Search 直連 API，高品質搜尋結果

使用範例：

「搜尋最新的 Python 3.13 新功能」
「找找台灣近期關稅政策變化」

AI 自動判斷是否需要搜尋，無需手動指定。

🌐 瀏覽器工具

兩種模式，依管理員設定開放：

唯讀瀏覽器（puppeteer_readonly_browser）

• 開啟網頁、擷取內容、分析頁面文字
• 適合：「幫我分析這個網頁的內容」

互動瀏覽器（puppeteer_browser）

• 可登入網站、填表、點擊、截圖、上傳檔案
• 適合：「登入我的 WordPress，新增一篇文章」

使用範例：

「開啟 https://example.com 並截圖」
「登入 https://blog.urcloud.biz，新增一篇標題為'測試'的文章」
「幫我填寫這個表單並送出」

警告：互動瀏覽器可以在真實網站執行動作，請確認指令正確再下達

💻 Terminal 工具

terminal_execution — 在伺服器端執行系統指令

Sandbox 模式（白名單指令）：

whoami / hostname / git status / dir / ipconfig
git diff --stat / python --version

Full 模式（需管理員開啟）：可執行所有允許的指令

使用範例：

「查看目前 git 的變更狀態」
「列出 D:VER12SANDBOX 的檔案」
「執行 python --version 確認 Python 版本」

所有指令執行都有審計日誌記錄

🔌 MCP 外部工具

mcp_list_tools — 查詢已安裝的 MCP Server 和工具清單

mcp_tool — 呼叫指定 MCP 工具

目前已安裝：Telegram MCP Server

使用範例：

「列出我的 Telegram 未讀對話」
「在 Telegram 搜尋包含'報表'的訊息」
「傳送訊息到 Telegram 的'IT通知'群組：系統維護完成」

注意：SendMessage 有獨立的 TELEGRAM_SEND 權限控制，且所有傳送動作都有審計記錄

🧠 跨回合記憶

update_session_memory — AI Agent 工作記憶

當 Agent 完成一個工具動作後，關鍵資訊（如查詢結果、對話群組 ID）會自動存入記憶，供後續工具呼叫使用，無需重複說明。

Agent 使用技巧

最佳實踐

1. 明確說明目標，不要說「幫我查一下」，要說「查詢本週 IT 工單的未結件數量」
2. 指定資料庫別名（多庫環境），如「從 primary_9526 查詢…」
3. 複雜任務可分步驟，Agent 最多執行 20 次工具呼叫

對話策略

✅ 好的問法：
「請查詢 spmdb 中本月製令（MO）的完成率，並以表格顯示，再搜尋業界標準完成率作比較」

❌ 避免的問法：
「查一下工單」（太模糊）
「查所有資料」（範圍太大）

權限等級說明

請聯絡管理員（uradmin）開啟所需的群組權限

未來發展藍圖

優先順序排列

🔴 高優先（架構影響大）
🟡 中優先（功能擴充）
🟢 低優先（優化類）

🔴 1. Multi-DB Provider（多資料庫類型支援）

現況：目前僅支援 MSSQL（多個別名並行查詢）

計劃：

• 擴充 mssql_routes.py 成抽象 DB Layer
• 新增 Provider 驅動：Oracle、MySQL、PostgreSQL
• config.ini 新增 [ORACLE.*], [MYSQL.*], [PGSQL.*] 設定區段
• Agent 工具自動辨識資料庫類型選用正確驅動

預期影響：db_run_query 工具無需修改，驅動層透明切換

🔴 2. Channel-Core 系統架構

現況：Flask 單體應用，所有功能都在 app.py

計劃：

• 設計「Channel（通道）」抽象層
• 每個通道（Web Chat / Telegram / Line / Email）共用相同 AI Core
• AI Core 負責：工具管理、記憶、模型呼叫
• Channel 負責：訊息格式化、認證、傳送

用戶 → Channel Adapter → AI Core → Tool Manager → 各工具
                              ↓
                         Memory Store

🟡 3. Conversation-Centric Task Scheduler（對話為中心的任務排程）

概念：讓 AI 可以設定「定時任務」

功能願景：

• 在對話中說「每天早上 8 點幫我查昨日銷售報表發到 Telegram」
• 系統自動建立排程，定時執行 Agent 工具組合
• 任務執行結果推送到指定通道（Telegram/Web）

技術需求：

• 任務佇列（Celery/APScheduler）
• 任務模板（儲存工具呼叫序列）
• 任務執行歷史記錄

🟡 4. DB Alias 細粒度存取控制

現況：有 AUTOSQL_ELIGIBLE 的用戶可查詢所有 MSSQL 別名

計劃：在 user_overrides 表加入：

• override_type = "db_alias"：限制可存取的資料庫別名
• override_type = "db_table_filter"：限制可查詢的 Table（支援通配符如 dbo.Public.*）

Admin UI：在用戶管理頁面，管理員可為個別用戶設定 DB 別名白名單

不影響現有架構，只需擴充 _check_user_override() 的呼叫點

🟢 5. AI 提示詞 / 角色管理界面

現況：System Prompt 和角色（Role）寫死在 app.py 或 config 檔案

計劃：

• Admin 後台新增「提示詞管理」頁面
• 可視化編輯各角色的 System Prompt
• 支援多版本管理（草稿/發布/歷史版本）
• 可為不同群組綁定不同預設角色
• 新增角色時不需改程式碼（資料庫驅動）

架構演進路徑總覽

現在（v8.0）
  ├── Flask 單體
  ├── MSSQL 多別名
  ├── AI Agent Tool Call（10個工具）
  └── MCP Adapter（Telegram）

近期目標（v9.0）
  ├── Multi-DB Provider（MySQL/PostgreSQL）
  ├── DB Alias 細粒度權限
  └── 提示詞管理界面

中期目標（v10.0）
  ├── Channel-Core 架構重構
  └── Task Scheduler

長期目標（v11.0+）
  ├── Multi-Channel（Line/Email/Slack）
  └── Agent Marketplace（社群 MCP 技能市場）

文件由 Antigravity AI 整理自 git history（共 367 commits），最後更新：2026-06-19