From 3a4fd4136d15de3837e20058329f0722acda796b Mon Sep 17 00:00:00 2001
From: Accusys <accusys@Accusyss-MacBook-Pro.local>
Date: Sat, 9 May 2026 14:28:47 +0800
Subject: [PATCH] docs: wiki vs RAG distinction in model lifecycle

wiki is not traditional RAG:
- RAG: ephemeral query-time augmentation
- Wiki: permanent model corrections, versioned, packaged with model
- Edits accumulate across versions as ground truth
---
 docs/RELEASE_PHASES.md | 57 +++++++++++++++++++++++++++++++++---------
 1 file changed, 45 insertions(+), 12 deletions(-)

diff --git a/docs/RELEASE_PHASES.md b/docs/RELEASE_PHASES.md
index 25a40f3..a62aa18 100644
--- a/docs/RELEASE_PHASES.md
+++ b/docs/RELEASE_PHASES.md
@@ -119,42 +119,75 @@ release/
 
 每個 momentry model（`{uuid}_v1` / `v2` / `v3`）不只是唯讀的產出，而是可透過 wiki 機制持續改善。
 
+### 與傳統 RAG 的區別
+
+| | 傳統 RAG | momentry wiki |
+|---|---|---|
+| 知識儲存 | vector DB（ephemeral） | model package（permanent） |
+| 修正方式 | query 時 LLM 決定是否採用 | 使用者/Agent 直接編輯 |
+| 修正持久性 | ❌ 下次 query 就消失 | ✅ 寫入 model，版本化保存 |
+| 模型改進 | 無（僅改變 prompt） | 下次 version bump 時合併為 ground truth |
+| 協作方式 | 單向（retrieve → generate） | 雙向（編輯 → 合併 → 改進） |
+| 離線可用 | ❌ 需 vector DB + LLM | ✅ 離線查閱 wiki 目錄 |
+
+**momentry wiki 不是 RAG 的替代品，而是 model 的生命週期管理機制。**
+
 ### 概念
 
 ```
 momentry model (release package)
   ├── output_json/          ← 唯讀，processor 產出
-  ├── chunks/               ← 唯讀，ingestion 產出  
-  ├── vectors/              ← 唯讀，embedding 產出
+  ├── chunks.csv            ← 唯讀，ingestion 產出
+  ├── vectors.csv           ← 唯讀，embedding 產出
   └── wiki/                 ← 可編輯，使用者貢獻知識
-        ├── identities.json   ← "這個 trace 是 Audrey Hepburn"
-        ├── objects.json      ← "這個 object 是郵票 #42"
-        ├── corrections.json  ← "ASR 'Hello' 應為 'Halo'"
+        ├── identities.json   ← "trace 5 = Audrey Hepburn"
+        ├── objects.json      ← "object 42 = 郵票 #1"
+        ├── corrections.json  ← "ASR 'Hello' → 'Halo'"
         └── changelog.json    ← 編輯歷史
 ```
 
-### wiki 資料流向
+### 資料流向
 
 ```
 使用者/Agent 編輯 wiki
         ↓
-  wiki/{topic}.json 更新
+  DB wiki_entries + wiki_revisions 寫入
         ↓
-  下次 release 打包時合併
+  下次 release 打包時 merge 進 model
         ↓
-  新版 model（version bump）
+  TKG label 更新 (tkg_nodes.label)
+        ↓
+  新版 model version bump
 ```
 
 ### 與 TKG 的關係
 
-wiki 的 identity 和 object 標註會回寫到 TKG：
+wiki 的 identity 和 object 標註會回寫到 TKG node label：
 ```
-(face_trace:5) -[:IDENTIFIED_AS]-> (identity:Audrey Hepburn)   ← wiki 編輯
-(object_instance:42) -[:LABELED_AS]-> (object_class:stamp)     ← wiki 編輯
+(face_trace:5) label="Audrey Hepburn"     ← wiki 編輯
+(object_instance:42) label="郵票 #1"       ← wiki 編輯
 ```
 
 這些編輯累積後，可做為下一版 model training 的 ground truth。
 
+### 實作方向
+
+**DB 層** — 新 table `wiki_entries` + `wiki_revisions`：
+```sql
+wiki_entries (target_type, target_id, title, body, summary, status, version, file_uuid)
+wiki_revisions (entry_id, version, title, body, summary, change_summary, edited_by)
+```
+
+**API 層** — CRUD + 版本歷史：
+```
+GET    /api/v1/wiki/{target_type}/{target_id}
+PUT    /api/v1/wiki/{target_type}/{target_id}
+GET    /api/v1/wiki/{target_type}/{target_id}/revisions
+POST   /api/v1/wiki/search
+```
+
+**打包層** — `release_pack.py` 加入 wiki 匯出，與 model 共存
+
 ---
 
 ## Phase 3：Object Identity（v3 model）