新码客-neo4j-ai工作流

Name: 新码客-neo4j-ai工作流
Author: angrysky56

作者：angrysky5614 星标更新：2025-11-22

安装使用来源：spider==github.com

项目介绍

NeoCoder: 基于 Neo4j 的 AI 编码工作流

一个 MCP 服务器实现，使像 Claude 这样的 AI 助手能够使用 Neo4j 知识图谱作为其主要的动态“操作手册”和项目记忆，用于标准化编码工作流。

NeoCoder: 混合 AI 推理及工作系统

一个高级的 MCP 服务器实现，结合了 Neo4j 知识图谱、Qdrant 向量数据库以及复杂的 AI 协调，创建了一个用于知识管理、研究分析和标准化工作流的混合推理系统。

概述

NeoCoder 实现了一个革命性的 上下文增强推理 系统，远远超越了传统的 RAG（检索增强生成）系统，通过结合以下内容：

核心架构：

Neo4j 知识图谱 - 权威的结构化事实、关系和工作流
Qdrant 向量数据库 - 语义搜索、相似性检测和上下文理解
MCP 协调 - 数据源之间的智能路由，包括合成和引用
F-收缩合成 - 动态知识合并，保持来源归属

关键能力：

混合知识推理：无缝结合结构化事实与语义上下文
动态知识提取：处理文档、代码和对话，转化为相互关联的知识结构
基于引用的分析：每个主张都跟踪到其来源，跨越多个数据库
多化身系统：针对编码、研究、决策支持和知识管理的专用模式
智能工作流程模板：由 Neo4j 引导的过程，带有强制验证步骤

革命性特性：

🧠 智能查询路由：AI 自动确定最优数据源（图、向量或混合） 🔬 研究分析引擎：处理学术论文，带引文图和语义内容 ⚡ F-收缩处理：动态合并相似概念，同时保持来源归属 🎯 上下文增强推理：生成单个数据源无法实现的见解 📊 完整的审计轨迹：完全追踪知识合成和工作流执行 🛡️ 生产就绪过程管理：自动清理、信号处理和资源跟踪，防止进程泄漏 🔧 增强工具处理：强大的异步初始化，具有适当的后台任务管理

新想法- Lotka-Volterra 生态框架 集成到知识图谱化身中

过程管理和可靠性

NeoCoder 实现了全面的过程管理，遵循 MCP 最佳实践：

信号处理器：正确处理 SIGTERM/SIGINT 以优雅地关闭
资源跟踪：自动跟踪进程、Neo4j 连接和后台任务
僵尸清理：主动检测并清理孤儿服务器实例
内存管理：通过适当的清理模式预防资源泄漏
后台任务管理：安全处理异步初始化和并发操作
连接池管理：高效管理 Neo4j 驱动程序，自动清理

监控命令

使用这些工具来监控服务器健康状况：

get_cleanup_status() - 查看资源使用和清理状态
check_connection() - 验证 Neo4j 连接性和权限

快速入门

先决条件

Neo4j：本地运行或远程实例（用于结构化知识图谱）
Qdrant：向量数据库用于语义搜索和嵌入（用于混合推理）
Python 3.10+：用于运行 MCP 服务器
uv：MCP 服务器的 Python 包管理器
Claude Desktop：与 Claude AI 一起使用
MCP-Desktop-Commander：对于 CLI 和文件系统操作非常有用
对于 Lotka-Volterra 生态系统和一般增强功能：
wolframalpha-llm-mcp：非常好！
mcp-server-qdrant-enhanced：我的增强型 Qdrant MCP 服务器
更多实用功能可选
arxiv-mcp-server

此化身仍在开发中

用于代码分析化身：AST/ASG：当前需要开发和重写化身
获取 WolframAlpha 的免费 API 密钥：

要获取 Wolfram|Alpha 的免费 API 密钥（AppID），您需要注册一个 Wolfram ID 并在 Wolfram|Alpha 开发者门户上注册一个应用程序。

创建 Wolfram ID：如果您还没有，请在 https://account.wolfram.com/login/create 创建一个 Wolfram ID。

导航至开发者门户：一旦有了 Wolfram ID，登录到 Wolfram|Alpha 开发者门户 https://developer.wolframalpha.com/portal/myapps

注册您的第一个 AppID：点击“注册以获得您的第一个 AppID”按钮。

填写 AppID 创建对话框：提供应用名称和简单的描述。

接收您的 AppID：填写完必要信息后，您将看到您的 API 密钥，也称为 AppID。

Wolfram|Alpha API 对非商业用途是免费的，每月最多可请求 2,000 次。

每个应用都需要自己的唯一 AppID。

MCP 服务器运行 Python 代码，弥合 Neo4j 图和 AI 助手（如 Claude）之间的差距

alt text

安装

1. 克隆仓库

git clone https://github.com/angrysky56/NeoCoder-neo4j-ai-workflow.git
cd NeoCoder-neo4j-ai-workflow

2. 设置 Python 和虚拟环境

