（1791期）raycast – 官方Raycast扩展开发完全指南

官方Raycast扩展开发完全指南 基于React与TypeScript构建Raycast原生扩展的官方API开发技能，覆盖UI组件、数据存储、AI与浏览器集成等完整能力 使用说明 Raycast Extensions Skill 综合评估 核心用法 该技能提供Raycast原生扩展开发的完整技术栈支持，基于官方@raycast/api构建。核心工作流包括： UI组件选型：根据数据类型选择List（文本密集型）或Grid（图像密集型），详情展示用Detail，表单输入用Form 参考驱动开发：强制引用references/api/*.md作为组件规格唯一真理源 反馈与数据策略：showToast用于加载/成功/失败状态，Cache处理高频临时数据，LocalStorage持久化用户配置 受限API安全访问：AI与BrowserExtension必须包裹environment.canAccess检测 显著优点 官方权威性：直接绑定Raycast官方API文档，组件签名、Props定义实时同步 React原生体验：基于React+TypeScript，开发者无需学习新框架 模块化架构：UI/交互/工具/数据/高级五大分类，30+细分API清晰组织 最佳实践内建：Cookbook模式涵盖List/Grid/Detail/Form/Feedback/Data/AI等高频场景 类型安全：TypeScript-first设计，编译期捕获API误用 潜在局限 生态锁定：深度绑定macOS Raycast平台，扩展无法迁移至其他启动器 运行时限制：AI与浏览器API需显式权限检测，增加代码复杂度 参考文件依赖：实际效能取决于references/api/*.md的完整性与更新及时性 无可视化调试：依赖Raycast开发者工具，断点与热重载体验弱于Web开发 适合人群 macOS重度用户：需将高频工作流（Jira、GitHub、内部工具）集成至命令面板 全栈/前端开发者：熟悉React生态，希望扩展个人工具链 效率工具创作者：计划发布至Raycast Store获取分成的独立开发者 企业IT团队：需构建内部CLI工具封装层，降低非技术同事使用门槛 常规风险 | 风险类别 | 具体表现 | 缓解建议 ||---------|---------|---------|| API版本漂移 | Raycast更新导致组件Props变更 | 锁定@raycast/api版本，关注官方Changelog || 权限配置遗漏 | AI/BrowserExtension未声明capabilities | 严格遵循environment.canAccess检查模式 || 数据持久化混淆 | Cache与LocalStorage选用不当 | 遵循"Cache=高频临时，Storage=用户配置"原则 || 性能劣化 | 大数据集未启用throttle或虚拟化 | List/Grid开启throttle，分页加载 || 安全合规 | OAuth/Token管理不当 | 使用内置OAuth模块，禁止硬编码密钥 | 总体评价 该技能是Raycast扩展开发的事实标准入口，文档结构清晰、示例完备，适合作为Agent处理Raycast相关任务的首选技能。建议在实现复杂交互时，严格遵循"参考文档→Cookbook模式→实现→引用溯源"的四步流程。 原始说明 Build and maintain Raycast extensions using the Raycast API. Triggers on @raycast/api, List, Grid, Detail, Form, AI.ask, LocalStorage, Cache, showToast, and BrowserExtension. Use this repo's references/api/*.md files as the primary source of truth for component specs and API usage.