摘要为实现“在编辑器内完成安全复核与教学式解释”的目标本文以 CodeGuard Tutor 为对象围绕 VS Code 扩展层与本地 FastAPI 后端之间的最小可行接口进行原型搭建。核心思想是契约驱动开发Contract-First先固定扩展激活与命令入口再统一后端请求字段确保前端插件能够在独立运行窗口中触发分析并获得结构化响应从工程层面降低后续引入 Problems/高亮/Webview 的复杂度风险。1. 问题定义在研究与工程的交汇场景中“能启动、能触发、能请求、能展示”属于最小闭环Minimum Loop。只有最小闭环稳定后才谈得上源-汇追踪、渐进式上下文补全与 AI 语义复核。因此成员 A 的第一个开发任务并非直接做漏洞识别而是先将“扩展生命周期 命令触发 后端通信通道”搭建成可验证系统。2. 方法以激活事件与命令入口为中心的扩展生命周期设计VS Code 扩展的激活并不是必然发生而是由 activationEvents 触发。因此本原型通过命令注册来建立可观测入口用户在命令面板触发分析时扩展必须被激活并执行网络请求。核心配置片段如下package.json{ main: ./out/extension.js, contributes: { commands: [ { command: codeguardTutor.analyzeSelection, title: CodeGuard Tutor: Analyze Selection }, { command: codeguardTutor.analyzeCurrentFile, title: CodeGuard Tutor: Analyze Current File } ], configuration: { title: CodeGuard Tutor, properties: { codeGuardTutor.backendUrl: { type: string, default: http://127.0.0.1:8000/analyze, description: Backend analyze endpoint URL. }, codeGuardTutor.requestTimeoutMs: { type: number, default: 15000, minimum: 1000, description: Request timeout in milliseconds for backend calls. } } } }, scripts: { compile: tsc -p ./, watch: tsc -watch -p ./, vscode:prepublish: npm run compile }, devDependencies: { types/node: ^22.10.1, types/vscode: ^1.90.0, typescript: ^5.7.2 } }激活事件与命令的绑定关系体现在activationEvents: [ onCommand:codeguardTutor.analyzeSelection, onCommand:codeguardTutor.analyzeCurrentFile ],3. 关键实现命令回调与后端通信的最小闭环在扩展代码 extension.ts 中activate() 负责注册命令并把执行权交给 analyzeActiveEditor() 从而将“UI 触发”和“分析请求构造”解耦export function activate(context: vscode.ExtensionContext): void { const output vscode.window.createOutputChannel(CodeGuard Tutor); context.subscriptions.push(output); context.subscriptions.push( vscode.commands.registerCommand(codeguardTutor.analyzeSelection, async () { await analyzeActiveEditor(selection, output); }) ); context.subscriptions.push( vscode.commands.registerCommand(codeguardTutor.analyzeCurrentFile, async () { await analyzeActiveEditor(file, output); }) ); }此处的研究含义在于对扩展层而言网络通信是“外部世界”的不确定对象应通过统一输出通道 OutputChannel 提供可观测性对用户体验而言命令触发必须及时返回并呈现成功/失败状态。4. 与后端契约的对齐策略后端采用固定的请求模型AnalysisRequest。其字段结构精简版如下class AnalysisRequest(BaseModel): mode: Literal[selection, file] language: str file_path: str code: str workspace_root: Optional[str] None cursor_range: Optional[CursorRange] None后端分析端点当前是 scaffold占位返回便于在早期完成端到端验证router.post(/analyze) def analyze(req: AnalysisRequest): return { summary: Backend is alive, risk_level: suspicious, received_language: req.language, received_file: req.file_path, code_length: len(req.code) }因此扩展层不需要在当前阶段理解漏洞逻辑只需保证输入字段正确映射即可.5. 实验结果与开发进度经过本轮开发“扩展可创建 可在 Extension Development Host 启动 命令可触发 后端可返回 JSON”这一最小闭环已完成。对后续“Problems/高亮/Webview”的引入这一步提供了稳定的“请求-响应基线”。6. 展望下一阶段可在该基线之上扩展1.将后端返回 risks/findings 映射到 Diagnostics2.引入 Webview 结构化解释面板最终形成风险-解释-修复的闭环
面向可解释安全复核的 VS Code 扩展原型构建——从可启动到接口契约驱动
发布时间：2026/6/27 4:57:06
摘要为实现“在编辑器内完成安全复核与教学式解释”的目标本文以 CodeGuard Tutor 为对象围绕 VS Code 扩展层与本地 FastAPI 后端之间的最小可行接口进行原型搭建。核心思想是契约驱动开发Contract-First先固定扩展激活与命令入口再统一后端请求字段确保前端插件能够在独立运行窗口中触发分析并获得结构化响应从工程层面降低后续引入 Problems/高亮/Webview 的复杂度风险。1. 问题定义在研究与工程的交汇场景中“能启动、能触发、能请求、能展示”属于最小闭环Minimum Loop。只有最小闭环稳定后才谈得上源-汇追踪、渐进式上下文补全与 AI 语义复核。因此成员 A 的第一个开发任务并非直接做漏洞识别而是先将“扩展生命周期 命令触发 后端通信通道”搭建成可验证系统。2. 方法以激活事件与命令入口为中心的扩展生命周期设计VS Code 扩展的激活并不是必然发生而是由 activationEvents 触发。因此本原型通过命令注册来建立可观测入口用户在命令面板触发分析时扩展必须被激活并执行网络请求。核心配置片段如下package.json{ main: ./out/extension.js, contributes: { commands: [ { command: codeguardTutor.analyzeSelection, title: CodeGuard Tutor: Analyze Selection }, { command: codeguardTutor.analyzeCurrentFile, title: CodeGuard Tutor: Analyze Current File } ], configuration: { title: CodeGuard Tutor, properties: { codeGuardTutor.backendUrl: { type: string, default: http://127.0.0.1:8000/analyze, description: Backend analyze endpoint URL. }, codeGuardTutor.requestTimeoutMs: { type: number, default: 15000, minimum: 1000, description: Request timeout in milliseconds for backend calls. } } } }, scripts: { compile: tsc -p ./, watch: tsc -watch -p ./, vscode:prepublish: npm run compile }, devDependencies: { types/node: ^22.10.1, types/vscode: ^1.90.0, typescript: ^5.7.2 } }激活事件与命令的绑定关系体现在activationEvents: [ onCommand:codeguardTutor.analyzeSelection, onCommand:codeguardTutor.analyzeCurrentFile ],3. 关键实现命令回调与后端通信的最小闭环在扩展代码 extension.ts 中activate() 负责注册命令并把执行权交给 analyzeActiveEditor() 从而将“UI 触发”和“分析请求构造”解耦export function activate(context: vscode.ExtensionContext): void { const output vscode.window.createOutputChannel(CodeGuard Tutor); context.subscriptions.push(output); context.subscriptions.push( vscode.commands.registerCommand(codeguardTutor.analyzeSelection, async () { await analyzeActiveEditor(selection, output); }) ); context.subscriptions.push( vscode.commands.registerCommand(codeguardTutor.analyzeCurrentFile, async () { await analyzeActiveEditor(file, output); }) ); }此处的研究含义在于对扩展层而言网络通信是“外部世界”的不确定对象应通过统一输出通道 OutputChannel 提供可观测性对用户体验而言命令触发必须及时返回并呈现成功/失败状态。4. 与后端契约的对齐策略后端采用固定的请求模型AnalysisRequest。其字段结构精简版如下class AnalysisRequest(BaseModel): mode: Literal[selection, file] language: str file_path: str code: str workspace_root: Optional[str] None cursor_range: Optional[CursorRange] None后端分析端点当前是 scaffold占位返回便于在早期完成端到端验证router.post(/analyze) def analyze(req: AnalysisRequest): return { summary: Backend is alive, risk_level: suspicious, received_language: req.language, received_file: req.file_path, code_length: len(req.code) }因此扩展层不需要在当前阶段理解漏洞逻辑只需保证输入字段正确映射即可.5. 实验结果与开发进度经过本轮开发“扩展可创建 可在 Extension Development Host 启动 命令可触发 后端可返回 JSON”这一最小闭环已完成。对后续“Problems/高亮/Webview”的引入这一步提供了稳定的“请求-响应基线”。6. 展望下一阶段可在该基线之上扩展1.将后端返回 risks/findings 映射到 Diagnostics2.引入 Webview 结构化解释面板最终形成风险-解释-修复的闭环
