23-agent-active-heartbeat.md 6.12 KB

Edit Raw Blame History


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. 核心流程图
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 系统契合互补。


四、技术优势

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