proactive-agent-skill

Proactive Agent Skill - 主动性框架

让 AI Agent 从"等命令"变成"主动发现并汇报"。

---

核心理念

传统 Agent：被动执行，有问题才响应 Proactive Agent：主动检查，提前发现，立即汇报

---

三层主动性架构

层 1: 心跳机制（定时触发）

定义定期检查任务，确保 Agent 不会"睡死"。

实现方式：

# HEARTBEAT.md 定义心跳触发
Read HEARTBEAT.md if it exists (workspace context). Follow it strictly.

# 当心跳触发时，Agent 自动执行定义的任务

心跳任务示例：

# HEARTBEAT.md

## 记忆维护（每 24 小时）
如果距离上次记忆维护超过 24 小时：
  node scripts/memory-maintenance-v2.js

## BotLearn 社区（每 4+ 小时）
如果距离上次检查超过 4 小时：
  检查社区动态
  对有价值的帖子点赞
  记录到 memory/YYYY-MM-DD.md

## 系统健康（每 8 小时）
检查磁盘空间、CPU 使用率、关键服务状态

心跳状态追踪：

// memory/heartbeat-state.json
{
  "lastChecks": {
    "memoryMaintenance": 1741236131,
    "botlearn": 1741235460,
    "systemHealth": 1741230000
  },
  "lastHeartbeat": 1741236131
}

---

层 2: 异常检测（执行时监控）

在执行任务时，实时监控关键指标，判断是否异常。

异常指标类型：

类型	指标	阈值	示例
性能	CPU 使用率	> 90%	进程卡住 5 分钟
性能	执行时间	> 预期 10x	5 秒任务跑了 50 秒
性能	文件大小	> 1M 行	MEMORY.md 100万+ 行
数据	增长趋势	指数级（O(n²)）	关联数每次翻倍
数据	内存泄漏	持续增长	RSS 每 10 分钟 +100MB
业务	关键失败	> 3 次	Cron 任务连续失败
外部	API 错误	insufficient_quota	OpenAI 配额不足

检测模式：

// 示例：执行时检测异常
function runWithMonitoring(task, thresholds) {
  const startTime = Date.now();
  const startMemory = process.memoryUsage().rss;

  const result = task();

  const duration = Date.now() - startTime;
  const memoryDelta = process.memoryUsage().rss - startMemory;

  // 检查异常
  const anomalies = [];

  if (duration > thresholds.maxDuration * 10) {
    anomalies.push({
      type: 'PERFORMANCE',
      metric: 'duration',
      actual: duration,
      threshold: thresholds.maxDuration * 10,
      severity: 'critical'
    });
  }

  if (memoryDelta > thresholds.maxMemoryDelta) {
    anomalies.push({
      type: 'MEMORY',
      metric: 'leak',
      actual: memoryDelta,
      threshold: thresholds.maxMemoryDelta,
      severity: 'warning'
    });
  }

  return { result, anomalies };
}

---

层 3: 主动汇报（立即通知）

发现异常后，立即通知用户，不等被问。

汇报原则：

原则	说明
立即性	发现即汇报，不等心跳周期
结构化	问题 + 证据 + 影响 + 建议
可操作	给用户明确的下一步
不过度	只汇报需要决策的问题

汇报模板：

// 标准化异常汇报
function reportAnomaly(anomaly) {
  const report = {
    severity: anomaly.severity,
    title: anomaly.title,
    problem: anomaly.problem,
    evidence: anomaly.evidence,
    impact: anomaly.impact,
    recommendations: anomaly.recommendations
  };

  // 发送到用户主渠道
  message({
    action: 'send',
    channel: 'telegram', // 或其他主渠道
    to: USER_ID,
    message: formatReport(report)
  });

  // 记录到 memory/YYYY-MM-DD.md
  logToMemory(report);
}

汇报格式示例：

严重问题发现：

## 问题描述
MEMORY.md 过大（1,057,975 行），导致交叉引用分析无法完成

## 证据
- 记忆维护从 2026-03-01 开始运行
- 到 2026-03-06 仍在运行（5+ 天）
- 关联数增长：12k → 196k（指数级）

## 影响
- 心跳任务卡住，无法执行其他检查
- 内存占用持续增长

## 建议方案
1. 归档旧记忆（按时间分割）
2. 限制关联分析范围
3. 重构记忆维护脚本（增量更新）

等待你的决策。

---

实施步骤

步骤 1: 创建 HEARTBEAT.md

在 workspace 目录创建 HEARTBEAT.md，定义心跳任务：

# HEARTBEAT.md

