项目地址：
https://github.com/jiuguandemao/multimodal-bug-agent

说明：如果 CSDN 对 GitHub raw 图片加载不稳定，可以把本文用到的图片手动上传到 CSDN。图片都在仓库的 assets/ 和 examples/ 目录下。

1. 前言

做了一个偏测试开发方向的小项目：MultiBug-Agent。

一开始我并不想做那种“输入一句话，调用大模型生成一段分析”的项目。那样确实容易做出来，但很难讲清楚工程价值。真实的 Bug 排查不是只看一句用户描述，更多时候要同时看：

• 页面截图；
• 用户怎么操作的；
• 浏览器 console 报错；
• 后端接口日志；
• 相关前后端代码；
• 修复后应该补哪些回归测试。

所以这个项目的目标很明确：

把 Web 缺陷排查过程中分散的证据收集起来，做一次结构化分析，最后自动生成 Bug 报告和测试用例。

项目已经开源：

https://github.com/jiuguandemao/multimodal-bug-agent

2. 项目做了什么

MultiBug-Agent 是一个面向 Web 应用的缺陷定位和自动化测试生成工具。

它可以输入：

• 用户描述；
• 页面截图；
• 操作录屏；
• 前端 console 日志；
• 后端接口日志；
• 前后端代码片段或代码目录。

然后输出：

• 缺陷类型；
• 严重程度；
• 影响模块；
• 复现步骤；
• 关键证据；
• 根因分析；
• 可疑代码位置；
• 修复建议；
• pytest 接口测试；
• Playwright UI 自动化测试；
• Markdown 格式 Bug 报告。

项目里内置了几个可复现的 Bug 场景，比如注册接口 500、登录 loading 卡死、上传文件过大、个人中心白屏、订单金额错误、权限 403 等。

例如注册提交 500 的截图：

还有个人中心白屏场景：

3. 多模态

这里我没有把“多模态”当成一个空概念。

项目里确实有多种不同类型的数据进入同一个分析流程：

模态	项目中的输入	处理方式
文本	用户描述、Bug 描述	提取操作路径和业务上下文
图像	页面截图	Pillow 基础分析 + Qwen-VL 视觉理解
视频	操作录屏	抽取关键帧，分析页面变化
日志	console 日志、后端日志	识别错误类型、接口、堆栈、关键词
代码	前端/后端源码	切分代码块，检索可疑位置
结构化数据	metadata、评估标注	生成报告和评估指标

我的理解是，真正有用的多模态不是“我上传了一张图”，而是要回答：

不同类型的信息怎么被抽取、怎么对齐、怎么共同影响最后的判断？

所以这个项目里设计了一个中间层：Evidence Packet，也就是结构化证据包。

它大概包含：

用户描述 截图路径和尺寸 Qwen-VL 的视觉分析结果 录屏关键帧 前端日志信号 后端日志信号 可疑代码片段 规则引擎初步判断

后续 DeepSeek 做二次审查时，看的不是一堆混乱的原始文件，而是整理好的证据包。

---

4. 整体架构

项目整体架构如下：

可以简单理解成四层：

4.1 输入层

包括截图、录屏、日志、代码和用户描述。

这些数据来源不同，格式也不同，所以不能直接一起丢给模型。

4.2 证据抽取层

不同模态分别处理：

• 截图交给 screenshot_analyzer.py 和 vision_analyzer.py；
• 录屏交给 video_analyzer.py；
• 日志交给 log_parser.py；
• 代码交给 code_parser.py 和 code_locator.py。

4.3 推理层

先用规则引擎做一版稳定、可解释的判断，再用 DeepSeek 做二次审查。

我这里没有完全依赖大模型，主要是因为：

• 规则结果更稳定；
• 代码定位需要证据链；
• 没有 API Key 时项目也应该能运行；
• 大模型更适合作为增强层，而不是唯一判断来源。

4.4 输出层

最终输出 Bug 报告和测试用例。

报告里会包含：

• 缺陷摘要；
• 关键证据；
• 复现步骤；
• 根因分析；
• 可疑代码位置；
• 修复建议；
• AI 二次审查；
• pytest / Playwright 测试。

---

5. 日志解析怎么做

真实 Bug 定位里，日志通常是最关键的证据之一。

项目中定义了几类常见错误：

server_error frontend_type_error timeout permission upload_limit data_mismatch network unknown

比如下面这些日志：

POST /api/register 500 Internal Server Error TypeError: Cannot read properties of undefined ValueError: birthday must not be empty

系统会从中提取：

• 错误级别；
• 来源是前端还是后端；
• 错误类别；
• 接口路径；
• 文件名；
• 关键词。

这些结果会被组织成 LogSignal。

