SuperAPI AI 工具集

apple-docs

编程与开发

查看项目

更新于 10-16 18:41

技能介绍

用途

apple-docs 用于在终端中查询 Apple 开发者文档,而不是凭记忆回答 Apple API、设计规范(HIG)和商店政策问题。它被定位为一种“查找”而非“流程”,因此没有命令包装它;其他移动发布类技能在需要重新推导某个被标记为过时的规格时会使用它。该技能始终可无人值守运行,因为它只读取数据。

主要能力

  • 从 Apple 官方来源回答 API、设计与政策问题,而非依赖回忆。
  • 处理 Apple 文档站为单页应用的问题:直接抓取 developer.apple.com/documentation/... 只会返回约 17 KB 的空壳,可见文本仅为“This page requires JavaScript”。真实内容以 DocC JSON 形式从并行的主机路径提供。
  • 提供 URL 到 JSON 的映射规则:在路径中插入 /tutorials/data 并在末尾追加 .json。
  • 提供按字段提取的 jq 配方,例如 abstract、签名、可用性与弃用、参数、discussion、topicSections、seeAlsoSections、breadcrumbs 等。
  • 说明如何从 metadata.platforms 读取可用性,并检查 deprecatedAt 而非 deprecated 布尔值(两者可能不一致)。
  • 设计规则使用 /tutorials/data/design/human-interface-guidelines/<page>.json 路由;商店政策使用服务端渲染的 HTML 页面。
  • 对本地 Swift 包或 Xcode 离线文档,提供 references/local-docs.md 参考。

使用方式

核心机制是 curl + jq。示例:

# docs URL:  https://developer.apple.com/documentation/uikit/uiviewcontroller/viewwillappear(_:)
# JSON URL:  insert /tutorials/data, append .json
curl -s "https://developer.apple.com/tutorials/data/documentation/uikit/uiviewcontroller/viewwillappear(_:).json" \
  | jq -r '.metadata.roleHeading + ": " + .metadata.title,
           ([.abstract[]?.text]|join("")),
           (.primaryContentSections[]|select(.kind=="declarations")|.declarations[].tokens|map(.text)|join("")),
           (.metadata.platforms[]|"  \(.name) \(.introducedAt // "—")")'

references/appledoc.sh 将上述调用包装为 appledoc show|search|index|hig 子命令,它是便利工具而非依赖;curl + jq 调用才是接口。

流程要点:

  1. 判断问题需要哪条路由——API 符号、HIG 还是商店政策。政策与指南页面以纯 HTML 抓取;文档与 HIG 页面则不是。
  2. 若已知文档 URL,插入 /tutorials/data 并追加 .json 转换。
  3. 若不知道确切路径,不要猜测同级 slug。没有可用的 Apple 搜索 API。使用按框架的索引路由查找路径,或沿父页面的 topicSections 向下查找。
  4. 抓取 JSON 并只提取问题所需字段,不要把整页读入上下文。
  5. 从 metadata.platforms 读取可用性,检查 deprecatedAt。
  6. 引用实际抓取的 URL,并标注 [verified];无法抓取的声明保持 [unverified]。
  7. 只加载某一步骤实际需要的参考文件。

适用场景

  • 需要确认某个 Apple API 的签名、可用平台与弃用状态。
  • 需要查阅 Apple 人机界面指南(HIG)中的设计规则。
  • 需要查阅 App Store 商店政策与 App Store Connect 帮助页面。
  • 需要重新推导其他技能标记为过时的规格数字。
  • 需要从 WWDC 会话页面提取摘要、章节、资源与文字记录。
  • 需要处理本地 Swift 包或 Xcode 离线文档。

限制

  • 这些页面体积很大:UIKit 索引为 4.8 MB,Foundation 索引为 6.6 MB,单个类页面为 327 KB。不要把抓取到的页面或索引直接 cat 进上下文,应通过 jq 或 grep 提取后丢弃。
  • 不适用于语言问题。Swift 语法、泛型、并发语义和标准库更适合直接回答,文档会增加抓取成本而不增加准确性。
  • 不适用于其他技能已覆盖的发布环节任务(签名、上传、审核就绪、截图规格、列表限制等)。
  • 不要把符号的完整讨论粘贴进答案,只引用决定问题的那句话并附上 URL。
  • 不要把 404 当作 API 不存在。JSON 端点的 404 更常意味着 slug 错误,应先通过索引解析路径。
  • 已知不可用的方式:developer.apple.com/search/search_data.php?q=… 返回 404;/search/api/ 与 /search/suggestions/ 返回 404;/search/?q=… 返回 200 但结果由客户端渲染,结果容器为空;直接抓取 /documentation/… 或 /design/human-interface-guidelines/… 返回 200 但只有约 150 字符的“This page requires JavaScript”;JSON 端点上的 ?language=objc 被忽略,响应字节完全相同;/tutorials/data/index/human-interface-guidelines 返回 200 但为空;docs-assets.developer.apple.com(示例代码 zip)在当前环境的代理处被阻止。
  • 没有第一方等价于 Android 文档搜索的接口;索引路由是最接近的替代,且是客户端 grep 而非排序搜索。
  • Apple 会不经通知地调整文档路径。当技能与实时抓取不一致时,以抓取为准,并报告差异以便更新技能。

验证说明

references/endpoints.md 中的每个端点在 2026-08-06 从该环境抓取,HTTP 状态与响应大小均有记录。四个失败的搜索候选也已抓取并记录失败。references/jq-recipes.md 中的每个配方都针对真实抓取页面执行过。codeVoice 陷阱是测试中发现的真实 bug:codeVoice 节点携带 .code 而非 .text,朴素的扁平化会静默丢弃行内代码。deprecated: false 与 deprecatedAt: "12.0" 并存的情况在 UIWebView 上被观察到,应读取 deprecatedAt。路径映射规则不区分大小写。references/local-docs.md 是最弱的文件,其中内容未被执行,因为编写环境为 Linux 且无 Xcode,相关命令与布局来自二手来源。示例代码 zip 主机在该环境的代理处不可达,可能在其他环境可用。