AI导哈

意图到代码跟踪协议代理

一个基于模型上下文协议（MCP）的AI治理架构，旨在通过闭环系统确保代码执行与业务意图的一致性。

  • by Ashishsharmastudio
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Ashishsharmastudio/Agent-Integration-with-MCP-Servers-Notion-Git-

使用说明

对齐驱动开发（ADD）代理

通过MCP实现意向代码可追溯性协议

闭环人工智能治理架构，旨在使用模型上下文协议（MCP）连接业务意图（Notion）和执行状态（GitHub）。

🛑 问题：规范熵

在人工智能辅助的软件开发中，团队通常会以比管理更快的速度发布生成的代码。一个功能在规范中定义，传递给LLM，然后合并。随着时间的推移，代码库偏离了最初的业务意图，造成了巨大的有状态内存真空。

此存储库提供 意图代码可追溯性协议 为了解决这个问题。它迫使LLM违背初衷来管理其代码，确保AI在接触代码库之前阅读手册。该代理不是将LLM连接到任务跟踪器上，而是充当文档和代码库之间的有状态治理桥梁。

🏗️ 核心架构：治理循环

该系统在4步编排循环上运行，利用MCP服务器来维护上下文隔离和数据安全。

  1. 意图层（概念MCP）： 我们将Notion视为规范和架构决策的不可变真理来源。代理在接触代码之前必须阅读手册。
  2. 治理桥梁（推理引擎）： 语义路由器(reasoning.py)分析查询，选择适当的MCP工具，并将业务逻辑映射到代码库，确保上下文在翻译中不会丢失。
  3. 执行状态（GitHub MCP）： 代理遍历存储库树并读取代码的当前状态(mcp_manager.py).
  4. 审计追踪： 该代理通过将精确的Notion规范URL嵌入到生成的Git提交消息中，建立从产品意图到合并提交的永久可追溯性，从而促进了一个决策分类账，使其在团队更替中幸存下来。

🧠 “对齐门”的实施(feature_diff.py)

治理循环的核心是对齐门。在执行之前，系统在Notion规范和GitHub存储库之间执行确定性特征差异，以停止违反记录意图的“修复”。

  • 它从Notion标记中提取结构化需求列表。
  • 它从Git blob中提取已实现的功能。
  • 它计算一个确定性交叉点(overlap, only_in_notion, only_in_code).
  • 它揭示了工程团队（或人工智能）需要优先考虑的三大架构差距，以符合规范。

🚀 快速启动和部署

该架构已准备好投入生产，并已容器化。

选项1：单命令Docker执行（推荐）

启动完全容器化的治理桥梁：

# Linux/macOS
./run_with_docker.sh

# Windows
run_with_docker.bat

选项2：手动设置

cp .env.example .env
# Fill in required tokens
pip install -r requirements.txt
python app.py

🔌 API和校准闸门正在运行

代理通过中央统一端点进行操作(GET /agent)并且可以在您的意图和执行层访问35个以上的粒度工具。

示例工作流：

  • 触发对齐门： GET /agent?query=compare%20features%20between%20docs%20and%20code 返回一个严格的特征差异，根据Notion规范评估代码真实性。
  • 审核分类账： GET /agent?query=how%20many%20commits%20are%20in%20the%20repository 直接工具执行返回执行层的当前状态。
  • 验证意图： GET /agent?query=Find%20documentation%20about%20the%20API 迫使代理从指定的真实来源合成响应。

🔑 环境配置

为了保护治理桥，必须在您的 .env:

变量 描述 必填
OPENAI_API_KEY 协调语义路由和对齐差异 ✅
GITHUB_PERSONAL_ACCESS_TOKEN 授予执行层读取权限 ✅
GITHUB_TOOLSETS GitHub工具集（默认：repos） ✅
GITHUB_REPO 目标存储库位于 owner/repo 格式 ✅
GITHUB_DEFAULT_REF 默认分支（默认：master） ✅
NOTION_TOKEN 授予意图层读取权限 ✅
PORT 应用程序端口（默认值：5000） ❌
FLASK_ENV Flask环境（默认：开发） ❌

🧪 测试可追溯性协议

该存储库包括一个全面的测试套件，涵盖推理引擎、对齐门和MCP状态管理器。

# Test the unified workflow
python test_workflow.py

# Run all unit and integration tests
python run_tests.py

相关 MCP