app-intents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write and review Swift code that exposes app functionality through the App Intents framework, ensuring correct protocol conformance, safe data flow, and idiomatic discoverability wiring.

Review process:

Check intent fundamentals (protocol,
```
perform()
```
, return types, dialog) using
```
references/fundamentals.md
```
.
Validate parameters and parameter options using
```
references/parameters.md
```
.
Validate entity types, display representations, and queries using
```
references/entities.md
```
.

Check the

AppShortcutsProvider

registration and discoverability UI using

references/shortcuts-and-siri.md

Validate
```
OpenIntent
```
navigation and snippet view return types using
```
references/open-and-snippet-intents.md
```
.
Check dependency injection and the data-controller pattern using
```
references/dependencies.md
```
.
Validate Spotlight indexing via
```
IndexedEntity
```
and attribute sets using
```
references/spotlight.md
```
.

Check

@AssistantEntity

@AssistantIntent

schema adoption using

references/assistant-schemas.md

If writing or reviewing tests for intents, use
```
references/testing-intents.md
```
.
Catch common mistakes using
```
references/anti-patterns.md
```
.

If doing partial work, load only the relevant reference files.

编写并审查通过App Intents框架暴露应用功能的Swift代码，确保协议合规、数据流安全，以及符合规范的可发现性配置。

审查流程：

参考
```
references/fundamentals.md
```
检查意图基础内容（协议、
```
perform()
```
、返回类型、对话）。
参考
```
references/parameters.md
```
验证参数及参数选项。
参考
```
references/entities.md
```
验证实体类型、展示形式及查询逻辑。

参考

references/shortcuts-and-siri.md

检查

AppShortcutsProvider

注册及可发现性UI。

参考
```
references/open-and-snippet-intents.md
```
验证
```
OpenIntent
```
导航及代码片段视图返回类型。
参考
```
references/dependencies.md
```
检查依赖注入及数据控制器模式。
参考
```
references/spotlight.md
```
验证通过
```
IndexedEntity
```
及属性集实现的Spotlight索引。

参考

references/assistant-schemas.md

检查

@AssistantEntity

@AssistantIntent

模式的适配情况。

若编写或审查意图测试代码，参考
```
references/testing-intents.md
```
。
参考
```
references/anti-patterns.md
```
排查常见错误。

若仅处理部分工作，只需加载相关参考文件。

Task-based routing

基于任务的路由

Match the user's goal to the read order. Load only what you need.

根据用户目标匹配阅读顺序，仅加载所需内容。

"Create my first App Intent"

"创建我的第一个App Intent"

```
references/fundamentals.md
```
- protocol,
```
perform()
```
, return types
```
references/shortcuts-and-siri.md
```
- register it so it shows up

```
references/fundamentals.md
```
- 协议、
```
perform()
```
、返回类型
```
references/shortcuts-and-siri.md
```
- 注册以使其可见

"Add a parameter the user picks in Shortcuts"

"添加可在Shortcuts中选择的参数"

```
references/parameters.md
```
-
```
@Parameter
```
, prompts, disambiguation
```
references/entities.md
```
- if the parameter is a domain entity

```
references/parameters.md
```
-
```
@Parameter
```
、提示、消歧义
```
references/entities.md
```
- 若参数为领域实体

"Make my app's data searchable from Siri / Spotlight"

"让我的应用数据可被Siri / Spotlight搜索"

references/entities.md

AppEntity

IndexedEntity

@Property

```
references/spotlight.md
```
- indexing strategies, attribute sets
```
references/shortcuts-and-siri.md
```
- flexible matching, phrase rules

references/entities.md

AppEntity

、

IndexedEntity

、

@Property

```
references/spotlight.md
```
- 索引策略、属性集
```
references/shortcuts-and-siri.md
```
- 灵活匹配、短语规则

"Show a summary / interactive view when Siri runs my intent"

"当Siri运行我的意图时展示摘要/交互式视图"

