如何为VSCode创建适配自研Python库的自定义Python Intellisense

VSCode的Python智能感知默认由Pylance语言服务器驱动，自研库无法触发补全、提示的问题，按实现成本从低到高可选择以下方案，绝大多数场景不需要从零开发完整扩展即可解决。

低配置成本方案（优先尝试，覆盖90%常规场景） #

• 校准解释器与扫描路径
  首先确认VSCode左下角选中的Python解释器，是你安装了自研库的目标环境（虚拟环境/Conda环境/系统环境均可）。如果是本地未打包发布的源码库，直接在项目根目录的.vscode/settings.json中添加库的根路径到Pylance的扫描列表：

  {
    "python.analysis.extraPaths": [
      "./your_custom_lib_root"
    ]
  }
  

  配置完成后按Ctrl+Shift+P调出命令面板，执行Python: Restart Language Server重启语言服务即可生效。
• 补全合规类型标注
  如果自研库代码没有遵循PEP484规范写类型注解，Pylance无法静态推断函数参数、返回值、类属性的类型，自然无法输出精准提示。只需要给对外暴露的API补上对应类型注解，不需要额外开发即可获得原生级别的补全体验。
• 生成类型存根文件
  如果你不想侵入原有业务代码，或者自研库包含C扩展等无法直接静态扫描的编译产物，可以用mypy内置的stubgen工具自动生成类型存根（.pyi文件）：

  # 先安装依赖
  pip install mypy
  # 为目标库生成存根文件，输出到./stubs目录
  stubgen -o ./stubs your_custom_lib_name
  

  生成的存根文件只保留类结构、函数签名、类型信息，把存根目录加到前面提到的python.analysis.extraPaths配置中，Pylance会优先读取存根信息生成提示。对于元编程动态生成、静态扫描不到的API，也可以直接手动编辑.pyi文件补充对应签名，补全效果和原生代码一致。

中等定制方案（适配动态API、自定义诊断需求） #

如果你的库存在大量运行时动态生成的逻辑，或者需要自定义语法校验规则，不需要开发完整扩展即可实现：

• 手动维护存根文件补充动态API：对于运行时通过元类、装饰器动态挂载的方法、属性，直接在对应位置的.pyi文件中声明其签名、参数说明、文档字符串，Pylance会直接读取这些声明输出提示。
• 自定义诊断规则：在项目根目录编写pyrightconfig.json配置文件，针对自研库的特定调用约束自定义错误、警告规则，即可实现类似原生语法提示的校验效果。

深度定制方案（开发专属VSCode扩展） #

如果上述方案无法满足需求（比如需要结合运行时上下文做动态补全、专属重构能力、自定义代码片段联动），可以按以下步骤开发扩展：

• 初始化扩展项目：全局安装yo和generator-code，执行yo code选择TypeScript扩展模板生成项目骨架。
• 注册补全提供者：通过VSCode内置APIvscode.languages.registerCompletionItemProvider注册Python语言的补全处理器，在provideCompletionItems方法中实现自定义补全逻辑——可以搭配后台常驻的LSP服务，实时读取自研库的运行时状态返回动态补全项、悬浮提示、跳转定位信息。
• 复用Python扩展能力：官方Python扩展暴露了公共API，可以直接获取当前激活的解释器信息、已安装包列表、Pylance已有的分析结果，不需要重复实现Python环境探测、基础语法分析的逻辑。
• 打包使用：开发完成后用vsce工具打包为.vsix本地安装包，即可在团队内分发使用。

注意：绝大多数自研库补全失效的问题，都是路径配置错误、缺少类型标注导致的，优先尝试低配置成本方案即可解决，直接开发扩展会带来长期的维护成本，非必要不选择。

内容的提问来源于stack exchange，提问作者Aravind B