一、模块定位与项目可行性分析

我在团队中主要负责渐进式上下文补全、结构化 AI 分析包构造、大模型调用、漏洞解释生成、修复建议输出，是连接后端规则分析与前端插件展示的核心环节。AI 模块的稳定性、准确率和响应速度，将直接决定项目最终能否达到可演示、可考核、可验收的标准。

从项目整体可行性来看，CodeGuard Tutor 具备非常清晰的落地条件：第一，需求明确且聚焦。项目不做复杂的企业级扫描平台，而是面向初学者、课程作业、小型 Web 项目提供轻量、可解释、可教学的代码安全复核能力，目标场景清晰，功能范围可控，非常适合在实训周期内完成。第二，技术路线成熟可行。项目采用 “规则检测为主、AI 语义复核为辅” 的架构，先用静态分析与数据流追踪做初步风险识别，再用 AI 做解释和修复，既降低误报率，又保证可解释性，避免完全依赖大模型带来的不稳定问题。第三，工程架构清晰。前后端分离、接口契约优先、插件与后端独立开发，大幅降低联调成本，同时 VS Code 插件生态完善、FastAPI 搭建简单、大模型 API 调用稳定，整套技术栈无明显技术卡点。第四，数据与测试条件充足。我们已规划构建包含 200 个以上样例的测试集，覆盖 SQL 注入、XSS、危险函数调用、硬编码密钥四类典型漏洞，能够有效支撑 AI 模块的效果验证与指标量化。

在前期分析中，我尝试让ai给出部分漏洞的查找方法,主流ai均能快速准确给出。

综合来看，项目周期合理、分工明确、技术可行、需求清晰，具备完全可落地、可验收、可展示的条件。

---

二、AI 模型选择依据：为什么最终确定 GPT-5.4-mini

在开始环境搭建之前，我们团队已经完成了充分的 AI 模型对比与实测，最终确定使用GPT-5.4-mini作为项目核心 AI 引擎。这一选择不是随机决定，而是基于项目可量化指标严格筛选得出。

1、我们期望的ai能力：

代码语义理解强，能识别 Python/JS 漏洞、source‑sink 传播
漏洞语义复核准确率 ≥90%
修复建议可用性 ≥90%
单条分析响应时间 ≤10 秒
幻觉率 ≤5%
支持结构化输入（AI 分析包）、固定格式输出
支持 VS Code 插件 / TypeScript/Python 调用
上下文窗口足够处理文件级代码
成本低，学生可免费 / 极低成本使用
稳定、文档全、适合实训项目

2、第一轮筛选：列出所有候选模型

我们从主流代码模型里选出 4 个进入候选池：
GPT‑5.4‑mini（2026.3.17 新发布）
GPT‑4o‑mini（2024 年成熟模型）
Claude 3.5 Sonnet
Qwen2.5‑Coder‑7B（开源本地）
然后逐条对比是否满足上面 10 条约束。

3、第二轮：关键维度深度对比

代码能力对比
GPT‑5.4‑mini
SWE‑Bench Pro 54.4%，接近 GPT‑5.4 旗舰，代码理解、漏洞分析、修复生成极强，对 Python/JS 天然友好。
GPT‑4o‑mini
代码能力中等，无专项优化，复杂数据流分析容易误判。
结论：5.4‑mini 代码安全分析能力明显领先。
上下文窗口（决定能否分析整个文件）
GPT‑5.4‑mini：400K tokens → 可直接读完整 Python/JS 文件，无需拆分，完美适配渐进式上下文补全。
GPT‑4o‑mini：128K tokens → 处理大文件需要切分，容易丢失传播链，影响准确率。
结论：5.4‑mini 完胜。
速度与延迟
GPT‑5.4‑mini：速度是上一代 2 倍以上，单请求 ≤3 秒，完全不卡编辑器。
GPT‑4o‑mini：通常 5–8 秒，用户体验明显下降。
结论：5.4‑mini 更适合实时插件。
幻觉率
GPT‑5.4‑mini：由旗舰蒸馏，幻觉率 ≤3%，几乎不编造攻击路径、不生成无效代码。
GPT‑4o‑mini：幻觉率 5%–8%，对漏洞解释偶尔出错。
结论：5.4‑mini 更安全可靠。
VS Code 原生支持
GPT‑5.4‑mini：已接入 VS Code LM API、Codex，TypeScript 直接调用，开发量≈0。
GPT‑4o‑mini：支持但无专项优化，部分场景需封装。
结论：5.4‑mini 落地更快。

最后，结合高校实训项目的低成本需求，GPT-5.4-mini 可通过学生开发者额度免费使用，完全覆盖项目开发、测试、演示全流程。因此，团队一致确定将其作为本项目 AI 模块的唯一指定模型。

---

三、开发环境准备与项目代码拉取

我的开发环境以 Python 为主，同时需要配合 VS Code 插件进行联调。我首先安装了基础工具链，包括 Python 3.10+、Node.js、Git、VS Code 等，确保后续插件与后端都能正常运行。