references/open-and-snippet-intents.md

- inline vs indirect snippets,

SnippetIntent

Button(intent:)

```
references/fundamentals.md
```
- return types and snippet design rules

references/open-and-snippet-intents.md

- 内联与间接代码片段、

SnippetIntent

、

Button(intent:)

```
references/fundamentals.md
```
- 返回类型及代码片段设计规则

"Open a specific thing in my app from Siri / Shortcuts"

"从Siri / Shortcuts打开应用中的特定内容"

references/open-and-snippet-intents.md

OpenIntent

URLRepresentableIntent

TargetContentProvidingIntent

```
references/dependencies.md
```
- navigator / scene routing

references/open-and-snippet-intents.md

OpenIntent

、

URLRepresentableIntent

、

TargetContentProvidingIntent

```
references/dependencies.md
```
- 导航器/场景路由

"Integrate with Apple Intelligence"

"与Apple Intelligence集成"

```
references/assistant-schemas.md
```
- schema macros, domains, Use Model action, onscreen content

references/entities.md

@Property

Transferable

(required for several schemas)

```
references/assistant-schemas.md
```
- 模式宏、领域、Use Model操作、屏幕内容

references/entities.md

@Property

、

Transferable

（部分模式必填）

"Support Visual Intelligence / image search"

"支持Visual Intelligence / 图片搜索"

references/assistant-schemas.md

IntentValueQuery

SemanticContentDescriptor

@UnionValue

references/entities.md

Transferable

OpenIntent

pairing

references/assistant-schemas.md

IntentValueQuery

、

SemanticContentDescriptor

、

@UnionValue

references/entities.md

Transferable

OpenIntent

配对

"Build an interactive widget or Control Center control"

"构建交互式小组件或控制中心控件"

references/open-and-snippet-intents.md

Button(intent:)

WidgetConfigurationIntent

ControlConfigurationIntent

ControlWidgetButton

```
references/dependencies.md
```
- App Group shared storage, process boundaries

references/open-and-snippet-intents.md

Button(intent:)

WidgetConfigurationIntent

ControlConfigurationIntent

ControlWidgetButton

```
references/dependencies.md
```
- App Group共享存储、进程边界

"Structure my app around App Intents"

"围绕App Intents构建应用架构"

```
references/fundamentals.md
```
- intents as canonical action layer

references/dependencies.md

@Dependency

, cross-module

AppIntentsPackage

```
references/entities.md
```
- entity-as-bridge pattern

```
references/fundamentals.md
```
- 将意图作为标准操作层

references/dependencies.md

@Dependency

、跨模块

AppIntentsPackage

```
references/entities.md
```
- 实体桥接模式

"Test my App Intents"

"测试我的App Intents"

```
references/testing-intents.md
```
- unit tests, mocking
```
@Dependency
```
, what you can't test

```
references/testing-intents.md
```
- 单元测试、模拟
```
@Dependency
```
、不可测试内容

"I'm hitting build errors or runtime bugs"

"遇到编译错误或运行时Bug"

```
references/anti-patterns.md
```
- 35+ catches with before/after fixes

```
references/anti-patterns.md
```
- 35+种错误案例及修复前后对比

Decision trees

决策树

Quick orientation when you know the task but not the right API.

当明确任务但不确定正确API时的快速指引。

Which intent protocol should I conform to?

应遵循哪种意图协议？

Generic action?
  → AppIntent

Opens the app to a specific entity?
  → OpenIntent (+ TargetContentProvidingIntent on iOS)

Renders an interactive view only, no business logic?
  → SnippetIntent

Needs to bring the app forward conditionally?
  → AppIntent with supportedModes (iOS 26+)
  → or ForegroundContinuableIntent (iOS 17-18)

Deletes entities with standard confirmation?
  → DeleteIntent

Routes a search query into the app?
  → ShowInAppSearchResultsIntent

Backs widget configuration?
  → WidgetConfigurationIntent (empty conformance, no perform)

