#!/usr/bin/env python3
"""
EwoooC — AI 自主學習流程 Skill
skill: ai-self-learning-flow
version: 1.0.0
updated: 2026-04-18

用途：指導 Claude 在執行任何 AI 功能改動時，完整走過三層沉澱流程。
遵循 ADR-001（三 Agent 分工）、ADR-007（雙寫規範）、Memory 規範。
"""

SKILL_DESCRIPTION = """
# EwoooC AI 自主學習流程 (ai-self-learning-flow)

## 觸發條件
當統帥要求「新增 AI 功能」、「修改 AI 洞察寫入邏輯」、「新增 KM 記錄類型」時，
Claude 應主動走過此 Skill 的三層 Checklist。

## Phase 1：規劃（5 分鐘）

### 1.1 確認 Agent 歸屬
- [ ] 此功能屬於採集層（Hermes）？
- [ ] 此功能屬於處理層（NemoTron）？
- [ ] 此功能屬於應用層（OpenClaw）？
- [ ] 有無跨層的資料傳遞？傳遞格式？

### 1.2 確認雙寫需求（ADR-007）
- [ ] 是否有 AI 產出需要沉澱？（PPT 洞察、競品分析、對話）
- [ ] DB sink：哪張表？哪些欄位？
- [ ] KM sink：是否需要 embedding？哪個模型？維度？

### 1.3 確認成本影響
- [ ] 是否增加 NemoTron 每日 tool call 次數？
- [ ] 是否增加 OpenClaw API 費用？
- [ ] 月成本目標：Hermes=$0, NemoTron=$0, OpenClaw<$5

## Phase 2：執行（主要開發）

### 2.1 Hermes 採集層（若適用）
```python
# services/hermes_analyst_service.py 或新服務
# 任務：embedding、tag、去重、品質分數
# 連線：http://192.168.0.111:11434/api/embeddings
# 模型：bge-m3 (1024 dim)
```

### 2.2 NemoTron 處理層（若適用）
```python
# services/nemoton_dispatcher_service.py
# 任務：tool calling 寫入、分類派發
# 注意：HTTP 429 → fallback 到 _hermes_rule_fallback() (ADR-004)
```

### 2.3 OpenClaw 應用層（若適用）
```python
# services/gemini_service.py 或 ppt_generator.py
# 任務：最終生成、RAG 引用歷史洞察
# RAG 查詢需套用時間衰減（ADR-005）
```

### 2.4 DB Migration（若需新欄位）
```sql
-- 放在 migrations/NNN_description.sql
-- 新欄位遵循現有命名規範（snake_case）
-- embedding 欄位：vector(1024) 搭配 HNSW 索引
```

## Phase 3：驗證（完成後必做）

### 3.1 本地測試
- [ ] 手動觸發一次完整流程（採集 → 處理 → 應用）
- [ ] 確認 DB 有寫入資料
- [ ] 確認 embedding 欄位不為 NULL
- [ ] 確認 Telegram 告警（若有）格式正確

### 3.2 Fallback 測試（NemoTron 相關必做）
- [ ] 模擬 NIM 回 429，確認 degraded 模式正常啟動
- [ ] 確認降級訊息有 🟡 標記

### 3.3 三層沉澱（每次完成必做）
- [ ] `docs/adr/ADR-XXX.md` — 有無需新建 ADR？（重大決策才建）
- [ ] `docs/AI_INTELLIGENCE_MODULE_SOT.md` — 更新架構圖或表格
- [ ] `memory/` — 有無新的 project/feedback memory 需要寫入？
- [ ] `CLAUDE.md` — 有無新的憲法條款？
- [ ] `TODO_NEXT_STEPS.txt` — 標記完成項目 ✅

## 常見問題

### Q: 這個 insight 該用哪個 `insight_type`？
| 類型 | 適用場景 |
|---|---|
| `price_alert` | 競價告警分析 |
| `ppt_insight` | PPT 生成洞察 |
| `weekly_trend` | 週報 meta-analysis |
| `conversation` | 用戶對話記錄 |
| `structural` | 不變的結構知識（不套時間衰減） |
| `constitutional` | 專案憲法類（不套時間衰減） |

### Q: 需要建新 ADR 的判斷標準？
以下情況需建 ADR：
- 引入新的外部依賴（新 API、新資料庫、新模型）
- 改動資料庫 schema（不含純加欄位的 migration）
- 改變 AI 路由邏輯（哪個 Agent 做什麼）
- 改變成本結構（預計月費增加 > $1 USD）

以下不需建 ADR：
- Bug fix
- 效能優化（不改架構）
- 新增 Telegram 告警模板
- UI 改動

### Q: embedding 失敗時怎麼辦？
1. DB 先寫入（`embedding = NULL`）
2. 放入 retry queue（`embedding_retry_queue` 表）
3. Hermes batch job 每天 03:00 重試所有 `embedding IS NULL` 的記錄
"""

if __name__ == "__main__":
    print(SKILL_DESCRIPTION)
