---
description: "Task list for implementing On-Call Runbook 百科 MCP 伺服器"
---
# Tasks: On-Call Runbook 百科 MCP 伺服器
**Input**: Design documents in `specs/001-feature-on-call/`
**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/openapi.yaml
**Tests**: 功能規格明確定義驗收與成功指標（偏重可測 / 安全），屬於高風險領域（避免幻覺、風險指令分類），故採 TDD（產生對應測試任務）。
## Format: `[ID] [P?] [Story] Description`
- **[P]**: 可平行（不同檔案/模組，無直接依賴）
- **[Story]**: User Story (US1 / US2 / US3)
- 任務需具體：指出檔案路徑、交付產出或可驗證條件
---
## Phase 1: Setup (Shared Infrastructure)
**Purpose**: 初始化專案骨架與基本工具（不含業務邏輯）。
- [x] T001 [P] 建立 `package.json`（scripts: `test`, `test:watch`, `bench`, `lint`(占位)）
- [x] T002 [P] 建立目錄結構：`src/{core,adapters,services,mcp,utils}` `tests/{unit,unit/core,unit/adapters,integration,benchmark}`
- [x] T003 [P] 新增 `.editorconfig`、`.gitignore`、`README.md`（連結 quickstart）
- [x] T004 [P] 安裝依賴：`gray-matter`, `vitest`, `glob`, `fast-glob`(選擇其一), `kleur`(日誌著色, 可選), `minimist` (未來 CLI)；開發依賴：`@types/node` (型別支援)
- [x] T005 建立 `tsconfig.json` (即便先用 JS，可作為未來 TS 遷移基礎，宣告 `allowJs`)
- [x] T006 設定 `vitest.config.mjs`（支援 ESM 與 coverage）
- [x] T007 建立 `scripts/benchmark-seed.mjs` (骨架, TODO: 之後填充)
- [x] T008 建立 `src/utils/logger.mjs`（console JSON，介面：log(event, meta)）
- [x] T009 建立 `src/utils/errors.mjs`（定義 Error 類型：ValidationError, NotFoundError, SecurityError）
- [x] T010 建立 `src/utils/validation.mjs`（frontmatter 欄位檢查 helper）
- [x] T011 建立 `src/core/constants.mjs`（FRESHNESS_DAYS=90, DEFAULT_TOPK=5 等）
**Checkpoint**: 專案可 `npm test` 成功（尚無實質測試时可通過空測試）。
---
## Phase 2: Foundational (Blocking Prerequisites)
**Purpose**: 所有 User Story 共用的純函式與底層能力。完成前不得開始任何 Story 實作。
### Tests (必須先寫再實作)
- [x] T012 [P] 建立測試 `tests/unit/core/tokenize.spec.mjs`：覆蓋中英文、全半形、停用詞。
- [x] T013 [P] 建立測試 `tests/unit/core/chunk.spec.mjs`：heading 分段、>800字再細切、保留 headingPath。
- [x] T014 [P] 建立測試 `tests/unit/core/score.spec.mjs`：交集比例、平手 tie-break（淺層 heading 優先）。
- [x] T015 [P] 建立測試 `tests/unit/core/freshness.spec.mjs`：stale / fresh / 無效日期 warning。
- [x] T016 [P] 建立測試 `tests/unit/core/risk-classify.spec.mjs`：中央字典匹配 + runbook risk_ops 合併去重 + rollback 缺失提醒。
- [x] T017 建立測試 `tests/unit/core/severity.spec.mjs`：關鍵字 mapping → 建議 SEV。
### Implementation
- [x] T018 [P] `src/core/tokenize.mjs` 實作 (多語 + 正規化 + 停用詞)
- [x] T019 [P] `src/core/chunk.mjs` heading-aware 分段 + 800 長度再切 + headingPath
- [x] T020 [P] `src/core/score.mjs` 計算交集比例 + tie-break 規則
- [x] T021 [P] `src/core/freshness.mjs` Clock 注入 + stale 判斷 + 解析錯誤 warnings
- [x] T022 [P] `src/core/risk-dictionary.json`（≥20 詞）
- [x] T023 [P] `src/core/risk-classify.mjs` 合併 central + frontmatter + fence 抽取
- [x] T024 [P] `src/core/severity.mjs` 規則表 & 推論
- [x] T025 `src/adapters/fsio.mjs` 安全讀取 (拒絕 .. 與磁碟跳脫) + list markdown
- [x] T026 `src/adapters/config.mjs` 讀取環境變數 (RUNBOOK_ROOT, FRESHNESS_DAYS, TOPK_DEFAULT)
- [x] T027 `src/services/indexer.mjs` 建立載入+解析管線 (frontmatter→chunks→cache)
- [x] T028 `tests/integration/foundation.spec.mjs`：索引最小 corpus，驗證 invalid 排除、stale 標記、指令抽取。
**Checkpoint**: 所有純函式與索引基礎通過測試；P95（模擬 50 runbooks）基準腳本可執行（目標數據占位即可）。
---
## Phase 3: User Story 1 - 檢索並獲得安全初步處置 (Priority: P1) 🎯 MVP
**Goal**: 提供快速檢索 + 初步診斷 checklist + 風險/安全指令分類 + 新鮮度提示。
**Independent Test**: 僅啟用 US1 相關檔案即可完成從 query→結果輸出；滿足驗收情境 1~3。
### Tests (先寫)
- [x] T029 [P] [US1] `tests/integration/us1-search-basic.spec.mjs`：2~3 關鍵詞查詢回傳 TopK 結構。
- [x] T030 [P] [US1] `tests/integration/us1-stale-flag.spec.mjs`：過期 runbook 顯示 stale。
- [x] T031 [P] [US1] `tests/integration/us1-no-match.spec.mjs`：無結果返回 UNKNOWN/ESCALATE。
- [x] T032 [P] [US1] `tests/unit/services/checklist.spec.mjs`：抽取初步診斷+緩解步驟。
- [x] T033 [P] [US1] `tests/unit/services/commands-extract.spec.mjs`：safe/risk 分類 & rollback 缺失提醒。
### Implementation
- [x] T034 [P] [US1] `src/services/searchService.mjs`：封裝 scoring + ranking + stale 標示
- [x] T035 [P] [US1] `src/services/checklistService.mjs`：擷取"初步診斷/緩解"標題或模式
- [x] T036 [P] [US1] `src/services/commandExtractService.mjs`：合併 risk/safe ops + 字典分類
- [x] T037 [US1] `src/mcp/tools/search.mjs`：rb.search 工具（參數：q, topK）
- [x] T038 [US1] `src/mcp/tools/read.mjs`：rb.read（輸出 frontmatter + body sections）
- [x] T039 [US1] `src/mcp/tools/checklist.mjs`：rb.checklist
- [x] T040 [US1] `src/mcp/tools/commands.mjs`：rb.commands
- [x] T041 [US1] `tests/integration/us1-tools.spec.mjs`：串接 search→checklist→commands 流程
- [x] T042 [US1] 更新 `README.md` 增加 US1 使用示例
**Checkpoint**: US1 測試全綠，可單獨交付為 MVP。
---
## Phase 4: User Story 2 - 規則導向問答與降級 (Priority: P2)
**Goal**: 問答流程：檢索 + 規則聚合 + 風險標註 + 有/無 LLM 降級一致輸出（含 citations）。
**Independent Test**: 僅載入 US1 + US2 服務；驗收情境 1~3 (US2) 均成立。
### Tests
- [x] T043 [P] [US2] `tests/integration/us2-answer-llm-off.spec.mjs`：無金鑰擷取式回答（summary=null）。
- [x] T044 [P] [US2] `tests/integration/us2-answer-llm-on.spec.mjs`：mock LLM 返回摘要（不得新增未引用資訊）。
- [x] T045 [P] [US2] `tests/unit/services/answer-aggregate.spec.mjs`：衝突介面（component > service > time）。
- [x] T046 [P] [US2] `tests/unit/services/citation-format.spec.mjs`：citation 組裝正確性。
### Implementation
- [x] T047 [P] [US2] `src/adapters/llmAdapter.mjs`：stub（若無金鑰回傳 null）；介面 generateSummary(chunks, question)
- [x] T048 [P] [US2] `src/services/answerService.mjs` 組合：search→risk/安全→衝突解決→citations→summary(decision)
- [x] T049 [US2] `src/mcp/tools/answer.mjs`：rb.answer (inputs: question, topK, useLLM)
- [x] T050 [US2] 擴充 `README.md` 問答模式示例
**Checkpoint**: US2 所有整合測試通過；離線與線上行為對照一致。
---
## Phase 5: User Story 3 - 事件交接與事後檢討骨架 (Priority: P3)
**Goal**: 提供 handoff 與 postmortem 模板輸出。
**Independent Test**: 僅啟用 template 服務即可產出標準欄位與占位；不依賴 LLM。
### Tests
- [x] T051 [P] [US3] `tests/unit/services/handoff.spec.mjs`：四區塊皆非空欄位生成。
- [x] T052 [P] [US3] `tests/unit/services/postmortem.spec.mjs`：Timeline 表頭 + ≥5 action items 占位。
- [x] T053 [P] [US3] `tests/integration/us3-tools.spec.mjs`：rb.handoff 與 rb.postmortem 輸出結構。
### Implementation
- [x] T054 [P] [US3] `src/services/handoffService.mjs` 模板生成
- [x] T055 [P] [US3] `src/services/postmortemService.mjs` 模板生成
- [x] T056 [US3] `src/mcp/tools/handoff.mjs`：rb.handoff
- [x] T057 [US3] `src/mcp/tools/postmortem.mjs`：rb.postmortem
- [x] T058 [US3] 更新 `README.md` 增加 handoff / postmortem 使用示例
**Checkpoint**: 三個使用者故事均可獨立驗證與展示。
---
## Phase 6: Polish & Cross-Cutting Concerns
**Purpose**: 強化、最佳化與治理。
- [ ] T059 [P] 加入 `scripts/benchmark-run.mjs`：生成假 corpus (100/300) + 報告 P95 延遲
- [ ] T060 [P] 性能微調：簡單快取 tokenization 結果（Map<path, tokens[]>）
- [ ] T061 [P] 增加 citation offset（可選）並調整測試
- [ ] T062 程式碼巡檢：重構重複程式 & 提取共用 util
- [ ] T063 安全檢查：新增路徑白名單測試 + 惡意 frontmatter 解析測試
- [ ] T064 文件強化：補充風險字典版本策略與貢獻指南（CONTRIBUTING 占位）
- [ ] T065 [P] 風險字典覆蓋率測試（收集測試語料比對召回）
- [ ] T066 [P] 新增 CI 腳本草稿（lint + test）（僅文件說明或 GitHub Actions 草稿）
- [ ] T067 最終 README 更新 + 徽章（coverage/benchmark 摘要）
- [ ] T068 [P] 新增 `tests/unit/services/severity.spec.mjs`（FR-006 規則與邊界）
- [ ] T069 [P] 新增 `tests/unit/utils/no-log-persist.spec.mjs`（驗證 FR-020：不寫入檔案 / 僅記憶體暫存統計）
- [ ] T070 分析報告：建立 `specs/001-feature-on-call/analysis.md` （需求→任務映射 + 缺口與建議）
- [ ] T071 [P] `src/services/severityService.mjs`（FR-006 規則服務）
- [ ] T072 [P] `src/mcp/tools/severity.mjs`（rb.severity 工具 + README 補充）
- [ ] T073 [P] `tests/unit/tools/topk-boundary.spec.mjs`（TopK 1 與 20 邊界 + 超界拒絕）
- [ ] T074 基準驗證：擴充 benchmark 腳本若 P95>500ms 退出非 0（對應 SC-002）
- [ ] T075 風險字典 coverage assert 腳本（計算遺漏率 <5% 否則 fail）（SC-004）
**Checkpoint**: 可提交初版對外展示或內部試用。
---
## Dependencies & Execution Order
### Phase Dependencies
- Setup → Foundational → User Stories (US1 → US2 → US3 可依優先或並行) → Polish
- US2 依賴 Foundational + US1 部分服務（search/commandExtract）
- US3 僅依賴 Foundational（可與 US2 並行，若不需 answer 之進階功能）
### User Story Independence
- US1 為 MVP 核心
- US2 在 US1 基礎上增加問答與降級能力
- US3 與 US1 共用基礎，但不依賴 US2（除非想引用 answer summary，可延後）
### Parallel Opportunities
- Tokenization / Chunk / Score / Freshness / Risk / Severity 純函式 (T018~T024) 可平行
- MCP tool 實作（search / read / checklist / commands）可在服務完成後分工
- US2 中 LLM Adapter / Answer 聚合 / citation 測試可並行 (T043~T048)
- US3 模板服務與工具可獨立並行 (T051~T057)
---
## Parallel Examples
### US1
```
# 平行編寫（不同檔案）：
T034 searchService / T035 checklistService / T036 commandExtractService
# 另一組平行：工具層
T037 search tool / T038 read tool / T039 checklist tool / T040 commands tool
```
### US2
```
T043 us2-answer-llm-off test | T044 us2-answer-llm-on test
T045 answer-aggregate unit | T046 citation-format unit
T047 llmAdapter | T048 answerService | T049 answer tool
```
### US3
```
T051 handoff unit | T052 postmortem unit | T053 integration
T054 handoffService | T055 postmortemService | T056 handoff tool | T057 postmortem tool
```
---
## Implementation Strategy
### MVP (最小可行)
1. 完成 Phase 1 + Phase 2
2. 完成 US1（全部測試通過）
3. 基準測試與安全檢查（stale, risk）
4. 交付 / 試用收集回饋
### Incremental
- US2：加上問答與降級摘要能力
- US3：補齊交接與事後檢討模板提升流程治理
### 風險與緩解對應
| 風險 | 任務緩解 | 驗證 |
|------|----------|------|
| 幻覺回答 | US2 測試（llm-off / llm-on 對照） | T043/T044 |
| 風險指令漏標 | 風險字典 + classify 單元測試 | T016/T065 |
| 性能退化 | 基準測試腳本 | T059/T060 |
| Stale 判斷錯誤 | freshness 單元 + 整合 | T015/T028/T030 |
| Path Traversal | fsio 安全測試 | T028/T063 |
---
## Task Counts
- Total Tasks: 75
- Setup: 11
- Foundational: 17 (含測試 6 + 實作 11)
- US1: 14 (測試 5 + 實作 7 + README 更新)
- US2: 11 (測試 4 + 實作 3 + README 更新 + adapter)
- US3: 8 (測試 3 + 實作 5)
- Polish: 21 (含新增 severity 服務+工具、TopK 邊界、性能閾值、coverage assert)
(合計時含 README/benchmark/logging 相關項；若有差異以實際列表為準)
## MVP 範圍建議
- 任務 T001~T042 完成即可：具檢索 / checklist / commands / stale 標示 / 無匹配 UNKNOWN，符合 SC-001~SC-006 之多數基礎指標（除問答摘要與模板）。
---
## Notes
- 所有 [P] 任務需注意避免共享未建立檔案競爭；建議先建立空檔再並行填充。
- 測試使用 vitest，命名規則：`*.spec.mjs`。
- Citation 格式初版簡單 (path + chunkIndex)；若 Phase 6 增 offset 需回溯更新測試。
