核心用法
CrabPath 是一款纯 Python 实现的内存图引擎，采用调用方提供回调的架构设计。核心库（crabpath）完全零依赖、零网络调用，所有嵌入生成与LLM推理均需通过外部回调函数注入。
典型工作流：
1. 使用 split_workspace() 解析工作目录，分离图谱结构与文本内容
2. 选择嵌入方式：默认 HashEmbedder（1024维哈希向量）或传入自定义 embed_fn 回调
3. 构建 VectorIndex 索引，通过 upsert() 写入节点向量
4. 查询时通过 llm_fn 回调路由至目标模型（如 gpt-5-mini）
5. 支持 --state 参数持久化会话状态，可用 replay_queries 预热历史查询
显著优点
- 极致隔离：核心无网络、无密钥发现、无子进程包装，安全边界清晰
- 嵌入无关性：不绑定特定嵌入模型，维度不匹配时显式报错而非静默失败
- 状态可移植：单文件
state.json格式，便于版本控制与迁移 - 会话可复现：内置查询回放机制，利于调试与性能优化
潜在局限
- 上手门槛：需自行整合嵌入服务与LLM客户端，非开箱即用
- 性能瓶颈：纯 Python 实现，大规模数据时可能成为瓶颈
- 生态依赖：缺少预置的云端集成，需用户自行对接 OpenAI/Anthropic 等
- 功能边界：定位为"引擎"而非完整RAG系统，需配合其他工具链
适合人群
- 对数据隐私有严格要求、需在隔离环境运行的企业开发者
- 希望完全控制嵌入模型与LLM供应商的高级用户
- 需要将图谱能力嵌入自有框架的基础设施团队
常规风险
- 回调注入风险：
embed_fn/llm_fn由调用方提供，若注入恶意回调可导致数据外泄 - 状态文件泄露：
state.json含完整图谱与向量数据，需妥善保管访问权限 - 哈希碰撞：默认
HashEmbedder为确定性哈希，语义相似性表达能力有限，生产环境建议替换为真实嵌入模型