axiom-apple-docs-research

Apple 文档研究

何时使用此技能

✅ 在以下情况下使用此技能：

• 研究 Apple 框架或 API（WidgetKit、SwiftUI 等）
• 需要包含代码示例的完整 WWDC 会议文字稿
• 查找 Apple Developer 文档
• 想从 WWDC 演示文稿中提取代码示例
• 基于 Apple 技术构建全面的技能

❌ 以下情况不要使用此技能：

• 第三方框架文档
• 通用网络研究
• 现有技能已回答的问题
• 基础 Swift 语言问题（请使用 Swift 文档）

相关技能

• 使用 superpowers-chrome:browsing 进行交互式浏览器控制
• 使用 writing-skills 根据 Apple 文档创建新技能
• 使用 reviewing-reference-skills 验证 Apple 文档技能

核心理念

Apple Developer 视频页面包含完整的逐字稿、时间戳和完整代码示例。Chrome 的自动捕获功能让这些内容无需手动复制即可立即访问。

关键要点：不要手动转录 WWDC 视频或从中复制代码。页面上已经有完整的逐字稿，并带有时间戳和格式。

通过 Chrome 获取 WWDC 会议文字稿

方法

Apple Developer 视频页面（developer.apple.com/videos/play/wwdc20XX/XXXXX/）包含 Chrome 会自动捕获的完整文字稿。

分步流程

1. 使用 Chrome 浏览器 MCP 工具访问页面：

   {
     "action": "navigate",
     "payload": "https://developer.apple.com/videos/play/wwdc2025/278/"
   }
   

   工具名称：mcp__plugin_superpowers-chrome_chrome__use_browser

   完整调用：

   Use the mcp__plugin_superpowers-chrome_chrome__use_browser tool with:
   - action: "navigate"
   - payload: "https://developer.apple.com/videos/play/wwdc2025/278/"
   

