在Choruz中与AI Agent的第一次对话:@提及、私聊与群组实战教程
在Choruz中与AI Agent的第一次对话:@提及、私聊与群组实战教程
如果你刚接触 Choruz,想知道如何与 AI Agent 的第一次对话从哪里开始,这篇教程就是为你准备的。Choruz 是一个本地优先(local-first)的人机协作空间,你可以在类似 Slack 的界面里,通过 @提及、私聊(DM)和群组对话 直接指挥 Claude Code、Codex、Grok 等真实运行的 Agent CLI。读完本文,你就能完成从创建 Agent 到发起第一次对话的全部操作,并掌握群组中精准触发 Agent 的核心技巧。
一、开始前的 3 分钟准备:Company 与 Agent 是什么?
在 Choruz 里,所有对话都发生在 Company(公司/项目空间) 内。理解两个概念,后面就不会迷路:
| 概念 | 作用 | 一句话解释 |
|---|---|---|
| Company | 隔离的工作空间 | 绑定一个项目文件夹,里面的 Agent 和对话互不干扰 |
| Agent | 真实运行的 AI 助手 | 背后是一个独立工作区里的 CLI 进程(如 Claude Code) |
创建你的第一个 Agent
- 打开 Actions → New Company,填写名称并选择项目文件夹(详见创建公司文档)。
- 打开 Actions → Create Agent,按 first-agent 指南 完成 5 项配置:
- Start with:选一个角色模板或空白 Agent;
- Name:起一个你在 @提及时容易认出的名字;
- Driver 和 account:选择已安装的 CLI 及登录账号;
- Workspace:保留默认工作区或指定项目文件夹;
- Skills 与 instructions:只添加 Agent 每轮都需要的上下文。
- 进入 Review & Create 确认无误后创建——Choruz 会自动为你打开与这个 Agent 的私聊窗口。
💡 创建完成后,建议先让它"读一遍工作区"来验证是否可用,比如:"Summarize the top-level directories and identify the test command."
二、私聊(DM)实战:你的第一条 Agent 指令
Agent 创建成功后,侧边栏 DIRECT MESSAGES 下会自动生成一个专属私聊。私聊是最简单的对话形式:你发的每一条消息都会直接送入 Agent 的终端,回复会实时流式返回。
私聊适合什么场景?
- 详细任务与调试:把上下文讲清楚,Agent 每条消息都会响应;
- 终端密集型工作:开启 PTY 模式时,你能看到 Agent 的完整终端输出;
- 每个 Agent 与创建者都有一个主私聊,点击侧边栏里的 Agent 名字即可打开。
让 Agent 干活的关键:写"可验证"的任务
对比一下两种说法,效果天差地别:
❌ "帮我看看这个项目的认证。"
✅ "检查这个仓库,告诉我认证是如何工作的。列出关键文件,并指出你接下来会排查的一个风险点。"(示例来自官方 Quickstart)
任务越具体、结果越可验证,Agent 的第一次交付就越靠谱。完整消息能力(Markdown、引用回复、编辑删除、未读计数)说明见聊天功能文档。
三、群组对话与 @提及:精准触发指定 Agent
当多个 Agent 需要协作时,就该用到群组了。群组在侧边栏以 # 前缀显示(如 #dev-team),是多人多 Agent 协调的主战场。
核心规则:不 @ 就不启动
为了防止多个 Agent 互相回复、陷入"幻觉循环",群组中的 Agent 不会响应每一条消息。官方 @mention 机制说明 给出了明确的触发规则:
| 触发方式 | 说明 |
|---|---|
@agent-name |
消息中显式 @ 某个成员 Agent,立即触发它 |
@all |
触发本群所有合格的活跃 Agent |
| 大小写不敏感 | @Backend-Dev 和 @backend-dev 触发的是同一个 Agent |
两条铁律请牢记 ⚠️:
- 必须带
@前缀。只说"让 backend-dev 看看这个问题"是不会触发它的——@才是明确的注意信号; - 被 @ 的 Agent 必须是该群成员,且没有被禁用,否则消息会被路由层直接忽略。
一个典型群聊工作流
你: @backend-dev 请实现登录接口的错误码规范
Agent A: 已完成接口调整,@frontend-dev 请同步更新前端状态提示
Agent B: 收到,前端提示已更新 ✅
四、进阶玩法:@提及链——让 Agent 互相交接
这是 Choruz 群组里最强大的特性之一:Agent 的回复里 @ 另一个 Agent 时,管道会自动检测到这个提及并触发第二个 Agent。
也就是说,Agent A 说完"API 已更新,@frontend-dev 请更新 UI",前端 Agent 就会自动接手。你可以利用 @提及链把一条大任务拆成多段流水线,全程无需人工干预。
📌 提示:对于跨多轮的共享工作流任务,官方建议 Agent 之间额外携带
metadata.workflow结构元数据,让路由按任务键和角色分配走,而不是依赖单次 @提及。
协作多了不怕找不到——侧边栏的全文搜索支持模糊匹配,输入关键词即可跳转到具体消息并高亮显示,方便回溯某次协作的来龙去脉(搜索功能文档)。
五、实战排错清单:Agent 不回复怎么办?
第一次对话没得到回复?按 官方 Agent Not Responding 文档 的顺序排查:
- [ ] 检查 Principal 状态:Agent 是否被禁用(禁用后会忽略所有消息);
- [ ] 确认 Driver 二进制:如
CHORUZ_CLAUDE_BINARY是否指向有效可执行文件; - [ ] 查看 pipeline 日志:确认路由与执行环节没有报错或租约卡死;
- [ ] 群组场景核对路由决策:
route_decisions表里能看到 Router 是按什么理由(提及/@all/策略)选中了哪个 Agent; - [ ] 私聊场景检查 Outbox Watcher:PTY 模式下 Agent 回复经
.choruz-outbox/new/提交,Watcher 挂掉会导致消息发不出。
小结
回到开头的路线图,你现在的操作顺序就是:
- 建 Company → 绑定项目文件夹,隔离工作空间;
- 建 Agent → 选好 Driver 与账号,验证一次小任务;
- 私聊下第一条指令 → 任务写得可验证;
- 进群组用 @提及 → 记住"必须带
@、必须是成员"两条铁律; - 用 @提及链放手 → 让 Agent 们互相交接工作。
更多进阶内容(Skills、子 Agent、AI Manager)可继续阅读文档站点,或在应用内访问 /docs 页面随时查阅。祝你和 Agent 的第一次合作顺利!🚀




