插件不启动的最常见原因是activationEvents配置错误；VS Code默认懒加载，需正确配置onCommand等事件确保插件激活，同时须防御性检查activeTextEditor是否为空，并在AI生成时传入完整上下文。
activationEvents 配置错，插件根本不会启动——这是你写完插件却始终没反应的最常见原因
为什么插件注册了命令却点不动？
插件代码写完了，package.json里也注册了 commands 和 menus，但右键菜单不出现、命令面板搜不到。问题大概率出在 activationEvents 上。
VS Code 默认懒加载插件，只有触发对应事件才会激活。如果你只写了 "onCommand:myext.generate"，但没在用户执行前让插件“醒过来”，那命令就永远卡在未激活状态。
- 常见错误：漏写
activationEvents字段，或只写onLanguage:python却在 JS 文件里测试 - 稳妥做法：至少加一条
"onCommand:your-ext-id.your-command"，确保命令能被触发 - 进阶场景：如果想一打开 Python 文件就预热插件，再补上
"onLanguage:python"，但注意这会增加启动开销
vscode.window.activeTextEditor 为空怎么办？
调用 vscode.window.activeTextEditor 获取当前编辑器时返回 null，多数是因为用户没聚焦在编辑器区域（比如光标在侧边栏、终端或设置页），或者插件在编辑器还没准备好时就执行了逻辑。
这不是 bug，是 VS Code 的正常行为。必须做防御性判断，否则整个命令会静默失败。
- 必须检查：
if (!editor) return，不能直接链式调用editor.document.getText() - 更安全的做法：用
vscode.window.onDidChangeActiveTextEditor监听切换，缓存最新 editor 实例 - 调试技巧：在
activate函数里加console.log('activated')，确认插件真被激活了
AI生成代码时如何传入上下文？
单纯把用户输入的自然语言当 prompt 发给模型，生成结果往往脱离项目实际——缺 import、变量名冲突、不兼容已有函数签名。关键是要把当前文件内容、光标位置、选中代码块、语言 ID、甚至 workspace root 路径一起打包过去。
Cline 插件这类方案之所以好用，不是因为模型强，而是上下文提取做得扎实。
- 必传字段：
document.getText()（全文）、editor.selection（选区）、editor.document.languageId（语言） - 建议字段：
vscode.workspace.workspaceFolders?.[0]?.uri.fsPath（项目根路径），用于推断依赖和配置 - 避坑点：不要直接拼接大段文本传给 API，先用
document.offsetAt(selection.start)算出光标偏移量，让模型知道“重点改这里”
本地调试时 vsce package 报错找不到模块？
用 vsce package 打包时报 Error: Cannot find module 'vscode' 或类似路径错误，本质是构建环境没区分开发依赖和运行时依赖。
VS Code 插件在调试时靠 vscode 这个假模块模拟 API，但打包时它不该被打包进去——它是宿主环境提供的。
- 检查
package.json的devDependencies是否包含vscode，且dependencies里绝对不能有它 - 确保
vsce package前已运行npm install --production，避免把 dev 依赖混进去 - 验证方式：解压生成的
.vsix，打开package.json查dependencies字段是否为空