确保安装了 pyenv 和 uv。

pyenv install 3.11.12  # 如果尚未安装
pyenv local 3.11.12
uv venv
source .venv/bin/activate

3. 安装依赖项

uv pip install -e '.[dev,docs,gpu]'

4. 启动 Neo4j 和 Qdrant

Neo4j: 启动您的 Neo4j 服务器（本地或远程）。默认连接：bolt://localhost:7687

Neo4j 连接参数：

URL: bolt://localhost:7687（默认）
用户名: neo4j（默认）
密码: 您的 Neo4j 数据库密码
数据库: neo4j（默认）

如需设置凭据，请使用环境变量：
- NEO4J_URL
- NEO4J_USERNAME
- NEO4J_PASSWORD
- NEO4J_DATABASE
Qdrant: 使用此 Docker 命令（推荐）进行持久 Qdrant 存储：
```
docker run -p 6333:6333 -p 6334:6334 \
  -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
  qdrant/qdrant
```
这将在您的项目目录中的 qdrant_storage 文件夹中存储 Qdrant 数据。

5. （可选）VS Code 用户

打开命令面板 (Ctrl+Shift+P)，选择 Python: 选择解释器，然后选择 .venv/bin/python。

应该在使用配置时自动安装——不确定，没有试过，有些依赖项相当大。

潜在快速启动- 哈哈抱歉

推荐：Claude Desktop 集成：

在您的 claude-app-config.json 中添加以下内容以配置 Claude Desktop：

