City 配置存储（downcity.db）

从当前版本开始，City 侧共享配置不再使用：

1. ~/.downcity/downcity.json
2. ~/.downcity/.env

City 侧配置统一存储在：

• ~/.downcity/downcity.db

存储内容

downcity.db 中主要包含以下数据域：

1. City AIService 模型目录（providers/models）
2. City 侧管理的 env 记录（env_entries）
3. Bot 账号凭据池（channel_accounts）
4. Chat 用户授权（chat_auth_roles、chat_auth_role_permissions、chat_auth_channel_defaults、chat_auth_user_roles）

其中敏感字段（如 API Key）采用加密存储。

与 Agent 项目配置的边界

以下文件仍然是 Agent 项目级配置（保留不变）：

1. <agent>/downcity.json
2. <agent>/.env

也就是：

• City：~/.downcity/downcity.db
• Agent：项目目录下的 downcity.json/.env

环境变量作用域（重要）

当前版本按明确分层工作：

1. 宿主显式注入 env：new Agent({ env })
2. Agent 本地运行时覆盖：<agent>/.env（用户维护）
3. Chat 渠道凭据：channel_accounts（由 downcity.json 的 channelAccountId 绑定）
4. Chat 用户授权：chat_auth_* 结构化表（city 全局生效）

关键行为：

1. Agent 运行时 env 最终是 new Agent({ env }) + <agent>/.env（.env 优先）。
2. 当宿主是 town 时，会先从 downcity.db 读取 City 侧 env，再显式传给 Agent。
3. downcity.json 只保存渠道绑定（channelAccountId），不保存明文密钥。
4. 渠道真实凭据来自 channel_accounts。
5. 用户聊天权限来自 chat_auth_* 表，不保存在 agent 项目里。
6. plugin 参数来自项目 downcity.json，plugin 运行态归属于 Agent 进程。

常用操作

初始化本地 Town 状态和 City 连接元信息：

town init

查看项目 plugin 参数：

town config get plugins.asr
town config set plugins.asr.modelId '\"SenseVoiceSmall\"'

需要运行态操作时，使用显式 plugin 命令：

town asr on
town asr off

让 Agent 项目使用 City 模型：

town city status
town config set execution.modelId <modelId>

相关文档

• Env 与 downcity.db 数据库设计
• 环境变量配置逻辑（City 侧 vs Agent 私有）

运行文件

以下运行文件仍保留在文件系统（非配置）：

1. ~/.downcity/main/city.pid
2. ~/.downcity/main/city.log
3. ~/.downcity/main/console.pid
4. ~/.downcity/main/console.log
5. ~/.downcity/main/console.json
6. ~/.downcity/main/agents.json