项目提交说明 / DGX Spark Hackathon项目名称Visual Troubleshooting Agent核心能力多模态错误理解、Agent Loop、工具调用、自动修复、验证闭环核心模型StepFun Step-5-previewQwen 视觉模型Skillskills/troubleshooting/SKILL.md本地平台DGX Spark本地 Agent Runtime、工具执行、本地 Qwen2.5-VL 启动验证一、项目概述Visual Troubleshooting Agent 是一个面向开发者故障排查场景的多模态自主调试智能体。项目目标不是让模型只“解释报错”而是让智能体从截图或终端错误出发完成问题理解、文件定位、代码读取、修复执行与结果验证形成“理解—行动—反馈—再规划—验证”的完整闭环。用户可以输入两类信息一类是终端报错或 traceback 文本另一类是错误截图。截图首先交由视觉模型识别软件环境、错误类型与可能原因再将结构化诊断结果传入核心 Agent。核心 Agent 使用 StepFun Step-5-preview 进行任务规划与动作选择并结合自定义 troubleshooting Skill 决定下一步是搜索项目、读取源码、修改文件还是执行命令。每次工具执行结果都会重新返回给模型作为新证据使 Agent 能根据真实结果调整下一步策略而不是只进行单轮问答。项目已经完成两类典型闭环测试其一是缺少 Python 包时Agent 能判断依赖问题、执行安装命令并验证导入是否成功其二是 Python 源码逻辑错误例如 return sum(nums) / len 导致 TypeErrorAgent 能从错误截图中识别问题在文件路径未知的情况下先搜索项目、读取候选源码、定位错误表达式、自动替换为 len(nums)最后执行原程序并得到正确输出 2.0。该流程体现了 Agent Skills、工具调用、多模态理解与迭代反馈的融合。二、作品特点与核心亮点1. 多模态输入支持截图和文本两种故障输入方式。视觉模型负责从截图中提取错误类型、代码线索与可能原因降低用户手工复制 traceback 的成本。2. Skill 驱动的任务执行项目将故障处理策略独立写入 skills/troubleshooting/SKILL.md其中定义使用场景、工具选择规则、文件定位策略、视觉调试规则、迭代推理规则与验证要求使“如何排障”从主程序逻辑中解耦。3. 自定义 Agent Loop模型不是只生成一次答案。每次工具执行结果都会追加到上下文中由 Step-5-preview 再次判断下一步动作。若第一次假设错误Agent 可以根据失败结果重新搜索并继续执行。4. 自动代码定位与修复当截图没有提供可靠文件路径时Agent 不直接猜文件而是先使用 shell 搜索当前项目随后读取目标文件并确认代码内容再执行最小化文本替换。5. 自动验证代码修改后执行 verify_command只有验证成功后 Agent 才结束任务。若验证失败结果会进入下一轮推理从而形成可恢复的闭环。三、系统架构与执行流程整体流程如下截图 / 文本错误↓视觉理解截图模式/ 错误解析文本模式↓Step-5-preview 核心 Agent↓Troubleshooting Skill 约束与策略↓动作选择run_command / read_file / edit_file / none↓本地工具执行↓工具结果反馈给 Agent↓重新规划下一步动作↓验证成功后结束这种架构的关键不是某一个模型单独完成任务而是将视觉感知、LLM 推理、Skill 规则与本地工具执行连接成可迭代的任务系统。四、Agent Skill 设计Troubleshooting Skill 是项目的行为规范层。当前 Skill 主要包含以下设计• 使用条件错误截图、终端报错、Python 环境问题、源码运行时错误。• 工具规则环境问题优先 run_command文件未知时先搜索文件已定位但代码上下文不足时使用 read_file确认错误代码后再使用 edit_file。• 文件位置策略禁止猜测文件路径必须以搜索结果或可见 traceback 为证据编辑前确认目标文件与原始代码。• 视觉调试策略从截图中提取错误信息、文件路径和代码片段若截图信息不足则进入项目搜索流程。• 迭代推理规则每次工具执行结果都作为新证据失败后重新规划仅在问题验证解决后结束。• 输出规范Agent 仅返回结构化 JSON包括 analysis、action、command、file、old、new、verify_command 等字段便于程序稳定解析与执行。五、部署说明与 DGX Spark 本地算力使用项目开发与运行环境位于 DGX Spark 服务器智能体主程序、文件搜索、源码读取、代码修改、命令执行与验证均在本地项目环境中完成。该模式使故障处理过程能够直接作用于开发者当前工作区不需要把整个代码仓库上传到外部服务。视觉侧目前主流程采用 Qwen 视觉 API 以保证比赛 Demo 的稳定性同时已在 DGX Spark 上通过 Ollama 下载并成功启动本地 Qwen2.5-VL 模型完成本地视觉模型运行验证。后续可以将 qwen_vision.py 抽象为 provider 层在 API 与本地 Qwen2.5-VL 之间切换从而进一步提升隐私性、离线能力与对 DGX Spark 本地算力的利用率。当前版本没有额外依赖复杂的 NVIDIA SDKDGX Spark 主要承担本地 Agent Runtime、工具执行环境以及本地视觉模型部署验证。后续可继续引入更完整的 NVIDIA 推理与服务化技术栈对本地模型延迟、吞吐与资源占用进行优化。六、模型与技术栈说明• 核心推理模型StepFun Step-5-preview用于问题分析、动作规划、工具选择与多轮 Agent 决策。• 视觉理解当前 Demo 主流程使用 Qwen 视觉 APIDGX Spark 本地已部署并验证 Qwen2.5-VLOllama可启动运行。• 运行语言Python。• Agent 机制自定义消息历史 while 循环实现的迭代 Agent Loop。• SkillMarkdown 形式的 SKILL.md描述故障处理流程与工具调用策略。• 工具shell_tool、read_file、edit_file、verify_command。• 本地执行subprocess 命令执行、源码读取、精确文本替换与验证。• API 兼容Step Plan 通过 OpenAI 兼容 SDK 调用。七、关键实现细节1. 结构化动作协议Step-5-preview 每轮返回 JSON例如 actionrun_command/read_file/edit_file/none。主程序解析后调用对应工具避免自然语言与执行逻辑混在一起。2. 工具反馈回灌工具结果会追加到 messages 中并重新请求模型。这样 Agent 可以根据真实 stdout、stderr、文件内容或编辑结果进行下一步推理。3. 最小化代码修改edit_file 使用 old/new 精确替换仅修改确认过的代码片段避免一次性重写整个文件。4. 文件路径未知时的搜索截图可能只包含错误信息而不含文件名。此时 Skill 规定禁止猜测路径Agent 先通过 run_command 搜索项目再读取候选文件。5. 验证驱动结束修改完成后执行 verify_command。只有验证返回成功、原错误消失时才输出 actionnone 并结束任务。八、Demo 演示案例演示案例为一个 Python TypeError。原始代码为return sum(nums) / len运行后出现TypeError: unsupported operand type(s) for /: int and builtin_function_or_method演示时仅提供报错截图并刻意不让截图包含可靠的目标文件路径。系统首先由视觉模型识别错误原因随后 Agent 发现文件路径未知调用搜索命令定位 bug_demo.py再读取文件确认实际代码随后调用 edit_file将错误表达式改为 return sum(nums) / len(nums)最后执行 python bug_demo.py得到输出 2.0。验证成功后 Agent 自动结束任务。该案例能够集中展示本项目的核心能力多模态理解、文件搜索、工具调用、自动修复、工具反馈与闭环验证。九、优化方案与后续方向1. 本地视觉模型切换将当前 Qwen API 视觉模块抽象为统一 Vision Provider支持 Qwen API 与 DGX Spark 本地 Qwen2.5-VL 一键切换。2. 更安全的执行沙箱当前 shell_tool 仍允许较自由的命令执行后续应增加命令白名单、路径限制、dry-run 与人工确认机制。3. AST 级代码修改当前 edit_file 采用精确文本替换后续可升级为 AST/语法树级补丁提高复杂代码修改的鲁棒性。4. 多文件故障分析支持跨文件调用链、配置文件与依赖关系分析。5. 评测体系构建包含依赖错误、运行时错误、路径错误与简单逻辑错误的测试集统计 repair success rate、平均工具调用轮数与平均修复时间。6. 本地推理优化进一步利用 DGX Spark 本地 GPU 对视觉模型或 Agent 模型进行本地部署和性能优化减少云端依赖。• GitHub / 开源项目链接GitHub - milkiller/visual-troubleshooting-agent · GitHub• Demo 视频链接B站https://www.bilibili.com/video/BV164aJ6MEUT/?spm_id_from333.1387.homepage.video_card.click