名称： raycast-extensions
描述： 使用 Raycast API 构建和维护 Raycast 扩展。在 @raycast/api、List、Grid、Detail、Form、AI.ask、LocalStorage、Cache、showToast 和 BrowserExtension 等场景下触发。请将此仓库的 references/api/*.md 文件作为组件规范和 API 使用的主要参考来源。

Raycast 扩展技能

使用 React、TypeScript 和 Raycast API 构建功能强大的扩展。

快速开始（工作流指南）

当需要实现或修复 Raycast 功能时，请遵循以下步骤：

1. 确定核心组件：判断 UI 需要使用 List、Grid、Detail 还是 Form。
2. 查阅参考文档：打开并阅读 references/api/ 目录下的对应文件（例如 references/api/list.md）。
3. 使用默认规范：
   • 用户反馈：使用 showToast 处理加载/成功/失败状态。仅在快速后台任务完成时使用 showHUD。
   • 数据管理：频繁使用或临时数据使用 Cache，需要持久化的用户数据使用 LocalStorage。
   • 权限访问：在使用 AI 或 BrowserExtension 前，务必先检查 environment.canAccess(AI) 或 environment.canAccess(BrowserExtension)。
4. 实现代码：使用 @raycast/api 组件提供简洁的实现代码。
5. 引用说明：链接回你所使用的具体 references/api/*.md 文件。

实用模式指南

1. 列表与网格（可搜索界面）

文本密集型数据使用 List，图像密集型数据使用 Grid。
- List 参考 | Grid 参考

<List isLoading={isLoading} searchBarPlaceholder="搜索项目..." throttle>
  <List.Item
    title="项目标题"
    subtitle="副标题"
    accessories={[{ text: "标签" }]}
    actions={
      <ActionPanel>
        <Action.Push title="查看详情" target={<Detail markdown="# 详情" />} />
        <Action.CopyToClipboard title="复制" content="值" />
      </ActionPanel>
    }
  />
</List>

2. 详情视图（富文本 Markdown）

用于显示长篇幅内容或项目详情。
- Detail 参考

<Detail
  isLoading={isLoading}
  markdown="# 标题\n内容在此。"
  metadata={
    <Detail.Metadata>
      <Detail.Metadata.Label title="状态" text="活跃" icon={Icon.Checkmark} />
    </Detail.Metadata>
  }
/>

3. 表单（用户输入）

务必包含 SubmitForm 操作。
- Form 参考

<Form
  actions={
    <ActionPanel>
      <Action.SubmitForm onSubmit={(values) => console.log(values)} />
    </ActionPanel>
  }
>
  <Form.TextField id="title" title="标题" placeholder="输入标题" />
  <Form.TextArea id="description" title="描述" />
</Form>

4. 反馈与交互

多数反馈场景优先使用 showToast。
- Toast 参考 | HUD 参考

// 成功/失败
await showToast({ style: Toast.Style.Success, title: "成功！" });

// HUD（覆盖层）
await showHUD("完成！");

5. 数据持久化

性能优先使用 Cache，持久化存储使用 LocalStorage。
- Cache 参考 | Storage 参考

// Cache（同步/临时）
const cache = new Cache();
cache.set("key", "value");

// LocalStorage（异步/持久化）
await LocalStorage.setItem("key", "value");

6. AI 与浏览器扩展（受限 API）

始终使用 environment.canAccess 进行检查。
- AI 参考 | Browser 参考

if (environment.canAccess(AI)) {
  const result = await AI.ask("提示词");
}

if (environment.canAccess(BrowserExtension)) {
  const tabs = await BrowserExtension.getTabs();
}

其他资源

API 参考目录

• UI 组件
  • 操作面板
  • 详情视图
  • 表单
  • 网格
  • 列表
  • 用户界面
• 交互功能
  • 操作
  • 弹窗
  • 键盘
  • 导航
  • Raycast 窗口搜索栏
• 工具与服务
  • AI
  • 浏览器扩展
  • 剪贴板
  • 环境
  • 反馈与 HUD
    • HUD
    • Toast
  • OAuth
  • 系统工具
• 数据与配置
  • 缓存
  • 颜色
  • 图标与图像
  • 偏好设置
  • 存储
• 高级功能
  • 命令相关工具
  • 菜单栏命令
  • 工具
  • 窗口管理

示例

查看结合了多种组件和 API 的端到端示例，请参阅 examples.md。