圆桌 Step2：固定协调员单例、优化调度性能、修正研讨中状态

将 roundtable-coordinator 改为内置单例避免重复创建；legacy sync 加 TTL 减少 runs/stream 延迟；前端仅当前发言者显示研讨中。

Co-authored-by: Cursor <cursoragent@cursor.com>

frontend-web/docs/multi-agent-backend-dev.md

@@ -12,8 +12,8 @@
 
 - 三个圆桌 Router（`intent / recommend / multi_agent`）**通过 httpx ASGITransport 进程内直调本机 ASGI app**，复用既有 `/api/threads`、`/api/agents`、`/api/threads/{id}/runs/stream` 路由——**不走 TCP / 不经过网络栈**。所有 client 都由 `multi_agent._make_loopback_client(request)` 工厂统一构造。
 - 历史包袱：早期实现走 `httpx.AsyncClient(trust_env=False)` + `127.0.0.1:<port>`，遇到开发机 `HTTP_PROXY` / `HTTPS_PROXY` 时仍可能把回环走代理（症状 `headers_in=42.160s`）。**改用 ASGITransport 后此问题不再存在**，相关 `trust_env=False` workaround 全部移除。
-- **席位 agent 持久注册**（磁盘 `.deer-flow/agents/` + `_sync_legacy_agents`），**协调智能体每次新建**（命名 `roundtable-coordinator-{timestamp36}`，DB 累积，需后续 GC）。
-- **`.deer-flow/` 整个目录被 git ignore**（仓库根 `.gitignore` 第 64 / 74 行），`git clone` 后内置 agent 目录在部署机上**不会存在**——任何环境都必须把 `roundtable-intent` + `roundtable-recommender` 两个**功能型 agent** 持久化进发布物，否则 `/api/intent/stream` 报 500。**互联网 demo 还需要 6 个示例研讨席位**（`roundtable-intelligence` 等），**内网部署用客户自有 agent 替代**这些席位，无需打包。详见 §11.7。
+- **席位 agent 持久注册**（磁盘 `.deer-flow/agents/` + `_sync_legacy_agents`），**协调智能体也是持久单例**（id 固定为 `roundtable-coordinator`，与 intent/recommender 同样走 `_roundtable_seed.ensure_roundtable_functional_agents()` 缺失自动落地）。2026-05 之前曾按 `roundtable-coordinator-{timestamp36}` 每会话新建并把动态席位列表写进 SOUL，导致 `.deer-flow/agents/` 累积大量壳目录；改造后 SOUL 是静态通用版本，「本次可调度席位列表」由 `multi_agent.init` 在 coordinator thread 创建后以 human 消息追加到对话历史，leader run 每轮都能看到。
+- **`.deer-flow/` 整个目录被 git ignore**（仓库根 `.gitignore` 第 64 / 74 行），`git clone` 后内置 agent 目录在部署机上**不会存在**。但功能型 agent 现在通过 `_roundtable_seed.ensure_roundtable_functional_agents()` **自动落地**（首次任何 intent/recommend/multi-agent 路由调用都会触发），因此**新部署不再需要手动准备** `roundtable-intent` / `roundtable-recommender` / `roundtable-coordinator` 三个目录——它们都是 seeder 自动写盘的。**互联网 demo 仍需要 6 个示例研讨席位**（`roundtable-intelligence` 等），**内网部署用客户自有 agent 替代**这些席位，无需打包。详见 §11.7。
 - **`init` 是 SSE 而非一次性 JSON**：用 `asyncio.as_completed` 按真实完成顺序推送 `seat_ready`，前端因此能逐个点亮席位。
 - **`init_done.thread_ids` 包含协调智能体自身**（`agent_threads[main_agent_name] = coord_thread`），前端 Step 3 列文件时需自行过滤。
 - **澄清协议统一**：Step 1 与 Step 2 leader 都借 `ask_clarification` + 终态 `clarification` 帧驱动同一套选项卡片组件；`allow_multiple` 默认 false（单选、点击即发送）。
