CLI 快速开始

第一次安装和运行 Downcity CLI 时，先分清 fed/downfed 与 city/downcity。

downcity 包会安装两组命令：

fed / downfed：管理和部署 Federation。
city / downcity：管理本机 Agent、本地插件、chat/gateway，以及当前本机登录到哪个 Federation。

安装

npm i -g downcity

查看版本：

fed -v
city -v

管理 Federation：用 fed

当你要创建、部署或管理共享后端时，使用 fed。

fed
fed create .
fed deploy
fed deploy --dry-run
fed deploy --verify

fed create 生成 Federation 项目骨架，配置文件是 federation.json。fed deploy 读取本地 Federation 项目并部署到目标平台；Cloudflare Workers 目标会自动准备 D1、Queue 和 R2 storage。

管理已部署 Federation：

fed server add
fed server manage
fed query GET /health
fed query GET /v1/ai/models
fed query POST /v1/ai/image/result --data '{"job_id":"..."}'

fed query 会使用当前 active Federation，并带上保存的 admin_secret_key。

管理本机 Agent 和登录态：用 city

当你要让本机连接某个 Federation、登录用户态账号、运行 Agent 或进入 chat 时，使用 city。

city
city federation status
city federation join https://your-federation.example.com
city federation login
city agent create .
city agent list
city agent start
city agent chat

city federation ... 只管理本机的 Federation 成员资格和用户登录态，不负责部署 Federation。

后台 Agent 每次启动都有独立实例 ID。city agent stop 会同时校验 PID、项目路径和实例 ID；如果 pid/meta 已过期或 PID 已被其他进程复用，CLI 只清理 stale 状态文件，不会向无关进程发送信号。

选择 GitHub、Google 等 OAuth 登录方式后，CLI 会始终输出 authorization_url。本地图形环境会同时尝试打开默认浏览器；通过 SSH 登录 VPS 或运行在无图形环境时，请复制该链接到你自己的浏览器中完成授权，CLI 会继续等待登录结果。

federation.json 里的默认存储

Cloudflare Workers Federation 项目可以在 federation.json 里声明默认 storage。当前支持 R2：

{
  "resources": {
    "storage": {
      "type": "r2",
      "binding": "DOWNCITY_STORAGE",
      "name": "downcity-storage",
      "public_url_prefix": "https://images.example.com"
    }
  }
}

部署时 fed deploy 会先检查同名 R2 bucket 是否存在；不存在且不是 dry-run 时会自动创建。随后 CLI 会把它写入临时 wrangler.toml 的 [[r2_buckets]]，并把 public_url_prefix 写成 Worker var。

fed：管理共享后端和 admin 侧能力。
city：管理本机 Agent 和用户态连接。

继续阅读

要部署 Federation，读部署到 Cloudflare Workers
要排查本机状态，读运维与排查
要理解 Federation runtime，读 Federation 运行时

安装

管理 Federation：用 fed

管理本机 Agent 和登录态：用 city

federation.json 里的默认存储

常见误解

`city deploy` 不是部署入口

`city create` 不是 Federation 项目入口

fed 和 city 不是同一个角色

继续阅读

目录