wooo/awoooi
1
1
Fork 0
Code Issues 2 Pull Requests 1 Actions 4 Packages Projects Releases Wiki Activity

docs: 新增 Telegram 訊息模板規範 v1.0

Browse Source 
定義 12 種訊息類別:
- 6 種已實作 (Incident/CI/PR/Exec/Heartbeat/Silence)
- 6 種待實作 (Sentry/Resource/Repair/Daily/Deploy/RateLimit)

包含:
- 完整模板格式
- 按鈕功能對照表
- Emoji 使用規範
- 字元限制規則
- 實作優先級 (P1: 5h, P2: 5h, P3: 1h)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
OG T
2026-03-29 20:44:16 +08:00
parent 21e08fbabb
commit 1eb0be8f3f
1 changed files with 475 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

475
docs/reference/TELEGRAM_MESSAGE_TEMPLATES.md Normal file
View File

@@ -0,0 +1,475 @@
# Telegram 訊息模板規範
> **版本**: v1.0
> **建立日期**: 2026-03-29 (台北時區)
> **負責人**: CIO
> **用途**: 定義所有 Telegram 告警訊息的標準格式
---
## 訊息類別總覽
| # | 類別 | 代碼 | 按鈕 | 狀態 |
|---|------|------|------|------|
| 1 | Incident Alert | `INCIDENT` | 4-5 顆 | ✅ 已實作 |
| 2 | CI Failure Diagnosis | `CI_FAILURE` | 0 顆 | ✅ 已實作 |
| 3 | GitHub PR Review | `PR_REVIEW` | 0 顆 | ✅ 已實作 |
| 4 | Execution Result | `EXEC_RESULT` | 0 顆 | ✅ 已實作 |
| 5 | Heartbeat | `HEARTBEAT` | 0 顆 | ✅ 已實作 |
| 6 | Silence Alert | `SILENCE` | 0 顆 | ✅ 已實作 |
| 7 | Sentry Error | `SENTRY_ERROR` | 2 顆 | 🆕 待實作 |
| 8 | Resource Exhaustion | `RESOURCE_WARN` | 2 顆 | 🆕 待實作 |
| 9 | Auto-Repair Report | `REPAIR_REPORT` | 0 顆 | 🆕 待實作 |
| 10 | Daily Summary | `DAILY_SUMMARY` | 0 顆 | 🆕 待實作 |
| 11 | Deployment Success | `DEPLOY_SUCCESS` | 0 顆 | 🆕 待實作 |
| 12 | Rate Limit Warning | `RATE_LIMIT` | 0 顆 | 🆕 待實作 |
---
## 已實作訊息模板
### 1️⃣ Incident Alert (INCIDENT)
**檔案**: `telegram_gateway.py:99` - `TelegramMessage`
**按鈕配置**:
```
第一行: [✅ 簽核] [❌ 拒絕]
第二行: [⏰ 稍後] [🔕 靜默 1h]
第三行: [⚡ 執行自動調優] (可選，有 auto_tuning_command 時顯示)
```
**模板**:
```
═══════════════════════════
🚨 CRITICAL | harbor-core
═══════════════════════════
📋 INC-20260321-0001
🎯 資源: harbor-core-7d4b8c9f5
━━━━━━━━━━━━━━━━━━━
🤖 Gemini 仲裁
👥 責任: ⚙️ BE (後端)
📊 信心: 🟢 88%
💰 Tokens: 1,234 / $0.0012
💡 原因: JVM Heap 配置不當
━━━━━━━━━━━━━━━━━━━
📊 頻率統計 ⚠️
├ 1h: 3 次
├ 24h: 8 次
└ 修復: 2 次
🔺 升級: REPEAT
━━━━━━━━━━━━━━━━━━━
📊 SignOz 指標
├ RPS: 150.2 📈
├ Error: 🟢 0.5%
└ P99: 245ms ➡️
━━━━━━━━━━━━━━━━━━━
🔧 建議: 刪除 Pod
⏱️ 停機: ~30s
🔍 查看 SignOz Trace (±5min)
[✅ 簽核] [❌ 拒絕]
[⏰ 稍後] [🔕 靜默 1h]
[⚡ 執行自動調優]
```
**按鈕功能**:
| 按鈕 | Callback | Handler | 功能 |
|------|----------|---------|------|
| ✅ 簽核 | `approve` | `sign_approval()` | 執行建議操作 |
| ❌ 拒絕 | `reject` | `reject_approval()` | 拒絕並記錄 |
| ⏰ 稍後 | `snooze` | `_handle_snooze()` | 30 分鐘後再提醒 |
| 🔕 靜默 1h | `silence` | `_handle_silence()` | 同資源告警靜默 1 小時 |
| ⚡ 執行自動調優 | `tune` | 執行 kubectl 指令 | 自動調整資源配置 |
---
### 2️⃣ CI Failure Diagnosis (CI_FAILURE)
**檔案**: `github_webhook.py:1186`
**按鈕**: 無
**模板**:
```
🔴 **CI 失敗診斷** | awoooi
📋 **Workflow**: CD
👤 **觸發者**: ogt
🔗 [查看 Workflow](https://github.com/...)
📝 **摘要**: Build failed due to missing dependency
🔍 **根因**: prometheus-client package not installed
⚠️ **錯誤類型**: DEPENDENCY_ERROR
🎯 **風險等級**: MEDIUM
🔧 **修復決策**: 🤖 自動修復
💡 **AI 建議**:
1. 安裝 prometheus-client 依賴
2. 更新 pyproject.toml
🔨 **修復選項**:
1. `AUTO_FIX` (85% 信心)
`pip install prometheus-client`
🆔 `CI-20260329-0001`
```
---
### 3️⃣ GitHub PR Review (PR_REVIEW)
**檔案**: `github_webhook.py:1400+`
**按鈕**: 無
**模板**:
```
📝 **PR 審核** | awoooi
🔗 PR #123: feat: 新增 NVIDIA 整合
👤 作者: @ogt
📋 審核者: @reviewer
✅ **已通過**
💬 評論: LGTM! 程式碼品質良好
```
---
### 4️⃣ Execution Result (EXEC_RESULT)
**檔案**: `approval_execution.py:250` - `NotificationMessage`
**按鈕**: 無
**模板 (成功)**:
```
✅ **執行完成** | restart-pod
📋 Approval: APR-20260329-0001
🔧 操作: RESTART_DEPLOYMENT
📁 Namespace: awoooi-prod
⏱️ 耗時: 2.3s
👥 簽核者:
- @ogt: 已授權
🎯 影響:
├ Pod 數: 2
├ 停機: ~30s
└ 服務: awoooi-api
```
**模板 (失敗)**:
```
❌ **執行失敗** | restart-pod
📋 Approval: APR-20260329-0001
🔧 操作: RESTART_DEPLOYMENT
📁 Namespace: awoooi-prod
⚠️ 錯誤: Deployment not found
👥 簽核者:
- @ogt: 已授權
```
---
### 5️⃣ Heartbeat (HEARTBEAT)
**檔案**: `telegram_gateway.py:1408`
**按鈕**: 無
**模板**:
```
📡 告警鏈路: ✅ 正常
⏰ 2026-03-29 12:00 (台北)
🔗 AWOOOI API → Telegram
```
---
### 6️⃣ Silence Alert (SILENCE)
**檔案**: `telegram_gateway.py:1462`
**按鈕**: 無
**模板**:
```
⚠️ **沉默告警**
Telegram 已 **2 小時**沒有收到任何訊息！
請檢查告警鏈路是否正常運作。
🔗 檢查項目:
├ Alertmanager → AWOOOI API
├ OpenClaw → Telegram Bot
└ K8s NetworkPolicy
```
---
## 🆕 待實作訊息模板
### 7️⃣ Sentry Error (SENTRY_ERROR)
**優先級**: P1
**按鈕配置**:
```
第一行: [🔍 查看詳情] [🔕 靜默 1h]
```
**模板**:
```
═══════════════════════════
🐛 SENTRY ERROR | awoooi-api
═══════════════════════════
📋 SENTRY-abc123
🎯 錯誤: TypeError: Cannot read property 'x'
━━━━━━━━━━━━━━━━━━━
📊 統計
├ 發生次數: 15
├ 影響用戶: 3
└ 首次發生: 10 分鐘前
━━━━━━━━━━━━━━━━━━━
📍 位置: src/api/v1/incidents.py:123
🔗 Stack Trace (前 3 行):
→ incidents.py:123 in get_incident
→ service.py:45 in fetch_data
→ db.py:89 in query
🔍 [查看 Sentry](http://192.168.0.110:9000/...)
[🔍 查看詳情] [🔕 靜默 1h]
```
---
### 8️⃣ Resource Exhaustion (RESOURCE_WARN)
**優先級**: P1
**按鈕配置**:
```
第一行: [⚡ 自動擴展] [🔕 靜默 1h]
```
**模板**:
```
═══════════════════════════
⚠️ 資源告警 | awoooi-api
═══════════════════════════
📋 RES-20260329-0001
🎯 Pod: awoooi-api-7d4b8c9f5-abc12
━━━━━━━━━━━━━━━━━━━
📊 資源使用率
├ CPU: 🔴 92% (limit: 500m)
├ Memory: 🟡 78% (limit: 512Mi)
└ Disk: 🟢 45%
━━━━━━━━━━━━━━━━━━━
📈 趨勢: 過去 30 分鐘上升 25%
💡 建議: 增加 replicas 或調整 limits
[⚡ 自動擴展] [🔕 靜默 1h]
```
---
### 9️⃣ Auto-Repair Report (REPAIR_REPORT)
**優先級**: P2
**按鈕**: 無
**模板**:
```
═══════════════════════════
🔧 自動修復報告 | 每日彙總
═══════════════════════════
📅 2026-03-29
━━━━━━━━━━━━━━━━━━━
📊 統計
├ 總修復次數: 12
├ 成功: ✅ 10 (83%)
├ 失敗: ❌ 2 (17%)
└ 節省人工: ~45 分鐘
━━━━━━━━━━━━━━━━━━━
🔝 Top 3 問題:
1. Pod CrashLoopBackOff (5 次)
2. OOM Killed (4 次)
3. Image Pull Failed (3 次)
━━━━━━━━━━━━━━━━━━━
💰 AI 成本
├ Gemini: $0.0234 (1,823 tokens)
├ Nvidia: $0.00 (免費)
└ 總計: $0.0234
```
---
### 🔟 Daily Summary (DAILY_SUMMARY)
**優先級**: P2
**按鈕**: 無
**模板**:
```
═══════════════════════════
📊 每日摘要 | AWOOOI
═══════════════════════════
📅 2026-03-29
━━━━━━━━━━━━━━━━━━━
🚨 告警統計
├ 總數: 45
├ Critical: 2
├ Medium: 18
└ Low: 25
━━━━━━━━━━━━━━━━━━━
✅ 處理統計
├ 自動修復: 30 (67%)
├ 人工簽核: 10 (22%)
├ 忽略/靜默: 5 (11%)
└ 平均回應: 2.3 分鐘
━━━━━━━━━━━━━━━━━━━
📈 可用性
├ API: 99.95%
├ Web: 99.98%
└ Worker: 99.90%
━━━━━━━━━━━━━━━━━━━
💰 成本
├ AI: $0.15
├ 雲端: $0.00
└ 預算剩餘: $9.85
```
---
### 1️⃣1️⃣ Deployment Success (DEPLOY_SUCCESS)
**優先級**: P3
**按鈕**: 無
**模板**:
```
✅ **部署成功** | awoooi
📋 Commit: abc1234
👤 觸發者: @ogt
📁 環境: Production
━━━━━━━━━━━━━━━━━━━
📊 部署詳情
├ API: v1.2.3 ✅
├ Web: v1.2.3 ✅
├ Worker: v1.2.3 ✅
└ 耗時: 3m 45s
━━━━━━━━━━━━━━━━━━━
🧪 E2E 測試: 26/26 PASSED
📊 健康檢查: ✅ 全部通過
🔗 [查看 Workflow](https://github.com/...)
```
---
### 1️⃣2️⃣ Rate Limit Warning (RATE_LIMIT)
**優先級**: P1
**按鈕**: 無
**模板**:
```
⚠️ **API 限額警告**
━━━━━━━━━━━━━━━━━━━
📊 Gemini API
├ 今日用量: 450/500 (90%)
├ Token: 85,000/100,000
└ 成本: $0.08
💡 建議:
- 考慮切換到 Ollama 優先
- 或增加每日限額
🔄 將於明日 00:00 重置
```
---
## 按鈕 Callback 對照表
| Callback | Handler | 功能 | 適用訊息 |
|----------|---------|------|----------|
| `approve` | `sign_approval()` | 簽核執行 | INCIDENT |
| `reject` | `reject_approval()` | 拒絕執行 | INCIDENT |
| `snooze` | `_handle_snooze()` | 延遲 30 分鐘 | INCIDENT |
| `silence` | `_handle_silence()` | 靜默 1 小時 | INCIDENT, SENTRY_ERROR, RESOURCE_WARN |
| `tune` | kubectl 執行 | 自動調優 | INCIDENT |
| `scale` | HPA 觸發 | 自動擴展 | RESOURCE_WARN |
| `view` | 開啟連結 | 查看詳情 | SENTRY_ERROR |
---
## 訊息格式規範
### Emoji 使用規則
| 類別 | Emoji | 用途 |
|------|-------|------|
| 嚴重度 | 🚨 🔴 ⚠️ ℹ️ | Critical/High/Medium/Low |
| 狀態 | ✅ ❌ 🟢 🟡 | 成功/失敗/正常/警告 |
| 操作 | 🔧 ⚡ 🔍 📊 | 修復/執行/查看/統計 |
| 資源 | 📋 🎯 📁 👤 | ID/資源/目錄/用戶 |
| 成本 | 💰 💵 | Token/費用 |
### 分隔線樣式
```
═══════════════════════════ # 主標題分隔 (27 個 ═)
━━━━━━━━━━━━━━━━━━━ # 區塊分隔 (19 個 ━)
├ ─ └ # 樹狀結構
```
### 字元限制
- 總長度: **900 字元** (Telegram 限制 4096，預留空間)
- 標題: **25 字元**
- 摘要: **50 字元**
- 操作建議: **35 字元**
---
## 實作優先級
| 優先級 | 訊息類別 | 預估工時 |
|--------|----------|----------|
| 🔴 P1 | SENTRY_ERROR | 2h |
| 🔴 P1 | RESOURCE_WARN | 2h |
| 🔴 P1 | RATE_LIMIT | 1h |
| 🟠 P2 | REPAIR_REPORT | 2h |
| 🟠 P2 | DAILY_SUMMARY | 3h |
| 🟡 P3 | DEPLOY_SUCCESS | 1h |
| **總計** | | **11h** |
---
## 變更記錄
| 日期 | 版本 | 內容 |
|------|------|------|
| 2026-03-29 | v1.0 | 初始建立，定義 12 種訊息模板 |