# Shared Drive Index v2 維護說明

## 目標

shared drive index v2 不是每日全掃，而是 **可續掃的分批索引器**。

設計目標：
- 每天只在 `01:00~02:00` 內工作
- 超過 `02:00` 不開新一輪
- 若還沒掃完，保留 queue 與 cycle，隔天 `01:00` 接著掃
- 避免超大公槽每天從頭重掃

---

## 核心腳本

- `~/.hermes/scripts/shared_drive_index_v2.py`
  - `tick`：跑一輪分批續掃
  - `status`：看目前 queue / cycle 狀態
  - `reset-root <root_type>`：清某個 root 的索引與掃描狀態
- `~/.hermes/scripts/shared_drive_index_v2_daily.py`
  - 給 cron 用的靜默 wrapper
  - 正常時不輸出
  - root 缺失或執行異常時才輸出告警文字

---

## 維護模式

### 1. 日常維護
排程：`01:00` 啟動 `shared_drive_index_v2_daily.py`

內部實際執行：
- `shared_drive_index_v2.py tick`
- 預設 time budget：`3540s`（約 59 分）
- 預設工作視窗：`01:00~02:00`

### 2. 續掃
若前一天沒掃完：
- 不重建新 cycle
- 不從頭開始
- 保留 `scan_queue` 與 `scan_state`
- 下一次 `01:00` 繼續同一個 `active_cycle_id`

### 3. 低頻 full rebuild
若懷疑索引飄移、殘影、或 schema 要重整，可手動跑：

```bash
python3 ~/.hermes/scripts/shared_drive_index_build.py --reset
```

這是校正用途，不是日常主流程。

---

## 目前狀態資料存放

都在 `shared_drive_index.db` 裡：
- `files`
- `content_extracts`
- `files_fts`
- `scan_state`
- `scan_queue`

另有：
- `~/.hermes/state/shared_drive_index/last_tick.json`

---

## 建議日常檢查

### 看狀態
```bash
python3 ~/.hermes/scripts/shared_drive_index_v2.py status
```

關鍵欄位：
- `status`
- `active_cycle_id`
- `processed_dirs`
- `indexed_entries`
- `queue_remaining`
- `last_error`

### 手動補跑一輪（忽略時窗）
```bash
python3 ~/.hermes/scripts/shared_drive_index_v2.py tick --ignore-window
```

### 重置單一 root
```bash
python3 ~/.hermes/scripts/shared_drive_index_v2.py reset-root project
```

---

## 何時該手動介入

### 1. queue 長期不下降
表示：
- 某些子樹太大
- 權限/IO 有問題
- 每日一小時預算不夠

可做：
- 提高 `--max-dirs-per-root`
- 提高 `--time-budget-seconds`
- 拆 root / 拆子資料夾

### 2. last_error 持續出現
先看：
- 路徑權限
- 掛載狀態
- 是否有異常檔名 / 無法讀取資料夾

### 3. 使用者找不到，但明明知道大概在哪
這時不要只信索引，改走：

```bash
python3 ~/.hermes/scripts/shared_drive_chat_workflow.py search <query> --scope <path>
```

也就是先請使用者提供更明確的共享槽 / 年份 / 品牌 / 專案資料夾，再做**實地搜尋**。

---

## 使用者查找 fallback 規則

如果索引內找不到：
1. 先請使用者提供更明確的位置或範圍
2. 再用 `search --scope <path>` 實地搜尋
3. 若找到候選，可直接回 `選取鍵` 或實際路徑
4. 交付時可走：

```bash
python3 ~/.hermes/scripts/shared_drive_chat_workflow.py bundle --paths /absolute/path/to/file --requester dk96@bremen.com.tw
```

---

## 目前已建立的排程
- `shared-drive-index-v2-daily`
- job_id: `db7af591579e`
- schedule: `0 1 * * *`
- delivery: `telegram`
- mode: `no_agent=true`

正常時靜默；異常時才送出訊息。