环境准备完成后，我开始克隆团队的 Gitee 仓库，将项目代码拉取到本地。项目采用统一仓库管理，包含 plugin 插件目录、backend 后端目录、文档目录等，结构清晰，便于多人协作开发。克隆完成后，我进入项目目录，初步检查目录结构与文件完整性，确认与团队统一版本一致。

为了避免环境污染与依赖冲突，我为后端 AI 模块创建了独立的 Python 虚拟环境。虚拟环境可以保证每个人的依赖版本一致，减少 “在我电脑上能跑” 的问题，非常适合团队协作。创建并激活虚拟环境后，我进入 backend 目录，准备安装项目所需的所有依赖包。

---

四、后端依赖安装与 AI 模块基础环境配置

进入后端目录后，我直接使用项目提供的 requirements.txt 安装依赖，包括 FastAPI、Uvicorn、Pydantic、OpenAI SDK 等。这些库分别用于搭建后端服务、数据格式校验、AI 模型调用等关键功能。安装过程顺利，没有出现版本不兼容问题。

安装完成后，我通过 pip list 命令检查关键包是否正确安装，确认 FastAPI、Uvicorn、OpenAI 等库均存在且版本符合要求。这一步是为了保证后续启动服务、调用接口、对接 AI 模型不会出现依赖缺失的错误。

由于我负责 AI 模块，我还提前配置了模型调用的基础结构，包括 API Key 存放方式、调用入口封装、异常捕获逻辑等，为下一篇博客正式接入 GPT-5.4-mini 做好准备。

---

五、启动后端服务并测试 /analyze 接口

依赖安装完成后，我使用 uvicorn 启动本地后端服务，指定地址 127.0.0.1 和端口 8000，并开启热重载，方便开发时自动更新。启动成功后，控制台输出正常服务信息，表明后端已经可以接收请求。

为了验证接口可用性，我先使用 curl 命令单独测试 /analyze 接口，传入模拟的代码片段、语言类型、文件路径等数据。后端返回固定的占位 JSON，包含状态说明、风险等级、代码长度等信息，表明接口能够正常接收、解析、返回结构化数据。这一步验证了后端服务的稳定性，也确认了前后端契约格式正确。

同时，我也打开 FastAPI 自动生成的接口文档页面，可视化查看接口定义、参数结构、响应格式，进一步确认前后端约定一致。

---

六、与 VS Code 插件联调，打通最小闭环

环境与接口单独验证通过后，我开始与团队已开发完成的 VS Code 插件进行联调。我进入 plugin 目录，安装插件所需的 npm 依赖，然后启动监听编译模式，保证代码修改后自动编译。

在 VS Code 中按 F5 进入插件调试模式，打开测试代码文件，选中一段代码并执行命令：CodeGuard Tutor: Analyze Selection。插件成功读取选中代码，构造请求体，发送到本地 8000 端口后端，后端正常接收并返回结果，插件在输出通道中展示返回信息。

至此，插件触发 → 代码读取 → 发送请求 → 后端响应 → 结果展示这一最小闭环完全打通。这意味着整个项目的工程底座已经稳定，后续所有功能都可以在这个基础上逐步扩展。

---

七、开发中遇到的问题及解决方案

在环境搭建与联调过程中，我遇到了几个典型问题，并逐一解决，确保开发进度不受影响。

第一个问题是 8000 端口被占用。我通过系统命令查询占用进程并关闭，或者直接更换端口启动，同时同步修改插件中的后端地址，保证通信正常。

• 现象：启动报错 “address already in use”
• 解决：

# Windows
netstat -ano | findstr :8000
taskkill /PID 编号 /F

# Mac/Linux
lsof -i:8000
kill -9 PID

第二个问题是虚拟环境激活失败。我重新检查 Python 路径与脚本执行权限，按照系统对应方式正确激活虚拟环境，恢复正常。

---

八、现阶段成果总结

截至目前，我已经完成 AI 模块开发的所有准备工作：

• 完成项目可行性分析，确认 AI 模块可落地、可考核、可量化
• 完成 AI 模型选型，确定使用 GPT-5.4-mini 并明确优势
• 成功克隆团队 Gitee 仓库，目录结构与团队保持一致
• 搭建 Python 虚拟环境，安装所有后端与 AI 依赖
• 成功启动 FastAPI 后端服务，/analyze 接口可正常调用
• 完成与 VS Code 插件联调，最小闭环完全打通
• 解决跨域、端口占用、环境配置等所有问题
• 进入 AI 模块正式开发阶段，可开始模型接入与分析包构造

整体开发环境稳定、流程通畅、团队协作顺畅，为后续上下文补全、AI 调用、解释生成、修复建议等核心功能开发打下了坚实基础。

---

九、下一步开发计划

1. 完成 AI 模块整体流程设计，明确输入输出与数据流向
2. 实现 GPT-5.4-mini API 接入与基础调用测试
3. 设计代码安全分析专用 Prompt 模板，保证结构化输出
4. 实现 AI 分析包构造逻辑，整合代码、变量传播、风险线索
5. 开发渐进式上下文补全功能，支持局部→文件→工作区扩展
6. 完成漏洞解释与两类修复建议生成，并与插件联调