DeepActionPotential/AgentsStudio
GitHub: DeepActionPotential/AgentsStudio
一款基于多 LLM Agent 协作的 Web 应用，通过结构化输出对代码质量、安全性、性能和架构进行全面深度审查。
Stars: 4 | Forks: 0
# AgentsStudio
一款用于进行全面代码分析的先进 Web 应用程序。该平台编排了一个由专业化 **大型语言模型 (LLM) agent** 组成的团队，旨在针对代码质量、安全性、性能和架构提供深入、结构化且可操作的反馈。
采用 **Python (Flask) 后端** 进行编排，并结合单页应用 (SPA) 前端，以提供响应迅速、类似于桌面应用程序的用户体验。
## 核心理念：结构化 Agentic 分析
首要目标是通过强制执行结构化的分析输出，超越简单的基于关键词的分析。系统使用 **Pydantic** 严格约束 LLM，迫使它们生成可靠、机器可读的 JSON 报告。
这种结构化方法确保了：
* **可靠性：** 报告保证匹配预定义的 schema，使前端易于使用。
* **可操作性：** 每个发现都包含特定字段，如 `severity`、`issue_type` 和 `line` 号。
* **深度：** 所有分析报告均继承自 `BaseLLMResponse`，这**要求**提供一个高度详细的、Markdown 格式的 `MarkdownDescription` 字段，确保每个结果都附带全面、人类可读的解释。
## 功能：专业化 Agent 套件
该平台采用了一个由九个专业化 LLM agent 组成的强大系统，每个 agent 都受到其独特的 `system_prompt` 和 Pydantic schema 的严格约束，以提供可靠、结构化的报告。
| 类别 | Agent 名称 | 核心关注领域 | 输出 Schema | 系统 Prompt 关注点 |
| :--- | :--- | :--- | :--- | :--- |
| **基础** | **Summarizer** | 对代码目的和组件角色进行高层次、中立的解释。 | `SummaryResponse` | 中立性、清晰度、功能性。 |
| **静态分析** | **Code Smell** | 识别反模式：长方法、魔术数字、不良命名、代码重复。 | `CodeSmellReport` | 可维护性、可读性、重构候选对象。 |
| | **Complexity** | 使用如圈复杂度和深层嵌套等指标衡量代码难度。 | `ComplexityReport` | 认知负荷与可测试性。 |
| | **Dependency** | 标记未使用的 import、已弃用/过时的包以及未锁定的依赖项。 | `DependencyReport` | 安全性、稳定性和构建可靠性。 |
| **质量与设计**| **SOLID** | 分析对基本 **SOLID** 面向对象原则的遵循情况。 | `SolidReport` | 接口隔离、单一职责、里氏替换。 |
| | **Architecture**| 关注结构性问题：强耦合、低内聚、分层违规、God Class。 | `ArchitectureReport` | 可扩展性、模块化和可扩展性。 |
| | **Refactor** | 为代码改进提供实用、人性化且可操作的建议。 | `RefactorReport` | 实用、对开发者友好的代码改进。 |
| **风险与性能**| **Security** | 检测关键漏洞：注入、硬编码密钥、路径遍历、弱加密。 | `SecurityReport` | 真实世界利用、OWASP Top 10、安全编码实践。 |
| | **Performance**| 精确定位 runtime 瓶颈：O(n²) 行为、低效数据结构、缓存问题、阻塞 I/O。 | `PerformanceReport` | 算法复杂度、Runtime 效率、资源使用。 |
## 架构深度剖析
### 后端：Python (Flask 与编排)
后端管理 job 状态、文件 I/O、配置，并协调 LLM 调用。
* **`app.py`：** 主入口点。它负责设置 Flask 应用程序并处理路由。关键在于，它集成了 **Hybrid Threading Model** 以促进原生文件对话框的操作（参见**关键技术**）。
* **`analysis_orchestration.py`：** **Analysis Orchestrator**。这个类是分析工作流的核心：
* **Job 管理：** 它启动并跟踪批量分析 job，维护实时的 `status` 和 `progress`。
* **可靠性：** 它针对瞬态 LLM 错误或格式错误的 JSON 响应强制执行**重试逻辑**（默认 3 次尝试），确保极高的 job 完成率。
* **并发性：** 它以非阻塞的多线程批处理方式执行 agent，使 UI 在长时间的 LLM 调用期间保持响应。
* **`base_agent.py`：** 定义了 **BaseAgent** 类，所有 LLM agent 均继承自该类。它抽象了 `pydantic-ai` 库，为每个 agent 实例强制执行 `system_prompt` 和 `output_type`。
* **`llm_loader.py`：** 一个抽象层，根据 `llm_config.yaml` 中的集中配置解析正确的 LLM 提供商（例如 Google、OpenAI、本地 Ollama）。
### 前端：Web 界面 (SPA)
一款快速、响应灵敏的单页应用，设计得如同桌面 IDE 一样，使用原生 JavaScript 以提高效率。
* **UI 组件：**
* **文件树：** 用于在项目根目录中选择文件的导航侧边栏。
* **代码编辑器：** 用于查看代码的可调整大小面板。
* **分析结果：** 用于显示结构化 JSON 报告及其相应 `MarkdownDescription` 的选项卡视图。
* **运行模态框：** 用于启动、跟踪和取消批量分析 job 的非阻塞模态框，具有实时进度条和日志流。
* **样式与主题：** 使用 **Tailwind CSS** 进行实用优先的样式设计，并使用自定义的 **VS Code 风格暗色主题** (`styles.css`) 以提供熟悉的开发者体验。
* **状态管理：** `store.js` 管理全局变量（`projectRoot`、`currentFile`、`agentResults`）并提供跨会话的数据持久化。
## 安装与设置
按照以下步骤在本地设置和运行 Code Analysis Studio。
### 前置条件
* Python 3.9+
* 稳定的互联网连接（用于云端 LLM）或本地 **Ollama** 安装。
* 所选云端 LLM 提供商（例如 Google Gemini）的有效 **API Key**。
### 1\. 设置
克隆仓库并安装依赖项。
```
# Clone the repository
git clone https://github.com/DeepActionPotential/AgentsStudio
cd multi-agent-ai-code-review
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### 2\. 配置
设置 LLM 连接详细信息和核心分析参数。
1. **LLM 提供商：** 在 `src/config/llm_config.yaml` 中配置你的 API 访问权限。
* 将 `default_llm_type: cloud` 设置为 `cloud`，并在 `cloud` 部分提供你的 `api_key`。
* 或者，将 `default_llm_type` 设置为 `local`，并为你的本地 Ollama 实例配置 `id` 和 `base_url`。（也可以通过 `settings.html` UI 进行配置更新）。
2. **分析参数：** 查看 `src/config/analysis_config.yaml` 以了解关键限制：
* `max_file_size_kb: 300`：LLM 处理的文件大小限制。`file_loader.py` 强制执行此检查，以防止 API 请求过大。
* `timeout.seconds: 40`：允许单个 agent 执行的最长时间。
```
# analysis_config.yaml snippet
max_file_size_kb: 300
retry:
attempts: 3
timeout:
seconds: 40
```
### 3\. 运行应用程序
启动 Flask 开发服务器：
```
python app.py
```
控制台将确认双线程启动：
### 4\. 用法
1. 打开浏览器并导航到本地地址（`http://127.0.0.1:5000`）。
2. 点击“Open Folder”以触发**原生 OS 文件夹对话框**（由主线程处理）。选择你的项目根目录。
3. **文件树**将被填充。选择要分析的文件。
4. 从模态框中运行**批量分析**。监控进度条和实时日志（错误、警告、成功消息）。
5. 查看结果。点击任意文件/agent 组合的选项卡，以查看详细的 JSON 报告及相关的 `MarkdownDescription`。
### 5\. 演示图片
## 常见问题与故障排除
| 问题 | 根本原因与代码组件 | 解决方案 |
| :--- | :--- | :--- |
| **LLM 超时** | LLM 在分析复杂或大型文件期间超出了配置的 `timeout.seconds`（默认 40 秒）。 | 在 `analysis_config.yaml` 中增加 `timeout.seconds`。拆分非常大的文件或检查代码复杂度。 |
| **格式错误的 JSON / 重试失败** | 在所有 `retry.attempts` 之后，LLM 未能生成严格符合所需 Pydantic schema 的输出。 | 尝试以更好的指令遵循能力而闻名的高级 LLM（例如，“Pro”或“Turbo”模型）。检查 agent 的 `system_prompt` 是否清晰。 |
| **文件被跳过** | 文件超过了 `max_file_size_kb` 限制（默认 300KB）或具有不允许的扩展名。 | 在 `analysis_config.yaml` 中增加 `max_file_size_kb`。`file_loader.py` 模块会强制执行此操作。 |
| **原生文件夹对话框未出现** | 这通常是 **Hybrid Threading Model** 中的失败，即主进程被阻塞，或者 `tkinter` 库在系统上（例如，在非 GUI 环境中）未完全正常运行。 | 确保你的 OS 安装了所有 `tkinter` 依赖项。如果在无头模式下运行，请确保你配置了 X-server（或使用远程桌面 GUI）。 |
| **配置未保存** | 从 Settings UI 更新 `llm_config.yaml` 时出错。 | 验证 `src/logic/utils/config_editor.py` 是否能在没有权限错误的情况下正确加载/保存 YAML。使用 `ruamel.yaml` 库来保留文件格式。 |
## 关键技术
### 用于本地文件访问的 Hybrid Threading Model
构建需要访问本地文件系统（以加载源代码）的 Web 应用程序的主要技术挑战由该混合模型解决。
* **限制：** Web 浏览器无法在无用户交互的情况下安全地启动文件对话框来读取任意本地目录路径。
* **解决方案：** 应用程序在后台 daemon 线程中运行 **Flask (Web UI)**，并将**主线程**保留给隐藏的 **Tkinter** 实例。
* **工作流：** 当用户在浏览器中点击“Open Folder”时：
1. Flask endpoint 接收请求。
2. Flask 将一条消息放入线程安全的 `queue.Queue` 中。
3. 主线程的 `handle_dialogs()` 函数不断监听此队列。
4. 主线程执行 `tkinter.filedialog.askdirectory()`，这将显示原生 OS 对话框。
5. 所选路径通过另一个队列返回给 Flask 线程，随后该线程开始扫描并加载文件。
### LLM 集成与结构化输出
该平台严重依赖 **`pydantic-ai`** 库来保证输出质量。
* **Agent 约束：** 每个 LLM agent（例如 `SecurityAgent`、`PerformanceAgent`）都定义了一个 Pydantic `output_type`。
* **模型指导：** Agent 的 `system_prompt` 和 Pydantic schema 被发送给 LLM，指示它生成严格符合该 schema 的 JSON 对象。
* **验证：** 如果 LLM 返回不符合规范的 JSON，`pydantic-ai` 验证将失败，从而触发 `AnalysisOrchestrator` 的重试机制以确保可靠性。
标签：Flask, LLM代理, Python, 代码分析, 代码安全审计, 凭证管理, 数据可视化, 无后门, 逆向工具