TextCommand类必须继承sublime_plugin.TextCommand，否则Sublime Text无法识别；edit对象仅在run()内有效，不可缓存或跨调用复用；需用view.sel()遍历多光标，通过sublime.status_message调试。
TextCommand类必须继承sublime_plugin.TextCommand
不继承这个基类，Sublime Text根本不会识别你的类为可执行命令。插件加载时会扫描所有继承sublime_plugin.TextCommand的类，并将其注册为可用命令（如my_custom_command），否则调用view.run_command("my_custom_command")会静默失败或报command not found错误。
常见错误是误继承sublime_plugin.WindowCommand或直接写个普通类——前者只能通过窗口上下文触发（比如菜单里“Project → …”），后者压根不会被加载。
- 确保文件保存在
Packages/User/或自定义包路径下，且后缀为.py - 类名需遵循驼峰命名，但命令名由
def name(self)返回值或类名自动转为下划线风格（如MyExampleCommand→my_example） - 不要在
__init__里做耗时操作，run方法才是实际执行入口
run()方法接收edit对象，不能缓存或跨调用复用
edit对象是Sublime Text提供的临时编辑令牌，仅在当前run()生命周期内有效。试图把它存为实例变量、传给异步回调、或在另一个run()里重用，都会触发RuntimeError: Trying to use invalid edit object。
典型翻车场景：想异步处理完再修改文本，结果把edit塞进sublime.set_timeout回调里；或者在run()里调了两次view.insert(edit, ...)却用了不同edit实例。
- 所有文本变更（
insert、erase、replace等）必须在同一个run()内、用同一个edit对象完成 - 如需延迟操作，改用
sublime.set_timeout(lambda: view.run_command("another_command"), 0)触发新命令 - 获取当前选区用
view.sel()，获取内容用view.substr(region)，这些都不依赖edit
命令触发方式决定可用API范围
从命令面板（Ctrl+Shift+P）或按键绑定触发的TextCommand，其view对象始终指向当前活动视图；但若通过右键菜单或context_menu配置触发，可能面对多视图、甚至无焦点视图的情况。
这意味着：直接调用view.window()可能返回None，view.file_name()可能为None（比如未保存的缓冲区），而view.settings()总是可用。
- 安全访问窗口：先判空
if view.window(): window = view.window() - 文件路径相关逻辑（如读取同目录配置）务必加
if view.file_name()保护 - 涉及多光标编辑时，
view.sel()返回RegionList，需遍历每个region单独处理，不能只取[0]
调试TextCommand最有效的办法是print+sublime.status_message
Sublime Text不支持pdb断点，print()语句默认输出到Console（Ctrl+`），但容易被淹没。更可靠的是用sublime.status_message("msg")把关键状态打到底部状态栏，配合sublime.error_message("err")弹窗强提醒。
注意：print()在插件热重载后可能不刷新，而status_message每次调用都可见；另外，异常堆栈默认不显示在状态栏，需手动捕获并输出。
- 在
run()开头加sublime.status_message("my_command started")确认是否进入 - 关键分支加
sublime.status_message(f"pos={view.sel()[0].a}")验证光标位置 - 包裹
try/except，在except Exception as e:里用sublime.error_message(f"Err: {e}")
TextCommand机制看着轻量，但edit生命周期、视图上下文不确定性、以及缺乏运行时反馈，会让问题藏得比较深——尤其在多光标、未保存缓冲区、或从右键菜单触发时，稍不注意就变成“点了没反应”。 
