Agent 是什么

Downcity 的 agent 是一个面向单个项目的运行时。

你可以把它理解成：

• 一个绑定到代码仓库的 AI 执行实例
• 一个能保存会话、读取项目配置、调用工具、运行 plugin 的项目级助手
• 一个既能通过 CLI 使用，也能通过 SDK 嵌入到你自己的应用里的执行单元

它不是一个“网页聊天窗口”，也不是一个“多项目控制台”。

Agent 负责什么

一个 agent 启动后，会围绕当前项目做这些事：

• 读取项目根目录下的 downcity.json
• 加载 PROFILE.md 和 SOUL.md
• 绑定项目选择的 City AIService 模型
• 创建和维护会话
• 暴露 HTTP / CLI 入口
• 启动项目配置中启用的 plugin
• 把消息、日志和运行产物落盘到 .downcity/

从执行视角看，agent 更像一个“项目级上下文装配器”：

• 它把项目配置、提示词和会话历史装配起来
• 它决定本轮执行可以调用哪些工具
• 它负责让不同入口复用同一套 session 执行内核

因此，一个 agent 不只是“会回答问题”，而是“知道这个项目应该如何被执行”。

Agent 不负责什么

• 不负责管理多个项目
• 不负责 City AIService 模型目录管理
• 不负责 city 级 channel account 的保存
• 不负责全局控制面和 Console UI

这些职责会拆分到 Town 和 City：Town 管本地 Agent 与 Agent plugin，City 管模型、渠道账号等能力。

如果你把 town 和 agent 的职责混在一起理解，后面就会很容易遇到这些困惑：

• 不知道模型应该去哪里配
• 不知道 channel account 应该改项目还是改全局
• 不知道某个问题是 agent runtime 的问题，还是控制面的问题

所以先建立这个边界感非常重要。

你会在什么场景下用它

• 让一个项目变成可对话的 agent
• 通过 town agent chat 在终端里直接和项目对话
• 通过 Telegram、飞书、QQ 等渠道把消息送进项目 agent
• 在 Node.js 应用里通过 @downcity/agent 嵌入本地 agent
• 通过 RemoteAgent 调用另一个进程里已经运行的 agent

如果你的目标是“让仓库本身带有对话和执行能力”，那基本都属于 agent 的适用场景。

两种主要使用方式

1. CLI / Runtime 方式

你在项目目录里运行：

town agent create .
town agent start
town agent chat

这条路径适合“把一个代码仓库启动成一个 agent”。

2. SDK 嵌入方式

你在自己的应用里：

import { Agent } from "@downcity/agent";

然后用 new Agent(...) 创建本地 agent，或者用 new RemoteAgent(...) 调远程 agent。

这条路径适合“把 agent 能力集成进自己的程序”。

什么时候优先用 CLI，什么时候优先用 SDK

更适合 CLI 的情况：

• 你现在的主要目标是把某个仓库先跑起来
• 你想快速验证项目级模型绑定、提示词和聊天入口
• 你需要人工对话和日常使用，而不是程序化集成

更适合 SDK 的情况：

• 你已经有自己的 Node.js 服务、脚本或产品
• 你要把 agent 作为能力嵌入到某个调用链里
• 你希望自己掌控 tools、plugins 和 session 生命周期

一个推荐的阅读顺序

第一次读 Agent 文档时，建议按下面的顺序走：

1. 先看 Agent 和 Console 的关系
2. 再看 Agent 生命周期
3. 然后跑一遍 创建第一个 Agent
4. 如果你要做集成，再进入 Agent SDK 总览

继续阅读

• Agent 和 Console 的关系
• Agent 生命周期
• 第一个 Agent
• Agent SDK 总览