日期：2026-05-07
主题：多风险分项展示（后端 + 插件）/ 跨文件结果完整汇总 / Gitee 代码同步

---

1. 本次改动总览

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

实际上做的更多是完善工作。前期说要向git推送更新后的代码结果没推上，导致队友在旧版本上进行的开发，后面代码合并就出了不少问题，也算是吃一堑长一智吧。

本次主要完成四类工作：

1. 协作与仓库同步：从 Gitee 拉取远端更新并与本地分支合并，保证主线功能（后端分析、VS Code 插件）与团队协作进度一致，降低分叉带来的集成成本。
2. 手工测试资产：在 tests/cases/python/ 下新增「漏洞样例」目录，覆盖当前引擎支持的 SQLInjection、HardcodedSecret、DangerousFunction，并区分「跨文件入口 / 单文件聚合」两种用法，便于验证分析与插件流程。
3. 后端 API 增强：/analyze 返回的每条 RiskItem 增加「如何解决」聚合字段、带行号的原始片段、启发式「修改示例」；路由传入完整源码供切片与生成修复示例。
4. 插件体验：同一文件或跨文件分析命中多条风险时，输出面板逐条展示；跨文件补全结束后不再仅提示「首条」，而是汇总全部漏洞，并为每一条打开独立 Webview 详情页（同列多标签），同时将完整说明写入输出通道。

---

2. 协作与仓库同步（Gitee）

改动内容（进行合并）

• 使用 Gitee 对托管仓库执行 pull 与本地变更的 merge（或等价集成策略），将远端功能分支或主干的更新合入当前开发环境。但是很不幸git自动合并把我本地的跨文件上下文补全删了，于是进行返工。

做法问题

• 个人本地在第 4 份文档所述功能（跨文件补全、.gitignore 等）之上继续迭代时，需与团队远端保持一致，避免重复劳动与合并冲突堆积。本来期望的是合并后再提交「多风险展示 / 修复片段」等改动，便于 Code Review 与版本可追溯。
• 但是在合并的时候直接选择跟随仓库中文件了，没有保存自己的版本，导致了功能丢失。

说明

• 目前改回来了，会提交到git仓库上，大家直接拉取即可。

---

3. 按模块 / 文件维度说明

3.1 tests/cases/python/vulnerability_samples/（返工以及一些优化）

改动内容

• 新增跨文件演示入口 crossfile_entry.py：以 import 关联同级 fixture_*.py，本身不承载完整污点链，用于触发「当前文件无风险 → 跨文件补全」插件路径。
• 新增 fixture_sqli.py、fixture_secret.py、fixture_danger.py：分别在单文件内构成可命中的一类风险（注意 SQL 注入需满足引擎要求的「调用路径」，见《当前逻辑判断流程与可测试检测类型》）。
• 新增 single_file_all_risks.py：单文件内三类风险各一处，用于一次性验证 /analyze 多检测器合并结果。

为什么这样改

• 文档已写明当前不支持跨文件污点传播；跨文件能力体现在插件侧「发现关联文件并分别分析」。样例将「可命中」与「跨文件入口」拆开，测试意图清晰。

影响到的用户流程

• 开发者与验收人员可用固定样例回归「分析当前文件 / 跨文件补全 / 合并告警」行为。

---

3.2 backend/schemas/final_result_schema.py

改动内容

• RiskItem 新增可选展示字段（默认值避免破坏旧客户端）：
  • how_to_fix：合并 fix_minimal 与 fix_best 的可读说明；
  • original_snippet：带行号的源码片段；
  • fixed_snippet：启发式生成的修改示例（需人工复核）。

改动逻辑

• 同一文件多条告警时，插件需要结构化字段逐条展示「第几行、什么漏洞、怎么改、改写成什么样」，而不是仅靠摘要字符串。

---

3.3 backend/core/detectors/fix_snippet.py（新增）

改动内容

• 从完整源码中按 start_line/end_line 截取行并格式化为「行号 | 内容」。
• 按风险类型生成启发式 fixed_snippet（如单行 cursor.execute(f"...") 尝试改为参数化形态、password = "..." 改为 os.getenv 示例、eval/os.system 等给出替换思路）；无法可靠改写时退回通用模板。

改动逻辑

• 将「修复建议」从笼统文案推进到「可对照的示例代码」，仍保持规则引擎可控、不依赖外网大模型。原来版本的输出太笼统了，对初学者而言不直观没什么用，这部分后期应该还会再改，给出查看的选项。

风险与边界

• 复杂 SQL、多占位符、非常规 API 可能无法自动改写；模板仅供参考。

---

3.4 backend/core/detectors/result_converter.py

改动内容