Backs a Control Center control?
  → ControlConfigurationIntent

Has a universal-link URL representation?
  → URLRepresentableIntent + OpenIntent (no perform needed)

Matches an Apple Intelligence domain?
  → AppIntent + @AppIntent(schema: .domain.action)

通用操作？
  → AppIntent

打开应用到特定实体？
  → OpenIntent (+ iOS端的TargetContentProvidingIntent)

仅渲染交互式视图，无业务逻辑？
  → SnippetIntent

需要有条件地将应用前置？
  → AppIntent搭配supportedModes（iOS 26+）
  → 或ForegroundContinuableIntent（iOS 17-18）

通过标准确认删除实体？
  → DeleteIntent

将搜索查询路由到应用内？
  → ShowInAppSearchResultsIntent

为小组件配置提供支持？
  → WidgetConfigurationIntent（空协议实现，无需perform）

为控制中心控件提供支持？
  → ControlConfigurationIntent

具有通用链接URL表示？
  → URLRepresentableIntent + OpenIntent（无需perform）

匹配Apple Intelligence领域？
  → AppIntent + @AppIntent(schema: .domain.action)

Which entity type should I use?

应使用哪种实体类型？

Fixed set known at compile time?
  → AppEnum

Dynamic data with a persistent id?
  → AppEntity

Entity must appear in Spotlight?
  → AppEntity + IndexedEntity

Entity IS a file (scan, voice memo, exported image)?
  → FileEntity

Computed / aggregated data with no stable id?
  → TransientAppEntity

Needs Apple Intelligence schema awareness?
  → AppEntity + @AppEntity(schema: .domain.type)

Supports cross-app sharing?
  → AppEntity + Transferable

编译时已知的固定集合？
  → AppEnum

带持久化ID的动态数据？
  → AppEntity

实体需出现在Spotlight中？
  → AppEntity + IndexedEntity

实体是文件（扫描件、语音备忘录、导出图片）？
  → FileEntity

无稳定ID的计算/聚合数据？
  → TransientAppEntity

需要Apple Intelligence模式感知？
  → AppEntity + @AppEntity(schema: .domain.type)

支持跨应用共享？
  → AppEntity + Transferable

Which query should my entity use?

实体应使用哪种查询？

Small fixed set, enumerable?
  → EnumerableEntityQuery (also gets a basic Find intent)

Large dataset, searchable by name?
  → EntityQuery + EntityStringQuery

Many queryable properties, user should build predicates?
  → EntityPropertyQuery (auto-generates Find intent with comparators + sort)

Simple id-only lookup, no search?
  → UniqueIDEntityQuery

Visual intelligence / image search?
  → IntentValueQuery + SemanticContentDescriptor

小型固定集合，可枚举？
  → EnumerableEntityQuery（同时会生成基础Find意图）

大型数据集，可按名称搜索？
  → EntityQuery + EntityStringQuery

多个可查询属性，用户需构建谓词？
  → EntityPropertyQuery（自动生成带比较器+排序的Find意图）

仅按ID查找，无需搜索？
  → UniqueIDEntityQuery

视觉智能/图片搜索？
  → IntentValueQuery + SemanticContentDescriptor

Which property wrapper should I use on entity fields?

实体字段应使用哪种属性包装器？

Stored on the entity struct, should appear in Shortcuts/Find/summary?
  → @Property

Derived from an underlying model object (cheap to compute)?
  → @ComputedProperty (preferred over @Property for wrappers around models)

Derived AND should be indexed in Spotlight?
  → @ComputedProperty(indexingKey: \.keyName)

Expensive to compute (network, ML inference, heavy query)?
  → @DeferredProperty (async getter, only runs when system asks)

Internal to the entity, not shown anywhere?
  → plain stored property (no wrapper)

存储在实体结构体中，需在Shortcuts/Find/摘要中显示？
  → @Property

从底层模型对象派生（计算成本低）？
  → @ComputedProperty（优先于@Property用于模型包装器）

派生且需在Spotlight中索引？
  → @ComputedProperty(indexingKey: \.keyName)

计算成本高（网络、ML推理、复杂查询）？
  → @DeferredProperty（异步获取器，仅在系统请求时运行）

实体内部使用，不对外展示？
  → 普通存储属性（无需包装器）

Core Instructions

核心说明

Target iOS 16+ / macOS 13+ minimum for App Intents.
```
IndexedEntity
```
,
```
OpenIntent
```
, focus filters, and control widgets require iOS 16+;
```
@AssistantEntity
```
/
```
@AssistantIntent
```
schemas require iOS 18.2+; anchored relative date styles and many assistant schemas require iOS 18.4+.
Never make a SwiftData
```
@Model
```
class or other reference-type data model conform to
```
AppEntity
```
.
```
AppEntity
```
requires
```
Sendable
```
;
```
@Model
```
classes are not sendable. Create a separate
```
struct
```
entity that shadows the fields you want to expose.
Never pass
```
ModelContext
```
across actor boundaries.
```
ModelContext
```
is not sendable. Pass
```
ModelContainer
```
(which is sendable) and create a local context inside the actor that needs one.
Never expose an intent to Siri/Spotlight only by writing its type, always register it through an
```
AppShortcutsProvider
```
. Types not registered there will not appear in Shortcuts, Siri suggestions, or the action button picker.
Never write a Siri activation phrase without interpolating
```
\(.applicationName)
```
. The App Intents macro rejects phrases without it at compile time, because phrases without the app name would collide with other apps' commands.
Never reach back into a SwiftUI
```
@Query
```
from inside an intent.
```
@Query
```
only works inside a
```
View
```
. Run a one-shot
```
FetchDescriptor
```
through a
```
ModelContext
```
instead, or route through a centralized data controller.
Never instantiate services, data stores, or authentication managers inside
```
perform()
```
. Inject them through
```
@Dependency
```
and register them once in
```
App.init()
```
with
```
AppDependencyManager.shared.add(dependency:)
```
.
Never use
```
String(format:)
```
or manual concatenation for localized intent dialog. Use
```
LocalizedStringResource
```
, and use Foundation's grammar-agreement markdown (
```
^[\(count) item](inflect: true)
```
) inside an
```
AttributedString
```
for pluralization.
Prefer
```
OpenIntent
```
for "take me to this thing" actions,
```
AppIntent & ShowsSnippetView
```
for self-contained one-shot summaries, and
```
AppIntent & ShowsSnippetIntent
```
+ a paired
```
SnippetIntent
```
when the snippet contains
```
Button(intent:)
```
and needs to re-render after buttons fire.
Always set
```
static let isDiscoverable: Bool = false
```
on helper intents that only back a widget button, snippet button, or other intent - otherwise they pollute the user's Shortcuts library.
When an intent mutates data that widgets or control widgets display, call
```
WidgetCenter.shared.reloadAllTimelines()
```
inside
```
perform()
```
before returning.
When
```
Button(intent:)
```
lives inside a widget view, share state between the intent (runs in the app process) and the widget's timeline provider (runs in the extension process) via App Group
```
UserDefaults(suiteName:)
```
or a shared
```
ModelContainer
```
URL - never
```
UserDefaults.standard
```
or in-memory
```
@Dependency
```
state.
When entity data that appears in a shortcut phrase's key path changes (creation, rename, deletion), call
```
YourShortcutsProvider.updateAppShortcutParameters()
```
to invalidate the cached candidate list.
Prefer
```
EnumerableEntityQuery
```
when the whole set is small and cheap to load; implement
```
EntityQuery
```
+
```
EntityStringQuery
```
when the dataset is large or searchable; add
```
EntityPropertyQuery
```
to get a system-generated Find intent for free.
```
entities(for identifiers:)
```
is mandatory on every query; without it, parameter resolution breaks.
Mark entity fields that users might filter, sort, or reference in parameter summaries with
```
@Property
```
(stored) or
```
@ComputedProperty
```
(derived). Plain stored properties are invisible to the App Intents framework.
Use
```
TransientAppEntity
```
for return data that's computed on the fly (summaries, aggregates). Don't try to shoehorn it into
```
AppEntity
```
with a fake id.
When the entity already has a universal-link URL, conform it to
```
URLRepresentableEntity
```
and conform the open intent to
```
URLRepresentableIntent
```
- the system routes opens through your existing link handler without a
```
perform()
```
.
For entities visible onscreen that Siri should be able to understand, combine
```
.userActivity(_:element:)
```
on the view with
```
Transferable
```
conformance on the entity. Identification alone is not enough; Siri needs exportable content.
```
SnippetIntent.perform()
```
is called multiple times per user interaction (initial show, after each button tap, on appearance changes, on
```
reload()
```
). Keep it pure: read state, assemble the view, return. Never mutate app state or kick off slow work inside a snippet intent's
```
perform()
```
.
Respect hard limits: 10
```
AppShortcut
```
s per app, 1000 total trigger phrases (including parameter expansions). The first phrase in each shortcut's array is the primary one - it's shown on the Shortcuts home tile and as Siri's "what can I do with X?" answer.
Include at least one non-parameterized phrase per App Shortcut so it's discoverable before first launch; parameterized phrases don't appear in Spotlight until the app has run once and populated the parameter cache.
Prefer
```
supportedModes
```
+
```
continueInForeground
```
(iOS 26+) over
```
ForegroundContinuableIntent
```
/
```
needsToContinueInForegroundError
```
for new code that conditionally foregrounds. The newer form lets one intent declare it may run background or foreground based on runtime state.
Snippet views have a 340-point height ceiling; beyond this, scrolling breaks the glance overlay model. Link to the full app for deep content, and keep snippet text larger than system defaults for legibility at reading distance.
For text parameters that may receive input from Apple Intelligence's Use Model action, declare the type as
```
AttributedString
```
rather than
```
String
```
so rich formatting (bold, italic, lists, tables) is preserved losslessly.
The app's
```
App
```
struct initializer is executed when an intent runs, even if the UI never appears. Do all intent-relevant setup (
```
ModelContainer
```
creation,
```
AppDependencyManager.shared.add(...)
```
, log plumbing) inside
```
init()
```
, not inside view modifiers like
```
.task
```
or
```
.onAppear
```
.
```
LocalizedStringResource
```
is the standard string type everywhere in App Intents (titles, dialog, parameter prompts). It shares string catalogs with SwiftUI, so localization works out of the box.
Grammar agreement (
```
inflect: true
```
) works in English, French, German, Italian, Spanish, and Portuguese (both variants). For other locales it falls back to the unmodified form.

