turbovec 是一个操作型技能包，用于协助在项目中集成 RyanCodrai/turbovec 的 TurboQuant 向量索引。其内容以使用指引和预检脚本为主，而非独立产品服务。
用途：帮助开发者在使用 turbovec 前检查源码检出状态、核对选定的固定文件哈希，并了解该库的 API 表面与适用范围，从而降低误用风险。
主要能力：
- 预检。在 jeo-skills 仓库根目录运行 python3 .agent-skills/turbovec/scripts/preflight.py --repo /absolute/upstream --json；已安装副本使用其自带 scripts/preflight.py。不提供 --repo 时仅做清单统计。该辅助脚本检查部分固定文件哈希，不检查 Git HEAD、完整源码树、依赖安装或实际执行。
- API 表面选择。Python 从 turbovec 导入 TurboQuantIndex 或 IdMapIndex；Rust 使用 turbovec crate。该库为进程内向量索引，对压缩向量做线性扫描，不提供服务器、复制、租户隔离或分布式索引。
- 数据与质量确认。需先确认向量维度、Python 的行主序 float32 输入、位宽（2 或 4）、评分语义（内积；余弦需归一化）、召回目标以及是否需要稳定 ID，并在有代表性的本地数据上比较量化前后的召回效果。
- 副作用审批。在安装包或工具链、下载模型或向量数据集、读取或嵌入私有源数据、使用付费或远程嵌入、写入/同步/加载索引文件、重建或删除索引、围绕其启动 API 或服务之前，应先获得批准。文件中提示不要把文件路径和凭证写入公开日志。sync(path) 会持久化数据，后续调用会更新。
- 固定 API 检查与往返验证。获得批准后，检查检出代码中的 Python/Rust API 文档与包帮助，先用小样本验证搜索结果和持久化/加载，再在目标机器上测量内存、召回和延迟。资料明确提示：不要从内存库的快速验证推断其具备生产服务就绪性。
使用方式示例（资料原文）：
Offline provenance check; absolute, non-symlink source checkout.
python3 .agent-skills/turbovec/scripts/preflight.py --repo /work/turbovec --json
仅在安装、数据、文件写入获得批准后： pip install turbovec python - <<'PY' import numpy as np from turbovec import TurboQuantIndex x = np.load("vectors.npy").astype(np.float32) index = TurboQuantIndex(dim=x.shape[1], bit_width=4) index.add(x) scores, slots = index.search(x[:1], k=5) index.sync("index.tv") PY
最佳实践：若结果需要在槽位变化或删除后保持稳定，使用 IdMapIndex 的稳定 uint64 ID；普通 TurboQuantIndex 返回槽位位置。项目仅记录 64 位目标，维度为 8 的倍数、最大 16,384，位宽为 2/4。量化有损，低维数据召回可能下降更多。搜索成本随语料规模增长，因为库会扫描向量；超大规模语料或网络客户端场景应选择 ANN/服务器架构，不要把 turbovec 当作此类方案。上游性能数据需结合其硬件、数据集和评测方法，本地重新验证，不应发布普适倍数。辅助检查后应报告 runtime_verified: false，因为预检不安装原生 wheel、不运行内核、不测试召回、不验证持久化。
适用场景：本地小规模向量检索原型、Python/Rust 进程内嵌入搜索、量化召回与内存/延迟的本地评估。
限制：有损量化；线性扫描导致规模化受限；无服务器、复制、多租户或分布式能力；预检脚本支持 POSIX Linux/macOS/WSL2 上的 Python 3.10+，在无法安全遍历目录时失败关闭，不支持原生 Windows；预检不覆盖完整源码与依赖，也不验证运行期行为。