Qdrant 与 Worker 本地常驻部署运维
Hippo 采用 100% 本地优先原则,底层向量存储依赖运行在 127.0.0.1:6333 的单二进制 Qdrant 实例。
1. 运行模式
Hippo 支持两种 Qdrant 运行模式:
- LaunchAgent 系统常驻模式(推荐): 通过 macOS 的
launchd机制将 Qdrant 注册为系统级后台常驻服务(dev.hippo.qdrant),开机自启、崩溃自动重启。 - 按需按次拉起模式(On-Demand Fallback): 若未安装常驻服务,每次调用
hippo命令或通过 MCP 唤起时,Hippo 会自动检测端口6333;若未监听且本地二进制存在,会自动通过后台子进程拉起。
MCP 项目路由与排障
hippo-mcp 的工作目录可能是安装仓库;客户端通过 uv --directory 启动服务时,这个目录也不代表当前聊天项目。MCP 的 search_memories(包括时间线查询)和 add_memory 优先使用显式 project_id,省略时读取当前请求所属客户端的 MCP roots,并仅在能够确定唯一 Git 仓库时自动路由。
scope='project'只使用已解析项目;scope='all'加入当前用户的全局偏好,两者都需要可靠的项目身份。scope='global'无需项目。搜索的旧agent_id继续优先覆盖范围,agent_id='global'仅查全局。- roots 缺失、不支持、不可访问、非 Git、涉及多个仓库,或客户端 2 秒内未返回时,工具会提示显式选择项目,且不会访问记忆后端。服务不会用自己的目录或
default_project猜测项目。 - 同仓库的多个子目录可自动解析;多仓库列表无法说明聊天属于哪一个,需要显式选择。roots 的显示名称不会成为项目标签。
收到“无法可靠解析调用方项目”时,使用本次聊天的项目名,或本机 Git 仓库绝对路径重试。例如:
{"query": "项目技术选型", "scope": "project", "project_id": "repository-a"}{"text": "项目使用 uv 管理 Python 依赖", "scope": "project", "project_id": "repository-a"}也可让客户端仅提供当前仓库 root。绝对路径会沿用现有 Git 仓库名命名空间,与自动选择该仓库一致;MCP 不接受相对路径。修复部署后重启宿主中的 Hippo MCP 连接并刷新工具 schema,让客户端识别写入新增的 project_id。该修复不迁移历史记忆,CLI、SDK 与 Hook 的缺省目录路由保持原有契约;共享路由器将显式项目名固定为命名空间,避免按服务目录下的同名子目录重新解释,CLI/SDK 的相对路径选择器须包含 /(例如 ./repository-a)。详见 ADR-0009。
2. Qdrant 管理命令
使用 hippo service 子命令管理 Qdrant LaunchAgent:
# 查看当前双服务状态(Qdrant + Worker)
hippo service status
# 安装并启动 Qdrant LaunchAgent 常驻服务(默认行为)
hippo service install
# 卸载并停止 Qdrant 常驻服务
hippo service uninstall3. Worker 常驻守护部署
Spool 异步蒸馏队列的消费由 dev.hippo.worker LaunchAgent 服务负责。
3.1 安装与管理
# 安装 Worker 常驻守护进程
hippo service install worker
# 同时安装 Qdrant 与 Worker
hippo service install all
# 重启 Worker 服务
hippo service restart worker
# 卸载 Worker 常驻服务
hippo service uninstall worker
# 查看双服务运行状态(含 PID、退出码等)
hippo service status3.2 Worker 运行机制
- 单实例排他锁:Worker 通过内核
fcntl.flock实现单进程互斥,同时只有一个 Worker 实例可以运行; - 轻量活跃索引与空闲短路(#120):
- Worker 仅轮询
active/活跃作业索引条目(内含指向jobs/的软链接),并在队列全空时以微秒级前置短路(has_active_jobs())彻底规避目录扫描与状态解析开销; - 实测空闲性能(1800 历史终态作业基线,macOS arm64 / Python 3.12):单周期 CPU Process Time 由 997.66 ms 降至 0.05 ms(降幅 > 99.99%),文件打开数由 54,000 次降至 0 次;
- 冷启动与存量升级自愈:通过
active/.initialized标记位实现零负担自愈。存量旧队列无需额外维护,首次被任何工具(CLI、Worker、查询)读取时自动一次性对齐索引; - 租约安全与双层保底:
ACTIVE_STATES包含PENDING与PROCESSING,作业持锁消费期间始终保留在active/中,空闲短路绝不影响租约恢复;若发生极端磁盘损坏或进程被强杀漏写软链,启动时(L1)与每 300s 周期巡检(L2)自动执行全量对齐;
- Worker 仅轮询
- LaunchAgent 保活:plist 中配置
KeepAlive: true+RunAtLoad: true,崩溃后由launchd自动拉起; - 优雅退出:Worker daemon 监听
SIGTERM/SIGINT信号,收到信号后完成当前安全边界再退出; - 日志路径:
~/.hippo/logs/worker.log; - 环境变量:Worker LaunchAgent 自动注入
HIPPO_DISABLE_RECOVERY_WAKEUP=1,禁用多余的定时唤醒进程。
3.3 Fallback 按需消费模式
若未安装 Worker LaunchAgent,每次 Hook 捕获(hippo hook capture)后会自动 spawn 一次性后台 --drain 进程消费队列。此模式无需额外配置,但在宿主 Hook 不频繁触发时可能导致积压。
4. 核心路径与目录结构
所有 Hippo 运行时数据均统一保存在 ~/.hippo(或环境变量 HIPPO_HOME 指定的目录):
~/.hippo/
├── bin/
│ └── qdrant # Qdrant 单二进制执行文件
├── config/
│ └── qdrant.yaml # Qdrant 服务端配置文件
├── storage/ # 物理持久化目录
│ ├── history.db # SQLite 记忆版本历史
│ └── qdrant/ # Qdrant 向量库存储
├── spool/ # 异步会话蒸馏队列
│ ├── jobs/ # 作业目录(payload.json + state.json 事实源)
│ ├── active/ # 活跃作业轻量索引条目(pending/processing,空闲零开销)
│ ├── receipts/ # 语义去重收据(永不清理)
│ └── tombstones/ # 已清理作业墓碑标记(保持 job-id 幂等)
├── logs/
│ └── worker.log # Worker 常驻守护日志
├── qdrant.log # Qdrant 服务端运行与崩溃日志
└── .env # 本地环境配置 (API 密钥与模型参数)