emma-hermes/docs/shared-drive-file-access/README.md

Shared Drive File Access

這組文件用來定義：

• 同事如何透過 Hermes 以語意 / 模糊搜尋查找公槽檔案或資料夾
• 找到後如何以候選清單互動選擇
• 何時只回路徑、何時提供24 小時下載連結
• 資料夾如何改成最多 10 檔選取後壓縮
• 含個資 / 財務資料時，何時改成加密壓縮檔 + 分通道傳密碼

文件導覽

1. shared-drive-file-access-spec.md

   • 功能規格 + SOP
   • 對象、流程、限制、風險、例外處理

2. shared-drive-file-access-implementation-plan.md

   • 第一版實作規格
   • 資料模型、索引策略、下載流程、敏感檢查、回覆格式、落點模組

3. shared-drive-file-access-validation-matrix.md

   • MVP 驗收矩陣
   • 查找、打包、敏感加密、24h 下載、cleanup 驗證標準

4. shared-drive-file-access-reply-formats.md

   • 候選清單、選檔、下載完成、超限、風險提示回覆模板

5. shared-drive-index-v2-maintenance.md

   • 分批續掃索引器 v2 維護說明
   • 01:00~02:00 時窗、queue/cycle、續掃、手動介入方式

6. shared-drive-v2-validation-template-full.md

   • shared drive v2 驗收模板完整版
   • 適合內部工程驗收與留完整紀錄

7. shared-drive-v2-validation-template-compact.md

   • shared drive v2 驗收模板精簡版
   • 適合 Telegram / LINE / email 快速回報

目前已落地的 MVP 骨架腳本

• ~/.hermes/scripts/shared_drive_common.py
• ~/.hermes/scripts/shared_drive_index_build.py
• ~/.hermes/scripts/shared_drive_index_v2.py
• ~/.hermes/scripts/shared_drive_index_v2_daily.py
• ~/.hermes/scripts/shared_drive_content_extract.py
• ~/.hermes/scripts/shared_drive_content_extract_daily.sh
• ~/.hermes/scripts/shared_drive_index_query.py
• ~/.hermes/scripts/shared_drive_lookup.py
• ~/.hermes/scripts/shared_drive_delivery_bundle.py
• ~/.hermes/scripts/shared_drive_cleanup.py
• ~/.hermes/scripts/shared_drive_chat_workflow.py

目前可直接走的聊天工作流

1. shared_drive_chat_workflow.py search <query>
   • 產生可直接貼在聊天裡的候選清單
2. shared_drive_chat_workflow.py children <folder_file_id>
   • 展開資料夾並列出可選檔案（最多 10 檔）
3. shared_drive_chat_workflow.py bundle --file-ids ... --requester <email>
   • 直接打包 / 驗證 / 產出下載連結
4. shared_drive_chat_workflow.py search <query> --scope <path>
   • 當索引未命中時，改用使用者提供的更明確範圍做實地搜尋

目前已落地的 v2 維護方式

• 每天 01:00~02:00 內跑 queue-based index tick
• 超過 02:00 不開新一輪，隔天 01:00 繼續同一個 cycle
• 已建立靜默排程：shared-drive-index-v2-daily（job_id: db7af591579e）
• 已建立靜默排程：shared-drive-content-extract-daily（job_id: 8d81f84bc48e，02:20 跑低 token 增量內容抽取，避開 index v2 時窗）
• 若索引未命中，先請使用者提供更明確位置/範圍，再做 --scope 實地搜尋

低 token 內容索引補強

• shared_drive_content_extract.py 會把 pdf/docx/pptx/xlsx 與文字檔的可讀內容增量補進 content_extracts / files_fts
• 這一層不做 embeddings，也不批次呼叫 LLM 摘要，成本主要是本機 CPU / I/O，不是 token
• metadata/index 掃描仍由 shared-drive-index-v2-daily 負責；內容抽取則由 shared-drive-content-extract-daily 在後段接手

一句話版

推薦方案是：

• 先做共享槽 FTS / 摘要索引 + 候選清單互動
• 下載一律先複製到 Hermes 本機 staging，再產生 24h signed link
• 資料夾不整包外送，改成最多 10 檔選取後壓縮
• 命中個資 / 財務或無法可靠解析時，預設走加密壓縮檔