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 create ./edge-fed --template cloudflare-workers
fed create ./custom-fed --template git://example.com/custom-fed.git
fed deploy
fed deploy --dry-run
fed deploy --verify

fed create 默认生成 Local Node.js + SQLite 项目。--template 可以选择 cloudflare-workers 或 Git 模板。项目身份和部署方式统一写在 federation.json 中。

fed deploy 表示部署当前项目，不区分本地与云端。本地目标会从 12314 开始分配端口并启动受管进程；首次部署时 CLI 交互式设置管理员 ID 和密码，后续普通部署复用现有管理员。重复部署同一 fed_id 时会用最新代码替换旧实例，不会修改管理员。Cloudflare Workers 目标会准备 D1、Queue 和 R2，再发布 Worker，并通过管理员登录创建有期限的 Session Token 保存到本地 registry。

管理已部署 Federation：

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

所有 Federation URL、active 状态、管理员 ID、管理员 Session Token、本地 PID、端口、日志和部署状态都保存在系统级 Federation registry，不依赖当前路径。downfed 没有默认 Federation；fed deploy 只登记或更新实例，不会修改 active_server_url。用户在 downfed 界面明确打开 Federation 后，它才成为 active。fed query 在存在有效管理员 Session 时自动携带 Authorization: Bearer，Session 失效后要求重新登录。

federation.json

{
  "schema": 1,
  "type": "federation",
  "id": "fed_example",
  "name": "example",
  "entry": "src/index.ts",
  "deployment": {
    "target": "local",
    "scripts": {
      "build": "pnpm typecheck",
      "deploy": "pnpm start"
    }
  }
}

deployment.scripts 是可选覆盖。没有配置时使用目标内置部署器；配置 build 或 deploy 时只替换对应阶段。

管理本机 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 agent chat 会持续订阅当前 Session，并实时合并 Message、Part、文本、reasoning、Tool、Interaction 和配置状态。顶部会显示当前 Session 的模型名称；使用 /model 可从当前用户可调用的模型目录中选择模型，也可通过 /model <model-id> 直接切换。模型切换只影响当前 Session，并通过 Session Mutation 更新界面，不会修改 Agent 默认模型。使用 /session 切换会话时，TUI 会先订阅新 Session，再加载完整快照并合并期间收到的事件。模型提供可见 reasoning 文本时，TUI 会按 Assistant Part 顺序弱化展示；只有 reasoning metadata 时不会生成虚假的推理内容。

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：

{
  "deployment": {
    "target": "cloudflare-workers",
    "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

federation.json

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

federation.json 里的默认存储

常见误解

`city deploy` 不是部署入口

`city create` 不是 Federation 项目入口

fed 和 city 不是同一个角色

继续阅读

目录