prompts.chat Raycast 扩展:在 Mac 上搜索、浏览并一键运行社区 AI Prompt 的完整技术指南

prompts.chat Raycast 扩展:在 Mac 上搜索、浏览并一键运行社区 AI Prompt 的完整技术指南

【免费下载链接】prompts.chatf.k.a. Awesome ChatGPT Prompts. Share, discover, and collect prompts from the community. Free and open source — self-host for your organization with complete privacy.项目地址: https://gitcode.com/GitHub_Trending/aw/prompts.chat

prompts.chat 官方提供了一个 Raycast 扩展,让你直接在 macOS 的 Raycast 中搜索、浏览社区 Prompt,并可把任意 Prompt 发送到 ChatGPT、Claude、Cursor、VS Code 等 25+ 个 AI 平台执行。读完本文,你将了解该扩展的五个命令、离线缓存机制(全量下载prompts.json)、${variable}变量填充原理、各平台 URL 深链构造规则,以及通过 Base URL 指向自托管实例的配置方法,并能掌握本地开发与构建该扩展的方式。

扩展概览:五个命令与功能特性

README(见 packages/raycast-extension/README.md)中列出的核心特性包括:

• Search Prompts— 快速搜索数千个社区 AI Prompt
• Browse Prompts— 按类型筛选、按不同排序方式浏览最新 Prompt
• Random Prompt— 随机抽取一条 Prompt 获取灵感
• Run Prompts— 直接在 ChatGPT、Claude、Cursor 等 25+ 个 AI 平台上运行 Prompt
• Variable Support— 运行前先填充 Prompt 变量

README 的"Commands"表格只列出了三个常用命令,但从扩展清单 package.json 的实际声明来看,该扩展一共注册了5 个 view 模式命令:

几个从package.json可以确认的工程事实:

• 扩展仅支持macOS("platforms": ["macOS"]),许可协议为MIT;
• 运行时依赖为@raycast/api@^1.104.1与@raycast/utils@^1.19.1;
• 分类标签为Productivity与Developer Tools。

其中Download All Prompts 是整个扩展的数据基石:搜索、浏览、随机三个命令都从本地缓存读取数据,首次使用前必须先执行一次全量下载。CHANGELOG.md 也确认了"Local caching for offline access"是该扩展的核心能力之一。

数据流架构:prompts.json 全量下载与本地检索

全量下载与本地存储

下载逻辑实现于 src/cache.ts:downloadAllPrompts()向${baseUrl}/prompts.json发起请求(该端点对应仓库主站的 src/app/prompts.json/route.ts 路由),拿到完整 Prompt 列表后映射为轻量的CachedPrompt结构——只保留id、title、content、description、type、author、slug、category、tags、voteCount这些字段,随后整体 JSON 序列化写入 Raycast 的LocalStorage:

// src/cache.ts const PROMPTS_CACHE_KEY = "cached_prompts"; const CACHE_TIMESTAMP_KEY = "cached_prompts_timestamp"; export async function setCachedPrompts(prompts: CachedPrompt[]): Promise<void> { await LocalStorage.setItem(PROMPTS_CACHE_KEY, JSON.stringify(prompts)); await LocalStorage.setItem(CACHE_TIMESTAMP_KEY, Date.now().toString()); }

同时记录下载时间戳,便于用户判断缓存新鲜度。缓存被读取时若 JSON 解析失败会安全地返回空数组,而不是让命令崩溃。

本地多字段检索

下载完成后,searchPrompts(prompts, query)完全在本地执行子串匹配,覆盖七个字段:标题、正文内容、描述、作者用户名、作者昵称、分类名、标签——全部不区分大小写。这意味着离线状态下(甚至断网)搜索依然可用,且速度不依赖网络往返。

缓存到标准 Prompt 的转换

列表组件统一消费 src/types.ts 中定义的Prompt类型(字段包括type: "TEXT" | "IMAGE" | "VIDEO" | "AUDIO" | "SKILL"、author、category、tags、voteCount等)。convertToPrompt()负责把缓存项"补全"成完整Prompt——本地数据没有头像、认证标识、创建时间,这些字段会被填为占位值(id: "local"、verified: false、当前时间),从而复用同一套详情视图组件。

