企业官网建设流程全解析

项目提交说明 / DGX Spark Hackathon

一、项目概述

Visual Troubleshooting Agent 是一个面向开发者故障排查场景的多模态自主调试智能体。项目目标不是让模型只“解释报错”，而是让智能体从截图或终端错误出发，完成问题理解、文件定位、代码读取、修复执行与结果验证，形成“理解—行动—反馈—再规划—验证”的完整闭环。

用户可以输入两类信息：一类是终端报错或 traceback 文本；另一类是错误截图。截图首先交由视觉模型识别软件环境、错误类型与可能原因，再将结构化诊断结果传入核心 Agent。核心 Agent 使用 StepFun Step-5-preview 进行任务规划与动作选择，并结合自定义 troubleshooting Skill 决定下一步是搜索项目、读取源码、修改文件，还是执行命令。每次工具执行结果都会重新返回给模型作为新证据，使 Agent 能根据真实结果调整下一步策略，而不是只进行单轮问答。

项目已经完成两类典型闭环测试：其一是缺少 Python 包时，Agent 能判断依赖问题、执行安装命令并验证导入是否成功；其二是 Python 源码逻辑错误，例如 `return sum(nums) / len` 导致 TypeError，Agent 能从错误截图中识别问题，在文件路径未知的情况下先搜索项目、读取候选源码、定位错误表达式、自动替换为 `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 SDK；DGX Spark 主要承担本地 Agent Runtime、工具执行环境以及本地视觉模型部署验证。后续可继续引入更完整的 NVIDIA 推理与服务化技术栈，对本地模型延迟、吞吐与资源占用进行优化。

六、模型与技术栈说明

• 核心推理模型：StepFun Step-5-preview，用于问题分析、动作规划、工具选择与多轮 Agent 决策。

• 视觉理解：当前 Demo 主流程使用 Qwen 视觉 API；DGX Spark 本地已部署并验证 Qwen2.5-VL（Ollama）可启动运行。

• 运行语言：Python。

• Agent 机制：自定义消息历史 + while 循环实现的迭代 Agent Loop。

• Skill：Markdown 形式的 `SKILL.md`，描述故障处理流程与工具调用策略。

• 工具：shell_tool、read_file、edit_file、verify_command。

• 本地执行：subprocess 命令执行、源码读取、精确文本替换与验证。

• API 兼容：Step Plan 通过 OpenAI 兼容 SDK 调用。

七、关键实现细节

1. 结构化动作协议：Step-5-preview 每轮返回 JSON，例如 action=run_command/read_file/edit_file/none。主程序解析后调用对应工具，避免自然语言与执行逻辑混在一起。

2. 工具反馈回灌：工具结果会追加到 messages 中，并重新请求模型。这样 Agent 可以根据真实 stdout、stderr、文件内容或编辑结果进行下一步推理。

3. 最小化代码修改：edit_file 使用 old/new 精确替换，仅修改确认过的代码片段，避免一次性重写整个文件。

4. 文件路径未知时的搜索：截图可能只包含错误信息而不含文件名。此时 Skill 规定禁止猜测路径，Agent 先通过 run_command 搜索项目，再读取候选文件。

5. 验证驱动结束：修改完成后执行 verify_command。只有验证返回成功、原错误消失时才输出 action=none 并结束任务。

八、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_from=333.1387.homepage.video_card.click