# Implementation Plan: On-Call Runbook 百科 MCP 伺服器
**Branch**: `001-feature-on-call` | **Date**: 2025-10-13 | **Spec**: ./spec.md
**Input**: 來源為功能規格 `specs/001-feature-on-call/spec.md`
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
## Summary
建立一個離線優先 (offline-first) 的 On-Call Runbook MCP 伺服器：以 Markdown runbook（具 frontmatter）為唯一知識來源，提供檢索、問答（含降級）、checklist/commands 擷取、severity 判斷、handoff 與 postmortem 模板輸出。核心策略：
- 檢索：Heading-aware chunk 拆分 + set-overlap baseline，後續可插拔 TF-IDF。
- 安全：風險指令（risk_ops）統一經中央字典 + 內容抽取分類，回答強制引用來源與警示。
- 新鮮度：last_verified_at 超過 90 天標示 STALE。
- 降級：無 LLM 僅擷取組裝；有 LLM 增摘要但不可新增未引用資訊。
首要交付最小可運作工具集合 (rb.search, rb.read, rb.answer, rb.checklist, rb.commands, rb.severity, rb.handoff, rb.postmortem) 並達成 P95 <500ms（100 runbooks）。
## Technical Context
**Language/Version**: Node.js 18 (ESM)
**Primary Dependencies (計畫)**:
- markdown/frontmatter：`gray-matter`
- 解析：`remark` / `unified`（若需 AST；第一版可暫不引入，視複雜度）
- 相似度/檢索：內建實作（tokenize + set overlap），可選 `natural` 或自行 TF-IDF 實作延伸點
- 測試：`vitest`（快速 + ESM 友好）
- 型別：原生 JS + JSDoc（MVP），後續可遷移 TypeScript（延後降低初始阻力）
**Storage**: 本機檔案系統 (只讀)
**Testing**: 單元 (vitest) + 整合 (simulate MCP calls) + 基準 (node 基準腳本)
**Target Platform**: 本機 / CI（Windows + Linux）
**Project Type**: 單一後端工具伺服器（MCP Server）
**Performance Goals**: P95 <500ms (100 runbooks, 2KB/chunk) offline；核心純函式平均 <5ms/chunk scoring
**Constraints**: Offline-first、無外部 DB、禁止 hallucination、風險命令必須標註、Stale 警示
**Scale/Scope**: MVP 目標：≤ 300 runbooks（線性可擴展至 1000 前不需索引升級）
### Derived Technical Decisions
- Tokenization：以非字母數字邊界拆分 + toLowerCase + 全半形正規化 + 基本英文/中文常見停用詞去除。
- Chunking：依 heading 分段；若 heading 區塊 > 800 字再次按空行切割；保留 heading path 作為 chunk context。
- Scoring：計算查詢詞集合與 chunk 詞集合交集大小 / 查詢詞數；平手以 chunk 最近 heading 深度較淺優先。
- 多語：簡單正規化（英文小寫、中文原樣）+ 別名映射表（service 名稱 variants）。
- 風險字典：初稿 ≥20 核心詞（危險動作動詞 + kubernetes / 資料庫破壞性命令）。
- Freshness：以注入 Clock 物件比較 last_verified_at；無法解析日期 → 加入 warnings。
- 降級模式：省略 LLM 摘要模組；回應格式欄位保持一致（summary=null）。
- Citation：path + chunkIndex；後續可擴增 offset。
- 衝突選擇：多來源時只將主來源細節放置主回答，其餘列 meta.secondarySources。
- 安全策略：拒絕包含 .. 或 絕對磁碟符號（例如 C:\）的讀取請求。
## Constitution Check
| Principle/Gate | 評估 | 說明 |
|----------------|------|------|
| P1 Frontmatter Source-of-Truth | 通過 | 解析缺欄位即標記 invalid 並排除，列 warnings |
| P2 Deterministic Retrieval | 通過 | Set-overlap + 規則排序；無結果返回 UNKNOWN/ESCALATE |
| P3 Risk Annotation | 通過 | 風險字典 + 擷取分類，缺回退提示時顯示人工確認 |
| P4 Offline Behavior | 通過 | 所有工具純本機；LLM 僅附加摘要可省略 |
| P5 Pure Function Coverage | 通過 | chunking/tokenize/scoring/risk classify/freshness/severity 為純函式 |
| Performance Gate | 通過 | 預估 100 runbooks：I/O <150ms + scoring <50ms + assemble <50ms |
| Freshness Handling | 通過 | Clock 注入、>90 天標記 stale、無效日期進 warnings |
| Logging Constraint | 部分 | MVP 先實作 console 結構化 JSON；後續可抽象 logger |
無 NEEDS CLARIFICATION 項目；Logging 進階（集中式輸出）延後，標記 non-blocking。
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
[Gates determined based on constitution file]
## Project Structure
### Documentation (this feature)
```
specs/[###-feature]/
├── plan.md # This file (/speckit.plan command output)
├── research.md # Phase 0 output (/speckit.plan command)
├── data-model.md # Phase 1 output (/speckit.plan command)
├── quickstart.md # Phase 1 output (/speckit.plan command)
├── contracts/ # Phase 1 output (/speckit.plan command)
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
```
### Source Code (repository root)
<!--
ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
for this feature. Delete unused options and expand the chosen structure with
real paths (e.g., apps/admin, packages/something). The delivered plan must
not include Option labels.
-->
```
src/
core/ # 純函式：tokenize, chunk, score, classify, freshness, severity
adapters/ # fsio, llm(optional stub), config loader
services/ # orchestration: searchService, answerService, checklistService
mcp/ # MCP server entry + tool registrations
utils/ # 通用：logger（簡單 JSON）、validation、normalization
tests/
unit/core/
unit/adapters/
integration/
benchmark/
scripts/ # 基準測試與字典產生工具（可能）
docs/ (產生的 quickstart 可鏈接)
```
**Structure Decision**: 單一後端專案（Option 1 基底），以 domain-oriented 分層（core/adapters/services/mcp）。確保 core 無第三方依賴（除非純字串處理）。
## Complexity Tracking
*Fill ONLY if Constitution Check has violations that must be justified*
| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| Logger placeholder only (console JSON) | 先交付核心功能 | 引入成熟 logging 套件增加設定複雜度，不影響安全規則 |
| 手寫檢索實作 | 控制可預測性與簡單性 | 早期引入外部全文檢索庫（如 lunr）增加索引記憶體與學習成本 |
## Phase 0: Research (Completed)
- 產出 `research.md`（檢索、tokenization、風險字典、freshness、降級、衝突解決、日誌策略）。
- 無未決澄清。
## Phase 1: Design & Contracts (Current)
交付項目：`data-model.md`, `contracts/openapi.yaml`, `quickstart.md`, 更新 `plan.md`。
| Task | 說明 | Output | Gate |
|------|------|--------|------|
| Build data model | 實體與欄位約束 | data-model.md | P1/P5 |
| API contract | 工具邏輯抽象介面 | openapi.yaml | P2 |
| Risk dictionary seed | 初始 ≥20 風險指令 | dictionary list (quickstart) | P3 |
| Freshness logic spec | Clock 注入策略 | research.md 條目 | P1 |
| Degradation mapping | 有/無 LLM 對照表 | plan.md Technical Context | P4 |
| Logging minimal schema | JSON 欄位定義 | plan.md | Constraint 8 |
## Phase 2: Implementation Plan (Forthcoming)
（/speckit.tasks 產生任務細項，以下為預規劃）
| Epic | 子任務摘要 | 風險 | 測試對應 |
|------|-----------|------|-----------|
| Core parsing | frontmatter parse, heading chunk, tokenization | 中 | unit(core) + invalid cases |
| Retrieval | score + rank + tie-break | 低 | unit(score) + integration(search) |
| Risk classification | 字典載入 + 抽取 + 合併去重 | 中 | unit(classify) + risk coverage test |
| Freshness | date parse + clock 注入 | 低 | unit(freshness) + stale/fresh cases |
| Severity | keyword map + rule evaluate | 低 | unit(severity) |
| Answer orchestration | search→aggregate→format | 中 | integration(answer LLM off/on) |
| CLI/MCP layer | tool binding + input validation | 中 | integration(tool flows) |
| Templates | handoff / postmortem 生成 | 低 | unit(template) + integration |
| Benchmark | corpus generator + latency測量 | 中 | benchmark report |
| Logging | JSON schema & emit | 低 | integration(log presence) |
## Post-Design Constitution Re-Check (Planned)
將在核心純函式草稿完成後再度核對：
- Retrieval deterministic 性是否被 TF-IDF 選項改寫（若導入）。
- Risk 字典是否需要版本欄位（可能新增 gating）。
- Logging 是否需要新增 result_class 詳細分類（e.g. PARTIAL）。
### 初步檢視（本階段設計完成）
目前設計未引入 TF-IDF / embeddings；保持 deterministic。風險字典版本化標記將暫緩至第一次擴充（記錄於未來 tasks）。Logging result_class 暫維持四種（ANSWERED|ESCALATE|STALE|ERROR），PARTIAL 視後續需求再評估。
