downcity

downcity 是 Downcity 的全局安装聚合包。

npm install -g downcity
downcity -v

安装后会得到 city / downcity 与 fed / downfed 两个相互独立的工具：

• city 是本机 Agent 宿主。CLI 通过数据库 Adapter 和 Repository 读取配置，显式创建 Agent，再由 City 按 ID 统一转发 HTTP/RPC。
• fed 是 Federation Server Manager；TUI 用于注册和管理 Server，项目命令读取当前目录的 federation.json。Local Node.js 和 Cloudflare Workers 都通过 fed deploy 部署。
• fed web 在 127.0.0.1:43128 启动当前 Federation 的本地 Web 管理 UI；管理员登录后的 Session 只保留在 CLI 本地 BFF 内存中。

fed create ./my-fed
cd my-fed
pnpm install
fed deploy
fed

fed create 默认生成 Local Node.js + SQLite 项目。首次 fed deploy 或 fed deploy --admin-reset 会交互式要求输入管理员 ID、密码和确认密码；密码至少 12 个字符，CLI 只在内存中使用明文并将摘要写入数据库。遗失密码时，只有拥有目标基础设施部署权限的人可以运行 fed deploy --admin-reset，非交互环境还必须显式传入 --yes（该参数只确认重置，不跳过凭证输入）。重置会撤销全部现有管理员 Session。CLI 通过本地 SQLite 事务或 Wrangler 远程 D1 权限直接完成管理员恢复，不要求 Worker 读取恢复环境变量；普通 deploy 永远不会修改管理员。部署期间会持续显示当前构建、资源准备、Worker 发布、健康检查与管理员验证阶段。无参数执行 fed 会进入系统级 Federation 管理面板，已部署实例不依赖当前工作目录。

City 的主要命令：

city agent create .
city on
city status
city agent chat <agent_id>
city agent token create <agent_id> --name local
city plugin action <plugin_name> <action_name> <agent_id> --input '{}'

CLI 从本地产品配置装配的 Agent 默认启用 ask_question Tool。使用 city agent chat <agent_id> 交互时，模型可以在缺少关键信息时显示文本、单选或多选问题； 回答会通过 Session Interaction 提交，并在同一轮模型执行中继续处理。

Agent 定义保存在 ~/.downcity/agents/<agent_id>/agent.json，主体指令保存在同目录的 SOUL.md。Plugin 以稳定 ID 使用 ~/.downcity/plugins/<plugin_id>/，每个 Plugin 的唯一明文配置位于自己的 config.toml。第三方 Plugin 的安装目录只保留唯一 plugin.json、建立 ESM 边界的 package.json 与自包含入口，不保留源码和构建配置。Plugin 运行时状态和缓存由宿主放入 ~/.downcity/agents/<agent_id>/plugins/<plugin_id>/，不写入 Plugin 配置目录，也不按 Workspace 复制。downcity.db 只保存 Workspace 索引、Token 与平台状态。Agent 与 Workspace 不绑定，同一个 Agent 可以进入多个 Workspace；Agent 不保存 Plugin 引用，City 自动把全部已注册 Plugin 和同一份配置提供给所有 Agent。CLI daemon 和 Desktop 各自创建独立的 City 实例，加入 City 后，Agent 的 Session 状态统一保存在 ~/.downcity/agents/<agent_id>/sessions/<session_id>/；未加入 City 时只保存在当前 Agent 实例内存中。Workspace 只在 Session 的 meta.json 中作为可选 workspace_id 记录，项目目录不创建 .downcity。

CLI City 只维护一个 daemon，并分别监听一个 HTTP 端口和一个原生 TCP RPC 端口。两种协议都按 agent_id 路由，不为每个 Agent 分配独立端口。

Federation Admin 配置与 Embassy User Session 同样保存在 ~/.downcity/downcity.db。升级后，CLI 会把旧 ~/.downcity/federation.db 中的管理配置一次性迁入统一数据库；旧文件保留用于人工恢复，但后续不再读取。脚本可通过 DOWNCITY_FEDERATION_URL 和 DOWNCITY_USER_TOKEN 显式覆盖当前 Embassy 用户身份。

为独立产品后端登记 Bureau：

fed bureau token

命令打开 Bureau Token 交互式管理界面，可签发、查看和撤销 Token。签发时必须先登录 Federation Admin 并输入用途，也可以直接运行 fed bureau token issue <bureau_id>。CLI 不生成凭证；它请求 Federation 生成明文、保存 hash，并将明文返回一次。把明文写入 Bureau 业务服务的 DOWNCITY_BUREAU_TOKEN 环境变量。脚本中可用 fed bureau token list 查看元数据，使用 fed bureau token revoke <token_id> 撤销。Bureau Token 不能签发 User Token。