用途：指导用 TypeScript 和 @raycast/api 开发 Raycast 扩展，覆盖从脚手架、封装 CLI、状态管理到发布商店的完整流程。
主要能力：提供四阶段校验门（tsc --noEmit、dev-check、ray lint、ray build），说明各命令能捕获与遗漏的问题；给出仓库布局约定（扩展即仓库根目录，package.json 为清单，raycast-env.d.ts 由构建生成并需提交）；梳理入口点（view、no-view、menu-bar、AI tools、脚本命令）；提供封装 CLI 的传输层设计（Mutation 数据联合、绝对路径解析、execFile 数组、maxBuffer、超时、stderr 分类）；讲解 useCachedPromise 缓存与 mutate 乐观更新、错误描述符渲染、菜单栏限制、商店发布清单与 AI 工具层。
使用方式：可用 scripts/new-raycast-extension.sh 生成脚手架，随后 npm install、npm run build、just check；已有扩展可复制 Justfile、tsconfig、dev-check 模板。发布前运行 scripts/check-store-readiness.sh。
适用场景：构建或改造 Raycast 扩展、封装 CLI/API、排查仅在 Raycast 中出现的环境问题、菜单栏数据异常、动作回退、商店发布准备、添加 AI 工具。
限制：不适用于 Raycast 脚本命令、通用 React/TSX 质量、被封装 CLI 自身语义，也无法自动截取商店截图；部分内容仅限 macOS，Windows 支持情况资料未完全说明。