NSHipster/sosumi.ai
Making Apple docs AI-readable
sosumi.ai – AI 可读的 Apple 开发者文档
是什么 : 一个托管在 Cloudflare Workers 上的小型 Web 服务，将通常由 JavaScript 渲染的 Apple 开发者文档页面（包括 Swift 文档、HIG 和 WWDC 演讲转录）转换为干净的 Markdown 格式，使语言模型或其他自动化工具易于消费。
如何工作 ：
- 该服务将 Apple 文档 URL 的主机部分从
developer.apple.com（或 Swift-DocC 站点）重写为sosumi.ai。 - 解析底层 DocC JSON 端点，提取内容，并以 Markdown（或用于脚本的 JSON 包装 Markdown）形式返回。
- 对于外部 Swift-DocC 站点，也可以以相同方式代理，尊重
robots.txt并使用自定义sosumi-ai用户代理。
主要使用方式
- HTTP API – 只需替换任何 Apple 文档或 WWDC 视频 URL 中的主机部分。
相同模式适用于人机界面指南和 WWDC 演讲转录 URL。https://developer.apple.com/documentation/swift/array → https://sosumi.ai/documentation/swift/array - MCP（消息控制协议）集成 – 一个支持流式传输的端点（
/mcp），可通过 HTTP、Server-Sent Events 或简单 stdio 代理（npx mcp-remote …）使用。 - CLI –
npx @nshipster/sosumi fetch <url>（或全局安装为sosumi）。支持获取文档、HIG 页面、视频转录、外部 Swift-DocC 站点以及搜索 Apple 文档索引。使用--json可获取 JSON 输出。 - Chrome 扩展 – 在 Apple 文档页面上添加“复制 sosumi 链接”按钮（社区维护）。
- AI-代理技能文件 – 一个 Markdown 格式的技能定义文件（
https://sosumi.ai/SKILL.md），可通过npx skills add https://sosumi.ai添加到符合规范的代理中。
内置关键工具（通过 MCP 暴露）
searchAppleDocumentation– 全文搜索，返回标题、URL、面包屑等信息。fetchAppleDocumentation– 以 Markdown 格式获取文档页面。fetchAppleVideoTranscript– 获取 WWDC 会话转录内容。fetchExternalDocumentation– 获取任何公开的 Swift-DocC 页面（受主机允许/阻止列表限制）。
自托管
- 使用 Node 20+ 和 Hono 框架编写，因此可在 Cloudflare Workers、Vercel、Netlify 或任何支持 Hono 的平台运行。
- 克隆后，
npm install，然后npm run dev启动本地开发服务器（默认http://localhost:8787）。 - 生产部署使用 Cloudflare Workers（
wrangler），支持可选的 Ed25519 Web Bot 认证签名，适用于需要验证的主机。密钥通过WEB_BOT_AUTH_KEY秘密提供。 - 可通过
EXTERNAL_DOC_HOST_ALLOWLIST/EXTERNAL_DOC_HOST_BLOCKLIST环境变量限制外部主机访问。
开发与质量
- 使用 vitest 进行测试（
npm run test）。 - 使用 Biome 进行格式化/ lint（
npm run check）。 - CI/CD 将带标签的发布版本自动推送到 npm 和 GitHub 发布。
法律声明
- 非官方，与 Apple 无关联。仅按需获取页面，尊重 robots 指令，不存储永久副本。
快速开始
# 克隆并本地运行
git clone https://github.com/nshipster/sosumi.ai.git
cd sosumi.ai
npm install
npm run dev # 打开 http://localhost:8787
# 使用 CLI
npx @nshipster/sosumi fetch https://developer.apple.com/documentation/swift/array
有用链接
相关
- 项目
- 项目
- 项目
- 项目
- 项目