必须安装python docstring generator（id：njpwerner.autodocstring），而非autodocstring；前者依赖快捷键触发、支持google/numpy风格细粒度配置，后者为输入"""后回车自动补全，二者行为逻辑不同且配置项互不兼容。
确认你装的是 Python Docstring Generator 而不是 AutoDocstring
这两个扩展名字接近、作者相同（Nils Werner），但行为逻辑不同：Python Docstring Generator 依赖快捷键触发，AutoDocstring 是输入 """ 后回车自动补全。如果你想要「明确按快捷键生成」+「支持 Google/NumPy 风格细粒度控制」，必须安装前者，否则后续配置无效。
常见错误现象：装了 AutoDocstring 却去搜 python.docstringGenerator.style 设置项，结果找不到——因为那是给官方 Python 扩展或 Python Docstring Generator 用的。
- 在扩展市场搜索
Python Docstring Generator，认准 ID 是njpwerner.autodocstring（注意不是adamcharnock.autodocstring） - 安装后重启 VSCode，确保右下角语言模式显示为
Python - 检查是否冲突：禁用
AutoDocstring或其他 docstring 类扩展，避免快捷键打架
设置 docstring 风格为 google 或 numpy
Python Docstring Generator 默认不启用格式识别，必须手动指定风格，否则生成的注释会空参数、缺返回值，甚至格式错乱（比如缩进塌陷、字段名写成 Arguments: 而非标准 Args:）。
打开设置的 JSON 文件（Cmd + , → 点右上角 {} 图标），添加这两行：
"python.docstringGenerator.style": "google", "python.docstringGenerator.enable": true
如果要用 NumPy 风格，把 "google" 换成 "numpy" 即可。注意大小写敏感，不能写成 Google 或 NUMPY。
-
google风格更易被 Sphinx + Napoleon 解析，也更适合带类型提示的函数 -
numpy风格字段名是Parameters/Returns，但需要额外确保python.analysis.extraPaths已设（否则参数类型可能识别失败） - 别碰
python.docstringFormat—— 这是旧版 AutoDocstring 的配置项，对本扩展无效
触发生成：光标位置和快捷键必须严格匹配
快捷键 Cmd + Shift + 2（macOS）或 Ctrl + Shift + 2（Windows/Linux）只在特定上下文生效，不是“ anywhere 按就出”。最容易踩坑的是光标放错位置。
正确姿势：
- 光标必须在函数定义行的**正下方第一行**（即 def 行之后、函数体之前），且该行为空或仅含缩进
- 函数签名需完整：至少要有参数名，推荐加上类型提示（如
price: float），否则生成的Args:字段会漏掉类型信息 - 不要在函数体内、注释行、类方法中间随便按快捷键——它不会报错，但会静默失败
示例（光标停在第 2 行末尾）：
def calculate_total(price: float, tax_rate: float = 0.08) -> float: | # ← 光标在这里（竖线位置），按 Cmd+Shift+2
为什么生成的注释字段空、类型没填、缩进乱？
这不是扩展 bug，而是 VSCode 语言服务没拿到足够信息。核心原因只有两个：类型推断失败，或格式模板未加载。
- 检查当前文件是否在 Python 工作区里：根目录下有
pyproject.toml、setup.py或__init__.py，否则python.analysis.engine可能退化为基本解析器 - 确保已安装 Microsoft 官方
ms-python.python扩展，且未被禁用 - 如果用了 Poetry 或 conda 环境，确认 VSCode 已选中对应解释器（Cmd+Shift+P →
Python: Select Interpreter） - 缩进错乱通常是因为设置了
"editor.insertSpaces": false或混用了 tab/space；建议统一设为"editor.insertSpaces": true和"editor.tabSize": 4
最常被忽略的一点：生成后别直接敲字覆盖占位符。先用 Tab 键跳转到每个 Args: 下的描述字段再填写，否则格式容易崩。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