@@ -282,33 +282,50 @@ offline-backend-20260512/backend/
 请求体:
 {
   "agent_names":     ["roundtable-intelligence", ...],   // 用户选的席位 id
-  "main_agent_name": "roundtable-coordinator-xxx",       // 当次总控 id,前端生成
-  "model":           "deepseek-chat"                     // 可选,写入 coordinator agent
+  "main_agent_name": "<可选,已废弃>",                       // 历史字段;2026-05 改造后后端忽略,统一用 COORDINATOR_AGENT_ID
+  "model":           "deepseek-chat"                     // 可选;不传由 lead_agent 回退到 config.yaml models[0]
 }
 ```
 
+**协调智能体改造说明（2026-05）**：以前 `main_agent_name` 由前端用时间戳生成
+（`roundtable-coordinator-${Date.now().toString(36)}`），后端 `_create_coordinator_direct`
+把动态拼接的席位列表 SOUL 写盘并入 DB，导致 `.deer-flow/agents/` 越用越多。改造后：
+
+- **id 固定**：`COORDINATOR_AGENT_ID = "roundtable-coordinator"`（前后端常量必须保持一致）；
+- **缺失自动落地**：路由入口调 `ensure_roundtable_functional_agents()`，与 intent/recommender 共用同一套 seeder；
+- **席位列表运行时注入**：init 创建好 coordinator thread 之后，立刻通过 `_append_thread_message` 把「【圆桌系统初始化】本次可调度席位:…」作为 human 消息追加到 thread 历史最前面，leader run 每轮都能看到；
+- **`main_agent_name` 入参保留为向后兼容**：旧 client 仍可传，后端只是日志里看到不会用它创建新 agent。
+
 **早期校验**（同步抛 HTTP 4xx，**不**进 SSE）：
 
 - `agent_names` 必须非空
-- 每个 `agent_names` 元素 + `main_agent_name` 都需通过 `_AGENT_ID_PATTERN = ^[A-Za-z0-9_-]+$`（用 `_validate_agent_id` 提前 400；上游若收到不合规 id 会抛 422，提前拦更友好）
+- 每个 `agent_names` 元素需通过 `_AGENT_ID_PATTERN = ^[A-Za-z0-9_-]+$`（用 `_validate_agent_id` 提前 400；上游若收到不合规 id 会抛 422，提前拦更友好）
 - 所有 id 都 `.lower()` 后比较 / 存储
+- `main_agent_name` 入参不再做校验（被忽略，统一用 `COORDINATOR_AGENT_ID` 常量）
 
-**SSE 内部流程**：
+**SSE 内部流程**（2026-05 单例改造后）：
 
 ```
+ensure_roundtable_functional_agents()
+  // 路由入口:保证 .deer-flow/agents/roundtable-coordinator/ 存在
+  // 缺失时由 _roundtable_seed.COORDINATOR_AGENT_SOUL 落地静态 SOUL
+
 asyncio.as_completed(各席位 _prepare_sub_agent)
   每完成一个 → data: {"event":"seat_ready","agent_name","thread_id","display_name","description"}
   (按真实完成顺序,先完成先发,前端因此能逐个点亮)
 
 异常时:取消所有未完成的 task,避免泄露到 AsyncClient close 之后
 
-协调智能体:
-  POST /api/threads → coord_thread
-  POST /api/agents
-    skills=["agent_orchestration"]
-    soul=动态拼接(本次 init 的席位列表 + 派活规则)
-    id=main_agent_name(前端生成的 roundtable-coordinator-<ts36>)
+协调智能体(单例):
+  main_agent_name = COORDINATOR_AGENT_ID   # 固定常量,不再每次新建 agent
+  coord_thread = _create_thread_direct(...)  # 仍然每次新 thread,会话独立
   agent_threads[main_agent_name] = coord_thread     // ⚠️ thread_ids 含 coordinator 自身
+
+  # 通过 HTTP loopback append 一条 human 消息,把本次席位清单写入对话历史:
+  #   "【圆桌系统初始化】本次研讨可调度的席位清单如下..."
+  # leader run 每轮都能从对话历史里读到,等效于旧版动态 SOUL 的作用。
+  _append_thread_message(seed_client, ..., coord_thread, seat_introduction)
+
   → data: {"event":"coordinator_ready","main_agent_name","thread_id"}
 
 → data: {"event":"init_done","main_agent_name","thread_ids":{...}}
