5959855a71
- 字體：Syne (標題) + DM Mono (內文) + VT323 (品牌點陣)，替換 Inter - Tailwind: fontFamily 更新 + 5 層文字色彩 token (primary→disabled) - Sidebar: NemoClaw 白瓷龍蝦爪 SVG + AWOOOI 用 VT323 放大 - OpenClaw Panel: 還原 NemoClaw 3D 白瓷龍蝦爪 (替換 NemoNodeAnimation) - Knowledge Base 設計文件 (B分離/A K8s Job/Phase1跳過向量搜尋) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
186 lines
5.6 KiB
Markdown
186 lines
5.6 KiB
Markdown
# 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）
|
||
|
||
```sql
|
||
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 時觸發）
|