City SDK
面向多个 AI 产品的 Federation 与 SDK 能力。
Downcity 的 City SDK 用来创建、部署和调用 City。一个 Federation 可以同时服务网页、扩展、App、桌面工具、客户 Demo 或内部工具，不需要每个 AI 产品都重搭一套 AI 后端。
City 对外暴露的不是 provider API，而是稳定的产品调用边界。在 City 内部，能力通过 Service、Action 和 AIService 组织：
- 产品侧拿到
user_token（其中包含bureau_id） - 用
User City调text()、stream()、image()这类 service - City 内部自己决定模型目录、provider 路由、hooks、usage 和 env
服务端运行时的类叫 Federation（本文里也称 Federation），产品侧用 City 客户端去访问它。两者的边界见 Federation 与 City。
先选你的阅读入口
最短路径启动 Federation，暴露一个模型，签发 token，让产品端成功调到 text() 或 stream()。
先分清 Federation、产品前端、业务后端、AI Gateway 和真实 provider 分别负责什么。
Real Scenarios我已经在接真实产品看纯客户端产品、多产品复用、鉴权、provider env、hooks 和商业逻辑的真实使用方式。
Packages我想按包来查直接按 @downcity/city、client 和 CLI 理解实现边界；官方服务请进入 Federation Services Docs。
按角色直接看 City、User City、FederationAdmin、HTTP API 和环境变量说明。
一张图看懂它怎么工作
User City + user_token (which contains bureau_id)对产品来说，City 暴露的是稳定的 Service action 和 model；上游接什么 provider、网关或私有部署，都是服务端内部细节。
City SDK 负责什么
- Runtime 数据库和 Service 声明的表
- provider key 和 Runtime env
user_token校验与管理员会话管理能力Provider+AIService.use()注册模型，自动提供 SDK 和 OpenAI 兼容两条通路city.ai.catalog()读取 Runtime 注册出来的公开模型目录- usage 记录和 hooks 扩展点
它不负责什么
- 你的用户系统
- 订单、订阅、CRM、内容数据
- 产品自己的页面、交互和业务体验
- 对外暴露“统一 provider API”给其他系统直接调用
更准确地说：
City SDK 负责 Federation 以及其中面向 Service 的 AI 基础设施。 产品继续负责自己的用户、业务、界面和商业模式。