Agent Guardian 🛡️

AI 助手體驗守護系統——讓使用者永遠不會覺得你"卡了"或"亂說話"。

問題背景

AI 助手在實際使用中常見的體驗痛點：

1. 無響應 — 工具呼叫卡住，使用者乾等沒反饋
2. 狀態不透明 — 使用者不知道AI在幹什麼

   7w4.net收錄了海量優質技能外掛。

3. 語言混亂 — 中文對話裡夾雜英文短語
4. 任務死迴圈 — 同一個錯誤反覆重試

架構

┌─────────────────────────────────────────────┐
│                Agent Guardian               │
├─────────────┬──────────────┬────────────────┤
│ 🐕 看門狗    │ 📊 狀態彙報   │ 🔤 語言過濾    │
│ (cron 3min) │ (cron 5min)  │ (出站 hook)    │
├─────────────┼──────────────┼────────────────┤
│ 🔍 即時查詢  │ 📝 訊息佇列   │ ⏰ 活躍追蹤    │
│ (systemd)   │ (指令碼)       │ (外掛 hook)    │
└─────────────┴──────────────┴────────────────┘

安裝

bash {baseDir}/scripts/install.sh

互動式安裝，會詢問渠道型別和使用者ID。

安裝後還需：

1. 新增 openclaw cron 看門狗任務（見下方）
2. 應用渠道外掛 patch（見 references/patches/）
3. 重啟 gateway

元件說明

🐕 看門狗（supervisor.sh）

每3分鐘由 openclaw cron 觸發，檢測：

• 任務卡住（3分鐘無狀態更新）
• 死迴圈（同一狀態重複5次）
• 錯誤累積（連續3次錯誤）
• 殭屍程序

設定 cron 任務示例：

{
  "name": "agent-guardian-watchdog",
  "schedule": { "kind": "cron", "expr": "*/3 * * * *", "tz": "Asia/Shanghai" },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "讀取 /tmp/agent-supervisor-report.txt，如果有告警內容就發給使用者，沒有就回復 HEARTBEAT_OK"
  }
}

📊 智慧狀態彙報（smart-status-report.sh）

系統 crontab 每5分鐘執行，智慧開關：

• 對話時（最近10分鐘有訊息）→ 推送狀態
• 沉默時 → 自動靜默，不打擾

🔍 即時狀態查詢（status-query-daemon.sh）

使用者發"狀態"→ 渠道外掛攔截 → 寫觸發檔案 → 守護程序秒回 不經過AI，即使AI卡死也能響應。

🔤 語言一致性過濾（lang-filter.py + detect-language.py）

出站訊息自動檢測並替換常見英文混用。

• 70+ 常見英文短語對映（金融/日常/科技）
• 技術術語白名單保護（AI/API/GDP等不替換）
• 字元集 + langdetect 雙重語言檢測

📝 訊息佇列（msg-queue.py）

追蹤每條訊息的處理狀態（waiting → processing → done）。

• 自動超時：processing 超5分鐘自動標記完成
• 日報統計：今日處理數量

AI 幹活時的狀態更新

在執行任務時呼叫：

bash {baseDir}/scripts/update-work-state.sh working "任務描述"

完成時：

bash {baseDir}/scripts/update-work-state.sh done

出錯時：

bash {baseDir}/scripts/update-work-state.sh error "任務描述" "yes"

渠道適配

• QQ Bot: 詳見 references/patches/qqbot.md
• 通用指南: 詳見 references/patches/generic.md
• 核心原理：在入站（收訊息）和出站（發訊息）兩個 hook 點插入 Guardian 邏輯

不修改外掛的降級模式

即使不 patch 渠道外掛，看門狗和定時彙報仍可獨立執行。 語言過濾和即時查詢需要外掛 patch 才能完全生效。

檔案清單

scripts/
├── install.sh              # 一鍵安裝
├── supervisor.sh            # 看門狗
├── update-work-state.sh     # 工作狀態更新
├── smart-status-report.sh   # 智慧彙報
├── status-query-daemon.sh   # 即時查詢守護程序
├── detect-language.py       # 語言檢測
├── lang-filter.py           # 語言過濾
├── msg-queue.py             # 訊息佇列
└── reset-work-state.sh      # 狀態重置
references/
└── patches/
    ├── qqbot.md             # QQ Bot 適配指南
    └── generic.md           # 通用適配指南

這個 Skill 解決了 AI 助手"卡了不回覆"、"中英文混著說"、"不知道在幹嘛"等常見煩人問題，用多個指令碼配合監控和彙報，體驗提升明顯。文件寫得很清楚，安裝指引詳細。主要缺點是有些功能需要改外掛程式碼才能完全生效，維護起來有點麻煩；語言過濾只覆蓋常見英文短語，專業術語可能漏掉。總體質量不錯，但自動化程度還有提升空間。