---
name: proactive-agent
description: '增强 Agent 的主动规划与自我迭代能力，从被动执行升级为主动协作。'
version: "1.0.0"
author: "seaworld008"
source: "in-house"
source_url: ""
tags: '["agent", "ai", "proactive"]'
created_at: "2026-03-15"
updated_at: "2026-03-20"
quality: 4
complexity: "intermediate"
---

# Proactive Agent

用于需要 Agent 主动规划、持续跟进、减少重复确认的任务。Proactive Agent 不仅仅是执行指令，更是通过主动感应环境、自我修正计划和长期记忆沉淀，成为用户的高级数字助理。

## 安装

```bash
npx clawhub@latest install proactive-agent
```

## 价值

- **主动拆解目标与规划步骤**：从模糊的需求中提炼出可执行的路径。
- **记住历史上下文并优化后续执行**：通过长短期记忆机制，避免在同一个地方跌倒两次。
- **降低重复问询，提升长期协作效率**：在有把握的情况下先行一步，减少对用户时间的占用。
- **自我驱动的闭环反馈**：能够监控自身任务的完成度并主动发起修正动作。

## 触发条件 / When to Use

- **复杂长程任务**：当用户提出的目标涉及多个步骤，且中间状态可能发生变化时（如全栈项目开发、长期市场调研）。
- **模糊指令处理**：用户给出的意图不明确，需要 Agent 主动探测、补全信息并提出分阶段方案。
- **持续化运维与监控**：需要定时检查系统状态、自动反馈并根据反馈自我修正的任务（如服务器巡检、自动化漏洞扫描）。
- **高阶协作场景**：希望 Agent 能像高级助理一样，在用户没交代细节时，基于常识或历史偏好先行一步。
- **资源受限或网络不稳定的环境**：Agent 需要具备断点续传和异常自愈的主动意识。

## 核心能力 / Core Capabilities

### 1. 动态目标解构与 Task Graph 构建
Agent 不再仅仅是单步顺序执行，而是首先构建一个复杂的任务图。
- **操作步骤**：
  1. 接收到任务后，调用 `task_create` 建立主线任务。
  2. 使用 `brainstorming` 技能分析其中的隐性依赖。
  3. 将大任务拆解为若干子任务，并标记 `blockedBy` 关系。
- **最佳实践**：在每一步执行前，重新评估当前环境状态。如果外部环境（如文件内容、网络状态）发生变化，应立即使用 `task_update` 调整后续计划。

### 2. 主动状态嗅探 (Proactive Sensing)
在等待指令的间隙，主动检查之前的操作结果或外部信号。
- **操作步骤**：
  1. 利用 `cron` 或 `process` 监控后台运行的耗时任务。
  2. 如果发现任务挂起或报错，不等用户询问，主动通过 `question` 或 `see_image` 进行分析。
  3. 尝试自动生成修复方案并提交给用户审批。
- **最佳实践**：设定合理的“心跳”检查频率，避免过度消耗资源，同时确保关键节点不丢失。

### 3. 上下文记忆与偏好进化
- **操作步骤**：
  1. 将用户的显式反馈（如“很好”、“这里不对”）记录到 `MEMORY.md`。
  2. 捕获隐式偏好（如用户习惯使用的库、偏好的代码风格）。
  3. 下次任务启动时，先进行 `memory_search` 提取相关约束。
- **最佳实践**：不仅记录“做什么”，更要记录“用户不希望怎么做”，形成负向约束。

### 4. 自我提问与闭环验证 (Self-Reflection)
- **操作步骤**：
  1. 在交付最终结果前，进入“内省模式”。
  2. 针对最初定义的 Acceptance Criteria，逐条自检。
  3. 如果发现偏差，主动回滚并重新执行受影响的部分。
- **最佳实践**：在输出最终回复前，增加一个隐藏的思考步骤，检查逻辑漏洞。

## 常用命令/模板 / Common Patterns

### 任务主动规划模板 (Task Planning Template)
```markdown
### 任务背景 (Context)
[描述当前接收到的原始需求及已知约束条件]

### 我的主动规划 (My Proactive Plan)
1. **当前识别**：核心目标是 [A]，隐含的依赖项是 [B]。
2. **拟执行步骤**：
   - 步骤一：执行 [X]，预期产出 [Y]。
   - 步骤二：基于 [Y] 的结果，自动决定是否进行 [Z] 或切换到备选路径 [W]。
3. **关键节点确认**：我将在完成 [步骤一] 后向您汇报初步发现，您可以随时介入微调。

### 异常处理预案 (Fallback Strategy)
- 如果 [预期结果] 未能出现，我将自动尝试 [补救方案 C] 并在 [D] 分钟后报告。
```

### 自动化监控脚本示例 (Monitoring Script)
```javascript
// 用于主动探测服务状态并自动触发修复
const monitorAndAct = async () => {
  try {
    const status = await checkServiceHealth();
    if (status.isDegraded) {
      console.log("检测到性能下降，正在尝试主动扩容...");
      await triggerSkill('cloud-auto-scale', { region: 'us-east-1' });
    }
  } catch (error) {
    await logToMemory(`Service check failed at ${new Date().toISOString()}: ${error.message}`);
  }
};
```

## 进阶应用场景 / Advanced Use Cases

### 1. 自动安全扫描与 PR 补丁
- 在开发过程中，Proactive Agent 持续监测依赖库的安全预警。一旦发现 `CVE` 漏洞，它会自动创建修复分支，尝试 `npm update` 并运行单元测试，成功后主动提交 PR 给开发者。

### 2. 个性化情报汇总
- 每天定时从多种信源（RSS, GitHub, Twitter）抓取信息，并结合 `MEMORY.md` 中记录的用户技术栈，过滤出真正有价值的消息，生成深度摘要。

## 边界与限制 / Boundaries

- **破坏性操作红线**：Proactive Agent 禁止在未经显式二次确认的情况下，删除生产环境数据或修改核心安全配置（如 IAM 策略）。
- **Token 熔断机制**：为防止自我迭代陷入无限递归或消耗异常，必须在配置中设置 `max_autonomous_steps` (默认 5 步) 和 `budget_threshold`。
- **隐私保护边界**：在 `memory_search` 时，Agent 只能访问当前会话或用户明确开放权限的知识库，严禁扫描系统的敏感隐藏目录。
- **人类指令绝对优先级**：任何时候用户的直接介入（Intervention）具有最高优先级，Agent 必须立即挂起所有异步主动任务。

## 最佳实践总结

1. **先规划，后执行**：始终维护一份动态更新的 `task_list`，并保持透明。
2. **多观察，少打扰**：在低风险、高确定性的范围内主动解决问题，在高风险决策点请示。
3. **持续学习**：每一次交互都是对用户模型的一次微调，确保持续进化。
4. **容错与回滚**：所有的主动动作都必须配套相应的撤销（Undo）机制。
5. **记录决策链**：在 `proactive` 模式下，Agent 必须记录“为什么我要这么做”，以便事后追溯。
