diff --git a/docs/draft.md b/docs/draft.md index d875660..ecce051 100644 --- a/docs/draft.md +++ b/docs/draft.md @@ -132,7 +132,68 @@ Orchestrator.run(scheme, task) Task Output + Metrics Log ``` -### 3.4 人类介入机制(Human-in-the-Loop Gate) +### 3.4 Agent 间通信机制(MessageBus) + +**核心原则:拓扑决定路由规则,不决定通信接口。** Agent 只调用 `send` / `receive`,由 Orchestrator 持有路由表按拓扑转发,Agent 本身不感知自己处于哪种拓扑。 + +#### 统一消息结构 + +```python +@dataclass +class Message: + id: str + from_agent: str + to_agent: str # 单播;广播由 Orchestrator 展开为多条单播 + msg_type: str # task | result | critique | approval | human_input + content: str + metadata: dict # round, confidence, milestone 等附加信息 +``` + +#### MessageBus 实现 + +每个 Agent 拥有独立的 inbox 队列,Orchestrator 负责将消息投递到正确的队列: + +```python +class MessageBus: + def __init__(self): + self.queues: dict[str, asyncio.Queue] = {} + + async def send(self, msg: Message): + await self.queues[msg.to_agent].put(msg) + + async def receive(self, agent_id: str) -> Message: + return await self.queues[agent_id].get() +``` + +#### 不同拓扑下的路由规则 + +拓扑的差异只体现在 Orchestrator 如何填写 `to_agent`,消息格式和队列机制完全相同: + +| 拓扑 | 路由规则 | +|------|---------| +| pipeline | 按顺序转发,to_agent 固定为下一个节点 | +| star | Coordinator 广播任务给所有 worker;收集全部 result 后合并 | +| debate | 每轮将所有 Agent 的输出广播给其他所有 Agent | +| parallel | Orchestrator 同时广播,等 all result 到齐后 merge | + +#### Human Gate 作为特殊 Agent + +Human Gate 实现与普通 Agent 完全相同的 `receive` / `send` 接口,内部不调用 LLM,而是阻塞等待人类输入: + +```python +class HumanGateAgent: + async def run(self, msg: Message) -> Message: + if not self.should_trigger(msg): # 触发条件由 Orchestrator 在路由时判断 + return Message(msg_type="approval", content="auto_approved") + + display(msg.content) # 展示给人类(CLI 或 Web UI) + action, feedback = await self.wait_for_human_input() # 阻塞等待 + return Message(msg_type=action, content=feedback) +``` + +触发条件判断在 Orchestrator 路由层完成——不满足则跳过 Human Gate 节点,满足才投递消息到其 inbox。这样 Human Gate 可以插入任意拓扑的任意位置,不影响其他 Agent 的通信逻辑。 + +### 3.5 人类介入机制(Human-in-the-Loop Gate) 对应 GQM Q5(M20-M23),人类介入点可配置触发条件: @@ -151,7 +212,7 @@ Task Output + Metrics Log 平台记录每次介入的时间戳、操作类型、修改量(用于计算 HIF、HTC、HER、AR)。 -### 3.5 评测采集层(Metrics Collector) +### 3.6 评测采集层(Metrics Collector) 自动从运行日志中计算 GQM 定义的 23 项指标: