awoooi/docs/superpowers/specs/2026-04-02-knowledge-base-design.md

Knowledge Base 設計文件

版本: v1.0 日期: 2026-04-02 作者: ogt + Claude Code 狀態: 已批准，待實作

---

背景與目標

打造 AWOOOI 知識庫系統，讓工程師與 AI 管理人員可查閱 SRE 知識，同時作為 OpenClaw 決策的 Context 來源。

已確認決策:

• 使用者：工程師 + AI 管理人員
• 知識來源：AI 自動萃取為主，人工審核補充
• 用途：人工查閱 + AI 自動引用（兩者兼備）
• 資料結構：兩層架構（底層知識條目 + Playbook 為特殊關聯）
• UI：左側分類導航 + 頂部搜尋 + 右側詳情

---

架構決策

項目	決策	理由
Playbook 邊界	分離，用 related_playbook_id 關聯	執行語意 ≠ 查閱知識，職責不同
Migration	K8s Job（沿用現有方式）	4 個 table，Alembic 是過度工程
Vector Search	Phase 1 跳過，關鍵字 + tag	Phase 2 再評估 pgvector

---

資料模型

KnowledgeEntry（新 PostgreSQL table）

CREATE TABLE knowledge_entries (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title           VARCHAR(255) NOT NULL,
  content         TEXT NOT NULL,           -- Markdown
  entry_type      VARCHAR(50) NOT NULL,    -- 'incident_case' | 'runbook' | 'best_practice' | 'postmortem'
  category        VARCHAR(100) NOT NULL,   -- 對應左側分類樹
  tags            JSONB DEFAULT '[]',      -- string[]
  source          VARCHAR(20) NOT NULL,    -- 'ai_extracted' | 'human'
  status          VARCHAR(20) NOT NULL DEFAULT 'draft', -- 'draft' | 'review' | 'approved'
  related_incident_id UUID REFERENCES incidents(id) ON DELETE SET NULL,
  related_playbook_id VARCHAR(255),        -- Playbook Redis key（非 FK）
  view_count      INTEGER DEFAULT 0,
  created_by      VARCHAR(100),
  created_at      TIMESTAMPTZ DEFAULT NOW(),
  updated_at      TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_knowledge_entries_type     ON knowledge_entries(entry_type);
CREATE INDEX idx_knowledge_entries_category ON knowledge_entries(category);
CREATE INDEX idx_knowledge_entries_status   ON knowledge_entries(status);

entry_type 分類

type	說明
incident_case	AI 從 Incident 萃取的案例分析
runbook	手動建立的操作手冊
best_practice	最佳實踐文章
postmortem	事後分析報告

category 分類樹（左側導航）

全部
├── 基礎設施
│   ├── K8s / K3s
│   ├── 資料庫
│   └── 網路
├── 應用層
│   ├── API 服務
│   └── 前端
├── AI 系統
│   ├── OpenClaw
│   └── Playbook
└── 安全 / 合規

---

API 設計

Base path: /api/v1/knowledge

Method	Path	說明
GET	/	列表（支援 category, type, status, q 搜尋, tags 篩選）
GET	/{id}	單筆（同時 view_count +1）
POST	/	建立新條目
PATCH	/{id}	更新（含狀態流轉）
POST	/{id}/approve	審核通過（status: draft/review → approved）
DELETE	/{id}	軟刪除（status → archived）
GET	/categories	取得分類樹（含各類數量）
GET	/search	關鍵字搜尋（title + content + tags）

---

後端分層架構

遵循 leWOOOgo 積木化原則：

apps/api/src/
├── db/models.py              # 新增 KnowledgeEntry ORM class
├── models/knowledge.py       # Pydantic Schema (Request/Response)
├── repositories/
│   ├── interfaces.py         # 新增 IKnowledgeRepository Protocol
│   └── knowledge_repository.py  # PostgreSQL CRUD 實作
├── services/
│   └── knowledge_service.py  # 業務邏輯（搜尋、狀態流轉、view_count）
└── api/v1/
    └── knowledge.py          # Router，prefix /knowledge

---

前端設計

頁面結構

/knowledge-base
├── 左側分類導航 (w-52, 固定)
│   ├── 全部 (N)
│   ├── 基礎設施 (N)
│   ├── 應用層 (N)
│   ├── AI 系統 (N)
│   └── 安全/合規 (N)
├── 主區域
│   ├── 頂部搜尋欄 + 篩選 (type / source / status)
│   ├── 結果列表
│   │   └── KnowledgeCard (title, type badge, tags, view_count, 相關 Playbook)
│   └── 空態
└── 右側詳情 Panel (抽屜式，點擊條目開啟)
    ├── 標題 + meta
    ├── Markdown 渲染
    ├── 相關 Playbook 連結
    └── 審核操作（approve / 回 review）

KnowledgeCard

┌─────────────────────────────────────────┐
│ [type badge]  標題文字               👁 12 │
│ category · source · 2026-04-01          │
│ [tag] [tag] [tag]                       │
│ 🔗 相關 Playbook: restart-api-server    │
└─────────────────────────────────────────┘

狀態標示

status	顯示	顏色
draft	草稿	gray
review	審核中	warning（黃）
approved	已批准	healthy（綠）

---

Migration K8s Job

參考 k8s/jobs/migrate-phase18-audit-logs.yaml，建立：

k8s/jobs/migrate-knowledge-entries.yaml

執行 CREATE TABLE knowledge_entries ... + index。

---

Phase 2（未來）

• pgvector 語意搜尋
• OpenClaw 在評估 Incident 時自動 RAG 查詢 Knowledge Base
• Embedding 自動化（建立 entry 時觸發）