Writing Tools API：应用如何接入 Apple Intelligence 的写作层

Apple Intelligence 的写作层（品牌名为 Writing Tools）已在所有启用了 Apple Intelligence 的 iOS 18+ 设备中发布。用户选中文本，点击 Writing Tools 菜单，即可获得校对、改写（友好、专业、简洁）、摘要、列表与表格生成，以及（自 iOS 18.2 起）生成式撰写功能¹。该能力位于系统层而非任何单一应用中，用户期望它在每一个文本输入框中都能正常工作。

使用 UITextView、NSTextView 或 WKWebView 的应用无需编写代码即可获得集成，前提是文本视图运行在 TextKit 2 上²。具有自定义文本引擎的应用则需要 UIWritingToolsCoordinator API，将其文本存储与渲染接入 Writing Tools 体验。本文将对照 Apple 官方文档梳理该 API 的接口面，列出三个接入层级，并说明何时应当退出（因为并非每一个文本输入都应接受生成式改写）。

TL;DR

• 运行在 TextKit 2 上的标准文本视图（UITextView、NSTextView、WKWebView）可免费获得 Writing Tools，享有完整的内联改写带动画体验²。
• 自定义文本视图通过采用 UITextInteraction 即可获得呼出菜单/上下文菜单的集成，无需更多代码；完整的内联集成则需要 UIWritingToolsCoordinator API³。
• UIWritingToolsBehavior 是一个单一的枚举属性，用于控制体验层级：.complete、.limited 或 .none⁴。.default 值是一个请求，由系统在运行时解析为这三者之一；它并不是第四个层级。对于敏感文本（密码、源代码编辑器、用户不希望被改写的聊天框），应设置为 .none。
• allowedWritingToolsResultOptions 让应用声明其可接受的输出形态（纯文本、富文本、列表、表格，或 iOS 26 中新增的 .presentationIntent），从而避免 Writing Tools 返回应用无法渲染的内容⁵。
• 与智能体工作流的关联：Writing Tools 与 App Intents、Foundation Models 一样属于 Apple Intelligence 的接入面，但其作用层级是文本输入层而非动作层。

Writing Tools 究竟做了什么

iOS 18+ 的 Writing Tools 菜单对选中的文本提供一组操作。根据 Apple 开发者文档及 WWDC 2024 的介绍，当前公开的操作集如下⁶：

校对（Proofread）。 修复语法、拼写、标点和用词。返回一份差异，用户可以接受、拒绝或逐项查看。

改写（Rewrite）。 三种预设语气（友好、专业、简洁）以及一个”描述你想要的修改”的自定义提示。模型按所选语气重写选中的文本。

摘要（Summarize）。 长文变短文。变体包括”摘要”、”要点”、”列表”、”表格”。由用户决定输出形态。

撰写（Compose）。 根据提示进行生成式写作（iOS 18.2+）。用户描述想要的内容，模型生成新文本而非改写已有文本。

驱动 Writing Tools 的模型，在受支持的硬件上是 Apple 端侧的基础模型，对于较大的请求则有私有云计算作为后备¹。用户的文本永远不会发送给任何第三方。隐私保障是其价值主张的重要组成部分。

三个接入层级

应用根据所需的 Writing Tools 集成深度，分属以下三个层级之一。

层级 1：标准文本视图（零代码）

使用 UITextView、NSTextView 或 WKWebView 作为文本输入的应用，无需编写任何代码即可获得 Writing Tools，前提是文本视图使用 TextKit 2²。系统负责处理菜单、内联改写界面、动画以及校对的内联高亮。应用的职责仅仅是使用标准文本视图。

let textView = UITextView()
textView.text = "Original content."
textView.isEditable = true
// Writing Tools just works.

TextKit 2 这一前提之所以重要，是因为 TextKit 1 采用了不同的布局架构，不支持内联改写动画。面向 iOS 18+ 的新应用应默认使用 TextKit 2；遗留应用可能需要进行迁移。在 iOS 16+ 中，通过 Interface Builder 或现代初始化器创建的 UITextView 默认使用 TextKit 2。

层级 2：采用 UITextInteraction 的自定义文本视图（仅呼出菜单）

具有自定义文本视图的应用可以采用 UITextInteraction，从而在呼出栏和上下文菜单中获得 Writing Tools，无需更多代码⁷。用户可以唤起 Writing Tools，看到面板式的校对/改写/摘要界面，并接受或拒绝结果。结果通过标准的粘贴/替换流程交付给应用。

