App Intents 代码审查

快速参考

审查清单

• 若需访问 UI 或主线程资源，perform() 已标注 @MainActor
• perform() 在 30 秒超时限制内完成（不执行重型下载或计算任务）
• 自定义错误类型符合 CustomLocalizedStringResourceConvertible 协议
• EntityQuery.entities(for:) 能优雅地处理缺失的标识符
• 若需支持 Siri 语音输入，请使用 EntityStringQuery（而非普通 EntityQuery）
• suggestedEntities() 返回合理的默认值以辅助消歧
• AppShortcut 的短语中包含 .applicationName 参数
• 非可选的 @Parameter 具备合理默认值，或使用 requestValue()
• iOS 16 目标平台未使用 @IntentParameterDependency（该用法会导致崩溃）
• 短语在 AppShortcuts.strings 中本地化，而非 Localizable.strings
• App Intents 定义于应用 Bundle 中，而非 Swift Package（iOS 17 之前）
• 仅用于内部调用或 Widget 的 Intent 设置 isDiscoverable = false

何时查阅参考文档

• AppIntent 协议实现 → intent-structure.md
• 实体查询（Entity queries）、标识符、Spotlight 集成 → entities.md
• App Shortcuts、短语（phrases）、发现机制（discovery）→ shortcuts.md
• 参数验证、动态选项 → parameters.md

审查问题

1. perform() 是否对长时间运行的操作设置了超时处理？
2. 实体查询是否自包含（即在 Siri 上下文中不依赖 @Dependency 注入）？
3. 短语是否自然通顺，并明确包含应用名称？
4. SwiftData 模型是否通过 persistentModelID 传递，而非直接传递模型实例？
5. 从 SiriKit 迁移至 App Intents 是否会破坏用户已创建的快捷指令？

硬性准入条件（报告前必须满足）

对每个你计划报告的问题，请**按顺序**完成以下全部步骤。任一条件未满足前，不得继续后续操作。

1. 位置凭证（Location artifact） —— 问题描述中包含来自当前文件内容的 [FILE:LINE]（或行号范围）；该路径在本仓库中可解析。
2. 作用域通读（Scope read） —— 你已完整阅读被标记代码所在的整体类型定义：包括 AppIntent / AppEntity / EntityQuery / AppShortcutsProvider（或其等价类型），而不仅限于 diff 片段或代码片段。
3. 平台或集成声明（Platform or integration claim）（仅当问题依赖最低 iOS 版本、Swift Package 与应用 Target 区分、@IntentParameterDependency 可用性、SiriKit 迁移影响，或 isDiscoverable / 扩展放置位置等上下文时适用）—— 你须明确指出一个你已查验的具体凭证（例如 Xcode 项目中的 IPHONEOS_DEPLOYMENT_TARGET 或 Target 成员关系、Package.swift 中的 platforms 声明、Entitlements 文件，或 Intent 文件的实际存放位置）；或 将该问题降级为开放性问题（open question）并暂不报告。
4. 协议合规（Protocol） —— 本项已满足 review-verification-protocol 中规定的预报告步骤（若未满足，则不得生成任何问题）。

每个报告的问题请严格采用格式：[FILE:LINE] ISSUE_TITLE。第 4 条硬性准入条件即为此技能对应审查类型的完整预报告检查清单。