# On-Call 百科（Runbook Encyclopedia）MCP Server 需求分析與任務清單
> 日期：2025-10-13
> 階段：需求分析與技術調研（尚未進入實作）
> 版本：v0.1 (Draft)
## 目標概述
建置一個透過 Markdown Runbook 知識庫提供 On-Call 支援的自訂 MCP Server，支援檢索、規則導向問答、清單/指令萃取、嚴重度判斷、交接與事後檢討模板，初期以本機檔案系統為資料來源，後續可抽換為遠端儲存（例如 Azure Blob / 既有 Proxy）。
## 範圍
- In Scope：MCP 工具集合（search/read/answer/checklist/commands/severity/handoff/postmortem）、MD frontmatter 規範、檢索與風險規則、LLM 回答降級機制。
- Out of Scope (本階段)：實際程式撰寫、部署、自動化審批寫回、跨雲儲存整合、權限控管、多租戶分隔。
## Use Cases（高優先）
1. On-Call 值班工程師快速搜尋特定故障症狀對應 Runbook。
2. 快速取得初步診斷與安全步驟 checklist。
3. 問答模式：使用者輸入自然語言問題→規則導向萃取/LLM 回答→引用來源段落。
4. 事件升級：依症狀描述判斷建議 SEV 等級與通知通道。
5. 交接：生成簡潔狀態與下一步摘要。
6. 事後檢討：自動產出 Postmortem 範本骨架。
## 需求明細
### 功能性需求 (FR)
- FR1: 支援關鍵字多詞檢索，回傳 Top K 文件或分段分數。
- FR2: 可讀取指定路徑 Runbook（含 frontmatter metadata 與 headings）。
- FR3: 問答工具執行：檢索→選段→規則整併→(有 API Key 則 LLM, 否則擷取式回覆)→引用與分數。
- FR4: Checklist 工具從內容擷取「初步診斷 / 緩解步驟」並回傳 safe_ops meta。
- FR5: Commands 工具分辨 safe_ops vs risk_ops 並加標註。
- FR6: Severity 工具依 symptom 關鍵字與 severity matrix 指南給出建議 SEV 與通知清單。
- FR7: Handoff 工具生成標準欄位骨架。
- FR8: Postmortem 工具生成 RCA 範本（Timeline 表格 + 後續行動清單）。
- FR9: 所有回答需遵守規則：不編造、風險標註、缺資訊提醒 Owner。
- FR10: 若 runbook last_verified_at > 90 天，回答需提示「可能過時」。
### 非功能性需求 (NFR)
- NFR1: 可在無網路（無 LLM）條件下運作（降級）。
- NFR2: 易於替換 I/O（抽象 fsio 層）。
- NFR3: 平均查詢延遲（本機 100 個 runbooks、每 2KB chunk）< 500ms（目標）。
- NFR4: 安全：阻擋路徑跳脫（path traversal）。
- NFR5: 可測試：search/rules/chunking 具純函式界面。
### Frontmatter 規格
必填：title, service, component, severity_default, last_verified_at, owner_slack, owner_team
選填：tags, depends_on, risk_ops[], safe_ops[]
### 規則引擎要點
- 集合所有匹配分段的 risk_ops, owner_slack。
- 回答中：每個風險指令附 ⚠️ 與回退建議（若原文無回退→提醒人工確認）。
- 若多文件衝突：選擇 (component 相同 > service 相同 > 更新時間最近)。
## 資料流程（DFD）
```mermaid
graph TD
A[Client 問題/工具請求] --> B[MCP Server]
B -->|rb.search| S[(Indexed Markdown Corpus)]
B -->|rb.read| F[Filesystem]
B -->|rb.answer 檢索| S
S -->|Top K chunks| R[Rules Aggregator]
R -->|上下文 + Policy| L{LLM?}
L -->|是| O[LLM Chat API]
L -->|否| E[擷取式組裝]
O -->|回答| Q[格式化 + Citation]
E -->|回答| Q
Q --> A
```
## 系統架構（高層）
```mermaid
graph LR
subgraph Client Side
C1[MCP Client]
end
subgraph Server Side
S1[server.mjs]
S2[fsio]
S3[md parser]
S4[search]
S5[rules]
S6[llm adapter]
end
C1 --> S1
S1 --> S2
S1 --> S3
S1 --> S4
S1 --> S5
S1 --> S6
S2 -->|read .md| Storage[(Runbook Filesystem)]
```
## 問答序列圖
```mermaid
sequenceDiagram
participant U as User
participant C as MCP Client
participant S as server.mjs
participant X as search
participant P as rules
participant L as LLM(Optional)
U->>C: 問題輸入
C->>S: rb.answer(question)
S->>X: searchRanked(question)
X-->>S: Top K chunks
S->>P: 聚合 meta 產生 policy
alt 有 LLM
S->>L: 提示+上下文
L-->>S: 回答草稿
else 無 LLM
S-->>S: 擷取式回答
end
S-->>C: answer + citations
C-->>U: 顯示結果
```
## 時程（初版估算）
```mermaid
gantt
dateFormat YYYY-MM-DD
section Phase 1 (需求/設計)
需求蒐集 & 調研 :done, p1, 2025-10-13, 1d
規格文件/任務清單 :active, p2, 2025-10-13, 1d
section Phase 2 (MVP 實作)
目錄/Frontmatter範例 :p3, 2025-10-14, 0.5d
Core fsio/md/search :p4, 2025-10-14, 1d
Rules + answer :p5, 2025-10-15, 1d
Checklist/Commands :p6, 2025-10-16, 0.5d
Severity/Handoff/PM :p7, 2025-10-16, 0.5d
LLM Adapter/降級 :p8, 2025-10-17, 0.5d
section Phase 3 (測試/強化)
單元測試 + 基準 :p9, 2025-10-17, 0.5d
Edge cases & QA :p10, 2025-10-17, 0.5d
section Phase 4 (擴充預研)
Azure Blob 介面抽象 :p11, 2025-10-20, 1d
rb.update 審批流 PoC :p12, 2025-10-21, 0.5d
```
## 關鍵風險 & 緩解
- 片段檢索覆蓋不足：調整 chunk 策略（依 heading 拆 + 空行 fallback）。
- LLM 幻覺：溫度低 + 嚴格系統提示 + citation 比對。
- runbook 過期：自動日期檢查與提示。
- Risk ops 錯誤分類：允許後續新增 rule test cases。
- 性能：如 >1000 檔需改進 ranking（倒排索引 + TF-IDF）。
## 邊界與 Edge Cases
- 問題無匹配：返回「未涵蓋」且提供 escalation owner。
- 空 runbook 或缺 frontmatter：標記 invalid 並跳過檢索排名。
- 重複路徑或大小寫差異：正規化路徑小寫比較避免重複。
- 指令區塊內含多行空白：過濾空行。
- last_verified_at 格式錯誤：忽略新鮮度檢查並警告。
## 未來擴充想法（不進本階段）
- 指令模擬或 dry-run 驗證。
- 風險操作自動生成回退藍本（基於 pattern）。
- Slack/Teams 自動廣播（SEV1+）。
- 向量嵌入檢索（可選）+ Multi-store federation。
## 任務清單（執行導向）
Legend: [P]riority (H/M/L), [S]tatus (Todo/Doing/Blocked/Done)
### 需求/設計
- [ ] (H) 建立 frontmatter schema JSON（驗證用） S:Todo
- [ ] (H) 定義 risk/safe ops 標記規則測試樣本 S:Todo
- [ ] (M) 設計 chunk strategy (heading-aware) S:Todo
- [ ] (M) 規則：多文件衝突解決演算法細化 S:Todo
- [ ] (M) last_verified_at 新鮮度閾值設定 (90d 可調) S:Todo
### 基礎模組
- [ ] (H) fsio: read/list 實作 + path traversal 單元測試 S:Todo
- [ ] (H) md parser: frontmatter + heading + chunk tests S:Todo
- [ ] (H) search: baseline (set overlap) + test corpus S:Todo
- [ ] (M) search: 擴充為詞頻加權 (TF-IDF) 選擇性 S:Todo
- [ ] (L) 指定停用詞表/字詞正規化策略 S:Todo
### 規則與回答
- [ ] (H) ruleGuard 聚合風險/owner + 單元測試 S:Todo
- [ ] (H) 風險指令注記與回退占位符格式 S:Todo
- [ ] (M) 過期 runbook 檢測邏輯 S:Todo
- [ ] (M) 多 runbook 衝突挑選策略實作草稿 S:Todo
- [ ] (L) Citation 格式標準化（path#chunk + offset） S:Todo
### 工具 (MCP)
- [ ] (H) rb.search 介面 & 參數驗證 S:Todo
- [ ] (H) rb.read 介面 S:Todo
- [ ] (H) rb.answer 流程（檢索→聚合→策略→LLM/降級） S:Todo
- [ ] (M) rb.checklist 正規表達式改進（多語別） S:Todo
- [ ] (M) rb.commands 指令抽取強化（支援 code fence 語言多樣） S:Todo
- [ ] (M) rb.severity 關鍵字規則表外部化 S:Todo
- [ ] (L) rb.handoff / rb.postmortem 模板客製參數化 S:Todo
### LLM & 降級
- [ ] (H) LLM adapter（OpenAI 初始化 + 無金鑰 fallback） S:Todo
- [ ] (M) 系統提示模板化（可覆蓋） S:Todo
- [ ] (M) token 長度截斷策略 (context window safe) S:Todo
- [ ] (L) 指令引用數據用戶端可視化標記 S:Todo
### 驗證 / 測試
- [ ] (H) 單元測試：search/rules/chunk/risk annotation S:Todo
- [ ] (H) 整合測試：rb.answer（含無結果） S:Todo
- [ ] (M) 基準測試：100/500/1000 runbook latency S:Todo
- [ ] (M) 安全測試：路徑跳脫、惡意 frontmatter S:Todo
- [ ] (L) LLM 幻覺率抽樣評估流程 S:Todo
### DevX / 可維運性
- [ ] (M) README: 使用方式 + 環境變數 S:Todo
- [ ] (M) mcp.config.json 範例校對 S:Todo
- [ ] (M) CI: lint + test (Node) pipeline 規劃 S:Todo
- [ ] (L) Pre-commit: schema validate runbooks S:Todo
### 擴充預研
- [ ] (M) fsio 介面抽象設計（adapter pattern） S:Todo
- [ ] (M) Azure Blob adapter spike 設計草稿 S:Todo
- [ ] (L) rb.update 草稿（審批流程狀態機） S:Todo
- [ ] (L) Slack/Teams 通知介面調研 S:Todo
### 治理 / 憲法落地
- [ ] (H) 建立 governance CI 驗證腳本規格（schema/stale/risk pattern） S:Todo
- [ ] (M) agent-file-template 原則摘要自動生成規劃 S:Todo
- [ ] (M) Benchmark 基線腳本設計（離線模式 100 runbooks） S:Todo
- [ ] (M) 「UNKNOWN / ESCALATE」政策訊息格式規格書 S:Todo
- [ ] (L) 風險命令分類詞典初稿（delete/cordon/drain 等） S:Todo
- [ ] (L) CHANGE LOG 區塊規範範例（供 runbook 作者引用） S:Todo
## 依賴 / 前置條件
- Node.js 18+（ESM 支援）
- 模型 API Key（可選，用於升級回答品質）
## 待確認問題（需與利害關係人澄清）
1. 是否需要支援多語 Runbook（中/英混合）檢索與回答？
2. 指令風險分類是否有中央字典（例如 delete/cordon/drain 一律 risky）？
3. 是否需記錄查詢日誌（合規 / 稽核用途）？
4. Postmortem 模板是否需自動填充 SEV 與 Owner 初始值？
5. SEV 關鍵字規則是否已有現行矩陣文件可匯入？
## 決策記錄 (ADR 簡要)
- ADR-001: 檢索先採 set-overlap baseline（低實作成本），後續視精度再升級 TF-IDF/Embeddings。
- ADR-002: 以 frontmatter 驅動規則聚合，避免外部 DB 依賴，確保易於離線攜帶。
- ADR-003: 降級模式僅使用擷取式回答（top chunk），保障無 API Key 仍可用。
---
> 請審閱以上需求與任務清單，回覆：
> 1) 是否需要調整/增補任務項目？
> 2) 待確認問題的答案（若已有）？
> 3) 是否進入下一階段（MVP 實作規劃）？
