pp-apple-docs

Apple Developer Documentation — Printing Press CLI

前置条件：安装 CLI

此 skill 使用 apple-docs-pp-cli 二进制文件。**调用此 skill 中的任何命令前，必须确认已安装 CLI。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。macOS/Linux 上默认将二进制文件安装到 $HOME/.local/bin，Windows 上则安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install apple-docs --cli-only
   

2. 验证：apple-docs-pp-cli --version
3. 确保报告的安装目录位于将调用此 skill 的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接通过 Go 安装的方式（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/developer-tools/apple-docs/cmd/apple-docs-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。验证成功前，不要继续执行 skill 命令。

何时使用此 CLI

当你需要在终端中阅读 Apple 文档、Agent 需要依据最新 Apple API 生成 Swift 代码、规划平台迁移（iPad → visionOS、AppKit → SwiftUI），或撰写“iOS N 中有哪些内容已弃用”指南时，可以使用此 CLI。本地 SQLite 存储支持查询——跨框架 grep、快照差异、弃用断崖——这些功能是在线文档查看器所不具备的。

不适用场景

请勿将此 CLI 用于：

• 请勿使用此 CLI 编写 Apple ID 或 App Store Connect API 调用；这些操作请使用单独的 App Store Connect CLI。
• 请勿将此 CLI 用作 Swift 包管理器；它读取的是文档，而非源代码。
• 请勿使用此 CLI 获取完整的 WWDC 视频文字稿；它会索引文档页面中的 WWDC 引用，但不托管视频内容。

独特能力

这些能力在其他任何适用于此 API 的工具中都不可用。

面向 Agent 的原生支持

• doc get — 将 50KB 以上的 DocC JSON 页面精简为 Agent 实际需要的字段——摘要、签名、平台，或三者全部——每次查询都能节省上下文令牌。

  当 Agent 依据 Apple 符号生成代码，且只需要摘要、签名和最低平台要求，而不需要完整讨论内容和“另请参阅”树时使用。

  apple-docs-pp-cli doc get 'swiftui/view/onappear(perform:)' --shape min --agent
  

• bundle — 将某个符号的 Markdown 及其深度为 1 的“另请参阅”页面打包为单个令牌预算内的内容块，可直接粘贴到 Agent 提示词中。

  当 Agent 需要关于某个符号及其最接近相关内容的完整上下文块，又不想执行 N 次往返和 N 次 JSON 解析时使用。

  apple-docs-pp-cli bundle 'swiftui/view/onappear(perform:)' --depth 1 --max-tokens 4000
  

会不断累积的本地状态

• port-to — 如果某个符号在目标平台上不可用，沿着 See-Also / Replacement-Of 图遍历，直到找到一个在该平台上可用且本身未弃用的替代项。

  在 Apple 平台之间移植代码时（iPad → visionOS、AppKit → SwiftUI、已弃用 → 当前版本）使用；当你需要的是迁移目标，而不只是名称相似的 API 时尤其适用。

  apple-docs-pp-cli port-to visionOS uikit/uitableview --agent
  

• snapshot diff — 比较两个已存储的框架索引快照，并将每项差异归类为新增、已移除、已弃用或可能重命名（基于路径词干相似度）。

  在每次 WWDC 或小版本发布后使用，以便在框架层面发现新增、已移除或已弃用的符号。

  apple-docs-pp-cli snapshot diff swiftui --from 2025-06-09 --to 2026-05-28 --agent
  

• deprecation-cliff — 列出指定平台版本中所有已弃用的 Apple API，按框架和符号类型分组，并从引用中合并替代提示列。

  在规划迁移冲刺或撰写“今年有哪些内容已弃用”指南时使用；这是一次性获取完整列表的唯一方式。

  apple-docs-pp-cli deprecation-cliff --os iOS --version 18 --framework swiftui --agent
  

