# 23. Agent Active Heartbeat System — 主动心跳与监控架构

> **版本**: v1.0 (设计稿)
> **日期**: 2026-03-25
> **状态**: 规划中
> **前置**: Phase 3 记忆架构已完成，OKR 目标大盘已上线

---

## 一、需求背景与痛点

当前的 LemonBoss 架构中，所有的 Agent（包含管理者、执行者、QA 仲裁者等）都处于**“被动响应”**状态。
即：只有当人类或者其他 Agent 发送一条消息（如 `TaskDispatch` 或直接 Chat），它们才会被唤醒并进行一轮推理和动作执行。

**痛点：**
随着 OKR 系统（Goal Nodes）复杂度的增加，如果一个任务的负责人（Owner）迟迟不推进进度，或者产出质量不达标。在没有外部输入时，系统的主节点（如 `qa-judge` 质量裁判，或者 `master` 主节点）只能一直假死等待，这严重违背了“**自主智能体（Autonomous Agent）**”能在后台 24/7 监控并主动下发指令的设计初衷。

**目标：**
使特定的高级 Agent（如 `qa-judge`）具备内建的相对时间感知能力。通过实现一套主推的“心跳机制（Active Heartbeat）”，使其能每隔 N 分钟自动“苏醒”，根据当前注入体内的 OKR 目标大盘数据，主动进行一次进度巡检、质量总结，并主动向下游 Agent 节点派发反馈任务或催办通知。

---

## 二、架构设计原理

由于 LLM（如 Claude）本身是无状态、无法自主定时的算法黑盒，我们必须通过 Node.js 后端作为起搏器（Pacemaker）来主动触碰 Agent 的执行核心。

### 1. 核心流程图

```mermaid
sequenceDiagram
    participant Cron as Node.js Heartbeat Service
    participant Goal as OKR / Goals Data
    participant Agent as qa-judge (Agent)
    participant Worker as poet (Downstream Agent)

    loop 每 N 分钟
        Cron->>Goal: 获取当前活跃的 OKR 大盘状态
        Cron->>Agent: [SYSTEM HEARTBEAT] 唤醒 (无前端UI展示)
        Note over Agent: 挂载 memory、heartbeat.md 及最新 Goal Context
        Agent->>Agent: 推理分析 (是否有节点超时/待验收？)
        
        alt 需要干预
            Agent->>Worker: API调用: TaskDispatch (催促或驳回重做)
            Agent->>Agent: "已向负责人发送警告"
        else 一切正常
            Agent->>Agent: "保持观察，无需操作"
        end
        Agent-->>Cron: 结束本次心跳推理 (保存 session 记录入短期记忆)
    end
```

### 2. 参与模块设计

#### (1) 后端起搏器 (`server/services/heartbeat-service.js`)
- 系统级别的 `setInterval` 或使用 `node-cron` 定时任务管理器。
- 模块初始化时，读取注册了 `cron.json` 或在 `config.json` 中配置了 `active_heartbeat: true` 的全网 Agent。
- 按设定时间周期（如每 5 分钟、或 15 分钟），发起内部进程级或 HTTP `POST /api/agent/:id/chat` 请求。
- **消息构造**：必须带有特殊的标记，如 `[SYSTEM HEARTBEAT] 这是系统周期心跳。时间：{当前时间}。如果无需采取行动，请只回复[心跳正常]；如果发现 OKR 或任务阻塞，请使用你的 dispatch 工具发送跟进动作。`

#### (2) Agent 身份与职责声明 (`data/agents/qa-judge/heartbeat.md`)
这部分将作为心跳特供的系统注入层。因为 Agent 被系统唤醒后可能“不知所措”，所以需要在注入时提供明确的**心跳策略**。
- `qa-judge` 的 `heartbeat.md` 应当规定：
  - 检查当前全局进度是低于预期、正常还是卡点。
  - 对于已经标记为 `ready_for_review` 的节点，主动执行抽样检查工具，如果抽样不通过，则主动调度退回给原作者。
  - 规定其只有遇到问题才说话，没事的时候必须节约 Token，直接结案。

#### (3) 会话隐藏与静默运行 (隐式聊天机制)
为了不污染用户的主聊天界面：
- 心跳触发的 Conversation 应当拥有独特的 ID（如 `heartbeat-177xxxxx`）。
- 在前端 UI（AgentChat.vue）中，如果不特别切换到 heartbeat 专区，应该不展示这类后台巡逻日志，以保持人类界面的干净。
- 但心跳的整个完整推演过程（产生的 session）**必须依然进入现有的 Memory 三层架构**。也就是说，如果 `qa-judge` 在心跳中发出了很多派发任务，这个行为依然会记录进 `short-term/session.md` 里并最终写进日常报表（Daily Report）。

---

## 三、待实现 TODO 计划

- [ ] **1. Heartbeat 后端引擎设计**
  - 在 `server/services/heartbeat-service.js` 实现通用的心跳轮询控制器。
  - 能够读取各个 Agent 配置的 `heartbeatInterval`（支持独立配置时间间隔，如 qa-judge 15分钟，master 30分钟）。
- [ ] **2. 隐式对话 API (`agent-chat.js` 支持)**
  - 修改 `agent-chat.js` 中的底层 ACP 唤起逻辑，支持传入 `silent: true` 以及 `isHidden` 参数。
  - 确保这些会话依然会经历 Phase 1 的记忆提取。
- [ ] **3. `qa-judge` 的专项 prompt 优化**
  - 完善 `qa-judge/heartbeat.md` 与 `qa-judge/cron.json`，使其明确自己“裁判+巡检”的作用和判定 OKR 进度的标准。
- [ ] **4. 拦截发散风暴 (Anti-Loop 制衡机制)**
  - 防止 Agent 每次心跳都在给别人发重复的警告。
  - **方案**：因为有 Memory 架构的存在，Agent 在心跳前会读到自己最近的 session（如“我在 15分钟前刚发过催促”），因此可以通过 prompt 指导它：“如果发现最近一次记忆中已经催促过了，请安静等待至少半天再做后续操作”。这完美与最新的 22 号文档中完成的 Memory 系统契合互补。

---

## 四、技术优势

1. **“起搏”+“记忆”打造真实自主引擎**：依赖已实现的海马体与短期记忆，Agent 不再是简单的代码循环，而是拥有自己时间轴与经验累积的鲜活生命体。
2. **极低侵入性**：依然可以复用现有的 Claude CLI 通道和 `runClaudeCliSession` 函数，仅仅是多了一个虚拟的“系统定时发信人”。
3. **闭环 OODA loop**：观察（OKR数据注入）- 导向（heartbeat.md规则）- 决策（推理判定）- 行动（ToolDispatch），在此实现完整的智能自主控制闭环。