apple-targets

Apple 扩展目标技能参考

此目录包含所有受支持的 Apple 扩展和目标类型的完整技能文档。每份技能文档都提供 AI Agent 理解、实现和排查特定 Apple 扩展类型所需的一切内容，包括：

• Apple 文档链接和 WWDC 主题演讲引用
• 运行时行为和生命周期说明
• 实际用例和实现模式
• 可用于生产环境的 Swift 代码示例
• 平台可用性和版本要求
• 常见注意事项和调试技巧

安装此技能

使用 npx skills 将此技能安装到你的编码 Agent（Claude Code、Cursor、Codex 等）中：

npx skills add EvanBacon/expo-apple-targets/tree/main/skills/apple-targets

CLI 会自动检测你已安装的 Agent，并将 SKILL.md（以及此目录中的支持参考文档）复制到 Agent 的技能目录中（例如 .claude/skills/ 或 .agents/skills/）。安装后，每当你要求 Agent 构建 Apple 扩展或目标时，它都会自动加载这些指南。

如何使用这些技能

适用于 AI Agent：

1. 当用户询问特定扩展类型时（例如，“如何构建小组件？”或“我需要添加共享扩展”），请阅读相应的技能文档，以获取完整的实现指南。

2. 规划可能需要扩展的功能时（例如，“添加主屏幕显示” → 阅读 widget.md），请查阅技能文档，了解相关要求和限制。

3. 排查扩展问题时，请参考相关技能文档中的“注意事项”部分，其中汇集了 Apple Developer Forums 和实际经验中的常见问题。

4. 不确定哪种扩展类型适用于某个用例时，请浏览相关技能文档中的“用例”部分，找到最合适的选项。

每份技能文档的结构：

每份技能文档都遵循 _template.md 中定义的模板：

• Frontmatter：标题、一句话描述、最低 OS 版本
• Apple 文档：官方参考链接
• WWDC 历程：展示功能演进的主题演讲链接
• 功能说明：逐步介绍运行时行为
• 用例：按行业／应用类型整理的实际场景
• 关键类：重要框架类型表
• 实现：带有行内注释的可用于生产环境的 Swift 代码
• 与 @bacons/apple-targets 配合使用：此插件的设置说明
• 平台可用性：OS 版本矩阵
• 注意事项：常见错误、内存限制和无提示故障模式

按类别划分的技能

用户界面扩展

技能	扩展类型	何时阅读
widget.md	widget	用户需要主屏幕小组件、锁定屏幕小组件、实时活动、待机模式界面或控制中心控件（iOS 18+）。基于时间线的 SwiftUI 视图。
clip.md	clip	用户需要通过 NFC、二维码、App Clip 代码、Safari 横幅或“信息”链接触发的即时启动迷你应用。这不是扩展，而是一个受大小限制的应用目标。
share.md	share	用户希望自己的应用出现在系统共享表单中，以接收其他应用分享的 URL、图像、文本或文件。
action.md	action	用户需要在 Safari、“照片”或“文件”中使用上下文菜单操作来转换内容，并可选择返回修改后的数据。
keyboard.md	keyboard	用户需要具有专用输入功能的自定义系统键盘（表情符号选择器、GIF 搜索、特定语言布局、计算器）。
photo-editing.md	photo-editing	用户希望直接在“照片”应用的编辑界面中为照片/视频添加滤镜、调整效果或特效。
quicklook-preview.md	quicklook-preview	用户需要在 Quick Look 中为自定义文件类型提供带交互控件和多页内容的丰富预览。
quicklook-thumbnail.md	quicklook-thumbnail	用户需要为 Finder、“文件”应用和 Spotlight 中显示的自定义文件类型生成缩略图。

通知

技能	扩展类型	何时阅读
notification-service.md	notification-service	用户需要在推送通知显示之前下载图像、解密负载或修改通知内容。此扩展在后台运行，时间限制为 30 秒。
notification-content.md	notification-content	用户需要为展开的推送通知提供自定义 SwiftUI/UIKit 界面，并加入交互控件和丰富媒体。

Siri 与意图

技能	扩展类型	何时阅读
intent.md	intent	用户需要用于内置领域（消息、支付、锻炼、媒体播放、预约乘车）的 Siri 语音命令。使用旧版 SiriKit 框架。
intent-ui.md	intent-ui	用户在确认或处理意图时，需要在 Siri 界面中显示自定义 UI。这是 intent 扩展的配套组件。
app-intent.md	app-intent	用户需要用于快捷指令、Spotlight、Siri、专注模式过滤器和控制中心小组件的现代 App Intents（iOS 16+）。可替代自定义 .intentdefinition 文件。

网络与 VPN

