build-raycast-script-command

构建 Raycast 脚本命令

编写或修复 Raycast 脚本命令（单个 .sh 或 .py 文件，带有 # @raycast.* 元数据头，并由 Raycast 从脚本目录中发现）。此技能仅适用于脚本命令，不适用于 Raycast Extensions API（@raycast/api、ray build、React <List>/<Detail> 视图）。

适用场景

斜体触发条件——匹配任意一项：

• 从头创建新的 .sh 或 .py Raycast 脚本命令
• 将现有 Python 或 shell 脚本转换为 Raycast 脚本命令
• 添加、移除或修复 # @raycast.title / # @raycast.mode / # @raycast.argument* 元数据块
• 在 fullOutput、compact、silent 或 inline 模式之间进行选择（或修复 refreshTime / packageName）
• 将 # @raycast.argument* 类型化参数连接到 sys.argv[1..3] 或 $1..$3
• 诊断脚本为何未出现在 Raycast 中（发现机制、shebang、chmod +x、schemaVersion）
• 修复错误的 stdout 格式、刷新频率、失败时的退出码或缺少依赖时的用户体验
• 按照 Raycast 社区仓库规范强化命令

请勿将此技能用于：

• Raycast Extensions（任何导入 @raycast/api、使用 ray build/ray develop、包含 JSX 视图或扩展 package.json 的内容）——此技能仅涵盖脚本命令。
• 构建 Chrome 或浏览器扩展——请使用 build-chrome-extension。
• 不含 # @raycast.* 头且没有 Raycast 集成意图的普通 Python/Bash 脚本。
• 浏览器自动化流程（run-agent-browser）。

如果你看到 import { ... } from "@raycast/api" 或声明了 "raycast": { ... } 的 package.json，这就是一个扩展——请退出此技能。

触发特征

文件只有在同时满足以下所有条件时才属于适用范围：

1. 文件名以 .sh 或 .py 结尾（也可能使用其他解释器，但很少见）。
2. 第一行是 shebang（例如 #!/bin/bash、#!/usr/bin/env python3）。
3. 头部包含 # @raycast.schemaVersion 1、# @raycast.title … 和 # @raycast.mode …，且它们紧接在 shebang 之后。
4. 文件预期放在 Raycast 脚本目录中（通过 Raycast Settings → Extensions → Script Commands → Add Script Directory 添加），而不是扩展目录树中的 src/ 下。

如果缺少或与上述任意一项（1）–（4）相矛盾，请停止操作，并在编辑前确认适用范围。

关键规则

编辑文件前请先阅读这些内容。详细说明位于 references/ 中——以下规则不得违反。

必需元数据（每条命令）

字段	必需	说明
# @raycast.schemaVersion 1	是	固定值。错误或缺失 → 命令永远不会出现。
# @raycast.title <Human Title>	是	显示在 Raycast 根搜索中。
# @raycast.mode <fullOutput|compact|silent|inline>	是	决定 stdout 规范。
# @raycast.icon	否	表情符号或路径；有助于用户发现。
# @raycast.packageName	否	Raycast UI 中的分组标签。
# @raycast.refreshTime <Ns|Nm|Nh>	仅 inline 必需	秒／分钟／小时。
# @raycast.argument1..3	否	每个参数对应一个 JSON 对象。见下文。

详细说明：references/metadata/required-fields.md。

模式 → stdout 规范

模式	适用场景	显示的 stdout	失败时的用户体验
fullOutput	结果供阅读（列表、报告、多行文本）	在结果窗口中显示完整文本	最后一行 + 非零退出码
compact	操作完成的一行确认信息（类似 Toast）	最后一条非空 stdout 行	最后一行 + 非零退出码
silent	纯副作用，无 UI	成功时不显示任何内容	最后一行 + 非零退出码
inline	按定时器刷新的仪表板小组件	第一条非空行，并按 refreshTime 刷新	第一行 + 非零退出码

inline 必须包含 # @raycast.refreshTime。其他模式均不使用它。

详细说明：references/metadata/mode-selection.md、references/metadata/inline-refresh-and-errors.md。

类型化参数（脚本命令仅支持 3 个）

# @raycast.argument1 { "type": "text",     "placeholder": "query" }
# @raycast.argument2 { "type": "password", "placeholder": "secret", "optional": true }
# @raycast.argument3 { "type": "dropdown", "placeholder": "env", "data": [{"title":"Prod","value":"prod"}] }

• 支持的类型： text、password、dropdown。不支持 select、file 或 number——这些仅适用于扩展。
• 最多支持 3 个参数。参数 2 和参数 3 可以是可选的；参数 1 实际上是必需的（Raycast 会提示输入）。
• 在 Python 中，使用 sys.argv[1]、sys.argv[2]、sys.argv[3] 读取（可选参数始终要检查长度）。
• 在 Bash 中，使用 "$1"、"$2"、"$3" 读取（始终加引号；对可选参数使用 -z 检查）。

