cold_display_guard/tasks/lessons.md

Lessons

• 2026-06-10: 远端接收端路由不能只凭已有相似服务或历史路径推断，必须先对用户指定的精确路径做真实 HTTP 探测，再决定配置值。 Prevention:

  1. 对每个用户指定的 Webhook 路径，先在目标主机上用与真实请求接近的 POST 探测并记录状态码。
  2. 如果存在多个相似路径，只能在验证过用户指定路径不可用后，才考虑回退到其它路径。
  3. 切换远端配置前，先确认发送端容器对目标主机名或 IP 实际可达，避免写入不可解析的地址。

• 2026-06-15: 告警截图叠加中文区域名时，不能依赖默认西文字体或手写点阵字形；这会在现场截图里表现为乱码或不可读文字。 Prevention:

  1. 涉及中文截图叠字时，镜像必须安装可验证的 CJK 字体包，并在容器内用 fc-match :lang=zh-cn 确认命中 CJK 字体。
  2. 部署后必须在目标容器内跑一次中文标签叠图烟测，确认真实渲染路径可用，而不只检查像素变化。
  3. 字体渲染不可用时，回退文本必须转换成可读 ASCII 标识，例如 区域 1 -> R1、垃圾区 -> TRASH，避免继续绘制乱码中文。

• 2026-06-15: 现场识别抖动排查时，不能先假设某个区域为空；用户指出区域 1、2、6 实际都有物后，原先单纯调高相对暗区阈值会压掉真实占用。 Prevention:

  1. 调整视觉阈值前，必须向现场实际状态对齐，明确每个被分析区域当前应该是有物还是空。
  2. 如果物品已存在于启动基线中，不能只依赖相对基线变化；需要绝对特征或重新采空基线来识别。
  3. 对“正常取用”误报，应优先检查有物状态是否短暂掉空，并用判空确认帧数或滞后来处理抖动，而不是只提高占用阈值。