knowhere | 番外篇 02：本地调试与测试运行手册

番外定位番外篇 02 面向实际开发过程：当你要在本地修改 Knowhere、运行测试、定位失败、验证一个小改动时，应该从哪些命令开始，如何判断依赖环境是否满足，如何选择最小测试集，以及如何避免本地状态污染导致误判。这篇适合在第 12 课之后阅读，也可以作为日常开发前的检查清单。1. 本地调试目标本地调试不是一次性跑完整项目，而是完成三个目标：环境可用：依赖、PostgreSQL 测试二进制、扩展、Python package 正常。改动可验证：能运行最小相关测试。行为可解释：失败时能定位到 API、Worker、DB、Redis、对象存储或外部 mock 边界。不建议每次修改都直接跑全量测试。更合理的顺序是：环境检查 - 最小相关 contract test - make check - 必要时扩大测试范围2. 环境检查测试环境检查命令：uv run python apps/api/scripts/ensure_test_environment.py如果缺少 PostgreSQL server binaries 或 contrib extensions：