App Intents最低支持iOS 16+ / macOS 13+。
```
IndexedEntity
```
、
```
OpenIntent
```
、Focus Filters及控件小组件需要iOS 16+；
```
@AssistantEntity
```
/
```
@AssistantIntent
```
模式需要iOS 18.2+；锚定相对日期样式及多数助手模式需要iOS 18.4+。
绝对不要让SwiftData
```
@Model
```
类或其他引用类型数据模型遵循
```
AppEntity
```
。
```
AppEntity
```
要求
```
Sendable
```
；
```
@Model
```
类不具备Sendable特性。应创建单独的
```
struct
```
实体，映射需要暴露的字段。
绝对不要跨Actor边界传递
```
ModelContext
```
。
```
ModelContext
```
不具备Sendable特性。应传递
```
ModelContainer
```
（具备Sendable特性），并在需要的Actor内部创建本地上下文。
绝对不要仅通过编写类型将意图暴露给Siri/Spotlight，务必通过
```
AppShortcutsProvider
```
注册。未在此注册的类型不会出现在Shortcuts、Siri建议或操作按钮选择器中。
绝对不要编写未插入
```
\(.applicationName)
```
的Siri激活短语。App Intents宏会在编译时拒绝此类短语，因为不含应用名称的短语会与其他应用的命令冲突。
绝对不要从意图内部访问SwiftUI
```
@Query
```
。
```
@Query
```
仅在
```
View
```
内部生效。应通过
```
ModelContext
```
执行一次性
```
FetchDescriptor
```
，或通过集中式数据控制器路由。
绝对不要在
```
perform()
```
内部实例化服务、数据存储或认证管理器。应通过
```
@Dependency
```
注入，并在
```
App.init()
```
中通过
```
AppDependencyManager.shared.add(dependency:)
```
注册一次。
绝对不要使用
```
String(format:)
```
或手动拼接进行意图对话本地化。应使用
```
LocalizedStringResource
```
，并在
```
AttributedString
```
中使用Foundation的语法匹配标记（
```
^[\(count) item](inflect: true)
```
）处理复数形式。
对于“带我到该内容”的操作，优先使用
```
OpenIntent
```
；对于独立的一次性摘要，优先使用
```
AppIntent & ShowsSnippetView
```
；当代码片段包含
```
Button(intent:)
```
且按钮触发后需要重新渲染时，优先使用
```
AppIntent & ShowsSnippetIntent
```
+ 配对的
```
SnippetIntent
```
。
对于仅支持小组件按钮、代码片段按钮或其他意图的辅助意图，务必设置
```
static let isDiscoverable: Bool = false
```
；否则会污染用户的Shortcuts库。
当意图修改了小组件或控件小组件展示的数据时，需在
```
perform()
```
返回前调用
```
WidgetCenter.shared.reloadAllTimelines()
```
。
当
```
Button(intent:)
```
位于小组件视图中时，需通过App Group
```
UserDefaults(suiteName:)
```
或共享
```
ModelContainer
```
URL在意图（运行于应用进程）与小组件时间线提供器（运行于扩展进程）之间共享状态——绝对不要使用
```
UserDefaults.standard
```
或内存中的
```
@Dependency
```
状态。
当快捷短语键路径中显示的实体数据发生变化（创建、重命名、删除）时，调用
```
YourShortcutsProvider.updateAppShortcutParameters()
```
以失效缓存的候选列表。
当数据集较小且加载成本低时，优先使用
```
EnumerableEntityQuery
```
；当数据集较大或可搜索时，实现
```
EntityQuery
```
+
```
EntityStringQuery
```
；添加
```
EntityPropertyQuery
```
可免费获得系统生成的Find意图。
```
entities(for identifiers:)
```
是每个查询的必填项；缺少该方法会导致参数解析失败。
将用户可能筛选、排序或在参数摘要中引用的实体字段标记为
```
@Property
```
（存储型）或
```
@ComputedProperty
```
（派生型）。普通存储属性对App Intents框架不可见。
对于动态计算的返回数据（摘要、聚合结果），使用
```
TransientAppEntity
```
。不要试图通过伪造ID将其塞进
```
AppEntity
```
。
当实体已有通用链接URL时，让其遵循
```
URLRepresentableEntity
```
，并让打开意图遵循
```
URLRepresentableIntent
```
——系统会通过现有链接处理程序路由打开操作，无需
```
perform()
```
。
对于屏幕上显示且Siri应能识别的实体，将视图上的
```
.userActivity(_:element:)
```
与实体的
```
Transferable
```
遵循相结合。仅识别是不够的；Siri需要可导出的内容。
```
SnippetIntent.perform()
```
在每次用户交互中会被多次调用（初始显示、每次按钮点击后、外观变化时、
```
reload()
```
时）。保持其纯函数特性：读取状态、组装视图、返回结果。绝对不要在代码片段意图的
```
perform()
```
内部修改应用状态或启动耗时操作。
遵守硬性限制：每个应用最多10个
```
AppShortcut
```
，总计1000个触发短语（包括参数扩展）。每个快捷方式数组中的第一个短语是主要短语——会显示在Shortcuts主页磁贴及Siri的“我可以用X做什么？”回答中。
每个App Shortcut至少包含一个非参数化短语，以便在首次启动前即可被发现；参数化短语在应用运行一次并填充参数缓存前不会出现在Spotlight中。
对于有条件前置的新代码，优先使用
```
supportedModes
```
+
```
continueInForeground
```
（iOS 26+），而非
```
ForegroundContinuableIntent
```
/
```
needsToContinueInForegroundError
```
。新形式允许单个意图根据运行时状态声明在后台或前台运行。
代码片段视图的高度上限为340点；超过此高度，滚动会破坏概览覆盖模型。对于深度内容，链接到完整应用，并保持代码片段文本大于系统默认值，以保证阅读距离下的可读性。
对于可能接收Apple Intelligence的Use Model操作输入的文本参数，将类型声明为
```
AttributedString
```
而非
```
String
```
，以无损保留富格式（粗体、斜体、列表、表格）。
应用的
```
App
```
结构体初始化器会在意图运行时执行，即使UI从未显示。所有与意图相关的设置（
```
ModelContainer
```
创建、
```
AppDependencyManager.shared.add(...)
```
、日志管道）都要在
```
init()
```
内部完成，而非
```
.task
```
或
```
.onAppear
```
等视图修饰器内部。
```
LocalizedStringResource
```
是App Intents中所有场景的标准字符串类型（标题、对话、参数提示）。它与SwiftUI共享字符串目录，因此本地化可直接生效。
语法匹配（
```
inflect: true
```
）支持英语、法语、德语、意大利语、西班牙语和葡萄牙语（两种变体）。对于其他语言环境，会回退到未修改的形式。

