🎖️ 任务奖励 — 学完你能做到
配置出稳定运行的 Heartbeat，让 AI 每天主动汇报进度而不是等你问
📖 本章目标：了解 Heartbeat 的三大已知 Bug 和子 Agent 的配置陷阱，避免踩坑
8.1 三大已知 Bug
❌ Bug 1：heartbeat.model 污染主 session（Issue #22133）
状态：Open（2026-02-20）
症状：配置本地 Ollama 作为 heartbeat 专用模型时，heartbeat 触发后不只影响 heartbeat，还会把主 session 的模型也切换成 Ollama 模型。
影响：你的主对话突然变成本地小模型在回答，质量大幅下降。
临时解法：
不要在主配置中设置
heartbeat.model为 Ollama 模型。等待官方补丁，或改用 model fallback 链。
❌ Bug 2：本地模型 heartbeat 不加载工作区文件（Issue #10002）
状态：已修复（升级最新版验证）
症状：Ollama 模型执行 heartbeat 时，HEARTBEAT.md / SOUL.md 等文件不被注入。heartbeat 的行为完全不可控。
临时解法：
升级到最新版后测试。若仍有问题，在
HEARTBEAT.md开头直接写出所有指令内容，不要依赖文件注入。
❌ Bug 3：Breaking Change — heartbeat DM 默认值反复横跳
症状：
| 版本 | 默认行为 |
|---|---|
| 2026.2.24 | heartbeat DM 默认关闭 |
| 2026.2.25 | heartbeat DM 默认改回 allow |
从 .24 升级到 .25 后，agent 会突然开始主动发 DM，惊吓用户。
解法：
在配置中明确写死，不要依赖默认值：
"delivery": { "directMessage": false }
8.2 Heartbeat 完整配置参考
"agent": {
"heartbeat": {
"every": "1h",
"target": "last",
"delivery": {
"directMessage": false
}
}
}HEARTBEAT.md 中必须加的 CONTRACT
// CONTRACT: Reply HEARTBEAT_OK if nothing needs attention.这行 CONTRACT 是框架识别”无事可报”的信号，能避免 agent 发出大量无意义消息。
8.3 子 Agent 已知 Bug（Issue #24852）
状态：Open（2026-02-21）
❌ 踩坑
通过 sessions_spawn 创建子 agent 后，子 agent 只加载：
- ✅
AGENTS.md - ✅
TOOLS.md
不加载：
- ❌
SOUL.md - ❌
IDENTITY.md - ❌
USER.md
结果：子 agent 不知道自己的角色，行为完全通用化。
✅ 临时解法
方法一：在 AGENTS.md 开头手动内嵌关键角色定义
# AGENTS.md
## 角色定义（子 agent 临时嵌入，待 #24852 修复后可移除）
我是 [名字]，[角色描述]。我的核心原则是 [...]方法二：在 sessions_spawn 的 task 参数中直接包含上下文
task: "你是 [名字]，[角色描述]。你的任务是：[具体任务]"8.4 Heartbeat vs Cron 决策树
这个任务需要 LLM 语义判断吗？
├── 是 → 用 Heartbeat
│ ↓
│ 频率高于 1 小时吗？
│ ├── 是 → 考虑是否真的需要这么频繁
│ └── 否 → 配置 every: "1h"
│
└── 否 → 用 Cron
↓
固定时间执行 → sessionTarget: 'isolated'