详细说明：references/metadata/typed-arguments.md。

发现命令的硬性要求

除非同时满足以下所有条件，否则命令不会出现在 Raycast 中：

1. 脚本的父目录已在 Raycast 设置 → 脚本命令 中注册。
2. 文件具有可执行权限（chmod +x file.sh / chmod +x file.py）。
3. 第一行是有效的 shebang，且对应的解释器已在用户的 PATH 中。
4. 元数据头紧接在 shebang 下方，中间不能有空行（Raycast 对此要求严格）。
5. schemaVersion、title 和 mode 均存在且可解析。
6. 文件名不包含 .template.（此类文件会被有意隐藏，要求用户先编辑）。

详细说明：references/troubleshooting/discovery-checklist.md。

失败与依赖项体验

• 任何错误情况下都以非零状态码退出。发生失败时，Raycast 会显示 stdout/stderr 的最后一行（若为 inline，则显示第一行）。
• 如果命令需要 jq、gh、requests 等依赖项，先检测是否缺少依赖项，并输出一行安装提示，然后以非零状态码退出。不要让晦涩的 command not found 错误直接显示给用户。
• 对于 compact、silent 或 inline，切勿输出嘈杂的多行进度信息——它们都会折叠 stdout。

详细说明：references/troubleshooting/runtime-and-output-issues.md、references/foundations/dependencies-and-portability.md。

工作流

步骤 1 — 确定范围

开始编写前先检查工作区：

• 是否已有需要转换的 .py 或 .sh 文件，还是要从头开始？
• 现有文件头是否使用 # @raycast.*？格式是否正确？
• 周边仓库是否为 Raycast 扩展（检查是否存在 @raycast/api、ray build，或包含 "raycast" 键的 package.json）？如果是，请退出此技能。
• 决定使用 Python 还是 Bash：参见 references/foundations/language-selection.md 和下方的 默认值。

如果检查后仍无法确定任务类型，请阅读 references/foundations/scope-and-fit.md。

Step 2 — 按任务选择

编写前，仅阅读与分支相关的参考资料：

任务	首先阅读
新建 Python 命令	references/foundations/workflow.md → references/python/file-anatomy.md → references/python/implementation-patterns.md → references/metadata/mode-selection.md → references/python/python-recipes.md
新建 Bash 命令	references/foundations/workflow.md → references/bash/bash-script-patterns.md → references/metadata/mode-selection.md → references/bash/bash-recipes.md
转换现有脚本	references/foundations/workflow.md → references/metadata/required-fields.md → references/foundations/dependencies-and-portability.md → references/troubleshooting/discovery-checklist.md
选择／修复模式	references/metadata/mode-selection.md → references/metadata/inline-refresh-and-errors.md → references/troubleshooting/runtime-and-output-issues.md
添加／修复参数	references/metadata/typed-arguments.md → references/python/implementation-patterns.md 或 references/bash/bash-script-patterns.md
命令未显示	references/troubleshooting/discovery-checklist.md → references/metadata/required-fields.md
运行环境／输出错误	references/troubleshooting/runtime-and-output-issues.md → references/metadata/mode-selection.md → references/metadata/inline-refresh-and-errors.md
Python 与 Bash 的选择	references/foundations/language-selection.md
让命令可供他人使用	references/foundations/community-repo-conventions.md → references/foundations/dependencies-and-portability.md
来源／源代码审计	references/foundations/source-map.md

Step 3 — 构建或修复

• 从 assets/templates/python-script-command.py 或 assets/templates/bash-script-command.sh 开始——它们是起始文件，并非完整代码。
• 将元数据块放在 shebang 正下方。Python 和 Bash 都使用 # @raycast.*（# 行注释语法相同）。
• 谨慎读取参数：在 Python 中检查 sys.argv 的长度；在 Bash 中引用 "$1" 并检查 -z "$2"。
• 对任何外部工具添加缺少依赖项时的预检，并在失败时输出一行用户可读的消息。
• 严格遵循所选模式的 stdout 约定——参见上表。

Step 4 — 验证

使用随附的检查工具检查实际命令文件：

1. scripts/check-raycast-script-metadata.sh path/to/command.{py,sh} — 验证 shebang、必需元数据、模式是否合法、inline 模式是否包含 refreshTime，以及类型化参数 JSON。
2. scripts/preview-script.sh path/to/command.{py,sh} [args...] — 运行命令，并预览 Raycast 将如何显示其 stdout（按声明的模式）。
3. 如果命令未显示，请遵循 references/troubleshooting/discovery-checklist.md。
4. 如果输出／刷新／退出语义未通过检查，请遵循 references/troubleshooting/runtime-and-output-issues.md。
5. 报告确切达到的验证阶段（读取 / 元数据检查器 / 预览 / 已在 Raycast 中安装并运行）。不要把“看起来合理”当作冒烟测试。

