{"id":39817989,"url":"https://github.com/kkdai/linebot-gemini-file-search","last_synced_at":"2026-01-18T12:53:08.296Z","repository":{"id":323005510,"uuid":"1091742675","full_name":"kkdai/linebot-gemini-file-search","owner":"kkdai","description":"LINE Bot with Google Gemini File Search","archived":false,"fork":false,"pushed_at":"2025-11-23T11:21:15.000Z","size":162,"stargazers_count":33,"open_issues_count":1,"forks_count":9,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-23T13:11:09.890Z","etag":null,"topics":["gemini","gemini-file-search","linebot"],"latest_commit_sha":null,"homepage":"https://www.evanlin.com/linebot-gemini-file-search/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kkdai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-07T13:03:04.000Z","updated_at":"2025-11-23T11:21:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kkdai/linebot-gemini-file-search","commit_stats":null,"previous_names":["kkdai/linebot-gemini-file-search"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kkdai/linebot-gemini-file-search","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkdai%2Flinebot-gemini-file-search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkdai%2Flinebot-gemini-file-search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkdai%2Flinebot-gemini-file-search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkdai%2Flinebot-gemini-file-search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kkdai","download_url":"https://codeload.github.com/kkdai/linebot-gemini-file-search/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkdai%2Flinebot-gemini-file-search/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28536554,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T10:13:46.436Z","status":"ssl_error","status_checked_at":"2026-01-18T10:13:11.045Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gemini","gemini-file-search","linebot"],"created_at":"2026-01-18T12:53:08.088Z","updated_at":"2026-01-18T12:53:08.237Z","avatar_url":"https://github.com/kkdai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LINE Bot 智能文件助手 📚\n\n\u003e 一個結合 LINE Bot 與 Google Gemini File Search 的智能文件問答機器人\n\n\u003cimg width=\"1179\" height=\"2556\" alt=\"image\" src=\"https://github.com/user-attachments/assets/4d5a4e0e-0eec-4753-a1b0-8b1e1e6d661a\" /\u003e\n\n\n## 🎯 這是什麼？\n\n想像一下：你可以把任何 PDF、Word 文件、圖片傳給 LINE Bot，然後直接問它「這份文件在講什麼？」、「幫我整理重點」、「這張圖片裡有什麼？」，Bot 就會用 AI 幫你分析並回答！\n\n這個專案讓你輕鬆打造一個專屬的文件智能助手，只要：\n1. 📤 傳送文件或圖片給 Bot\n2. 💬 用自然語言提問\n3. 🤖 AI 立即分析並回答\n\n## ✨ 功能特色\n\n### 📁 支援多種檔案格式\n- 📄 文件檔案：PDF、Word (DOC/DOCX)、PowerPoint (PPT/PPTX)、純文字 (TXT) 等\n  - 自動上傳到 File Search Store\n  - 支援後續文字查詢\n  - **自動轉換功能**：\n    - .doc 格式自動轉換為 .docx\n    - .ppt 格式自動轉換為 .pptx\n- 🖼️ 圖片檔案：JPG、PNG 等\n  - 使用 Gemini 視覺理解能力即時分析\n  - 無需上傳，直接回傳分析結果\n\n### 🧠 AI 智能問答\n- 使用 Google Gemini 2.5 Flash 模型\n- 基於你上傳的文件內容回答問題\n- 支援繁體中文、英文等多語言\n\n### 💬 對話記憶功能 🆕\n- **記住對話歷史**：AI 會記得之前的對話內容，支援追問和延伸討論\n- **自動上下文理解**：使用 Google ADK Chat Session 技術\n- **智能 Session 管理**：\n  - 每位用戶獨立的對話記憶\n  - 自動超時清理（1小時無活動）\n  - 手動清除指令：輸入「清除對話」、「reset」或「clear」\n- **無縫整合 File Search**：對話記憶與文件搜尋完美結合\n\n### 👥 多人協作支援\n- **1 對 1 聊天**：每個人有自己的文件庫（隔離的），所有訊息都會回覆\n- **群組聊天**：\n  - 群組成員共享文件庫（大家都能查詢）\n  - **需要 @提及（mention）機器人才會回覆文字訊息**\n  - 上傳檔案/圖片不需要 mention，會自動處理\n  - 回覆訊息會顯示在群組中，所有成員都看得到\n- 自動識別對話類型，無需手動設定\n\n### 📋 檔案管理功能\n- **AI 口語化列表**：使用 Google ADK Agent 以自然對話方式介紹檔案\n- **智能識別**：支援多種關鍵字（列出檔案、顯示檔案、list files 等）\n- **Quick Reply 快速操作**：上傳成功後提供「生成摘要」、「重點整理」等快捷按鈕\n- **明確檔案指定**：Quick Reply 自動帶入檔案名稱，避免混淆\n- **檔案刪除**：每個檔案都有刪除按鈕，輕鬆管理文件庫\n\n### 🚀 部署簡單\n- 支援 Docker 容器化部署\n- 可部署到 Google Cloud Run\n- 或在本地開發測試\n\n### 🔮 未來規劃\n更多精彩功能正在開發中！查看 [功能開發計畫](./features.md) 了解即將推出的新功能。\n\n## 📸 使用範例\n\n### 📤 上傳文件並查詢\n\n```\n👤 你: [上傳一份會議記錄.pdf]\n🤖 Bot: ✅ 檔案已成功上傳！\n       檔案名稱：會議記錄.pdf\n\n       現在您可以詢問我關於這個檔案的任何問題。\n\n       [Quick Reply 按鈕]\n       📝 生成檔案摘要 | 📌 重點整理 | 📋 列出檔案\n\n👤 你: [點擊「📝 生成檔案摘要」]\n     → 自動發送「請幫我生成「會議記錄.pdf」這個檔案的摘要」\n\n🤖 Bot: 好的！這份會議記錄主要記錄了 2025 年第一季的營運會議...\n\n       主要決議包括：\n       1. 下季度預算增加 15%\n       2. 新產品預計 6 月上市\n       3. 人力資源部門將擴編 3 名員工\n       ...\n```\n\n### 🔄 自動轉換 .doc 檔案\n\n```\n👤 你: [上傳舊版報告.doc]\n🤖 Bot: 正在處理您的檔案，請稍候...\n\n🤖 Bot: 🔄 偵測到 .doc 格式，正在自動轉換為 .docx...\n\n🤖 Bot: ✅ 檔案已成功上傳！\n       檔案名稱：舊版報告.docx\n\n       📝 註：檔案已自動從 .doc 轉換為 .docx 格式\n\n       現在您可以詢問我關於這個檔案的任何問題。\n\n       [Quick Reply 按鈕]\n       📝 生成檔案摘要 | 📌 重點整理 | 📋 列出檔案\n\n👤 你: 這份報告的重點是什麼？\n🤖 Bot: 好的！這份報告主要討論...\n```\n\n\u003e 💡 **自動轉換功能**：系統使用 LibreOffice 自動將 .doc 轉換為 .docx，無需手動操作！\n\n### 📊 自動轉換 .ppt 簡報檔\n\n```\n👤 你: [上傳季度報告.ppt]\n🤖 Bot: 正在處理您的檔案，請稍候...\n\n🤖 Bot: 🔄 偵測到 .ppt 格式，正在自動轉換為 .pptx...\n\n       ⏳ PPT 檔案較大，轉換可能需要 10-30 秒，請稍候...\n\n🤖 Bot: ✅ 檔案已成功上傳！\n       檔案名稱：季度報告.pptx\n\n       📊 註：檔案已自動從 .ppt 轉換為 .pptx 格式\n\n       現在您可以詢問我關於這個檔案的任何問題。\n\n       [Quick Reply 按鈕]\n       📝 生成檔案摘要 | 📌 重點整理 | 📋 列出檔案\n\n👤 你: 這份簡報的主要內容是什麼？\n🤖 Bot: 這份季度報告簡報包含以下重點：\n       1. 第一季營收達成率 120%\n       2. 新產品市場反應良好\n       3. 下季度策略規劃...\n```\n\n\u003e 💡 **PPT 轉換說明**：\n\u003e - 保留文字、圖片、表格內容\n\u003e - 動畫效果可能遺失\n\u003e - 轉換時間視檔案大小而定（通常 10-30 秒）\n\u003e - PPTX 格式可直接上傳，無需轉換\n\n### 💬 多輪對話記憶 🆕\n\n```\n👤 你: 這份 Q1 報告的營收是多少？\n🤖 Bot: 根據 Q1 報告，營收為 NT$ 12,000,000，\n       相比去年同期成長了 18%。\n\n👤 你: 那成本呢？\n🤖 Bot: （記得你在問 Q1 報告）\n       Q1 的總成本為 NT$ 8,500,000，\n       營運成本佔比 45%，人力成本佔比 35%。\n\n👤 你: 淨利率是多少？\n🤖 Bot: （知道你在討論 Q1 的財務數據）\n       Q1 的淨利率為 29.2%\n       （營收 1200萬 - 成本 850萬 = 淨利 350萬）\n\n👤 你: 清除對話\n🤖 Bot: ✅ 對話記憶已清除。我們可以重新開始對話了！\n```\n\n\u003e 💡 **對話記憶說明**：\n\u003e - AI 會記住整個對話歷史，理解「那」、「它」等代詞\n\u003e - 支援追問和延伸討論，無需重複完整問題\n\u003e - 輸入「清除對話」、「reset」或「clear」可清除記憶\n\u003e - 1小時無活動會自動清除（節省資源）\n\n### 📋 列出檔案（AI 口語化）\n\n```\n👤 你: 列出檔案\n🤖 Bot: 我看到你上傳了 3 個檔案唷！\n\n       首先是「會議記錄.pdf」，這是在 1月8日下午2點半上傳的。\n       接著是「技術文件.docx」，是在下午3點20分傳的。\n       最後一個是「報告.txt」，這個是在下午4點10分上傳的。\n\n       需要我幫你查詢哪個檔案的內容呢？😊\n```\n\n\u003e 💡 **提示**：使用 Google ADK Agent 讓 AI 用自然對話方式介紹檔案，比傳統的清單或卡片更親切！\n\n### 🗑️ 刪除檔案\n\n```\n👤 你: 列出檔案\n🤖 Bot: [顯示檔案列表，每個檔案都有刪除按鈕]\n\n       ┌─────────────────────┐\n       │ 會議記錄.pdf        │\n       │ 2025-01-08 14:30    │\n       │ [🗑️ 刪除檔案]      │\n       └─────────────────────┘\n\n👤 你: [點擊 🗑️ 刪除檔案]\n🤖 Bot: ✅ 檔案已刪除成功！\n\n       如需查看剩餘檔案，請點擊下方按鈕。\n```\n\n\u003e 💡 **檔案刪除說明**：\n\u003e - 每個檔案都有紅色的刪除按鈕\n\u003e - 刪除是永久性的，無法復原\n\u003e - 刪除後會立即從文件庫移除\n\n### 🖼️ 圖片分析\n\n```\n👤 你: [傳送圖片]\n🤖 Bot: 正在分析您的圖片，請稍候...\n\n🤖 Bot: 📸 圖片分析結果：\n\n       這張圖片顯示了一個現代化的辦公室空間...\n```\n\n### 👥 群組聊天使用\n\n```\n[在群組中]\n\n👤 Alice: [上傳 Q1報告.pdf]\n🤖 Bot: ✅ 檔案已成功上傳！\n       檔案名稱：Q1報告.pdf\n\n       現在您可以詢問我關於這個檔案的任何問題。\n       📝 生成檔案摘要 | 📌 重點整理 | 📋 列出檔案\n\n👤 Bob: 這份報告的結論是什麼？\n（Bot 不回覆，因為沒有 mention）\n\n👤 Charlie: @bot 這份報告的結論是什麼？\n🤖 Bot: 根據 Q1 報告，主要結論如下：\n       1. 營收成長 20%\n       2. 客戶滿意度提升到 90%\n       3. 新產品線表現優異\n       ...\n\n👤 Alice: @bot 列出檔案\n🤖 Bot: 我看到這個群組上傳了 1 個檔案唷！\n\n       是「Q1報告.pdf」，這是在今天下午3點上傳的。\n       需要我幫你查詢這個檔案的內容嗎？😊\n```\n\n\u003e 💡 **群組使用重點**：\n\u003e - ✅ 上傳檔案/圖片：直接上傳，無需 mention\n\u003e - ⚠️ 查詢文件：需要 @機器人\n\u003e - ✅ 所有成員共享文件庫\n\n## 🛠️ 技術架構\n\n- **Python 3.9+**\n- **FastAPI** - 高效能異步 Web 框架\n- **LINE Messaging API** - LINE Bot 介面（含 Quick Reply）\n- **Google Gemini API** - 文件搜尋與 AI 問答\n- **Google ADK (Agent Development Kit)** - 口語化檔案管理 Agent\n- **Docker** - 容器化部署\n\n## 📦 快速開始\n\n### 1️⃣ 環境準備\n\n首先，你需要準備這些：\n\n**LINE Bot 設定**\n1. 到 [LINE Developers Console](https://developers.line.biz/console/) 建立一個 Messaging API channel\n2. 取得你的 `Channel Secret` 和 `Channel Access Token`\n\n**Google Gemini API**\n1. 到 [Google AI Studio](https://aistudio.google.com/app/apikey) 建立 API Key\n2. 複製你的 `API Key`\n\n### 2️⃣ 下載專案\n\n```bash\ngit clone \u003c你的 repo URL\u003e\ncd linebot-file-search-adk\n```\n\n### 3️⃣ 安裝套件\n\n```bash\npip install -r requirements.txt\n```\n\n**額外依賴：LibreOffice（用於 .doc 和 .ppt 格式轉換）**\n\n為了支援舊版 .doc 和 .ppt 檔案的自動轉換，需要安裝 LibreOffice：\n\n```bash\n# macOS\nbrew install --cask libreoffice\n\n# Ubuntu/Debian\nsudo apt-get update\nsudo apt-get install -y libreoffice libreoffice-impress\n\n# 驗證安裝\nsoffice --version\n```\n\n\u003e 💡 **注意**：如果未安裝 LibreOffice，.doc 和 .ppt 檔案將無法上傳，但其他格式（.docx, .pptx, .pdf 等）仍可正常使用。\n\n### 4️⃣ 設定環境變數\n\n建立 `.env` 檔案或直接設定環境變數：\n\n```bash\nexport ChannelSecret=\"你的 LINE Channel Secret\"\nexport ChannelAccessToken=\"你的 LINE Channel Access Token\"\nexport GOOGLE_API_KEY=\"你的 Google Gemini API Key\"\n```\n\n### 5️⃣ 啟動服務\n\n```bash\nuvicorn main:app --reload\n```\n\n服務會在 `http://localhost:8000` 啟動\n\n### 6️⃣ 設定 Webhook\n\n如果在本地開發，使用 ngrok 來建立公開的網址：\n\n```bash\nngrok http 8000\n```\n\n然後到 LINE Developers Console，把 Webhook URL 設定為：\n```\nhttps://你的-ngrok-網址.ngrok.io/\n```\n\n## 🎮 使用方式\n\n### 📱 在不同對話中使用\n\n**1 對 1 聊天**：\n- ✅ 直接發送訊息，無需 mention\n- ✅ 每個人有獨立的文件庫\n- ✅ 所有訊息都會得到回覆\n\n**群組聊天**：\n- ✅ **上傳檔案/圖片**：直接上傳，無需 mention\n- ⚠️ **查詢文件內容**：需要 @提及（mention）機器人\n- ✅ 回覆訊息會顯示在群組中\n- ✅ 所有成員共享同一個文件庫\n\n\u003e 💡 **群組使用提示**：在群組中查詢文件時，記得要 @機器人，例如：「@bot 這份報告的結論是什麼？」\n\n### 📤 上傳檔案\n\n**文件檔案（PDF、DOCX、TXT 等）：**\n1. 直接在 LINE 聊天室傳送文件檔案（**群組中無需 mention**）\n2. Bot 會回覆「正在處理您的檔案，請稍候...」\n3. 上傳完成後會顯示「✅ 檔案已成功上傳！」\n4. 現在可以開始提問關於文件的內容\n   - **1對1**：直接提問\n   - **群組**：需要 @機器人\n\n**圖片檔案（JPG、PNG 等）：**\n1. 直接在 LINE 聊天室傳送圖片（**群組中無需 mention**）\n2. Bot 會回覆「正在分析您的圖片，請稍候...」\n3. 立即收到圖片分析結果\n4. 圖片不會儲存，每次都是即時分析\n\n### 💬 開始提問\n\n**1 對 1 聊天（直接提問）：**\n\n- 「這份文件的重點是什麼？」\n- 「幫我整理成條列式」\n- 「第三章在講什麼？」\n- 「根據這份報告，我們應該注意什麼？」\n\n**群組聊天（需要 mention）：**\n\n- 「@bot 這份文件的重點是什麼？」\n- 「@bot 幫我整理成條列式」\n- 「@bot 第三章在講什麼？」\n- 「@bot 根據這份報告，我們應該注意什麼？」\n\n**圖片分析（直接傳圖片，無需 mention）：**\n\n- 傳送圖片後自動分析\n- 會描述圖片的內容、場景、物品、文字等\n- 無需額外提問\n\n### 📋 管理已上傳的檔案\n\n**列出檔案（AI 口語化）：**\n\n支援多種關鍵字來查看已上傳的文件：\n- 「列出檔案」或「列出文件」\n- 「顯示檔案」或「查看檔案」\n- 「我的檔案」或「檔案列表」\n- 英文：「list files」、「show files」、「my files」\n\n**使用方式**：\n- **1對1**：直接輸入「列出檔案」\n- **群組**：輸入「@bot 列出檔案」\n\nBot 會用 **Google ADK Agent** 以自然對話方式介紹檔案：\n- 🤖 口語化描述（而非條列式清單）\n- 📅 自動格式化上傳時間\n- 💬 友善親切的語氣\n- 🎯 智能總結（檔案多時會挑重點說明）\n\n**Quick Reply 快速操作：**\n\n上傳檔案成功後，Bot 會提供快捷按鈕：\n- 📝 **生成檔案摘要** - 自動帶入檔案名稱「請幫我生成『檔名』這個檔案的摘要」\n- 📌 **重點整理** - 自動帶入檔案名稱「請幫我整理『檔名』的重點」\n- 📋 **列出檔案** - 查看所有已上傳的文件\n\n\u003e 💡 **提示**：\n\u003e - Quick Reply 會自動帶入剛上傳的檔案名稱，避免多檔案時的混淆\n\u003e - **在群組中點擊 Quick Reply 後，仍需手動加上 @機器人**\n\n### 📁 檔案管理方式\n\n**文件檔案：**\n- **1對1 聊天**：\n  - 每個人有獨立的文件庫（`user_U123456`）\n  - 只能查詢自己上傳的檔案\n  - 完全隔離，保護隱私\n- **群組聊天**：\n  - 所有群組成員共享同一個文件庫（`group_G123456`）\n  - 任何人上傳的檔案都能被查詢\n  - **注意**：群組中的文件對所有成員公開\n- 文件會持續保存在 File Search Store 中\n\n**圖片檔案：**\n- 不會儲存到 File Search Store\n- 每次傳送都是即時分析\n- 分析完成後圖片會自動清除\n\n\u003e ⚠️ **隱私提醒**：如果需要查詢私密文件，請在 1對1 聊天中上傳，避免在群組中分享敏感資料。\n\n## 🐳 Docker 部署\n\n### 建立映像檔\n\n```bash\ndocker build -t linebot-file-search .\n```\n\n### 啟動容器\n\n```bash\ndocker run -p 8000:8000 \\\n  -e ChannelSecret=你的SECRET \\\n  -e ChannelAccessToken=你的TOKEN \\\n  -e GOOGLE_API_KEY=你的API_KEY \\\n  linebot-file-search\n```\n\n## ☁️ 部署到 Google Cloud Run\n\n### 步驟 1：安裝 Google Cloud SDK\n\n參考[官方文件](https://cloud.google.com/sdk/docs/install)安裝\n\n### 步驟 2：登入並設定專案\n\n```bash\ngcloud auth login\ngcloud config set project 你的專案ID\n```\n\n### 步驟 3：建立並上傳 Docker 映像\n\n```bash\ngcloud builds submit --tag gcr.io/你的專案ID/linebot-file-search\n```\n\n### 步驟 4：部署到 Cloud Run\n\n```bash\ngcloud run deploy linebot-file-search \\\n  --image gcr.io/你的專案ID/linebot-file-search \\\n  --platform managed \\\n  --region asia-east1 \\\n  --allow-unauthenticated \\\n  --set-env-vars ChannelSecret=你的SECRET,ChannelAccessToken=你的TOKEN,GOOGLE_API_KEY=你的API_KEY\n```\n\n### 步驟 5：取得服務網址\n\n```bash\ngcloud run services describe linebot-file-search \\\n  --platform managed \\\n  --region asia-east1 \\\n  --format 'value(status.url)'\n```\n\n把這個網址設定到 LINE Bot 的 Webhook URL 就完成了！\n\n## 🔒 安全性建議\n\n**不要把敏感資訊寫進程式碼！** 建議使用 Google Secret Manager：\n\n```bash\n# 建立 secrets\necho -n \"你的SECRET\" | gcloud secrets create line-channel-secret --data-file=-\necho -n \"你的TOKEN\" | gcloud secrets create line-channel-token --data-file=-\necho -n \"你的API_KEY\" | gcloud secrets create google-api-key --data-file=-\n```\n\n部署時使用 secrets：\n\n```bash\ngcloud run deploy linebot-file-search \\\n  --image gcr.io/你的專案ID/linebot-file-search \\\n  --platform managed \\\n  --region asia-east1 \\\n  --allow-unauthenticated \\\n  --update-secrets=ChannelSecret=line-channel-secret:latest,ChannelAccessToken=line-channel-token:latest,GOOGLE_API_KEY=google-api-key:latest\n```\n\n## 📊 監控與除錯\n\n部署後可以透過 Google Cloud Console 監控：\n\n### 查看 Logs\n\n```bash\ngcloud logging read \"resource.type=cloud_run_revision AND resource.labels.service_name=linebot-file-search\" --limit 50\n```\n\n### 檢查服務狀態\n\n直接到 [Cloud Run Console](https://console.cloud.google.com/run) 查看服務狀態、錯誤率、回應時間等指標\n\n## 💡 使用小技巧\n\n1. **上傳多份文件**：可以連續上傳多份文件，Bot 會記住所有文件並在查詢時搜尋\n2. **圖片即時分析**：圖片不需要「上傳」，直接傳送就會立即分析並回覆\n3. **文件持久化**：上傳的文件會持續保存在 File Search Store，可隨時查詢\n4. **Quick Reply 快捷操作**：\n   - 上傳檔案後立即使用 Quick Reply 按鈕（生成摘要、重點整理）\n   - Quick Reply 會自動帶入檔案名稱，避免多檔案時混淆\n   - 點擊按鈕比手動輸入更快速方便\n5. **AI 口語化檔案列表**：\n   - 輸入「列出檔案」會得到自然對話式的回應\n   - AI 會用親切的語氣介紹每個檔案和上傳時間\n   - 比傳統清單更友善、更易讀\n6. **支援的檔案類型**：\n   - 文件：PDF、Word (DOC/DOCX)、PowerPoint (PPT/PPTX)、TXT、Markdown、HTML、CSV、RTF 等\n   - 圖片：JPG、JPEG、PNG、GIF、WebP\n   - **自動轉換**：\n     - .doc 檔案自動轉換為 .docx（2-5秒）\n     - .ppt 檔案自動轉換為 .pptx（10-30秒）\n7. **Loading 動畫優化體驗** 🆕：\n   - 上傳檔案時自動顯示 LINE 官方 loading 動畫\n   - 根據檔案類型智能調整顯示時間（圖片 15s / 文件 30s / PPT 60s）\n   - 讓用戶清楚知道 Bot 正在處理中\n\n## 🤔 常見問題\n\n### 基本使用\n\n**Q: 為什麼我問問題時 Bot 說「您還沒有上傳任何檔案」？**\nA: 這個訊息是針對文件查詢。請先上傳文件檔案（PDF、DOCX 等），Bot 才能根據文件內容回答。如果您想分析圖片，請直接傳送圖片，無需上傳。\n\n**Q: 圖片和文件的處理有什麼不同？**\nA:\n- **文件**：會上傳到 File Search Store，可以後續查詢，適合需要反覆查詢的資料\n- **圖片**：即時分析後立即清除，適合快速了解圖片內容\n\n**Q: 檔案會保存多久？**\nA: 文件檔案會持續保存在 Google Gemini 的 File Search Store，圖片分析後會立即清除。\n\n**Q: 支援哪些語言？**\nA: Google Gemini 支援多種語言，包括繁體中文、簡體中文、英文、日文等。\n\n**Q: 可以處理多大的檔案？**\nA: 取決於 Google Gemini File API 的限制，一般文件都沒問題。圖片建議不超過 10MB。\n\n**Q: 支援舊版 .doc 格式嗎？**\nA: **支援**！系統會自動使用 LibreOffice 將 .doc 轉換為 .docx 格式再上傳。轉換過程完全自動化，無需手動操作。如果轉換失敗（例如未安裝 LibreOffice），系統會提示您手動轉換。\n\n**Q: .doc 轉換需要多久時間？**\nA: 通常只需要幾秒鐘。系統會顯示「🔄 偵測到 .doc 格式，正在自動轉換為 .docx...」的訊息。檔案過大時可能需要更長時間（最多 60 秒超時限制）。\n\n**Q: 支援舊版 .ppt 格式嗎？**\nA: **支援**！系統會自動使用 LibreOffice 將 .ppt 轉換為 .pptx 格式再上傳。PPTX 格式可直接上傳無需轉換。轉換過程完全自動化，會保留文字、圖片、表格等內容，但動畫效果可能遺失。\n\n**Q: .ppt 轉換需要多久時間？**\nA: PPT 檔案通常較大，轉換時間約 10-30 秒。系統會顯示「🔄 偵測到 .ppt 格式，正在自動轉換為 .pptx...」並提示預計等待時間。超大檔案（\u003e50MB）或內容複雜時可能需要更長時間（最多 120 秒超時限制）。\n\n### 對話記憶功能 🆕\n\n**Q: 對話記憶是什麼？**\nA: Bot 會記住你們之前的對話內容，讓你可以追問和延伸討論，不需要每次都重複完整的問題。例如問完「Q1 報告的營收是多少？」後，可以直接問「那成本呢？」，Bot 會知道你在問 Q1 報告的成本。\n\n**Q: 對話記憶會保存多久？**\nA: 每個用戶的對話記憶會保存 1 小時。如果 1 小時內沒有任何活動，系統會自動清除記憶以節省資源。你也可以隨時輸入「清除對話」、「reset」或「clear」來手動清除。\n\n**Q: 群組聊天的對話記憶是共享的嗎？**\nA: 是的。同一個群組內的所有成員共享對話記憶，任何人的提問都會被記錄。這讓團隊討論更順暢。但每個用戶在 1 對 1 聊天時有自己獨立的記憶。\n\n**Q: 如何清除對話記憶？**\nA: 輸入以下任一指令即可：\n- 「清除對話」\n- 「清除对话」（簡體）\n- 「reset」\n- 「clear」\n- 「重置對話」\n- 「清空對話」\n\n**Q: 對話記憶會影響費用嗎？**\nA: 對話記憶會讓每次 API 調用包含歷史對話，可能增加 token 使用量。但我們已設置 1 小時自動清除機制來控制成本。如果你想進一步節省費用，可以在討論完一個主題後手動清除對話。\n\n**Q: PPT 轉換會保留動畫和特效嗎？**\nA: 文字、圖片、表格等內容會完整保留，但動畫效果、轉場特效、嵌入影片可能會遺失。如果需要完整格式，建議使用 Microsoft PowerPoint 手動將 .ppt 另存為 .pptx 格式後再上傳。\n\n### 群組使用\n\n**Q: 為什麼在群組中 Bot 不回覆我的問題？**\nA: 在群組聊天中，Bot **只會在被 @提及（mention）時回覆文字訊息**。請確保你的訊息中有 @機器人，例如：「@bot 這份報告的結論是什麼？」\n\n**Q: 在群組中上傳檔案需要 mention 嗎？**\nA: **不需要**！上傳檔案或圖片時不需要 mention，Bot 會自動處理。只有**查詢文件內容**時才需要 @機器人。\n\n**Q: 群組中上傳檔案後，為什麼我收到私訊？**\nA: 這個問題已經修復！現在群組中上傳檔案後，成功訊息會顯示在群組中，所有成員都看得到。\n\n**Q: 群組聊天中，其他人上傳的檔案我也能查詢嗎？**\nA: **可以**！群組中所有成員共享同一個文件庫。但要記得 @機器人才能查詢，例如：「@bot 列出檔案」\n\n**Q: 在群組中點擊 Quick Reply 按鈕後還需要 mention 嗎？**\nA: **需要**！Quick Reply 會自動帶入問題文字，但在群組中仍需要手動加上 @機器人。例如點擊「生成檔案摘要」後，需要改成「@bot 請幫我生成...」\n\n**Q: 群組中的文件會被其他成員看到嗎？**\nA: **會**！群組中所有成員共享同一個文件庫，任何人上傳的文件都可以被查詢。如果需要查詢私密文件，請在 1對1 聊天中上傳。\n\n### 功能相關\n\n**Q: Quick Reply 按鈕是什麼？**\nA: Quick Reply 是上傳檔案成功後出現的快捷按鈕（📝 生成檔案摘要、📌 重點整理、📋 列出檔案）。點擊按鈕會自動發送完整問題，比手動輸入更方便，且會自動帶入檔案名稱避免混淆。\n\n**Q: 為什麼列出檔案時不是顯示清單或卡片？**\nA: 我們使用 Google ADK Agent 讓 AI 用自然對話方式介紹檔案，而非傳統的條列式清單或卡片。這樣的呈現更友善、更像真人對話，使用者體驗更好。AI 會根據檔案數量智能調整說明方式。\n\n**Q: 如何自訂 Quick Reply 按鈕的文字？**\nA: 在 `main.py` 的 `handle_document_message()` 函數中可以修改 Quick Reply 的設定。你可以調整按鈕的 `label`（顯示文字）和 `text`（發送內容）。\n\n## 🔧 進階設定\n\n### 修改 AI 模型\n\n在 `main.py` 第 51 行可以修改使用的模型：\n\n```python\nMODEL_NAME = \"gemini-2.5-flash\"  # 可改成其他 Gemini 模型\n```\n\n### 調整文件查詢的回應溫度\n\n在 `main.py` 約第 220 行可以調整 AI 的創意程度：\n\n```python\ntemperature=0.7,  # 0.0 = 保守精確, 1.0 = 創意發散\n```\n\n### 自訂圖片分析的提示詞\n\n在 `main.py` 約第 270 行可以修改圖片分析的提示：\n\n```python\ncontents=[\"請詳細描述這張圖片的內容，包括主要物品、場景、文字等資訊。\", image],\n```\n\n可以改成：\n- `\"請用英文描述這張圖片\"` - 英文回應\n- `\"這張圖片中有哪些文字？\"` - 專注於 OCR\n- `\"這張圖片的主題是什麼？\"` - 摘要式回應\n\n### 自訂 Quick Reply 按鈕\n\n在 `main.py` 的檔案上傳成功處理部分（約第 447-452 行）：\n\n```python\nquick_reply = QuickReply(items=[\n    QuickReplyButton(action=MessageAction(\n        label=\"📝 生成檔案摘要\",\n        text=f\"請幫我生成「{file_name}」這個檔案的摘要\"\n    )),\n    QuickReplyButton(action=MessageAction(\n        label=\"📌 重點整理\",\n        text=f\"請幫我整理「{file_name}」的重點\"\n    )),\n    QuickReplyButton(action=MessageAction(\n        label=\"📋 列出檔案\",\n        text=\"列出檔案\"\n    )),\n])\n```\n\n你可以：\n- 修改 `label` 來改變按鈕顯示文字\n- 修改 `text` 來改變點擊後發送的內容\n- 新增或移除按鈕（LINE 限制最多 13 個）\n- 使用 `{file_name}` 變數來自動帶入檔案名稱\n\n### 自訂 FileManagerAgent 的語氣和風格\n\n在 `file_manager_agent/agent.py` 中修改 agent instruction（約第 24-33 行）：\n\n```python\ninstruction=\"\"\"你是一個友善的檔案管理助手。\n\n當使用者要求列出檔案時：\n1. 使用 list_files tool 來取得檔案清單\n2. 用口語化、友善的方式呈現結果\n3. 不要使用條列式或表格，用自然的對話方式說明\n4. 例如：「我看到你上傳了 3 個檔案唷！首先是『會議記錄.pdf』...」\n5. 語氣要輕鬆、親切\n\n回應時請用繁體中文。\"\"\"\n```\n\n你可以調整：\n- **語氣風格**：從「親切」改為「專業」、「幽默」等\n- **語言**：改為英文或其他語言\n- **呈現方式**：要求 AI 用特定格式（如分類、排序等）\n- **細節程度**：決定要說明到多詳細\n\n## 📝 授權條款\n\nMIT License - 歡迎自由使用、修改、分享！\n\n## 🙌 貢獻\n\n歡迎提交 Issue 或 Pull Request！\n\n## 📚 相關連結\n\n### 官方文件\n- [Google Gemini File Search 官方文件](https://ai.google.dev/gemini-api/docs/file-search?hl=zh-tw)\n- [Google ADK (Agent Development Kit) 文件](https://ai.google.dev/gemini-api/docs/adk)\n- [LINE Messaging API 文件](https://developers.line.biz/en/docs/messaging-api/)\n- [LINE Messaging API - Quick Reply](https://developers.line.biz/en/docs/messaging-api/using-quick-reply/)\n- [LINE Messaging API - Mention Object](https://developers.line.biz/en/reference/messaging-api/#mention-object)\n- [FastAPI 文件](https://fastapi.tiangolo.com/)\n\n### 專案文件\n- [features.md](./features.md) - 功能開發計畫與路線圖 🔮\n- [GROUP_USAGE_GUIDE.md](./GROUP_USAGE_GUIDE.md) - LINE Group 使用完整指南\n- [CHANGES_GROUP_SUPPORT.md](./CHANGES_GROUP_SUPPORT.md) - Group 支援變更摘要\n\n---\n\n⭐ 如果這個專案對你有幫助，請給個 Star 支持一下！\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkdai%2Flinebot-gemini-file-search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkkdai%2Flinebot-gemini-file-search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkdai%2Flinebot-gemini-file-search/lists"}