agf-wiring-apple-llm

# 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「禁手写」的**唯一豁免点**，豁免范围仅限流式通道本身；请求/响应模型仍用生成类型）： ```swift // AppCore/Sources/AppCore/LLM/StreamingClient.swift —— 唯一允许的手写网络层（SSE 豁免） 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 } // decode 用生成的 Components.Schemas.ChatChunk 类型，不手写 DTO } ``` - 首 token 延迟（TTFT）必须上报（客户端打点 → 后端 o...