Bremen
/
emma-hermes
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
emma-hermes/docs/shared-drive-file-access/shared-drive-file-access-im...

8.1 KiB
Raw Blame History

Shared Drive File Access 第一版實作規格

1. 實作目標

建立一條可重複、可驗證的執行路徑：

  • 使用者用自然語言 / 模糊描述找共享槽檔案
  • Hermes 回傳候選清單
  • 使用者選定單檔或從資料夾清單中最多選 10 檔
  • Hermes 複製到本機 staging
  • 視敏感度決定是否改成加密 zip
  • 產生 24 小時有效下載連結
  • 必要時另通道傳密碼

2. 建議架構

User query
  -> Retrieval orchestrator
      -> AI_Result local cache query path
      -> Shared-drive file index query path
  -> Candidate formatter
  -> User selection
  -> Delivery packager
      -> stage files locally
      -> inspect sensitivity
      -> zip / encrypted zip
      -> managed_downloads token URL
  -> Optional secondary-channel password delivery

3. 模組切分建議

A. 搜尋入口層

建議新腳本 / 模組：

  • scripts/shared_drive_lookup.py

責任：

  • 接收查詢字串
  • 先判斷是否偏 AI_Result 類問題
  • 決定走：
    • ai_result_nl_query.py / ai_result_cache_query.py
    • 或共享槽索引查詢
  • 輸出候選資料結構

B. 共享槽索引建置層

建議新腳本：

  • scripts/shared_drive_index_build.py

責任：

  • 掃描：
    • /Volumes/Project
    • /Volumes/Materials
    • /Volumes/media
  • 排除：
    • #recycle
  • 抽取：
    • path
    • filename
    • extension
    • size
    • mtime
    • root type
    • folder title tokens
    • content preview / summary（若可抽）
    • parseability
    • sensitivity hints
  • 寫入索引 DB

C. 索引查詢層

建議新腳本：

  • scripts/shared_drive_index_query.py

責任：

  • 對共享槽索引 DB 做 FTS / metadata query
  • 支援：
    • keyword match
    • filename fuzzy
    • folder fuzzy
    • content preview fuzzy
    • extension filters（可後續加）

D. 打包與交付層

建議新腳本：

  • scripts/shared_drive_delivery_bundle.py

責任：

  • 接收選定檔案清單
  • 檢查最多 10 檔
  • 複製到本機 staging
  • 做敏感檢查
  • 產生 zip / encrypted zip
  • 呼叫 managed download 產生 24 小時 URL

E. 密碼通知層

建議優先不做成獨立服務，先封裝 helper：

  • scripts/shared_drive_password_notice.py 或直接內嵌在 delivery bundle module

責任：

  • 決定 secondary channel
  • 產生短密碼
  • 發送到 email / 第二平台

4. 資料模型

索引 DB 建議

建議新建：

  • ~/.hermes/cache/shared_drive_index/shared_drive_index.db

Table: files

  • file_id TEXT PK
  • root_type TEXT -- project / materials / media / ai_result_optional
  • mac_path TEXT
  • windows_path TEXT
  • rel_path TEXT
  • file_name TEXT
  • file_ext TEXT
  • parent_dir TEXT
  • size_bytes INTEGER
  • mtime TEXT
  • is_dir INTEGER
  • parseability TEXT -- text / office / pdf_text / pdf_scan / image / binary / unknown
  • sensitivity_level TEXT -- low / high / unknown
  • contains_pii_hint INTEGER
  • contains_finance_hint INTEGER
  • download_allowed INTEGER
  • indexed_at TEXT

Table: content_extracts

  • file_id TEXT PK/FK
  • title_hint TEXT
  • summary_text TEXT
  • sample_text TEXT
  • keyword_json TEXT
  • extract_status TEXT

FTS table

建議：

  • files_fts

索引欄位：

  • file_name
  • parent_dir
  • rel_path
  • summary_text
  • sample_text
  • title_hint

Table: delivery_audit（可 Phase 1 就先做簡版）

  • bundle_id TEXT PK
  • requester TEXT
  • source_query TEXT
  • selected_count INTEGER
  • encrypted INTEGER
  • password_channel TEXT
  • download_url TEXT
  • expires_at TEXT
  • created_at TEXT

5. 敏感度判斷策略

第一版不要做太複雜的 NLP classifier

先做規則式即可。

規則來源

  • 檔名命中：
    • 報價 成本 財務 預算 invoice salary
  • 內容命中：
    • email pattern
    • phone pattern
    • 身分證樣式
    • 銀行資訊常見欄位
    • 財務表格詞
  • 無法可靠抽取內容：
    • 掃描 PDF
    • image-only
    • binary / unknown

