1.vscode

插件

1. folder-alias

• 作用: 给文件夹设置别名
• 心得: 文件夹不能命名为中文, 但是为了方便查找不得不用中文
• 备注: 和idea的treeinfotip类似
• 建议快捷键: 不支持

2. open in browser

• 作用: html文件打开在浏览器中
• 心得: 比live service好用, 更加轻量
• 备注:
• 建议快捷键: 建议右键菜单→打开

Snippet

Snippet(代码片段)生成网站: https://snippet-generator.app/?description=&tabtrigger=&snippet=&mode=vscode

IntelliCode

三个 VSIX 直链（弃用前最后稳定版）

• 如何使用: 下载后名字都是相同的的, 需要手动改为vsix然后拖入插件

扩展	版本	VSIX 直链
IntelliCode（主扩展）	1.3.2	link
IntelliCode Completions（补全）	2.0.1	link
IntelliCode API Usage Examples (调用量)	0.2.9	link

• 这里选择环境, 这个环境有的包就能补全

Cmd+Shift+P → "Python: Select Interpreter" → 选 /opt/homebrew/bin/python3（即使是同一个也重新点一下）

njpwerner.autodocstring

这个配置必须准确，先查证官方模板语法再回答。

toolName: web_search

status: success

query: njpwerner autodocstring customTemplatePath custom template variables handlebars example

官方确认用 mustache.js 引擎。拉取官方 google.mustache 模板源码确认全部变量名。

toolName: web_search

status: failed

query: https://raw.githubusercontent.com/NilsJPWerner/autoDocstring/master/templates/google.mustache

toolName: run_command

status: success

command: curl -sL https://raw.githubusercontent.com/NilsJPWerner/autoDocstring/master/templates/google.mustache | head -80 undefined

toolName: run_command

status: success

command: curl -sL “https://api.github.com/repos/NilsJPWerner/autoDocstring/git/trees/master?recursive=1“ 2>/dev/null | python3 -c “import json,sys; d=json.load(sys.stdin); [print(t[‘path’]) for t in d.get(‘tree’,[]) if ‘mustache’ in t[‘path’] or ‘template’ in t[‘path’].lower()]” 2>&1 | head -30 undefined

toolName: run_command

status: success

command: curl -sL “https://raw.githubusercontent.com/NilsJPWerner/autoDocstring/master/src/docstring/templates/google.mustache“ undefined

官方模板拿到了。再确认自定义标签 customTags 配置语法（用户模板里有 @api）。

toolName: web_search

status: success

query: https://raw.githubusercontent.com/NilsJPWerner/autoDocstring/master/README.md

官方文档已确认（mustache.js 引擎，customTemplatePath 支持绝对路径或相对项目根路径）。回答如下：

1. autoDocstring.customTemplatePath 怎么写

在 settings.json（项目 .vscode/settings.json 或用户级）中：

{
  "autoDocstring.docstringFormat": "custom",
  "autoDocstring.customTemplatePath": ".vscode/my_docstring.mustache",
  "autoDocstring.quoteStyle": "\"\"\"",
  "autoDocstring.startOnNewLine": true,
  "autoDocstring.includeExtendedSummary": true,
  "autoDocstring.guessTypes": false
}

要点（均有官方文档佐证）：

• docstringFormat 必须设为 custom，否则自定义模板不生效
• customTemplatePath 支持绝对路径或相对项目根路径（README）；不支持 ${workspaceFolder} 变量（issue #72），所以用相对路径最稳
• quoteStyle 保持 """（Python docstring），模板里不用写引号，扩展自动包裹

2. 模板文件内容（my_docstring.mustache）

对照你的 diff_worker.py:30-34 目标格式（中文描述 + @param + @returns）：

{{! 自定义 docstring 模板：中文 JSDoc 风格 }}
{{summaryPlaceholder}}

{{extendedSummaryPlaceholder}}
{{#parametersExist}}

{{#args}}
@param {{var}} {{descriptionPlaceholder}}
{{/args}}
{{#kwargs}}
@param {{var}} {{descriptionPlaceholder}}
{{/kwargs}}
{{/parametersExist}}
{{#exceptionsExist}}

{{#exceptions}}
@raises {{type}} {{descriptionPlaceholder}}
{{/exceptions}}
{{/exceptionsExist}}
{{#returnsExist}}

{{#returns}}
@returns {{descriptionPlaceholder}}
{{/returns}}
{{/returnsExist}}

生成效果：

"""
处理单条 diffing 事件：读快照 → 算 diff → 更新 meta → 删快照 → 标 descing

