`downcity.json` 参考

项目 downcity.json 是本地 Agent 的运行契约。它声明 Agent 身份、执行绑定、插件配置和 sandbox 边界。City 模型和 Service 细节不直接写进项目文件。

1) Agent 项目最小结构

{
  "$schema": "./.downcity/schema/downcity.schema.json",
  "name": "my-agent",
  "version": "1.0.0",
  "execution": {
    "type": "api",
    "modelId": "quality"
  },
  "plugins": {}
}

execution.type 现在固定为 api，并且 execution.modelId 必须能对应已连接 City AIService 暴露的某个模型。

2) City 模型绑定

项目里只保存选中的模型 ID。

在 City 管理侧选择模型 ID，然后在项目里保留绑定：

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

3) 运行时解析规则

agent 启动时：

先检查项目是否声明了 execution
如果 execution.type = "api"，通过已连接的 City AIService 解析模型 ID
把解析后的模型注入 Agent session runtime

execution 必须合法，否则启动失败。

4) Plugin 配置

插件行为配置写在项目 downcity.json 的 plugins.*。

插件如果需要额外模型、命令模板或本地路径，也直接写在对应的 plugins.<name>.* 下。

例如 asr：

{
  "plugins": {
    "asr": {
      "enabled": true,
      "provider": "local",
      "modelId": "SenseVoiceSmall"
    }
  }
}

5) Chat 渠道绑定

downcity.json 中的 chat 渠道应只绑定全局 bot 账户 ID：

{
  "plugins": {
    "chat": {
      "channels": {
        "telegram": {
          "enabled": true,
          "channelAccountId": "telegram-main"
        }
      }
    }
  }
}

channelAccountId 会解析到 ~/.downcity/downcity.db 的 channel_accounts.id。

6) 推荐操作方式

在 City 层维护 provider/model
在 agent 层配置 execution.type="api" 与 execution.modelId
项目级插件统一放在 plugins.*
本地 shell / CLI 命令默认强制运行在 sandbox 中，项目层 sandbox 只用于调整边界参数
修改后重启 agent：

town agent restart .

7) Sandbox

项目层 sandbox 用于调整 shell / CLI 命令的执行边界，不涉及审批流或 chat 用户权限系统。

示例：

{
  "sandbox": {
    "networkMode": "off",
    "writablePaths": [".", ".downcity"],
    "envAllowlist": ["PATH", "LANG", "TERM", "SHELL"]
  }
}

字段说明：

sandbox.networkMode
- 默认是 full
- off：禁网
- restricted：当前先按放开网络处理
- full：允许网络访问
sandbox.writablePaths
- 允许写入的路径列表
- 可以写相对路径，默认相对项目根目录解析
- 当前只允许项目根目录内路径
sandbox.envAllowlist
- 允许导出到 sandbox 的环境变量名列表

当前实现边界：

当前优先支持 macOS，本地 backend 使用 sandbox-exec
shell 命令强制经过 sandbox，不支持关闭，也不会回退到宿主机普通子进程执行
kind=script 的 task 正文也通过同一套 sandbox backend 执行
未挂入 sandbox 的宿主路径默认不可见
shell 的隔离 HOME / TMPDIR 会落在 .downcity/shell/<shellId>/sandbox/

downcity.json 参考