Apple 开发者文档搜索（Raycast 私人扩展）

这是一个供组织内部和个人使用的 Raycast 扩展，用于在 Raycast 中快速搜索 Apple 开发者文档。

它在原版 Apple Developer Docs 扩展的基础上增加了 Apple 历史归档文档搜索：除了当前的 API、框架、示例代码和 WWDC 内容，还可以搜索 Apple 已经从主站下线、但仍保留在 Documentation Archive 中的旧文档和章节。

本仓库是私人维护版本，不是 Raycast Store 官方发布版本，也不代表 Apple 或 Raycast。

主要功能

• 搜索当前 Apple Developer Documentation。
• 搜索示例代码、视频和一般开发者内容。
• 可选搜索 Apple Documentation Archive 中的历史文档。
• 首次使用归档搜索时，自动下载总索引并建立章节级索引。
• 将在线结果和归档结果按统一相关度排序。
• 提供 Archive 筛选器，只查看历史归档结果。
• 显示下载、建立索引、完成和失败状态。
• 保存最近访问过的搜索结果，并根据当前查询过滤历史记录。

使用前提

使用本扩展需要：

• macOS。
• 已安装并能正常运行的 Raycast。
• Node.js 和 npm。建议使用当前维护中的 Node.js 长期支持版本。
• 能够访问 Apple Developer 网站；实时搜索和首次建立归档索引都需要网络。
• 如需从 GitHub 克隆私人仓库，需要拥有 XiyouMobile3G-iOS 组织中本仓库的读取权限。

Raycast 是运行本扩展的必要依赖。本项目不是独立的 macOS 应用，不能脱离 Raycast 单独使用。

安装

1. 克隆仓库

git clone https://github.com/XiyouMobile3G-iOS/Raycast-Apple-Developer-Docs.git
cd Raycast-Apple-Developer-Docs

也可以使用 GitHub CLI：

gh repo clone XiyouMobile3G-iOS/Raycast-Apple-Developer-Docs
cd Raycast-Apple-Developer-Docs

2. 安装依赖

npm install

3. 注册开发扩展

npm run dev

等待终端出现：

ready - built extension successfully

npm run dev 会构建扩展、将其注册到 Raycast，并监听源码变化。私人开发和使用期间建议保持这个进程运行。

仅运行 npm run build 会生成构建文件，但在扩展曾被用户从 Raycast 卸载的情况下，不一定会重新注册命令。因此首次安装或重新安装应运行 npm run dev。

在 Raycast 中使用

1. 打开 Raycast。
2. 搜索命令 Search Documentation。
3. 确认副标题为 Apple Developer。
4. 输入关键词，例如 SwiftUI、UIViewController 或 Core Data。
5. 使用搜索框右侧的类型筛选器切换全部、文档、示例代码、视频或归档结果。

主搜索界面显示的是命令标题 Search Documentation，因此只搜索仓库名或扩展包名时可能找不到命令。

启用历史归档文档

归档搜索默认关闭，需要手动开启：

1. 找到 Search Documentation 命令。
2. 打开命令操作菜单，选择 Configure Command。
3. 开启 Include Documentation Archive。
4. 运行命令，选择 all 或 archive 筛选器。
5. 输入至少两个非空字符。

扩展没有单独的“下载归档”按钮。满足以上条件后，它会自动：

1. 下载 Apple 历史文档总索引。
2. 找出可建立章节索引的书籍。
3. 并发获取各书籍的章节目录。
4. 把结果缓存在本地供后续搜索使用。

首次索引所需时间取决于网络和 Apple 归档服务状态。界面会显示当前处理进度。

本地数据与网络请求

扩展会访问以下 Apple 服务：

• 当前开发者内容搜索接口。
• developer.apple.com/library/archive/ 下的历史文档总索引和章节索引。

归档缓存使用 Raycast 的本地缓存接口，命名空间为 apple-developer-docs-archive，容量上限约 25 MiB。搜索历史使用 Raycast LocalStorage 保存。项目不会把搜索历史上传到本仓库。

常用开发命令

# 开发、注册并监听源码
npm run dev

# 构建并检查 TypeScript
npm run build

# 代码规范检查
npm run lint

# 自动修复可修复的规范问题
npm run fix-lint

更新

git pull
npm install
npm run dev

如果依赖锁文件没有变化，通常不需要重复安装依赖，但运行 npm install 可以确保本地依赖与仓库一致。

卸载

在 Raycast 设置的扩展管理页面找到开发版本并移除。之后可删除本地仓库目录。

删除扩展后，如果以后只执行 npm run build，命令可能仍不会出现；重新安装时应执行 npm run dev 完成注册。

常见问题

找不到扩展

• 搜索命令名 Search Documentation，不要只搜索仓库名。
• 确认 Raycast 正在运行。
• 确认 npm run dev 仍在运行且没有构建错误。
• 如果曾手动卸载开发扩展，再次执行 npm run dev。

找不到归档下载按钮

这是正常行为。归档下载由查询自动触发。需要先在命令设置中启用 Include Documentation Archive，然后在 all 或 archive 筛选器下输入至少两个字符。

已启用归档搜索，但没有开始索引

• 确认查询不是空字符串或单个字符。
• 确认筛选器不是仅限视频、示例代码等非归档类型。
• 检查能否访问 developer.apple.com。
• 重新打开命令，观察是否显示网络错误状态。

重启 Raycast 后命令消失

重新进入仓库并执行：

npm run dev

开发扩展与 Raycast Store 安装的正式扩展不同，不应把一次 npm run build 当作永久安装。

项目结构

assets/                 扩展图标和图片资源
metadata/               Raycast 扩展展示图片
src/index.tsx           搜索界面和在线结果处理
src/hooks/              搜索历史与归档索引逻辑
src/config.ts           Apple 接口和归档地址
src/scoring.ts          搜索相关度计算
文档/智能体记忆/        私人开发说明和维护记忆
package.json            Raycast 清单、依赖和命令

维护说明

本仓库用于私人维护。功能来源、分支关系、归档实现约束和安装排障记录位于 文档/智能体记忆/。这些说明不应提交到 Raycast 官方扩展仓库的 PR。

许可证

本项目基于 Raycast Extensions 仓库中的 MIT 许可代码，具体内容见 LICENSE。