简化后的逻辑是：

def parse_logs(frontend_log: str, backend_log: str):
    signals = []
    for source, text in (("frontend", frontend_log), ("backend", backend_log)):
        for line_no, line in enumerate(text.splitlines(), start=1):
            severity = detect_severity(line)
            category = detect_category(line)
            if severity != "info" or category != "unknown":
                signals.append(LogSignal(
                    severity=severity,
                    source=source,
                    message=line,
                    line_no=line_no,
                    category=category,
                ))
    return signals

这一步看起来不复杂，但很重要。因为后面的代码检索和缺陷分类都依赖这些结构化日志信号。

6. 代码定位怎么做

我没有让大模型直接读完整代码仓库。

因为真实项目代码量可能很大，直接塞给模型不现实，也不利于解释。

所以项目采用了一个轻量的代码定位流程：

扫描代码目录 ↓ 过滤 node_modules / venv / 缓存目录 ↓ 按函数或代码块切分 ↓ 根据日志关键词和错误类别打分 ↓ 返回 Top-N 可疑代码片段

例如注册接口 500 这个场景，后端代码里有：

  def register_user(payload):
        username = payload.get("username")
        password = payload.get("password")
        birthday = payload["birthday"]
     if not username or not password:
        raise ValueError("username and password required")
    return {"id": 1, "username": username, "birthday": birthday}

关键问题在这里：

birthday = payload["birthday"]

如果请求体没有传 birthday，这里就可能触发异常。结合后端日志：

ValueError: birthday must not be empty

系统就能把 register_service.py 排到比较靠前的位置。

这类定位不追求一开始就做到“完全自动修复”，而是先做到：

把排查范围从整个项目缩小到几个可疑文件和代码片段。

这对测试开发和缺陷分析已经有实际价值。

7. Qwen-VL 在项目里做什么

Qwen-VL 主要负责视觉理解。

截图里有些信息日志不一定能体现，比如：

• 页面是不是白屏；
• 是否有错误弹窗；
• 是否一直 loading；
• 表单字段有没有明显错误；
• 页面上展示的错误文案是什么。

项目中的 vision_analyzer.py 会读取截图，把图片转成 base64 data URL，然后通过 OpenAI-compatible 接口发送给 Qwen-VL。

配置示例：

VISION_PROVIDER=qwen QWEN_API_KEY=your_dashscope_key VISION_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1 VISION_MODEL=qwen3-vl-plus

Qwen-VL 的输出会被写入截图证据中，例如：

页面类型：注册表单 可见异常：右上角出现服务器异常 500 可疑组件：提交注册按钮、错误 toast 建议结合：前端 console 和后端 /api/register 日志继续定位

然后这些视觉信息会进入 Evidence Packet。

---

8. DeepSeek 在项目里做什么

DeepSeek 不是用来直接看图的。

它在这个项目里的作用是：

对结构化证据包做二次审查。

也就是说，系统先把截图分析、日志信号、可疑代码片段和规则引擎结果整理好，再交给 DeepSeek。

DeepSeek 负责补充：

• 当前规则判断是否可信；
• 可能根因是什么；
• 还缺哪些证据；
• 修复建议是否完整；
• 应该补哪些回归测试。

配置示例：

LLM_PROVIDER=deepseek DEEPSEEK_API_KEY=your_deepseek_key LLM_API_BASE=https://api.deepseek.com LLM_MODEL=deepseek-v4-flash

这样设计的好处是：即使 DeepSeek 不可用，项目仍然可以依靠本地规则引擎跑通；如果 API 可用，就能得到更完整的二次分析。

---

9. 自动生成测试用例

Bug 定位之后，下一步应该是回归测试。

所以项目会根据缺陷类型生成两类测试模板：

• 后端接口测试：pytest
• 前端 UI 自动化测试：Playwright

例如注册接口 500 场景，生成的 pytest 大概是：

def test_register_should_validate_required_fields(client):
    response = client.post("/api/register", json={
        "username": "",
        "password": "123456"
    })
    assert response.status_code == 400
    assert "username" in response.get_json()["message"].lower()

对应的 Playwright 测试：

def test_register_submit_error_should_show_message(page):
    page.goto("http://localhost:3000/register")
    page.fill("#username", "demo")
    page.fill("#password", "123456")
    page.click("#submit")
    expect(page.locator(".error-message")).to_be_visible()

这里需要说明一下：当前生成的是测试模板，不是对任意真实项目都能 100% 直接运行。真实落地时还需要根据项目的鉴权方式、fixture、接口地址和选择器做适配。

10. 项目目录

项目结构如下：

