VSCode需依赖插件实现Python注释自动填充，koroFileHeader是最佳选择：它严格按函数签名推导参数与类型（需Pylance支持），保存时自动更新时间戳，支持离线精准生成，而Copilot等AI工具易脱离上下文、无法保障时间同步。
VSCode 本身不自带 Python 注释自动填充功能，必须依赖插件实现；koroFileHeader 是目前最稳定、可配置性最强的选择，比 GitHub Copilot 或 Continue 的注释生成更精准、更可控，且完全离线运行，不上传代码。
为什么不用 Copilot 或 Continue 填充 Python 注释？
它们生成的注释往往脱离上下文：比如把 def calculate_total(items: list) -> float: 错误补全成 @param items: list of dicts，而实际传入的是 NamedTuple；或漏掉 @return 类型、参数文档空泛。更关键的是，它们无法保证每次保存都更新 @lastmodified 时间，团队协作中容易失效。
koroFileHeader 则严格按函数签名推导参数名和类型（需配合 Pylance），并支持保存时自动刷新时间戳，这是 AI 插件做不到的硬性保障。
安装与基础快捷键必须配对生效
仅安装插件不生效——必须确认快捷键未被其他插件占用，且语言模式识别正确：
立即学习“Python免费学习笔记（深入）”；
- 安装后重启 VSCode，或重载窗口（
Ctrl+Shift+P→ 输入Developer: Reload Window） - 新建一个
.py文件，确认右下角状态栏显示Python（不是Plain Text） - 默认快捷键：
Ctrl+Alt+I（文件头）、Ctrl+Alt+T（函数注释），若失效，检查是否被Tabnine或Continue拦截（它们常劫持Ctrl+Alt+T） - 可在
Ctrl+Shift+P中输入Preferences: Open Keyboard Shortcuts (JSON)手动绑定，例如：{"key": "ctrl+alt+t", "command": "koroFileHeader.cursorStart", "when": "editorTextFocus && editorLangId == 'python'"}
settings.json 关键配置项不能只抄模板
直接粘贴网上通用配置大概率导致函数注释为空或字段错乱。以下是 Python 场景下真正起作用的最小必要配置：
-
"fileheader.customMade"：必须显式写全字段，否则$description$等变量不渲染："fileheader.customMade": { "Author": "Your Name", "Date": "Do not edit", "LastEditTime": "Do not edit", "Description": "", "FilePath": "Do not edit" } -
"fileheader.configObj"中"autoadd"和"autoupdate"必须设为true，否则保存不更新时间 - Python 函数模板必须用
"fileheader.functionTemplate"单独定义，不能复用 JS 模板："fileheader.functionTemplate": { "content": "/**\n * @description: $description$\n * @param {${1:type}} $1 - $2\n * @return {${3:type}} $3\n */"}注意${1:type}是占位符语法，会被 Pylance 实际类型覆盖 - 禁用
"fileheader.cursorMode"（设为false），否则光标会跳到注释末尾，打断编码流
Python 特有坑：类型提示缺失会导致参数推导失败
koroFileHeader 依赖 Pylance 解析函数签名。如果函数没写类型提示，它只能靠字符串匹配猜参数名，极易出错：
- 错误示例：
def process(data):→ 注释里生成@param data -，无类型、无说明 - 正确做法：补全类型提示后重试：
def process(data: dict[str, int]) -> list[float]:→ 自动推导出@param {dict[str, int]} data和@return {list[float]} - 若项目不允许加类型提示，可在
settings.json中关闭自动推导："fileheader.functionParams": false，改用手动填写 - 虚拟环境未激活时，Pylance 可能无法加载第三方库类型（如
pd.DataFrame），此时需先在 VSCode 底部状态栏选对解释器
真正的难点不在装插件，而在让注释模板和你的代码风格、类型系统、团队规范三者咬合。一旦配错一个字段或忽略类型提示，生成的注释就变成噪音而非文档。