默认值（除非任务另有要求，否则使用）

• Python 适用于：HTTP／API 调用、JSON 解析、较复杂的文本处理，以及任何涉及结构化数据的多步骤任务。
• Bash 适用于：对现有 CLI（gh、pbcopy、osascript、open）进行轻量封装，以及简单的文件系统操作。
• 用户需要阅读结果时，使用 模式 fullOutput。
• 用一行确认“已完成”时，使用 模式 compact。
• 仅执行副作用（剪贴板、启动应用、系统操作）且没有有用输出时，使用 模式 silent。
• 仅对仪表盘式状态小组件（电池、天气、构建状态）使用 模式 inline，并设置 refreshTime。

捆绑脚本

每个脚本旁边都有对应的 .md 文档。

脚本	用途	是否会修改？
scripts/check-raycast-script-metadata.sh	验证 shebang、必需元数据、模式、内联 refreshTime 和类型化参数 JSON。请参阅 scripts/check-raycast-script-metadata.md。	否
scripts/preview-script.sh	执行命令，并预览所声明模式下 Raycast 的标准输出显示约定。请参阅 scripts/preview-script.md。	否

捆绑资源

资源	用途
assets/templates/python-script-command.py	Python 命令模板，包含元数据头、参数框架、依赖项检查和退出码规范。
assets/templates/bash-script-command.sh	Bash 命令模板，包含相同的框架。

参考索引

文件	阅读时机
references/foundations/scope-and-fit.md	判断任务是否确实属于脚本命令，而不是完整的 Raycast 扩展。
references/foundations/workflow.md	创建或转换命令的端到端构建流程。
references/foundations/language-selection.md	在 Python 和 Bash 之间进行选择。
references/foundations/community-repo-conventions.md	遵循 raycast/script-commands 仓库的分享规范。
references/foundations/dependencies-and-portability.md	命令依赖外部工具或软件包，或必须保持可移植性时。
references/foundations/source-map.md	内部参考资料的来源；基于原始 Raycast 研究扩展此技能。
references/metadata/required-fields.md	添加或修复元数据头。
references/metadata/mode-selection.md	在 fullOutput、compact、silent、inline 之间进行选择。
references/metadata/inline-refresh-and-errors.md	内联刷新频率、首行/末行行为及失败语义。
references/metadata/typed-arguments.md	添加、更改或调试 @raycast.argument*。
references/python/file-anatomy.md	Python 命令文件的结构：shebang、头部和代码区域。
references/python/implementation-patterns.md	设置 sys.argv、依赖说明、失败消息和输出模式。
references/python/python-recipes.md	可直接复制并调整的具体 Python 命令模式。
references/bash/bash-script-patterns.md	构建或修复基于 Bash 的脚本命令。
references/bash/bash-recipes.md	可直接复制并调整的具体 Bash 命令模式。
references/troubleshooting/discovery-checklist.md	命令未显示在 Raycast 中时。
references/troubleshooting/runtime-and-output-issues.md	输出、刷新或失败行为不正确时。

注意事项

• 不要发明上表中没有的元数据字段；只有经过 Raycast 官方来源验证的字段才有效。
• 不要导入 @raycast/api、AI Extension 或扩展 Form 架构；这些属于扩展，而非脚本命令。
• 不要使用不受支持的参数类型（select、file、number）；仅使用 text、password、dropdown。
• 未设置 refreshTime 时，不要声明 inline。
• 对于 compact、silent 或 inline，不要输出多行进度信息。
• 不要以不安全的方式读取可选参数；应检查 sys.argv 长度，并为 "$1"/"$2"/"$3" 加引号。
• 不要让 command not found 提示显示给用户；应预先检查依赖项，并以易读的方式报错。
• 除非命令确实要求用户在首次使用前编辑，否则最终文件名中不要保留 .template.。
• 如果对应的参考文档已涵盖相关内容，不要添加 shell 或 Python 教程内容凑篇幅。

输出约定

任务完成后，报告以下内容：

• 命令文件路径
• 选定的模式，以及它为何符合输出形式
• 已填写的元数据字段（以及添加的任何可选字段）
• 支持的参数，以及它们如何映射到 $1..$3 / sys.argv[1..3]
• 依赖项和任何设置说明
• 验证结果：metadata-checker 的结果和预览结果
• Raycast 安装/使用说明（包括相关时添加脚本目录的说明）
• 达到的验证阶段（read / metadata-checker / preview / installed-and-ran-in-Raycast）