multimodal-bug-agent/
├── app.py
├── run_demo.py
├── requirements.txt
├── README.md
├── assets/
│   ├── demo.gif
│   └── architecture.png
├── docs/
├── eval/
│   ├── cases.json
│   ├── evaluate.py
│   └── results.md
├── examples/
├── prompts/
├── src/
│   ├── bug_reasoner.py
│   ├── code_locator.py
│   ├── code_parser.py
│   ├── llm_client.py
│   ├── log_parser.py
│   ├── multimodal_context.py
│   ├── report_generator.py
│   ├── screenshot_analyzer.py
│   ├── test_generator.py
│   ├── video_analyzer.py
│   └── vision_analyzer.py
├── tests/
└── tools/

其中几个核心文件：

文件	作用
app.py	Streamlit 页面入口
run_demo.py	命令行运行入口
bug_reasoner.py	缺陷分析主流程
log_parser.py	日志解析
code_locator.py	可疑代码定位
vision_analyzer.py	Qwen-VL 视觉分析
llm_client.py	DeepSeek 调用封装
test_generator.py	测试用例生成
report_generator.py	Bug 报告生成

11. 如何运行

项目地址：

https://github.com/jiuguandemao/multimodal-bug-agent

克隆项目：

git clone https://github.com/jiuguandemao/multimodal-bug-agent.git
cd multimodal-bug-agent

创建虚拟环境：

python -m venv .venv

安装依赖：

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

命令行运行：

.\.venv\Scripts\python.exe run_demo.py --case case_01_register_500

启用 DeepSeek 二次审查：

.\.venv\Scripts\python.exe run_demo.py --case case_01_register_500 --use-llm

启动页面：

.\.venv\Scripts\python.exe -m streamlit run app.py

浏览器打开：

http://localhost:8501

12. 评估结果

项目里提供了一个简单的评估脚本：

.\.venv\Scripts\python.exe eval\evaluate.py

当前内置 6 个可复现场景上的结果：

指标	结果
缺陷类型识别准确率	6/6 = 100.0%
Top-1 可疑文件命中率	4/6 = 66.7%
Top-3 可疑文件命中率	6/6 = 100.0%

这个评估集目前还是合成场景，主要用于验证 pipeline 是否完整。后续如果接入真实历史 Bug 数据，评估会更有说服力。

13. 一些取舍和不足

这个项目目前不是一个“万能自动修 Bug 系统”。

我现在更愿意把它定位成：

多模态证据融合 + 缺陷定位 + 测试生成的工程实践。

当前还有一些不足：

1. 代码定位主要还是关键词和规则打分，后续可以加入 AST 调用链和向量检索。
2. Demo 场景是可复现的合成场景，还需要更多真实项目数据。
3. 生成的测试用例是模板级别，真实运行需要适配项目 fixture 和 selector。
4. 录屏目前主要做关键帧抽取，后续可以结合 Playwright trace 做更完整的自动复现。

但这些不足也是后续可以继续扩展的方向。

---

14. 后续计划

后续准备继续补几个方向：

• 引入 FAISS / Chroma 做代码向量检索；
• 接入 Playwright trace，自动采集 console、network、screenshot；
• 增加更多真实 Bug 场景；
• 支持 Docker 部署；
• 做一个在线 Demo；
• 扩大 benchmark，统计更多指标；
• 增加 issue template 和 contribution guide。

---

15. 可以泛化到哪些场景

这个项目背后的方法其实可以迁移到别的方向：

多源证据抽取 ↓ 统一证据包 ↓ 规则/检索基线 ↓ LLM/VLM 增强 ↓ 结构化输出

类似方法可以用于：

场景	输入	输出
运维告警分析	监控图、日志、Trace、配置	根因分析、处理步骤
代码评审	PR diff、CI 日志、测试结果	风险点、测试建议
合同审核	PDF、图片、OCR 文本	风险点、审核报告
工业巡检	图片、视频、传感器数据	异常检测、整改建议
客服质检	工单、通话文本、截图	问题分类、改进建议

所以 MultiBug-Agent 本身是测试开发项目，同时也可以看作一个多模态 Agent 工程模板。

16. 总结

MultiBug-Agent 主要做了这样一件事：

把 Web Bug 排查里的截图、录屏、日志、代码和用户描述统一起来，结合 Qwen-VL、DeepSeek、日志解析和代码检索，生成可解释的缺陷报告和自动化测试用例。

它更偏工程实践，而不是算法训练项目。

我觉得它比较适合作为：

• 测试开发项目；
• AI 测试项目；
• 大模型应用项目；
• Python 工程化项目；

项目地址：

https://github.com/jiuguandemao/multimodal-bug-agent

如果这个项目对你有帮助，欢迎点 Star 或提 Issue 交流。