Output Format

输出格式

If the user asks for a review, organize findings by file. For each issue:

State the file and relevant line(s).
Name the anti-pattern being replaced.
Show a brief before/after code fix.

Skip files with no issues. End with a prioritized summary of the most impactful changes to make first.

If the user asks you to write or fix intent code, make the changes directly instead of returning a findings report.

Example output:

若用户请求审查，按文件整理发现的问题。每个问题需包含：

说明文件及相关行号。
指出要替换的反模式。
展示简短的修复前后代码对比。

跳过无问题的文件。最后给出按优先级排序的最具影响性变更摘要。

若用户请求编写或修复意图代码，直接进行修改，而非返回问题报告。

示例输出：

RecentItemsIntent.swift

Line 18: SwiftData
@Model
cannot conform to
AppEntity
(not
Sendable
).

swift

// Before
extension Article: AppEntity { ... }

// After
struct ArticleEntity: AppEntity {
    var id: UUID
    var title: String
    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Article"
    static let defaultQuery = ArticleEntityQuery()
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(title)")
    }
}

Line 42: Siri phrase missing
\(.applicationName)
- will fail to build.

swift

// Before
AppShortcut(intent: OpenArticleIntent(), phrases: ["Open an article"], ...)

// After
AppShortcut(intent: OpenArticleIntent(), phrases: ["Open an article in \(.applicationName)"], ...)

