继前两期博客梳理 CodeGuard Tutor 原型链路后，本期我们聚焦项目核心能力之一——“读取选中代码/读取当前文件”的工程实现，将其转化为“分析请求包（Analysis Input Pack）”的标准化构造问题。核心目标是解决 VS Code 前端选区语义与后端接口契约的协同一致性，为后续漏洞定位、代码高亮及 Explain 面板的精准联动奠定基础。

在安全复核场景中，“读取代码”绝非简单的文本提取，而是需要整合“文本内容+位置信息+语言类型+上下文元信息”的结构化输入。其中，位置信息的准确性尤为关键——它直接决定了后续漏洞定位的精准度、代码高亮的匹配度，以及 Explain 面板中证据链的可追溯性，是保障系统可解释性的核心前提。

一、Selection 读取：精准处理选区，实现行号语义对齐

我们在 analyzeActiveEditor() 方法中，完成了对 VS Code 编辑器选区的读取与约束校验，核心逻辑围绕“有效选区判断”与“行号映射”展开。

首先，方法会先校验当前是否存在活动编辑器，若不存在则弹出警告并终止流程；若存在，则获取编辑器的选区（selection）、选中代码（selectedCode）及文档信息。针对“选区分析”模式，我们增加了空选区约束——若用户选择该模式但未选中有效文本，将及时提示并终止，避免无效请求发送至后端。

关键代码片段如下：

async function analyzeActiveEditor(mode: AnalysisMode, output: vscode.OutputChannel): Promise<void> {
  const editor = vscode.window.activeTextEditor;
  if (!editor) {
    vscode.window.showWarningMessage("CodeGuard Tutor: No active editor.");
    return;
  }
 
  const document = editor.document;
  const selection = editor.selection;
  const selectedCode = document.getText(selection);
 
  if (mode === "selection" && !selectedCode.trim()) {
    vscode.window.showWarningMessage("CodeGuard Tutor: Please select code before analyzing selection.");
    return;
  }
 
  const language = normalizeLanguage(document.languageId);
  const code = mode === "selection" ? selectedCode : document.getText();
  const workspaceRoot = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
  const filePath = document.uri.fsPath;
}

在选区模式下，最关键的工程细节的是行号映射：VS Code 选区的行号采用 0-based 语义（从 0 开始计数），而后端接口契约中 cursor_range 的 start_line/end_line 采用 1-based 语义（从 1 开始计数）。因此，我们在构造请求包时，对选区的起始行和结束行进行了 +1 处理，确保前后端坐标系统一。

if (mode === "selection") {
  payload.cursor_range = {
    start_line: selection.start.line + 1,
    end_line: selection.end.line + 1
  };
}

这一处理并非简单的数值修正，而是前端工程细节与后端语义契约的关键衔接，直接决定了后续漏洞定位、代码高亮等功能的一致性，避免因坐标系差异导致的功能异常。

二、Language 归一：标准化语言输入，降低跨语言误判风险

后端接口对语言类型（language）的输入有明确要求，需为稳定的字符串取值。但 VS Code 的 languageId 存在多种变体（如 typescript、javascript 均属于 JS 家族），若直接传入后端，可能导致规则检测时出现非确定性误差。

为此，我们实现了 normalizeLanguage 方法，对 VS Code 的 languageId 进行归一化处理，将相似语言归类为后端可稳定识别的离散集合——例如将 typescript 与 javascript 统一归一为 javascript，同时保留 python 等核心语言的原始标识，未知语言则统一标记为“unknown”。

function normalizeLanguage(vscodeLanguageId: string): string {
  if (vscodeLanguageId === "javascript" || vscodeLanguageId === "typescript") {
    return "javascript";
  }
  if (vscodeLanguageId === "python") {
    return "python";
  }
  return vscodeLanguageId || "unknown";
}

从技术原理来看，这一步对应机器学习中的“特征标准化”思想——通过将输入空间映射到后端规则检测更易处理的范围，减少非必要的变量干扰，提升后续漏洞检测的准确性和稳定性。

三、Input Pack 构造：字段级对齐，打通前后端数据流转

结合上述处理，我们最终构造出符合后端契约的完整分析请求包（AnalysisRequest），包含 mode、language、file_path、code、workspace_root 五大核心字段，在选区模式下还会补充 cursor_range 字段。

前端构造代码如下：

const payload: AnalysisRequest = {
  mode,
  language,
  file_path: filePath,
  code,
  workspace_root: workspaceRoot
};

后端接口对应的请求模型（精简版）如下：

class AnalysisRequest(BaseModel):
    mode: Literal["selection", "file"]
    language: str
    file_path: str
    code: str
    workspace_root: Optional[str] = None
    cursor_range: Optional[CursorRange] = None

这种“字段级严格对齐”的设计，实现了前后端数据流转的无缝衔接：后端可根据 mode 字段判断是否需要利用 cursor_range 生成可定位的漏洞证据，前端则可依据同样的字段规则，决定是否触发代码高亮（Decorations）、漏洞提示（Problems）等定位逻辑，确保整个系统的协同一致性。

四、阶段开发进度总结

本阶段已顺利完成前端核心任务之一：实现了 VS Code 插件端对两种粒度输入（选区 selection、全文件 file）的精准读取，通过行号映射、语言归一化等工程处理，构建出完全符合后端契约的标准化分析请求包。

这一成果不仅解决了前后端数据协同的核心痛点，更为后续功能开发奠定了坚实的输入工程基础——后续我们将基于此，实现“渐进式上下文补全”与“风险定位映射”，让漏洞检测更精准、更具可解释性。

五、后续展望：从输入包到可定位风险

当后端完成漏洞检测并返回包含结构化 location 字段的响应后，下一阶段我们将聚焦前端展示与交互的完善，重点实现三大核心功能：

1. 将后端返回的 cursor_range/location 字段，精准映射到 VS Code 的 DiagnosticRange，实现漏洞位置的精准标记；

2. 根据漏洞的 type（类型）和 severity（严重程度），映射为不同的代码装饰风格，让用户直观区分漏洞等级；

3. 在 Webview 组件的 Explain 面板中，复用同一套证据链结构，实现漏洞解释的可追溯、可跳转，提升系统的可解释性。

后续我们将持续推进这部分功能开发，逐步完善 CodeGuard Tutor 的核心链路，让安全复核更高效、更精准。