技能	扩展类型	何时阅读
network-packet-tunnel.md	network-packet-tunnel	用户需要构建 VPN 客户端，通过自定义协议隧道传输设备的全部流量。支持经典和现代个人 VPN。
network-app-proxy.md	network-app-proxy	用户需要应用级网络过滤（按应用配置 VPN），让特定应用通过自定义代理路由流量。需要 MDM 或受监管设备。
network-dns-proxy.md	network-dns-proxy	用户需要在系统范围内拦截并响应 DNS 查询，以实现 DNS 过滤、日志记录或自定义解析。
network-filter-data.md	network-filter-data	用户需要进行深度数据包检测以过滤内容（家长控制、企业安全）。需要 Apple 特殊授权。

文件管理

技能	扩展类型	何时阅读
file-provider.md	file-provider	用户想在“文件” App 中提供云存储或远程文件系统，并支持按需下载、搜索和同步。
file-provider-ui.md	file-provider-ui	用户想为文稿选取器中的文件操作（共享、权限）提供自定义 UI。与 File Provider 扩展配套。

通信与电话

技能	扩展类型	何时阅读
message-filter.md	message-filter	用户想过滤收到的 SMS/MMS 消息，将垃圾信息、交易信息或促销信息分类到不同标签页。
call-directory.md	call-directory	用户想屏蔽电话号码，或为来电提供来电者 ID 标签。更新由系统管理的 SQLite 数据库。
unwanted-communication.md	unwanted-communication	用户想提供 UI，让用户向举报服务举报骚扰电话、消息或 FaceTime 呼叫。需要特殊授权。

内容与媒体

技能	扩展类型	何时阅读
broadcast-upload.md	broadcast-upload	用户想将 ReplayKit 屏幕录制流式传输到直播服务（Twitch、YouTube Live）。实时接收视频/音频缓冲区。
broadcast-setup-ui.md	broadcast-setup-ui	用户想提供自定义 UI 来配置直播（选择流密钥、隐私设置）。与直播上传扩展配套。
safari.md	safari	用户想使用 Safari Web 扩展（Manifest V3），包含内容脚本、后台页面，以及与宿主应用的原生消息传递。
content-blocker.md	content-blocker	用户想在 Safari 中使用基于规则的 JSON 声明式规则来拦截广告、跟踪器或隐藏内容。不执行 JavaScript。

教育与屏幕使用时间

技能	扩展类型	何时阅读
classkit-context.md	classkit-context	用户想通过 ClassKit 框架，将教育类 App 中的学生进度报告到 Apple 的 Schoolwork App。
device-activity-monitor.md	device-activity-monitor	用户想监控 App/网站使用情况，并在达到屏幕使用时间限制时触发操作。适用于家长控制和专注类 App。
shield-action.md	shield-action	用户想在用户尝试绕过屏幕使用时间限制屏蔽（被屏蔽的 App/网站）时显示自定义 UI。处理或拒绝该请求。
shield-config.md	shield-config	用户想在屏幕使用时间规则限制 App 或网站时显示自定义屏蔽 UI（屏蔽画面）。

身份验证与安全

技能	扩展类型	何时阅读
authentication-services.md	authentication-services	用户想在 Safari 和 App 中使用密码和通行密钥自动填充。这是 credentials-provider 的现代替代方案。支持创建/验证通行密钥（WebAuthn）。
credentials-provider.md	credentials-provider	用户想使用旧版密码自动填充（iOS 12+）。对于新项目，请改用 authentication-services，它同时支持密码和通行密钥。
smart-card.md	smart-card	用户想通过 CryptoTokenKit 框架使用智能卡或硬件令牌（YubiKey、PIV 卡）进行身份验证。适用于企业场景。
account-auth.md	account-auth	用户想修改 Kerberos 或其他企业单点登录（SSO）协议的身份验证请求。需要特殊授权。

位置与后台服务

技能	扩展类型	何时阅读
location-push.md	location-push	用户希望使用静默推送通知唤醒应用，以获取高精度位置更新。适用于车队追踪、配送应用和基于位置的提醒。
bg-download.md	bg-download	用户希望按需获取资源，或由系统的后台资源下载器管理大型资源下载。适用于游戏和媒体应用。

智能家居与 Matter

技能	扩展类型	何时阅读
matter.md	matter	用户希望添加 Matter 智能家居设备支持，以便通过“家庭”应用为设备配网。需要注册 MFi 并通过 Matter 认证。

打印

技能	扩展类型	何时阅读
print-service.md	print-service	用户希望发现网络打印机并向其打印，而不使用 AirPrint；或为专业打印机提供自定义打印渲染。

搜索与索引

技能	扩展类型	何时阅读
spotlight.md	spotlight	用户希望在 Spotlight 中为应用内容建立索引、提供丰富的搜索结果，并处理从 Spotlight 搜索触发的点按操作。使用 Core Spotlight 和 NSUserActivity。
spotlight-delegate.md	spotlight-delegate	用户希望使用后台扩展进行大规模 Spotlight 索引，并按系统管理的计划定期运行。仅限 macOS（不适用于 iOS）。

协作与会议

