| name | agf-wiring-apple-llm |
| description | Use when wiring LLM features into the Apple client (macOS / iOS) — streaming chat via the FastAPI multi-LLM gateway, or on-device inference (Apple Foundation Models / Core ML). Provides the route decision (gateway vs on-device), streaming transport pattern, env/config contract, offline & cost guardrails, and minimum verifications before declaring the integration done. |
Wiring LLM into the Apple client (gateway streaming / on-device)
Use this skill when:
- 给
apple/ app 加对话 / 生成 / 总结类 LLM 功能
- 把某条 LLM 路径从后端网关切到 on-device（或反向）
- 调试 Apple 客户端的流式输出 / token 计量 / 降级行为
Decision: gateway or on-device?
默认走后端网关：FastAPI 后端已按 skill agf-wiring-multi-llm-sdk 封装 DeepSeek / Doubao / Qwen / MiniMax（provider 切换、fallback、cost telemetry 全在服务端）。客户端只对一个自有 API 说话，不直连任何 LLM 厂商。
| 场景 | 路由 | 理由 |
|---|
| 对话 / 生成 / RAG（默认） | 后端网关 | key 不进客户端、provider 可热切、成本计量集中、合规审计单点 |
| 离线可用 / 隐私敏感（文本不出设备）/ 低延迟小任务（分类、摘要短文本） | on-device（Apple Foundation Models framework，iOS 26+ / macOS 26+；或 Core ML 自带模型） | 零 token 成本、断网可用；但模型能力 / 上下文受限 |
| 多模态生成（文生图 / 视频） | 后端网关（ml-engineer 维护的推理服务） | 客户端不嵌大模型 |
铁律：LLM 厂商 API key 永不进客户端。客户端二进制可被逆向，任何打进 app 的 key 等于公开。只有自有后端的会话凭证可进客户端。
on-device 路径若成为产品主路径（非补充），属技术选型变更 → tech-lead 新开 ADR。
Gateway streaming pattern（默认路径）
后端以 SSE（text/event-stream）暴露流式 chat 端点。注意：OpenAPI 对 SSE 描述能力有限——流式端点允许在生成 client 之外手写一个最小 SSE transport（这是 ADR-008「禁手写」的唯一豁免点，豁免范围仅限流式通道本身；请求/响应模型仍用生成类型）：
let (bytes, response) = try await URLSession.shared.bytes(for: request)
for try await line in bytes.lines {
guard line.hasPrefix("data: ") else { continue }
let payload = line.dropFirst(6)
if payload == "[DONE]" { break }
}
- 首 token 延迟（TTFT）必须上报（客户端打点 → 后端 observability.md 字段）
- 取消语义：视图消失 / 用户停止 →
Task.cancel() 必须真正断开 SSE 连接（防后台烧 token）
- UI 增量渲染走
@MainActor 的 AsyncSequence 消费，禁在主线程做 JSON 解析
Config contract
客户端无 .env；配置走 build configuration / Info.plist 注入：
| 项 | 载体 | 说明 |
|---|
| 网关 base URL | xcconfig per-configuration（Debug → localhost / UAT 栈，Release → 生产） | 禁硬编码在 Swift 源码 |
| 会话凭证 | Keychain | 禁 UserDefaults / 文件 |
| on-device 模型开关 | feature flag（后端下发或本地配置） | 降级链路可远程关 |
Fallback & guardrails
- 网关不可达 → 有 on-device 路径的功能降级 on-device 并明示用户"离线模式"；无降级路径的功能给可重试错误态（禁白屏 / 禁假装成功）
- on-device 模型不可用（机型 / OS 不支持 Foundation Models）→
@available + 能力探测 gating，回落网关或隐藏入口
- 成本护栏：客户端不直接产生 token 成本（网关集中计量），但必须防"循环重试风暴"——重试上限 + 指数退避
- 合规（
apple-native.md §7）：AI 生成内容须有举报 / 过滤入口；用户输入发往后端在隐私政策声明；隐私清单如实标注
Verifications before "done"
Anti-patterns
- ❌ 厂商 API key 编进客户端（含"先临时测一下"）—— 逆向即泄漏
- ❌ 客户端直连 DeepSeek / Doubao / Qwen / MiniMax —— provider 切换 / 计量 / 合规全失控
- ❌ 借 SSE 豁免扩大手写面 —— 豁免仅限流式通道，请求/响应类型仍走生成代码
- ❌ 流式 UI 全量 setState 重渲染长文本 —— 增量 append，注意 attributed string 成本
- ❌ 取消只停 UI 不断连接 —— 后台连接继续烧 token
- ❌ on-device 与网关行为差异不告知用户 —— 离线模式必须明示
References
- 后端 provider 封装 / env 契约 / fallback：skill
agf-wiring-multi-llm-sdk（服务端 SSOT，本 skill 不重复）
- 契约纪律与豁免边界：ADR-008
- Apple Foundation Models framework：developer.apple.com（接入前 WebFetch 当前文档，API 迭代快）