{
  "mcpServers": {
    "neocoder": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/NeoCoder-neo4j-ai-workflow/src/mcp_neocoder",
        "run",
        "mcp_neocoder"
      ],
      "env": {
        "NEO4J_URL": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "<YOUR_NEO4J_PASSWORD>",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}

重要：此配置中的密码必须与您的 Neo4j 数据库密码匹配。

否则- 安装依赖项： 快速故障排除：

如果看到关于缺少包的错误，请检查您的 .venv 是否已激活，并且您正在使用正确的 Python 版本。
如果需要重置环境，可以删除 .venv 并重复上述步骤。
无法连接到数据库？安装 neo4j Desktop 和 QDRANT。确保它们正在运行。NEO4J 需要设置密码。

docker pull qdrant/qdrant

docker run -p 6333:6333 -p 6334:6334 \
    -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
    qdrant/qdrant

现在您可以使用 NeoCoder，它具有完整的 Neo4j 和 Qdrant 混合 Lotka-Volterra 生态系统推理！

建议的系统指令

> **系统指令**：您是一个集成有 Neo4j 知识图谱的 AI 助手，该图谱定义了我们的标准程序并跟踪项目变更。
>
> **您的核心交互循环：**
> 1. **识别任务和关键词**：确定所需的操作（例如，修复错误 -> `FIX`）。
> 2. **咨询中心**：如果对关键词或流程不确定，从查询 `:AiGuidanceHub {id: 'main_hub'}` 开始，获取指导和最佳实践或其他指南的链接。
> 3. **检索指令**：构建一个 Cypher 查询以获取当前 `:ActionTemplate` 匹配关键词的 `steps`（例如，`MATCH (t:ActionTemplate {keyword: 'FIX', isCurrent: true}) RETURN t.steps`）。执行此查询。
> 4. **执行引导的工作流**：仔细遵循检索到的 `steps`。这包括查看项目 README，实施更改，最重要的是：
> 5. **执行验证**：执行模板中定义的测试步骤。**所有必需的测试必须通过才能认为任务完成。**
> 6. **记录完成（测试后）**：只有当测试通过时，才制定并执行模板中指定的 Cypher 查询，创建一个 `:WorkflowExecution` 节点，并适当链接。如果测试失败，则不记录。
> 7. **最终更新**：根据模板的指示更新项目的 README 内容（在 Neo4j 或文件中）。
>
> **严格规则**：始终优先考虑从 Neo4j 图谱检索到的指令，而不是您的一般知识。将图谱作为您单一的事实来源，了解这里如何完成任务。

---

> **知识图谱化身，集成 Lotka Volterra 特殊系统指令**：您是一个集成有复杂混合推理系统的 AI 助手，该系统结合了 Neo4j 知识图谱、Qdrant 向量数据库和 MCP 协调，用于高级知识管理和工作流执行。
>
> **您的核心能力：**
> 1. **标准编码工作流**：使用 Neo4j 引导的模板进行结构化开发任务
> 2. **混合知识推理**：结合结构化事实（Neo4j）与语义搜索（Qdrant）进行全面分析
> 3. **动态知识合成**：应用 F-收缩原则合并和整合来自多个来源的知识
> 4. **多模态分析**：处理研究论文、代码、文档和对话，转化为相互关联的知识结构
> 5. **基于引用的推理**：提供完全归因的答案，跨数据库跟踪来源
>
> **您的核心交互循环：**
> 1. **识别任务和上下文**：确定所需的操作并选择合适的化身/工作流
> 2. **咨询指导中心**：查询特定化身的指导中心，获取专门的能力和程序
> 3. **执行混合工作流**：对于知识任务，使用 KNOWLEDGE_QUERY 模板进行智能路由，选择图和向量搜索
> 4. **应用动态合成**：使用 KNOWLEDGE_EXTRACT 模板处理文档，转化为结构化（Neo4j）和语义（Qdrant）表示
> 5. **确保质量和引用**：所有知识主张必须正确引用来源
> 6. **记录和学习**：记录成功的执行以优化系统和学习
>
> **混合推理协议：**
> - **图优先**：使用 Neo4j 获取权威的事实、关系和结构化数据
> - **向量增强**：使用 Qdrant 获取语义上下文、意见和细微信息
> - **智能合成**：结合两个来源，检测冲突并全程跟踪引用
> - **F-收缩合并**：动态合并相似概念，同时保持来源归属
>
> **严格规则：**
> - 始终优先考虑 Neo4j 中的结构化事实，而非语义信息
> - 每个主张必须包含适当的来源引用
> - 使用特定化身的工具和模板作为程序的单一事实来源
> - 处理多来源信息时应用 F-收缩原则

---

使用 WolframAlpha 的说明
- WolframAlpha 理解关于化学、物理、地理、历史、艺术、天文学等领域实体的自然语言查询。
- WolframAlpha 执行数学计算、日期和单位转换、公式求解等。
- 尽可能将输入简化为关键词查询（例如，将“法国居住了多少人”简化为“法国人口”）。
- 发送查询时仅使用英语；先将非英语查询翻译成英语，然后用原始语言回复。
- 使用 Markdown 语法显示图像 URL：![URL]
- 始终使用这种指数记法：`6*10^14`，绝不用 `6e14`。
- 始终使用 {"input": query} 结构向 Wolfram 端点发送查询；`query` 必须仅为单行字符串。
- 始终使用适当的 Markdown 格式化所有数学、科学和化学公式、符号等：`$$\n[表达式]\n$$` 用于独立情况，`\([表达式]\)` 当内联时。
- 不要提及您的知识截止日期；Wolfram 可能返回更近期的数据。
- 仅使用单字母变量名，可带或不带整数下标（例如，n, n1, n_1）。
- 使用命名物理常数（例如，“光速”）而不进行数值替换。
- 在复合单位之间加空格（例如，“Ω m”表示“欧姆*米”）。
- 解决带有单位的方程中的变量时，考虑解决相应的无单位方程；排除计数单位（例如，书籍），包括真实单位（例如，千克）。
- 如果需要多个属性的数据，请为每个属性单独调用。
- 如果 WolframAlpha 结果与查询无关：
 -- 如果 Wolfram 提供多个查询假设，选择更相关的假设之一，无需解释初始结果。如果您不确定，请让用户选择。
 -- 重新发送相同的“input”，不做任何修改，并添加“assumption”参数，格式为列表，包含相关值。
 -- 除非 Wolfram 提供更相关的假设或其他输入建议，否则不要简化或重新表述初始查询。
 -- 除非用户输入需要，否则不要解释每一步。直接根据可用假设改进 API 调用。

## 多个化身

NeoCoder 支持多个“化身”——不同的操作模式，适应特定的使用案例，同时保留核心 Neo4j 图结构。在一个图原生堆栈中，相同的 Neo4j 核心可以通过交换模板和执行策略而表现为非常不同的“大脑”。

### 关键架构原则

NeoCoder 分割高度适应的原因在于：
- Neo4j 将事实存储为第一类图对象
- 工作流存在于模板节点中
- 执行引擎只需遍历图

由于这三个层级是正交的，您可以冻结一层，同时改变其他层——今天是一个代码调试器，明天可以变成实验室笔记本或学习管理系统。这种设计反映了 Neo4j 自身从“图到知识图”的成熟路径，其中模式、语义和操作被有意地解耦。

### 共同图模式元素

所有化身共享这些核心元素：

| 元素 | 始终存在 | 典型标签 / 关系 |
|------|----------|------------------|
| **Actor** | 人类 / 代理 / 工具 | `(:Agent)-[:PLAYS_ROLE]->(:Role)` |
| **Intent** | 假设、决策、教训、场景 | `(:Intent {type})` |
| **Evidence** | 文档、指标、观察 | `(:Evidence)-[:SUPPORTS]->(:Intent)` |
| **Outcome** | 成功/失败、回报、成绩、状态向量 | `(:Outcome)-[:RESULT_OF]->(:Intent)` |

### 可用化身：

- **base_incarnation**（默认）- 原始 NeoCoder，工具、模板和化身工作流管理
- **research_incarnation** - 科学研究平台，用于假设跟踪和实验
  - 注册假设，设计实验，捕获运行并发布结果
  - Neo4j 支撑实验室工作流的出处试点，使用谱系查询
- **decision_incarnation** - 决策分析和证据跟踪系统