agent-guardian

# Agent Guardian 🛡️

AI 助手体验守护系统——让用户永远不会觉得你"卡了"或"乱说话"。

## 问题背景

AI 助手在实际使用中常见的体验痛点：
1. **无响应** — 工具调用卡住，用户干等没反馈
2. **状态不透明** — 用户不知道AI在干什么
3. **语言混乱** — 中文对话里夹杂英文短语
4. **任务死循环** — 同一个错误反复重试

## 架构

```
┌─────────────────────────────────────────────┐
│                Agent Guardian               │
├─────────────┬──────────────┬────────────────┤
│ 🐕 看门狗    │ 📊 状态汇报   │ 🔤 语言过滤    │
│ (cron 3min) │ (cron 5min)  │ (出站 hook)    │
├─────────────┼──────────────┼────────────────┤
│ 🔍 即时查询  │ 📝 消息队列   │ ⏰ 活跃追踪    │
│ (systemd)   │ (脚本)       │ (插件 hook)    │
└─────────────┴──────────────┴────────────────┘
```

## 安装

```bash
bash {baseDir}/scripts/install.sh
```

交互式安装，会询问渠道类型和用户ID。

安装后还需：
1. 添加 openclaw cron 看门狗任务（见下方）
2. 应用渠道插件 patch（见 `references/patches/`）
3. 重启 gateway

## 组件说明

### 🐕 看门狗（supervisor.sh）

每3分钟由 openclaw cron 触发，检测：
- 任务卡住（3分钟无状态更新）
- 死循环（同一状态重复5次）
- 错误累积（连续3次错误）
- 僵尸进程

设置 cron 任务示例：
```json
{
  "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 双重语言检测

### 📝...