CLI 命令

City 与 Fed 的常用命令

City 生命周期

city on                         # 启动唯一 CLI City daemon
city on --port 5314 --rpc-port 15314
city status
city restart
city off
city reset                       # 确认后重置本地配置数据库
city reset --yes                 # 跳过确认

CLI City 使用一个 HTTP 端口和一个原生 TCP RPC 端口，并在两个协议内按 agent_id 路由全部 Agent。

city reset 会先停止 CLI City daemon，再删除 downcity.db、downcity.db-wal 和 downcity.db-shm。它不会删除 .env、Agent/Power 配置或 Workspace 中的 Session 文件。

Agent

city                               # 直接打开 Agent 列表
city agent                         # 打开同一个 Agent 列表
city agent create [path]           # 不传路径：当前目录或系统文件夹选择窗口
city agent list
city agent model [agent_id]
city agent chat [agent_id]

裸 city 命令直接打开 Agent 列表，不展示 Agent runtime 状态。city agent list 以 名称 · agent_id 展示每个 Agent。Federation、全局 Powers、语言和命令帮助直接位于同一列表末尾的“设置”分组。

City 装配的 Agent 默认启用 ask_question Tool。在 city agent 面板选择 Agent 后会直接进入最近一次对话，并跟随该 Session 所属 Workspace；该 Agent 还没有历史时，在入口 Workspace 新建 Session。模型需要关键补充信息时会显示文本、单选或多选面板；CLI 将完整答案提交给当前 Session，并继续同一个 Turn。按 Esc 可停止当前 Turn。

Agent 与 Workspace 独立登记。Agent 每次执行时进入所选 Workspace，不保存持久化 Workspace 绑定。Agent 没有独立启动状态；city agent chat --session-id <id> 必须指向已存在的 Session，并进入该 Session 所属 Workspace；--workspace <id> 会把 Chat 限定在该 Workspace：只在其中查找 Session、必须与所选 --session-id 的 Workspace 一致，新 Session 也会创建在那里。Chat 内使用 /new 创建新 Session、/session 选择已有 Session 或新建 Session、/config 打开 Agent 配置，配置完成后会回到原对话。City 运行时 Chat 走 RPC，脚本化的一次性调用在 City 关闭时仍可使用本地装配路径。

在输入框中可以使用 slash command 打开系统文件选择器并添加本地附件：

/attach

附件会加入下一条消息；也可以使用 /file 别名。Unix 终端的 Ctrl-V（Windows 为 Alt-V）会优先尝试粘贴剪贴板中的图片或文件，无法识别时仍按普通文本粘贴处理。

审批请求在专用面板中完成，不再使用 /approve 或 /deny slash 命令。

单 Agent Token

Token 只属于一个 Agent，并可访问该 Agent 的全部非公开 HTTP API。没有 User、Role 或 Permission 层。

city agent token list [agent_id]
city agent token create [agent_id] --name automation
city agent token create [agent_id] --name temporary --expires-at 2026-08-01T00:00:00Z
city agent token delete <token_id> [agent_id]

Power

city power list 会展示每个 Power 的标题、稳定 ID、用途、来源和是否提供 Config。

city power list
city power install <local-directory|git-url|github:owner/repo#ref>
city power update <power_id>
city power uninstall <power_id>
city power inspect <power_id>
city power config <power_id>
city power config <power_id> --set '{"key":"value"}'
city power action <power_id> <action_name> [agent_id] --input '{"key":"value"}' --token <token>

一个第三方来源目录只定义一个 Power。power.json 声明 schema_version: 1、全局唯一 id、版本、必填的 .md readme 相对路径，以及可选的 main、renderer。main 是自包含的统一 City Power ESM；renderer 对象声明单文件 ESM 入口以及 sidebar、mainview、config 三项静态能力，Sidebar 与 Mainview 必须成对出现。两个运行入口至少提供一个。package.json 必须声明 "type": "module"。安装目录只保留声明制品、文档、可选图标与本地 config.toml；安装过程不会执行依赖安装、构建脚本或任何第三方入口。

