| 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「禁手写」的唯一豁免点，豁免范围仅限流式通道本身；请求/响应模型仍用生成类型）：
