# turbovec - Doramagic AI Context Pack > 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。 ## 充分原则 - **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。 - **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。 ## 给宿主 AI 的使用方式 你正在读取 Doramagic 为 turbovec 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。 ## Claim 消费规则 - **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。 - **事实最低状态**：`supported` - `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。 - `weak`：只能作为低置信度线索，必须要求用户继续核实。 - `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。 - `unverified`：不得作为事实使用，应明确说证据不足。 - `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。 ## 它最适合谁 - **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0002` supported 0.86 ## 它能做什么 - **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86 ## 怎么开始 - `pip install turbovec` 证据：`README.md` Claim：`clm_0003` supported 0.86 - `pip install maturin` 证据：`README.md` Claim：`clm_0004` supported 0.86 - `pip install target/wheels/*.whl` 证据：`README.md` Claim：`clm_0005` supported 0.86 ## 继续前判断卡 - **当前建议**：仅建议沙盒试装 - **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。 ### 30 秒判断 - **现在怎么做**：仅建议沙盒试装 - **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装 - **先别相信**：真实输出质量不能在安装前相信。 - **继续会触碰**：命令执行、本地环境或项目文件、宿主 AI 上下文 ### 现在可以相信 - **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86 - **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86 - **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86 ### 现在还不能相信 - **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。 - **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。 - **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 - **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。 - **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 - **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。 - **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md` ### 继续会触碰什么 - **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md` - **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md` - **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。 ### 最小安全下一步 - **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。） - **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。） - **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。） ### 退出方式 - **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。 - **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。 - **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。 ## 哪些只能预览 - 解释项目适合谁和能做什么 - 基于项目文档演示典型对话流程 - 帮助用户判断是否值得安装或继续研究 ## 哪些必须安装后验证 - 真实安装 Skill、插件或 CLI - 执行脚本、修改本地文件或访问外部服务 - 验证真实输出质量、性能和兼容性 ## 边界与风险判断卡 - **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0006` inferred 0.45 - **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0007` supported 0.86 - **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。 - **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。 - **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。 ## 开工前工作上下文 ### 加载顺序 - 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。 - 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。 - 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。 - 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。 - 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。 ### 任务路由 - **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86 ### 上下文规模 - 文件总数：119 - 重要文件覆盖：40/119 - 证据索引条目：71 - 角色 / Skill 条目：9 ### 证据不足时的处理 - **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。 - **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。 - **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。 - **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。 ## Prompt Recipes ### 适配判断 - 目标：判断这个项目是否适合用户当前任务。 - 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。 ```text 请基于 turbovec 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。 ``` ### 安装前体验 - 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。 - 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。 ```text 请把 turbovec 当作安装前体验资产，而不是已安装工具或真实运行环境。 请严格输出四段： 1. 先问我 3 个必要问题。 2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。 3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。 4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。 硬性边界： - 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。 - 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。 - 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。 - 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。 - Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。 - 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。 ``` ### 角色 / Skill 选择 - 目标：从项目里的角色或 Skill 中挑选最匹配的资产。 - 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。 ```text 请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。 ``` ### 风险预检 - 目标：安装或引入前识别环境、权限、规则冲突和质量风险。 - 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。 ```text 请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。 ``` ### 宿主 AI 开工指令 - 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。 - 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。 ```text 请基于 turbovec 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。 ``` ## 角色 / Skill 索引 - 共索引 9 个角色 / Skill / 项目文档条目。 - **Python**（project_doc）：A 10 million document corpus takes 31 GB of RAM as float32. turbovec fits it in 4 GB - and searches it faster than FAISS. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md` - **Contributing**（project_doc）：Thanks for your interest in turbovec. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md` - **API Reference**（project_doc）：turbovec exposes two index types and one serialization format per type. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api.md` - **Agno integration**（project_doc）：turbovec.agno.TurboQuantVectorDb is an Agno https://github.com/agno-agi/agno VectorDb backed by an IdMapIndex . It implements the same public surface as agno.vectordb.lancedb.LanceDb the closest in-tree single-machine backend so this can be swapped in wherever LanceDb is used. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/integrations/agno.md` - **Haystack integration**（project_doc）：turbovec.haystack.TurboQuantDocumentStore is a Haystack 2.x DocumentStore https://docs.haystack.deepset.ai/docs/document-store backed by an IdMapIndex . It implements the same public surface as haystack.document stores.in memory.InMemoryDocumentStore and can be used as a drop-in replacement wherever the in-memory store is used. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/integrations/haystack.md` - **LangChain integration**（project_doc）：turbovec.langchain.TurboQuantVectorStore is a LangChain VectorStore https://python.langchain.com/docs/integrations/vectorstores/ backed by an IdMapIndex . It implements the same public surface as langchain core.vectorstores.in memory.InMemoryVectorStore and can be used as a drop-in replacement wherever the in-memory store is used. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/integrations/langchain.md` - **LlamaIndex integration**（project_doc）：turbovec.llama index.TurboQuantVectorStore is a LlamaIndex BasePydanticVectorStore https://docs.llamaindex.ai/en/stable/module guides/storing/vector stores/ backed by an IdMapIndex . It implements the same public surface as llama index.core.vector stores.simple.SimpleVectorStore and can be used as a drop-in replacement wherever the simple in-memory store is used. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/integrations/llama_index.md` - **Changelog**（project_doc）：All notable changes to turbovec are recorded here. The format is based on Keep a Changelog https://keepachangelog.com/en/1.1.0/ and the project follows Semantic Versioning https://semver.org/spec/v2.0.0.html . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md` - **Security Policy**（project_doc）：Thank you for helping keep turbovec and its users safe. Security reports are genuinely appreciated. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md` ## 证据索引 - 共索引 71 条证据。 - **Python**（documentation）：A 10 million document corpus takes 31 GB of RAM as float32. turbovec fits it in 4 GB - and searches it faster than FAISS. 证据：`README.md` - **Contributing**（documentation）：Thanks for your interest in turbovec. 证据：`CONTRIBUTING.md` - **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the "Software" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE` - **API Reference**（documentation）：turbovec exposes two index types and one serialization format per type. 证据：`docs/api.md` - **Agno integration**（documentation）：turbovec.agno.TurboQuantVectorDb is an Agno https://github.com/agno-agi/agno VectorDb backed by an IdMapIndex . It implements the same public surface as agno.vectordb.lancedb.LanceDb the closest in-tree single-machine backend so this can be swapped in wherever LanceDb is used. 证据：`docs/integrations/agno.md` - **Haystack integration**（documentation）：turbovec.haystack.TurboQuantDocumentStore is a Haystack 2.x DocumentStore https://docs.haystack.deepset.ai/docs/document-store backed by an IdMapIndex . It implements the same public surface as haystack.document stores.in memory.InMemoryDocumentStore and can be used as a drop-in replacement wherever the in-memory store is used. 证据：`docs/integrations/haystack.md` - **LangChain integration**（documentation）：turbovec.langchain.TurboQuantVectorStore is a LangChain VectorStore https://python.langchain.com/docs/integrations/vectorstores/ backed by an IdMapIndex . It implements the same public surface as langchain core.vectorstores.in memory.InMemoryVectorStore and can be used as a drop-in replacement wherever the in-memory store is used. 证据：`docs/integrations/langchain.md` - **LlamaIndex integration**（documentation）：turbovec.llama index.TurboQuantVectorStore is a LlamaIndex BasePydanticVectorStore https://docs.llamaindex.ai/en/stable/module guides/storing/vector stores/ backed by an IdMapIndex . It implements the same public surface as llama index.core.vector stores.simple.SimpleVectorStore and can be used as a drop-in replacement wherever the simple in-memory store is used. 证据：`docs/integrations/llama_index.md` - **Standalone smoke test crate that lives outside the workspace on purpose —**（source_file）：workspace members = "turbovec", "turbovec-python" Standalone smoke test crate that lives outside the workspace on purpose — it must mimic a real downstream cargo add turbovec user no inherited workspace settings, no shared lockfile . exclude = "examples/downstream-smoke" resolver = "2" 证据：`Cargo.toml` - **Cargo**（source_file）：package name = "turbovec-python" version = "0.8.0" edition = "2021" rust-version = "1.70" 证据：`turbovec-python/Cargo.toml` - **Build**（source_file）：fn main { 证据：`turbovec-python/build.rs` - **Pyproject**（source_file）：build-system requires = "maturin =1.12,<2.0" build-backend = "maturin" 证据：`turbovec-python/pyproject.toml` - **build.rs emits the BLAS link directive directly openblas on Linux,**（source_file）：package name = "turbovec" version = "0.9.0" edition = "2021" rust-version = "1.70" description = "Fast vector quantization with 2-4 bit compression and SIMD search" license = "MIT" repository = "https://github.com/RyanCodrai/turbovec" homepage = "https://github.com/RyanCodrai/turbovec" readme = "../README.md" keywords = "vector-search", "quantization", "nearest-neighbor", "ann", "simd" categories = "algorithms", "science", "compression" 证据：`turbovec/Cargo.toml` - **Build**（source_file）：fn main { match std::env::var "CARGO CFG TARGET OS" .as deref { Ok "linux" = println! "cargo:rustc-link-lib=openblas" , Ok "macos" = println! "cargo:rustc-link-lib=framework=Accelerate" , 证据：`turbovec/build.rs` - **Standalone crate NOT a workspace member that depends on turbovec via**（source_file）：package name = "downstream-smoke" version = "0.0.0" edition = "2021" publish = false 证据：`examples/downstream-smoke/Cargo.toml` - **Main**（source_file）：use turbovec::TurboQuantIndex; ⋮---- fn unit vectors n: usize, dim: usize, seed: u64 - Vec { ⋮---- let mut out = vec! 0.0f32; n dim ; for v in out.chunks mut dim { for x in v.iter mut { x = next ; ⋮---- let norm = v.iter .map x x x .sum:: .sqrt .max 1e-12 ; ⋮---- fn main { let db = unit vectors N DB, DIM, 1 ; let queries = unit vectors N QUERIES, DIM, 2 ; let mut index = TurboQuantIndex::new DIM, 4 .expect "construct" ; index.add &db ; index.prepare ; let results = index.search &queries, K ; assert eq! results.nq, N QUERIES ; assert eq! results.k, K ; ⋮---- let idxs = results.indices for query q ; assert eq! idxs.len , K ; ⋮---- assert! 0..N DB as i64 .contains &i , "out-of-range index {i}"… 证据：`examples/downstream-smoke/src/main.rs` - **Init**（source_file）：all = "IdMapIndex", "TurboQuantIndex" 证据：`turbovec-python/python/turbovec/__init__.py` - **Lazy: the underlying IdMapIndex is created by create , not**（source_file）：INDEX FILENAME = "index.tvim" STORE FILENAME = "docstore.json" DOCSTORE SCHEMA VERSION = 1 class TurboQuantVectorDb VectorDb ⋮---- Lazy: the underlying IdMapIndex is created by create , not in init . This matches LanceDb's exists contract: a freshly-constructed store doesn't "exist" until create is ⋮---- def issue handle self - int def create self - None async def async create self - None def drop self - None async def async drop self - None def exists self - bool async def async exists self - bool def delete self - bool def optimize self - None def get count self - int async def async get count self - int def name exists self, name: str - bool async def async name exists self, name: str -… 证据：`turbovec-python/python/turbovec/agno.py` - **Defer the removal until after the add succeeds so a**（source_file）：class TurboQuantDocumentStore ⋮---- def del self - None def shutdown self - None def issue handle self - int ⋮---- @property def storage self - Dict str, Document def count documents self - int ⋮---- docs = ⋮---- docs = self. reconstruct data for data in self. u64 to doc.values ⋮---- policy = DuplicatePolicy.FAIL to write: List Document = batch pos: Dict str, int = {} to remove: List str = written = len documents ⋮---- present = doc.id in self. str to u64 or doc.id in batch pos ⋮---- Defer the removal until after the add succeeds so a failed validation/add never destroys existing data issue 89 . ⋮---- Last write wins: replace the earlier queued document in place rather than appending a seco… 证据：`turbovec-python/python/turbovec/haystack.py` - **---- Max marginal relevance ---------------------------------------**（source_file）：INDEX FILENAME = "index.tvim" STORE FILENAME = "docstore.json" DOCSTORE SCHEMA VERSION = 1 class TurboQuantVectorStore VectorStore ⋮---- def issue handle self - int ⋮---- @property def embeddings self - Embeddings def select relevance score fn self - Callable float , float ⋮---- texts list = list texts ⋮---- metadatas = {} for in texts list ⋮---- ids = str uuid.uuid4 for in texts list ⋮---- vectors = np.asarray self. embedding.embed documents texts list , dtype=np.float32 ⋮---- vectors = np.asarray ⋮---- texts = doc.page content for doc in documents metadatas = doc.metadata for doc in documents ⋮---- ids = doc.id or str uuid.uuid4 for doc in documents ⋮---- result ids = ids keep = resolve d… 证据：`turbovec-python/python/turbovec/langchain.py` - **IdMapIndex itself supports lazy construction now — no per-store**（source_file）：INDEX EXT = ".tvim" STORE EXT = ".nodes.json" NAMESPACE SEP = " " DEFAULT PERSIST FNAME = "vector store.json" DEFAULT VECTOR STORE = "default" NODES SCHEMA VERSION = 2 NODES SCHEMA COMPAT = 1, 2 def split persist base persist path: str Path - Path ⋮---- p = Path persist path ⋮---- class TurboQuantVectorStore BasePydanticVectorStore ⋮---- """LlamaIndex VectorStore backed by a :class: IdMapIndex . Vectors are quantized to 2–4 bits per dimension. A side-car dictionary holds node text and metadata keyed by node id . Supports delete by ref doc id , removing every node with that ref and delete nodes by node id — both O 1 per node. """ stores text: bool = True is embedding query: bool = True flat… 证据：`turbovec-python/python/turbovec/llama_index.py` - **classmethod**（source_file）：use pyo3::types::PyType; fn not contiguous err kind: &str - PyErr { pyo3::exceptions::PyValueError::new err format! ⋮---- fn shape err e: numpy::ndarray::ShapeError - PyErr { pyo3::exceptions::PyRuntimeError::new err format! ⋮---- fn validate queries values: & f32 , dim: usize - PyResult { ⋮---- return Err pyo3::exceptions::PyValueError::new err format! ⋮---- Ok ⋮---- struct TurboQuantIndex { ⋮---- impl TurboQuantIndex { ⋮---- fn new dim: Option , bit width: usize - PyResult { ⋮---- .map err e pyo3::exceptions::PyValueError::new err e.to string ?; Ok Self { inner } ⋮---- fn add &mut self, vectors: PyReadonlyArray2 - PyResult { let arr = vectors.as array ; let dim = arr.ncols ; let slice = a… 证据：`turbovec-python/src/lib.rs` - **Dump State**（source_file）：use std::env; ⋮---- use turbovec::codebook::codebook; use turbovec::rotation::make rotation matrix; fn write f32s w: &mut W, vals: & f32 - std::io::Result { ⋮---- w.write all &v.to le bytes ?; ⋮---- Ok ⋮---- fn main { let args: Vec = env::args .collect ; if args.len " ; ⋮---- create dir all out dir .unwrap ; ⋮---- eprintln! "Dumping d={} bits={}", dim, bits ; let rotation = make rotation matrix dim ; let boundaries, centroids = codebook bits, dim ; assert eq! rotation.len , dim dim ; assert eq! boundaries.len , 1 {}", path ; 证据：`turbovec/examples/dump_state.rs` - **Kernel Xtest**（source_file）：use std::env; use std::io::Write; use turbovec::TurboQuantIndex; ⋮---- fn main { let args: Vec = env::args .collect ; let dim: usize = args.get 1 .map s s.parse .unwrap .unwrap or 1536 ; let bits: usize = args.get 2 .map s s.parse .unwrap .unwrap or 4 ; let seed: u64 = args.get 3 .map s s.parse .unwrap .unwrap or 42 ; let arch = if cfg! target arch = "x86 64" { ⋮---- } else if cfg! target arch = "aarch64" { ⋮---- eprintln! " arch={arch} dim={dim} bits={bits} seed={seed} n db={N DB} n queries={N QUERIES} k={K}" ; let mut state = splitmix64 init seed ; let mut db = vec! 0.0f32; N DB dim ; let mut queries = vec! 0.0f32; N QUERIES dim ; ⋮---- v = next normal &mut state ; ⋮---- normalize rows &m… 证据：`turbovec/examples/kernel_xtest.rs` - **Io**（source_file）：use std::fs::File; ⋮---- use std::path::Path; ⋮---- type CoreLoad = usize, usize, usize, Vec , Vec , Vec , Vec ; pub fn write ⋮---- f.write all TV MAGIC ?; f.write all & TV VERSION ?; write core ⋮---- f.flush ?; Ok ⋮---- pub fn load path: impl AsRef - io::Result { ⋮---- f.read exact &mut magic ?; ⋮---- if 2..=4 .contains &magic 0 { return Err io::Error::new ⋮---- format! ⋮---- f.read exact &mut version ?; read core versioned &mut f, version 0 , TV VERSION, ".tv" ⋮---- pub fn write id map ⋮---- assert eq! ⋮---- f.write all TVIM MAGIC ?; f.write all & TVIM VERSION ?; ⋮---- f.write all &id.to le bytes ?; ⋮---- pub fn load id map ⋮---- read core versioned &mut f, version 0 , TVIM VERSION, ".tvi… 证据：`turbovec/src/io.rs` - **Lib**（source_file）：compile error! "turbovec requires a 64-bit target target pointer width = \"64\" " ; pub mod codebook; pub mod encode; pub mod error; pub mod id map; pub mod io; pub mod pack; pub mod rotation; pub mod search; ⋮---- pub use id map::IdMapIndex; use std::path::Path; use std::sync::OnceLock; ⋮---- pub fn first invalid coord values: & f32 , dim: usize - Option { for i, x in values.iter .enumerate { if !x.is finite x.abs = MAX INPUT MAGNITUDE { ⋮---- return Some vector index, coord index, x ; ⋮---- struct BlockedCache { ⋮---- pub struct TurboQuantIndex { ⋮---- pub struct SearchResults { ⋮---- impl SearchResults { pub fn scores for query &self, qi: usize - & f32 { ⋮---- pub fn indices for query &s… 证据：`turbovec/src/lib.rs` - **Pack**（source_file）：use crate::BLOCK; pub fn repack ⋮---- let mut codes flat = vec! vec! 0u8; n byte groups ; n vectors ; ⋮---- let blocked = pack blocked n vectors, n blocks, n byte groups, blocked size, &codes flat, &perm0 ; ⋮---- fn pack blocked ⋮---- let mut blocked = vec! 0u8; blocked size ; ⋮---- pub crate fn deinterleave x86 code byte blocked: & u8 , group off: usize, lane: usize - u8 { ⋮---- mod tests { ⋮---- fn deinterleave x86 recovers sequential code bytes { ⋮---- let mut codes flat = vec! vec! 0u8; n byte groups ; BLOCK ; ⋮---- s = s.wrapping mul 1 664 525 .wrapping add 1 013 904 223 ; ⋮---- let mut blocked = vec! 0u8; n byte groups BLOCK ; ⋮---- assert eq! 证据：`turbovec/src/pack.rs` - **Search**（source_file）：pub fn blocks skipped by mask - u64 { BLOCKS SKIPPED BY MASK.load Ordering::Relaxed ⋮---- pub fn reset blocks skipped by mask { BLOCKS SKIPPED BY MASK.store 0, Ordering::Relaxed ; ⋮---- unsafe fn score 4bit block neon ⋮---- let mask = vdupq n u8 0x0F ; let v scale = vdupq n f32 scale ; ⋮---- let mut fa = vdupq n f32 bias ; 8 ; let codes base = blocked codes.as ptr .add block offset ; let luts base = uint8 luts.as ptr ; ⋮---- let g end = g start + FLUSH EVERY .min n byte groups ; let mut accum = vdupq n u16 0 ; 4 ; ⋮---- let lp0 = luts base.add g 32 ; let lp1 = luts base.add g + 1 32 ; let lp2 = luts base.add g + 2 32 ; let lp3 = luts base.add g + 3 32 ; let cp0 = codes base.add g BLOCK ; le… 证据：`turbovec/src/search.rs` - **Changelog**（documentation）：All notable changes to turbovec are recorded here. The format is based on Keep a Changelog https://keepachangelog.com/en/1.1.0/ and the project follows Semantic Versioning https://semver.org/spec/v2.0.0.html . 证据：`CHANGELOG.md` - **Security Policy**（documentation）：Thank you for helping keep turbovec and its users safe. Security reports are genuinely appreciated. 证据：`SECURITY.md` - **None also short-circuits defensive against upstream un-init .**（source_file）：DIM = 64 class StubEmbedder ⋮---- enable batch = False def init self, dim: int = DIM - None def embed self, text: str - list float ⋮---- rng = np.random.default rng abs hash text % 2 32 v = rng.standard normal self.dimensions .astype np.float32 ⋮---- def get embedding self, text: str - list float async def async get embedding self, text: str - list float ⋮---- embedder = StubEmbedder DIM ⋮---- class BatchEmbedder StubEmbedder ⋮---- enable batch = True ⋮---- def get embeddings batch and usage self, texts async def async get embeddings batch and usage self, texts ⋮---- class ReverseReranker AgnoReranker ⋮---- calls: int = 0 def rerank self, query: str, documents def test search results carry… 证据：`turbovec-python/tests/test_agno.py` - **Test Haystack**（source_file）：DIM = 128 def unit vector seed: int - list float ⋮---- rng = np.random.default rng seed v = rng.standard normal DIM .astype np.float32 ⋮---- def make docs n: int, seed offset: int = 0 - list Document def test count documents starts at zero ⋮---- store = TurboQuantDocumentStore dim=DIM, bit width=4 ⋮---- def test blob field round trips through filter and retrieval ⋮---- payload = b"binary-payload-bytes" blob = ByteStream data=payload, meta={"origin": "test"}, mime type="application/octet-stream" doc = Document ⋮---- def test sparse embedding field round trips through filter and retrieval ⋮---- sparse = SparseEmbedding indices= 0, 7, 42 , values= 0.1, 0.5, 0.9 ⋮---- def test blob and sparse e… 证据：`turbovec-python/tests/test_haystack.py` - **Test Langchain**（source_file）：class StubEmbeddings Embeddings ⋮---- def init self, dim: int = 64 - None def embed self, text: str - list float ⋮---- rng = np.random.default rng abs hash text % 2 32 v = rng.standard normal self.dim .astype np.float32 ⋮---- def embed documents self, texts def embed query self, text def test from texts infers dim and indexes ⋮---- emb = StubEmbeddings dim=64 store = TurboQuantVectorStore.from texts ⋮---- def test similarity search returns documents ⋮---- store = TurboQuantVectorStore.from texts "a", "b", "c" , emb, bit width=4 results = store.similarity search "a", k=2 ⋮---- def test similarity search results carry document id ⋮---- results = store.similarity search "a", k=3 ⋮---- scored =… 证据：`turbovec-python/tests/test_langchain.py` - **Mimic StorageContext.persist's filename layout.**（source_file）：def unit vec seed: int, dim: int - list float ⋮---- rng = np.random.default rng seed v = rng.standard normal dim .astype np.float32 ⋮---- node = TextNode text=text, metadata=metadata or {}, embedding= unit vec seed, dim ⋮---- def test from params creates index ⋮---- store = TurboQuantVectorStore.from params dim=64, bit width=4 ⋮---- def test constructor no index is lazy ⋮---- store = TurboQuantVectorStore ⋮---- result = store.query ⋮---- def test lazy dim locked on first add ⋮---- store = TurboQuantVectorStore bit width=2 ⋮---- def test from params without dim is lazy ⋮---- store = TurboQuantVectorStore.from params bit width=4 ⋮---- def test persist and load lazy uncommitted store tmp path… 证据：`turbovec-python/tests/test_llama_index.py` - **Concurrent Search**（source_file）：use std::sync::Arc; use std::thread; ⋮---- fn make vectors n: usize, dim: usize, seed: u64 - Vec { let mut state = seed.wrapping mul 0x9E3779B97F4A7C15 ; ⋮---- .wrapping mul 6364136223846793005 .wrapping add 1442695040888963407 ; ⋮---- out.push u 2.0 - 1.0 ; ⋮---- fn build index - TurboQuantIndex { ⋮---- let vectors = make vectors n, dim, 1 ; let mut index = TurboQuantIndex::new dim, bit width .unwrap ; index.add &vectors ; assert eq! index.len , n ; ⋮---- fn search is deterministic across threads { let index = Arc::new build index ; index.prepare ; let queries = make vectors 4, index.dim , 42 ; ⋮---- let reference = index.search &queries, k ; ⋮---- .map qi reference.indices for query qi .t… 证据：`turbovec/tests/concurrent_search.rs` - **Settings**（structured_config）：{ "worktree": { "bgIsolation": "none" } } 证据：`.claude/settings.json` - **Compression**（structured_config）：{ "glove d200 2bit": { "n": 100000, "dim": 200, "bit width": 2, "fp32 mb": 76.3, "index mb": 5.1, "ratio": 14.8 }, "glove d200 4bit": { "n": 100000, "dim": 200, "bit width": 4, "fp32 mb": 76.3, "index mb": 9.9, "ratio": 7.7 }, "openai d1536 2bit": { "n": 100000, "dim": 1536, "bit width": 2, "fp32 mb": 585.9, "index mb": 37.0, "ratio": 15.8 }, "openai d1536 4bit": { "n": 100000, "dim": 1536, "bit width": 4, "fp32 mb": 585.9, "index mb": 73.6, "ratio": 8.0 }, "openai d3072 2bit": { "n": 100000, "dim": 3072, "bit width": 2, "fp32 mb": 1171.9, "index mb": 73.6, "ratio": 15.9 }, "openai d3072 4bit": { "n": 100000, "dim": 3072, "bit width": 4, "fp32 mb": 1171.9, "index mb": 146.9, "ratio": 8.0 } } 证据：`benchmarks/results/compression.json` - **Recall D1536 2Bit**（structured_config）：{ "dataset": "openai-1536", "dim": 1536, "bit width": 2, "faiss variant": "IndexPQ m=384, nbits=8 ", "seed": 42, "tq recalls": { "1": 0.891, "2": 0.979, "4": 0.998, "8": 1.0, "16": 1.0, "32": 1.0, "64": 1.0 }, "faiss recalls": { "1": 0.872, "2": 0.977, "4": 0.997, "8": 1.0, "16": 1.0, "32": 1.0, "64": 1.0 } } 证据：`benchmarks/results/recall_d1536_2bit.json` - **Recall D1536 4Bit**（structured_config）：{ "dataset": "openai-1536", "dim": 1536, "bit width": 4, "faiss variant": "IndexPQ m=768, nbits=8 ", "seed": 42, "tq recalls": { "1": 0.974, "2": 0.998, "4": 1.0, "8": 1.0, "16": 1.0, "32": 1.0, "64": 1.0 }, "faiss recalls": { "1": 0.966, "2": 0.998, "4": 1.0, "8": 1.0, "16": 1.0, "32": 1.0, "64": 1.0 } } 证据：`benchmarks/results/recall_d1536_4bit.json` - **Recall D3072 2Bit**（structured_config）：{ "dataset": "openai-3072", "dim": 3072, "bit width": 2, "faiss variant": "IndexPQ m=768, nbits=8 ", "seed": 42, "tq recalls": { "1": 0.929, "2": 0.988, "4": 0.999, "8": 1.0, "16": 1.0, "32": 1.0, "64": 1.0 }, "faiss recalls": { "1": 0.912, "2": 0.986, "4": 1.0, "8": 1.0, "16": 1.0, "32": 1.0, "64": 1.0 } } 证据：`benchmarks/results/recall_d3072_2bit.json` - **Recall D3072 4Bit**（structured_config）：{ "dataset": "openai-3072", "dim": 3072, "bit width": 4, "faiss variant": "IndexPQ m=1536, nbits=8 ", "seed": 42, "tq recalls": { "1": 0.974, "2": 0.999, "4": 1.0, "8": 1.0, "16": 1.0, "32": 1.0, "64": 1.0 }, "faiss recalls": { "1": 0.972, "2": 0.998, "4": 1.0, "8": 1.0, "16": 1.0, "32": 1.0, "64": 1.0 } } 证据：`benchmarks/results/recall_d3072_4bit.json` - **Recall Glove 2Bit**（structured_config）：{ "dataset": "glove", "dim": 200, "bit width": 2, "faiss variant": "IndexPQ m=50, nbits=8 ", "seed": 42, "tq recalls": { "1": 0.5637, "2": 0.7209, "4": 0.8443, "8": 0.9236, "16": 0.9676, "32": 0.9892, "64": 0.9966 }, "faiss recalls": { "1": 0.5643, "2": 0.7188, "4": 0.8446, "8": 0.9252, "16": 0.97, "32": 0.9908, "64": 0.9981 } } 证据：`benchmarks/results/recall_glove_2bit.json` - **Recall Glove 4Bit**（structured_config）：{ "dataset": "glove", "dim": 200, "bit width": 4, "faiss variant": "IndexPQ m=100, nbits=8 ", "seed": 42, "tq recalls": { "1": 0.8498, "2": 0.9584, "4": 0.9936, "8": 0.9998, "16": 1.0, "32": 1.0, "64": 1.0 }, "faiss recalls": { "1": 0.841, "2": 0.9515, "4": 0.9914, "8": 0.9986, "16": 1.0, "32": 1.0, "64": 1.0 } } 证据：`benchmarks/results/recall_glove_4bit.json` - **Speed D1536 2Bit Arm Mt**（structured_config）：{ "dim": 1536, "bit width": 2, "arch": "arm", "threading": "mt", "tq ms per query": 0.103, "faiss ms per query": 0.115 } 证据：`benchmarks/results/speed_d1536_2bit_arm_mt.json` - **Speed D1536 2Bit Arm St**（structured_config）：{ "dim": 1536, "bit width": 2, "arch": "arm", "threading": "st", "tq ms per query": 1.083, "faiss ms per query": 1.235 } 证据：`benchmarks/results/speed_d1536_2bit_arm_st.json` - **Speed D1536 2Bit X86 Mt**（structured_config）：{ "dim": 1536, "bit width": 2, "arch": "x86", "threading": "mt", "tq ms per query": 0.304, "faiss ms per query": 0.295 } 证据：`benchmarks/results/speed_d1536_2bit_x86_mt.json` - **Speed D1536 2Bit X86 St**（structured_config）：{ "dim": 1536, "bit width": 2, "arch": "x86", "threading": "st", "tq ms per query": 1.271, "faiss ms per query": 1.172 } 证据：`benchmarks/results/speed_d1536_2bit_x86_st.json` - **Speed D1536 4Bit Arm Mt**（structured_config）：{ "dim": 1536, "bit width": 4, "arch": "arm", "threading": "mt", "tq ms per query": 0.185, "faiss ms per query": 0.22 } 证据：`benchmarks/results/speed_d1536_4bit_arm_mt.json` - **Speed D1536 4Bit Arm St**（structured_config）：{ "dim": 1536, "bit width": 4, "arch": "arm", "threading": "st", "tq ms per query": 1.992, "faiss ms per query": 2.45 } 证据：`benchmarks/results/speed_d1536_4bit_arm_st.json` - **Speed D1536 4Bit X86 Mt**（structured_config）：{ "dim": 1536, "bit width": 4, "arch": "x86", "threading": "mt", "tq ms per query": 0.576, "faiss ms per query": 0.59 } 证据：`benchmarks/results/speed_d1536_4bit_x86_mt.json` - **Speed D1536 4Bit X86 St**（structured_config）：{ "dim": 1536, "bit width": 4, "arch": "x86", "threading": "st", "tq ms per query": 2.439, "faiss ms per query": 2.56 } 证据：`benchmarks/results/speed_d1536_4bit_x86_st.json` - **Speed D3072 2Bit Arm Mt**（structured_config）：{ "dim": 3072, "bit width": 2, "arch": "arm", "threading": "mt", "tq ms per query": 0.201, "faiss ms per query": 0.224 } 证据：`benchmarks/results/speed_d3072_2bit_arm_mt.json` - **Speed D3072 2Bit Arm St**（structured_config）：{ "dim": 3072, "bit width": 2, "arch": "arm", "threading": "st", "tq ms per query": 2.124, "faiss ms per query": 2.439 } 证据：`benchmarks/results/speed_d3072_2bit_arm_st.json` - **Speed D3072 2Bit X86 Mt**（structured_config）：{ "dim": 3072, "bit width": 2, "arch": "x86", "threading": "mt", "tq ms per query": 0.626, "faiss ms per query": 0.59 } 证据：`benchmarks/results/speed_d3072_2bit_x86_mt.json` - **Speed D3072 2Bit X86 St**（structured_config）：{ "dim": 3072, "bit width": 2, "arch": "x86", "threading": "st", "tq ms per query": 2.657, "faiss ms per query": 2.582 } 证据：`benchmarks/results/speed_d3072_2bit_x86_st.json` - **Speed D3072 4Bit Arm Mt**（structured_config）：{ "dim": 3072, "bit width": 4, "arch": "arm", "threading": "mt", "tq ms per query": 0.375, "faiss ms per query": 0.448 } 证据：`benchmarks/results/speed_d3072_4bit_arm_mt.json` - **Speed D3072 4Bit Arm St**（structured_config）：{ "dim": 3072, "bit width": 4, "arch": "arm", "threading": "st", "tq ms per query": 3.968, "faiss ms per query": 4.925 } 证据：`benchmarks/results/speed_d3072_4bit_arm_st.json` - **Speed D3072 4Bit X86 Mt**（structured_config）：{ "dim": 3072, "bit width": 4, "arch": "x86", "threading": "mt", "tq ms per query": 1.177, "faiss ms per query": 1.177 } 证据：`benchmarks/results/speed_d3072_4bit_x86_mt.json` - **Speed D3072 4Bit X86 St**（structured_config）：{ "dim": 3072, "bit width": 4, "arch": "x86", "threading": "st", "tq ms per query": 5.342, "faiss ms per query": 5.474 } 证据：`benchmarks/results/speed_d3072_4bit_x86_st.json` - **Target the x86-64-v3 microarchitecture level on all x86 64 builds.**（source_file）：Target the x86-64-v3 microarchitecture level on all x86 64 builds. x86-64-v3 corresponds to the generic Haswell/Excavator feature set AVX, AVX2, BMI1, BMI2, FMA, F16C, LZCNT, MOVBE, OSXSAVE which has been ubiquitous since 2013 and is the minimum floor for running turbovec's AVX2 SIMD kernel anyway. Setting it here lets LLVM emit AVX2/FMA instructions in the surrounding non-intrinsic Rust code rotation loops, LUT build, heap update which measurably improves the non-hot-kernel paths. We do NOT set x86-64-v4 AVX-512 here because the AVX-512 kernel is already runtime-dispatched via is x86 feature detected! , and raising the baseline to v4 would make the whole crate SIGILL on CPUs without AVX-51… 证据：`.cargo/config.toml` - 其余 11 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。 ## 宿主 AI 必须遵守的规则 - **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `CONTRIBUTING.md`, `LICENSE` - **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `CONTRIBUTING.md`, `LICENSE` ## 用户开工前应该回答的问题 - 你准备在哪个宿主 AI 或本地环境中使用它？ - 你只是想先体验工作流，还是准备真实安装？ - 你最在意的是安装成本、输出质量、还是和现有规则的冲突？ ## 验收标准 - 所有能力声明都能回指到 evidence_refs 中的文件路径。 - AI_CONTEXT_PACK.md 没有把预览包装成真实运行。 - 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。 --- ## Doramagic Context Augmentation 下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。 ## Human Manual 骨架 使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。 宿主 AI 硬性规则： - 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。 - 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。 - 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。 - **turbovec Overview & TurboQuant Algorithm**：importance `high` - source_paths: README.md, turbovec-python/README.md, CHANGELOG.md - **Core Rust Crate: Index Types, Encoding, and File Formats**：importance `high` - source_paths: turbovec/src/lib.rs, turbovec/src/codebook.rs, turbovec/src/encode.rs, turbovec/src/pack.rs, turbovec/src/search.rs - **Python Bindings & Framework Integrations**：importance `high` - source_paths: turbovec-python/pyproject.toml, turbovec-python/Cargo.toml, turbovec-python/build.rs, turbovec-python/src/lib.rs, turbovec-python/python/turbovec/__init__.py - **Performance, Building, Deployment & Operations**：importance `medium` - source_paths: README.md, Cargo.toml, .cargo/config.toml, turbovec/build.rs, turbovec/examples/dump_state.rs ## Repo Inspection Evidence / 源码检查证据 - repo_clone_verified: true - repo_inspection_verified: true - repo_commit: `1e7200cfd8f26c92ce2855652db64bc7f85bc039` - inspected_files: `README.md`, `docs/api.md`, `docs/integrations/agno.md`, `docs/integrations/haystack.md`, `docs/integrations/langchain.md`, `docs/integrations/llama_index.md`, `examples/downstream-smoke/Cargo.toml` 宿主 AI 硬性规则： - 没有 repo_clone_verified=true 时，不得声称已经读过源码。 - 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。 - 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。 ## Doramagic Pitfall Constraints / 踩坑约束 这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。 ### Constraint 1: 来源证据：Proposal: official Node.js binding (turbovec-node) - Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: official Node.js binding (turbovec-node) - Why it matters: 可能增加新用户试用和生产接入成本。 - Evidence: community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/85 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 2: 来源证据：TurboVec on Snowpark Container Services (SPCS) - Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：TurboVec on Snowpark Container Services (SPCS) - Why it matters: 可能增加新用户试用和生产接入成本。 - Evidence: community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/95 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 3: 来源证据：Add insertion + removal speed benchmarks to benchmarks/suite/ - Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add insertion + removal speed benchmarks to benchmarks/suite/ - Why it matters: 可能影响授权、密钥配置或安全边界。 - Evidence: community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/65 | 来源类型 github_issue 暴露的待验证使用条件。 - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 4: 来源证据：Public Read/Write I/O API + pub TurboQuantIndex::from_parts - Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Public Read/Write I/O API + pub TurboQuantIndex::from_parts - Why it matters: 可能阻塞安装或首次运行。 - Evidence: community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/70 | 来源类型 github_issue 暴露的待验证使用条件。 - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 5: 来源证据：Proposal: Swift / macOS binding (turbovec-swift) - Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: Swift / macOS binding (turbovec-swift) - Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Why it matters: 可能增加新用户试用和生产接入成本。 - Evidence: community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/86 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 6: 来源证据：TQ+ calibration: silent identity-freeze on small first add; fit from a cumulative warm-up sample - Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：TQ+ calibration: silent identity-freeze on small first add; fit from a cumulative warm-up sample - Why it matters: 可能增加新用户试用和生产接入成本。 - Evidence: community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/107 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 7: 来源证据：x86_64 scalar fallback (no AVX2 at runtime) returns incorrect results: reads perm0-interleaved layout as if sequential - Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：x86_64 scalar fallback (no AVX2 at runtime) returns incorrect results: reads perm0-interleaved layout as if sequential - Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Why it matters: 可能阻塞安装或首次运行。 - Evidence: community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/106 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 8: 来源证据：✨ Node.js / TypeScript bindings (turbovec-node) - Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：✨ Node.js / TypeScript bindings (turbovec-node) - Why it matters: 可能增加新用户试用和生产接入成本。 - Evidence: community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/111 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 9: 能力判断依赖假设 - Trigger: README/documentation is current enough for a first validation pass. - Host AI rule: 将假设转成下游验证清单。 - Why it matters: 假设不成立时，用户拿不到承诺的能力。 - Evidence: capability.assumptions | https://github.com/RyanCodrai/turbovec | README/documentation is current enough for a first validation pass. - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 10: 来源证据：bug: agno insert() orphans vectors on intra-batch duplicate derived doc_ids - Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug: agno insert() orphans vectors on intra-batch duplicate derived doc_ids - Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Why it matters: 可能增加新用户试用和生产接入成本。 - Evidence: community_evidence:github | https://github.com/RyanCodrai/turbovec/issues/104 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。