博客 • AI / JSON Schema

iPhone 18 AI 功能背后的数据结构：Apple Intelligence、App Actions 与 JSON Schema 如何连接？

iPhone 18 上的 AI 动作能接到 App，靠的不是一段产品介绍，而是一份和 Intent 参数对齐的 JSON Schema。系统模型给出候选字段，@Parameter 声明 App 能接受什么。Schema 在两者中间：对不上的对象进不了动作。

产品叙事见 iPhone 18 为什么不只是硬件。一条指令怎么从短语走到 API，见 App Actions 的数据路径。本篇只写字段：类型怎么映射、哪些值必须拒绝。

• Intent 参数是 App 侧的类型合同
• JSON Schema 是你用来卡住模型输出的同一份字段表
• AppEnum 对 enum，AppEntity 只收 id，不收展示名
• additionalProperties 为 false，多出来的键直接失败

三边怎么接上

App 能接受的值写在 Intent 参数上。说明见 为 App Intent 添加参数。模型可以提议一个 JSON 对象，但不能改这张字段表。

1. 1
   系统侧给出候选

   设备上的模型或快捷指令填出一个对象：动作名、数量、履约方式、商品 id。这只是候选，不是已经执行的调用。

2. 2
   App 侧声明类型

   每个参数是字符串、整数、固定枚举，还是必须解析的实体。可选参数不放进 required。

3. 3
   Schema 决定放不放行

   候选对象先过你的 Schema。通过才写入 Intent。失败就停在校验，不调用动作，也不打 API。

类型怎么对上

字段表以外的键用 additionalProperties: false 拒绝。模型多写一个 note 或 user，也不能混进动作。

一份能贴进校验器的 Schema

下面这份对齐一个下单动作：意图名固定，参数里有商品 id、数量和履约方式。它是你的契约，不是 Apple 的线上格式。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "required": ["intent", "parameters"],
  "properties": {
    "intent": { "const": "StartOrder" },
    "parameters": {
      "type": "object",
      "additionalProperties": false,
      "required": ["item_id", "quantity", "fulfillment"],
      "properties": {
        "item_id": { "type": "string", "minLength": 1 },
        "quantity": { "type": "integer", "minimum": 1 },
        "fulfillment": { "enum": ["pickup", "delivery"] }
      }
    }
  }
}

{
  "intent": "StartOrder",
  "parameters": {
    "item_id": "sku_42",
    "quantity": 1,
    "fulfillment": "pickup"
  }
}

把履约方式写成自然语言，或把 item_id 留空，这条就不能过。通过之后才交给上一篇说的执行路径。

四种应该拒绝的形状

为什么模型输出先要 Schema，见 AI 为什么需要 JSON Schema。本篇把那张表接到 App 动作的参数上。

和另外两篇怎么分工

在 JSONNote 里对上这张表

1. 1
   贴上 Schema

   把上面的 Schema 贴进 JSON Schema。确认 intent 是 const，fulfillment 是 enum。

2. 2
   用一条候选去撞

   用 JSON 校验 贴一条候选。空 id、额外字段、错误枚举都应该失败。

3. 3
   改字段后再比

   用 JSON Diff 看 required 里有没有少掉 item_id。少一个必填，比改一句文案更危险。

常见问题

JSON Schema 是 Apple 的请求格式吗？

不是。Apple 用 App Intent 的参数类型描述动作。Schema 是你放在模型输出和 perform() 之间的校验。对不上就不要调用。

为什么实体字段不能是商品名？

名称会变、会重复。AppEntity 的主键是稳定 id。Schema 用非空字符串卡住 id，名称只给人看。

可选参数要不要写进 Schema？

要写进 properties，但不要放进 required。这样缺了仍合法，出现了则必须符合类型。

校验通过就可以执行动作吗？

还不行。Schema 只证明形状。实体 id 仍要查询解析成功。形状对、对象不存在，一样不能下单。

和「AI 为什么需要 JSON Schema」是同一篇吗？

不是。那篇讲模型输出为什么要有形状。本篇讲这个形状怎样对齐 App 动作的参数，多一个键或错一个枚举就要拒绝。

总结

Apple Intelligence 和 App 动作之间，靠的是同一组字段：动作名、类型、枚举和实体 id。JSON Schema 把这组字段写成可以失败的检查。

直接结论：参数类型先对齐 Schema；多出来的键拒绝；实体只收 id；校验失败就不进入动作。

返回博客