app-intents-code-review

App Intents 代码审查

快速参考

问题类型	参考
AppIntent 协议、perform()、返回类型	references/intent-structure.md
AppEntity、EntityQuery、标识符	references/entities.md
AppShortcutsProvider、短语、发现	references/shortcuts.md
@Parameter、验证、动态选项	references/parameters.md

审查清单

• 如果访问 UI／主线程资源，perform() 是否标记了 @MainActor
• perform() 是否能在 30 秒超时限制内完成（无繁重下载／处理）
• 自定义错误是否遵循 CustomLocalizedStringResourceConvertible
• EntityQuery.entities(for:) 是否能妥善处理缺失的标识符
• 如果需要 Siri 语音输入，是否使用了 EntityStringQuery（而非普通的 EntityQuery）
• suggestedEntities() 是否为消歧提供了合理的默认值
• AppShortcut 短语是否包含 .applicationName 参数
• 非可选的 @Parameter 是否有合理的默认值，或是否使用了 requestValue()
• iOS 16 目标是否未使用 @IntentParameterDependency（会导致崩溃）
• 短语是否本地化在 AppShortcuts.strings 中，而非 Localizable.strings
• iOS 17 之前，App Intents 是否定义在应用程序包中，而非 Swift Package 中
• 仅供内部／小组件使用的 intents 是否设置了 isDiscoverable = false

何时加载参考资料

• AppIntent 协议实现 -> intent-structure.md
• 实体查询、标识符、Spotlight -> entities.md
• App Shortcuts、短语、发现 -> shortcuts.md
• 参数验证、动态选项 -> parameters.md

审查问题

1. 对于长时间运行的操作，perform() 是否处理了超时限制？
2. 实体查询是否自包含（Siri 上下文中不使用 @Dependency 注入）？
3. 短语读起来是否自然，且包含应用名称？
4. SwiftData 模型是否通过 persistentModelID 传递，而非直接传递？
5. 从 SiriKit 迁移是否会破坏用户现有的快捷指令？

硬性门槛（报告前）

对每项准备报告的问题，按顺序完成以下步骤。满足通过条件前，不要继续。

1. 位置凭据 — 问题包含从当前文件内容复制的 [FILE:LINE]（或行范围）；该路径在此仓库中有效。
2. 读取相关范围 — 阅读包含被标记代码的完整类型：AppIntent／AppEntity／EntityQuery／AppShortcutsProvider（或等效类型），不能只看 diff 片段或代码片段。
3. 平台或集成声明（仅当问题取决于最低 iOS 版本、Swift Package 与应用目标的区别、@IntentParameterDependency 的可用性、SiriKit 迁移，或 isDiscoverable／扩展的位置时）— 指明检查过的一项具体凭据（例如 IPHONEOS_DEPLOYMENT_TARGET、Xcode 项目中的目标成员关系、Package.swift 中的 platforms、entitlements，或 intent 文件所在位置），或将问题删除或降级为待确认的问题。
4. 协议 — 此项必须满足 review-verification-protocol 中适用于此审查类型的报告前步骤（若未满足，则不得报告问题）。

每项报告的问题使用格式 [FILE:LINE] ISSUE_TITLE。硬性门槛 4 是此技能审查类型的完整报告前检查清单。