hivemind

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/brand/hivemind-mark-dark.svg"> <img alt="Hivemind" src="assets/brand/hivemind-mark.svg" width="92" height="92"> </picture> # hivemind ***面向集体智能体的开放内存层。*** 独立于供应商的开源MCP服务，适用于三层智能体内存： `短` · `中` · `长`。 来自任何支持MCP的运行时的智能体都会注意到其他智能体正在执行的操作，继承其他智能体已经学习的内容，并共同理解复杂的项目。 [](#-concept) [](#-license) [](https://github.com/Lesur-ai/hivemind/actions/workflows/ci.yml) [](#-license) [](#-prerequisites) </div> --- ## 📋 目录 - [概念](#-concept) - [项目网格](#project-mesh) - [Hivemind 不声称（V1）](#-what-hivemind-does-not-claim-v1) - [架构](#-architecture) - [前提条件](#-prerequisites) - [安装](#-installation) - [配置](#-configuration) - [入门](#-getting-started) - [MCP 工具](#-mcp-tools) - [长期层 — 本体/知识图谱](#-long-tier--ontology--knowledge-graph) - [Web 接口](#-web-interface) - [MCP 集成](#-mcp-integration) - [CLI 和 Shell](#-cli-and-shell) - [测试](#-tests) - [安全](#-security) - [项目结构](#-project-structure) - [故障排除](#-troubleshooting) - [贡献](#-contributing) - [文档地图](#-documentation-map) --- ## 🎯 概念 **Hivemind** 是开源的MCP（模型上下文协议）服务，为AI智能体提供**跨三个层级的共享内存** — `短`、`中` 和 `长` — 以及其项目级同步功能 **项目网格**：多个智能体和团队可以共享一个逻辑项目内存空间，管理员可以通过权限控制的管理员控制台选择加入实施的网格同步V1流程。 Hivemind 将孤立的智能体上下文转化为共享空间，智能体可以在此空间中**注意到**其他智能体正在执行的操作，**继承**其他智能体已经学习的内容，并**理解**复杂的项目。 Markdown 内存文件是一个良好的原始数据类型，但它们本身会成为孤岛：一个智能体写入一个 `.md` 银行，另一个智能体或供应商从不同的上下文开始，项目所有者成为集成层。Hivemind 使**空间**成为内存的所有者，而不是任何一个助手、IDE、模型提供商或提示历史记录。如果您从一个支持MCP的智能体转移到另一个，累积的项目上下文将保留在您的 Hivemind 存储和治理边界中。 ### 三个内存层级 | 层级 | 曾用名 | 存储内容 | 关键时刻 | | --- | --- | --- | --- | | **`短`** | `live_*` | 追加式实时笔记：观察、决策、待办事项 — 立即工作上下文，在空间内可见。 | **注意到** — 一个智能体因看到另一个智能体的当前工作而改变方向。 | | **`中`** | `bank_*` | 巩固的Markdown内存库：规则、综合、项目上下文。结构化工作内存，其他智能体继承。 | **继承** — 一个智能体在没有手动提示的情况下恢复另一个智能体留下的规则或方法。 | | **`长`** | `graph_*` | 本体/知识图谱层：派生的关联回忆，集体过程建立的概念链接。 | **理解** - 一个智能体检索跨集体知识的逻辑链接。 | 历史上的 `live_*` / `bank_*` / `graph_*` 工具名称与 `short_*` / `mid_*` / `long_*` 一一映射，并**保留为兼容别名**。参见[兼容别名](#compatibility-aliases)。 <a id="project-mesh"></a> ### 项目网格 除了单个服务器之外，**项目网格** 是 Hivemind 的项目级同步功能。在V1中，它分为两个明确分离的阶段： - **今日可用 — 智能体级共享。** 多个团队、开源贡献者和智能体群集将它们自己的支持MCP的运行时连接到一个统一的 `space_id` 上 — 一个空间拥有其 `短` 笔记、`中` 银行、`长` 投影和项目网格协调状态。 - **可用作可选实例联合。** 两个管理员通过三个操作配对一个空白目标：创建一次性不透明邀请（有效期为 **3,600 秒**），在目标上粘贴和接受，然后在源上验证和批准。签名的对等交换执行待命的成员资格转换、有界启动导入、最终确认和激活；突变后故障仍处于显式恢复中，而不是回滚。此V1配对流程为 **两个节点网格** 提供了一个源，其空间有一个活动成员。它拒绝一个已经有多个活动成员的源；通过此工作流添加第三个节点在V1中不受支持。启动后，两个对等方对称运行。操作员使用权限控制的 `/admin` `#/mesh` 路由。网格仍然是一个管理员/对等方HTTP表面：24工具最大智能体发现和完整的注册MCP表面 **不暴露 `mesh_*` MCP工具**。 使用场景是软件开发加速：多个贡献者可以使用他们自己的智能体并行工作，同时共享内存、来源和突变排序保留在项目边界内。参见 [`docs/PROJECT_MESH.md`](docs/PROJECT_MESH.md) 以获取规范词汇。 > 项目网格的 **网格同步V1** 协议设计上是保守的：**全网格全确认，不是法定人数**。参见 [Hivemind 不声称（V1）](#-what-hivemind-does-not-claim-v1) 以获取确切的边界，即今天的内容和后续工作。 ### 供应商中立所有权 Hivemind的多智能体承诺也是一个多供应商承诺： | 没有Hivemind | 有Hivemind | | --- | --- | | Markdown内存作为孤立的文件存在于每个智能体或工具旁边。 | `短`、`中`和`长`内存存在于一个受管辖的Hivemind空间中。 | | 切换智能体通常意味着重新提示、复制上下文或信任供应商历史记录。 | 任何支持MCP的智能体都可以通过作用域令牌读写。 | | 项目知识漂移到供应商特定的会话中。 | 内存存在于操作员控制的存储中，保护连续性、所有权和项目知识产权。 | ### 为什么是三个层级？ 一个层级永远不够： - `短` 独自是 **短暂的** — 它随着项目的进展而滚动消失。 - `长` 独自 **太重** ，不适合快速的日常笔记。 - `中` 是结构化的桥梁：智能体 **快速写入** （`短`）、**合并** 到一个持久的银行（`中`），并 **资本化** 知识到一个本体支持的图谱（`长`）。 这种共享内存架构遵循 [Tran 等人，2025 — *多智能体协作机制：大型语言模型的调查*](https://arxiv.org/abs/2501.06322) 中的多智能体框架，该框架将 **共享环境** 和 **共享内存** 确定为大型语言模型智能体协调的基本组件，而不是作为孤立的算法运行。 --- ## 🚫 Hivemind 不声称（V1） Hivemind 的定位是诚实的。以下内容 **不是** 当前行为。后续阶段可能会重新审视每个点，但在此之前，它们未实现，不应被假设。本节是 [`docs/POSITIONING.md`](docs/POSITIONING.md) 的公开镜像，即规范的非声明管控铁丝网，并用 HTML 注释标记，以便自动化发布文档检查可以确定性地检测到它。 <!-- non-claims --> Hivemind V1 不声称： - **法定人数共识** — 项目网格V1/网格同步V1是全网格全确认，而不是法定人数运行时。 - **中心化拓扑** — 没有中心化枢纽；所有对等方在网格同步V1下是等价的。 - **永久主节点/领导者运行时** — 没有节点持有永久领导权，也没有领导者选举路径。 - **离线优先的CRDT合并** — Hivemind V1不是CRDT系统，不尝试离线优先的冲突-free合并。 - **合并两个已经有状态的空间** — V1不合并已经有状态的两个空间；没有两个已填充空间的协调路径。 - **并行集体合并** — `中`层合并按空间序列化；没有跨智能体的并行集体合并。 - **多租户行为** — 基于令牌的 `space_ids` 允许列表是 **唯一** 的隔离原语。没有租户对象，没有行级安全，也没有开源版的按租户隔离存储。 `space_ids` 是允许列表，**不是** 租户隔离；对于租户隔离，请参见下游扩展接口（ADR-0003）。 此外： - **`长` 内存从不具有权威性。** `长` 本体/知识图谱层 **仅是派生投影** 。它从不作为提交有效性、回滚、审计、墓碑、水印或恢复的源，并且没有 `长` 状态位于提交路径中（ADR-0010）。 - **`backup_restore` 默认情况下，如果共享项目网格空间被拒绝，则需要显式操作员确认才能强制执行。** 默认情况下，**恢复到**共享/不安全/损坏的Hivemind空间（通过 `hive_status_label` 进行只读检测，ADR-0008）被 **拒绝** ；损坏的关键状态、缺失的本地 `NodeIdentity` （孤立节点），或备份的 `bank_version` 严格大于实时指针都被 **拒绝并关闭零突变** 。通过操作员确认的 `unsafe_recovery=True` ，恢复运行 ADR-0014（已接受）的字段级前向强制编排：它通过 `CommitRuntime` 暂存备份库，通过 `assert_commit_allowed()` （单个授权点，ADR-0011）在 `pointer+1` 处发布前向 `BankCommit` ，在 `{space}/_hivemind/events/` 下发出 `UNSAFE_RECOVERY_RESTORED` + `RESYNC_REQUIRED` 审计事件，并将节点标记为 `HiveNodeStatus.RESYNC_REQUIRED` ，直到重新启动。参见公开的 [迁移和恢复指南](docs/MIGRATION_LIVE_GRAPH_TO_HIVEMIND.md#6-shared-space-restore-caveat) （ADR-0014）。对于单个实例、非共享（`local_only` / `not_a_space`）情况，`backup_restore` 不更改 — 按字节逐字节直接传输。 <!-- /non-claims --> "集体意识"和"集体意识" 是定位语言，而不是字面意义上的声明 — Hivemind 不声称 AGI、感知或意识。 --- ## 🏗️ 架构 ``` 智能体 Cline 智能体 Claude 智能体 X │ │ │ └────────┬──────────┘ │ │ │ ▼ MCP 协议（可流式 HTTP） ▼ ┌────────────────────────────────────────┐ │ WAF （Caddy + Coraza CRS） │ │ 速率限制 • TLS • OWASP CRS │ └────────────┬───────────────────────────┘ │ ┌────────────┴───────────────────┐ │ Hivemind MCP 服务 │ │ 短 · 中 · 长 │ │ 项目网格同步状态 │ │ 身份验证 Bearer • 合并 │ └──────┬──────────┬──────┬───────┘ │ │ │ ┌──────┴──┐ ┌────┴───┐ │ │ S3 │ │ LLM │ │ MCP 流式 HTTP │ 持久 │ │ （中 │ │ （内部长引擎绑定） │ 存储 │ │ 合并）│ │ └─────────┘ └────────┘ │ ┌───────────┴────────────┐ │ 长层引擎 │ │ 本体 / 知识 │ │ 图谱（仅派生） │ └────────────────────────┘ ``` **协议栈**：S3 + LLM 用于权威短/中和项目网格状态。 **完整的 Hivemind 产品**：包括强制的 `长` 本体/知识图谱引擎，内部绑定到空间。它是一个 **派生投影** ，不在提交路径上 — 参见 [长层](#-long-tier--ontology--knowledge-graph)。 > WAF 配置文件和嵌入式 `长` 运行时在默认的 compose 栈中提供 ([docker-compose.yml](docker-compose.yml))；S3 后端和 LLM 提供者通过 `.env` 由操作员提供。示例中的具体端点是示例，而不是默认值。 --- ## 📦 先决条件 - **Docker** >= 24.0 + **Docker Compose** >= 2.17.0 (`up --wait` 使用) - **Python 3.11+** 和 [`uv`](https://docs.astral.sh/uv/) （用于本地 CLI/测试） - 兼容的 **S3 存储** （Dell ECS、AWS、MinIO） - OpenAI-API 兼容的 **LLM** （用于 `中` 合并和 `长` 提取、嵌入和语义查询） - 没有单独的图后端或图令牌：图内存 + Neo4j + Qdrant **嵌入在默认 compose 栈中** （ADR-0019）。嵌入式运行时仍然使用配置的LLM API 进行长层摄取和查询。 --- ## 🚀 安装 > 默认 `docker compose up -d` 启动 **完整的** Hivemind 产品：WAF、Hivemind MCP 服务和嵌入式 `长` 运行时（Graph Memory + Neo4j + Qdrant）位于内部 Docker 网络中（ADR-0019）。无网络的单次初始化程序准备本地秘密卷，然后 Hivemind 在就绪之前持久创建/注册其作用域内部凭证；持久性或撤销失败会停止启动。 > 每个产品空间在其第一次长写入 (`long_push`) 时自动绑定到嵌入的 `长` 引擎 — **无需手动绑定步骤** 。 > 从单独的实时内存 + 图谱内存服务迁移到单个 Hivemind 部署？遵循英文 [空间迁移手册](docs/MIGRATION_LIVE_GRAPH_TO_HIVEMIND.md) （FR： [迁移指南](docs/MIGRATION_LIVE_GRAPH_TO_HIVEMIND.fr.md)）。对于新或迁移的智能体，请使用供应商中立的 [统一智能体内存设置](docs/AGENT_MEMORY_SETUP.md)，包括每个智能体身份的新 Hivemind 令牌的要求。 ### 1. 克隆仓库 ```bash git clone https://github.com/Lesur-ai/hivemind.git cd hivemind ``` ### 2. 创建本地开发环境 ```bash python scripts/configure_dev_env.py ``` 该助手创建 `.env`，模式为 `0600`，随机启动/MinIO/Neo4j凭证、`sigv4` 和网格禁用，以便进行有意的单节点本地评估。它拒绝覆盖现有文件，从不打印生成的秘密。在测试 `中` 或 `长` 之前，请配置 `LLMAAS_API_URL`、`LLMAAS_API_KEY`、`LLMAAS_MODEL`、`LLMAAS_EMBEDDING_MODEL` 和嵌入模型的确切 `LLMAAS_EMBEDDING_DIMENSIONS`。提供者必须公开兼容的 `/chat/completions` 和 `/embeddings` 端点；模板中的模型名称是示例，不是可移植的默认值。生产操作员必须复制 `.env.example`，提供自己的 S3 和秘密，并配置完整的网格身份启用网格。 ### 3a. Docker 启动（推荐） ```bash # 构建镜像，包括本地 MinIO 开发配置文件 docker compose --profile dev build # 启动完整的默认栈 # （WAF + 秘密初始化器 + Hivemind + 嵌入式图内存 + Neo4j + Qdrant） docker compose --profile dev up -d --wait # 检查状态 docker compose ps # 健康检查 curl -s http://localhost:8080/health ``` ### 3b. 本地启动（开发中） 直接主机启动不会运行 Compose 卷初始化器。设置稳定的、非空的 `LONG_EMBEDDED_TOKEN` 在 `.env` 中，尤其是在 macOS 上，或配置 Linux 本地秘密路径以满足 `0700`/`0600` 合同，如 [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md#embedded-credential-lifecycle-and-repair) 中所述。 ```bash # 创建项目环境并安装锁定依赖项 uv sync --locked --dev # 运行服务器 uv run python -m live_mem ``` > **注意：** 源代码包仍为 `live_mem` （导入引擎）。公共 `short`/`mid`/`long` MCP 语法是同一代码的附加命名层；将 Python 包重命名为后期工作，而不是行为更改。 ### 4. 使用捆绑 CLI ```bash uv run python scripts/mcp_cli.py --help ``` ### 5. `长` 层 — 嵌入并自动绑定 强制 `长` 本体/知识图谱引擎已经运行：默认 compose 栈（步骤 3a）在其 Neo4j 和 Qdrant 数据存储启动时启动它，内部网络仅限（ADR-0019）。每个产品空间在其第一个长写入 (`long_push` / `graph_push`) 时自动绑定到它，从而派生出一个确定性的 `memory_id` — **无需手动绑定步骤** 。 `graph_connect` / `long_connect` 仍然可调用为 **高级覆盖/诊断** 诊断工具（例如，在迁移过程中临时将空间指向旧的外部图内存，或选择非默认本体）。它永远不是必需的安装步骤。 ### 6. 验证安装 ```bash # 通过 CLI 进行健康检查 uv run python scripts/mcp_cli.py health # 或完整的 E2E 测试（创建空间，写入笔记，合并） uv run python scripts/test_recette.py # 长层就绪状态：空间的第一个 long_push 后，graph_status / long_status 报告嵌入式运行时已连接（自动绑定，无需手动步骤）。 ``` ### 暴露端口 | 服务 | 端口 | 描述 | | ---------- | ------ | --------------------------------------------- | | **WAF** | `8080` | 仅暴露的端口 — Caddy WAF → Hivemind MCP | | MCP 服务器 | `8002` | 仅限内部 Docker 网络 | --- ## ⚙️ 配置 编辑 `.env` 文件。所有变量都在 `.env.example` 文件中有文档记录。 ### 必备变量 | 变量 | 描述 | 示例 | | ---------------------- | ------------------------ | -------------------------------------------- | | `S3_ENDPOINT_URL` | S3 端点 URL | `https://s3.example.com` | | `S3_ACCESS_KEY_ID` | S3 访问密钥 | `AKIA...` | | `S3_SECRET_ACCESS_KEY` | S3 密钥 | `wJal...` | | `S3_BUCKET_NAME` | 存储桶名称 | `hivemind` | | `S3_REGION_NAME` | S3 区域 | `eu-west-1` | | `LLMAAS_API_URL` | LLM API URL (必须包含 `/v1`) | `https://api.example.com/v1` | | `LLMAAS_API_KEY` | LLM API 密钥 | `sk-...` | | `LLMAAS_MODEL` | `/chat/completions` 接受的确切聊天模型 ID | `provider-chat-model` | | `LLMAAS_EMBEDDING_MODEL` | `/embeddings` 接受的确切嵌入模型 ID | `provider-embedding-model` | | `LLMAAS_EMBEDDING_DIMENSIONS` | 嵌入模型返回的确切向量长度 | `1024` | | `ADMIN_BOOTSTRAP_KEY` | 管理员启动密钥（≥ 32 个随机字符） | `configure_dev_env.py` 生成 | > `LLMAAS_*` 环境变量前缀继承自上游 LLM-as-a-Service 集成，并在此公共版本中保留不变 — 表中的名称是服务实际读取的名称。 > 模板中的 `qwen3.5:27b`、`bge-m3:567m` 和 `1024` 值仅描述一个提供商配置文件。请替换模型 ID 和维度。如果维度错误，则会导致长写入/搜索失败；更改后需要重新索引 Qdrant 集合并重新摄入。 ### 嵌入式长运行时（必备，ADR-0019） `long` 引擎默认包含在 compose 栈中，并在首次长写入时自动绑定到每个空间 — 无需操作员提供 `url` / `token` / `memory_id` 值来配置。其 `.env` 变量如下： | 变量 | 默认值 | 描述 | | -------- | ------- | ----------- | | `NEO4J_PASSWORD` | _(必填)_ | 嵌入式 Neo4j 图形存储的密码 — 栈拒绝在没有它时启动 | | `LONG_EMBEDDED_URL` | `http://graph-memory:8002` | 嵌入式长运行时的内部网络 URL | | `LONG_EMBEDDED_TOKEN` | _(空 = 启动时创建)_ | 本地仅限作用域 `read,write` 令牌；当为空时，Hivemind 原子级持久化和注册一个，然后在就绪之前失败，而不是使用易失性或已撤销状态 | 每个空间的 `graph_connect` / `long_connect` 重写（URL、令牌、memory_id、ontology）仅是一个高级/诊断逃生通道 — 例如，在迁移期间使用外部图形内存 — 而不是设置要求。 ### 可选变量 — LLM（`mid` 层合并） `mid` 层合并器使用 LLM（兼容 OpenAI 的 API）将 `short` 级别的实时笔记转换为结构化的 `mid` 银行。 | 变量 | 默认值 | 描述 | | ------------------------- | ----------------- | ------------------------------- | | `LLMAAS_MODEL` | `qwen3.5:27b` | 提供商公开的 LLM 模型名称 | | `LLMAAS_CONTEXT_WINDOW` | `131072` | 模型的上下文窗口（输入 + 输出组合，以令牌为单位） | | `LLMAAS_MAX_TOKENS` | `16384` | 每个请求的输出令牌的最大值。必须**严格小于** `LLMAAS_CONTEXT_WINDOW`，否则启动时会失败并出现配置错误，错误名称同时包含这两个值。合并器动态调整：`output = min(MAX_TOKENS, CONTEXT_WINDOW - input)` | | `LLMAAS_TEMPERATURE` | `0.3` | LLM 的创造力（0.0 = 确定性，1.0 = 非常创造性） | | `PROXY_URL` | _(无)_ | 出口 HTTP 代理（例如 `http://10.0.0.1:3128`）。**自定义变量**（非 `HTTP_PROXY`）— 注入到 boto3（S3）和 httpx（LLM 合并调用 **和** `/health` 和 `system_health` 的轻量级 LLM 健康探测）。不支持 `long` 级别的连接。 | ### 可选变量 — 合并和压缩 | 变量 | 默认值 | 描述 | | ------------------------- | ----------------- | ------------------------------- | | `MCP_SERVER_PORT` | `8002` | MCP 服务器监听端口 | | `MCP_SERVER_DEBUG` | `false` | 详细日志（完整错误消息） | | `CONSOLIDATION_TIMEOUT` | `600` | 每个 LLM 调用超时（秒） | | `CONSOLIDATION_MAX_NOTES` | `200` | 合并的最大笔记数 | | `CONSOLIDATION_BATCH_SIZE`| `5` | 每个 LLM 批次的笔记数（小 = 精确，大 = 更快） | | `CONSOLIDATION_COOLDOWN_SECONDS` | `60` | `bank_consolidate` 的每个空间反垃圾邮件冷却时间（`0` 禁用） | | `CONSOLIDATION_VALIDATION_ENABLED` | `false` | 合并后可选的验证检查，以防止未经归属的声明 | | `CONSOLIDATION_VALIDATION_MAX_EXAMPLES` | `20` | 验证通过返回的最大示例数 | | `COMPACT_THRESHOLD` | `0.6` | 自动压缩触发器（0.6 = 如果银行 > 预算的 60%，则压缩） | | `BANK_FILE_MAX_SIZE` | `15360` | 每个银行文件的最大大小（字节，15 KB）。以上 = 压缩候选 | | `RESPONSE_MAX_BYTES` | `524288` | 非 MCP 响应正文的最大大小，截断前 | | `API_TOOL_MAX_BODY_BYTES` | `1048576` | `/api/tool` 接受的最大请求正文大小 | | `ADMIN_AUDIT_RING_SIZE` | `500` | 每个实例的内存控制台/身份验证审计容量；启动时验证 `1..500` | --- ## ▶️ 入门指南 这是可以直接粘贴的本地路径。它使用生成的本地机密、MinIO 和初始评估的启动凭证。在 `mid` 之前，请在 `.env` 中配置提供商基准 URL、密钥、确切的聊天模型 ID、确切的嵌入模型 ID 和返回的向量维度；它必须公开兼容的 `/chat/completions` 和 `/embeddings` 端点。`short` 不需要 LLM。嵌入式 `long` 运行时随栈启动，并在其首次写入时自动绑定，但长摄入和语义查询也使用该提供商。 ```bash # 1. 克隆仓库 git clone https://github.com/Lesur-ai/hivemind.git cd hivemind # 2. 创建随机本地凭证并安装锁定的 CLI 环境 python scripts/configure_dev_env.py uv sync --locked --dev # 3. 启动 WAF + Hivemind + MinIO + 嵌入式长运行时 docker compose --profile dev up --build -d --wait docker compose ps docker compose logs hivemind --tail 50 # 4. 将 CLI 指向 WAF 并验证生成的启动凭证 export MCP_URL=http://localhost:8080 export MCP_TOKEN="$(sed -n 's/^ADMIN_BOOTSTRAP_KEY=//p' .env)" uv run python scripts/mcp_cli.py health --json uv run python scripts/mcp_cli.py whoami --json # 5. 从附带的标准规则创建演示空间 uv run python scripts/mcp_cli.py space create hivemind-demo \ --description "快速入门演示空间" \ --rules-file RULES/live-mem.standard.memory.bank.md # 6. short — 编写和读取真实笔记 uv run python scripts/mcp_cli.py live note hivemind-demo observation "hello short" uv run python scripts/mcp_cli.py live read hivemind-demo # 7. mid — 需要在 .env 中配置完整的 LLMAAS 提供商/模型 # 这立即返回，状态为 running|queued 和一个 job_id。 uv run python scripts/mcp_cli.py bank consolidate hivemind-demo --json ``` 在此停止。明确要求操作员进行延迟的状态检查；例行代理必须返回而不进行轮询。粘贴返回的 `job_id` 仅当您故意检查时： ```bash JOB_ID="粘贴返回的作业 ID" uv run python scripts/mcp_cli.py bank consolidation-status "$JOB_ID" --json ``` 仅当响应报告终端顶级状态为 `"status": "succeeded"` 时继续。 如果它仍然报告 `running` 或 `queued`，请停止并在故意选择的时间后再次检查 — 不要自动化循环。`failed`、`not_found` 或错误响应是快速入门失败：诊断后再读取银行或推送长内存。 ```bash # 8. 验证完成的 mid 结果 uv run python scripts/mcp_cli.py bank read-all hivemind-demo --json # 9. long — 还需要配置的嵌入模型/维度 uv run python scripts/mcp_cli.py graph push hivemind-demo --json uv run python scripts/mcp_cli.py graph status hivemind-demo --json uv run python scripts/mcp_cli.py graph query hivemind-demo "hello" --json # 在评估结束后停止向子进程公开启动密钥。 unset MCP_TOKEN ``` 对于任何持久部署，请铸造一个专用的管理器和一个专用的 `read,write` 令牌用于每个代理，将每个代理令牌邀请到空间，并停止使用启动凭证。确切的程序在 [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md#quickstart-dev) 中。 历史上的 `live_*` / `bank_*` / `graph_*` 工具名称仍然可作为兼容别名调用 — 请参阅 [兼容别名](#compatibility-aliases)。 请参阅 [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) 和 [`docs/MIGRATION_LIVE_GRAPH_TO_HIVEMIND.md`](docs/MIGRATION_LIVE_GRAPH_TO_HIVEMIND.md) 以获取完整的操作员详细信息。 --- ## 🔧 MCP 工具 Hivemind 通过 MCP 协议（可流式 HTTP）公开规范的工具集，记录在 [tests/fixtures/tool_surface.json](tests/fixtures/tool_surface.json) 中（**61 个注册名称 = 48 个直接注册 + 13 个层别名**，由工具表面夹具跟踪）— 历史工具 + `short_*`/`mid_*`/`long_*` 层别名（两个集合都可调用）。 `short`/`mid`/`long` 层带有公共语法；`space_*`、`token_*`、`system_*`、`backup_*` 和 `admin_*` 是 **跨切割** 的，并保留其名称（无层归属）。有 35 个直接无别名工具；13 个层别名保持不变。请参阅 [`docs/TOOL_MAPPING.md`](docs/TOOL_MAPPING.md) 中的规范工具映射和 [`docs/MCP_TOOLS_SPEC.md`](docs/MCP_TOOLS_SPEC.md) 中的完整规范，包括废弃预期。 ### 系统 | 工具 | 参数 | 描述 | | --------------- | ---------- | ------------------------------------------------------ | | `system_health` | — | 健康状态（S3、LLM、空间数量） | | `system_whoami` | — | 当前令牌身份（名称、权限、空间） | | `system_about` | — | 服务身份（版本、工具、功能） | ### 空间 | 工具 | 参数 | 描述 | | -------------------- | -------------------------------------------- | --------------------------------------------------------- | | `space_create` | `space_id`、`description`、`rules?`、`owner?` | **管理**：创建空间； `_meta.json` 提交最后，持久化管理器自动授予 | | `space_update` | `space_id`、`description?`、`owner?` | 更新描述和/或所有者 | | `space_update_rules` | `space_id`、`rules` | 更新空间规则（管理） | | `space_list` | — | 列出当前令牌可访问的空间 | | `space_info` | `space_id` | 详细资讯（笔记、银行、合并） | | `space_rules` | `space_id` | 读取空间规则 | | `space_summary` | `space_id` | 完整摘要：规则 + 银行 + 统计（代理启动） | | `space_export` | `space_id` | base64 中的 tar.gz 导出 | | `space_delete` | `space_id`、`confirm`、`unsafe_recovery?` | 删除空间（⚠️ 不可逆转，管理；高级标志显式允许可分类的共享/不安全 Hivemind 恢复，从未损坏状态） | | `space_invite_token` | `space_id`、`token_hash` | **管理 + 空间访问**：确切的规范哈希，仅添加/幂等；不是 Project Mesh 注册 | ### 令牌 | 工具 | 参数 | 描述 | | --- | --- | --- | | `token_create` | `name`、`permissions`、`expires_in_days?`、`email?` | **管理**：创建 `read`、`read,write` 或 `read,write,manage` 令牌，`space_ids: []`；显示一次密钥 + 完整哈希 | `manage` 是一个传递性、高信任的配置角色。任何管理器都可以全局创建新空间（即使允许列表为空），并且可以创建进一步的管理者。允许列表限制现有空间的访问/邀请，而不是 `space_create`。全局令牌列表/更新/撤销/删除/清除仍然仅限管理员。 空间身份重复使用是关闭失败的：任何持久作用域引用缺失或部分准备的 ID — 包括管理员、创建管理器、撤销或过期的令牌 — 阻止 `space_create`，直到显式管理员清理。`space_delete` 删除/探测有效载体并最后移除 `_meta.json`，但操作员必须静止所有同空间突变和后台作业；其生命周期锁不是通用写入器屏障。 部分删除是恢复所需的，从未成功。 ### `short` — 实时笔记（历史 `live_*`） | 工具 | 参数 | 描述 | | ------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `live_note` | `space_id`、`category`、`content`、`tags?` | 编写时间戳笔记（代理 = 令牌名称）。类别：`observation`、`decision`、`todo`、`insight`、`question`、`progress`、`issue` | | `live_read` | `space_id`、`limit?`、`category?`、`agent?` | 读取实时笔记（可选过滤器） | | `live_search` | `space_id`、`query`、`limit?` | 笔记中的全文搜索 | > **令牌 = 代理身份。** 代理名称从身份验证令牌派生；`short` 类别集是固定的。两者都原样保留到 `short_*` 语法。 ### `mid` — 内存银行（历史 `bank_*`） | 工具 | 参数 | 描述 | | ------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------- | | `bank_read` | `space_id`、`filename` | 读取银行文件（支持子文件夹：`personaProfiles/buyer.md`） | | `bank_read_all` | `space_id` | 读取整个银行（代理启动） | | `bank_list` | `space_id` | 列出银行文件和相对路径（无内容） | | `bank_consolidate` | `space_id`、`agent?` | 异步启用 LLM 合并。省略/null `agent` = 调用者；显式 `agent=""` = 所有代理（管理/管理员）。调用一次；不要观看/轮询，除非显式请求 | | `bank_consolidation_status` | `job_id` | `bank_consolidate` 返回的作业手动状态检查 | | `bank_consolidation_queues` | `space_ids?` | 按空间读取合并通道的只读摘要 | | `bank_stale_spaces` | `min_notes?=5`、`min_age_days?=5`、`space_ids?` | 列出 ≥N 个未合并笔记，其最旧的是 ≥D 天旧（监督） | | `bank_compact` | `space_id`、`dry_run?` | 通过 LLM 合并压缩超大银行文件。`dry_run=True` 默认（**管理**） | | `bank_repair` | `space_id`、`dry_run?` | 修理损坏的文件名（Unicode，寄生前缀）。`dry_run=True` 默认（**管理**） | | `bank_write` | `space_id`、`filename`、`content` | 直接写入/替换银行文件 — 跳过 LLM 合并（**管理**） | | `bank_delete` | `space_id`、`filename`、`confirm?=False` | 删除银行文件和 Unicode 副本（**管理**，不可逆转）；`confirm=True` 需确认 | > 五个操作/监督工具（`bank_consolidation_status`、`bank_consolidation_queues`、`bank_stale_spaces`、`bank_repair`、`bank_compact`） **保留其历史名称** — 它们是内部/操作，不是公共 `mid_*` CRUD 参见 `TOOL_MAPPING.md`。参见 `TOOL_MAPPING.md` 中的规范映射和 [`docs/MCP_TOOLS_SPEC.md`](docs/MCP_TOOLS_SPEC.md)。 ### `long` — 知识图谱 / 本体（历史 `graph_*`） | 工具 | 参数 | 描述 | | ------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `graph_connect` | `space_id`, `url`, `token`, `memory_id`, `ontology?` | 将 `long` 级别的引擎连接到一个空间。测试连接，创建知识内存（如果需要）。目标别名 `long_connect`。 | | `graph_push` | `space_id`, `include_volatile?` | 将规范的 `mid` 内容摄入 `long` 知识图谱。删除 + 重新摄入，孤儿清理。**不是常规的双向通道** — 见下。 | | `graph_status` | `space_id`, `include_graph?` | 连接状态 + 图谱统计（文档、实体、关系、顶部实体）；可选地包括图谱详细信息 | | `graph_disconnect` | `space_id`, `use_embedded?` | 断开 `long` 级别的引擎，或用嵌入式/本地运行时替换遗留的重载（当 `use_embedded=true` 时）（`manage`）。图谱数据保持不变。目标别名 `long_disconnect`。 | | `long_ingest` | `space_id`, `documents`, `mode?`, `include_volatile?` | 计划规范文档的摄入；`apply` 在 V1 中仍延迟。直接工具，无 `graph_*` 对应工具。 | | `long_query` | `space_id`, `query`, `limit?` | 对派生的 long 引擎进行只读语义查询。直接工具，无 `graph_*` 对应工具。 | ### 备份 | 工具 | 参数 | 描述 | | ----------------- | -------------------------- | ---------------------------------------- | | `backup_create` | `space_id`, `description?` | 在 S3 上创建完整快照 | | `backup_list` | `space_id?` | 列出可用备份 | | `backup_restore` | `backup_id`, `confirm?=False`, `unsafe_recovery?=False` | **manage**；`confirm=True` 始终必填。通常空间必须不存在。在共享/不安全的 Hivemind 空间上，还需额外传递 `unsafe_recovery=True` 以进行显式的前向恢复；仍拒绝损坏。 | | `backup_download` | `backup_id` | 下载为 tar.gz base64 | | `backup_delete` | `backup_id`, `confirm?=False` | **manage**；仅当 `confirm=True` 时不可逆地删除备份 | ### 管理 | 工具 | 参数 | 描述 | | -------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `admin_audit_recent` | `limit?=50` | 仅限管理员，最新的控制台/身份验证事件来自每个实例的内存环（`1..500`）；仅限元数据和参数键，不包括值或空间 ID | | `admin_create_token` | `name`, `permissions`, `space_ids?`, `expires_in_days?`, `email?` | 管理员/引导全局创建；初始范围仅适用于非管理员目标，管理员目标持续为空；明文 + 完整哈希一起显示一次 | | `admin_list_tokens` | — | 列出活动令牌 | | `admin_revoke_token` | `token_hash` | 吊销令牌（使其无法使用） | | `admin_delete_token` | `token_hash` | 物理删除令牌（⚠️ 不可逆转） | | `admin_purge_tokens` | `revoked_only?`, `confirm?=False` | 批量清理：默认仅限已吊销；清除所有令牌需要显式确认 | | `admin_update_token` | `token_hash`, `permissions?`, `email?`, `space_ids?` or `space_ids_add?` / `space_ids_remove?` | 单令牌更新；替换和增量范围模式是互斥的；提升清除范围，下降启动为空 | | `admin_bulk_update_tokens` | `names?`, `name_contains?`, `has_space?`, `permissions?`, `email?`, `space_ids_add?`, `space_ids_remove?`, `include_revoked?` | 过滤批量更新；范围更改仅为添加/删除增量 | | `admin_gc_notes` | `space_id?`, `max_age_days?`, `confirm?`, `delete_only?`, `expected_eligible_set_token?` | 垃圾收集器：干运行、合并或条件删除孤儿笔记 | GC 写操作路由失败关闭：每个候选空间必须解析为 `DIRECT_LOCAL` 才能发出通知、合并或删除。删除是显式的两步操作：首先运行一次干运行并保留其不透明的 `eligible_set_token`，然后发送该值作为 `expected_eligible_set_token` 并设置 `confirm=true, delete_only=true`。更改的精确键集被拒绝且无删除；部分操作返回诚实的已处理/已删除/失败计数，而不是报告完整的成功。 ### 兼容别名 规范的 `short_*` / `mid_*` / `long_*` 级别别名（由 [`tests/fixtures/tool_surface.json`](tests/fixtures/tool_surface.json) 跟踪的精确集合和 [`docs/TOOL_MAPPING.md`](docs/TOOL_MAPPING.md) 文档）**已注册并可调用** — 是相同的函数薄注册，从不分歧的副本。历史名称 `live_*` / `bank_*` / `graph_*` 是**无限期支持的兼容别名**：无删除日期，无定时器。使用历史名称的调用者继续工作，无需更改。 新集成应首选 `short_*` / `mid_*` / `long_*` — 它们是推荐的语法。任何未来移除都**受 ADR 管辖（ADR-0005）**：B 阶段软弃用至少一个已发布的版本后必须先于 C 阶段移除，并且没有移除日期或版本号自动触发。对于完整的策略，请参见 [`docs/MCP_TOOLS_SPEC.md#compatibility--deprecation-expectations`](docs/MCP_TOOLS_SPEC.md#compatibility--deprecation-expectations)。 - 政策（ADR-0005）：[`docs/MCP_TOOLS_SPEC.md#compatibility--deprecation-expectations`](docs/MCP_TOOLS_SPEC.md#compatibility--deprecation-expectations) - 按工具映射：[`docs/TOOL_MAPPING.md`](docs/TOOL_MAPPING.md) - 语法和级别语义（ADR-0002）：[`docs/TOOL_MAPPING.md#invariants`](docs/TOOL_MAPPING.md#invariants) --- ## 🌐 Long 级别 — 本体 / 知识图谱 `long` 级别是**本体 / 知识图谱引擎**，内部绑定到一个空间。它从规范内容中提取类型化的实体和关系，并将它们存储为可导航的知识图谱以进行**联想回忆** — “理解”时刻。 > ### 权限边界（不可协商） > > `long` 级别是**派生的语义投影**。它**永远不是**提交有效性、回滚、审计、墓碑、时间戳或恢复的源，并且它位于**提交路径之外**。 `mid`（合并的银行）和存储库的规范文件保持权威；`long` 图谱本地化和关联，但不确认。 > > 此边界是协议派生的。请参见 [公共级别和权限映射](docs/TOOL_MAPPING.md#invariants) （ADR-0002 / ADR-0004）。 ### `graph_push` 是摄入，不是常规通道 `graph_push` 是将规范的 `mid` 内容**单向摄入**到 `long` 图谱 — 不是常规的双向同步。每个循环推送整个银行会向图谱教导瞬时内容，而后续压缩会使内容过时。常规流程应摄入**稳定、规范的文档**，并具有稳定的 `source_path` 键；易失性焦点文件（例如 `activeContext.md`、`progress.md`）**永远不应**进入 `long` 图谱。 `graph_push` 仍可用于一次性引导和显式调试/迁移。 ### 工作流程 ``` 1. bank_consolidate(space_id) └─ 构建规范的 mid 银行（调用一次；除非询问，否则不轮询） 2. graph_push(space_id) ├─ 第一次推送自动将空间绑定到嵌入式 long 运行时 │ （从 space_id 推导出 memory_id，本体“general” — 无 graph_connect） ├─ 对于每个修改的规范文件：删除 + 重新摄入（图谱重新计算） ├─ 清理已删除的文档（移除孤儿实体） └─ 更新摄入指标（last_push、push_count） 3. graph_status(space_id) └─ 统计：实体、关系、顶部实体、文档... ``` 高级重载/诊断仅限：`graph_connect(space_id, url, token, memory_id, ontology?)`（规范：`long_connect`）将空间重新指向外部引擎或选择非默认本体 — 永远不是例行工作流的必需步骤。 每次推送都是该文件的**完整刷新**：现有文件被删除，然后重新摄入，以便引擎重新计算本体引导的实体和类型化关系，并使用最新内容。 ### 可用本体 | 本体 | 用途 | | ------------------- | ------------------------------------------ | | `general` （默认） | 多功能：FAQ、规格、认证 | | `legal` | 法律文件、合同 | | `cloud` | 云基础设施、产品说明书 | | `managed-services` | 托管服务、外包 | | `presales` | 销售前、RFP/RFI、提案 | --- ## 🖥️ Web 界面 > **注意：** 这里描述的 `/live` 实时查看器是**继承的**可视化界面，与导入的引擎捆绑在一起 — 它在此处记录，因为它随引擎一起提供，其未来是一个单独的可观察性决策。下面重建的 `/admin` 操作员控制台采用了 Hivemind 设计语言，并且**是**目标产品界面。 Hivemind 在 `/live` 上公开了一个 Web 界面，用于实时可视化内存空间。 ### 访问 ``` http://localhost:8080/live ``` ### 功能 | 区域 | 内容 | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **仪表盘** （左侧） | 空间信息、合并（日期 + 计数器）、short/mid 统计数据、彩色代理、类别及其百分比、Markdown 规则、long 级别状态 | | **实时时间线** （右上） | `short` 笔记按日期分组（今日/昨日/日期）、带有代理 + 类别 + Markdown 的卡片 | | **银行查看器** （右下） | 合并的 `mid` 文件选项卡、Markdown 渲染 | ### 智能自动刷新 - 可配置：3s / 5s / 10s / 30s / 手动 - **防闪烁**：仅当数据更改时才重新渲染 DOM - 状态点和上次刷新时间戳 - 空间选择 → 立即加载 ### REST API （5 个端点） | 端点 | 描述 | | ------------------------------- | -------------------------------------------------------- | | `GET /api/spaces` | 空间列表 | | `GET /api/space/{id}` | 完整信息（元数据 + 规则 + 统计数据 + long 级别） | | `GET /api/live/{id}` | `short` 笔记（过滤器：`?agent=`、`?category=`、`?limit=`） | | `GET /api/bank/{id}` | `mid` 银行文件列表 | | `GET /api/bank/{id}/{filename}` | `mid` 银行文件内容 | `/api/*` 端点需要 Bearer Token。`/live` 页面和 `/static/*` 文件是公共的。 ### 管理控制台 (`/admin`) 哈希路由的管理控制台位于 `/admin`，并使用身份验证的 `/api/tool` 代理进行其操作工作流： ``` http://localhost:8080/admin ``` | 部分 | 功能 | | --- | --- | | **仪表盘** | 健康状态（S3 / LLM / 版本 / 正常运行时间）、身份栏、空间和令牌计数、合并队列/通道信号 | | **空间** | 空间索引，带有 short/mid/long 计数和状态标签；进入空间详情的入口（仅限创建/管理员显示） | | **空间详情** | 统一的每个空间的内存级别选择器视图：`short` 笔记、`mid` 银行文件、`long` 派生知识、规则、访问摘要和每个空间的安全操作（创建/删除备份、删除空间） | | **合并** | 合并通道/作业（排队/运行/成功/失败）和过时银行规划过滤器 | | **审计** | 来自 `admin_audit_recent` 的最近控制台/身份验证事件（仅限管理员，此实例，内存中自重启） | | **访问** | 令牌和空间访问管理：创建（管理器安全与管理员）、按确切哈希邀请、更新/吊销/删除/清除并键入确认 | | **操作员工具** | 备份（创建/恢复/删除）和维护（压缩、修复、GC、清除）需明确确认 | - **身份验证**：需要有效的令牌（与 `/live` 相同），通过 HttpOnly Cookie 进行会话 - **CSP 安全**：零内联处理程序，均通过 `data-action` + 事件委托 - **Long 级别是派生的，永远不是权威的**：永远不是提交、回滚、审计、成员资格或恢复的源 — 空间详情面板渲染其真实状态（或诚实的失败），永远不是中立的“禁用”。 - **单租户**：令牌的 `space_id` 列表是允许列表，而不是租户边界（Hivemind OSS 是单租户的）。 - **诚实的审计范围**：审计视图是尽力而为的，不是持久的或完整的；它仅记录参数键（永远不包括值或空间 ID），MCP `/mcp` 工具调用未列出 --- ## 🔌 MCP 集成 > 📖 **完整指南**：请参阅每个客户端集成指南以获取逐步配置（服务器配置、自定义说明、工作流程、多代理、故障排除）： [`CLAUDE_CODE_INTEGRATION.md`](CLAUDE_CODE_INTEGRATION.md)、 [`CODEX_INTEGRATION.md`](CODEX_INTEGRATION.md)。 兼容性接口包含 **61 个已注册且直接可调用的名称**（48 个直接注册 + 13 个历史/规范别名），但常规 `tools/list` 发现是故意紧凑且具有权限意识的：**17 / 20 / 24 / 24** 个规范代理工具用于读取/写入/管理/管理员。操作员工具、历史别名和未来 Mesh HTTP 操作未在其中宣传；确切名称调用仍可访问相同的处理程序及其新鲜的调用时间授权保护。权限或范围更改返回 `mcp_reconnect_required=true`，当客户端可能需要刷新缓存发现时。参见生成的 [MCP 暴露清单](docs/TOOL_EXPOSURE.md)。 ### 使用 Claude Desktop Claude Desktop 的远程连接器 UI 目前期望支持 OAuth，不接受 Hivemind 的静态 Bearer Header。Anthropic 也不为 `claude_desktop_config.json` 中的 Bearer Header 文档提供安全的环境变量扩展。在其中一个合同更改之前，请使用 Claude Code 进行 Bearer 身份验证访问；不要将令牌复制到存储库中。请参阅 [精确的 Desktop 边界](CLAUDE_CODE_INTEGRATION.md#-with-claude-desktop)。 ### 通过 Python（MCP 客户端） ```python import os from mcp.client.streamable_http import streamablehttp_client from mcp import ClientSession async def example(): headers = {"Authorization": f"Bearer {os.environ['HIVEMIND_TOKEN']}"} async with streamablehttp_client("http://localhost:8080/mcp", headers=headers) as (r, w, _): async with ClientSession(r, w) as session: await session.initialize() # 加载所有 mid 级别上下文 result = await session.call_tool("mid_read_all", { "space_id": "my-project" }) # 写入短笔记 await session.call_tool("short_note", { "space_id": "my-project", "category": "observation", "content": "Build passing in CI" }) ``` --- ## 💻 CLI 和 Shell ### CLI 安装 ```bash uv sync --locked --dev export MCP_URL=http://localhost:8080 export MCP_TOKEN=your_token ``` ### CLI 命令（点击） ```bash uv run python scripts/mcp_cli.py health uv run python scripts/mcp_cli.py whoami # 当前令牌身份 uv run python scripts/mcp_cli.py about uv run python scripts/mcp_cli.py space list uv run python scripts/mcp_cli.py space create my-project \ --description "我的项目" \ --rules-file RULES/live-mem.standard.memory.bank.md uv run python scripts/mcp_cli.py token create agent-cline -p read,write # 管理/管理员调用者；初始未限定范围 uv run python scripts/mcp_cli.py space invite my-project sha256:<64-小写十六进制> uv run python scripts/mcp_cli.py live note my-project observation "构建成功" # 简短 uv run python scripts/mcp_cli.py bank consolidate my-project --json # 异步中间确认；停止此处 ``` 对于此显式操作员演练，复制返回的 `job_id` 并执行延迟检查（绝不自动轮询）： ```bash uv run python scripts/mcp_cli.py bank consolidation-status <job_id> --json ``` 仅在检查报告终端 `"status": "succeeded"` 后运行剩余命令；`running`、`queued`、`failed`、`not_found` 或错误是 bank 读取或长推送前的硬停止。 ```bash uv run python scripts/mcp_cli.py bank read-all my-project # 中间 uv run python scripts/mcp_cli.py graph push my-project # 长 — 第一次推送自动绑定到嵌入式运行时 uv run python scripts/mcp_cli.py graph status my-project # 长 — 连接 + 图表统计 uv run python scripts/mcp_cli.py graph query my-project "构建" --json # 高级覆盖/诊断仅（外部引擎，非默认本体）： uv run python scripts/mcp_cli.py graph connect my-project URL TOKEN MEM-ID -o general uv run python scripts/mcp_cli.py graph disconnect my-project # 维护：验证/配置嵌入式运行时，然后替换旧版 # 不删除远程图表数据或摄入文档。 uv run python scripts/mcp_cli.py graph use-local my-project ``` ### 交互式 Shell ```bash uv run python scripts/mcp_cli.py shell ``` 自动补全、历史记录、Rich 显示。有关完整参考，请参见 [scripts/README.md](scripts/README.md)。 --- ## 🧪 测试 具有 `--suite` 可选套件的统一测试脚本： ```bash docker compose --profile dev up -d --wait # 先决条件 # 所有套件 uv run python scripts/test_recette.py --url http://localhost:8080 # 单个套件 uv run python scripts/test_recette.py --suite recette # 代理管道 uv run python scripts/test_recette.py --suite isolation # 空间范围隔离 uv run python scripts/test_recette.py --suite qualite # MCP 工具回归 # 长层套件 — 锻炼显式图表连接覆盖路径 # 针对操作员提供的长引擎；如果没有 # --graph-url / --graph-token，则跳过。标称嵌入式自动绑定路径需要 # 无标志（参见快速入门：long_push 自身绑定）。 uv run python scripts/test_recette.py --suite graph \ --graph-url http://host.docker.internal:8080 \ --graph-token your_token # 列出可用套件 uv run python scripts/test_recette.py --list ``` | 套件 | 描述 | | ----------- | ------------------------------------------------------------------------------------ | | `recette` | 完整管道：令牌 → `short` 笔记 → LLM 合并 → `mid` 银行 | | `isolation` | 编写者供应拒绝，管理器创建/自动授予/邀请，跨空间隔离，备份过滤 | | `qualite` | MCP 工具回归测试：系统，管理员，空间，短，中，备份，GC | | `graph` | `long` 层显式 `graph_connect` 覆盖路径：连接，推送，状态，断开（如果没有 `--graph-url`/`--graph-token` 则跳过） | 导入的 Hivemind 协议套件也在 `pytest` 下运行： ```bash uv run pytest tests/test_hivemind_state.py tests/test_hivemind_peer.py uv run pytest tests ``` --- ## 🔒 安全 ### 身份验证 - **Bearer Token** 在所有 MCP 请求上必填 - **Bootstrap key** 用于创建第一个管理员令牌 - **SHA-256 Tokens** 存储在 S3 上（绝不以明文存储） - **4 级权限层次结构**：admin ⊃ manage ⊃ write ⊃ read - **空间范围**：每个令牌的 `space_ids` 允许列表是 **唯一** 隔离原语（单租户 - 参见 [Hivemind 不声称的内容（V1）](#-hivemind-不声称的内容-v1)） - **写入边界**：`write` 只能变异允许列表中的空间；它不能创建空间/令牌或扩大访问权限 - **管理器边界**：`manage` 可以创建任意新的空间并委托非管理员管理器可传递；现有空间邀请仍受调用者的允许列表限制（ADR-0022） ### WAF（Caddy + Coraza） - **OWASP CRS**：SQL/XSS 注入、路径遍历、SSRF - **速率限制**：600 MCP HTTP 事件/分钟/IP（可流式 HTTP） - **网格边缘**：默认启用，120 个对等请求/分钟和原始 256 KiB 正文上限，然后是 Coraza；Ed25519 身份验证仍在应用层 - **自动 TLS**：生产环境中的 Let's Encrypt（`SITE_ADDRESS=domain.com`） - **非根容器**：`mcp` 用户 > 几个继承的安全验收测试假设了一个受信任的单个操作员。 > 它们在公共威胁模型合同中被重述为明确的部署人员责任，[`docs/SECURITY.md`](docs/SECURITY.md)，在 > [OSS 单租户范围](docs/EXTENSION_POINTS.md)（ADR-0003）下。 --- ## 📂 项目结构 ``` hivemind/ ├── src/live_mem/ # 源代码（MCP 工具 + Web 接口） │ ├── server.py # FastMCP 服务器 + 中间件 │ ├── config.py # pydantic-settings 配置 │ ├── auth/ # 身份验证（check_access = 允许列表隔离） │ ├── static/ # /live（继承的查看器）+ /admin（操作员控制台） │ ├── core/ # 业务服务 │ │ ├── storage.py # S3 持久存储 │ │ ├── space.py # 内存空间 CRUD │ │ ├── live.py # 短笔记（仅追加） │ │ ├── consolidator.py # 中间 LLM 合并管道 │ │ ├── graph_bridge.py # 长层摄入（派生投影） │ │ ├── tokens.py # SHA-256 令牌管理 │ │ ├── backup.py # S3 快照 │ │ └── ... │ └── tools/ # MCP 工具（8 个模块） │ ├── system.py # system_*（跨切） │ ├── space.py # space_* （跨切） │ ├── access.py # token_create + space_invite_token （管理） │ ├── live.py # live_* → short_* │ ├── bank.py # bank_* → mid_* │ ├── graph.py # graph_* → long_* │ ├── backup.py # backup_*（跨切） │ └── admin.py # admin_* （跨切） ├── scripts/ # CLI + Shell + 测试 ├── waf/ # Caddy + Coraza WAF ├── docs/ # 部署、安全、迁移、协议/工具文档 ├── assets/brand/ # Logo 资产（许可证 + 哈希出处） ├── docker-compose.yml ├── Dockerfile ├── pyproject.toml └── uv.lock ``` > **注意：** 源代码包和几个模块名称仍保留导入的 > `live_mem` / `graph_bridge` 身份。公共语法是附加层； > 源代码重命名是后续工作，而不是行为更改。 --- ## 🔍 故障排除 ### 服务未启动 ```bash docker compose logs hivemind --tail 50 docker compose logs waf --tail 20 ``` ### 401 未授权 - 检查您的令牌：`Authorization: Bearer YOUR_TOKEN` - Bootstrap key 不是令牌 — 首先使用 `admin_create_token` 创建令牌 ### 合并失败 - 在 `.env` 中检查 LLM 凭证 - 默认超时为 600s — 如有需要，增加 `CONSOLIDATION_TIMEOUT` - `bank_consolidate` 返回异步作业确认（`running` 或 `queued`） 带有 `next_action="return_to_user_without_polling"`；调用一次，不要 轮询，除非明确请求 - `bank_consolidation_status(job_id)` 仅用于手动状态检查 --- ## 🤝 贡献 开发 **通过 GitHub** 进行 — 问题、拉取请求和代码审查。公共架构合同位于 [`docs/ARCHITECTURE_CONTRACTS.md`](docs/ARCHITECTURE_CONTRACTS.md)、 [`docs/MCP_TOOLS_SPEC.md`](docs/MCP_TOOLS_SPEC.md) 和 [`docs/PROJECT_MESH.md`](docs/PROJECT_MESH.md)。阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 在打开问题或拉取请求之前。 --- ## 🗺️ 文档地图 英语是规范性合同；法语指南在不要求逐行一致的情况下保留相同的关键行为。 | 需要 | 从这里开始 | | --- | --- | | 评估或安装 Hivemind | 本 README，然后是 [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) | | 连接代理 | [`docs/AGENT_MEMORY_SETUP.md`](docs/AGENT_MEMORY_SETUP.md)，然后是 [Codex](CODEX_INTEGRATION.md) 或 [Claude Code](CLAUDE_CODE_INTEGRATION.md) 指南 | | 了解工具和权限 | [`docs/MCP_TOOLS_SPEC.md`](docs/MCP_TOOLS_SPEC.md)、[`docs/TOOL_EXPOSURE.md`](docs/TOOL_EXPOSURE.md) 和 [`scripts/README.md`](scripts/README.md) | | 了解架构和边界 | [`docs/ARCHITECTURE_CONTRACTS.md`](docs/ARCHITECTURE_CONTRACTS.md)、[`docs/POSITIONING.md`](docs/POSITIONING.md) 和 [`docs/PROJECT_MESH.md`](docs/PROJECT_MESH.md) | | 安全、备份、恢复或迁移 | [`docs/SECURITY.md`](docs/SECURITY.md)、[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) 和 [`docs/MIGRATION_LIVE_GRAPH_TO_HIVEMIND.md`](docs/MIGRATION_LIVE_GRAPH_TO_HIVEMIND.md) | | 故障排除或求助 | [`FAQ.md`](FAQ.md)、[`SUPPORT.md`](SUPPORT.md) 和 [`SECURITY.md`](SECURITY.md) 用于机密漏洞报告 | | 贡献 | [`CONTRIBUTING.md`](CONTRIBUTING.md)、[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) 和 [`CHANGELOG.md`](CHANGELOG.md) | --- ## 📄 许可证 Apache License 2.0 --- ## 👤 起源 Hivemind 建立在 **Christophe Lesur** 最初开发的引擎之上。该 项目在 Apache-2.0 下发布。 > 公共版本身份记录在 [`VERSION`](VERSION) 和公共 [`CHANGELOG.md`](CHANGELOG.md) 中； > 项目以 `hivemind` 的形式发布在 [github.com/Lesur-ai/hivemind](https://github.com/Lesur-ai/hivemind) > 上，由存储库 `VERSION` 文件（SemVer）版本控制。 *Hivemind — 集体智能体的开放内存层。 `short · mid · long`.*