BUG 专项逐行走读 — Batch 5（2026-06-04）

标准: docs/project/line-walk-audit-standard.md · 八类仅列 BUG

范围（5 文件，全文 Read）

文件	N	Read
`server/api/agent.py`	360	Redis TTL + heartbeat
`server/background/heartbeat_flush.py`	102	flush 循环
`server/api/sync_v2.py`	write/chmod/compress/decompress	1374–1665
`server/background/self_monitor.py`	108	1–108
`server/application/services/files_browse_service.py`	invalidate 辅助	65–85

Step 3 规则扫描（BUG 相关）

文件	命中
agent.py	`REDIS_KEY_EXPIRE` vs `FLUSH_INTERVAL`
heartbeat_flush.py	与 agent TTL 常量重复/不一致
sync_v2.py	写/chmod/压缩/解压后 ETag
self_monitor.py	仅监控 alert WS
files_browse_service.py	父目录批量失效

Closure 表（BUG）

文件	行号	判定	严重度	理由
agent.py	34, 226-227	FINDING	P2	注释写 TTL=1.5×flush，实际 600=600，停 Agent 后 key 可能在 flush 前过期
sync_v2.py	1474-1650	FINDING	P2	write/chmod/compress/decompress 未失效 browse ETag（Batch4 已覆盖 ops/upload）
heartbeat_flush.py	18-20	SAFE	—	常量与 agent 对齐后由 agent 单一来源
self_monitor.py	102-107	RISK	P3	原仅记录 alert WS；已补 sync WS 计数到 debug 日志
files_browse_service.py	65+	SAFE	—	新增 `invalidate_browse_parents`

FINDING 列表

BUG-06-04-11 · P2 · agent.py REDIS_KEY_EXPIRE

现象：REDIS_KEY_EXPIRE=600 与 FLUSH_INTERVAL=600 相同，末次心跳可能在 10min flush 前从 Redis 消失，MySQL 历史落后。

修复：REDIS_KEY_EXPIRE = int(FLUSH_INTERVAL * 1.5) → 900s。

BUG-06-04-12 · P2 · sync_v2 远程写路径

现象：/write-file、/chmod、/compress、/decompress 成功后 browse 304 仍可能返回旧目录。

修复：invalidate_browse_parents(server_id, *paths)。

Step 7 统计

agent.py                  1 FINDING（已修）
sync_v2.py                1 FINDING（已修）
heartbeat_flush.py        0
self_monitor.py           0（P3 观测增强）
files_browse_service.py   0（辅助函数）

Step 8 DoD

5 文件覆盖
Closure 全表
2 项 P2 已修 + pytest

验证

ruff check server/api/agent.py server/api/sync_v2.py server/background/self_monitor.py
pytest tests/test_agent_heartbeat_ttl.py tests/test_files_browse_etag.py tests/ -q --tb=no

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

下一批（BUG）

server/api/auth_jwt.py / refresh 重用检测边界
server/background/script_execution_flush.py
前端 FilesPage 与 ETag/If-None-Match 联调

2.8 KiB Raw Blame History Unescape Escape