通添加修æ”agent协议

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 项指标：