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
有用連結
相關
- 專案
- 專案
- 專案
- 專案
- 專案