# https://github.com/activeloopai/hivemind 项目说明书 生成时间：2026-07-06 14:05:45 UTC ## 目录 - [项目概述与系统架构](#page-1) - [核心功能与数据流（捕获、回忆、技能化、代码图谱）](#page-2) - [多 Agent 集成与 Harness 适配层](#page-3) - [运维、故障模式与社区热点问题](#page-4) ## 项目概述与系统架构 ### 相关页面 相关主题：[核心功能与数据流（捕获、回忆、技能化、代码图谱）](#page-2), [多 Agent 集成与 Harness 适配层](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/activeloopai/hivemind/blob/main/README.md) - [package.json](https://github.com/activeloopai/hivemind/blob/main/package.json) - [docs/ARCHITECTURE.md](https://github.com/activeloopai/hivemind/blob/main/docs/ARCHITECTURE.md) - [src/cli/index.ts](https://github.com/activeloopai/hivemind/blob/main/src/cli/index.ts) - [src/config.ts](https://github.com/activeloopai/hivemind/blob/main/src/config.ts) - [src/deeplake-api.ts](https://github.com/activeloopai/hivemind/blob/main/src/deeplake-api.ts) - [src/index-marker-store.ts](https://github.com/activeloopai/hivemind/blob/main/src/index-marker-store.ts) - [embed-deps/embed-daemon.js](https://github.com/activeloopai/hivemind/blob/main/embed-deps/embed-daemon.js)
# 项目概述与系统架构 ## 1. 项目定位与目标用户 Hivemind 是由 Activeloop 开发的、为 Anthropic Claude Code 提供团队级"记忆 + 召回 + 技能共享"能力的增强层。它在不替换 Claude Code 的前提下，通过钩子（hooks）和后台任务，把每一次会话的可观测上下文沉淀到共享存储中，并在下一次提示词提交时主动召回相关记忆，从而让跨会话、跨成员的协作经验得以复用。`资料来源：[README.md:1-40]()` 项目以 **deeplake + pg-deeplake** 作为远端真源，配合 PostgreSQL 提供行列混合查询与向量检索能力。仓库主线 `package.json` 显示其同时提供 CLI、MCP 连接器（v0.7.114 集成 Claude Cowork）、web UI 三类入口，避免在单一接入点上做硬绑定。`资料来源：[package.json:1-60]()` 值得强调的两点用户常被混淆的边界： - **Hivemind 自身不存储本地端点**：社区反馈明确指出，目前版本必须依赖 deeplake 后端与 pg-deeplake，无法把 trace 与 memory 搜索完全离线化。`资料来源：[README.md:60-90]()` - **多凭据 Claude 用户场景尚未原生支持自动分流**：在同一台机器上切换多套 Claude 凭证时，需要用户手动控制日志启用，CLI 没有提供按凭据维度的开关。`资料来源：[src/config.ts:1-40]()` ## 2. 技术栈与组件边界 | 层 | 组件 | 职责 | |---|---|---| | 接入层 | Claude Code Hooks / MCP Connector | 在 `UserPromptSubmit`、`SessionStart` 等事件触发时调用 Hivemind | | CLI / API 层 | `src/cli/index.ts` | 提供 `rules`、`skillify`、`openclaw` 等子命令 | | 数据访问层 | `src/deeplake-api.ts` | 封装 pg-deeplake 表、列、索引操作 | | 本地状态 | `src/index-marker-store.ts` | 维护"上次建索引"的 TTL 标记，避免重复 `CREATE INDEX` | | 嵌入服务 | `embed-deps/embed-daemon.js` | 独立的 Node 进程，负责把文本向量化 | | 知识沉淀 | Wiki Summary Worker | 异步总结长会话为可检索摘要（v0.7.117 修复崩溃） | `资料来源：[docs/ARCHITECTURE.md:1-80]()` ## 3. 端到端数据流：从一次用户提问说起 下面描述一次典型的 `UserPromptSubmit` 触发的召回流程，澄清各模块如何协作： ```mermaid sequenceDiagram participant U as 用户 participant CC as Claude Code participant HM as Hivemind Hook participant DL as deeplake/pg-deeplake participant EMB as embed-daemon U->>CC: 提交提示词 CC->>HM: 触发 UserPromptSubmit Hook (2s 超时) HM->>DL: 读取 memory/rules 表 + 命中条件 HM->>EMB: 请求向量召回 (可选) EMB-->>HM: top-k 命中片段 HM-->>CC: 注入额外上下文 CC-->>U: 渲染回答 HM->>DL: 异步写回本次 trace ``` 关键约束如下： - **2 秒硬超时**：`UserPromptSubmit` hook 在 Claude Code 端被截断为 2s；如果 `embed-daemon` 缺失或响应迟钝，会直接导致 hook 报错并丢弃输出。`资料来源：[src/cli/index.ts:1-60]()` - **索引去重**：`SessionStart` 路径下，`src/index-marker-store.ts` 负责 TTL 计算，`src/deeplake-api.ts:ensureLookupIndex` 在 marker 未过期时跳过 `CREATE INDEX`。在 ~40k 行 sessions 的活跃工作区中，不做这层判断会带来固定 10s 阻塞。`资料来源：[src/index-marker-store.ts:1-60]()``资料来源：[src/deeplake-api.ts:1-120]()` - **嵌入启动器必须存在**：当 `embed-deps/embed-daemon.js` 被清理而 embeddings 配置仍开启时，会出现"hook 一直超时但配置看似正常"的伪故障。`资料来源：[embed-deps/embed-daemon.js:1-40]()` ## 4. 已知限制与社区共识 最后用一组用户视角的边界做收束，便于新成员快速判断"这个项目现在能做、不能做什么"： - **离线 / 本地 API 模式暂未提供**：必须在 deeplake + pg-deeplake 生态上运行，对纯本地工作流的用户不友好。`资料来源：[README.md:60-90]()` - **schema 漂移会直接打穿 UI**：当 pg 端列索引与 deeplake dataset 不一致时，`memory` 表会因 `Data type mismatch` 无法在 UI 中加载，这是当前 #173 报告的核心矛盾。`资料来源：[src/deeplake-api.ts:120-180]()` - **可选原生模块按需加载**：例如 tree-sitter 在 v0.7.116 之前曾导致 CLI 在缺失环境中崩溃；现在改为运行时探测而非强制 require。`资料来源：[src/cli/index.ts:60-120]()` - **长会话 summary 工作负载已稳定**：v0.7.117–v0.7.118 修复了 wiki summary worker 在超长会话场景下的崩溃，是目前最稳定的一条路径。`资料来源：[package.json:60-120]()` 理解这些边界后，再阅读具体子模块（如 `rules`、`skillify`、`openclaw`）的细节会更连贯，下一章将进入配置与 CLI 用法的深入拆解。 --- ## 核心功能与数据流（捕获、回忆、技能化、代码图谱） ### 相关页面 相关主题：[项目概述与系统架构](#page-1), [多 Agent 集成与 Harness 适配层](#page-3), [运维、故障模式与社区热点问题](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/hooks/capture.ts](https://github.com/activeloopai/hivemind/blob/main/src/hooks/capture.ts) - [src/hooks/recall.ts](https://github.com/activeloopai/hivemind/blob/main/src/hooks/recall.ts) - [src/hooks/wiki-worker.ts](https://github.com/activeloopai/hivemind/blob/main/src/hooks/wiki-worker.ts) - [src/skillify/skillify-worker.ts](https://github.com/activeloopai/hivemind/blob/main/src/skillify/skillify-worker.ts) - [src/graph/graph-command.ts](https://github.com/activeloopai/hivemind/blob/main/src/graph/graph-command.ts) - [src/shell/deeplake-fs.ts](https://github.com/activeloopai/hivemind/blob/main/src/shell/deeplake-fs.ts)
# 核心功能与数据流（捕获、回忆、技能化、代码图谱） Hivemind 是面向 Claude Code 的团队记忆层。它通过 SessionStart / UserPromptSubmit 等钩子捕获会话事件，将数据写入由 deeplake + pg-deeplake 支撑的存储层，并由独立 worker 进程异步加工，最终通过 recall 与代码图谱两种方式把加工后的知识回流到模型上下文。整体数据流可概括为"捕获 → 索引 → 异步加工 → 召回 → 技能化/图谱化"。 ## 数据流概览 ```mermaid flowchart LR CC[Claude Code] -->|SessionStart / UserPromptSubmit| CAP[capture.ts] CAP --> DL[(deeplake-fs.ts
deeplake + pg_deeplake)] DL --> IDX[会话索引] DL --> WW[wiki-worker.ts] WW --> MEM[memory 表] MEM --> REC[recall.ts] REC -->|上下文注入| CC DL --> SK[skillify-worker.ts] DL --> CG[graph-command.ts] SK --> ORG[(org 表)] CG --> CGDB[(code graph)] ``` 捕获层只写，wiki-worker、recall、skillify、graph-command 只读 + 衍生写，这条"主路径只做最小动作、衍生动作异步化"的边界贯穿整个系统。 资料来源：[src/hooks/capture.ts:1-120]() 资料来源：[src/shell/deeplake-fs.ts:30-90]() ## 捕获与异步加工 `src/hooks/capture.ts` 是数据进入 Hivemind 的入口。它监听 `SessionStart`、`UserPromptSubmit`、`PostToolUse`、`Stop` 等钩子事件，把原始会话流切分成可被持久化的记录，并采用流式写入避免阻塞模型响应。 资料来源：[src/hooks/capture.ts:1-120]() 捕获层不直接维护业务表结构，而是把记录交给 `src/shell/deeplake-fs.ts` 提供的文件系统抽象。这一抽象统一了本地 deeplake 路径与 pg-deeplake 远程连接，让后续 worker 可以无差别地读写。wiki-worker 是主要的异步加工者，它消费原始会话、调用 LLM 生成"wiki 摘要"，并把摘要以可被 recall 检索的形式落到 `memory` 表中。 资料来源：[src/hooks/wiki-worker.ts:1-80]() 由于大工作区的 sessions 表可达数万行，`SessionStart` 期间执行的 `CREATE INDEX IF NOT EXISTS` 在 10 秒钩子超时窗口内可能失败，这也是 issue #89 报告的"忙表索引超时"问题的根因。 ## 回忆、技能化与代码图谱 **回忆（recall）**：`src/hooks/recall.ts` 实现主动团队记忆召回。每当 UserPromptSubmit 触发时，它把当前 prompt 与 `memory` 表中的向量做相似度检索，把最相关的若干条记录注入 system context。这一能力依赖嵌入服务，若 `embed-daemon.js` 启动器在 `embed-deps` 中缺失，钩子会卡死直到 2 秒超时被丢弃，对应 issue #296 的现象。 资料来源：[src/hooks/recall.ts:1-150]() **技能化（skillify）**：`src/skillify/skillify-worker.ts` 把本地经验沉淀为可被组织复用的技能。`skillify push` 命令读取本地 skill 文件，将其元数据与正文序列化后写入组织级 org 表，使团队其他成员在 recall 阶段就能命中这些显式沉淀下来的能力描述。它的关键差异在于强调"人类策展"：用户主动提交，worker 负责格式校验、版本化与去重合并。 资料来源：[src/skillify/skillify-worker.ts:1-100]() **代码图谱（graph）**：PR #293 引入的 openclaw 代码图谱由 `src/graph/graph-command.ts` 驱动。该模块在初始化阶段扫描仓库，调用可选的 tree-sitter 解析器构建函数级调用图，把节点和边写入专属 code graph 存储。由于 tree-sitter 是可选依赖，v0.7.116 的修复保证其缺失时 CLI 不会崩溃——`graph build` 退化为纯文本扫描但仍能完成数据写入。 资料来源：[src/graph/graph-command.ts:1-130]() ## 已知限制与社区讨论 | 主题 | 来源 | 影响 | |------|------|------| | 本地化 | issue #282 | 数据流强依赖云端 deeplake + pg-deeplake，纯本地不可用 | | 嵌入启动器缺失 | issue #296 | recall 钩子 2 秒超时被丢弃 | | 忙表索引 | issue #89 | SessionStart 期间索引创建超 10 秒 | | Schema drift | issue #173 | wiki-worker 写入 memory 表需与 pg-deeplake 投影列严格一致 | | 多账号 | issue #113 | recall 不区分 Claude 凭证，多账号用户需手工切换 | 资料来源：[src/shell/deeplake-fs.ts:90-160]() 整个数据流有两个不变式：捕获层只做最小写入，所有衍生数据（摘要、技能、图谱节点）都引用原始会话 ID，以便在 schema drift 或回溯排错时能定位来源——这也是 issue #173 中 `memory` 表错误能被工程上追溯的根本原因。 --- ## 多 Agent 集成与 Harness 适配层 ### 相关页面 相关主题：[项目概述与系统架构](#page-1), [核心功能与数据流（捕获、回忆、技能化、代码图谱）](#page-2), [运维、故障模式与社区热点问题](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [harnesses/claude-code/hooks/hooks.json](https://github.com/activeloopai/hivemind/blob/main/harnesses/claude-code/hooks/hooks.json) - [harnesses/codex/hooks/hooks.json](https://github.com/activeloopai/hivemind/blob/main/harnesses/codex/hooks/hooks.json) - [harnesses/codex/install.sh](https://github.com/activeloopai/hivemind/blob/main/harnesses/codex/install.sh) - [harnesses/codex/INSTALL.md](https://github.com/activeloopai/hivemind/blob/main/harnesses/codex/INSTALL.md) - [harnesses/openclaw/openclaw.plugin.json](https://github.com/activeloopai/hivemind/blob/main/harnesses/openclaw/openclaw.plugin.json) - [harnesses/openclaw/src/index.ts](https://github.com/activeloopai/hivemind/blob/main/harnesses/openclaw/src/index.ts)
# 多 Agent 集成与 Harness 适配层 ## 1. 设计目标与核心职责 Hivemind 的 `harnesses/` 目录实现了一个 **Agent 适配层（adapter layer）**，用于把不同厂商的 AI 编程 Agent（Claude Code、Codex、OpenClaw 等）以统一的钩子契约挂入 Hivemind 自身的会话采集、记忆检索与 recall 流程。 适配层的角色包括： - **声明式接入**：每个子目录提供一个目标 Agent 的安装包，描述事件钩子、脚本入口、依赖与元数据； - **事件归一化**：把不同 Agent 的 hook schema（Claude Code 使用 `UserPromptSubmit`/`SessionStart` 等事件，Codex 使用同等角色的事件）映射成 Hivemind 一侧的 recall、trace 上传入口； - **可选能力暴露**：通过 `plugin.json` 把命令、工具、session-inject 等扩展能力注册到宿主 Agent。 资料来源：[harnesses/claude-code/hooks/hooks.json:1-40]()、[harnesses/codex/hooks/hooks.json:1-40]()、[harnesses/openclaw/openclaw.plugin.json:1-30]() ## 2. 目录结构与适配器划分 `harnesses/` 下按目标 Agent 名字分包，每个包是一个独立的 install unit： | 子包 | 适配目标 | 关键文件 | 主要作用 | |---|---|---|---| | `harnesses/claude-code/` | Anthropic Claude Code | `hooks/hooks.json` | 注册 `UserPromptSubmit` 等事件钩子 | | `harnesses/codex/` | OpenAI Codex CLI | `hooks/hooks.json`、`install.sh`、`INSTALL.md` | 钩子 + 安装脚本 + 文档 | | `harnesses/openclaw/` | OpenClaw 子系统 | `openclaw.plugin.json`、`src/index.ts` | 声明 plugin 能力与入口 | 每个包的边界遵循「一份配置 + 一个入口 + 一个可选 plugin」的模式，宿主 Agent 通过自身扩展机制读取对应 `hooks.json` 或 `plugin.json`，进而调用 Hivemind 提供的 `hivemind recall`、`hivemind log-session` 等命令。 资料来源：[harnesses/codex/install.sh:1-30]()、[harnesses/openclaw/openclaw.plugin.json:1-30]() ## 3. 事件流与钩子契约 以 Claude Code 为例，`hooks.json` 把 `UserPromptSubmit`、`SessionStart` 这类原生事件分别绑定到 recall worker 与索引初始化；Codex 端的 `hooks.json` 复用同样的事件归一化约定，只是命令路径指向 `codex` 子目录。`INSTALL.md` 与 `install.sh` 负责把这些配置自动复制到用户级配置目录，并对 Command 路径进行占位替换。 下面是该层典型的端到端事件流： ```mermaid flowchart LR A[Agent Runtime
Claude Code / Codex] -- hook event --> B[hooks.json
注册器] B -- stdio / CLI 调用 --> C[recall worker
或 session-start] C -- HTTP / local --> D[Hivemind Core
deeplake + pg-deeplake] D -- vector 结果 --> C C -- inject 到 prompt --> A ``` **已知风险点**：当 `embed-daemon.js` 启动器缺失但 embeddings 已启用时，`UserPromptSubmit` 钩子会在 2 秒超时窗口内被强制丢弃（见 issue #296），因此 Harness 层往往需要保证 `embed-deps` 被完整部署，或在 `hooks.json` 中调高 `timeout` 字段。 资料来源：[harnesses/claude-code/hooks/hooks.json:1-40]()、[harnesses/codex/hooks/hooks.json:1-40]()、[harnesses/codex/INSTALL.md:1-20]() ## 4. OpenClaw 插件适配 `harnesses/openclaw/` 使用 `plugin.json` 而非 `hooks.json`，这表明 OpenClaw 走的是**插件**而非**钩子**模式。`openclaw.plugin.json` 通常声明 plugin 名、入口 `src/index.ts` 以及供宿主调度的命名空间；`src/index.ts` 则负责实现工具（tools）、自动构建（auto-build）与 session 注入（session inject）等具体行为（参见 v0.7.118 release notes）。 这意味着 Hivemind 通过两种并行方式覆盖不同 Agent： 1. **Hooks 模式**（Claude Code / Codex）：轻量、按事件触发，主要负责 recall 与 trace 注入； 2. **Plugin 模式**（OpenClaw）：重量级、长期驻留，可暴露 MCP 风格的工具集合。 资料来源：[harnesses/openclaw/openclaw.plugin.json:1-30]()、[harnesses/openclaw/src/index.ts:1-40]() ## 5. 局限与演进方向 - **后端强依赖**：目前 trace 与 recall 仍然依赖 deeplake + pg-deeplake 后端，本地纯离线流程尚未支持（参见 issue #282）； - **会话启动开销**：`session-start` 期间的索引重建在 `sessions` 表规模较大时（如 ~40k 行，参见 issue #89）容易达到 10s 超时阈值，是 Harness 适配层下一个重点优化点； - **多用户凭证区分**：同一台机器运行多个 Claude 凭证时，Harness 层尚不能按凭证路由数据（参见 issue #113），需要在 hook 调用链中尽早注入 `account id` 上下文。 资料来源：[harnesses/codex/install.sh:1-30]()、[harnesses/openclaw/src/index.ts:1-40]() --- ## 运维、故障模式与社区热点问题 ### 相关页面 相关主题：[项目概述与系统架构](#page-1), [核心功能与数据流（捕获、回忆、技能化、代码图谱）](#page-2), [多 Agent 集成与 Harness 适配层](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [src/hooks/recall.ts](https://github.com/activeloopai/hivemind/blob/main/src/hooks/recall.ts) - [src/embeddings/standalone-embed-client.ts](https://github.com/activeloopai/hivemind/blob/main/src/embeddings/standalone-embed-client.ts) - [src/embeddings/daemon.ts](https://github.com/activeloopai/hivemind/blob/main/src/embeddings/daemon.ts) - [src/embeddings/self-heal.ts](https://github.com/activeloopai/hivemind/blob/main/src/embeddings/self-heal.ts) - [src/index-marker-store.ts](https://github.com/activeloopai/hivemind/blob/main/src/index-marker-store.ts) - [src/deeplake-api.ts](https://github.com/activeloopai/hivemind/blob/main/src/deeplake-api.ts) - [src/deeplake-schema.ts](https://github.com/activeloopai/hivemind/blob/main/src/deeplake-schema.ts) - [src/rules/store.ts](https://github.com/activeloopai/hivemind/blob/main/src/rules/store.ts) - [src/wiki/summary-worker.ts](https://github.com/activeloopai/hivemind/blob/main/src/wiki/summary-worker.ts) - [src/cli/index.ts](https://github.com/activeloopai/hivemind/blob/main/src/cli/index.ts)
# 运维、故障模式与社区热点问题 本页梳理 Hivemind 在生产环境中频繁出现的故障模式、对应的源码定位，以及近期社区报告的热点问题与版本演进。读者可通过本页快速对照错误现象与代码模块，并了解已知限制（例如本地化部署尚未支持）。 ## 故障模式分类与典型症状 下表汇总了社区议题中高频出现的故障模式、对应源码模块与已发布的修复版本： | 故障现象 | 涉及源码模块 | 关联 Issue/Release | 修复版本 | | --- | --- | --- | --- | | `UserPromptSubmit` 钩子 2s 超时，`embed-daemon.js` 启动器缺失 | `src/hooks/recall.ts`、`src/embeddings/daemon.ts`、`src/embeddings/self-heal.ts` | [#296](https://github.com/activeloopai/hivemind/issues/296) | 待修复 | | `CREATE INDEX IF NOT EXISTS` 在 40k 行 sessions 表上 10s 超时 | `src/index-marker-store.ts`、`src/deeplake-api.ts:ensureLookupIndex` | [#89](https://github.com/activeloopai/hivemind/issues/89) | 待修复 | | `default.memory` 表出现 "schema drift" 错误 | `src/deeplake-schema.ts`、`src/deeplake-api.ts` | [#173](https://github.com/activeloopai/hivemind/issues/173) | 待修复 | | `wiki summary worker` 在长会话上崩溃 | `src/wiki/summary-worker.ts` | [#298](https://github.com/activeloopai/hivemind/pull/298) | v0.7.117 | | CLI 在缺少 `tree-sitter` addon 时崩溃 | `src/cli/index.ts` | [#295](https://github.com/activeloopai/hivemind/pull/295) | v0.7.116 | | `rules list` 在缺少 `hivemind_rules` 表时执行注定失败的 SELECT | `src/rules/store.ts` | [#292](https://github.com/activeloopai/hivemind/pull/292) | v0.7.115 | ## 嵌入守护进程与召回钩子链路 `UserPromptSubmit` 钩子在 Claude Code 每次提交提示词时被触发，由 `src/hooks/recall.ts` 启动召回流程。召回阶段需要调用嵌入服务生成向量；当用户配置启用了嵌入但 `embed-deps` 中缺失 `embed-daemon.js` 启动器时，`src/embeddings/daemon.ts` 会反复尝试 spawn 而失败，导致钩子输出被 2s 超时阈值丢弃。资料来源：[src/hooks/recall.ts:1-80]()。自愈逻辑位于 `src/embeddings/self-heal.ts`，负责检测启动器缺失并提示用户重新安装，但目前仍依赖外部修复。资料来源：[src/embeddings/standalone-embed-client.ts:40-120]()。社区已确认该问题在全新会话中持续复现，临时缓解方式包括：临时在 `settings.json` 中禁用相关钩子、或确保嵌入依赖完整安装。 ## 索引构建与会话启动延迟 `SessionStart` 阶段会调用 `src/deeplake-api.ts:ensureLookupIndex`，对 sessions 表执行 `CREATE INDEX IF NOT EXISTS`。在如 `activeloop/hivemind` 这类会话行数达到约 4 万的繁忙工作区上，该语句在 pg_deeplake 后端中耗时可达 10s，触发钩子超时。资料来源：[src/deeplake-api.ts:200-260]()。`src/index-marker-store.ts` 负责维护索引构建的时间戳与新鲜度标记，理论上应能跳过尚未过期的索引重建，但当前 TTL 与标记新鲜度校验的实现尚未覆盖高并发写入场景。资料来源：[src/index-marker-store.ts:30-90]()。运维建议：在大型工作区临时调高 SessionStart 钩子超时阈值，或定期手工重建索引以分散开销。 ## 模式漂移与查询错误 UI 层加载 `memory` 表时会触发 `Query Error: Data type mismatch: pg_deeplake: schema drift on table "default.memory"`，根因是 pg 投影的列索引与底层 deeplake 数据集结构不一致。`src/deeplake-schema.ts` 负责维护表结构映射，但在跨版本升级或外部直接修改数据集时容易发生漂移。资料来源：[src/deeplake-schema.ts:50-140]()。建议在升级前执行 schema 校验脚本，或在 UI 中提供"重建表结构"操作以恢复一致状态。 ## 已知限制与近期版本演进 社区已确认 Hivemind 当前不提供纯本地化部署方案，必须依赖 deeplake 后端与 pg-deeplake 来采集追踪、启用记忆搜索与召回。资料来源：[issue #282](https://github.com/activeloopai/hivemind/issues/282)。在多 Claude 凭据共存场景下（[#113](https://github.com/activeloopai/hivemind/issues/113)），Hivemind 尚不支持按凭据自动筛选采集，需用户手动切换日志开关。近期版本聚焦稳定性修复：v0.7.115 跳过缺失表上的失败 SELECT，v0.7.116 在 `tree-sitter` addon 缺失时降级而非崩溃，v0.7.117/v0.7.118 修复 `wiki summary worker` 在长会话上的崩溃并引入 openclaw 代码图自动构建。资料来源：[src/cli/index.ts:1-60]()、资料来源：[src/rules/store.ts:20-70]()、资料来源：[src/wiki/summary-worker.ts:1-50]()。建议运维在升级前参考对应 PR 与 release note，评估对自定义钩子与外部 addon 的影响。 --- --- ## Doramagic 踩坑日志 项目：activeloopai/hivemind 摘要：发现 22 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: Recall UserPromptSubmit hook hangs (2s timeout) when embed-daemon.js launcher is missing from...。 ## 1. 安装坑 · 失败模式：installation: Recall UserPromptSubmit hook hangs (2s timeout) when embed-daemon.js launcher is missing from... - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Recall UserPromptSubmit hook hangs (2s timeout) when embed-daemon.js launcher is missing from embed-deps despite embeddings enabled - 对用户的影响：Developers may fail before the first successful local run: Recall UserPromptSubmit hook hangs (2s timeout) when embed-daemon.js launcher is missing from embed-deps despite embeddings enabled - 证据：failure_mode_cluster:github_issue | https://github.com/activeloopai/hivemind/issues/296 | Recall UserPromptSubmit hook hangs (2s timeout) when embed-daemon.js launcher is missing from embed-deps despite embeddings enabled ## 2. 安装坑 · 失败模式：installation: v0.7.116 — fix(cli): don't crash when optional tree-sitter addon is absent (install P0) - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.7.116 — fix(cli): don't crash when optional tree-sitter addon is absent (install P0) - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.116 — fix(cli): don't crash when optional tree-sitter addon is absent (install P0) - 证据：failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.116 | v0.7.116 — fix(cli): don't crash when optional tree-sitter addon is absent (install P0) ## 3. 安装坑 · 来源证据：Recall UserPromptSubmit hook hangs (2s timeout) when embed-daemon.js launcher is missing from embed-deps despite embedd… - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Recall UserPromptSubmit hook hangs (2s timeout) when embed-daemon.js launcher is missing from embed-deps despite embeddings enabled - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/activeloopai/hivemind/issues/296 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 4. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/activeloopai/hivemind | host_targets=claude, openclaw, claude_code, cursor ## 5. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/activeloopai/hivemind | README/documentation is current enough for a first validation pass. ## 6. 运行坑 · 失败模式：runtime: session-start: CREATE INDEX IF NOT EXISTS times out at 10s on busy sessions tables - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this runtime risk before relying on the project: session-start: CREATE INDEX IF NOT EXISTS times out at 10s on busy sessions tables - 对用户的影响：Developers may hit a documented source-backed failure mode: session-start: CREATE INDEX IF NOT EXISTS times out at 10s on busy sessions tables - 证据：failure_mode_cluster:github_issue | https://github.com/activeloopai/hivemind/issues/89 | session-start: CREATE INDEX IF NOT EXISTS times out at 10s on busy sessions tables ## 7. 运行坑 · 失败模式：runtime: v0.7.117 — fix: stop wiki summary worker crash on long sessions - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this runtime risk before relying on the project: v0.7.117 — fix: stop wiki summary worker crash on long sessions - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.117 — fix: stop wiki summary worker crash on long sessions - 证据：failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.117 | v0.7.117 — fix: stop wiki summary worker crash on long sessions ## 8. 运行坑 · 失败模式：runtime: v0.7.118 — fix: stop wiki summary worker crash on long sessions - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this runtime risk before relying on the project: v0.7.118 — fix: stop wiki summary worker crash on long sessions - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.118 — fix: stop wiki summary worker crash on long sessions - 证据：failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.118 | v0.7.118 — fix: stop wiki summary worker crash on long sessions ## 9. 运行坑 · 来源证据：session-start: CREATE INDEX IF NOT EXISTS times out at 10s on busy sessions tables - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：session-start: CREATE INDEX IF NOT EXISTS times out at 10s on busy sessions tables - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/activeloopai/hivemind/issues/89 | 来源类型 github_issue 暴露的待验证使用条件。 ## 10. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/activeloopai/hivemind | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/activeloopai/hivemind | no_demo; severity=medium ## 12. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/activeloopai/hivemind | no_demo; severity=medium ## 13. 运行坑 · 失败模式：performance: Other (local) API options? - 严重度：low - 证据强度：source_linked - 发现：Developers should check this performance risk before relying on the project: Other (local) API options? - 对用户的影响：Developers may hit a documented source-backed failure mode: Other (local) API options? - 证据：failure_mode_cluster:github_issue | https://github.com/activeloopai/hivemind/issues/282 | Other (local) API options? ## 14. 运行坑 · 失败模式：performance: v0.7.109 — feat: add skillify push to upload local skills to org table - 严重度：low - 证据强度：source_linked - 发现：Developers should check this performance risk before relying on the project: v0.7.109 — feat: add skillify push to upload local skills to org table - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.109 — feat: add skillify push to upload local skills to org table - 证据：failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.109 | v0.7.109 — feat: add skillify push to upload local skills to org table ## 15. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/activeloopai/hivemind | issue_or_pr_quality=unknown ## 16. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/activeloopai/hivemind | release_recency=unknown ## 17. 维护坑 · 失败模式：maintenance: v0.7.110 — feat: add skillify push to upload local skills to org table - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v0.7.110 — feat: add skillify push to upload local skills to org table - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.110 — feat: add skillify push to upload local skills to org table - 证据：failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.110 | v0.7.110 — feat: add skillify push to upload local skills to org table ## 18. 维护坑 · 失败模式：maintenance: v0.7.111 — feat: add skillify push to upload local skills to org table - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v0.7.111 — feat: add skillify push to upload local skills to org table - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.111 — feat: add skillify push to upload local skills to org table - 证据：failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.111 | v0.7.111 — feat: add skillify push to upload local skills to org table ## 19. 维护坑 · 失败模式：maintenance: v0.7.112 — feat: add skillify push to upload local skills to org table - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v0.7.112 — feat: add skillify push to upload local skills to org table - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.112 — feat: add skillify push to upload local skills to org table - 证据：failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.112 | v0.7.112 — feat: add skillify push to upload local skills to org table ## 20. 维护坑 · 失败模式：maintenance: v0.7.113 — fix: fold skill trigger into host-visible description - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v0.7.113 — fix: fold skill trigger into host-visible description - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.113 — fix: fold skill trigger into host-visible description - 证据：failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.113 | v0.7.113 — fix: fold skill trigger into host-visible description ## 21. 维护坑 · 失败模式：maintenance: v0.7.114 — fix: fold skill trigger into host-visible description - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v0.7.114 — fix: fold skill trigger into host-visible description - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.114 — fix: fold skill trigger into host-visible description - 证据：failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.114 | v0.7.114 — fix: fold skill trigger into host-visible description ## 22. 维护坑 · 失败模式：maintenance: v0.7.115 — fix(rules): skip doomed SELECT on `rules list` when hivemind_rules is absent - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v0.7.115 — fix(rules): skip doomed SELECT on `rules list` when hivemind_rules is absent - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.115 — fix(rules): skip doomed SELECT on `rules list` when hivemind_rules is absent - 证据：failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.115 | v0.7.115 — fix(rules): skip doomed SELECT on `rules list` when hivemind_rules is absent