子智能体把工作拆出去:主智能体理解需求、做计划、写最终答复;子智能体负责跑工具、读代码、驱动 CLI 或调用远程端点。
Rabbit Chat Studio 支持三种运行时:
| 类型 | 运行位置 | 适合 |
|---|---|---|
llm |
应用内,自带工具循环 | 推理、调研、总结、可控的工具使用 |
cli |
本机安装的无头编程 CLI | 大规模改代码、重构、跑测试 |
cloud |
远程 HTTP 端点 | 已有远程智能体服务、隔离执行 |
磁盘上的定义
llm 智能体的身份与提示词存在 Markdown 文件里,不在 sub_agents.json 中:
<应用数据>/agents/
<分类>/<slug>.md # 导入/库内定义(面板里只读)
custom/<slug>.md # 面板里创建的智能体
index.yaml # 发现清单,点"刷新"时替换
- 文件是 YAML frontmatter(
name、description、emoji、color)加正文系统提示——与技能同构。 sub_agents.json只留运行时开关(enabled、model、token 上限、allowed_tools、allowed_skills、max_iterations、enable_mcp)和file引用。cli/cloud智能体的完整定义仍在其中。- 发现是显式的:打开面板只读
agents/index.yaml;只有 刷新 才重扫目录并替换清单。上次刷新后新增的文件在下一次刷新前不可见。 - 被发现但没有配置条目的文件列为一个禁用的虚拟智能体(
configured: false),在你启用或编辑它之前不会写进sub_agents.json。 - 只有
agents/custom/**能从面板删除;库内文件在面板里只读——请改为禁用。 - 面板保存只会在解析后的定义确实变化时重写文件,并先留
.bak.<n>备份。 - 旧版内联
llm提示(旧sub_agents.json或旧配置)会自动迁移成 Markdown 文件。
面板与编排
点顶部工具栏的 Agents。编排相关设置(自动规划、智能选择 agent、执行模式、并发、每对消息上限)收在面板的分组开关里,默认把空间留给智能体列表:折叠时只留总开关「子智能体系统」,展开后才是下面这几层开关。
子智能体系统(use_agents)
总开关,决定这套系统是否存在。
- 关:主智能体直接回答,
call_subagent既不下发也不可调用。 - 开:
call_subagent下发给主智能体,随时可以手动委派;是否自动规划交给下一层开关。
自动规划(auto_plan,默认开)
-
关:不做规划,主智能体直接作答;
call_subagent仍然可用,需要时由模型自己调用(手动委派)。 -
开:只要至少有一个子智能体启用,每条用户消息都先走编排:
- 规划器用主模型把需求拆成任务;
- 每个任务指派给一个子智能体;
- 任务并行或串行执行;
- 任务报告注入主智能体上下文;
- 主智能体写最终答复。
编排失败(没有启用的智能体、规划失败)时记一条警告并退回直接回答。
执行期间,聊天流会显示计划开始、任务开始/流式/完成/报错与汇总事件。
委派闸门:选择调用只提出候选名单,规划请求本身再回答一次"要不要委派"。明确说不就跳过本次任务——选择结果记为已谢绝,主智能体独自作答。名单芯片只在规划器确认后才发出,所以被谢绝的计划不会留下过期名单。只含一个任务的计划也是合法的。
实时任务行:每行自带状态——运行中显示思考计数与工具活动行,已停止的任务显示中性状态而不是完成,供应商错误只出现在任务行上,绝不会变成关闭你这一轮的聊天错误。
自动规划开着时每条消息都要付规划开销。简单问答就关掉自动规划(仍可手动委派),或只留一个轻量智能体。
智能选择 agent(auto_configure)
开启后,规划之前先用一次模型调用挑选本轮参与的子智能体,再交给规划器;任务类型变化很大时有用,代价是多一次 LLM 调用。关闭时所有已启用的子智能体全部参与,由规划器自行取舍。这个开关只在自动规划开启时生效。
执行模式
| 模式 | 行为 |
|---|---|
| 并行 | 任务并发执行,受 最大并发 限制 |
| 串行 | 按计划顺序逐个执行 |
规划器也可以把某个计划标为串行;以计划为准。
最大并发 1–10,默认 3。
智能体列表
每个智能体显示:
- 启用开关;
- 名称与类型徽标(LLM / CLI / Cloud);
- 状态(运行中 / 完成 / 报错);
- 目标(模型、命令或端点);
- 最近摘要 / 错误 / token 用量;
- 编辑与删除按钮。
列表可按启用状态筛选——全部 / 已启用 / 已禁用——并与搜索框叠加。
工具栏 Agents 旁的数字是已启用的智能体数量。
任务总线与规划器接管
每个由规划器派发的任务会建一个进程内发布/订阅总线(mbus):规划器与计划内任务是同级,broadcast 到达所有人,支持 +/# 主题订阅,总线还维护任务的实时状态登记。消息只在子智能体的下一个请求边界送达,绝不在流式输出中途插入。
- 每对上限 —— 面板设置 每对智能体消息数(默认 4,
0为关闭)。双向合并计数;主题发布对每个接收者分别计数;规划器豁免。两个智能体撞到上限时,最后那条仍然送达,规划器被通知一次,此后这对之间的消息被拒并附"已通知规划器",让规划器去协调而不是让两者互相刷屏。 - 规划器接管 —— 规划器可以用两个总线动作干预运行中的任务:
direct(目标 + 目的 + 可选完成条件)在该任务上存一份权威目的,每轮重新渲染进任务提示,因此能扛住上下文压缩;end_task(目标 + 可选说明)要求任务收尾;在它下一个推理边界,任务把当前结果作为成功上报,而不是再花一次请求。cli/cloud任务无法轮询总线,所以end_task对它们会被拒。
- 每个规划决策都会在聊天的智能体广播里留一行——
schedule、send、status、history、subscribe、finish,以及"指令 → 目标"和"已结束任务"标记。
创建 LLM 子智能体
- Agents → + 新建智能体。
- 类型:
LLM。 - 名称与描述。描述会出现在主智能体的可用智能体列表里,把职责写清楚。
- 系统提示:角色、输出格式、边界。
- 模型(可选):留空继承主模型,填写则覆盖。
- 最大补全 token 与温度(可选)。
- 最大迭代:默认 10;
0表示不限(由外部任务状态决定何时停)。 - 可用工具:勾选
file_actions/run_cmd/run_shell的子集;有 全选 / 全不选 快捷键。 - 保存并启用。
面板只提供这三个执行类工具,timer 永远被过滤。每个 llm 子智能体还默认带 memory 工具,且记忆作用域与主智能体共享:session 按主对话的 session_id 归属(主智能体 + 所有同级任务),user / repo 在 <工作区>/.data/memory,evolution 在自我进化模式下存在。子智能体提示要求它开工前先搜记忆、收工前记一条简明结论;它从不执行 consolidate。cli / cloud 智能体调不了应用工具,因此拿不到记忆摘要。自我进化模式下子智能体额外获得 file_actions,因为它可能要演进技能。
任务的静态提示里还带一段主对话摘要(MAIN CONVERSATION,最多 12 条 / 12 KB):委派时给的 description 与 context 可能很薄,这段摘要让它看到用户的原话。它只用于理解背景,任务描述仍然是权威的。
sub_agents.json里还有allowed_skills字段,但面板不暴露它,运行路径也不按它过滤技能;技能由主智能体加载。
创建 CLI 子智能体
CLI 智能体启动本机安装的无头编程 CLI,把任务作为提示传入,并流式读回输出。
必填
| 字段 | 说明 |
|---|---|
| 命令 | 可执行名(经 PATH 解析)或完整路径;Windows 的 .cmd / .bat / .ps1 会被处理 |
| 参数 | 每行一个;支持 {prompt}、{model}、{cwd}、{agent_name} |
| 提示传递 | 作为参数({prompt}) 或 经标准输入 |
可选
| 字段 | 说明 |
|---|---|
| 模型参数 | 每行一个;每次运行都追加——直接写模型 id(如 -m 与模型各占一行)。不继承主配置 |
| 环境变量 | 每行一个 KEY=VALUE;默认含 NO_COLOR=1、CLICOLOR=0、FORCE_COLOR=0、TERM=dumb;同名覆盖 |
| 工作目录 | 相对工作区的目录;留空为工作区根;会做沙箱检查 |
| 默认超时 | 秒,默认 600;0 = 不超时 |
| 需要批准 | 首次运行前询问;关闭后启用开关即长期授权 |
每次运行都是全新的 CLI 会话,不跨调用保留状态;非零退出或超时会把任务记为 failed。
内置无头调用
参数为空时,已知 CLI 自动套用无头形式:
| 命令 | 默认参数 |
|---|---|
opencode |
run {prompt} |
claude |
-p {prompt} |
codex |
exec {prompt} |
gemini |
-p {prompt} |
qwen |
-p {prompt} |
crush |
run {prompt} |
droid |
exec {prompt} |
cursor-agent |
-p {prompt} |
copilot |
-p {prompt} |
amp |
-x {prompt} |
显式参数永远优先;默认值只在参数列表为空时套用。
示例:opencode
命令:opencode
参数:
run
{prompt}
提示传递:作为参数
工作目录:(空)
超时:900
等价于:
opencode run "<任务>"
测试
编辑器里点 测试:
- CLI:执行
<命令> --version,显示解析到的路径、退出码与输出; - Cloud:对端点发一次 GET,显示可达性、HTTP 状态与详情。
运行行为
- 子进程 cwd 是工作区(或配置的相对
cwd),并同步PWD; - 输出流向前端并剥离 ANSI 颜色码;
- 超时、Stop、退出应用会杀掉整棵进程树(Unix 进程组 / Windows job);
- 非零退出或超时把任务标为
failed(不会出现绿色"完成"徽标); - Windows 上不弹控制台窗口;
- 若提示里可能含
cmd.exe会展开的文本(如%VAR%),优先用stdin。
创建 Cloud 子智能体
请求
| 字段 | 说明 |
|---|---|
| 端点 URL | 接收 POST |
| 令牌 | 可选,以 Authorization: Bearer <token> 发送 |
| 额外请求头 | 每行一个 KEY=VALUE |
| 请求体模板 | JSON;替换并转义 {prompt}、{agent_name}、{cwd} |
| 结果路径 | 响应中文本的点路径,如 choices.0.message.content 或 result.output |
| 超时 | 秒,默认 1800 |
默认请求体:
{"messages":[{"role":"user","content":"{prompt}"}]}
默认结果路径:
choices.0.message.content
异步轮询(可选)
若远端是"提交任务 → 轮询结果":
| 字段 | 说明 |
|---|---|
| 轮询 URL | 如 https://api.example.com/jobs/{id};{id} 会被替换 |
| 任务 id 路径 | 首次响应里的点路径,默认 id |
| 状态路径 | 轮询响应里的点路径,默认 status |
| 完成值 | 每行一个;默认 completed / succeeded / success / done / finished |
| 失败值 | 每行一个;默认 failed / error / cancelled / canceled |
| 轮询间隔 | 秒,默认 5 |
轮询 URL 留空表示只取一次响应。
call_subagent
编排开启时,主智能体还会得到 call_subagent:
{
"agent_id": "精确的智能体 id",
"task_description": "自包含的任务描述",
"context": "可选补充上下文",
"run_in_background": false
}
规则:
- 子智能体看不到当前对话;
task_description必须自包含。 context会附加到任务描述后;用于放文件路径、发现与约束。- 主智能体等待结果。
- 开启 设置 → 运行时与调试 → 后台执行 后,
run_in_background: true立即返回bg-…id:子智能体继续跑,主智能体继续干活,报告在它下一个请求前送达(期间本轮保持打开)。子智能体自己永远拿不到这个开关。 - 每次调用(以及每次规划任务)都有一个交付物交换目录:
<工作区>/.data/deliver/<会话 id>/<批次 id>/,含一个shared/和每个任务一个目录。子智能体的提示会点明自己的目录与共享目录;大输出应写在这里而不是硬塞进答复,依赖任务则被告知去读<交换根>/<任务 id>/<文件>。任务报告与call_subagent结果会列出产出文件及大小,主智能体可用file_actions打开。 - 交换区是长期保留的,没有自动清理。打开方式:标题栏
⋯菜单 → 打开交付物文件夹、任务监视器刷新按钮旁的按钮,或任务面板的交付物列表(列出已完成任务留下的文件)。它纳入配置备份,并随会话一起删除。cloud智能体够不到本地工作区,只能内联返回交付物;llm与cli使用目录。 - 最终答复仍由主智能体撰写;子智能体从不直接回复用户。
任务状态与监视器
每个子智能体任务在工作区 <工作区>/.data/chat.db 里有任务记录(agent_missions / agent_tasks)。
子智能体可以使用任务工具:
add_taskupdate_task_statusget_active_tasksmark_mission_accomplished
打开 设置 → 运行时与调试 → 智能体任务监视器 可查看:
- 任务状态、根任务描述、上下文;
- 活动任务及其状态;
- 任务产出的交付物;
- 情节摘要;
- 最终报告;
- 创建/更新时间。
停止与失败
-
生成过程中按 Stop:
- 规划阶段:步骤之间检查取消,不再启动新子智能体;
- 执行阶段:杀掉 CLI 进程树;云端轮询在两次之间检查取消标志并停止等待;剩余任务标为跳过;
- 任务状态变为
stopped,不是completed; - 主智能体不再继续写最终答复。
-
单个子智能体失败不会拖垮任务;错误记在该任务上,其他任务继续。
-
达到最大迭代仍未
mark_mission_accomplished,任务以未完成关闭。
批准
cli 与 cloud 智能体默认 需要批准:
- 每个智能体在每次应用运行中首次执行前询问一次;
- 允许后本次运行不再询问;
- 关掉它,启用开关就是长期授权;
- 这属于
external_agent确认类型,不在 工具 → 自动接受 覆盖范围内——后者只覆盖内置命令的 L0–L3 确认。
外部智能体跑在应用之外:CLI 以你的用户权限运行,Cloud 把任务发到远程端点。只启用你信任的智能体。
最佳实践
- 描述里写清"它负责什么、输出什么、不许做什么"。
- 给最小的 LLM 工具集;只读任务别给
run_shell。 - 按任务设 CLI 超时;大重构可能需要 1800–3600 秒。
- 先用测试或
curl验证云端结果路径。 - 简单问答关掉编排;复杂多文件工作再开。
- 并行任务不要写同一批文件,否则互相覆盖。
常见问题
| 现象 | 排查 |
|---|---|
| 编排开着却直接回答 | 有启用的智能体吗?编排失败了吗?看日志/任务监视器 |
| CLI 测试失败 | 命令在 PATH 里吗?Windows 是否需要 shell 包装?读 --version 输出 |
| CLI 输出为空 | 参数把提示传进去了吗?试试 stdin;看超时与退出码 |
| Cloud 401/403 | 令牌与请求头;是否还有其他认证要求 |
| Cloud 结果为空 | result_path 与响应 JSON 对得上吗? |
| 轮询一直不结束 | poll_status_path、完成值、轮询 URL |
| 子智能体看不到文件 | cwd、权限、工具白名单 |
新增的 agents/*.md 不出现在面板 |
点 刷新;面板读的是 agents/index.yaml,不是目录 |
| 发现的智能体是灰的 | 它在 sub_agents.json 里还没有条目:启用或编辑一次 |
| 删不掉库内智能体 | 只有 agents/custom/** 可删;请改为禁用 |
没有 run_in_background |
设置 → 运行时与调试 里后台执行没开 |
| Stop 之后仍有进程 | 正常会杀进程树;检查任务管理器与日志 |
| 任务监视器是空的 | 本次会话没有跑过子智能体;或工作区数据库换了? |