• conformance — 遍历框架的 relationshipsSections，列举协议的具体遵循类型及其祖先协议。

  在编写由协议驱动的代码（自定义 View、ObservableObject、Layout），且需要知道所有遵循该协议的具体类型时使用。

  apple-docs-pp-cli conformance View --framework swiftui --agent
  

• grep — 对所有已同步框架的符号执行正则表达式搜索，并可按类型、目标平台和弃用状态筛选。

  当你记得符号名称的大致形式，却不记得它属于何处，或要审查整个 Apple SDK 中的 API 模式时使用。

  apple-docs-pp-cli grep onAppear --framework swiftui --json
  

特定服务的模式

• wwdc symbols — 对于给定的 WWDC 场次 ID，列出文档页面引用该场次的所有符号。

  观看 WWDC 场次后，用于列举其中涉及的所有 API；也可用于查找某个 API 的官方首次发布场次。

  apple-docs-pp-cli wwdc symbols wwdc2024-10169 --agent
  

命令参考

doc get — 按路径获取任意文档页面（框架根页面、符号、方法、文章）

• apple-docs-pp-cli doc get <path> — 按路径获取文档页面，并以工具实际需要的形式返回（原始 DocC JSON、通过 --shape abstract|signature|platforms|min 投影，或通过 --markdown 渲染为 Markdown）。路径是 /documentation/ 下用小写字母和斜杠表示的标识符，例如 swiftui/view、swiftui/view/onappear(perform:)、foundation/url/init(string:)。

index — 获取框架的完整结构化索引（以树形形式包含每个符号）

• apple-docs-pp-cli index <framework> — 获取框架的完整分层索引。适用于离线全文搜索同步。索引较大（500KB–2MB）。

technologies — 列出所有 Apple 框架和技术（Swift、SwiftUI、UIKit 等）

• apple-docs-pp-cli technologies — 获取技术总索引，其中包含按主题分组的所有 Apple 框架。

新鲜度约定

此打印版 CLI 仅对已注册的、由存储支持的读取命令路径负责有限范围的新鲜度。在 --data-source auto 模式下，这些路径会检查 sync_state，并可能在读取本地数据前执行有限刷新。--data-source local 不会刷新。--data-source live 会读取 API，且不会修改本地存储。设置 APPLE_DOCS_NO_AUTO_REFRESH=1 可跳过新鲜度钩子，而不改变数据源选择。

涵盖的路径：

• apple-docs-pp-cli technologies
• apple-docs-pp-cli technologies get
• apple-docs-pp-cli technologies list
• apple-docs-pp-cli technologies search

当 JSON 输出使用生成的来源信息封装时，新鲜度元数据会出现在 meta.freshness。应将其视为对应命令路径的当前缓存新鲜度，而非完整历史回填或特定 API 数据增强的保证。

查找合适的命令

当你知道想做什么，却不知道该用哪个命令时，可以直接询问 CLI：

apple-docs-pp-cli which "<capability in your own words>"

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中匹配最合适的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有足够可信的匹配项，此时可改用 --help，或缩小查询范围。

示例

查找某个符号在 iOS 中首次引入的版本

apple-docs-pp-cli doc get 'swiftui/view/onappear(perform:)' --shape platforms --agent --select platforms[].introducedAt

只返回平台可用性映射，不到 500 字节；完整页面则有 9KB。

列出所有遵循 View 的具体 SwiftUI 类型

apple-docs-pp-cli conformance View --framework swiftui --json --select symbol,kind

遍历本地图关系图 relationshipsSections；无法通过任何单个 Apple 端点实现。

今年的 WWDC 上，SwiftUI 有哪些变化？

apple-docs-pp-cli snapshot diff swiftui --from 2025-06-09 --to 2026-05-28 --classify --json

一次调用即可将每项变化分类为新增、移除、已弃用或可能已重命名。

查找 UIKit 符号在 visionOS 中的替代项

apple-docs-pp-cli port-to visionOS uikit/uitableview --agent

沿着 See-Also 和 Replacement-Of 边遍历，直到找到 visionOS 上可用的符号。

将符号文档打包为 Agent 上下文

