必须继承sublime_plugin.TextCommand或WindowCommand，类名以Command结尾并置于Packages/User/下.py文件中，实现run(self, edit, **kwargs)方法，edit不可省略且不能跨调用复用。
怎么写一个可调用的自定义 Command 类
Sublime Text 的自定义 Command 不是写个 JSON 就能用的，必须用 Python 实现一个 TextCommand 或 WindowCommand 子类，放在 Packages/User/ 下的 .py 文件里。它不是配置，是代码——没运行、没加载，命令面板里就搜不到。
常见错误现象：写完保存，Ctrl+Shift+P 里搜不到名字，右键菜单也不出现，控制台也没报错——大概率是文件没放对位置，或者类名没按规范命名。
- 文件必须放在
Packages/User/目录下（Preferences → Browse Packages… 进去确认），后缀为.py，比如my_utils.py - 类名必须以
Command结尾，比如InsertTimestampCommand；注册到命令系统时会自动转成小写下划线格式：insert_timestamp - 继承
sublime_plugin.TextCommand（作用于当前视图）或sublime_plugin.WindowCommand（作用于整个窗口），别漏掉self.view或self.window的使用上下文 - 必须实现
run(self, edit, **kwargs)方法，edit对象不能省——所有文本修改都得通过它，否则静默失败
为什么 command 名在命令面板里搜不到
不是“没生效”，而是 Sublime 根本没加载这个 Python 文件。它只在启动时扫描 Packages/User/ 下的 .py 文件，且只认符合命名和结构规范的类。
验证方式很简单：打开控制台（Ctrl+`），输入 sublime.log_commands(True)，再手动从菜单或右键触发一次你写的命令（如果已配置好快捷键或菜单项）。如果控制台没输出 command: insert_timestamp 这类日志，说明命令压根没被识别。
- 检查文件编码是否为 UTF-8（无 BOM），尤其含中文注释时，BOM 会导致导入失败
- 类定义外不能有语法错误，哪怕一行
print都会让整个模块加载中断 - 别用
if __name__ == '__main__':块——Sublime 不执行主模块逻辑 - 插件未启用？检查 Preferences → Package Settings 里有没有对应条目；也可在控制台输
sublime.active_package_plugins()看是否在列表中
如何让自定义 Command 支持 args 和 context
Command 类本身不处理 args 和 context，它们由快捷键或菜单项传入，最终作为参数交给 run() 方法。你得在 run 签名里显式声明，否则会报 TypeError: run() got an unexpected keyword argument。
比如你想让命令接收一个前缀字符串，并只在 Python 文件里可用：
class InsertPrefixCommand(sublime_plugin.TextCommand):
def run(self, edit, prefix="TODO"):
self.view.insert(edit, self.view.sel()[0].begin(), prefix)
对应快捷键写法必须带 args 字段：
[{"keys": ["ctrl+alt+i"], "command": "insert_prefix", "args": {"prefix": "FIXME"}}]
-
args字典里的 key 必须和run()参数名完全一致（包括默认值），大小写敏感 -
context是快捷键/菜单的过滤条件，不是 Command 类的属性；它控制“什么时候显示/触发”，不参与 Python 层逻辑 - 想做更细粒度判断（比如光标前是空行），应在
run()里用self.view.line()、self.view.substr()等 API 主动检查，而不是依赖 context
右键菜单里加自定义 Command 为什么没反应
右键菜单项是否出现，只取决于两件事：命令名能否在命令面板里搜到，以及 Context.sublime-menu 文件是否合规。它不校验 Python 逻辑，只做字符串匹配。
典型失效场景：命令面板能搜到 insert_timestamp，但右键还是不显示——几乎肯定是菜单文件路径或格式错了。
- 文件必须严格命名为
Context.sublime-menu（首字母大写，无空格，无后缀），放在Packages/User/下 - 内容必须是合法 JSON 数组，每个对象至少含
caption和command字段，command值必须和命令面板里完全一致（比如"command": "insert_timestamp"） -
args里变量如$file_path不加引号，但整个args还是 JSON 字典，比如"args": {"path": "$file_path"} - 菜单项加了
context却没生效？注意它是“且”关系，多个条件同时满足才显示；调试时先删掉context测试基础通路
最易被忽略的一点：Sublime 加载菜单文件是惰性的，改完 Context.sublime-menu 后，不重启也能生效，但必须确保之前没打开过同名错误文件（比如 context.sublime-menu 小写开头），否则旧缓存可能卡住。
