更新日期2026-05-22更新主题学习资料上传与可配置解释来源C 层解释增强初版一、更新概述本次在既有B 阶段静态检测PythonSQL 注入、硬编码密钥、危险函数之上落地了C 层解释增强的第一版能力用户可在插件中上传自己的学习资料在分析检出漏洞后通过模态对话框选择解释所依据的资料来源由后端生成更完整的中文漏洞说明与修改方案。该能力不改变漏洞检测规则本身而是在 /analyze 返回结果之后通过新接口 /enrich-explanations 对 RiskItem 的 reason、how_to_fix 等字段进行二次 enrich。二、新增功能2.1 插件学习资料管理命令说明CodeGuard 导师上传学习资料从本地选择 .txt / .md 等文本文件上传PDF 会提示先转为文本CodeGuard 导师管理学习资料查看已上传资料列表支持删除资料保存在插件全局状态globalState键名 codeguard.referenceMaterials上限最多20份单份内容约10 万字符每条资料包含id、title、content、uploadedAt管理学习资料2.2 插件检出漏洞后的解释来源选择分析命令选中片段 / 当前文件在至少检出 1 条漏洞且配置项 codeGuardTutor.promptExplanationSource 为 true默认时会弹出居中模态对话框三选一① 仅根据我上传的资料— 从已上传文本中按漏洞类型关键词匹配段落生成说明② 参考我的资料与网上资源— 合并上传资料与内置公开安全知识③ 仅参考网上资源— 仅使用后端内置 OWASP/CWE 风格知识不发起外网请求用户也可选择「跳过使用引擎默认说明」保留 B 阶段转换后的原始文案。说明若本次分析未检出任何漏洞不会出现该对话框输出面板会提示可使用样例文件验证。2.3 后端解释 enrich 服务新增路由POST /enrich-explanations输入漏洞列表、源码片段、解释来源模式、可选参考资料列表输出enrich 后的 risks以及 materials_used、web_references_used 元数据实现模块backend/core/context/explanation_service.py资料匹配逻辑离线按漏洞类型SQLInjection、HardcodedSecret、DangerousFunction 等维护关键词表对上传资料标题与正文打分选取相关段落摘录约数百字无关键词命中时可回退使用首份资料的前几段网上资源离线内置按风险类型映射 OWASP/CWE 风格说明与修复建议当前为本地字典非实时爬取或调用外部 API降级策略选择「仅根据上传资料」但未上传任何资料时自动降级为网上资源避免返回空解释三、架构与数据流用户执行分析命令 → POST /analyzeB 阶段检测 result_converter → 若 risks.length 0 → 模态框选择 explanation_source → POST /enrich-explanationsC 层explanation_service → 合并 enrich 后的 risks 写回响应 → 输出面板 / Toast 展示与《开发框架契约》中A / B / C 分层对齐A插件资料 CRUD、来源选择、展示 enrich 结果B检测无改动仍由 dispatch_analysis convert_intermediate_result_to_response 完成C解释本次新增core/context/由 analyze 与 enrich-explanations 分步编排四、接口说明4.1POST /enrich-explanations请求体JSON示例{explanation_source:materials_and_web,reference_materials:[{id:uuid,title:实验三 SQL 安全,content:本章要求使用参数化查询……,uploaded_at:2026-05-22T10:00:00.000Z}],risks:[/* AnalyzeResponse.risks 中的 RiskItem 列表 */],source_code:……,language:python,file_path:/path/to/file.py}explanation_source 枚举值含义materials_only仅引用上传资料materials_and_web上传资料 内置公开知识web_only仅内置公开知识响应体字段字段说明explanation_source实际使用的来源模式risksenrich 后的风险列表reason、how_to_fix 等已更新materials_used引用到的资料标题列表web_references_used引用到的公开参考标识如 OWASP SQL Injection插件侧 enrich URL 由 codeGuardTutor.backendUrl 推导将/analyze替换为/enrich-explanations。五、配置项配置键类型默认值说明codeGuardTutor.promptExplanationSourcebooleantrue检出漏洞后是否弹出解释来源模态框既有配置backendUrl、requestTimeoutMs 等保持不变。六、交互与体验优化同日修订初版使用顶部QuickPick选择来源易被进度通知、输出面板抢焦点用户反馈「看不到选项」。同日已调整为使用showInformationMessage modal: true居中模态对话框去掉第二步「是否生成详细说明」确认选定来源后直接调用 enrich未检出漏洞时在输出面板输出明确提示行更新插件启动方式.txt中的操作说明与样例路径七、涉及文件清单7.1 新增文件路径说明backend/schemas/explain_schema.pyenrich 请求/响应与ReferenceMaterial模型backend/core/context/__init__.pyC 层包入口backend/core/context/explanation_service.py解释生成与资料匹配核心逻辑backend/api/routes/explain.py/enrich-explanations路由backend/tests/test_explanation_service.py解释服务单元测试vscode-extension/src/userMaterials.ts资料存储、上传/管理、来源选择 UI7.2 修改文件路径说明backend/app.py注册explain_routervscode-extension/src/extension.ts注册新命令、分析后 enrich 流程、展示 enrich 元数据vscode-extension/package.json新命令、新配置项、activationEvents插件启动方式.txt补充资料上传与解释来源选项说明八、已知限制与后续方向项目说明外网检索「网上资源」为后端内置知识库非实时联网LLM未接入大模型解释以模板 资料摘录 关键词匹配为主跨文件分析跨文件补全检出漏洞后暂未自动弹出解释来源选项主分析路径已支持PDF上传时不解析 PDF需用户自行转为文本flow_trace完整传播链仍在 B 阶段内部enrich 主要消费RiskItem已有字段九、小结本次更新完成了「用户资料 可选解释来源 → 漏洞说明与修改方案」的端到端闭环教学场景下可先上传实验讲义再在检出漏洞后按课程要求选择解释依据提升说明与课程资料的一致性。后续可能会扩展接入 API在 explanation_service 中按 explanation_source 组装 prompt 跨文件结果统一 enrichWebview 展示引用段落 资料向量化检索RAG替代关键词匹配 。目前智能支持文件内漏洞解答跨文件还有点bug输出也不好看。最近解决一下这些问题下次博客应该会写这个方面。后面可能会尝试接入api连网查资料先去平台上找点好用的大模型试试水。
