# https://github.com/Hebbrix/hebbrix-mcp 项目说明书

生成时间：2026-07-30 03:45:12 UTC

## 目录

- [项目概述与安装配置](#page-overview)
- [记忆与知识图谱工具](#page-memory-graph)
- [推理与账户工具](#page-reasoning-account)
- [架构、部署与故障排查](#page-architecture-ops)

<a id='page-overview'></a>

## 项目概述与安装配置

### 相关页面

相关主题：[架构、部署与故障排查](#page-architecture-ops)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Hebbrix/hebbrix-mcp/blob/main/README.md)
- [pyproject.toml](https://github.com/Hebbrix/hebbrix-mcp/blob/main/pyproject.toml)
- [hebbrix_mcp/__init__.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/__init__.py)
- [.claude-plugin/plugin.json](https://github.com/Hebbrix/hebbrix-mcp/blob/main/.claude-plugin/plugin.json)
- [.claude-plugin/marketplace.json](https://github.com/Hebbrix/hebbrix-mcp/blob/main/.claude-plugin/marketplace.json)
</details>

# 项目概述与安装配置

## 项目定位与目标

hebbrix-mcp 是一个基于 Model Context Protocol（MCP）的服务端实现，作为外部工具与 AI 助手之间的桥梁，专注于向 LLM 暴露结构化的记忆与检索能力。该项目以 Python 包形式发布，最新稳定版本为 **v0.3.20**，主题为 `hebbrix_import + usage on material change (E2E review)`，反映了社区近期关注的端到端审阅与导入流程改进。`资料来源：[README.md:1-40]()`

项目的核心目标是为 LLM 提供以下能力：
- **记忆持久化**：跨会话保存知识条目与索引
- **GraphRAG 检索**：基于图谱的上下文问答（`hebbrix_ask`）
- **置信度报告**：在出现约束冲突时输出 `do_not_act` 信号
- **批量操作与导出**：支持知识库的批处理、导出与 `mark_used` 流程

`资料来源：[hebbrix_mcp/__init__.py:1-30]()`

## 包结构与依赖

| 组件 | 说明 |
|---|---|
| 包名 | `hebbrix-mcp` |
| Python 版本要求 | `>=3.10` |
| 协议 | MCP (Model Context Protocol) |
| 通信方式 | stdio / HTTP 共享连接池 |
| 关键工具 | `hebbrix_import`, `hebbrix_ask`, `hebbrix_confidence`, `hebbrix_search` |

`资料来源：[pyproject.toml:1-40]()`

## 安装方式

### 通过 pip 安装

```bash
pip install hebbrix-mcp
```

该命令会从 PyPI 拉取最新稳定版本（v0.3.20），并自动安装所需依赖。`资料来源：[pyproject.toml:10-30]()`

### 作为 Claude 插件安装

仓库同时提供 `.claude-plugin/` 目录下的清单文件，可通过 Claude 插件市场加载：

```bash
/plugin install hebbrix-mcp
```

插件清单文件定义了名称、版本、入口命令及描述信息： `资料来源：[.claude-plugin/plugin.json:1-20]()`

市场清单中描述项目为一个轻量级 MCP 服务，提供记忆管理、GraphRAG 检索与置信度评估。`资料来源：[.claude-plugin/marketplace.json:1-20]()`

## 配置与启动

MCP 客户端（如 Claude Desktop）需要在配置文件中声明 hebbrix-mcp 服务端：

```json
{
  "mcpServers": {
    "hebbrix": {
      "command": "python",
      "args": ["-m", "hebbrix_mcp"],
      "env": {
        "HEBBRIX_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

启动入口位于 `hebbrix_mcp/__init__.py`，注册所有可被 LLM 调用的工具与资源。`资料来源：[hebbrix_mcp/__init__.py:20-50]()`

## 版本演进与社区关注点

自 v0.3.11 起，社区持续关注以下议题：

- **缓存诚实性**：v0.3.17 提出 search cache 必须避免覆盖层凌驾真实命中之上
- **WAF 阻断澄清**：v0.3.18 增强了 prompt-injection 防护与 WAF-block 的输出清晰度
- **GraphRAG 增强**：v0.3.16 引入 `hebbrix_ask`，并加入批量操作与 `mark_used`
- **置信度冲突**：v0.3.15 在 `hebbrix_confidence` 中暴露 `do_not_act` 状态
- **E2E 导入**：v0.3.20 在 `hebbrix_import` 中加入 material change 时的 usage 更新

## 适用场景

hebbrix-mcp 适合以下使用情境：
1. 需要为 LLM 提供**长期记忆**而不想全量重传上下文的场景
2. 在企业知识库中希望使用**图谱检索**提升问答质量
3. 需要对 AI 输出进行**置信度评估**并标记不确定结论
4. 在对话过程中希望对**检索结果进行反馈**（mark_used）以优化后续检索

建议初次使用者从 `hebbrix_import` 开始导入首批知识条目，随后使用 `hebbrix_ask` 验证 GraphRAG 路径，并最终通过 `hebbrix_confidence` 检查是否存在约束冲突。

---

<a id='page-memory-graph'></a>

## 记忆与知识图谱工具

### 相关页面

相关主题：[推理与账户工具](#page-reasoning-account)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Hebbrix/hebbrix-mcp/blob/main/README.md)
- [hebbrix_mcp/server.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/server.py)
- [hebbrix_mcp/__init__.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/__init__.py)
- [hebbrix_mcp/graph.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/graph.py)
- [hebbrix_mcp/search.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/search.py)
- [hebbrix_mcp/confidence.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/confidence.py)
- [hebbrix_mcp/import_export.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/import_export.py)
- [CHANGELOG.md](https://github.com/Hebbrix/hebbrix-mcp/blob/main/CHANGELOG.md)
- [pyproject.toml](https://github.com/Hebbrix/hebbrix-mcp/blob/main/pyproject.toml)
</details>

# 记忆与知识图谱工具

## 概述与定位

hebbrix-mcp 是一个基于 [Model Context Protocol](https://modelcontextprotocol.io) 的服务器实现，向 LLM 代理暴露一组用于"持久化记忆"与"知识图谱构建"的工具 (Tools)。这些工具围绕 `hebbrix_*` 命令族展开，使代理能够把对话事实写入长期存储，从图谱中检索实体关系，并对结果进行可信度评估。

资料来源：[README.md:1-40]()

项目将"记忆"与"知识图谱"统一在同一后端：每条记忆既是一段文本，也是图谱中的节点或边的来源。`server.py` 通过 `@server.list_tools()` 与 `@server.call_tool()` 注册全部工具入口，遵循 MCP 标准以 JSON Schema 描述输入参数。

资料来源：[hebbrix_mcp/server.py:1-80]()

## 核心工具家族

### hebbrix_ask —— GraphRAG 入口

`hebbrix_ask` 是图谱驱动的检索增强问答工具，引入于 v0.3.16。它接受自然语言问题，先在图谱上执行实体解析与关系扩展，再把命中的子图与文本片段一起送入生成阶段。

资料来源：[CHANGELOG.md:1-40]()

伴随 `hebbrix_ask` 一同加入的还有批量能力 (`batch`)、导出 (`export`) 以及使用标记 (`mark_used`)，用于让代理在多次检索中维护会话级的引用状态。

资料来源：[CHANGELOG.md:v0.3.16 行]()

### hebbrix_import —— 数据导入

`hebbrix_import` 在 v0.3.20 中正式引入，专门处理"材料级变更 (material change)"下的端到端导入流程：解析外部文档、抽取实体与关系、写入图谱、并刷新搜索索引。

资料来源：[CHANGELOG.md:v0.3.20 行]()

该流程在重大材料变更时会触发一次完整 review，确保索引与图谱之间的引用保持一致。

资料来源：[CHANGELOG.md:v0.3.20 行]()

### hebbrix_confidence —— 置信度与约束

`hebbrix_confidence` 自 v0.3.15 起对外开放，用于在每次检索结果中返回置信度评分以及"约束冲突"信号 (`do_not_act`)。当代理发现两条规则互相排斥时，会标记为不可执行。

资料来源：[CHANGELOG.md:v0.3.15 行]()

v0.3.19 进一步引入 `index_possibly_stale` 字段，提醒调用方索引可能因异步富化而滞后，并附带文档漂移 (doc-drift) 检测，用于应对残酷测试 (BT1/BT6) 中发现的真实场景。

资料来源：[CHANGELOG.md:v0.3.19 行]()

### 搜索与覆盖层 (overlay)

搜索工具维护一份"覆盖层 (overlay)"缓存，用于在不污染真实命中结果的前提下携带临时上下文。v0.3.17 明确保证：覆盖层永远不会高于真实命中 (overlay never outranks real hits)，避免幻觉放大。

资料来源：[CHANGELOG.md:v0.3.17 行]()

v0.3.12 对覆盖层做了精度修复：注入停用词时不再误召回 (N1)，并把"已修正 (corrected)"标志正确传递给下游 (N2)。

资料来源：[CHANGELOG.md:v0.3.12 行]()

v0.3.13 进一步将"持久化画像 (profile)"与"近期上下文 (recent)"分层存储，并清零相关性为 0 的搜索 padding，杜绝噪音占用上下文窗口。

资料来源：[CHANGELOG.md:v0.3.13 行]()

## 工作流与数据流

下表汇总记忆与图谱工具在一次完整调用中的典型流转步骤：

| 阶段 | 触发条件 | 主要工具 | 输出 |
| --- | --- | --- | --- |
| 写入 | 新事实或材料变更 | `hebbrix_import` | 节点、边、索引 |
| 富化 | 索引建立后异步进行 | 后台 worker | 富化属性 |
| 查询 | 用户提问 | `hebbrix_ask` | 子图 + 文本片段 |
| 评估 | 任何查询完成后 | `hebbrix_confidence` | 置信度、约束冲突、stale 标记 |
| 清理 | 代理标记使用 | `mark_used` / `batch` / `export` | 引用更新 |

资料来源：[hebbrix_mcp/server.py:80-200](), [hebbrix_mcp/graph.py:1-120]()

写入阶段调用 `hebbrix_import`，它在解析后既写图谱又写搜索倒排索引；查询阶段由 `hebbrix_ask` 统一调度，先经 `search.py` 的覆盖层+真实命中合并，再由 `graph.py` 在子图上扩展邻居节点。

资料来源：[hebbrix_mcp/search.py:1-100](), [hebbrix_mcp/graph.py:120-240]()

`wait_for_index` 是查询路径上的同步阻塞选项；当代理希望立即读到刚写入的内容时使用，否则将依赖 v0.3.11 中标注的"异步图谱富化"。

资料来源：[CHANGELOG.md:v0.3.11 行]()

## 错误处理与可靠性

服务器在每次工具调用失败时附加 `usage` 块 (v0.3.14)，向代理说明失败原因、可重试动作与建议参数；同时项目改用共享池化 HTTP 客户端以降低长连接成本。

资料来源：[CHANGELOG.md:v0.3.14 行]()

v0.3.18 加入"提示注入围栏 (prompt-injection fencing)"，并对 WAF 拦截返回更清晰的错误描述，应对红队测试 H1/M1 场景。

资料来源：[CHANGELOG.md:v0.3.18 行]()

## 小结

记忆与知识图谱工具族以 `hebbrix_ask` 为查询主轴，以 `hebbrix_import` 为写入主轴，以 `hebbrix_confidence` 为可信度主轴，配合搜索覆盖层、置信度 stale 检测与提示注入围栏，共同构成一条"写入 → 富化 → 查询 → 评估"的闭环。

资料来源：[README.md:40-120](), [CHANGELOG.md:v0.3.11-v0.3.20]()

---

<a id='page-reasoning-account'></a>

## 推理与账户工具

### 相关页面

相关主题：[记忆与知识图谱工具](#page-memory-graph)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Hebbrix/hebbrix-mcp/blob/main/README.md)
- [hebbrix_mcp/server.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/server.py)
- [hebbrix_mcp/tools/ask.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/tools/ask.py)
- [hebbrix_mcp/tools/confidence.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/tools/confidence.py)
- [hebbrix_mcp/tools/import_tool.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/tools/import_tool.py)
- [hebbrix_mcp/auth.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/auth.py)
- [hebbrix_mcp/usage.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/usage.py)
- [hebbrix_mcp/client.py](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hebbrix_mcp/client.py)
</details>

# 推理与账户工具

## 工具定位与作用域

`推理与账户工具` 是 hebbrix-mcp 服务暴露给模型客户端的两类核心 MCP 工具集合：一类负责基于图谱与上下文的推理问答（`hebbrix_ask`、`hebbrix_confidence`），另一类负责账户与计量相关的导入、等待索引和使用反馈（`hebbrix_import`、`wait_for_index`、使用块 usage block）。它们在 `hebbrix_mcp/server.py` 中通过 `FastMCP` 装饰器统一注册为可远程调用的工具，构成了上层 Agent 触发“思考-求证-落库”完整链路的主要入口 资料来源：[hebbrix_mcp/server.py:1-120]()。

README 明确将本服务定位为“记忆层 MCP”，并把推理与账户两类工具并列在功能矩阵中，强调它们是消费方调用 Hebbrix 平台 GraphRAG 能力与计费/配额体系的标准协议层 资料来源：[README.md:32-88]()。

## 核心推理工具：hebbrix_ask

`hebbrix_ask` 是 GraphRAG 风格的问答工具，接收自然语言问题并返回带证据的答复，v0.3.16 中增加了 `batch`、`export`、`mark_used` 等能力 资料来源：[hebbrix_mcp/tools/ask.py:1-90]()。该工具在客户端层会通过共享的池化 HTTP 客户端（v0.3.14 引入）发起请求，避免在长会话中反复建立连接 资料来源：[hebbrix_mcp/client.py:1-60]()。

在 `ask.py` 中，问答响应不仅返回答案文本，还附带 `sources`（引用节点）和 `confidence` 字段；上层 Agent 可据此把推理结果回灌到 `mark_used` 端点，从而影响后续排序与覆盖层质量 资料来源：[hebbrix_mcp/tools/ask.py:91-160]()。这种“推理即反馈”的设计让每一次 GraphRAG 调用都成为账户画像的一部分。

## 质量与置信度：hebbrix_confidence

`hebbrix_confidence` 用于在回答给出前显式评估证据强度，并在 v0.3.15 起新增了 `do_not_act` 状态：当检测到约束冲突（例如用户指令与系统策略、检索结果之间的矛盾）时，工具会返回 `do_not_act=True`，要求调用方暂停执行 资料来源：[hebbrix_mcp/tools/confidence.py:1-95]()。

v0.3.19 进一步在响应里暴露了 `index_possibly_stale` 标志，用于在文档与索引之间出现漂移（doc-drift）时提示推理可能基于过期上下文，这是 brutal-test BT1/BT6 关注的回归点 资料来源：[hebbrix_mcp/tools/confidence.py:96-150]()。

## 账户与数据接入：hebbrix_import 与 wait_for_index

v0.3.20 引入的 `hebbrix_import` 是账户侧的核心入口之一，用于把外部语料批量提交到 Hebbrix 平台，并支持在“材料发生实质变更”时重新走 E2E 复核流程 资料来源：[hebbrix_mcp/tools/import_tool.py:1-80]()。该工具在写入后会返回一个 `job_id`，调用方可以配合 `wait_for_index` 轮询直到索引完成，从而保证后续 `hebbrix_ask` 不会读到半成品数据 资料来源：[hebbrix_mcp/server.py:120-180]()。

`wait_for_index` 在 v0.3.11 中专门澄清了语义：它只保证倒排索引可见，并不保证图谱富集（async graph enrichment）已经完成；调用方若依赖图谱关系，需要额外检查 `graph_ready` 标志 资料来源：[hebbrix_mcp/server.py:180-230]()。

## 使用计量与错误反馈

账户层通过 `usage` 模块在每次工具调用后生成统一的 `usage` 块；v0.3.14 起，即便在错误返回中也会附带该块，让上层 Agent 与计费系统能够准确归因 资料来源：[hebbrix_mcp/usage.py:1-70]()。配额与认证信息由 `hebbrix_mcp/auth.py` 统一管理，工具调用前会校验 `HEBBRIX_API_KEY` 并在响应中嵌入账户标识 资料来源：[hebbrix_mcp/auth.py:1-55]()。

下表总结了推理与账户工具的协作关系：

| 工具 | 类别 | 主要职责 | 关键版本变化 |
| --- | --- | --- | --- |
| `hebbrix_ask` | 推理 | GraphRAG 问答、引用、批处理 | v0.3.16 新增 batch/export/mark_used |
| `hebbrix_confidence` | 推理质量 | 证据评估、冲突告警 | v0.3.15 do_not_act；v0.3.19 index_possibly_stale |
| `hebbrix_import` | 账户/数据 | 语料导入与变更复核 | v0.3.20 E2E review 引入 |
| `wait_for_index` | 账户/同步 | 索引就绪轮询 | v0.3.11 澄清 async graph 行为 |
| `usage` 块 | 账户/计量 | 错误路径下的用量上报 | v0.3.14 引入错误回带 |

调用方在使用时建议遵循“导入 → 等待索引 → 推理 → 置信度校验 → 使用回灌”的顺序，这样既能避免基于未完成索引推理，也能让 `mark_used` 与 `do_not_act` 信号持续校准账户画像与系统行为。

---

<a id='page-architecture-ops'></a>

## 架构、部署与故障排查

### 相关页面

相关主题：[项目概述与安装配置](#page-overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Hebbrix/hebbrix-mcp/blob/main/README.md)
- [Dockerfile](https://github.com/Hebbrix/hebbrix-mcp/blob/main/Dockerfile)
- [hooks/hooks.json](https://github.com/Hebbrix/hebbrix-mcp/blob/main/hooks/hooks.json)
- [scripts/session-init.sh](https://github.com/Hebbrix/hebbrix-mcp/blob/main/scripts/session-init.sh)
- [quick_setup.sh](https://github.com/Hebbrix/hebbrix-mcp/blob/main/quick_setup.sh)
- [SECURITY.md](https://github.com/Hebbrix/hebbrix-mcp/blob/main/SECURITY.md)
</details>

# 架构、部署与故障排查

## 1. 架构概览

hebbrix-mcp 是一个遵循 Model Context Protocol（MCP）规范的服务端实现，对外暴露一组结构化工具（`hebbrix_import`、`hebbrix_ask`、`hebbrix_confidence` 等），供 AI 客户端在对话上下文中调用，从而完成素材语义检索、图谱问答（GraphRAG）以及置信度评估。`README.md` 中描述了服务的整体定位与工具清单，`SECURITY.md` 则补充了提示注入防护与 WAF 拦截的处理边界。

整体采用「客户端 ↔ MCP Server ↔ 后端 API」的三段式结构：

```mermaid
flowchart LR
    A[MCP 客户端] -- stdio/JSON-RPC --> B[hebbrix-mcp Server]
    B -- 共享连接池 HTTP --> C[Hebbrix 后端 API]
    B -. 工具输出 .-> A
    C -. 异步图谱富化 .-> B
```

自 v0.3.14 起，服务统一了出站 HTTP 客户端并启用连接池，减少了因握手抖动导致的超时；v0.3.11 之后还明确了 `wait_for_index` 的语义并标记了异步图谱富化的进行中状态。资料来源：[README.md:1-120]()、[Dockerfile:1-30]()。

## 2. 部署指南

### 2.1 一键初始化

仓库根目录下的 `quick_setup.sh` 提供了面向新用户的引导脚本，负责校验依赖、写入环境变量并生成最小可运行配置；`scripts/session-init.sh` 则在每次会话启动时执行轻量级检查与状态重置。两者配合可覆盖「首次安装」与「会话热启动」两类场景。资料来源：[quick_setup.sh:1-60]()、[scripts/session-init.sh:1-45]()。

### 2.2 容器化部署

`Dockerfile` 描述了镜像构建步骤，建议在 CI 中通过多阶段构建以减小最终层体积。典型启动命令示例：

```bash
docker build -t hebbrix-mcp:latest .
docker run --rm -i --env-file .env hebbrix-mcp:latest
```

容器以 stdio 模式与宿主 MCP 客户端通信，因此必须保留 `-i` 以保持 stdin 打开。资料来源：[Dockerfile:1-30]()。

### 2.3 客户端 Hooks 注入

`hooks/hooks.json` 声明了客户端侧生命周期钩子（如 `SessionStart`），用于在会话开始时调用 `session-init.sh` 并刷新缓存。该机制确保 v0.3.13 引入的「持久/最近内容分离」在跨会话场景下保持一致。资料来源：[hooks/hooks.json:1-40]()。

## 3. 配置与运行时行为

服务行为受若干关键开关控制：导入（`hebbrix_import`）在素材发生实质性变化时触发使用量计量（v0.3.20）；`hebbrix_ask` 启用 GraphRAG 进行图谱问答，并在 v0.3.16 加入批处理、导出与标记已用节点能力；`hebbrix_confidence` 在检测到约束冲突时输出 `do_not_act` 标记（v0.3.15）。索引新鲜度则通过 `index_possibly_stale` 暴露（v0.3.19），调用方应据此决定是否降级信任结果。资料来源：[README.md:60-180]()、[SECURITY.md:1-40]()。

## 4. 故障排查

常见故障可分为三类：

| 类别 | 典型症状 | 排查要点 |
|------|---------|---------|
| 索引一致性 | 搜索结果缺失或陈旧 | 关注 `index_possibly_stale` 标志，避免在文档漂移时直接信任（v0.3.19） |
| 安全/WAF | 工具调用被拦截或返回异常 | 区分提示注入围栏与 WAF 拦截日志（v0.3.18），参考 `SECURITY.md` 中的判定规则 |
| 缓存与覆盖层 | 覆盖层条目盖过真实命中 | v0.3.17 起覆盖层永远不能压制真实命中；若出现反例即为缺陷 |

进一步的调试建议：检查 `session-init.sh` 是否成功执行、确认容器内环境变量已注入（特别是 API 凭据）、并通过 `usage` 字段确认工具调用是否产生副作用（v0.3.14 之后，错误响应也会附带 `usage` 块以便对账）。资料来源：[SECURITY.md:1-60]()、[scripts/session-init.sh:20-45]()。

## 5. 版本演进要点（截至 v0.3.20）

近期版本集中在「结果诚实性」与「安全边界」两条主线：v0.3.16 引入 GraphRAG 问答；v0.3.17–v0.3.18 强化了缓存与注入防护；v0.3.19–v0.3.20 进一步在导入路径与置信度信号上消除漂移。运维升级时应优先在隔离环境验证 `hebbrix_import` 的 E2E 流程，再切换生产流量。资料来源：[README.md:1-200]()。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：Hebbrix/hebbrix-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/Hebbrix/hebbrix-mcp | host_targets=mcp_host, claude, cursor, claude_code

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Hebbrix/hebbrix-mcp | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Hebbrix/hebbrix-mcp | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Hebbrix/hebbrix-mcp | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Hebbrix/hebbrix-mcp | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Hebbrix/hebbrix-mcp | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Hebbrix/hebbrix-mcp | release_recency=unknown

<!-- canonical_name: Hebbrix/hebbrix-mcp; human_manual_source: deepwiki_human_wiki -->