_extended_summary_
@param conn _description_
@param ev _description_
@returns _description_
"""

必须知道的限制：

• {{summaryPlaceholder}} / {{descriptionPlaceholder}} 生成后可 Tab 逐个填中文
• @api 这类自定义标签没有对应模板变量，无法动态生成，只能生成后手动补一行（或写死在模板里但内容固定）

然后与你对齐几个细节。

toolName: AskUserQuestion

status: success

按你的选择（用户级全局 + 忽略 @api + 带类型和默认值），操作步骤如下，全部由你手动执行。

操作步骤

Step 1: 创建模板文件 /Users/xi/.vscode/my_docstring.mustache

内容（基于官方 google.mustache 变量，中文 JSDoc 风格）：

{{! 自定义 docstring 模板：中文 JSDoc 风格 }}
{{summaryPlaceholder}}

{{extendedSummaryPlaceholder}}
{{#parametersExist}}

{{#args}}
@param {{var}} ({{typePlaceholder}}): {{descriptionPlaceholder}}
{{/args}}
{{#kwargs}}
@param {{var}} ({{typePlaceholder}}, optional): {{descriptionPlaceholder}}. Defaults to {{&default}}.
{{/kwargs}}
{{/parametersExist}}
{{#exceptionsExist}}

{{#exceptions}}
@raises {{type}}: {{descriptionPlaceholder}}
{{/exceptions}}
{{/exceptionsExist}}
{{#returnsExist}}

{{#returns}}
@returns {{typePlaceholder}}: {{descriptionPlaceholder}}
{{/returns}}
{{/returnsExist}}

Step 2: 打开用户设置 JSON

Cmd + Shift + P → 输入 Open User Settings (JSON) → 回车

Step 3: 添加配置

{
  "autoDocstring.docstringFormat": "custom",
  "autoDocstring.customTemplatePath": "/Users/xi/.vscode/my_docstring.mustache",
  "autoDocstring.quoteStyle": "\"\"\"",
  "autoDocstring.startOnNewLine": true,
  "autoDocstring.includeExtendedSummary": true,
  "autoDocstring.guessTypes": true
}

Step 4: 验证

在任意函数定义下一行输入 """ 回车，应生成：

def foo(conn, ev, retries: int = 3) -> str:
    """
    _summary_

    _extended_summary_
    @param conn (_type_): _description_
    @param ev (_type_): _description_
    @param retries (int, optional): _description_. Defaults to 3.
    @returns (str): _description_
    """

Tab 逐个填入中文即可。

对应关系表（官方变量佐证）：

目标格式	模板写法	官方变量
参数名	{{var}}	官方 {{var}}
参数类型	{{typePlaceholder}}	官方 {{typePlaceholder}}
参数描述	{{descriptionPlaceholder}}	官方 {{descriptionPlaceholder}}
默认值	{{&default}}	官方 {{&default}}（& 防转义）
返回	@returns {{typePlaceholder}}: {{descriptionPlaceholder}}	官方 {{#returns}} 块
无参/无返回时隐藏	{{#parametersExist}} / {{#returnsExist}}	官方 parametersExist / returnsExist

Sources: - autoDocstring README - 官方 google.mustache 模板

toolName: AskUserQuestion

status: success

这是 Trae IDE（VSCode 分支），全局设置路径不同。看一下该目录结构。

toolName: view_folder

status: success

/Users/xi/Library/Application Support/Trae/User

找到了。读一下现有全局 settings.json 确认格式。

toolName: view_files

status: success

filePath: /Users/xi/Library/Application Support/Trae/User/settings.json

确认了。你的 Trae IDE 全局设置就是 VSCode 的用户级 settings.json，路径为 /Users/xi/Library/Application Support/Trae/User/settings.json（结构与其他 VSCode 分支完全一致）。配置方式如下：

操作步骤（Trae 版）

Step 1: 创建模板文件

建议放在 Trae 用户目录（和 settings.json 同级），路径：

/Users/xi/Library/Application Support/Trae/User/my_docstring.mustache

内容（与之前一致，带类型+默认值）：

{{! 自定义 docstring 模板：中文 JSDoc 风格 }}
{{summaryPlaceholder}}

{{extendedSummaryPlaceholder}}
{{#parametersExist}}

{{#args}}
@param {{var}} ({{typePlaceholder}}): {{descriptionPlaceholder}}
{{/args}}
{{#kwargs}}
@param {{var}} ({{typePlaceholder}}, optional): {{descriptionPlaceholder}}. Defaults to {{&default}}.
{{/kwargs}}
{{/parametersExist}}
{{#exceptionsExist}}

{{#exceptions}}
@raises {{type}}: {{descriptionPlaceholder}}
{{/exceptions}}
{{/exceptionsExist}}
{{#returnsExist}}

{{#returns}}
@returns {{typePlaceholder}}: {{descriptionPlaceholder}}
{{/returns}}
{{/returnsExist}}

Step 2: 在 settings.json 添加 5 个键（追加到现有 JSON 末尾，注意逗号）：

"autoDocstring.docstringFormat": "custom",
"autoDocstring.customTemplatePath": "/Users/xi/Library/Application Support/Trae/User/my_docstring.mustache",
"autoDocstring.quoteStyle": "\"\"\"",
"autoDocstring.startOnNewLine": true,
"autoDocstring.includeExtendedSummary": true,
"autoDocstring.guessTypes": true