Coordinator

Coordinator 是用户实际对话的 persona。每个 chat session（web UI、Slack、Telegram、飞书）都属于一个 coordinator 实例。它不是 worker —— 而是驱动对话、决定何时直接回答、何时通过 AgentTool 派发给 specialist 的长生命 ReAct 循环。

身份

字段	取值
Persona name	`default`
能作为 worker spawn 吗	不能 —— agent catalog 排除了 `default`
Session 模型	每个 `(user, chat thread)` 一条长生命 `chat_sessions` 行
工具袋	宽：query_*、AgentTool、SendMessage、TaskStop、redirect stubs
Persona 正文	内置在 manager 镜像里；按组织通过挂载文件覆盖

要全机队改 coordinator 的行为，把自定义 default.md 挂载覆盖内置那个（见 Custom agents）。AgentRegistry.Replace seam 是用户自编 Agent UI 的底座；启动期的覆盖文件走同一条代码路径。

它能直接做什么

coordinator 的工具袋包含所有 manager 作用域的只读 query 工具：

query_promql、query_logql、query_traceql —— 遥测。已知幻觉场景在 coordinator 上以 stub 形式（redirect 到 incident-investigator）出现 —— 见下文。
query_knowledge —— RAG（vault + upload）。
query_incidents、get_incident_detail、query_alert_rules、query_devices —— 告警 / 库存。
query_change_events —— 最近的配置 / 规则 / 设备变更。
expand_topology、find_topology_node —— 服务图谱。
get_active_incidents —— 当前未消化告警。
BC handler 工具 —— 任何组织 / 用户管理员在 UI 上能干的事。

它有意不带主机 shell 或单主机巡检类工具。那些属于 specialist。

控制工具三剑客

只在 coordinator 上的三个特殊工具。它们控制多 Agent 编排，不查任何数据。

`AgentTool`

派发 worker。同步。完整 schema、去重行为、"别派琐事"护栏文档见 Agent 总览。形态：

json

{
  "description": "Find which process is OOM-ing on node-01",
  "subagent_type": "specialist-compute",
  "prompt": "On device_id=7 we saw mem_used_pct=98 at 14:02. Find the top RSS processes and check dmesg for oom-killer hits. The user originally asked: 'who's eating memory on node-01?'"
}

system reminder 把 persona catalog 注入进来，让 LLM 知道有效的 subagent_type 值。reminder 是按 turn 的 —— 长会话里 attention drift 之后，LLM 也不会忘 specialist 都有谁。

`SendMessage`

在不结束 turn 的前提下给用户发一条中间消息。用于 coordinator 想说"我正在派发给 specialist-network —— 稍等"之类的过场。worker 不带这个工具 —— 只有 coordinator 跟用户说话。

IM bridge 用它来更新聊天里那条占位消息（Slack 上 chat.update、Telegram 上 editMessageText、飞书上 PUT /messages）。web UI 用它在最终答案前流式输出中间文本。

`TaskStop`

礼貌地取消一个跑着的 worker。例如用户在派发中途换了话题，跑着的 worker 答案不再相关，coordinator 就 emit TaskStop。

内部调 Runtime.StopWorker，触发 worker 的 context.CancelFunc。worker 在下一次工具调用时看到 ctx.Done()，把 Status 置为 killed。

何时派发 vs 直接答

coordinator 的 persona prompt 写死了规则：

AgentTool 不是默认选项。能用本地工具 1-2 步答出来的，自己答。复杂深挖（需要 5+ 步 / 跨主机 / 跨信号面）才派。

也就是说，只有这种情况才派：

需要深度迭代（5+ 步聚焦巡检），
需要主机侧工具（host_bash、host_probe_*、host_du_summary），或
受益于一份 coordinator 没带的领域专属工具袋。

"node-01 负载多少？" —— coordinator 一次 get_host_load 就直接答（其实是经过 redirect stub 的 AgentTool(specialist-compute)；原理一样）。"order service 一直 502 应该怎么处理？" —— coordinator 派给 incident-investigator。

Redirect stub（反幻觉）

coordinator 的工具袋带 RedirectStub 条目，专门收已知 LLM 会幻觉的工具名（host_bash、host_du_summary、host_restart_service、get_host_load、correlate_incident…）。LLM 选中 stub 名时，stub 返回：

json

{
  "status": "redirect",
  "hint": "This tool is not available in coordinator scope. Re-invoke via AgentTool to dispatch to specialist-disk.",
  "reason": "目录占用分析",
  "suggested_call": "AgentTool(description=\"…\", subagent_type=\"specialist-disk\", prompt=\"<self-contained task>\", background=true)",
  "why_stub_exists": "Coordinator's job is dispatch + triage. Deep-dive tools live on specialist workers; calling them inline is the wrong pattern."
}

没这些 stub 的话，eino 的 graph runtime 会以 [NodeRunError] tool X not found in toolsNode indexes 中止，浪费一整个 turn。有了之后 LLM 从结果学习，下一次迭代用正确的 AgentTool 调用。stub 列表在 CoordinatorRedirectStubs —— 纯数据，新幻觉冒头就往里加。

别把整个 specialist 工具袋影上来

每个 stub 都占用 LLM 可见 schema 列表的一个槽。stub 太多，prompt 预算膨胀，LLM 反而可能把它们当合法候选。只有在 eval 里观察到会幻觉的工具才加 stub。

用户看到什么

每个 turn coordinator 可以：

直接流出 token —— 答案短而自洽。
inline 调只读 query 工具 —— query_incidents、expand_topology、query_knowledge。
通过 AgentTool 派 worker —— SPA 渲染一个 "Agent tile"，期间显示 persona 名 + 1 行 description。worker 最终结果作为 tile 的子项落下。
通过 SendMessage 发中间消息 —— 通常在慢派发落地前（"正在看；spawn specialist-network"）。
通过 TaskStop 停 worker —— 罕见，通常只在用户中途切换话题时。

用户永远看不到 worker 的原始 transcript。coordinator 把 worker 的 Result 合成进自己的回复。

Session 和审计

coordinator session 在 chat_sessions 里 agent_id = "default"、parent_session_id = NULL。
worker session 的 parent_session_id 指向 coordinator 那行。审计 UI 沿这棵树渲染父→子运行。
每次工具调用都有一行 audit_logs，记 LLM 视角的入参和截断的结果（见自观测）。

自定义 coordinator

可以覆盖 coordinator 的 persona 文件。通常想改的地方：

派发指引（你团队对"何时下派"有自己的政策）。
输出语言 / 语气（用通道上的 default_locale；或直接在 persona 正文里钉死）。
派发前 coordinator 想 inline 用的只读工具列表。

不应该改：

agent catalog 块 —— 机器生成。手改无效，下次 reload 就重新生成。
redirect-stub 语义 —— 是代码，不是 persona。
default 这个 name —— runtime 按名查 coordinator。

热加载故事见 Custom agents。

Coordinator ​

身份 ​

它能直接做什么 ​

控制工具三剑客 ​

AgentTool ​

SendMessage ​

TaskStop ​

何时派发 vs 直接答 ​

Redirect stub（反幻觉） ​

用户看到什么 ​

Session 和审计 ​

自定义 coordinator ​