需在 package.json 中注册 commands 并配置 menus，command 须全局唯一，menus 按 menu ID（如 file、editor/context）分组，支持 when 条件与 args 参数传递，调试需用开发者工具验证。
如果您在开发过程中需要自定义 VSCode 的命令行为或扩展其菜单选项，则需深入理解命令（commands）与菜单贡献点（menu contributions）的注册机制和作用范围。以下是针对该主题的详细说明：
本文运行环境：MacBook Pro，macOS Sequoia。
一、命令贡献点的定义与注册
命令是 VSCode 扩展中可被调用的功能单元，必须在 package.json 的 contributes.commands 字段中显式声明，否则无法通过命令面板触发或绑定快捷键。
1、在扩展根目录的 package.json 文件中定位到 contributes 字段。
2、在 contributes 对象内添加 commands 数组，每个数组项为一个对象，包含 command、title 和可选的 category 属性。
3、command 字符串必须全局唯一，推荐采用小写字母加连字符格式，例如 my-extension.format-code。
4、title 用于命令面板中显示的中文或英文描述，支持本地化字符串引用，如 %commands.formatCode%。
二、主菜单栏贡献点配置
主菜单栏（即顶部 File、Edit、View 等区域）的扩展项需通过 menus 字段下的 menu 字段声明，目标位置由 id 指定，例如 file、edit、selection。
1、在 package.json 的 contributes.menus 对象下新增 menu 键，值为对象类型。
2、在该对象中指定预定义菜单 ID，如 “file” 表示文件菜单，”edit” 表示编辑菜单。
3、对应 ID 的值为数组，每个元素包含 command（已注册的命令 ID）、when（条件表达式）和 group（排序分组名）。
4、group 值如 navigation、modification 可影响菜单项相对位置，navigation 组默认置于菜单前部，modification 组默认置于后部。
三、编辑器上下文菜单贡献点配置
编辑器右键菜单的扩展依赖于 editor/context 菜单 ID，其触发逻辑与当前光标所在编辑器状态强相关，支持细粒度的 when 条件控制。
1、在 contributes.menus.editor/context 下添加条目数组。
2、每个条目需指定 command，且该 command 必须已在 contributes.commands 中注册。
3、when 条件可使用 resourceLangId、editorTextFocus、editorHasSelection 等上下文键，例如 editorTextFocus && resourceLangId == ‘javascript‘ 限定仅在 JavaScript 文件聚焦时显示。
4、支持嵌套子菜单，通过 submenu 字段引用另一个已声明的菜单 ID，并在该 submenu 对应的 menus 下定义其子项。
四、命令执行时的参数传递机制
VSCode 允许在菜单项或快捷键绑定中向命令传递参数，参数将在 activate 函数中以 executeCommand 的第二个及以上参数形式接收。
1、在 menus 条目中添加 args 字段，值为 JSON 序列化的任意结构，如 [true, “default”] 或 {“mode”: “strict”}。
2、在 extension.ts 的 registerCommand 回调函数 中，参数列表将按顺序接收 args 内容，第一个参数始终为命令触发时的上下文对象。
3、args 中若含变量占位符，如 $selectedText 或 $fileBasename，需确保 when 条件中已启用对应上下文，否则值为空字符串。
4、args 不支持函数或 undefined 值，传入将导致命令执行失败且无错误提示。
五、调试菜单与命令可见性的验证方法
菜单项是否正常渲染、命令能否被识别，需借助 VSCode 内置的开发者 工具 进行实时校验，避免仅依赖静态配置检查。
1、在扩展开发窗口中按下 Cmd+Shift+P（macOS）打开命令面板。
2、输入 Developer: Toggle Developer Tools，打开 浏览器 开发者控制台。
3、在控制台中执行 vscode.commands.getCommands(true) 查看当前所有已注册命令列表。
4、右键编辑器任意位置，选择 Inspect Context Menu，查看 DOM 中是否渲染出对应 menuitem 元素及其 disabled 属性状态。