这种集成是部分性的：应用不会获得内联动画或校对内联高亮。这些需要完整的协调器才能实现。对大多数具有自定义文本视图的应用而言，采用 UITextInteraction 已经足够。

层级 3：UIWritingToolsCoordinator（完整内联体验）

希望在自定义文本存储上获得完整 Writing Tools 体验的应用，应采用 UIWritingToolsCoordinator（macOS 上为 NSWritingToolsCoordinator）³。协调器管理 Writing Tools 与应用之间的双向对话：

• 应用向协调器提供文本上下文（一个 NSAttributedString，表示当前选中内容及可选的周边段落）。
• 协调器管理面板 UI 和内联动画。
• 协调器通过委托回调，在应用的文本存储中插入、替换或动画化文本变更。

UIWritingToolsCoordinator.Delegate 上的关键委托方法（已对照 iOS 26 SDK 头文件验证³）：

• writingToolsCoordinator(_:requestsContextsForScope:completion:)。接入方法。Writing Tools 向应用请求给定范围内的相关文本上下文（每个上下文是一个 NSAttributedString 加一个选中范围）。应用从其文本存储构建上下文并返回。
• writingToolsCoordinator(_:replaceRange:inContext:proposedText:reason:animationParameters:completion:)。文本变更的主力方法。Writing Tools 为某个上下文中的某段范围提议新文本；应用将变更应用到自身存储中并确认。
• writingToolsCoordinator(_:finishTextAnimation:forRange:inContext:completion:)。当某段范围的文本动画（原文本与改写文本之间的形变）结束时调用。这并非会话结束信号。
• writingToolsCoordinator(_:willChangeToState:completion:)。会话生命周期信号。协调器会在各状态（idle、interactive、noninteractive 等）之间切换，并在每次切换前通知委托。这正是应用响应”会话开始”与”会话结束”的位置。

协调器 API 是为序列化文本引擎（TextKit 风格）、文档形态的编辑器以及希望部分集成的代码编辑器而设计的。Apple 在 WWDC 2025 的 “Dive deeper into Writing Tools” 会议⁸ 演示了多段落、多样式的应用案例。需要注意的是，UIWritingToolsCoordinator 首次作为公开 API 发布于 iOS 18.2；iOS 26 是对其加以深化，而非全新引入。

行为属性：UIWritingToolsBehavior

最重要的接入/退出控制是 UITextView、UITextField 以及任何遵循 UITextInputTraits 的视图上的 writingToolsBehavior 属性⁴：

textView.writingToolsBehavior = .complete   // full inline experience
textView.writingToolsBehavior = .limited    // panel-only (no inline rewrite)
textView.writingToolsBehavior = .none       // disabled entirely
textView.writingToolsBehavior = .default    // request system default

其中三个值是真实的体验层级；.default 是一个请求，由系统根据文本输入的特征解析为另外三者之一：

• .complete。 完整的 Writing Tools 体验，包括内联改写动画、内联校对高亮以及面板。最适合长文本编辑器（邮件撰写、备忘录、文档编辑器）。
• .limited。 仅面板体验。用户在菜单中能看到 Writing Tools，但改写发生在面板中而非内联。最适合内联动画显得过重的较短文本字段。
• .none。 该文本输入禁用 Writing Tools。用于敏感内容。
• .default。 一个请求，而非层级。头文件文档说明，解析后的值始终是 .none、.limited 或 .complete 之一；只读的 behavior 属性永远不会返回 .default。除非有特定理由覆盖，大多数应用应将该属性保持为 .default。

何时应当退出

以下三类文本输入应当设为 .none：

密码与敏感凭证。 密码框绝不应提供”用友好的语气改写”这样的选项。用户输入的是必须不被转换的字面文本。Apple 的 UITextField 在 isSecureTextEntry = true 时已默认禁用 Writing Tools；显式设置 .none 是双保险。

源代码编辑器。 一个 SwiftUI 代码编辑器或面向技术内容的 Markdown 编辑器，并不会因为被要求用”专业”语气改写选中代码而变得更好。Writing Tools 的改写路径是为自然语言调优的，而非为语法结构调优的。对于内容并非自然语言的文本视图，请设置 .none。