@@ -316,28 +333,26 @@ asyncio.as_completed(各席位 _prepare_sub_agent)
 失败 → data: {"event":"error","detail":"..."}
 ```
 
-**协调智能体创建幂等**：若 `_create_agent` 返回 (False, "exists ...")（同名 agent 已存在）则继续往下走，不报错。注意这里的「已存在」会复用历史 agent 的 SOUL（与本次动态拼接的不同），通常只在前端用同一个时间戳跑过两遍时触发。
+**协调智能体单例 SOUL**（磁盘上唯一一份，见 `_roundtable_seed.COORDINATOR_AGENT_SOUL`）：
 
-**协调智能体 SOUL**（动态拼接，与席位列表一起写入）：
+通用协调规则，**不含**席位列表。模型派活时从对话历史最前面的「【圆桌系统初始化】…」消息读取本次可用 agent_name。仍然强调英文 id（避免把中文显示名拼进 `agent_name`），靠后端 `_strip_display_suffix` 兜底（详见 §6.4）。
+
+**席位清单注入消息形状**（init 阶段写入 coordinator thread）：
 
 ```
-#核心定位:
-用途:根据用户的任务目标,调用其他智能体干活,只负责协调汇总,
-当你觉得已有信息支持回答用户问题时候,停止调度,并输出最后的结果
-
-#调度方法:
-通过使用 agent_orchestration 技能调用其他智能体干活,使用技能时传入
-agent_name 和需要做的活。
-⚠️ agent_name 必须严格使用下方列出的英文 id(例如 roundtable-intelligence),
-   不要把括号里的中文显示名拼进 agent_name 里。
-
-#可调度智能体:
-- agent_name: roundtable-intelligence(情报收集):<description>
-- agent_name: roundtable-environment(环境评估):<description>
+【圆桌系统初始化】本次研讨可调度的席位清单如下,请严格按 agent_name 通过 agent_orchestration 技能派活,不要派给不在清单内的 agent:
+- agent_name: roundtable-intelligence（情报收集）：<description>
+- agent_name: roundtable-environment（环境评估）：<description>
 ...
 ```
 
-中文显示名通过 `GET /api/agents/{id}` 取 `name`、描述取 `description`。**强调英文 id** 是因为部分模型会把整段 `roundtable-x（中文）` 当 `agent_name` 塞回来，靠后端 `_strip_display_suffix` 兜底（详见 §6.4）。
+中文显示名通过 `_get_agents_batch_direct` 一次 DB 查询取 `name`、描述取 `description`。
+
+**单例 agent 的几个语义保障**：
+
+1. **agent 落地幂等**：`_ensure_one` 检查目录是否存在，存在就 no-op，不覆盖运维手改的 SOUL；
+2. **席位列表 append 失败不阻断**：`_append_thread_message` 包在 try/except 里，失败只记 warning，leader run 仍能跑（只是看不到席位清单，可能派活到错的 id，由 `_validate_agent_id` 在 run/stream 里报错）；
+3. **`_create_coordinator_direct` 已删除**：旧函数已移除（2026-05 改造），避免后续维护者误调；如果你正在 review 旧 PR 看到这个函数，那是 pre-rebase 版本。
 
 ### 6.2 `/run/stream` — `agent_type = "leader"`（`_leader_run`）
 
@@ -609,13 +624,20 @@ httpx.AsyncClient(
 
 **已废止的 `trust_env=False` workaround**：旧版本走 `127.0.0.1:<port>` 真实 HTTP，需要 `trust_env=False` 阻止 httpx 读 `HTTP_PROXY` 把回环也走代理（症状日志 `headers_in=42.160s`）。改 ASGITransport 后这个问题在物理上已不存在——根本没走网络栈。
 
-### 9.2 协调智能体每次新建
+### 9.2 协调智能体单例（2026-05 改造）
 
-`main_agent_name` 形如 `roundtable-coordinator-{timestamp36}`，会话隔离；长期会累积 agent 目录（实际仓库已有数十个 `roundtable-coordinator-mp*`），需后续 GC 策略：
+历史实现 `main_agent_name = roundtable-coordinator-{timestamp36}`，会话隔离，但长期会累积 agent 目录（仓库里曾积累几十个 `roundtable-coordinator-mp*` 壳目录）。2026-05 改造选用上方决策 §9.2 选项 C 的本质：**把 coordinator 实例化为「内置 + 静态 SOUL + 运行时注入席位列表」**，固定 id `roundtable-coordinator`，与 `roundtable-intent` / `roundtable-recommender` 同样走 `ensure_roundtable_functional_agents()` 缺失自动落地。
 
-- 选项 A：定时任务清理 N 天前无活跃 thread 的 coordinator agent
-- 选项 B：每次创建前 LRU 清理（注意：跨服务实例难协调）
-- 选项 C：把 coordinator 实例化为「内置 + 动态 SOUL」复用同一个 id
+实现要点：
+
+- **磁盘 SOUL 是通用版本**：不含本次席位列表，只规定协调规则、工具用法、终止条件；
+- **席位列表运行时注入**：init 创建 coordinator thread 后立刻 `_append_thread_message` 写入一条 human 消息（"【圆桌系统初始化】…"），位置在对话历史最前面，leader run 每轮自然读到；
+- **`_create_coordinator_direct` 已删除**：不再有"每次创建"路径。
+
+**遗留 `roundtable-coordinator-*` 目录的处理**：仓库可能仍有几十个历史时间戳壳目录。改造后**不会**再生成新的，但旧目录目前不自动清理（避免破坏可能仍存在的旧草稿引用）。运维可通过：
+
+- 在 admin agents 管理页逐个 DELETE；
+- 或写一次性脚本扫描 `.deer-flow/agents/roundtable-coordinator-*` 并删除目录 + DB 记录（注意不要删除 `roundtable-coordinator` 本体）。
 
 ### 9.3 澄清协议统一
 
@@ -705,15 +727,22 @@ offline-backend-20260512/backend/.deer-flow/*
 
 | Agent | 角色 | 是否必须打包发布 |
 |-------|------|------------------|
-| `roundtable-intent` | **功能型**：Step 1 任务理解，所有部署都用它 | ✅ **必须**（任何环境） |
-| `roundtable-recommender` | **功能型**：Step 1→2 之间从候选池里挑推荐，所有部署都用它 | ✅ **必须**（任何环境） |
+| `roundtable-intent` | **功能型**：Step 1 任务理解，所有部署都用它 | ✅ seeder 自动落地（无需手工打包） |
+| `roundtable-recommender` | **功能型**：Step 1→2 之间从候选池里挑推荐，所有部署都用它 | ✅ seeder 自动落地（无需手工打包） |
+| `roundtable-coordinator` | **功能型单例**：Step 2 总控协调，2026-05 起为单例（id 固定） | ✅ seeder 自动落地（无需手工打包） |
 | `roundtable-intelligence` | 示例研讨席位（情报收集） | ⚠️ **互联网 demo 用**，内网不需要 |
 | `roundtable-environment` | 示例研讨席位（环境评估） | ⚠️ 同上 |
 | `roundtable-solution-design` | 示例研讨席位（方案设计） | ⚠️ 同上 |
 | `roundtable-risk-review` | 示例研讨席位（风险审查） | ⚠️ 同上 |
 | `roundtable-execution-plan` | 示例研讨席位（执行规划） | ⚠️ 同上 |
 | `roundtable-summary` | 示例研讨席位（总结陈述） | ⚠️ 同上 |
-| `roundtable-coordinator-*` | 协调智能体壳，每次会话动态新建 | ❌ **不打包**（运行时生成） |
+| `roundtable-coordinator-*`（带后缀） | 2026-05 之前每次会话动态新建的临时壳 | ❌ **遗留**（仓库可能仍有几十个旧目录，新版本不再生成；运维按需清理） |
+
+**关键变化（2026-05）**：三个功能型 agent（intent / recommender / coordinator）现在都由
+``_roundtable_seed.ensure_roundtable_functional_agents()`` **自动落地**——任何 intent /
+recommend / multi-agent 路由的入口都会触发，首次请求时缺什么补什么。所以**新部署的
+机器 `git clone` 后既不需要手工拷目录、也不需要走下文的 `.gitignore` 白名单方案**，
+SOUL 改动跟着 Python 代码走 git review 即可。
 
 **关键区分**：
 - `roundtable-intent` / `roundtable-recommender` 是**圆桌功能本身的一部分**——没有它们，整个 Step 1 + 推荐流程跑不起来，跟客户业务无关