此外,src/api.ts 中还保留了一组在线 API 封装(fetchPrompts、fetchPromptBySlug、searchPrompts),分别对接${baseUrl}/api/prompts、${baseUrl}/api/prompts/${slug}与${baseUrl}/api/prompts/search(查询串少于 2 个字符时直接返回空)。从源码结构看,它们为需要实时数据/在线分页的场景预留了能力;当前版本的搜索、浏览、随机三个命令则走缓存路径。

Search Prompts 与 Browse Prompts:两个列表命令

Search Prompts

入口组件为 src/search-prompts.tsx。它挂载时先读缓存;如果缓存为空,会显示 Empty View 并提供Download All Prompts按钮(按 Enter 直接触发下载,成功后以 Toast 提示Downloaded N prompts)。输入少于 2 个字符时提示"至少输入 2 个字符",与在线搜索接口的最小长度约束保持一致。

每条列表项的 Action 面板组织为四个分区:

1. Run—Run Prompt推入RunPromptForm(详见下文);
2. 默认区 —Copy Prompt(⌘C)、Open in Browser(⌘O)、Copy URL(⌘⇧C);
3. View Details(⌘D) — 推入PromptDetailView查看完整内容;
4. Open Extension Preferences— 打开偏好设置修改 Base URL。

列表项副标题展示@作者用户名 • N upvotes,右侧 accessory 标签显示 Prompt 类型(TEXT/IMAGE/…)。

Browse Prompts

入口组件为 src/browse-prompts.tsx,同样依赖本地缓存(缓存为空时会 Toast 提示先执行 Download All Prompts)。它的差异化能力在搜索框旁的下拉菜单(List.Dropdown),提供两组可记忆的筛选状态(storeValue):

• Sort(排序):Most Upvoted(按voteCount降序)、Most Recent(保持 API 返回的最新在前)、By Author(按作者用户名localeCompare排序);
• Type(类型过滤):All Types/Text/Image/Video/Audio/Skill,对应type字段取值TEXT、IMAGE、VIDEO、AUDIO、SKILL。

类型过滤与文本过滤组合后,再按所选排序输出——全部由前端useMemo内存计算完成,无网络开销。

Random Prompt

src/random-prompt.tsx 的逻辑非常直接:从缓存数组中Math.floor(Math.random() * prompts.length)随机取一条,转换为Prompt后推入PromptDetailView,并通过onRefresh回调支持反复"换一个"。缓存为空时给出明确指引:先运行Download All Prompts命令。

Run Prompts:变量填充与 27 个目标平台

这是该扩展最核心的能力:对任意 Prompt 按 Enter,即可选择目标 AI 平台执行。完整流程在 src/components/run-prompt.tsx 中实现,分两步:变量填充(如存在)→ 平台选择。

变量提取与模板编译

变量语法为${variableName}或带默认值的${variableName:default},提取与编译逻辑集中在 src/utils.ts:

// 提取变量:匹配 ${name} 或 ${name:default},自动去重 const regex = /\$\{([^}:]+)(?::([^}]*))?\}/g; // 编译模板:有用户值用用户值,否则用默认值,都没有则保留原占位符 export function compilePrompt(template: string, values: Record<string, string>): string { return template.replace( /\$\{([^}:]+)(?::([^}]*))?\}/g, (match, name, defaultValue) => { const trimmedName = name.trim(); return values[trimmedName] ?? defaultValue?.trim() ?? match; }, ); }

RunPromptForm的工作方式:

1. 挂载时用extractVariables(prompt.content)提取变量,并用默认值初始化表单状态;
2. 若没有任何变量,直接跳过表单,展示平台列表(所以无变量 Prompt 一次 Enter 即达平台选择);
3. 有变量时渲染Form,每个变量一个TextField(初始值为默认值、placeholder 提示Enter <name>),底部实时显示编译后的Preview预览;
4. 表单操作区提供Run Prompt(提交)与Copy Compiled Prompt(⌘C,复制编译后的最终文本)。

平台清单与 URL 构造规则

平台定义同样在 src/utils.ts,每个Platform包含四个关键属性:id、name、baseUrl、supportsQuerystring(该站是否支持通过 URL 参数自动填入 Prompt),部分平台额外标记isDeeplink: true。

Chat Platforms(17 个):ChatGPT、Claude、Microsoft Copilot、DeepSeek、fal.ai Sandbox、Gemini、Goose、Grok、HuggingChat、Meta AI、Manus、Le Chat、Perplexity、Phind、Pi、Poe、You.com。

Code Platforms(10 个):Windsurf、Cursor、VS Code、VS Code Insiders、GitHub Copilot、Netlify、Bolt、Lovable、v0、AI2SQL。

