更新 SwiftUI API
系統性地透過 Sosumi MCP 掃描 Apple 的開發者文件,找出已棄用的 SwiftUI API 及其現代替代方案,並更新 swiftui-expert-skill/references/latest-apis.md。
先決條件
- Sosumi MCP 必須啟用且可用(提供
searchAppleDocumentation、fetchAppleDocumentation、fetchAppleVideoTranscript、fetchExternalDocumentation) - 對此儲存庫(或其分支)具有寫入權限
工作流程
1. 了解目前涵蓋範圍
讀取 swiftui-expert-skill/references/latest-apis.md 以了解:
- 已記錄哪些從棄用到現代的轉換
- 正在使用的版本區段(iOS 15+、16+、17+、18+、26+)
- 底部的快速查詢表
2. 載入掃描清單
讀取 references/scan-manifest.md(相對於此技能)。其中包含分類的 API 區域、文件路徑、搜尋查詢以及要掃描的 WWDC 影片路徑清單。
3. 掃描 Apple 文件
對於清單中的每個類別:
- 使用列出的查詢呼叫
searchAppleDocumentation來發現相關頁面。 - 使用特定的文件路徑呼叫
fetchAppleDocumentation以取得完整的 API 詳細資訊。 - 尋找棄用通知、「已棄用」標籤以及「請改用...」的指引。
- 記下現代替代方案可用的 iOS 版本。
- 可選地,為宣布 API 變更的 WWDC 場次呼叫
fetchAppleVideoTranscript。
批次處理相關的搜尋以提高效率。專注於尋找尚未收錄在 latest-apis.md 中的新棄用項目。
4. 比較並識別變更
將發現的結果與現有條目進行比較。將結果分類:
- 新的棄用項目:
latest-apis.md中尚未記錄的 API - 修正:需要更新的現有條目(版本錯誤、有更好的替代方案可用)
- 新的版本區段:如果新的 iOS 版本引入了棄用項目,則新增一個區段
5. 更新 latest-apis.md
完全遵循既定的格式。每個條目必須包含:
區段放置 -- 放在正確的版本區段下:
- 「總是使用(iOS 15+)」適用於長期棄用的 API
- 「當目標為 iOS 16+」/「17+」/「18+」/「26+」適用於依版本限制的變更
條目格式:
**總是使用 `modernAPI()` 而非 `deprecatedAPI()`。**
\```swift
// 現代
View()
.modernAPI()
// 已棄用
View()
.deprecatedAPI()
\```
快速查詢表 -- 在檔案底部新增一行:
| `deprecatedAPI()` | `modernAPI()` | iOS XX+ |
保持檔案頂部的註明行:
基於使用 Sosumi MCP 對 Apple 文件的比較,我們找到了最新推薦使用的 API。
6. 開啟 Pull Request
- 從
main建立一個名為update/latest-apis-YYYY-MM(使用當前年份和月份)的分支。 - 提交對
swiftui-expert-skill/references/latest-apis.md的變更。 - 透過
gh pr create開啟一個 PR,內容包含:- 標題:「更新最新的 SwiftUI API(月份 年份)」
- 內容:新的/變更的條目摘要,以及對 Sosumi MCP 的歸屬
Sosumi MCP 工具參考
| 工具 | 參數 | 回傳值 |
|---|---|---|
searchAppleDocumentation | query (字串) | 包含 results[] 的 JSON,每個結果有 title、url、description、breadcrumbs、tags、type |
fetchAppleDocumentation | path (字串,例如 /documentation/swiftui/view/foregroundstyle(_:)) | Markdown 格式的文件內容 |
fetchAppleVideoTranscript | path (字串,例如 /videos/play/wwdc2025/10133) | Markdown 格式的逐字稿 |
fetchExternalDocumentation | url (字串,完整的 https URL) | Markdown 格式的文件內容 |
提示
- 從廣泛的
searchAppleDocumentation查詢開始,然後使用fetchAppleDocumentation深入特定的路徑。 - Apple 的棄用文件通常會在頁面中顯示「已棄用」並連結到替代方案。
- WWDC 「SwiftUI 新功能」場次是尋找新引入替代方案的最佳來源。
- 若不確定棄用項目的確切 iOS 版本,請透過檢查擷取文件中的「可用性」區段來驗證。
- 如果某個 API 已棄用但沒有直接的替代方案,請註明這一點,而不是建議錯誤的替代方案。