企业官网建设流程全解析

• 开发工具
• 桌面应用

本文以 commands/apps/agenda 目录下的三支脚本命令为完整示例，讲解如何通过 Raycast Script Commands 与 Agenda 的 x-callback-url 机制实现「On the Agenda 概览」「今日笔记概览」「创建并加入 On the Agenda 的新笔记」三个高频操作。读完本文，你将掌握 Agenda 脚本命令的元数据写法、URL Scheme 调用参数、百分号编码（percent-encoding）的正确使用方式，并能直接套用或改造这三支脚本。

一、三支命令能做什么

Agenda 是 macOS 上一款融合了日历与笔记的 App。本仓库用三个 Bash 脚本将其高频动作封装为 Raycast 命令，官方 README（commands/apps/agenda/README.md）给出的能力清单如下：

所有命令的前提是系统已安装 Agenda（Mac App Store 安装），脚本通过open命令唤起 Agenda 的 x-callback-url 来完成跳转或写入。

二、三个概览类命令：一行 URL 打开视图

On the Agenda 概览与今日概览的实现非常简洁，两者结构几乎一致，核心都是一条open语句：

# agenda-on-the-agenda.sh（完整源码见 commands/apps/agenda/agenda-on-the-agenda.sh） open "agenda://x-callback-url/on-the-agenda" echo "Opened On the Agenda Notes."

# agenda-today.sh（完整源码见 commands/apps/agenda/agenda-today.sh） open "agenda://x-callback-url/today" echo "Opened Today's Notes."

这里值得注意的细节有两点：

1. x-callback-url 是这套命令的灵魂。同一仓库中 bear（bear://x-callback-url/search?term=...）、goodlinks（goodlinks://x-callback-url/open?url=...）等命令也采用相同的scheme://x-callback-url/action调用模式，可见这是 macOS 应用间互操作的通用约定。
2. 输出模式选择silent。两支脚本都以# @raycast.mode silent声明运行模式。按 documentation/OUTPUTMODES.md 的说明，silent模式下脚本输出的最后一行会在 Raycast 窗口关闭后以 HUD toast 浮层展示，因此脚本结尾的echo "Opened ..."就是给用户的一次性成功反馈，适合这类「打开即走」的动作型命令。

三、创建笔记命令：三个参数 + 百分号编码

三支命令中最有技术含量的是 agenda-new-note.sh，它在脚本头部声明了最多三个用户输入参数，并把它们拼进 x-callback-url：

# @raycast.argument1 { "type": "text", "placeholder": "Project Title", "percentEncoded": true} # @raycast.argument2 { "type": "text", "placeholder": "Title", "percentEncoded": true } # @raycast.argument3 { "type": "text", "placeholder": "Note Text", "percentEncoded": true, "optional": true } open "agenda://x-callback-url/create-note?project-title=$1&title=$2&text=$3&on-the-agenda=true&date=today"

调用链拆解如下：

• 参数$1（项目标题）、$2（笔记标题）、$3（笔记正文，可选）分别注入 URL 的project-title、title、text三个查询字段；
• 固定字段on-the-agenda=true让新笔记直接进入 On the Agenda，date=today将其日期设为今天；
• 脚本结尾的echo "Created On the Agenda Note."同样作为silent模式下的 HUD 反馈。

3.1 percentEncoded 为什么必不可少

三条参数声明都带上了"percentEncoded": true，这一点直接决定脚本能否正确工作。文档 documentation/ARGUMENTS.md 的参数表说明：

用户输入的笔记标题或正文可能包含中文、空格、&、?等字符，若不做编码，直接拼进open "agenda://x-callback-url/create-note?..."会破坏 URL 的查询串结构，导致参数错位甚至命令失败。开启percentEncoded后 Raycast 在传参前完成转义，脚本拿到的$1/$2/$3即可安全拼接。这一点从仓库实现可以得到印证：凡是把用户输入直接拼进 URL 的脚本（如 bear-add-note.sh、goodlinks-open-link.sh）都无一例外地声明了percentEncoded: true。

3.2 可选参数的传参约定

第三个参数text标记为"optional": true。按 ARGUMENTS.md 的说明，optional缺省时参数视为必填，Raycast 会在输入为空时阻止执行；显式标记后用户可留空。需要注意脚本中$3仍会出现在 URL 里——当可选参数未填时它会变成空字符串，text=后面为空，Agenda 侧会按空正文处理，这属于可以接受的边界行为，也正说明「参数拼接 + 百分号编码」的组合需要使用者自己权衡。

四、元数据骨架：从模板到三支命令的共性

对比仓库根目录下的官方模板 templates/script-command.template.sh，可以清晰看到三支 Agenda 脚本沿用了完全一致的元数据骨架：

# Required parameters: # @raycast.schemaVersion 1 # @raycast.title On the Agenda Overview # @raycast.mode silent # Optional parameters: # @raycast.icon images/agenda.png # @raycast.packageName Agenda # Documentation: # @raycast.description Opens Agenda - On the Agenda Overview # @raycast.author Michael Ellis # @raycast.authorURL https://github.com/mtellis2

三支脚本共有的关键元数据及作用：

• @raycast.schemaVersion 1：脚本格式版本声明，所有命令必填；
• @raycast.mode silent：运行后不弹完整输出窗口，仅以 HUD toast 提示成功，符合快速动作类命令的交互预期；
• @raycast.icon images/agenda.png：为命令指定应用图标，指向本目录下 images/agenda.png；
• @raycast.packageName Agenda：把三支命令归入同一个「Agenda」分组，便于在 Raycast 中统一管理；
• @raycast.description：搜索结果中展示的说明文字；
• @raycast.author/@raycast.authorURL：作者署名与主页，便于其他用户回溯来源。

从截图也可以看到，三支命令在 Raycast 中归属于 Agenda 应用分组，并且自动获得了agc、agt等别名缩写，输入agenda即可一键唤起整套命令。

五、使用方法与扩展思路

安装与使用：将commands/apps/agenda目录下的三支.sh脚本加入 Raycast 的 Script Commands 目录（具体目录位置以 Raycast 设置为准），确保 macOS 已安装 Agenda。之后在 Raycast 输入agenda即可看到三支命令；输入别名（如截图中的agc/agt）可更快触发，选中创建笔记命令后按空格即可依次输入三个参数。

扩展思路：这支create-note命令展示了一个可直接复用的模式——「Raycast 参数 + percentEncoded + x-callback-url」。若想新增能力（例如创建后不加入 On the Agenda、或使用具体日期），只需调整 URL 中的on-the-agenda、date查询字段即可；若想增加更多输入，注意 Raycast 单个脚本最多支持 3 个参数（见 documentation/ARGUMENTS.md 的限制说明），超出后需要把参数编码进单一字段或用配置文件传入。

六、小结

三支 Agenda 脚本虽然代码量极小，却完整覆盖了 Raycast Script Commands 的核心工程要点：元数据声明（标题、模式、图标、分组）、参数系统（text类型、optional、percentEncoded）、输出模式（silent+ HUD 反馈），以及 macOS 应用互操作的 x-callback-url 调用方式。它们既是可直接安装使用的实用命令，也是理解整个 script-commands 仓库写作范式的入门级样本——类似的模式在同一仓库的 Bear、GoodLinks、BusyCal 等命令中反复出现，可互为参照。

• 开发工具
• 桌面应用