23-agent-active-heartbeat.md 6.19 KB

Edit Raw Blame History


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

版本: v2.0 (已实现)
日期: 2026-03-26
状态: ✅ 已完成 (Agent 级 + 公司级心跳均已上线)
前置: 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）。


三、实现状态

[x] 1. Heartbeat 后端引擎


server/services/heartbeat-service.js — Agent 级心跳服务（按 config.json 中的 heartbeatInterval 独立配置）
server/services/company-heartbeat-service.js — 公司级心跳服务（扫描所有公司，按 company.json 心跳配置唤醒 CEO）
已适配 multi-tenant 架构，支持 system/agents/ + data/{companyId}/agents/ 双路径

[x] 2. 隐式对话 API


agent-chat.js 支持 silent: true 模式，心跳会话不污染前端主界面
会话依然经历 Memory 三层架构，记录进 short-term + reflections

[x] 3. Agent 心跳策略


每个 Agent 的 heartbeat.md 定义专项心跳行为（如 CEO 早间巡检、晚间复盘）
模板库中 CEO/COO 等模板已包含 heartbeat.md

[x] 4. 前端心跳控制


CompanyDashboard.vue per-agent 心跳开关（启动/停止/配置间隔）
API: PUT /api/company/:companyId/agents/:agentId/heartbeat
API: POST /api/company/:companyId/agents/:agentId/heartbeat/start
API: POST /api/company/:companyId/agents/:agentId/heartbeat/stop

[x] 5. Anti-Loop 制衡


借助 Memory 架构，Agent 在心跳前读取最近 session，避免重复催促


四、技术优势

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