決策

  • contains_pii_hint = 1 或 contains_finance_hint = 1 → high
  • parseability in ('pdf_scan','image','binary','unknown') → unknown
  • high 或 unknown → 預設加密 zip

6. 打包與下載規則

輸入規則

  • 單檔：1 檔
  • 資料夾模式：最多 10 檔
  • 不支援直接整個資料夾原樣外送

打包規則

  • 先複製到本機工作目錄，例如：
    • ~/.hermes/state/shared-drive-downloads/<bundle_id>/input/
  • 產物輸出到：
    • ~/.hermes/state/shared-drive-downloads/<bundle_id>/output/

zip 規則

  • 單檔非敏感：
    • 可直接 stage file 後出連結
  • 多檔或資料夾選取：
    • 一律 zip
  • 敏感或 unknown：
    • zip + password

下載規則

  • 呼叫 managed_downloads.build_public_download_url(file_path)
  • 但 token expiry 要指定為 24h = 86400 秒
  • 若 helper 尚未直接暴露 expiry 參數給外層，需新增 wrapper

清理規則

  • 交付後保留到 expiry 後一段緩衝期（例如 +2h）
  • 由 cron / cleanup job 清掉 staging 與 zip

7. 密碼產生與通知

密碼規則

  • 建議自動生成 10~14 字元隨機密碼
  • 避免只用數字

通知順序

  1. 若使用者有已綁定 email → 優先 email 傳密碼
  2. 若有第二訊息平台 → 可走第二平台
  3. 若無第二通道 → fail closed，要求確認

注意

  • 下載連結與密碼不可放同一封 email / 同一則訊息（若策略要求分通道）
  • 記錄 password_channel 進 audit

8. 回覆格式規格

候選清單格式

每筆建議含：

  • 序號
  • 名稱
  • 類型（檔案 / 資料夾）
  • 所在共享槽
  • 修改時間
  • 簡短說明
  • 路徑（Mac + Windows）
  • 可下載：是 / 否

選檔提示格式

  • 單檔：請選擇 1 個序號
  • 資料夾：請選擇最多 10 個檔案序號

下載完成格式

  • 檔名 / 壓縮檔名
  • 是否加密
  • 下載期限
  • 下載連結
  • 密碼另送說明（若有）

9. 排序與搜尋策略

第一版建議排序

  1. 檔名命中
  2. 父資料夾命中
  3. 內容摘要命中
  4. 修改時間較新
  5. AI_Result / 已知快取來源優先（視 query 類型）

Query expansion

第一版可加：

  • 中文全半形 normalize
  • _ - 空白 normalize
  • 大小寫 normalize
  • 常見 alias（品牌 / 客戶）

不建議第一版就做的事

  • embeddings 全量建置
  • OCR 全量重做
  • 跨檔 chunk vector retrieval

10. 風險與防呆

主要風險

  1. 誤把敏感資料當低風險
  2. 一次外送太多檔案
  3. 把原共享槽路徑直接當 public link
  4. token 過期但 staging 未清
  5. 密碼與連結落在同通道，保護效果不足

防呆策略

  • unknown parseability 預設加密
  • 資料夾模式限制 10 檔
  • 總大小上限
  • fail closed：無第二通道時不自動外送敏感包
  • 所有下載一律走 staging + token URL

11. 實作落點建議

可重用現有元件

  • hermes_cli/managed_downloads.py
  • scripts/ai_result_cache_query.py
  • scripts/ai_result_nl_query.py
  • scripts/ai_result_path_formatter.py（若路徑顯示需統一）

建議新增元件

  • scripts/shared_drive_index_build.py
  • scripts/shared_drive_index_query.py
  • scripts/shared_drive_lookup.py
  • scripts/shared_drive_delivery_bundle.py
  • scripts/shared_drive_cleanup.py

若要進一步整合 Hermes 工具層

後續可考慮新增一個非核心 plugin/tool，而不是先塞進 core tool schema。 原因：

  • 這能力高度公司客製
  • 與你們共享槽、下載政策、敏感規則綁很深
  • 適合 plugin / local skill + script，而不是 Hermes 通用核心工具

12. MVP 建議

MVP cut line

第一版只做：

  • 查詢
  • 候選清單
  • 單檔下載
  • 資料夾最多 10 檔打包
  • 24h link
  • 規則式敏感判斷
  • 敏感時加密 zip
  • email 傳密碼

暫緩項目

  • embeddings
  • OCR-heavy 判斷
  • per-user ACL 細粒度權限
  • 下載 dashboard UI
  • 自動化稽核報表

13. 最終推薦方案

推薦你直接做這個方案：

以 模式 3 + 本機 staging + 24h signed link + 敏感加密 為主線， 搜尋層先用共享槽 FTS/摘要索引，不急著上向量資料庫。

這是目前對你最實用、也最方便 Hermes 建製與驗證的第一版。