2. 查找自动捕获的文件：

   • Chrome 保存到：~/.../superpowers/browser/YYYY-MM-DD/session-TIMESTAMP/
   • 会话目录使用以毫秒为单位的 Unix 时间戳（例如，session-1765217804099）
   • 文件名格式：NNN-navigate.md（例如，001-navigate.md）

   查找最新会话：

   # List sessions sorted by modification time (newest first)
   ls -lt ~/Library/Caches/superpowers/browser/*/session-* | head -5
   

3. 阅读捕获的文字稿：

   • 完整口述内容及时间戳（例如，[0:07]、[1:23]）
   • 代码和 API 用法的说明（口头描述，而非格式化代码）
   • 章节标记和资源链接

可以获取的内容

✅ WWDC 文字稿包含：

• 完整口述内容及时间戳（例如，[0:07]、[1:23]）
• 演讲者提到的 API 名称（例如，widgetRenderingMode、supportedMountingStyles）
• 代码功能说明（“我会将 widgetRenderingMode 环境变量添加到小组件中”）
• 实现过程的分步讲解
• 章节标记和资源链接

❌ WWDC 文字稿不包含：

• 可直接复制粘贴的格式化 Swift 代码块
• 完整实现
• 结构化代码示例

重要须知：文字稿是口述内容，不是代码。你会读到“我会将 widgetRenderingMode 环境变量添加到小组件视图中”这样的句子，需要根据这些描述自行还原代码。

如果文字稿中的代码描述不够清楚

如果文字稿中的代码描述不够详细，请按以下备用流程操作：

1. 查看 Resources 标签页

   • 返回 WWDC 会议页面
   • 点击“Resources”标签页
   • 查找“Download Sample Code”或“View on GitHub”
   • 下载包含完整可运行实现的 Xcode 项目

2. 使用 sosumi.ai 查找 API 详情

   • 查找文字稿中提到的特定 API
   • 示例：文字稿中提到“widgetAccentedRenderingMode” → 查找 sosumi.ai/documentation/swiftui/widgetaccentedrenderingmode
   • 获取准确的签名、参数和用法

3. 跳转到视频中的时间戳

   • 使用文字稿中的时间戳，直接跳转到视频中的代码讲解
   • 示例：文字稿指出代码出现在 [4:23] → 观看对应的 30 秒片段
   • 比观看完整的 45 分钟会议更快

4. 结合多个来源

   • 文字稿 = 概念理解 + 工作流
   • Resources = 完整代码
   • sosumi.ai = API 详情
   • 结果：无需手动还原所有内容，即可全面了解

文字稿结构示例：

# Session Title - WWDC## - Videos - Apple Developer

## Chapters
- 0:00 - Introduction
- 1:23 - Key Topic 1

## Transcript
0:00
Speaker: Welcome to this session...

[timestamp]
Now I'll add the widgetAccentedRenderingMode modifier...

示例会话

WWDC 2025-278「Widgets 有哪些新变化」：

• 导航至：https://developer.apple.com/videos/play/wwdc2025/278/
• 捕获文件：001-navigate.md
• 内容：约 15 分钟的完整文字稿，包含 API 引用和代码概念

通过 sosumi.ai 获取 Apple 文档

为什么选择 sosumi.ai

Developer.apple.com 文档包含大量 HTML，难以解析。sosumi.ai 提供相同内容的整洁 Markdown 格式。

URL 模式

替代：

https://developer.apple.com/documentation/widgetkit

使用：

https://sosumi.ai/documentation/widgetkit

URL 模式规则

格式：https://sosumi.ai/documentation/[framework]

框架名称规则：

1. 小写 - 即使框架名称使用大写，也要全部改为小写（SwiftUI → swiftui）
2. 不含空格 - 移除所有空格（Core Data → coredata）
3. 不含连字符 - 移除所有连字符（App Intents → appintents，而非 app-intents）
4. 不区分大小写 - SwiftUI 和 swiftui 均可用，但建议使用小写

常见错误：

• ❌ app-intents → ✅ appintents
• ❌ axiom-core-data → ✅ coredata
• ❌ AVFoundation → ✅ avfoundation

示例：

框架名称	sosumi.ai URL
SwiftUI	sosumi.ai/documentation/swiftui
App Intents	sosumi.ai/documentation/appintents
Core Data	sosumi.ai/documentation/coredata
AVFoundation	sosumi.ai/documentation/avfoundation
UIKit	sosumi.ai/documentation/uikit

与 WebFetch 或 Read 工具搭配使用

WebFetch:
  url: https://sosumi.ai/documentation/widgetkit/widget
  prompt: "Extract information about Widget protocol"

Result: Clean markdown with API signatures, descriptions, examples

框架示例

框架	sosumi.ai URL
WidgetKit	https://sosumi.ai/documentation/widgetkit
SwiftUI	https://sosumi.ai/documentation/swiftui
ActivityKit	https://sosumi.ai/documentation/activitykit
App Intents	https://sosumi.ai/documentation/appintents
Foundation	https://sosumi.ai/documentation/foundation

常见研究工作流

工作流 1：研究新的 iOS 功能

目标：为新的 iOS 26 功能创建全面的技能。

1. 查找 WWDC 会议 — 搜索「WWDC 2025 [feature name]」
2. 获取文字稿 — 使用 Chrome 导航至每个会议
3. 阅读文字稿 — 提取关键概念、代码模式和注意事项
4. 获取 API 文档 — 使用 sosumi.ai 获取框架参考资料
5. 交叉验证 — 确认代码示例与文档一致
6. 创建技能 — 整合文字稿中的见解和 API 参考资料

节省时间：相比观看视频并手动转录，可节省 3-4 小时

工作流 2：深入了解 API

目标：了解特定 API 或协议。

1. sosumi.ai 文档 — 获取协议/类定义
2. WWDC 会议 — 搜索提及该 API 的会议
3. 代码示例 — 从文字稿代码块中提取
4. 验证模式 — 确保示例与最新 API 一致

工作流 3：研究多个会议

目标：全面了解多个年份的变化（例如，Widgets 的演进）。

1. 并行导航 — 使用 Chrome 访问 3-6 个会议
2. 阅读所有文字稿 — 比较 API 的演进情况
3. 整理时间线 — 梳理 iOS 14 → 17 → 18 → 26 的变化
4. 整合内容 — 创建带版本注释的统一技能

示例：Extensions & Widgets 技能使用了 6 场 WWDC 会议（2023-2025）

反面模式

❌ 不要：手动观看视频

BAD:
1. Play WWDC video
2. Pause and take notes
3. Rewind to capture code
4. Type out examples manually

Result: 45 minutes per session

✅ 应该：使用 Chrome 自动捕获

GOOD:
1. Navigate with Chrome
2. Read captured .md file
3. Copy code blocks directly
4. Reference timestamps for context

Result: 5 minutes per session

❌ 不要：抓取 developer.apple.com 的 HTML

BAD:
Use WebFetch on developer.apple.com/documentation
Result: Complex HTML parsing required

✅ 应该：使用 sosumi.ai

GOOD:
Use WebFetch on sosumi.ai/documentation
Result: Clean markdown, instant access

故障排除

未找到 Chrome 会话目录

现象：无法找到 001-navigate.md 文件

解决方案：

1. 检查 Chrome 是否确实已导航（查找 URL 确认信息）
2. 查找最新会话：ls -lt ~/Library/Caches/superpowers/browser/*/
3. 会话目录格式：YYYY-MM-DD/session-TIMESTAMP/

文字稿不完整

现象：文件存在，但缺少文字稿

解决方案：

1. 页面可能仍在加载——等待 2-3 秒
2. 尝试重新导航
3. 某些会议需要滚动页面才能加载完整内容

sosumi.ai 返回错误

症状：404 或 URL 无效

解决方案：

1. 确认框架名称拼写正确
2. 检查 sosumi.ai 格式：/documentation/[frameworkname]
3. 备用方案：使用 developer.apple.com，但请注意内容会是 HTML

验证清单

使用捕获的内容前：

• ☐ 转录内容包含时间戳
• ☐ 代码示例完整（未被截断）
• ☐ 包含演讲者姓名和章节标记
• ☐ 多位演讲者均已正确标注
• ☐ 保留了代码语法高亮

资源

技能：superpowers-chrome:browsing、writing-skills、reviewing-reference-skills

---

节省时间：与手动观看视频并转录相比，使用此技巧每场 WWDC 会议可节省 30-40 分钟。对于跨多场会议的全面研究，累计可节省 3-4 小时。