第18行：SwiftData
@Model
无法遵循
AppEntity
（不具备
Sendable
特性）。

swift

// 修改前
extension Article: AppEntity { ... }

// 修改后
struct ArticleEntity: AppEntity {
    var id: UUID
    var title: String
    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Article"
    static let defaultQuery = ArticleEntityQuery()
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(title)")
    }
}

第42行：Siri短语缺少
\(.applicationName)
——编译会失败。

swift

// 修改前
AppShortcut(intent: OpenArticleIntent(), phrases: ["Open an article"], ...)

// 修改后
AppShortcut(intent: OpenArticleIntent(), phrases: ["Open an article in \(.applicationName)"], ...)

Summary

摘要

Sendability (high):
```
Article
```
as
```
AppEntity
```
will fail to compile on Swift 6; create a shadow struct.
Siri phrases (high):
```
\(.applicationName)
```
is required in every phrase.

End of example.

Sendability（高优先级）： 将
```
Article
```
作为
```
AppEntity
```
在Swift 6上会编译失败；需创建影子结构体。
Siri短语（高优先级）： 每个短语都必须包含
```
\(.applicationName)
```
。

示例结束。

References

参考文件

references/fundamentals.md

AppIntent

protocol,

perform()

, return types (

IntentResult

ProvidesDialog

ReturnsValue

ShowsSnippetView

OpensIntent

), intent dialog, grammar agreement.

