Nexus/docs/design/plans/2026-06-08-agent-401-stop-heartbeat.md

2026-06-08 — Agent 401 停心跳（A-05）

背景

BL-06 后中心仅接受 per-server agent_api_key；错误 key 时心跳 401。边端 Agent 须停止 while True 重试，避免日志与无效流量。72d82d7 已加 401 return，本子任务补齐可测策略、配置重载后重启心跳、子机 rollout 说明。

方案

1. web/agent/heartbeat_policy.py — heartbeat_should_stop(status_code, body) 纯函数
2. agent.py — 401 / discarded 统一走策略；AGENT_VERSION 常量 SSOT
3. /config/reload 更新 key 后 _start_heartbeat_task() 重启已停止的心跳协程
4. 子机需 批量升级 Agent 拉取含本逻辑的 agent.py（backlog #7）

涉及文件

• web/agent/heartbeat_policy.py
• web/agent/agent.py
• server/utils/agent_version.py — 读 AGENT_VERSION 常量
• tests/test_agent_heartbeat_stop.py

验证

pytest tests/test_agent_heartbeat_stop.py tests/test_agent_version.py -q
# 子机：故意错 key → journalctl 一条 401 后无新心跳；修正 key + config reload 后恢复

回滚

恢复 agent.py 内联 401 分支；删除 heartbeat_policy.py