apple-docs-pp-cli bundle 'swiftui/view/onappear(perform:)' --depth 1 --max-tokens 4000

以 Markdown 格式呈现该符号及所有深度为 1 的 See-Also 页面，并截断至指定的 token 预算。

身份验证设置

无需身份验证。https://developer.apple.com/tutorials/data/ 下的 DocC JSON 端点公开可用，并由 Apple 的 CDN 提供服务。

运行 apple-docs-pp-cli doctor 以验证设置。

Agent 模式

在任意命令后添加 --agent。这相当于添加：--json --compact --no-input --no-color --yes。

• 可通过管道传递 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留指定字段的子集。带点号的路径可深入嵌套结构；数组则逐项遍历。对于内容冗长的 API，这对控制上下文大小至关重要：

  apple-docs-pp-cli doc get swiftui/view --agent --select abstract,declaration,platforms
  

• 可预览 — --dry-run 显示请求内容，但不会发送

• 适合离线使用 — 同步／搜索命令在本地 SQLite 存储可用时可以使用它

• 非交互式 — 不会提示输入，所有输入都通过标志传入

• 只读 — 不要使用此 CLI 执行创建、更新、删除、发布、评论、点赞、邀请、下单、发送或其他会修改数据的请求

响应封装

从本地存储或 API 读取数据的命令，会将输出封装在一个来源信息对象中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 以获取数据，并查看 .meta.source 以判断数据来自实时来源还是本地存储。只有当 stdout 连接到终端，且未设置任何机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将便于阅读的 N results (live) 摘要输出到 stderr；通过管道接收的内容、Agent 使用者以及显式指定格式的运行都会在 stdout 上获得纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

apple-docs-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
apple-docs-pp-cli feedback --stdin < notes.txt
apple-docs-pp-cli feedback list --json --limit 10

条目会保存在本地的 ~/.local/share/apple-docs-pp-cli/feedback.jsonl 中。只有在设置了 APPLE_DOCS_FEEDBACK_ENDPOINT，且传入 --send 或设置 APPLE_DOCS_FEEDBACK_AUTO_SEND=true 时，才会将条目发送到外部。默认仅保存在本地。

写下让你感到意外的地方，而不是提交 Bug 报告。简短、具体、一行即可：这才是能不断积累价值的内容。

输出传递

每个命令都接受 --deliver <sink>。输出会发送到指定的 sink，同时也可选择输出到 stdout，或取代 stdout 输出，这样 Agent 就能路由命令结果，无需手动通过管道传递。支持三种 sink：

Sink	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子性地写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（使用 --compact 时，内容类型为 application/json 或 application/x-ndjson）

不支持的协议会被拒绝，并返回结构化错误，指出支持的协议。Webhook 请求失败时会返回非零状态，并在 stderr 中记录 URL 和 HTTP 状态。

命名配置

配置文件是一组已保存的标志值，可在多次调用中重复使用。当计划任务中的 Agent 每次运行都使用相同配置调用同一命令时，可以使用它——这是 HeyGen 的“Beacon”模式。

apple-docs-pp-cli profile save briefing --json
apple-docs-pp-cli --profile briefing doc get swiftui/view
apple-docs-pp-cli profile list --json
apple-docs-pp-cli profile show briefing
apple-docs-pp-cli profile delete briefing --yes

显式标志始终优先于配置文件中的值；配置文件中的值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置文件，以便 Agent 在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
5	API 错误（上游问题）
7	触发速率限制（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 apple-docs-pp-cli --help 的输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
3. 其他任何内容 → 直接使用（作为带 --agent 的 CLI 命令执行）

MCP 服务安装

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/developer-tools/apple-docs/cmd/apple-docs-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add apple-docs-pp-mcp -- apple-docs-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which apple-docs-pp-cli 如果未找到，请提供安装选项（参见本技能开头的先决条件）。
2. 根据用户查询，从上文的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

   apple-docs-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，请查看子命令帮助：apple-docs-pp-cli <command> --help。