Agent Guardian

Agent体验守护系统。解决AI助手常见体验问题：长时间无响应、任务卡死、中英文混用、状态不透明。包含看门狗监控、智能状态汇报、即时状态查询、语言一致性过滤、消息队列追踪。适用于所有渠道（QQ/微信/Telegram/飞书/Discord等）。当用户抱怨"等太久没回复"、"回复中英文混着"、"不知道在干什么"时使...

Security Scan

The skill's code and instructions mostly match its described monitoring/filtering purpose, but it asks to modify other plugins and system services (crontab/systemd) and injects execSync hooks into gateway code — actions that require high privileges and warrant careful review before installation.

Purpose & Capability

The files (watchdog, status reporter, language filter, message queue, channel patch guides) align with the stated goal of monitoring and improving agent UX. Requesting no API keys or env vars is consistent. However, the skill expects to patch channel plugin source code and to run system-level services (cron/systemd), which is more invasive than a purely runtime filter and should be justified by the operator.

Instruction Scope

SKILL.md and scripts instruct the agent/operator to: modify channel plugin source (gateway/outbound), add execSync calls that invoke the skill's scripts, write and read /tmp state files, add crontab entries, and install/enable a systemd service running as root. Those instructions go beyond simple in-process helpers — they alter other plugin code and introduce external command execution points inside the gateway process.

Install Mechanism

There is no packaged install spec; install.sh is an interactive local installer that sets permissions, installs python/apt packages (langdetect, inotify-tools), edits crontab, and writes a systemd unit. No remote downloads or obscure URLs are used (pip/apt are standard), but the installer requires root/system access to modify systemd and crontab.

Credentials

The skill does not request credentials or environment variables. It uses the openclaw CLI to send messages (so the gateway must already be configured). Notably, instead of env/secret requests it relies on filesystem and service-level access.

Persistence & Privilege

The installer creates a systemd service (runs as root), adds cron jobs, and the provided patch script will modify other plugin source files under the gateway extension directory. Writing systemd units and patching other skill/plugin code are privileged, persistent actions and increase blast radius if the skill or its scripts are later modified.

What to consider before installing

This skill is generally coherent with its described purpose, but it is invasive: the installer edits channel plugin source, adds cron/systemd services, and executes scripts as root. Before installing, do the following: 1) Review all scripts (install.sh, apply-qqbot-patch.sh, and the scripts/ directory) line-by-line and confirm paths are correct; 2) Backup your gateway/plugin source and configuration; 3) Test in an isolated environment or container first (not a production gateway); 4) Prefer to apply channel patches manually so you control the exact code changes (the automatic patcher appears brittle and may insert invalid code); 5) Ensure openclaw CLI behavior and permissions are acceptable — the skill uses openclaw message send and expects the gateway to be configured; 6) Consider running the service under a low-privilege user rather than root and avoid granting write access to other skills' directories. If you cannot audit or isolate these changes, do not install in production.

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

问题背景

AI 助手在实际使用中常见的体验痛点：

1. 无响应 — 工具调用卡住，用户干等没反馈
2. 状态不透明 — 用户不知道AI在干什么
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           # 通用适配指南