imagePlatforms与videoPlatforms目前为空数组——从源码结构看,这是为未来接入媒体生成平台预留的扩展位(与主站 Prompt 类型中的 IMAGE/VIDEO 对应)。

URL 构造由buildUrl()按平台逐一处理,典型规则(均可在源码中逐条核对):

执行策略在PlatformList.handleRun()中:

• supportsQuerystring === true:buildUrl()生成带参 URL 并open(url)直接打开,提示"Opening in <平台名>";
• supportsQuerystring === false:先把 Prompt 文本写入剪贴板,再打开平台主站,提示"Paste with ⌘V"。

列表界面用图标区分两种模式:播放图标(自动填充)与剪贴板图标(仅复制到剪贴板)。执行完成后popToRoot()回到根列表。

键盘快捷键

README 中声明的快捷键与源码中的shortcut定义完全一致:

源码中还可看到两个 README 未列出的辅助快捷键:⌘ D查看 Prompt 详情(src/search-prompts.tsx 中的 View Details)、变量表单内的⌘ C复制编译后文本(src/components/run-prompt.tsx)。

配置:Base URL 与自托管实例

README 声明的配置项只有一个,在 package.json 的preferences中定义:

"preferences": [ { "name": "baseUrl", "title": "Base URL", "description": "The base URL of the prompts.chat instance", "type": "textfield", "default": "https://prompts.chat", "required": false } ]

运行时,所有网络请求与 Web 链接都从这一偏好取值。src/api.ts 中的读取逻辑做了尾斜杠归一化与空值兜底:

function getBaseUrl(): string { const { baseUrl } = getPreferenceValues<PromptsChatPreferences>(); return baseUrl?.replace(/\/$/, "") || "https://prompts.chat"; }

因此https://your-instance.com/与https://your-instance.com等价,留空则回落到官方实例。getPromptUrl(username, slug)生成的"在浏览器中打开"链接为${baseUrl}/${username}/${slug},同样跟随 Base URL——把 Base URL 改成你的自托管地址后,搜索缓存、在线 API、浏览器打开详情三处会全部指向你的实例。自托管部署细节可参考仓库根目录的 SELF-HOSTING.md 与 compose.yml。注意前提是:自托管实例必须暴露扩展所依赖的公开端点(/prompts.json、/api/prompts、/api/prompts/search及/{username}/{slug}页面)。

本地开发、构建与发布

扩展源码位于 packages/raycast-extension 目录(含 tsconfig.json、eslint.config.mjs 等标准 Raycast 工程文件),package.json中的 scripts 即完整的开发闭环:

# 在 packages/raycast-extension 目录下 npm install # 安装 @raycast/api 等依赖 npm run dev # 等价于 ray develop,在 Raycast 开发环境中实时调试 npm run lint # ray lint,代码检查 npm run fix-lint # ray lint --fix npm run build # ray build,产出可分发的扩展包 npm run publish # npx @raycast/api@latest publish,发布到 Raycast Store

目录结构一览,便于按文件定位功能:

• src/api.ts — Base URL 解析与在线 API 封装;
• src/cache.ts — 全量下载、LocalStorage 缓存、本地检索;
• src/utils.ts — 变量提取/编译、平台清单、buildUrl;
• src/types.ts —Prompt等数据结构;
• src/search-prompts.tsx、src/browse-prompts.tsx、src/random-prompt.tsx、src/browse-categories.tsx、src/download-prompts.tsx — 五个命令入口;
• src/components/run-prompt.tsx、src/components/prompt-detail.tsx — 共享 UI 组件。

小结

prompts.chat 的 Raycast 扩展用"全量缓存 + 本地检索 + URL 深链"的轻量架构,把社区 Prompt 库接入了 macOS 的键盘工作流:Download All Prompts 一次拉取/prompts.json,Search/Browse/Random/Category 四个命令全部离线可用,Run Prompt 则通过变量编译和 27 个平台的 URL 规则把 Prompt 一键送进目标 AI 工具。对自托管场景,仅需在偏好设置中改写 Base URL 即可把整条链路指向自己的实例。

【免费下载链接】prompts.chatf.k.a. Awesome ChatGPT Prompts. Share, discover, and collect prompts from the community. Free and open source — self-host for your organization with complete privacy.项目地址: https://gitcode.com/GitHub_Trending/aw/prompts.chat