深度解析 Keyboard Maestro 变量系统：从全局持久化到局部作用域

在 macOS 自动化领域，Keyboard Maestro (KM) 不仅仅是一个快捷键工具，它更像是一个拥有图形化界面的脚本运行时。对于开发者而言，掌握其变量（Variables）的逻辑，等同于掌握了程序的“状态管理”。

---

1. 变量的定义与赋值

在 KM 中，变量不需要预先声明类型（类似于 Python 或 JavaScript）。你可以通过以下几种方式创建变量：

• Set Variable to Text: 最基础的赋值，支持纯文本或 Token 混合。
• Set Variable to Calculation: 执行数学运算（例如 1 + 2 或内置函数）。
• Action 结果输出: 许多动作（如 Execute Shell Script 或 JSON API）可以直接将输出保存到指定变量。

命名规范

KM 的变量名区分大小写，且支持使用空格。但作为程序员，建议遵循 PascalCase 或 snake_case，并利用 双下划线 (__) 来实现作用域控制。

---

2. 变量的作用域 (Scopes)

这是 KM 最具特色的地方。它没有显式的 public/private 关键字，而是通过命名前缀约定来区分作用域。

A. 全局变量 (Global Variables)

• 特征： 无特殊前缀（如 UserEmail）。
• 生命周期： 永久存储在磁盘。即使重启电脑或更新软件，值依然存在。
• 风险： 容易造成命名冲突，且随着时间推移会污染变量列表。

B. 局部变量 (Local Variables)

• 命名： 必须以 Local__ 开头（注意是两个下划线）。
• 生命周期： 仅限当前宏的单次运行过程。一旦宏结束（不论成功或失败），变量立即销毁。
• 优势： 线程安全，多实例运行互不干扰，内存管理优雅。

C. 实例变量 (Instance Variables)

• 命名： 必须以 Instance__ 开头。
• 生命周期： 在整个“调用链”中有效。
• 场景： 当宏 A 通过 Execute Macro 动作调用宏 B 时，它们共享同一个 Instance 变量。这在构建“子程序/函数”时非常有用。

---

3. 变量的获取与引用

A. 在 KM 动作界面中

使用 Token 语法引用变量：

• %Variable%YourVariableName%
• 如果是计算字段（Calculation），直接写变量名即可。

B. 在脚本环境中 (Interoperability)

KM 将变量映射为环境变量，方便外部脚本调用：

• Shell Script:

  echo $KMVAR_Local__MyData
  

• AppleScript:

  tell application "Keyboard Maestro Engine"
      set myValue to getvariable "Local__MyData"
  end tell
  

• JavaScript (JXA):

  const km = Application("Keyboard Maestro Engine");
  let data = km.getvariable("Local__MyData");
  

---

4. 调试技巧：变量监控

作为程序员，你不能盲目运行宏。以下是观察变量状态的三种手段：

1. Variables 面板： 在 Settings > Variables 中可以查看所有全局变量。
2. Interactive Debugger： 运行宏时开启调试器，可以实时看到 Local 和 Instance 变量的当前值。
3. Engine Log： 通过终端执行 tail -f ~/Library/Logs/Keyboard\ Maestro/Engine.log，配合 Log 动作输出调试信息。

---

总结

• 优先使用 Local__：除非你需要跨宏持久化数据，否则局部变量始终是首选，它能有效避免竞态条件。
• 规范化命名：利用 Instance__ 传递参数，让你的宏具备可重用的“函数化”特征。
• 清理全局变量：定期检查 Settings 面板，手动删除不再需要的全局变量以保持系统轻快。