ruoyunbai/compliance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

集成

Browse Source
This commit is contained in:
gongwenxin
2025-07-24 17:22:36 +08:00
parent fcdfe71646
commit 1901cf611e
24 changed files with 1263 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
compliance-mcp-agent/memory-bank/activeContext.md
+39
View File
@@ -0,0 +1,39 @@
# 活动上下文
## 当前工作焦点
我们正处于 **架构验证和问题修复的关键阶段**。在初步搭建了包含多个服务器（`APICaller`, `SchemaValidator`, `DMSProvider`, `TestManager`）的完整 MCP 架构后，我们遇到了一个**持续性的、与文件路径解析相关的核心障碍**。
当前所有工作的核心焦点是 **彻底解决在子进程中运行的 MCP 服务器无法正确定位其依赖文件（如 `domain.json`）的问题**，并最终让整个测试流程成功运转起来。
### 优先任务
1. **根源分析**: 彻底理解 `subprocess.Popen` 的工作目录（CWD）继承机制，以及它是如何与 `DMSProviderServer.py` 中 `os.path` 相关函数交互并导致错误的。
2. **实施健壮的解决方案**:
- **重构 `run_tests.py`**: 修改启动脚本，在创建服务器子进程时，为其**明确设置 `cwd` 参数**，确保每个服务器都在其脚本所在的目录中运行。
- **简化服务器路径**: 在 `DMSProviderServer.py` 中，将文件路径调整为基于其已被正确设置的 `cwd` 的、更简单的相对路径。
3. **最终验证**: 运行完整的端到端测试，确认 AI Agent 能够成功从 `DMSProviderServer` 获取 API 列表，并启动其测试循环。
## 最近变更
* **多服务器架构实现**: 我们已经成功创建并集成了四个独立的 MCP 服务器，每个服务器都提供一组特定的工具。
* **Agent 逻辑进化**: Agent 的主循环 (`agent_main_loop.py`) 已经从硬编码逻辑演变为一个完全由 LLM 驱动的、动态的测试流程。
* **启动器脚本**: 创建了 `run_tests.py`，用于统一启动所有服务器和 Agent 进程。
* **反复的路径修复尝试**: 多次尝试修改 `DMSProviderServer.py` 中的相对路径，但均未成功，这促使我们对问题进行更深入的分析。
## 活动决策和考虑
### 当前决策
1. **接受失败并深入分析**: 我们认识到，简单的路径调整是无效的。我们决定暂停“打地鼠”式的修复，转而投入时间去理解问题的根本原因——进程的执行上下文。
2. **采用 `cwd` 解决方案**: 我们确定，通过在 `subprocess.Popen` 中为每个服务器子进程显式设置 `cwd`，是解决此类问题的最健壮、最可靠的方法。这将使我们的系统对执行环境的变化更具弹性。
### 开放问题
1. **异步错误处理**: 当前的 `agent_main_loop.py` 在 `TaskGroup` 中遇到了未处理的异常。一旦路径问题解决，下一个需要关注的技术点将是如何在 `anyio` 和 `asyncio` 的环境中优雅地捕获和处理并发任务中的错误。
2. **LLM 的稳定性**: 尽管 Agent 的逻辑是 LLM 驱动的，但我们还未充分测试在真实、长链条的工具调用下，LLM 生成的参数和决策的稳定性。这可能是下一个潜在的问题点。
## 下一步计划
### 短期目标 (本次会话)
- [x] **重构 `run_tests.py`** 以正确设置服务器的 `cwd`。 (已完成)
- [x] **调整 `DMSProviderServer.py`** 中的文件路径以匹配新的 `cwd`。(已完成)
- [ ] **执行最终测试**: 在您重启对话后，我们将立即运行 `run_tests.py`，并期望看到 `DMSProviderServer` 成功加载 API 列表，Agent 开始执行测试。
- [ ] **修复 `TaskGroup` 异常**: 解决在 `agent_main_loop.py` 中出现的 `AttributeError: 'NoneType' object has no attribute 'get'`，这个错误很可能是由空的 API 列表间接触发的。
compliance-mcp-agent/memory-bank/productContext.md
+25
View File
@@ -0,0 +1,25 @@
# 产品上下文
## 问题陈述：传统测试框架的“天花板”
随着 API 数量的增多和合规性规则日益复杂，我们现有的、基于代码的合规性测试框架正面临一个难以突破的“天花板”。
1. **僵化与脆弱**: 每当出现一个新的合规规则，我们就必须编写一个新的、硬编码的测试用例。这种紧耦合的设计使得框架越来越臃肿，修改一处就可能引发意想不到的连锁反应。
2. **扩展性差**: 添加一种新的测试能力（比如，集成一个新的静态分析工具）需要深入修改核心的测试编排器逻辑。这个过程不仅耗时，而且对开发人员的水平要求很高，阻碍了社区贡献和团队协作。
3. **可维护性噩梦**: 测试逻辑、工具调用、报告生成等所有功能都混杂在一起，使得代码难以理解和维护。排查一个简单的 bug 可能需要在多个模块之间来回跳转，心智负担极重。
4. **智能程度低**: 传统框架只能执行预先定义好的、线性的测试路径。它无法理解规则的“意图”，也无法在遇到预期外情况时进行动态调整或探索性测试。
## 解决方案：一个“会思考”的测试平台
我们提出的基于 MCP 的 AI Agent 框架，旨在从根本上解决上述问题，将我们的测试工具从一个死板的“执行器”升级为一个会思考、可扩展的“平台”。
1. **从“硬编码”到“软编排”**: 我们不再编写固定的测试流程。取而代之的是，我们给 Agent 一个**目标**（“验证这个API是否符合这条规则”），然后由 Agent **自主地、动态地**编排和调用一系列原子化的工具来达成这个目标。这种灵活性是革命性的。
2. **无限的扩展能力**: 想要增加一个新的测试能力？非常简单，只需开发一个独立的、符合 MCP 规范的工具 Server 即可。这个新工具会自动被 Agent 发现并使用，完全不需要修改 Host 或 Client 的核心代码。这为框架的生态发展打开了无限可能。
3. **清晰的关注点分离**: Host 只关心“流程”，Client 只关心“思考”，Server 只关心“执行”。这种架构上的清晰性使得每个组件都变得简单、可独立开发和测试，极大地降低了维护成本。
4. **涌现的智能**: Agent 不仅能执行已知的测试，未来还有可能通过推理，发现规则之间隐藏的关联，或者设计出人类工程师没有想到的测试路径，从而找到更深层次的 bug。
## 用户体验目标
* **对于规则制定者**: 他们可以用更接近自然语言的方式来定义合规性规则，而无需关心具体的测试代码实现。
* **对于工具开发者**: 他们可以轻松地将自己的工具（如静态扫描器、安全检查器等）封装成 MCP Server，无缝集成到我们的测试生态中。
* **对于测试工程师**: 他们将得到一个高度自动化且结果可信、过程透明的测试伙伴，能将他们从繁琐的脚本编写中解放出来，专注于更有创造性的测试策略分析。
compliance-mcp-agent/memory-bank/progress.md
+57
View File
@@ -0,0 +1,57 @@
# 项目进度
## 里程碑 1: 最小可行产品 (MVP) - (已完成)
**目标**: 搭建并验证 MCP 架构的端到端通信。
### 已完成功能
- ✅ **项目初始化**
- ✅ 创建 `compliance-mcp-agent` 独立目录。
- ✅ 创建全新的 `memory-bank`。
- ✅ **核心文档撰写**
- ✅ `projectbrief.md`, `systemPatterns.md`, `techContext.md`, `productContext.md`...
- ✅ **搭建基础框架**
- ✅ 创建 `requirements.txt` 并添加依赖。
- ✅ 实现 `APICallerServer.py`。
- ✅ 实现 `run_tests.py` (Host)。
- ✅ 实现 `agent_main_loop.py` (Client)。
- ✅ **"Hello World" 级测试**
- ✅ 成功运行了第一个端到端的单服务器测试。
---
## 里程碑 2: 功能完备版本 - (进行中)
**目标**: 实现一个功能完备的、由 Agent 驱动的测试流程。
### 已完成功能
- ✅ **多服务器架构**
- ✅ 实现 `SchemaValidatorServer.py`，提供严格和灵活的 Schema 验证工具。
- ✅ 实现 `DMSProviderServer.py`，动态提供 API 列表和 Schema 定义。
- ✅ 实现 `TestManagerServer.py`，用于跟踪和管理测试进度。
- ✅ **LLM 驱动的 Agent**
- ✅ 在 `agent_main_loop.py` 中集成了真实的 LLM 调用。
- ✅ Agent 能够自主地与所有服务器交互，获取工具并制定初步计划。
### 正在进行的工作
- 🔄 **修复核心架构障碍**:
- [x] **根源定位**: 已准确定位到 `run_tests.py` 启动的子进程因错误的 CWD 而无法找到数据文件。
- [x] **解决方案实施**: 已重构 `run_tests.py` 以强制设定子进程的 `cwd`，并同步更新了 `DMSProviderServer.py` 中的文件路径。
- [ ] **最终验证**: 等待下一次运行，以确认 Agent 现在可以成功获取 API 列表并开始执行测试。
### 待完成工作
- ⏳ 解决 `agent_main_loop.py` 中出现的 `TaskGroup` 异步错误。
- ⏳ 实现完整的 CRUD (Create, Read, Update, Delete, List) 测试生命周期。
- ⏳ 生成结构化的、可读的测试报告。
---
## 里程碑 3: 企业就绪版本 (未来规划)
**目标**: 成为一个健壮、可靠、可用于生产环境的合规性审计平台。
- ⏳ 拥有完善的错误处理、重试和超时机制。
- ⏳ 提供清晰的日志和可观测性。
- ⏳ 支持更复杂的测试场景，如多 Agent 协作。
- ⏳ 具备优秀的用户文档和开发者文档。
- ⏳ (可选) 提供 Web 界面来配置和查看测试结果。
compliance-mcp-agent/memory-bank/projectbrief.md
+23
View File
@@ -0,0 +1,23 @@
# 项目简介：AI Agent 驱动的合规性测试框架
## 项目概述
本项目旨在从零开始，构建一个基于 **模型-上下文-协议 (Model-Context-Protocol, MCP)** 的下一代 API 合规性测试框架。我们将用一个自主决策的 **AI Agent** 来取代传统的、基于固定脚本的测试逻辑。这个 Agent 将利用一套标准化的、可扩展的 **工具集 (MCP Servers)**，动态地规划和执行测试步骤，以验证 API 是否符合指定的合规性规则。
## 核心需求
1. **MCP 原生架构**: 系统的所有组件交互都必须严格遵循 MCP 规范，实现 Host, Client, 和 Servers 之间的清晰分离。
2. **AI Agent 驱动**: 测试的执行逻辑由一个核心的 LLM Agent 驱动，它能够自主进行推理、规划和调用工具。
3. **可扩展的工具集**: 所有的测试能力（如 API 调用、数据生成、结果断言）都必须被封装成独立的、符合 MCP 规范的 Server。
4. **标准化与模块化**: 彻底抛弃硬编码的集成方式，实现测试能力和测试流程的完全解耦。
5. **透明的可审计性**: Agent 的每一个决策步骤、每一次工具调用都必须被完整记录，形成清晰、可审计的测试日志。
## 关键目标
1. **提升灵活性**: 使测试框架能够轻松适应新的合规规则，甚至在没有明确测试脚本的情况下，也能通过自然语言描述的规则进行测试。
2. **增强扩展性**: 允许任何开发者通过创建一个新的、符合 MCP 规范的工具服务器来为框架贡献新的测试能力。
3. **提高可维护性**: 通过将系统拆分为职责单一的独立组件，大幅降低代码的耦合度和维护成本。
4. **探索 Agentic Workflow**: 验证 AI Agent 在软件测试这一高度结构化领域的自主工作能力，为更复杂的 Agentic 自动化流程积累经验。
## 技术栈
- **核心协议**: Model-Context-Protocol (MCP)
- **官方 SDK**: `model-context-protocol/python-sdk`
- **核心语言**: Python 3.8+
- **Agent 大脑**: 兼容 OpenAI API 的大语言模型 (LLM)
compliance-mcp-agent/memory-bank/systemPatterns.md
+63
View File
@@ -0,0 +1,63 @@
# 系统架构与设计模式
## 核心架构：模型-上下文-协议 (MCP)
本系统严格遵循 MCP 定义的 **Host-Client-Server** 架构，旨在实现组件的终极解耦和高可扩展性。
```mermaid
graph TD
subgraph TestRunnerApp [测试运行程序 (MCP Host)]
style TestRunnerApp fill:#e6f2ff,stroke:#b3d9ff
A[<b>run_mcp_tests.py</b><br/><i>(Host 实例)</i>]
A -- 1. 为每个测试任务<br/>创建并管理Client会话 --> B
A -- 4. 汇总所有Client的<br/>结论，生成报告 --> E[最终测试报告]
end
subgraph AgentSession [独立的Agent会话 (MCP Client)]
style AgentSession fill:#e6ffe6,stroke:#b3ffb3
B[<b>Client 实例</b><br/><i>(包含LLM的Agent核心)</i>]
B -- 2. 向Host请求<br/>使用工具 --> D
end
subgraph Toolbelt [MCP工具集 (MCP Servers)]
style Toolbelt fill:#fff0e6,stroke:#ffccb3
D[<b>APICallerServer<br/>DataGenServer<br/>AssertionServer<br/>...</b>]
D -- 3. 执行操作<br/>并将结果通过Host返回 --> B
end
```
## 组件职责详解
### 1. MCP Host (测试运行程序)
* **角色**: 整个测试流程的 **总控制器**、**安全边界** 和 **环境提供者**。它如同一个“办公室”环境，为 Agent 的工作提供场地、工具和规则。
* **职责**:
* **流程编排**: 加载 API 规范和合规规则，生成测试任务列表，并为每个任务启动一个独立的、隔离的 Client 会话。
* **生命周期管理**: 负责创建、监督和销毁 Client 实例。如果某个 Agent 会话卡死或崩溃，Host 会终止它并继续下一个任务，确保整体流程的健壮性。
* **安全与路由**: 作为所有通信的中间人，它接收来自 Client 的工具调用请求，验证其权限，然后将其安全地路由到指定的 Server。它也负责将 Server 的结果返回给正确的 Client。**Client 和 Server 之间永不直接通信**。
### 2. MCP Client (Agent 会话)
* **角色**: 承载 **LLM（大语言模型）** 的执行实体，是 Agent 的“大脑”和“身体”的结合。
* **职责**:
* **任务执行**: 从 Host 接收一个明确的测试目标。
* **推理规划**: 内部的 LLM 负责思考和规划，决定需要执行哪些步骤、调用哪些工具来达成测试目标。
* **与 Host 通信**: 将 LLM 的决策转化为对 Host 的标准 `call_tool` 请求。
* **状态保持**: 在会话内部维持短期的记忆和上下文，以完成连贯的、多步骤的测试逻辑。
### 3. MCP Servers (工具集)
* **角色**: 提供单一、原子化能力的 **功能模块**。每个 Server 都是一个独立的微服务。
* **职责**:
* **提供能力**: 封装一种特定的能力，例如：
* `APICallerServer`: 仅负责发起 HTTP 请求。
* `DataGeneratorServer`: 仅负责根据 Schema 生成数据。
* `AssertionServer`: 仅负责比较两个值是否相等。
* **无状态与隔离**: Server 本身是无状态的（或会话状态由 Host 管理），并且对其他 Server 和整个测试任务一无所知。这种设计确保了工具的高度可复用性和可独立测试性。
## 设计模式应用
* **单一职责原则**: 每个组件（Host, Client, Server）和每个 Server 内部的工具都有单一、明确的职责。
* **策略模式**: 每个合规性规则可以被看作一种“策略”，Agent 根据不同的策略（规则目标）来组织其工具调用序列。
* **外观模式**: Host 为 Client 提供了一个统一的、简化的接口来访问背后复杂的工具集，Client 无需关心工具的具体位置和实现。
* **微服务架构**: 整个工具集由一系列独立的、可独立部署的 Server 构成，体现了微服务的思想，极大地提高了系统的灵活性和可维护性。
compliance-mcp-agent/memory-bank/techContext.md
+54
View File
@@ -0,0 +1,54 @@
# 技术上下文
## 核心技术栈
| 类别 | 技术/库 | 版本 | 用途 |
| ---------- | ----------------------------------------- | ---- | ---------------------------------------------- |
| 核心协议 | Model-Context-Protocol (MCP) | v1+ | 定义系统所有组件间的通信标准。 |
| **官方SDK** | **`model-context-protocol/python-sdk`** | 最新 | **我们实现Host, Client, Server的基石。** |
| 核心语言 | Python | 3.8+ | 主要开发语言。 |
| AI模型 | 兼容OpenAI API的大语言模型 (LLM) | - | 作为Agent的“大脑”，负责推理和规划。 |
| HTTP客户端 | requests | 最新 | 在APICallerServer中用于执行HTTP请求。 |
| Web框架 | (可选) FastAPI / Flask | - | 或许会用于构建可通过HTTP访问的远程MCP Server。 |
## 开发环境设置
### 必要组件
- Python 3.8 或更高版本
- `uv` 或 `pip` (用于管理Python包依赖)
- Git (版本控制)
- 支持Python的IDE (推荐 VS Code 或 PyCharm)
### 项目安装步骤 (预期)
1. **克隆代码仓库**:
```bash
git clone <仓库URL>
cd compliance-mcp-agent
```
2. **创建虚拟环境**:
```bash
python -m venv .venv
source .venv/bin/activate
```
3. **安装依赖**:
我们将创建一个 `requirements.txt` 文件，内容至少包括：
```
model-context-protocol
requests
# 其他未来可能需要的依赖
```
然后执行安装：
```bash
uv pip install -r requirements.txt
```
4. **运行项目**:
* **启动所有MCP Servers**: 需要编写一个脚本来并行启动所有工具服务器。
* **启动MCP Host**: 运行主程序 `run_mcp_tests.py` 来开始整个测试流程。
## 关键技术决策
1. **SDK 优先**: 我们将尽可能地利用官方 Python SDK 的能力，而不是重新发明轮子。所有的 Host/Client/Server 实现都应基于该 SDK 提供的类和方法。
2. **Stdio 通信**: 在项目初期，为了简单起见，Host 和 Client 之间的通信将主要通过标准输入/输出 (`stdio`) 进行，这由 `stdio_client` 提供支持。这对于本地运行的 Agent 来说足够高效。
3. **独立的 Server 进程**: 每个 MCP Server 都将作为一个独立的 Python 进程运行。这确保了工具之间的完全隔离，并为未来将某个工具部署为网络服务（例如使用 FastAPI）提供了可能性。
4. **异步编程**: 官方 SDK 大量使用了 `asyncio`。因此，我们的 Host 和 Client 代码也必须是异步的，以充分利用 SDK 的性能。
5. **LLM 接口**: Agent 与 LLM 的交互将通过一个通用的、兼容 OpenAI 的 API 客户端进行。这允许我们未来可以轻松切换不同的后端 LLM 服务。