Nexus/docs/changelog/2026-06-04-bug-batch5-agent-etag.md

Changelog — BUG Batch 5：心跳 TTL / 远程写 ETag（2026-06-04）

摘要

将 Agent 心跳 Redis TTL 调整为 flush 间隔的 1.5 倍，并补全远程写/chmod/压缩/解压后的 browse ETag 失效。

动机

• 注释要求 TTL 大于 10min flush，但 REDIS_KEY_EXPIRE 与 FLUSH_INTERVAL 同为 600s，停 Agent 后 key 可能先过期。
• Batch 4 仅覆盖 file-ops/upload/clipboard，写文件与 chmod 等仍会导致目录列表 304 陈旧。

变更

文件	说明
server/api/agent.py	REDIS_KEY_EXPIRE = int(FLUSH_INTERVAL * 1.5)
server/background/heartbeat_flush.py	移除重复 TTL 常量，注释指向 agent
server/application/services/files_browse_service.py	invalidate_browse_parents()
server/api/sync_v2.py	write/chmod/compress/decompress 后失效父目录缓存
server/background/self_monitor.py	debug 日志增加 ws_sync_clients
tests/test_agent_heartbeat_ttl.py	TTL > flush 断言
tests/test_files_browse_etag.py	invalidate_browse_parents 单测

迁移 / 重启

• 需重启 nexus。
• 无 DB 迁移；已有 Redis key 在下次心跳时刷新 TTL。

验证

ruff check server/api/agent.py server/api/sync_v2.py
pytest tests/test_agent_heartbeat_ttl.py tests/test_files_browse_etag.py tests/ -q

关联

• Batch 4：docs/changelog/2026-06-04-bug-batch4-push-etag-heartbeat.md