声明 Config 的 Power 在 powers/<power_id>/config.toml 中保存唯一配置。具体结构、校验、Secret 投影和 Config UI 都由 Power 自己管理。CLI 的 config --set 仅用于显式替换完整 JSON，不生成通用表单，也不会输出凭据原文；无 --set 时只显示是否已配置和字段名。

City 自动把全部已注册 Power 提供给全部 Agent；agent.json 不保存 Power 引用或配置。需要多账号时，由 Power 在自己的配置结构中表达账号集合和选择规则。配置保存后，Power 负责刷新受影响的长期资源。

CLI、Agent 的 Power 工具、HTTP 与定时任务统一调用 Power Action。不存在 power command，Chat 也不再是顶层命令特例。

Env 与 Federation

city env                                      # 打开 Env TUI
city env list --global
city env list --agent <agent_id>
city env set <key> <value> --global
city env set <key> <value> --agent <agent_id>
city env delete <key> --global
city env delete <key> --agent <agent_id>
city federation

Global Env 写入 ~/.downcity/.env；Workspace Env 写入项目根目录的 .env。也可以从 city agent 的“配置 Env”入口选择 Agent 所使用的 Workspace。修改完成后，CLI City 会更新受影响的 runtime Agent，并通过 Workspace 将新快照广播给已有 Session；未被该 City 持有的 Agent 会在下一次被 City 装配时读取新配置。

多个 Agent 在同一 Workspace 运行时共享同一个项目 .env。运行时优先级为：Global .env 低于 Workspace .env，启动进程显式环境变量最高。list 不显示明文值；copy 只允许从本机 CLI 显式执行。

Federation 用户请求统一通过 Embassy。交互登录态保存在 ~/.downcity/downcity.db；自动化脚本可以用 DOWNCITY_FEDERATION_URL 与 DOWNCITY_USER_TOKEN 显式覆盖当前登录态。这两个身份变量不会从 Global .env 注入 Workspace 进程。

Fed

fed                              # Federation Server 管理 TUI
fed web                         # 启动当前 Federation 的本地 Web 管理 UI
fed web --no-open --port 43128  # 启动但不自动打开浏览器
fed server add
fed server manage
fed bureau token                          # 打开 Bureau Token 管理 TUI
fed bureau token issue <bureau_id>        # 输入用途并请求 Federation 签发 Token
fed bureau token list
fed bureau token revoke <token_id>
fed query GET /health
fed create [dir]
fed deploy [source]

fed web 默认在 http://127.0.0.1:43128 启动本地控制面。它读取当前 active Federation，也可以用 --federation <name-or-url> 显式选择。管理员会话 Token 只由本地 CLI 进程持有，不会发送到浏览器；为避免把 Federation 管理控制面暴露到网络，该命令只允许监听 127.0.0.1、localhost 或 ::1。页面包含 Dashboard、用户、Bureau、模型、Env、 Credits、Usage、支付、Service 目录与调试器。分析区进一步分为数据概览、用户活跃、 Usage 消耗、用户留存、调用质量和用户明细。

Usage Dashboard 以浏览器所在 IANA 时区统计：日活是今日产生至少一次 AI Usage 的去重用户，周活和月活分别是滚动 7 天与 30 天去重用户。用户用量页展示所有注册用户，包括零用量用户；默认按 Total Tokens 降序排列，与总览的 Token 消耗排行使用相同口径，也可按调用数、Credits、P95 耗时与最后活跃时间排序。每个用户同时展示 Input、 Output、Total Token、成功率、Top Model、平均/P95 耗时和已入账 Credits 消耗。图表包含 DAU/WAU/MAU 折线、24 小时活跃柱状图、Token 堆叠图、模型与 Action 分布、执行结果与耗时趋势，以及 D1/D3/D7/D14/D30 Cohort 留存表和漏斗。