sublime_plugin 是唯一合法调用 Sublime Text API 的入口；TextCommand 适用于有视图的文本操作，WindowCommand 适用于窗口级操作；edit 对象不可跨线程或复用，须主线程重新 begin_edit；路径获取应依赖 window.folders() 和 extract_variables()。

sublime_plugin 是唯一能合法调用 Sublime Text API 的入口，直接 import sublime 或 sublime_api 在插件外运行会失败——API 只在插件加载后、plugin_loaded() 触发时才就绪。

TextCommand 和 WindowCommand 怎么选

选错命令类会导致 edit 对象不可用、view 为空或根本拿不到当前文件上下文：

• TextCommand：必须绑定到有视图（即打开的文件）的场景，self.view 可靠，edit 参数有效，适合文本替换、插入、选区操作
• WindowCommand：没有 view 属性，self.window 永远可用，适合新建文件、切换标签页、调用面板（如 show_panel）、批量处理多个视图
• 别在 TextCommand.run() 里调 self.window.run_command("save") —— 虽然不报错，但 save 不会触发保存钩子（如 on_pre_save），实际行为和手动 Ctrl+S 不一致

edit 对象为什么不能跨线程或延迟使用

edit 是一次性的、与当前编辑会话强绑定的句柄，超时或换线程后调用 view.replace(edit, ...) 会静默失败或抛 RuntimeError: Invalid edit object：

• HTTP 请求必须用 sublime.set_timeout_async(..., 0) 移出主线程
• 回调里不能传 edit 进去，只能传 region、text 等纯数据
• 写回编辑器必须切回主线程：sublime.set_timeout(lambda: view.replace(view.begin_edit(), region, result)) —— 注意这里要重新 begin_edit()，不能复用旧 edit
• 如果用 view.substr(region) 拿内容，务必先检查 if not region.empty():，否则空选区会返回空字符串，但逻辑可能崩在后续 JSON 解析或正则匹配上

如何安全获取当前项目/文件路径

别依赖 os.getcwd() 或硬编码路径，Sublime 的工作目录不固定；也别用 view.file_name() 判定项目归属——单文件没项目时返回 None：

• 获取当前视图所属项目根目录：view.window().folders() 返回列表，取第一个（多根项目需额外判断）
• 获取当前文件相对项目路径：view.window().extract_variables().get("file_rel_path")，比手动 os.path.relpath 更可靠
• 想列所有项目内 .py 文件？别用 os.walk ——慢且不响应排除规则（如 folder_exclude_patterns）。改用 view.window().lookup_symbols() 或监听 on_load 缓存，或直接调 window.run_command("find_in_files", {...}) 借壳

真正卡住的地方往往不是 API 写错，而是 edit 对象误复用、线程切换漏掉 set_timeout、或 view.file_name() 在未保存文件上返回 None 后没做防御性判断。这些点不报红，但结果就是命令点了没反应、内容没更新、或者偶尔崩溃。