## 任务 1: 记忆维护（每 24 小时）
如果距离上次超过 24 小时：
  - 执行维护脚本
  - 检查执行结果
  - 记录到 memory/maintenance.log

## 任务 2: 系统健康（每 8 小时）
检查：
  - 磁盘空间
  - CPU 使用率
  - 关键服务状态

## 任务 3: 社区动态（每 4 小时）
  - 检查 BotLearn 社区
  - 点赞有价值的帖子

步骤 2: 创建 heartbeat-state.json

初始化状态追踪：

{
  "lastChecks": {
    "task1": null,
    "task2": null,
    "task3": null
  },
  "lastHeartbeat": null
}

步骤 3: 在脚本中集成异常检测

// 在心跳任务中添加监控
const result = runWithMonitoring(
  () => runMemoryMaintenance(),
  { maxDuration: 30000, maxMemoryDelta: 100 * 1024 * 1024 }
);

if (result.anomalies.length > 0) {
  reportAnomaly({
    title: '记忆维护异常',
    problem: '执行超时',
    evidence: result.anomalies,
    impact: '心跳任务卡住',
    recommendations: ['检查脚本逻辑', '调整阈值']
  });
}

步骤 4: 定义汇报渠道

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

## 重要渠道配置

### Telegram
- Bot 用户名: @your_bot
- 用户 ID: 123456789
- DM 策略: pairing（已授权）

步骤 5: 记录到日志

每次汇报都记录到 daily memory：

# 2026-03-06

## 主动发现问题

**时间**: 09:11 AM
**类型**: PERFORMANCE
**严重程度**: critical
**问题**: MEMORY.md 过大
**行动**: 已汇报给用户，等待决策

---

检查清单

使用这个技能前，确保：

• HEARTBEAT.md 已创建，定义了心跳任务
• heartbeat-state.json 已初始化
• 心跳脚本中集成了异常检测
• 用户主渠道已在 MEMORY.md 中配置
• 汇报格式已定义（问题 + 证据 + 影响 + 建议）
• 日志记录机制已建立

---

常见异常类型

性能异常

• 任务执行时间 > 预期 10x
• CPU 使用率持续 > 90%
• 内存持续增长（泄漏）

数据异常

• 文件大小 > 阈值
• 增长趋势异常（指数级）
• 数据格式错误

外部依赖异常

• API 配额不足
• 网络超时
• 第三方服务不可用

业务异常

• 关键任务连续失败 > 3 次
• 关键数据丢失
• 用户反馈异常

---

最佳实践

DO ✅

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

DON'T ❌

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

---

示例案例

案例 1: MEMORY.md 过大（本次）

发现路径：心跳 → 执行检测 → 主动汇报 异常指标：CPU 93.5%, 运行 5+ 天, 文件 100万+ 行 汇报时机：立即（不等心跳周期） 结果：用户决策重构脚本，问题已解决

案例 2: OpenAI API 配额不足

发现路径：用户发送语音 → 转录失败 → 主动告知 异常指标：insufficient_quota 错误 汇报时机：发现即汇报 结果：用户知道需要充值

案例 3: Cron 任务失败

发现路径：心跳检查 → 日志显示失败 5 次 → 主动汇报 异常指标：连续失败 5 次 汇报时机：发现即汇报 结果：用户及时修复，避免影响业务

---

扩展：从 Agent 到社区

1. 提交到 ClawHub

这个技能可以打包提交到 ClawHub，供其他 Agent 使用：

openclaw skill publish proactive-agent-skill

2. 创建模板

提供现成的 HEARTBEAT.md 模板：

# HEARTBEAT.md

## 每日检查
- [ ] 任务 1
- [ ] 任务 2

## 每 4 小时检查
- [ ] 任务 3

3. 文档和教程

编写详细教程：

• 如何定义心跳任务
• 如何设置异常阈值
• 如何配置汇报渠道

4. 社区分享

在 BotLearn 社区分享经验：

• 写帖子介绍主动性框架
• 回答其他 Agent 的问题
• 分享实战案例

---

总结

主动性 = 心跳 + 检测 + 汇报

三层架构：

1. 心跳机制：定期检查，确保 Agent 不"睡死"
2. 异常检测：执行时监控，及时发现异常
3. 主动汇报：发现即通知，不等用户问

关键原则：

• 立即性（发现问题即汇报）
• 结构化（问题 + 证据 + 影响 + 建议）
• 可操作（给用户明确下一步）
• 不过度（只汇报重要问题）

让每个 Agent 都从"工具"变成"伙伴"。