改写会改变意图的聊天字段。 在消息应用或评论框中，用户的措辞（出于语气、嗓音、责任考量）极为关键，可能希望省略改写而保留校对。Writing Tools 当前的 API 不允许逐操作进行门控；.none 值会禁用整体体验。务实的做法是对那些偶尔适合改写但不应作为内联默认的字段使用 .limited（仅面板，用户必须主动唤起）。

allowedWritingToolsResultOptions 声明应用可渲染的内容

一个更细微的控制位于 UITextInputTraits.allowedWritingToolsResultOptions（也通过 UITextView.allowedWritingToolsResultOptions 暴露）⁵。该属性是一个 UIWritingToolsResultOptions 选项集，用于声明应用的文本视图可渲染的内容形态：

• .plainText。文本视图支持纯文本（不含格式化属性）。
• .richText。支持格式化文本（粗体、斜体等）。
• .list。支持列表渲染（项目符号、编号）。
• .table。支持表格渲染。
• .presentationIntent（iOS 26+）。支持丰富的语义意图标记（标题、块引用、代码块），通过 Foundation 框架的 PresentationIntent 类型实现，比纯富文本更具表达力。

设置后，Writing Tools 会将其输出限制在应用可接受的形态范围内。一个仅声明 .plainText 的纯文本编辑器，不会获得”将其转为表格”的建议。一个声明了 .richText 与 .list 但不声明 .table 的富文本编辑器，会获得列表输出，但不会获得表格输出。

默认值是 .default，由系统根据文本视图的特征自行决定。当自动检测产生错误形态时（例如某文本视图能够渲染富文本，但应用的数据模型仅存储纯文本），应显式设置该属性。

输出去向

对于层级 1 的应用（标准文本视图），输出通过标准文本视图机制内联替换选中内容。无需任何应用代码参与。

对于层级 2 的应用（带 UITextInteraction 的自定义视图），输出通过标准粘贴流程到达。处理变更的是文本视图的 UITextInput 协议实现。已正确实现 UITextInput 的应用，在添加 UITextInteraction 后即可”免费”获得集成。

对于层级 3 的应用（完整协调器），输出通过委托的 replaceRange: 方法到达。应用将变更应用到自身的文本存储中，在完成回调里返回新的文本边界，协调器则负责处理视觉过渡。文本存储的真实来源始终是应用本身。

WWDC 2025 深度解析新增了什么

WWDC 2025 的 “Dive deeper into Writing Tools” 会议⁸ 在三个值得点名的方向上扩展了 iOS 18 的 API：

多段落上下文。 应用现在可以向协调器提供更多周边上下文，使 Writing Tools 能够操作那些依赖周边段落的选中内容（例如某句话的含义依赖于其上一段）。

自定义改写提示。 iOS 18.2 测试版中的”描述你想要的修改”路径已完全公开，并提供了委托钩子，让需要在将提示传给模型之前进行检查或转换的应用可以介入。

对混合内容更好的处理。 跨多种样式或包含嵌入图片的文本选区，现在可以经由协调器流转，嵌入内容会作为不透明范围被保留下来。协调器不会尝试改写内联图片；它会保留图片并改写其周围的文本。

这些增量是对 iOS 18 模型的扩展，而非替代。已采用 iOS 18 Writing Tools API 的应用可继续工作；iOS 26 为有需要的应用解锁了更深的集成。

与智能体工作流的关联

Writing Tools 是第三方应用可以接入的三个 Apple Intelligence 接入面之一：

Writing Tools。 文本输入层。用户选中文本，请求系统进行转换，结果在内联返回。应用通过暴露规范的文本视图并（可选地）实现协调器来参与。用户唤起，应用接收结果。

App Intents。 动作层。用户（或智能体）请求 Apple Intelligence 执行某个动作，系统将请求路由到应用中已注册的意图。应用通过声明 AppIntent 类型、参数模式与结果类型来参与。详见 App Intents Are Apple’s New API to Your App。

Foundation Models。 运行时 LLM 层。应用通过 Foundation Models 框架直接调用端侧 LLM，进行应用内生成。详见 Foundation Models on-device LLM。

三个接入面可以组合使用。一款笔记应用可能会使用 Writing Tools（处理用户基于选区的改写）、App Intents（处理”总结昨天的笔记”）以及 Foundation Models（实现自动打标签等应用内生成功能）。每一层都是一种独立的集成，对应一种独立的用户心智模型。

