SpotlightShell 是一个面向 macOS 26 或更新版本的原生小工具，为 Spotlight 和“快捷指令”提供 Run Shell Command 动作。
有些操作只需要执行一条短命令，例如查看当前目录或得到一段文本结果，每次打开 Terminal 会多一步。SpotlightShell 让命令作为运行时参数输入，不需要事先维护一套固定命令菜单。
它执行的是当前用户权限下的 Shell 命令，不负责把自然语言翻译成命令，也不会自动获取管理员权限。
安装后让系统发现动作
项目 Releases 提供 DMG。按发布说明安装，先打开应用一次，再给 macOS 一点时间发现 App Shortcut。
按 Command-Space 打开 Spotlight，再用 Command-3 筛选动作，搜索 Run Shell Command 或 SpotlightShell（见图 1）。如果找不到，先检查 快捷指令 → App → SpotlightShell，并重新打开应用。
想用 sh 快速叫出动作，可以在 Spotlight 找到该动作，点击旁边的 Add quick keys，输入 sh 并确认。以后按 Command-Space、输入 sh，再填写命令即可。
先运行一条容易判断结果的命令
第一次可以使用：
|
|
选择后台模式，检查返回的输出与退出状态。工具分别保留标准输出和错误输出，不会简单地把“有文字返回”当作成功（见图 2）。
也可以试试 printf 'example error\n' >&2; exit 7：它会产生错误输出，并返回退出状态 7。这样就能看出“命令产生了文字”与“命令成功完成”不是一回事。在“快捷指令”中，同一个动作返回文本，可接“显示结果”；要根据成败决定后续步骤时，应检查状态。
后台和 Terminal 模式分别适合什么
Background 适合短时间、无需交互的命令。它运行登录 zsh，不提供交互输入，分别捕获两种输出，执行时限为 20 秒。每路保留最多 64 KiB，超出会注明截断；对话框实际展示的内容还可能更短。
需要终端输入、TTY 或较长会话的程序，选择 Terminal。这会打开 Apple Terminal 并交接命令。交接成功不等于命令最终运行成功，输出留在 Terminal 中。
工作目录是独立参数。可以填绝对路径、~ 或 ~/…，不需要在目录输入框中额外包一层 Shell 引号。
把命令和工作目录分别填清楚
例如想看“文稿”里某个项目的文件列表，可以把工作目录填写为 ~/Documents/My Project，命令填写为 pwd; ls。目录输入框是一个路径参数，包含空格也不用额外加引号；命令输入框才会交给 zsh 解释。不要把 cd 命令写进目录栏，也不要在这里填 $HOME 这样的变量表达。
pwd 会先显示执行位置，ls 再列出内容。第一次使用时保留这个检查步骤，能发现命令是否在预期目录运行。留空工作目录默认从个人主目录开始；相对路径则应写成完整路径，避免把“我在终端刚才进入的目录”误当成 Spotlight 的当前目录。
这与命令内部的引号规则不同。若命令要打开一个带空格的文件，仍需要按照 Shell 语法给那个文件路径加引号。简单记成两个问题即可：目录栏告诉工具在哪里开始；命令栏告诉 Shell 要做什么。两者分开填，也更容易检查出错位置。
需要交互时，让 Terminal 接手
可以用 printf 'hello\n'; tty 检查 Terminal 模式：文字会出现在新 Terminal 窗口，tty 则显示终端设备。需要连续运行并观察的工具也适合放在这里，例如 top，退出时在终端按 q。不要因为后台模式能运行一次输出，就假定它也适合长期监控。
第一次交接可能弹出让 SpotlightShell 控制 Terminal 的系统提示。这项授权用于打开终端并发送命令；后台运行不需要这个交接。如果之前拒绝过，后续选择 Terminal 却没有按预期启动，应先检查系统自动化权限，而不是把同一条命令反复提交。
交接后 SpotlightShell 可以结束，Terminal 会独立保留。若命令需要密码、键盘选择或其他输入，就在 Terminal 中完成。Spotlight 返回“已交接”只能说明命令送到了终端；实际是否完成、有没有报错，要看那个窗口。传输提示超时时，也先查看 Terminal，避免误以为没执行而重复运行。
在快捷指令里保存常用检查
经常执行同一条短命令时，可以在“快捷指令”中新建一个流程，加入 SpotlightShell 的 Run Shell Command，填好命令、目录和运行模式，再接“显示结果”。例如只检查某个目录的文件列表，就不必每次都重新输入路径。先用只读、输出较短的操作熟悉流程，再加入自己的日常命令。
不要只根据结果中有没有文字决定成功。printf 可以输出信息后返回错误状态，一个没有输出的命令也可能正常完成。后续如果还要处理文件，先判断返回报告中的退出状态；后台超时或输出截断时，也要把它看作需要检查的结果。
需要完整长日志的任务，直接交给 Terminal 更方便。后台模式适合“一次输入，短时间内取回一段结果”，而不是替代整个终端。把动作入口安排在 Spotlight，把持续交互留给 Terminal，日常操作会更清楚。
为什么和自己终端里的表现不同
后台模式读取登录 Shell 配置，但不加载交互式 .zshrc。只写在那里的别名、函数或 PATH 设置，可能无法使用；Terminal 模式则运行交互式登录 Shell。
选择模式时只需先问自己：命令是否需要键盘输入或持续运行？需要就选 Terminal；只想取得一段短结果，就选 Background。
应用本身不上传命令，但 Spotlight、快捷指令、Terminal、Shell 历史和被调用程序，仍可能按各自规则保留信息。它也拥有当前账户能够执行的能力，提交前应理解命令内容。
安装、签名、目录参数与输出限制见 README。如果对快捷指令与原生应用配合的方式感兴趣，也可以看 Auto Filename Helper。