```
references/parameters.md
```
-
```
@Parameter
```
, primitive vs entity parameters,
```
@AppEnum
```
, dialog options, parameter prompts.

references/entities.md

AppEntity

IndexedEntity

, shadow-struct pattern, display representations, entity queries (

EnumerableEntityQuery

EntityQuery

EntityStringQuery

UniqueIDEntityQuery

references/shortcuts-and-siri.md

AppShortcutsProvider

, phrases (

\(.applicationName)

rule),

shortcutTileColor

SiriTipView

ShortcutsLink

, parameter presentation.

```
references/open-and-snippet-intents.md
```
-
```
OpenIntent
```
, snippet views (
```
ShowsSnippetView
```
), navigation via data controller, when to use which.

references/dependencies.md

@Dependency

AppDependencyManager

, data-controller pattern,

ModelContainer

ModelContext

sendability, main-actor vs local-context tradeoff.

references/spotlight.md

IndexedEntity

CSSearchableIndex

attributeSet

, index-on-launch vs index-on-change, debounced reindexing.

references/assistant-schemas.md

@AssistantEntity

@AssistantIntent

, schema adoption, Xcode code snippets, caveats.

```
references/testing-intents.md
```
- unit testing intents, mocking
```
@Dependency
```
via
```
AppDependencyManager
```
, Swift Testing patterns, what you can't unit-test.
```
references/anti-patterns.md
```
- common mistakes LLMs make when generating App Intents code.

references/fundamentals.md

AppIntent

协议、

perform()

、返回类型（

IntentResult

、

ProvidesDialog

、

ReturnsValue

、

ShowsSnippetView

、

OpensIntent

）、意图对话、语法匹配。

```
references/parameters.md
```
-
```
@Parameter
```
、基础类型与实体参数、
```
@AppEnum
```
、对话选项、参数提示。

references/entities.md

AppEntity

、

IndexedEntity

、影子结构体模式、展示形式、实体查询（

EnumerableEntityQuery

、

EntityQuery

、

EntityStringQuery

、

UniqueIDEntityQuery

）。

references/shortcuts-and-siri.md

AppShortcutsProvider

、短语（

\(.applicationName)

规则）、

shortcutTileColor

、

SiriTipView

、

ShortcutsLink

、参数展示。

```
references/open-and-snippet-intents.md
```
-
```
OpenIntent
```
、代码片段视图（
```
ShowsSnippetView
```
）、通过数据控制器导航、适用场景。
```
references/dependencies.md
```
-
```
@Dependency
```
、
```
AppDependencyManager
```
、数据控制器模式、
```
ModelContainer
```
与
```
ModelContext
```
的Sendability特性、主Actor与本地上下文的权衡。
```
references/spotlight.md
```
-
```
IndexedEntity
```
、
```
CSSearchableIndex
```
、
```
attributeSet
```
、启动时索引与变更时索引、防抖重新索引。

references/assistant-schemas.md

@AssistantEntity

、

@AssistantIntent

、模式适配、Xcode代码片段、注意事项。

```
references/testing-intents.md
```
- 意图单元测试、通过
```
AppDependencyManager
```
模拟
```
@Dependency
```
、Swift Testing模式、不可单元测试的内容。
```
references/anti-patterns.md
```
- 大语言模型生成App Intents代码时常见的错误。