Proactive Agent Skill

让 AI Agent 从"等命令"变成"主动发现并汇报问题"的标准化框架。

简介

传统 AI Agent 是被动的：等命令 → 执行 → 报告结果

Proactive Agent 是主动的：

• 定期检查（心跳机制）
• 实时监控（异常检测）
• 提前预警（主动汇报）

核心架构

三层主动性

层级	功能	文件/工具
1. 心跳机制	定期检查任务	HEARTBEAT.md
2. 异常检测	执行时监控指标	heartbeat-helper.js
3. 主动汇报	发现即通知	message 工具

监控的异常类型

• 性能异常：CPU > 90%、执行时间 > 预期 10x
• 数据异常：文件过大、指数级增长
• 外部依赖：API 配额不足、服务不可用
• 业务异常：任务连续失败 > 3 次

安装

方式 1: 从 GitHub 安装

openclaw skill install https://github.com/jiyangnan/proactive-agent-skill.git

方式 2: 手动安装

git clone https://github.com/jiyangnan/proactive-agent-skill.git \
  ~/.openclaw/workspace/skills/proactive-agent-skill

快速开始

步骤 1: 创建 HEARTBEAT.md

在你的 workspace 创建 HEARTBEAT.md：

# HEARTBEAT.md

## 每日检查（24 小时）
如果距离上次超过 24 小时：
  - 检查系统健康
  - 运行维护任务

## 社区动态（4 小时）
如果距离上次检查超过 4 小时：
  - 检查社区帖子
  - 点赞有价值的内容

步骤 2: 初始化状态

创建 memory/heartbeat-state.json：

{
  "lastChecks": {},
  "lastHeartbeat": null
}

步骤 3: 在脚本中集成监控

const {
  runWithMonitoring,
  shouldRunTask,
  recordTaskCheck
} = require('./skills/proactive-agent-skill/scripts/heartbeat-helper.js');

// 定义心跳任务
if (shouldRunTask('dailyCheck', 24)) {
  runWithMonitoring(
    '每日检查',
    () => runDailyCheck(),
    {
      maxDuration: 30000, // 30 秒阈值
      onSuccess: (result, anomalies) => {
        if (anomalies.length > 0) {
          // 发现异常，主动汇报
          reportAnomaly({
            title: '每日检查异常',
            problem: '执行时发现异常',
            evidence: anomalies,
            impact: '无法完成日常检查',
            recommendations: ['检查脚本逻辑', '调整阈值']
          });
        }
      }
    }
  );
  recordTaskCheck('dailyCheck');
}

步骤 4: 配置汇报渠道

在 MEMORY.md 中记录用户主渠道：

## 重要渠道配置

### Telegram
- 用户 ID: 123456789
- DM 策略: pairing

API 文档

loadHeartbeatState()

加载心跳状态文件。

const state = loadHeartbeatState();
// 返回: { lastChecks: {}, lastHeartbeat: timestamp }

shouldRunTask(taskId, intervalHours)

检查任务是否需要运行。

if (shouldRunTask('memoryMaintenance', 24)) {
  // 执行任务
}

runWithMonitoring(taskName, task, options)

监控任务执行并检测异常。

const { result, anomalies } = runWithMonitoring(
  '记忆维护',
  () => runMemoryMaintenance(),
  {
    maxDuration: 30000,        // 最大执行时间（ms）
    maxMemoryDelta: 100 * 1024 * 1024, // 最大内存增长（bytes）
    onSuccess: (result, anomalies) => { },
    onFailure: (error) => { }
  }
);

返回值：

{
  success: boolean,
  result: any,
  anomalies: [
    {
      type: 'PERFORMANCE' | 'MEMORY',
      metric: string,
      actual: number,
      threshold: number,
      severity: 'critical' | 'warning' | 'info',
      message: string
    }
  ],
  duration: number,
  memoryDelta: number
}

formatAnomalyReport(anomaly)

格式化异常汇报。

const report = formatAnomalyReport({
  severity: 'critical',
  title: '严重问题',
  problem: '...',
  evidence: [...],
  impact: '...',
  recommendations: [...]
});

logAnomalyToMemory(anomaly)

记录异常到 daily memory。

logAnomalyToMemory({
  type: 'PERFORMANCE',
  severity: 'critical',
  problem: '...',
  action: '已汇报给用户'
});

示例案例

案例 1: 记忆维护异常

发现：心跳任务执行时 CPU 93.5%，运行 5+ 天

处理：

runWithMonitoring(
  '记忆维护',
  () => runMemoryMaintenance(),
  {
    maxDuration: 60000,
    onSuccess: (result, anomalies) => {
      if (anomalies.length > 0) {
        // 立即汇报给用户
        message({
          action: 'send',
          channel: 'telegram',
          to: USER_ID,
          message: formatAnomalyReport({
            severity: 'critical',
            title: '记忆维护异常',
            problem: 'MEMORY.md 过大（1,057,975 行）',
            evidence: anomalies,
            impact: '心跳任务卡住，无法执行其他检查',
            recommendations: ['归档旧记忆', '重构脚本', '实现增量更新']
          })
        });
        logAnomalyToMemory(anomalies[0]);
      }
    }
  }
);

结果：用户立即收到消息，2 小时内问题解决。

最佳实践

DO ✅

• 主动汇报：发现问题立即通知
• 结构化信息：问题 + 证据 + 影响 + 建议
• 可操作建议：给用户明确的下一步
• 记录日志：每次汇报都记录到 memory
• 适度频次：只汇报重要问题

DON'T ❌

• 沉默不报：等待用户发现
• 模糊描述："出了点问题"（没有证据）
• 过度报警：每个小异常都汇报
• 无建议汇报：只说问题，不给方案
• 忽视反馈：用户说不需要的还要汇报

检查清单

使用这个技能前：

• HEARTBEAT.md 已创建
• heartbeat-state.json 已初始化
• 心跳脚本中集成了异常检测
• 用户主渠道已配置
• 汇报格式已定义
• 日志记录机制已建立

相关资源

• OpenClaw 文档
• BotLearn 社区
• ClawHub

许可证

MIT License - 详见 LICENSE 文件

贡献

欢迎提交 Issue 和 Pull Request！

作者

由 未晞 创建

基于真实场景和实战经验开发。

---

#OpenClaw #主动性 #Agent #心跳机制