技能	扩展类型	何时阅读
virtual-conference.md	virtual-conference	用户希望将视频会议应用与系统通话界面和 CallKit 集成，从而启用接力、画中画和系统通话控制。

Apple Watch

技能	扩展类型	何时阅读
watch.md	watch	用户希望开发独立的 watchOS 应用，包含复杂功能、锻炼时段、HealthKit 集成，以及用于与 iPhone 同步的 Watch Connectivity。这不是扩展，而是一个完整的应用目标。

目标类型与扩展

应用目标（不是扩展）：

• App Clip（clip）— 使用产品类型 com.apple.product-type.application.on-demand-install-capable
• watchOS App（watch）— 使用产品类型 com.apple.product-type.application

这些都是完整的应用，拥有自己的 Info.plist、应用图标和生命周期。它们不使用 NSExtensionPointIdentifier。

其他所有类型都是应用扩展，使用产品类型 com.apple.product-type.app-extension，并在其 Info.plist 中声明扩展点标识符。

常见用例速查

用户说……	阅读此技能文档
“添加主屏幕小组件”	widget.md
“添加共享扩展”	share.md
“构建即时 App / App Clip”	clip.md
“与 Siri 集成”	intent.md 或 app-intent.md
“修改推送通知”	notification-service.md
“自定义通知界面”	notification-content.md
“构建 VPN 应用”	network-packet-tunnel.md
“密码管理器自动填充”	authentication-services.md
“拦截骚扰电话”	call-directory.md
“过滤短信垃圾信息”	message-filter.md
“添加到文件 App”	file-provider.md
“自定义键盘”	keyboard.md
“照片滤镜扩展”	photo-editing.md
“Safari 广告拦截器”	content-blocker.md
“Safari 扩展”	safari.md
“直播 / 屏幕录制”	broadcast-upload.md
“watchOS 应用”	watch.md
“屏幕使用时间家长控制”	device-activity-monitor.md
“智能家居 / Matter”	matter.md
“打印到网络打印机”	print-service.md
“Spotlight 搜索集成”	spotlight.md

使用 @bacons/apple-targets 创建新扩展

每份技能文档都包含一个“使用 @bacons/apple-targets”部分，其中介绍了三步设置：

# 1. Run the CLI to scaffold the extension
bunx create-target <type>

# 2. Ensure the plugin is in app.json
{
  "expo": {
    "plugins": [["@bacons/apple-targets"]]
  }
}

# 3. Generate the native project
npx expo prebuild --clean

<type> 参数对应各技能文档标题中显示的扩展类型 slug（例如 widget、share、clip、notification-service）。

何时运行 Prebuild

由于目标源文件位于 /ios 目录之外，并且是链接到 Xcode 项目中（而非复制），因此 Swift 代码更改会自动同步。编辑代码时无需重新运行 prebuild。

• 运行 prebuild --clean 的情况：

  • 创建新目标后的初始设置
  • 修改 expo-target.config.js（图标、颜色、权限、bundle ID、框架）
  • 修改 app.json 插件配置
  • 添加或移除目标
  • Xcode 项目损坏或出现原因不明的构建失败

• 运行 prebuild（不带 --clean） 的情况：

  • 需要重新生成项目，但希望保留手动进行的 Xcode 修改
  • 更新插件版本并进行少量项目更改

• 无需运行 prebuild 的情况：

  • 在 targets/<name>/ 目录中编辑 Swift 代码——文件通过链接引入，更改会立即显示在 Xcode 中
  • 在现有目标中添加或修改 Swift 文件
  • 目标实现的大多数日常开发工作

这种架构使你无需不断重新生成整个 Xcode 项目，就能迭代扩展代码，从而加快开发速度并保留手动进行的项目自定义。

权限与功能指南

entitlements/ 目录包含适用于多种扩展类型的 iOS 权限和功能指南：

指南	何时阅读
entitlements/app-groups.md	用户需要在主应用和扩展（小组件、共享、通知、App Clip）之间共享数据。涵盖命名约定、UserDefaults 套件、共享容器、Keychain 访问组以及自动 EAS 配置。

权限指南解答的常见问题：

• “如何在应用和小组件之间共享数据？” → 阅读 app-groups.md
• “我的扩展无法访问主应用中的 UserDefaults” → 阅读 app-groups.md
• “EAS 如何处理 App Groups 代码签名？” → 阅读 app-groups.md

新建技能的模板

如果需要编写新的技能文档，请以 _template.md 为起点。它定义了必需的 frontmatter、章节结构、代码示例格式和质量检查清单。

其他资源

• CLAUDE.md（项目根目录）：@bacons/apple-targets 插件本身的开发环境设置、构建说明和架构说明
• Apple Developer Documentation：每项技能都链接到 Apple 官方文档和 WWDC 会议
• Expo Documentation：https://docs.expo.dev/config-plugins/introduction/
• Continuous Native Generation：https://docs.expo.dev/workflow/continuous-native-generation/