RK3588开发环境搭建三步曲：从零构建嵌入式Linux编译与烧录系统
2026/5/23 20:59:44
更新日期：2026-05-22
更新主题：学习资料上传与可配置解释来源（C 层解释增强初版）
一、更新概述
本次在既有B 阶段静态检测（Python：SQL 注入、硬编码密钥、危险函数）之上，落地了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 /analyze（B 阶段：检测 + result_converter） → 若 risks.length > 0 → 模态框选择 explanation_source → POST /enrich-explanations（C 层：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 | 实际使用的来源模式 |
| risks | enrich 后的风险列表（reason、how_to_fix 等已更新） |
| materials_used | 引用到的资料标题列表 |
| web_references_used | 引用到的公开参考标识（如 OWASP SQL Injection） |
插件侧 enrich URL 由 codeGuardTutor.backendUrl 推导：将/analyze替换为/enrich-explanations。
五、配置项
| 配置键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| codeGuardTutor.promptExplanationSource | boolean | true | 检出漏洞后是否弹出解释来源模态框 |
既有配置（backendUrl、requestTimeoutMs 等）保持不变。
六、交互与体验优化（同日修订）
初版使用顶部QuickPick选择来源，易被进度通知、输出面板抢焦点，用户反馈「看不到选项」。同日已调整为：
- 使用showInformationMessage + modal: true居中模态对话框
- 去掉第二步「是否生成详细说明」确认，选定来源后直接调用 enrich
- 未检出漏洞时在输出面板输出明确提示行
- 更新
插件启动方式.txt中的操作说明与样例路径
七、涉及文件清单
7.1 新增文件
| 路径 | 说明 |
|---|---|
backend/schemas/explain_schema.py | enrich 请求/响应与ReferenceMaterial模型 |
backend/core/context/__init__.py | C 层包入口 |
backend/core/context/explanation_service.py | 解释生成与资料匹配核心逻辑 |
backend/api/routes/explain.py | /enrich-explanations路由 |
backend/tests/test_explanation_service.py | 解释服务单元测试 |
vscode-extension/src/userMaterials.ts | 资料存储、上传/管理、来源选择 UI |
7.2 修改文件
| 路径 | 说明 |
|---|---|
backend/app.py | 注册explain_router |
vscode-extension/src/extension.ts | 注册新命令、分析后 enrich 流程、展示 enrich 元数据 |
vscode-extension/package.json | 新命令、新配置项、activationEvents |
插件启动方式.txt | 补充资料上传与解释来源选项说明 |
八、已知限制与后续方向
| 项目 | 说明 |
|---|---|
| 外网检索 | 「网上资源」为后端内置知识库，非实时联网 |
| LLM | 未接入大模型；解释以模板 + 资料摘录 + 关键词匹配为主 |
| 跨文件分析 | 跨文件补全检出漏洞后，暂未自动弹出解释来源选项（主分析路径已支持） |
| 上传时不解析 PDF，需用户自行转为文本 | |
| flow_trace | 完整传播链仍在 B 阶段内部，enrich 主要消费RiskItem已有字段 |
九、小结
本次更新完成了「用户资料 + 可选解释来源 → 漏洞说明与修改方案」的端到端闭环；教学场景下可先上传实验讲义，再在检出漏洞后按课程要求选择解释依据，提升说明与课程资料的一致性。后续可能会扩展：接入 API，在 explanation_service 中按 explanation_source 组装 prompt ；跨文件结果统一 enrich；Webview 展示引用段落 ；资料向量化检索（RAG）替代关键词匹配 。
目前智能支持文件内漏洞解答，跨文件还有点bug，输出也不好看。最近解决一下这些问题，下次博客应该会写这个方面。后面可能会尝试接入api连网查资料，先去平台上找点好用的大模型试试水。