App Intents vs MCP Tools 一文 讨论了何时应通过 App Intents 暴露动作（Apple Intelligence），何时应通过 MCP 服务器暴露动作（通用智能体）。Writing Tools 不在这一问题的讨论范围内；它属于系统级接入面，在本系列覆盖的范围中没有第三方智能体的对应物。

该模式对 iOS 26+ 应用意味着什么

三个要点。

1. 默认采用标准文本视图与 TextKit 2。 大多数应用并不需要协调器 API。如果应用的文本输入是 UITextView 或 WKWebView，Writing Tools 无需代码即可工作；真正需要的工作是 TextKit 2 的迁移（如果应用仍在使用 TextKit 1）。

2. 对敏感输入有意识地设置 writingToolsBehavior = .none。 密码、代码编辑器、要求精确文本的字段。默认值会尝试做出正确决策，但显式设置是团队可以言之有理的产品决策。

3. 仅当应用的文本引擎确实是定制的，才考虑 UIWritingToolsCoordinator。 Markdown 编辑器、代码编辑器、有自定义渲染的文档应用、终端式文本视图。协调器是一项实打实的工程投入；对大多数自定义视图而言，层级 2（UITextInteraction）已经足够。

完整的 Apple 生态系列：强类型 App Intents；MCP 服务器；路由问题；Foundation Models；运行时与工具链 LLM 的区分；三个接入面；单一真实来源模式；两个 MCP 服务器；面向 Apple 开发的钩子；Live Activities；watchOS 运行时；SwiftUI 内部；RealityKit 的空间心智模型；SwiftData 模式纪律；Liquid Glass 模式；多平台发布；平台矩阵；Vision 框架；Symbol Effects；Core ML 推理；我拒绝写的话题。系列入口位于 Apple 生态系列。如需更广义的”iOS 与 AI 智能体”背景，请参阅 iOS 智能体开发指南。

FAQ

我需要 Apple Intelligence 才能在我的应用中测试 Writing Tools 吗？

要测试完整的用户体验，是的。面向用户的 Writing Tools 菜单只会出现在已启用 Apple Intelligence 的设备上（iPhone 15 Pro 或更新机型、M1 Mac 或更新机型，且系统为 iOS 18+ / macOS 15+）。出于开发目的，您可以在任何 iOS 18+ 模拟器或设备上测试 API 集成，方法是检查您的文本视图是否暴露 isWritingToolsActive，以及委托方法是否正确接入；只是在没有 Apple Intelligence 的情况下，系统菜单不会出现。

如果我在 iOS 18+ 应用中对 Writing Tools 不做任何处理会怎样？

对于标准文本视图（UITextView、WKWebView），Writing Tools 会自动出现。对于未采用 UITextInteraction 的自定义文本视图，Writing Tools 不会出现在菜单中，用户也无法在您的应用文本上唤起它。对于不适合出现 Writing Tools 的视图（密码字段、代码编辑器），不做任何处理是合理的默认；但对于一般的文本输入，不做处理意味着错失一项用户期待的系统功能。

.complete 与 .limited 有什么区别？

.complete 以内联方式运行 Writing Tools 改写，并伴随将原文本形变为改写文本的动画，外加内联校对高亮。.limited 通过面板 UI 运行 Writing Tools；用户在独立界面中看到改写结果，并决定是否应用。对长文本编辑器（内联动画能强化编辑流程）使用 .complete；对较短的文本字段（面板更合适）使用 .limited。

我可以自定义 Writing Tools 的提示或模型行为吗？

模型与提示由系统控制。应用无法将自定义改写行为注入 Writing Tools 菜单。对于应用专属的生成式写作功能，请直接使用 Foundation Models 框架（详见 Foundation Models on-device LLM），并通过自有 UI 暴露该功能。

Writing Tools 如何处理混合选区（文本+图片）？

根据 WWDC 2025 的 “Dive deeper into Writing Tools”⁸，包含嵌入内容（图片、附件）的混合选区会经由协调器流转，嵌入内容会作为不透明范围被保留下来。Writing Tools 会改写周围的文本，但不会尝试转换嵌入内容。对于使用协调器的应用，委托收到的提议文本载荷中，嵌入内容所对应的范围会被标记为未变更。

参考文献