• convert_intermediate_result_to_response 增加参数 source_code，在填充每条 RiskItem 时生成 how_to_fix、original_snippet、fixed_snippet。
• 若选中模式下源码切片与行号无法对齐，在 original_snippet 中返回中文提示而非空白。

---

3.5 backend/api/routes/analyze.py

改动内容

• 调用转换函数时传入 source_code=req.code，使每条风险都能映射到本次提交的源码文本。

---

3.6 backend/tests/test_detector_dispatcher.py

改动内容

• 转换层单测改为传入 req.code，并断言新字段（如 original_snippet 含行号、fixed_snippet 含关键关键字）。

---

3.7 vscode-extension/src/extension.ts

A) 主分析流程 Toast 与输出

改动内容

• 多条风险时 Toast 提示「共 N 条，详见输出面板」，避免只展示第一条的冗长摘要。
• formatRiskDetailZh 结构化输出：漏洞说明、如何解决、当前代码块、建议修改块；formatFirstRiskBriefZh 补充行号信息。

B) 跨文件补全结果汇总（在本日期基础上的增强）

改动内容

• 新增 flattenCrossFileRisks：将多个关联文件的 response.risks 全部展开为「文件路径 + 单条 risk」列表，不再只读取 riskHits[0]。
• 新增 showCrossFileRiskWebviewPanels：对展开后的每一条漏洞创建 createWebviewPanel，标题包含序号、中文类型、行号；HTML 内展示完整字段（含 how_to_fix、original_snippet、fixed_snippet）。
• 第一条 Webview 使用 ViewColumn.Beside，后续使用 ViewColumn.Active，使多个面板落在同一编辑器组内以标签页形式并存，实现「多个窗口（面板）一次性打开」。
• Webview Disposable 通过 extensionContext.subscriptions 注册，避免泄漏。
• activate 向 analyzeActiveEditor 传入 ExtensionContext，以便跨文件流程订阅面板。

为什么这样改

• 解决「跨文件只列出第一个漏洞」的问题；与输出面板逐条日志互为补充，便于对照源码标签页。

影响到的用户流程

• 跨文件检查结束后：输出通道中有按序编号的完整列表；编辑器区域出现 N 个 Webview 标签，每条漏洞一份完整可读报告。

关键代码

function flattenCrossFileRisks(
  riskHits: { filePath: string; response: Record<string, unknown> }[]
): { filePath: string; risk: Record<string, unknown> }[] {
  const out: { filePath: string; risk: Record<string, unknown> }[] = [];
  for (const hit of riskHits) {
    for (const r of extractRiskRecords(hit.response)) {
      out.push({ filePath: hit.filePath, risk: r });
    }
  }
  return out;
}

---

4. 本次「新增 / 强化能力」清单

• 后端：每条风险携带 如何解决、带行号原文、启发式修改示例。
• 插件：同文件多条风险时分条写入输出面板；Toast 与「首条摘要」策略调整。
• 插件：跨文件场景下 全量漏洞展开 + 每漏洞独立 Webview + 输出面板完整列表。
• 测试：vulnerability_samples 固定样例集，支撑手动与演示验收。
• 协作：Gitee 拉取合并，保持与远端仓库同步后再集成上述功能。

---

5. 使用流程

1. 后端：在仓库 backend 下执行 python -m unittest discover -s tests，确认 test_detector_dispatcher 等通过。
2. 单文件多风险：打开 tests/cases/python/vulnerability_samples/single_file_all_risks.py，执行「分析当前文件」，检查响应 JSON 中 risks 数组每条是否含 how_to_fix、original_snippet、fixed_snippet。
3. 插件输出：同上操作，展开「CodeGuard 导师」输出通道，确认多条风险分段清晰。
4. 跨文件：打开 crossfile_entry.py 先分析（无风险）→ 同意跨文件补全 → 确认输出面板列出所有展开项，且编辑器出现多个 Webview 标签、内容完整。
5. 协作：合并 Gitee 远端后再次编译插件 npm run compile、启动后端，做一轮冒烟分析。
   给出一些测试时的截图：
   
   
   
   
   

---

6. 总结

• 本次开发更多是教训，以后需要及时更新git仓库。
• 目前的文件内上下文补全和跨文件上下文补全都已经跑通了，在队友开发的几种漏洞检测中都表现得比较稳定。
• 这里简单说一下跨文件补全：原本是做的在打开项目，存在文件结构树的时候才会进行跨文件补全，但是初学者一般不会直接编写或者打开很大的项目，于是我就把逻辑改成了只要文件内检测不出来就弹出询问窗口，再依据import部分依次检测文件（不超过15个）。
• 另外一点就是输出，弹窗式的输出展示详细讲解不方便，我就改成了多个展示窗口，效果好一些。
• 后面会继续优化，可能会建立一个知识库来优化输出。