智能代码卫士：用AST在VSCode里实时检测TypeScript未覆盖分支

1. 为什么你的 TypeScript 项目总在 if/else 上翻车写 TypeScript 的人大多有过这种经历本地跑得好好的上线后某个边界值进来代码走进了一条从没被显式处理过的分支然后就是半夜爬起来看日志。问题不在于类型系统不够强而在于类型检查只回答“这个值是不是 string”它不回答“这条逻辑路径有没有被代码覆盖过”。传统做法是等tsc --noEmit或者跑一遍覆盖率报告但覆盖率是事后统计等你看到报告时 bug 可能已经发出去了。真正想要的是在编辑器里敲代码的当下光标停在某个if上就能知道这个分支的“另一条路”有没有被显式处理。这就是 AST 静态分析能做的事——它不依赖运行时直接读语法树结构判断if有没有else、switch有没有default、try有没有catch。这篇面向的是正在做 VSCode 插件开发、或者想给自己团队做一套编码期质量门禁的 TypeScript 工程师。我会从零拆一个叫 BranchGuard 的插件用 TypeScript Compiler API 解析 AST遍历节点找出未覆盖分支再通过 HoverProvider 在编辑器里实时告警。全程可复制配置片段和报错排查都会给全。如果你只是想快速验证模型对 AST 代码的理解可以先用 TaoToken 模型对话 把分析逻辑跑通再落到插件工程里。核心检索词先明确AST 实时检测 TypeScript 未覆盖分支指的是在编码阶段用抽象语法树静态识别缺失的 else/default 路径而不是等测试覆盖率报告。适合谁适合手里有中大型 TS 项目、分支逻辑多、又不想引入重型静态分析工具链的团队。2. TaoToken 前置准备把 AST 分析逻辑先跑通在动手写插件之前我建议先把“AST 遍历找未覆盖分支”这段纯逻辑单独验证一遍。原因很简单插件工程涉及package.json声明、激活事件、Provider 注册一旦报错你很难判断是分析逻辑错了还是插件配置错了。把分析函数抽出来用 Node 脚本直接跑能省掉大量排查时间。这一步需要两样东西一个能执行 TypeScript 的 Node 环境以及一个稳定的模型接口来帮你快速生成/校对 AST 遍历代码。TaoToken 在这里的角色是提供兼容 OpenAI 协议的 API 入口你可以把它当成一个统一的模型调用层用来生成ts.Visitor的遍历骨架、解释ts.isIfStatement这类 API 的返回值。它的 Base URL 是https://taotoken.net/apiKey 在控制台创建。具体操作先到 TaoToken API Keys 生成一个 Key然后在项目根目录建一个.env文件把 Key 写进去。注意不要提交到 git。接着用 curl 验证一下接口通不通curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-20250514, messages: [ {role: user, content: 用 TypeScript Compiler API 写一个函数遍历 AST 找出没有 else 的 if 语句返回位置数组} ] }如果返回里能看到choices[0].message.content带代码说明链路通了。这一步的意义是后面插件里findUncoveredBranches的遍历逻辑你可以先让模型生成一版再自己改。模型对ts.visitEachChild、ts.isSwitchStatement这些 API 的写法比较熟能帮你少查文档。需要提醒的是TaoToken 只是模型调用入口它不替代你的编辑器也不直接连你的生产数据库。插件工程本身还是跑在本地 VSCode 里。如果你打算长期做这类编码辅助工具可以考虑 TaoToken Coding Plan把模型调用额度固定下来避免调试时频繁换 Key。环境准备好后建一个最小验证脚本scripts/analyze.ts把分析函数先写出来跑通再进插件工程。这样第 3 章的配置你复制过去就能直接用。3. 可复制配置AST 遍历 插件激活 检测规则这一章是全文的技术核心分三块分析器代码、插件入口、规则配置。每一块都给完整可复制的片段路径和原文保持一致。先建目录结构vscode-branchguard/ ├── src/ │ ├── analyzer/ │ │ └── branchAnalyzer.ts │ └── extension.ts ├── package.json ├── tsconfig.json └── .vscodeignore第一块src/analyzer/branchAnalyzer.ts这是 AST 遍历的核心。它用 TypeScript Compiler API 创建 SourceFile然后用 Visitor 模式递归遍历识别两类问题没有 else 的 if、没有 default 的 switch。import * as ts from typescript; export interface BranchLocation { start: number; end: number; type: missing-else | missing-default; message: string; } export function findUncoveredBranches(sourceFile: ts.SourceFile): BranchLocation[] { const uncovered: BranchLocation[] []; const visitor: ts.Visitor (node: ts.Node): ts.VisitResultts.Node { if (ts.isIfStatement(node) !node.elseStatement) { uncovered.push({ start: node.getStart(), end: node.getEnd(), type: missing-else, message: 缺少 else 分支此 if 的否定路径未被显式处理, }); } if (ts.isSwitchStatement(node)) { const hasDefault node.caseBlock?.clauses.some((c) ts.isDefaultClause(c) ); if (!hasDefault) { uncovered.push({ start: node.getStart(), end: node.getEnd(), type: missing-default, message: 缺少 default 分支所有 case 之外的值未被处理, }); } } return ts.visitEachChild(node, visitor, ts.getProgram()!); }; ts.visitNode(sourceFile, visitor); return uncovered; }注意ts.getProgram()在纯脚本环境里可能为 null插件里因为有语言服务所以有值。如果你在独立脚本里跑把ts.visitEachChild的第三个参数换成undefined也能工作只是少了类型上下文。第二块src/extension.ts插件入口。它注册一个 HoverProvider当光标停在 TypeScript 文件里时实时解析当前文档并返回告警。import * as vscode from vscode; import * as ts from typescript; import { findUncoveredBranches } from ./analyzer/branchAnalyzer; export function activate(context: vscode.ExtensionContext) { const provider: vscode.HoverProvider { provideHover(document, position) { if (document.languageId ! typescript) return null; const text document.getText(); const sourceFile ts.createSourceFile( document.fileName, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS ); const branches findUncoveredBranches(sourceFile); const offset document.offsetAt(position); for (const branch of branches) { if (offset branch.start offset branch.end) { const md new vscode.MarkdownString(); md.appendMarkdown(**分支检测告警**\n\n${branch.message}\n\n); md.appendMarkdown(建议补充 else 或 default 显式处理边界路径); return new vscode.Hover(md); } } return null; }, }; context.subscriptions.push( vscode.languages.registerHoverProvider(typescript, provider) ); } export function deactivate() {}第三块package.json的 contributes 声明。这里要写全三件套激活事件、语言支持、配置项。{ name: vscode-branchguard, displayName: BranchGuard, version: 0.0.1, engines: { vscode: ^1.85.0 }, activationEvents: [onLanguage:typescript], main: ./out/extension.js, contributes: { configuration: { title: BranchGuard, properties: { branchguard.rules.requireElseForIf: { type: boolean, default: true, description: 要求 if 语句必须有 else 分支 }, branchguard.rules.requireDefaultForSwitch: { type: boolean, default: true, description: 要求 switch 语句必须有 default 分支 }, branchguard.ignorePatterns: { type: array, default: [\\.test\\.ts$, node_modules/], description: 忽略的文件路径模式 } } } } }tsconfig.json用标准配置即可关键是outDir指向out和main字段对应{ compilerOptions: { module: commonjs, target: ES2020, outDir: out, lib: [ES2020], sourceMap: true, rootDir: src, strict: true }, exclude: [node_modules, .vscode-test] }配置片段里出现的 Base URL、Key、Model ID 三件套在插件场景下指的是如果你想让插件调用模型做更复杂的语义判断可以在settings.json里配branchguard.api.baseUrl、branchguard.api.key、branchguard.api.model。Base URL 填https://taotoken.net/apiModel ID 填你控制台里可用的模型名。这三件套缺一不可否则请求会 401。4. 验证请求在编辑器里触发告警并确认分支被标记配置写完编译并加载插件。先跑编译npm install npm run compile然后在 VSCode 里按CtrlShiftP输入Developer: Install Extension from VSIX或者直接用 F5 启动扩展开发宿主窗口。在宿主窗口里打开一个.ts文件粘贴下面这段测试代码function getStatus(code: number): string { if (code 200) return OK; if (code 404) return Not Found; return Unknown; } function handleEvent(type: click | hover | scroll) { switch (type) { case click: return clicked; case hover: return hovered; } }把光标停在第一个if的if关键字上悬停。你应该看到黄色告警气泡内容是“缺少 else 分支此 if 的否定路径未被显式处理”。再把光标移到switch关键字上悬停看到“缺少 default 分支”。这里有个细节getStatus里虽然两个if都没写else但最后有return Unknown兜底逻辑上其实是覆盖了的。BranchGuard 当前版本只做结构判断不追踪控制流所以它会误报。这是静态分析的边界后面第 5 章会讲怎么用配置缓解。真正要验证的是handleEvent的switch——它确实没有default当type传入未列举的值时函数返回undefined这是真实风险。验证成功的标志有三个悬停出现告警、告警位置准确落在对应节点、修改代码后告警实时消失。你可以在handleEvent里加一行default: return unknown;保存再悬停switch告警应该立刻不见。这个“改完即消失”的反馈就是 AST 实时分析相比跑覆盖率报告的价值。如果你在验证时想确认模型对这段 AST 的理解是否准确可以把branchAnalyzer.ts贴到 TaoToken 模型对话 里让它解释ts.isIfStatement和node.elseStatement的判断逻辑对照自己的实现查漏。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth插件开发过程中最容易卡住的不是 AST 逻辑而是环境配置。下面按真实报错逐条排查。401 Unauthorized如果你在插件里集成了模型调用请求返回 401先检查三件套是否齐全。Base URL 必须是https://taotoken.net/apiKey 必须是从控制台创建的、未过期的Model ID 必须是账号下可用的。三者缺一或者 Key 里混入了空格、换行都会 401。排查方法用第 2 章的 curl 命令单独测curl 通了再查插件代码。local proxy failed这个报错通常出现在你本地配了网络代理但代理进程没启动或端口不对。VSCode 插件进程继承的是系统环境变量如果HTTP_PROXY指向一个不存在的端口请求就会失败。排查在终端echo $HTTP_PROXY看有没有值有的话临时unset再启动 VSCode。注意这里说的是本地开发环境的代理配置问题不涉及任何网络访问方式的选择。reading choices这个报错说明你拿到的响应体里没有choices字段代码却直接读了response.choices[0]。常见原因是接口返回了错误对象比如{error: {...}}或者返回的是流式响应但你没按流解析。排查先把原始响应console.log(JSON.stringify(response))打出来确认结构再取值。如果是流式要用for await逐块拼接。OAuth 相关报错如果你用的是需要 OAuth 授权的模型服务插件里没走完授权流程就会报 token 无效。TaoToken 的 API Key 方式是 Bearer Token不需要 OAuth 跳转所以直接用 Key 即可。如果你在别处见过 OAuth 报错检查是不是把两种鉴权方式混用了。另外如果你用了 CC Switch、Cline MCP 或 Codex 的auth.json记住它们都遵循同一套三件套逻辑Base URL、Key、Model ID。以auth.json为例{ baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet-4-20250514 }三个字段任何一个写错都会导致请求失败。Cline MCP 的配置同理在 MCP server 的 env 里把这三个值传进去。CC Switch 切换配置时确认切换后的 Base URL 没有多余斜杠。6. 从告警到修复把 BranchGuard 接进你的日常编码流插件跑通之后真正决定它有没有用的是你愿不愿意每天开着它。我的做法是把它和保存动作绑定在extension.ts里监听onDidSaveTextDocument保存时对当前文件跑一遍分析把未覆盖分支数量输出到状态栏。这样你不用主动悬停保存时扫一眼状态栏就知道这个文件有没有漏分支。状态栏代码片段const statusBar vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Right, 100); context.subscriptions.push(statusBar); vscode.workspace.onDidSaveTextDocument((doc) { if (doc.languageId ! typescript) return; const sourceFile ts.createSourceFile( doc.fileName, doc.getText(), ts.ScriptTarget.Latest, true, ts.ScriptKind.TS ); const branches findUncoveredBranches(sourceFile); statusBar.text branches.length 0 ? BranchGuard: ${branches.length} 处未覆盖 : BranchGuard: 通过; statusBar.show(); });再进一步把ignorePatterns用起来跳过测试文件和node_modules避免噪音。配置读取用vscode.workspace.getConfiguration(branchguard)在分析前先判断当前文件路径是否匹配忽略模式。最后说一个我踩过的坑AST 分析在超大文件上会卡。一个 3000 行的.ts文件每次悬停都重新createSourceFile会明显延迟。解决办法是加缓存——用WeakMapTextDocument, { version: number; branches: BranchLocation[] }文档版本号没变就复用上次结果。VSCode 的TextDocument.version会在每次编辑后自增用它做缓存键最准。这套东西做完你的编辑器就不只是语法检查器了它开始理解代码的“意图完整性”。下一步可以扩展规则检测try没有catch、检测Promise没有.catch、检测联合类型switch是否穷尽。每加一条规则都是在把编码期的质量门禁往前推一步。如果你要把这套逻辑做成团队共享的插件记得把模型调用的 Key 走环境变量别硬编码进package.json。