# Phase 0 Research & Decisions
所有需澄清項目已在規格階段解決，以下為關鍵技術決策彙總。
## 檢索 (Retrieval)
- Decision: Set-overlap 基線 + heading-aware chunk。
- Rationale: 最低實作成本、可預測、純函式易測。
- Alternatives considered: TF-IDF（延後導入, 增加計算與預處理）、向量嵌入（需外部模型與快取）。
## Tokenization / 多語支援
- Decision: 非字母數字邊界拆分 + 全半形/小寫正規化 + 英/中停用詞表 + 服務別名映射。
- Rationale: 輕量可維護，滿足第一階段需求。
- Alternatives: 專業中文斷詞庫（引入額外依賴與初始化成本；精度暫非瓶頸）。
## 風險指令分類
- Decision: 中央字典（≥20 核心危險動詞 / 操作）+ 正則前綴匹配；文件 risk_ops 陣列與抽取結果合併去重。
- Rationale: 保障一致性與可審計；字典可版本控管。
- Alternatives: 全文統計 + Heuristic 分數（偽陽率高）。
## Freshness 檢查
- Decision: Clock 注入 + ISO 日期解析；>90 天標記 stale；失敗加入 warnings。
- Rationale: 可測試、避免系統時間漂移干擾。
- Alternatives: 讀取系統時間直接比較（不利測試 determinism）。
## 降級策略
- Decision: LLM 缺失時 summary=null，保留 citations、risk segregation、stale 提示。
- Rationale: 完整保留安全與可追溯性。
- Alternatives: 直接拒答（降低可用性）。
## 衝突解決
- Decision: component > service > last_verified_at(desc) > path lexicographic。
- Rationale: 優先最精細範圍，確保新鮮度，最後 deterministic tie-break。
- Alternatives: 僅時間排序（忽略語義層級）。
## 結構化日誌
- Decision: MVP 僅 console.log(JSON)；欄位：timestamp, tool, latency_ms, result_class, stale_count。
- Rationale: 快速檢視與後續可抽換 logger。
- Alternatives: 導入 pino/winston（增加初期設定時間）。
## Citation 格式
- Decision: path + chunkIndex；後續可加 offset/token span。
- Rationale: 足以唯一回溯 chunk；保持精簡。
- Alternatives: 直接包含文字片段（重覆負擔、增回應大小）。
## 安全（Path Traversal）
- Decision: 正規化後拒絕含 .. 或 絕對磁碟前綴；僅允許在 root 下的相對路徑白名單。
- Rationale: 簡單且充分。
- Alternatives: 沙箱 FS 層 (fs jail) （超出 MVP 範圍）。
## 測試策略
- Decision: 單元（tokenize, chunk, score, classify, freshness, severity）+ 整合 (answer flow) + 基準 (100 runbooks mock) + 負面測試 (invalid frontmatter)。
- Rationale: 覆蓋核心純函式與端對端行為。
- Alternatives: 僅整合測試（定位困難）。
---
**All clarifications resolved: READY FOR PHASE 1.**
