Appearance
foundation-models-on-device Skill 是 Claude Code 针对 Apple FoundationModels 框架的端侧 LLM 集成方案，支持 iOS 26+ 设备上的文本生成、@Generable 结构化输出、工具调用和快照流式响应。它解决了隐私、离线和结构化 AI 生成等痛点，让开发者无需云依赖即可构建强大的 AI 辅助功能。本文将详细介绍其激活条件、使用流程、典型场景和与其他 Agent/Skill 的协作模式，助你在实际项目中高效落地端侧 LLM 能力。
Everything Claude Code Foundation Models On Device：iOS 26 Apple FoundationModels 端侧 LLM 与 @Generable 导引生成
随着 iOS 26 引入 FoundationModels 框架，开发者终于可以在本地设备上调用 Apple 官方大语言模型，实现隐私保护、离线可用的 AI 生成与推理。Claude Code 的 foundation-models-on-device Skill，正是针对这一新生态设计的专业插件，聚焦于端侧 LLM 的实际落地。它不仅支持常规的文本生成，还通过 @Generable 实现结构化数据输出、定制工具调用（Tool Calling）、以及快照流式响应，极大拓展了 AI 编程助手的能力边界。
本指南将带你系统掌握 foundation-models-on-device Skill 的激活条件、典型使用流程、常见输出、最佳实践与常见误区，帮助你在实际项目中安全、稳定、高效地用好 Apple FoundationModels。
1. 这个 Skill 解决什么问题？
在没有 foundation-models-on-device Skill 的情况下，开发者往往只能依赖云端 LLM 服务（如 OpenAI、Claude API 等）实现文本生成、结构化数据提取或 AI 辅助功能。这带来三大痛点：
- 隐私风险：用户数据需上传云端，难以满足本地隐私或合规要求；
- 离线不可用：无网络时 AI 功能失效，影响用户体验；
- 结构化输出困难：云端 LLM 返回纯文本，解析成本高，易出错。
而 foundation-models-on-device Skill 通过对接 Apple FoundationModels 框架，直接在 iOS 26+ 设备本地运行 LLM，具备如下优势：
- 本地推理，数据不出端，极致隐私保护；
- 离线可用，AI 功能随时响应；
- @Generable 导引生成，原生结构化输出，类型安全；
- 自定义 Tool Calling，让模型直接调用本地业务逻辑；
- 快照流式输出，实时 UI 响应，提升交互体验。
2. 何时激活 foundation-models-on-device Skill？
建议在以下场景启用本 Skill：
- 需要在 iOS 26+ 设备上实现 AI 辅助功能（如文本生成、摘要、对话等）；
- 对隐私有极高要求，不能将数据传到云端；
- 希望提取结构化数据（如表单、实体、命令参数）；
- 需要模型直接调用本地工具或业务逻辑（如搜索、计算、查找等）；
- 希望实现流式生成，实时更新 UI；
- 需要确保 AI 功能在无网络环境下也可用。
3. 实际项目中如何用好 foundation-models-on-device Skill？
以下是标准的 step-by-step 操作流程，涵盖可用性检测、基本对话、结构化生成、工具调用与流式快照五大核心模式。
步骤 1：模型可用性检测（强烈建议）
在创建 LLM 会话前，务必检测模型是否可用，避免因设备不支持、未开启 Apple Intelligence 或模型未就绪导致崩溃。
swift
struct GenerativeView: View {
private var model = SystemLanguageModel.default
var body: some View {
switch model.availability {
case .available:
ContentView()
case .unavailable(.deviceNotEligible):
Text("设备不支持 Apple Intelligence")
case .unavailable(.appleIntelligenceNotEnabled):
Text("请在设置中开启 Apple Intelligence")
case .unavailable(.modelNotReady):
Text("模型正在下载或尚未就绪")
case .unavailable(let other):
Text("模型不可用: \(other)")
}
}
}最佳实践：所有入口都应先检查
model.availability，并对不可用情况给出明确提示。
步骤 2：创建 LLM 会话（单轮/多轮）
- 单轮模式：每次请求新建会话，适合独立任务。
- 多轮模式：复用同一个 session，自动维护上下文，适合对话或连续交互。
swift
// 单轮
let session = LanguageModelSession()
let response = try await session.respond(to: "巴黎最佳旅游月份？")
print(response.content)
// 多轮
let session = LanguageModelSession(instructions: """
你是烹饪助手，根据食材推荐简洁实用的菜谱。
""")
let first = try await session.respond(to: "我有鸡肉和米饭")
let followUp = try await session.respond(to: "有素食选项吗？")说明：
instructions用于定义模型角色、行为、风格和安全边界，优先级高于 prompt。
步骤 3：@Generable 结构化导引生成
通过 @Generable，模型可直接生成强类型结构体，免去字符串解析烦恼。
1. 定义 Generable 类型
swift
@Generable(description: "猫的基础档案信息")
struct CatProfile {
var name: String
@Guide(description: "猫的年龄", .range(0...20))
var age: Int
@Guide(description: "一句话描述猫的性格")
var profile: String
}2. 请求结构化输出
swift
let response = try await session.respond(
to: "生成一只可爱的救助猫",
generating: CatProfile.self
)
print("名字: \(response.content.name)")
print("年龄: \(response.content.age)")
print("简介: \(response.content.profile)")优势：比解析原始字符串更安全、可维护，支持数值范围、数组长度等约束。
步骤 4：自定义 Tool Calling（模型调用本地工具）
让 LLM 直接调用 Swift 代码，实现如搜索、计算等业务逻辑。
1. 定义 Tool
swift
struct RecipeSearchTool: Tool {
let name = "recipe_search"
let description = "根据关键词搜索菜谱并返回结果列表"
@Generable
struct Arguments {
var searchTerm: String
var numberOfResults: Int
}
func call(arguments: Arguments) async throws -> ToolOutput {
let recipes = await searchRecipes(
term: arguments.searchTerm,
limit: arguments.numberOfResults
)
return .string(recipes.map { "- \($0.name): \($0.description)" }.joined(separator: "\n"))
}
}2. 创建带工具的会话
swift
let session = LanguageModelSession(tools: [RecipeSearchTool()])
let response = try await session.respond(to: "帮我找些意大利面菜谱")3. 错误处理
swift
do {
let answer = try await session.respond(to: "找一个番茄汤菜谱")
} catch let error as LanguageModelSession.ToolCallError {
print(error.tool.name)
// 可根据具体业务错误类型做定制处理
}应用场景：如本地搜索、数据库查询、设备控制等，极大扩展 LLM 能力边界。
步骤 5：快照流式响应（Snapshot Streaming）
适合实时 UI 场景，逐步展示结构化生成内容。
swift
@Generable
struct TripIdeas {
@Guide(description: "旅行建议")
var ideas: [String]
}
let stream = session.streamResponse(
to: "推荐一些有趣的旅行目的地",
generating: TripIdeas.self
)
for try await partial in stream {
// partial: TripIdeas.PartiallyGenerated，所有属性可选
print(partial)
}SwiftUI 集成示例
swift
@State private var partialResult: TripIdeas.PartiallyGenerated?
@State private var errorMessage: String?
var body: some View {
List {
ForEach(partialResult?.ideas ?? [], id: \.self) { idea in
Text(idea)
}
}
.overlay {
if let errorMessage { Text(errorMessage).foregroundStyle(.red) }
}
.task {
do {
let stream = session.streamResponse(to: prompt, generating: TripIdeas.self)
for try await partial in stream {
partialResult = partial
}
} catch {
errorMessage = error.localizedDescription
}
}
}特点：每次快照都是当前完整结构体的部分填充状态，适合进度条、实时预览等场景。
4. 输出示例
- 文本生成：
巴黎最佳旅游月份？→四月和五月气候宜人，游客较少，是游览巴黎的好时节。 - 结构化输出：生成猫档案 →
{ name: "Mimi", age: 2, profile: "活泼好动，喜欢和人亲近" } - 工具调用：
帮我找素食菜谱→- 西红柿意面: 新鲜番茄和意面搭配的经典素食菜肴... - 流式快照：
推荐旅行地→ UI 列表逐步出现“京都”、“冰岛”、“新西兰”等建议
5. 常见配套 Agent 与 Skill 协作
- 与 Codebase Onboarding Skill 协作：快速生成本地项目结构化说明，提升新成员上手效率（详见 Codebase Onboarding Skill）。
- 与 Verification Loop Skill 配合：本地 LLM 生成的内容可直接进入端到端验证循环，提升安全性和准确率（见 Verification Loop Skill）。
- 与 AI-First Engineering Skill 协同：实现端侧 AI 生成、结构化输出与自动化工程流水线的无缝衔接（参考 AI-First Engineering Skill）。
6. 最佳实践与常见误区
最佳实践：
- 必须检测
model.availability，并对所有不可用状态做兜底处理 - 用
instructions明确模型角色与行为，避免 prompt 歧义 - 单 session 仅允许一个请求，需检查
isResponding - 结构化输出优先用
@Generable，避免手动解析字符串 - 输入总 token 不可超过 4096（含 instructions + prompt + output），大输入需分块处理
- 用
GenerationOptions(temperature:)调整创意度 - 性能监控建议用 Xcode Instruments
反模式（Anti-Patterns）：
- 忽略可用性检查，导致崩溃或无响应
- 输入超出 token 限制
- 并发请求同一 session
- 解析字符串而非用结构体
- 复杂多步任务强行塞进单 prompt，应拆解为多步
FAQ
Q: foundation-models-on-device Skill 支持哪些 iOS 版本？ A: 仅支持 iOS 26 及以上，且设备需支持 Apple Intelligence。
Q: 如何保证输出内容的结构化和类型安全？ A: 推荐用 @Generable 定义目标结构体，模型会直接生成类型安全的结构化数据。
Q: 这个 Skill 能和云端 LLM 混用吗？ A: 可以，建议在隐私敏感或离线场景优先用本地模型，其他场景可灵活切换云端和端侧 LLM。