CLI 命令

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/Plugin 配置或 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 状态。Federation、全局 Plugins、语言和命令帮助直接位于同一列表末尾的“设置”分组。

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

Agent 与 Workspace 独立登记。Agent 每次执行时进入所选 Workspace，不保存持久化 Workspace 绑定。Agent 没有独立启动状态；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]

Plugin

city plugin list 会展示每个 Plugin 的标题、稳定 ID、用途、来源和已保存 profile。

city plugin list
city plugin install <local-directory|git-url|github:owner/repo#ref>
city plugin update <plugin_id>
city plugin uninstall <plugin_id>
city plugin inspect <plugin_id>
city plugin profiles <plugin_id>
city plugin config <plugin_id> [profile] --set '{"key":"value"}'
city plugin config <plugin_id> [profile] --interactive
city plugin config <plugin_id> [profile] --remove
city plugin enable <plugin_id> [agent_id] --profile <profile>
city plugin disable <plugin_id> [agent_id]
city plugin enabled [agent_id]
city plugin action <plugin_id> <action_name> [agent_id] --input '{"key":"value"}' --token <token>

一个第三方来源目录只定义一个 Plugin。plugin.json 声明 schema_version: 1、全局唯一 id、版本、单个自包含 ESM setup、可选的 icon；setup 模块导出 schema 与 setup(context)，package.json 必须声明 "type": "module"。来源目录必须包含 README.md。最终目录固定为 ~/.downcity/plugins/<plugin_id>/，包含安装后的 plugin.json、package.json、README.md、setup、可选本地图标与本地 config.toml，不复制源码和构建配置。安装过程不会执行 npm install、构建脚本、Plugin lifecycle 或调用 setup()。

Plugin 配置属于 plugins/<plugin_id>/config.toml 中的命名 profile。账号、渠道、端点等结构由 setup 模块导出的 JSON Schema 定义，TypeScript 类型由 Plugin 代码独立维护。配置以 0600 权限明文保存；CLI 在配置时加载同一 Schema，构建表单并脱敏 writeOnly 字段。Agent 未选择 profile 时只使用 {}，不会自动读取 default profile；只有明确传入 --profile 才会使用命名 profile。

Agent 的 agent.json 只保存 Plugin ID 和可选 profile 引用，移除该条目即禁用 Plugin。仍被 Agent 引用的 profile 或第三方 Plugin 不能删除。

修改 enable、disable 或 profile 配置后，运行中的 CLI City 需要执行 city restart，新的装配才会生效。

CLI、Agent plugin_call、HTTP 与定时任务统一调用 Plugin Action。不存在 plugin 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 留存表和漏斗。