汇总 4 个影响新用户体验的可用性问题，可以分 PR 解决，也可以一个 PR 全处理。
问题 1: EmbeddingEngine 默认硬编码 bge-m3（2.2GB），无离线/小模型选项
证据: embedding/engine.py L43 DEFAULT_MODEL = "BAAI/bge-m3"，模型路径覆盖靠环境变量 HIPPO_EMBED_MODEL_PATH，但 README 没文档化。
影响:
- v0.4 roadmap 写"bge-small-zh 5ms sweet spot"是用户最该用的，但用户必须读源码才知道怎么换
- 国内用户没梯子下不了 HF，2.2GB 一次下载就劝退
- 没有 HNSW/ANN 模型缓存机制，每次
SentenceTransformer(model) 都重新加载
建议:
- 把
HIPPO_EMBED_MODEL / HIPPO_EMBED_MODEL_PATH / HIPPO_EMBED_DIM 写进 README Configuration 章节
- 加
local_files_only=True + 本地路径覆盖路径（魔搭下载的模型目录直接可用）
- 默认模型改成
bge-small-zh-v1.5（183MB），把 bge-m3 标为"质量优先"档
问题 2: hippo/ 命名空间包混乱
证据:
hippo/ 只有 safety_guard.py，没有 __init__.pyfrom hippo import safety_guard 不工作（hippo 是 implicit namespace package）- README 示例
from hippo.safety_guard import SafetyGuard 暗示应该 work
- 但
safety_guard.py 在显式 import 形式下也能跑（Python 3 namespace pkg 机制）
影响: 用户照 README 复制代码直接报错；命名空间包和显式包混用令人困惑。
建议:
- 要么补
hippo/__init__.py 把 safety_guard 提升成完整子包
- 要么把文件挪到顶层
safety_guard.py 并修文档
问题 3: 文档与 wheel 不一致
证据: README 多个示例用 from hippo.embedding import VectorStore，但 wheel 把 embedding 铺在顶层。
建议:
- README 加顶部说明："Wheel flattens
embedding to top-level. Use from embedding.store import VectorStore for wheel installs. from hippo.embedding import VectorStore only works against source tree."
- 或者修打包配置让两种用法都 work（推荐）
问题 4: tests/ 覆盖度不均
证据:
embedding/ 目录下 0 个测试文件pipeline/ 下 4 个测试（test_backend_llama/loop_detector/phase2/rate_limiter）hippo/（safety_guard）和顶层 acceleration.py（15KB 复杂架构）都没测试覆盖
影响: 核心 embedding 模块的回归测试空白，发布质量靠人肉 review。
建议: 补
embedding/tests/test_store.py（sparse/hybrid 模式 + filter 行为）embedding/tests/test_engine.py（模型加载、embed 正确性）embedding/tests/test_importers.pytests/test_safety_guard_three_tier.py（L1→L2→L3 升维逻辑）
环境
- hippo-llm 0.3.1 (PyPI)
- 来源：lawcontinue/hippo @ commit e64c375
汇总 4 个影响新用户体验的可用性问题，可以分 PR 解决，也可以一个 PR 全处理。
问题 1:
EmbeddingEngine默认硬编码bge-m3（2.2GB），无离线/小模型选项证据:
embedding/engine.pyL43DEFAULT_MODEL = "BAAI/bge-m3"，模型路径覆盖靠环境变量HIPPO_EMBED_MODEL_PATH，但 README 没文档化。影响:
SentenceTransformer(model)都重新加载建议:
HIPPO_EMBED_MODEL/HIPPO_EMBED_MODEL_PATH/HIPPO_EMBED_DIM写进 README Configuration 章节local_files_only=True+ 本地路径覆盖路径（魔搭下载的模型目录直接可用）bge-small-zh-v1.5（183MB），把 bge-m3 标为"质量优先"档问题 2:
hippo/命名空间包混乱证据:
hippo/只有safety_guard.py，没有__init__.pyfrom hippo import safety_guard不工作（hippo是 implicit namespace package）from hippo.safety_guard import SafetyGuard暗示应该 worksafety_guard.py在显式 import 形式下也能跑（Python 3 namespace pkg 机制）影响: 用户照 README 复制代码直接报错；命名空间包和显式包混用令人困惑。
建议:
hippo/__init__.py把 safety_guard 提升成完整子包safety_guard.py并修文档问题 3: 文档与 wheel 不一致
证据: README 多个示例用
from hippo.embedding import VectorStore，但 wheel 把embedding铺在顶层。建议:
embeddingto top-level. Usefrom embedding.store import VectorStorefor wheel installs.from hippo.embedding import VectorStoreonly works against source tree."问题 4: tests/ 覆盖度不均
证据:
embedding/目录下 0 个测试文件pipeline/下 4 个测试（test_backend_llama/loop_detector/phase2/rate_limiter）hippo/（safety_guard）和顶层acceleration.py（15KB 复杂架构）都没测试覆盖影响: 核心 embedding 模块的回归测试空白，发布质量靠人肉 review。
建议: 补
embedding/tests/test_store.py（sparse/hybrid 模式 + filter 行为）embedding/tests/test_engine.py（模型加载、embed 正确性）embedding/tests/test_importers.pytests/test_safety_guard_three_tier.py（L1→L2→L3 升维逻辑）环境