圆桌 Step2:固定协调员单例、优化调度性能、修正研讨中状态
将 roundtable-coordinator 改为内置单例避免重复创建;legacy sync 加 TTL 减少 runs/stream 延迟;前端仅当前发言者显示研讨中。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
2371364911
commit
de597b602a
9 files changed
+507
-280
No files matched your search
@@ -2,21 +2,35 @@
|
||||
|
||||
适用场景
|
||||
--------
|
||||
``roundtable-intent`` / ``roundtable-recommender`` 是圆桌 Step 1 + 推荐链路的
|
||||
**功能型** 内置 agent,任何部署都必须存在。但仓库根 ``.gitignore`` 把整个
|
||||
``.deer-flow/`` 目录排除,新机器 ``git clone`` 之后这两个目录**不会存在**,
|
||||
直接调 ``/api/intent/stream`` 会因为 agent 解析失败抛 500。
|
||||
``roundtable-intent`` / ``roundtable-recommender`` / ``roundtable-coordinator``
|
||||
是圆桌 Step 1 + 推荐 + Step 2 总控链路的**功能型** 内置 agent,任何部署都必须
|
||||
存在。但仓库根 ``.gitignore`` 把整个 ``.deer-flow/`` 目录排除,新机器
|
||||
``git clone`` 之后这些目录**不会存在**,直接调对应 endpoint 会因为 agent
|
||||
解析失败抛 500。
|
||||
|
||||
本模块在三个路由入口(``intent.init``、``intent.stream``、``recommend.stream``)
|
||||
被调用,检查磁盘文件是否齐全;缺失则用下方嵌入的标准模板写回去。
|
||||
``_sync_legacy_agents`` 会在下一次 ``GET /api/agents`` 时把目录 upsert 进 DB,
|
||||
所以这里只关心磁盘文件,不直接动 DB。
|
||||
本模块在四个路由入口(``intent.init``、``intent.stream``、``recommend.stream``、
|
||||
``multi_agent.init``)被调用,检查磁盘文件是否齐全;缺失则用下方嵌入的标准模板
|
||||
写回去。``_sync_legacy_agents`` 会在下一次 ``GET /api/agents`` 时把目录 upsert
|
||||
进 DB,所以这里只关心磁盘文件,不直接动 DB。
|
||||
|
||||
为什么嵌入字符串而不是用 importlib.resources 资源文件
|
||||
------------------------------------------------------
|
||||
SOUL 体量不大(两个加起来 ~200 行),嵌入到 Python 文件里是**单一可信源**——改
|
||||
SOUL 体量不大(三个加起来 ~400 行),嵌入到 Python 文件里是**单一可信源**——改
|
||||
SOUL 走代码 review、commit 走 git 历史,且不会因为 wheel 打包漏配
|
||||
``package-data`` 导致部署机拿不到。
|
||||
|
||||
为什么 ``roundtable-coordinator`` 是单例而不是每次会话新建
|
||||
------------------------------------------------------------
|
||||
历史实现每次 Step 2 init 都用 ``roundtable-coordinator-<timestamp36>`` 这种
|
||||
带时间戳的临时 id 创建新 agent,把"本次可调度席位列表"写进动态拼接的 SOUL。
|
||||
长期跑下来 ``.deer-flow/agents/`` 累积了几十上百个完全相同的 coordinator
|
||||
壳,管理页非常杂乱。
|
||||
|
||||
改造后 coordinator 是 **单例**(id 固定为 ``roundtable-coordinator``):
|
||||
- SOUL 是**通用协调规则**,不含本次席位列表;
|
||||
- 本次圆桌可调度的席位清单由 ``multi_agent.init`` 在创建好 coordinator
|
||||
thread 后,以 human 消息的形式 append 到 thread 历史,让 leader run 自然
|
||||
读到。这样 SOUL 长期稳定,席位列表随会话动态注入。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -476,17 +490,91 @@ RECOMMENDER_AGENT_SOUL = """# 智能体推荐专员
|
||||
"""
|
||||
|
||||
|
||||
_BUILTIN_FUNCTIONAL_AGENTS: tuple[tuple[str, str, str, str], ...] = (
|
||||
(INTENT_AGENT_ID, INTENT_AGENT_NAME, INTENT_AGENT_DESCRIPTION, INTENT_AGENT_SOUL),
|
||||
(RECOMMENDER_AGENT_ID, RECOMMENDER_AGENT_NAME, RECOMMENDER_AGENT_DESCRIPTION, RECOMMENDER_AGENT_SOUL),
|
||||
COORDINATOR_AGENT_ID = "roundtable-coordinator"
|
||||
COORDINATOR_AGENT_NAME = "总控协调"
|
||||
COORDINATOR_AGENT_DESCRIPTION = (
|
||||
"圆桌总控协调智能体,基于「任务目标 + 当前会话已选席位列表」决定派活给哪些子智能体、"
|
||||
"汇总它们的交付,达成共识后输出最终方案。本身不调研、不写文档,只负责协调与综合。"
|
||||
)
|
||||
|
||||
# Coordinator SOUL 是**通用版本**——只规定协调规则、工具用法、终止条件,
|
||||
# **不**包含本次会话的席位列表。席位列表由 multi_agent.init 在创建 coordinator
|
||||
# thread 时以 human 消息的形式 append 进对话历史,leader run 每次都能看到。
|
||||
# 这样 SOUL 单例 + 席位列表动态注入,避免每次 init 重写 SOUL 文件。
|
||||
COORDINATOR_AGENT_SOUL = """# 圆桌总控协调智能体
|
||||
|
||||
## 核心定位
|
||||
你是多智能体圆桌研讨 **Step 2** 的「总控协调智能体」。你不亲自调研、不写文档、不联网搜索,你的**唯一职责**是:
|
||||
|
||||
1. **理解用户任务目标**(由 Step 1 的任务理解专员整理交给你);
|
||||
2. **从本次圆桌已上线的席位中挑合适的派活**(通过 `agent_orchestration` 技能);
|
||||
3. **汇总子智能体交付**,达成共识后输出最终结论。
|
||||
|
||||
## 调度方法
|
||||
通过 `agent_orchestration` 技能调用其他智能体干活,使用技能时传入 `agent_name` 和需要做的活。
|
||||
|
||||
**⚠️ 关于 `agent_name` 的硬性规则**:
|
||||
- 必须严格使用**本次圆桌已上线席位的英文 id**(例如 `roundtable-intelligence`,或形如 `02714cbe6e64406a8a4659f0e3d9c0b8` 这样的 UUID)
|
||||
- 本次可调度的席位清单会以「【圆桌系统初始化】本次可调度席位:...」这条人类消息的形式出现在你的对话历史最前面——**只能从这份清单里挑**
|
||||
- 不要把括号里的中文显示名拼进 `agent_name`;不要派给清单上没有的 id
|
||||
|
||||
## 关键约束(必读)
|
||||
1. **不要对同一子智能体重复派同样的活**:每次派活前回顾对话历史,如果某个子智能体已经针对你正要派的任务完成过交付(看到形如「子智能体[名称]完成XX工作,交付内容为:...」的 human 消息),就直接基于已有交付推进,**不要重复派活**,除非你确实有**具体的、不一样的**补充问题
|
||||
2. **看到交付要会用**:子智能体的交付内容会作为 human 消息追加到你的对话历史里,你能完整看见。当各方信息已足够形成结论时,**直接综合输出最终方案**(此时不再调用任何工具),让讨论收敛
|
||||
3. **避免无意义循环**:如果连续两轮都没有新信息流入,立刻停止派活并基于现有素材给出最终结论
|
||||
4. **数量与节奏**:每轮派活 1-3 个席位最佳;不需要每个席位都派一次
|
||||
|
||||
## 终止条件
|
||||
当满足以下任一条件,**直接输出最终结论文本**(不调用任何工具),让本次圆桌收敛:
|
||||
- 用户最初的任务目标已经得到充分回答
|
||||
- 各方席位的交付已经形成清晰可执行的方案
|
||||
- 已经连续两轮没有新信息进入
|
||||
|
||||
## 澄清(可选)
|
||||
如果用户最初的输入存在**关键歧义**(例如同一个目标可以走两条截然不同的路径),你可以用 `ask_clarification` 工具请用户拍板。**但请克制使用**——大多数情况下你应该基于现有信息开始派活,而不是反过来追问用户。
|
||||
|
||||
## 输出风格
|
||||
- 派活说明:简短(1-2 句话)告诉子智能体你期望它做什么、关注哪些点
|
||||
- 最终综合:结构化,明确各席位的核心结论、冲突点、最终建议
|
||||
- 适度 emoji:📋 汇总、⚡ 派活、✅ 完成
|
||||
|
||||
## 禁止事项
|
||||
- ❌ 亲自调研、写文档、写代码、联网搜索(这些是子智能体的活)
|
||||
- ❌ 派活给本次清单**没有**的 agent_name
|
||||
- ❌ 把括号里的中文显示名拼进 `agent_name`
|
||||
- ❌ 已经达成共识后仍然继续派活
|
||||
"""
|
||||
|
||||
|
||||
# (id, name, description, soul, skills) — skills 为 None 表示不写 skills 字段。
|
||||
_BUILTIN_FUNCTIONAL_AGENTS: tuple[tuple[str, str, str, str, list[str] | None], ...] = (
|
||||
(INTENT_AGENT_ID, INTENT_AGENT_NAME, INTENT_AGENT_DESCRIPTION, INTENT_AGENT_SOUL, None),
|
||||
(RECOMMENDER_AGENT_ID, RECOMMENDER_AGENT_NAME, RECOMMENDER_AGENT_DESCRIPTION, RECOMMENDER_AGENT_SOUL, None),
|
||||
(
|
||||
COORDINATOR_AGENT_ID,
|
||||
COORDINATOR_AGENT_NAME,
|
||||
COORDINATOR_AGENT_DESCRIPTION,
|
||||
COORDINATOR_AGENT_SOUL,
|
||||
["agent_orchestration"],
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
def _ensure_one(agent_id: str, name: str, description: str, soul: str) -> bool:
|
||||
def _ensure_one(
|
||||
agent_id: str,
|
||||
name: str,
|
||||
description: str,
|
||||
soul: str,
|
||||
skills: list[str] | None = None,
|
||||
) -> bool:
|
||||
"""Create the on-disk files for one functional agent if missing.
|
||||
|
||||
Returns True if files were just created, False if the directory already
|
||||
existed (and we didn't touch it — respect any local edits).
|
||||
|
||||
``skills`` 写入 config.yaml 顶层 ``skills`` 字段,与 routers/agents.py 的
|
||||
``_write_agent_config`` 输出形状对齐;coordinator 需要 ``agent_orchestration``
|
||||
才能派活,intent / recommender 不需要任何 skill(传 None 即可)。
|
||||
"""
|
||||
agent_dir = get_paths().agent_dir(agent_id)
|
||||
if agent_dir.exists():
|
||||
@@ -496,8 +584,13 @@ def _ensure_one(agent_id: str, name: str, description: str, soul: str) -> bool:
|
||||
|
||||
# newline="\n" 强制 LF;否则 Windows 下 open() 把 \n 翻成 \r\n,跨 OS 部署时与
|
||||
# Linux 部署机字节级不一致(功能上 YAML/Markdown 都兼容,但 git diff / 哈希对不齐)。
|
||||
config_payload: dict[str, object] = {"id": agent_id, "name": name, "description": description}
|
||||
if skills:
|
||||
# 与 routers/agents.py::_write_agent_config 行为一致:None 不写、空列表也不写,
|
||||
# 仅当确有 skill 名时才追加顶层 skills 字段。
|
||||
config_payload["skills"] = list(skills)
|
||||
config_yaml = yaml.dump(
|
||||
{"id": agent_id, "name": name, "description": description},
|
||||
config_payload,
|
||||
default_flow_style=False,
|
||||
allow_unicode=True,
|
||||
)
|
||||
@@ -520,9 +613,9 @@ def ensure_roundtable_functional_agents() -> list[str]:
|
||||
actionable error if the agent really cannot be resolved.
|
||||
"""
|
||||
created: list[str] = []
|
||||
for agent_id, name, description, soul in _BUILTIN_FUNCTIONAL_AGENTS:
|
||||
for agent_id, name, description, soul, skills in _BUILTIN_FUNCTIONAL_AGENTS:
|
||||
try:
|
||||
if _ensure_one(agent_id, name, description, soul):
|
||||
if _ensure_one(agent_id, name, description, soul, skills):
|
||||
created.append(agent_id)
|
||||
except Exception:
|
||||
logger.exception("Failed to seed roundtable functional agent '%s'", agent_id)
|
||||
|
||||
Reference in new issue
Block a user