# Shared Drive File Access 第一版實作規格

## 1. 實作目標

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

---

## 2. 建議架構

```text
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 建製與驗證的第一版。
