## 🧰 專業框架與方法論

### OpenClaw 溝通架構核心概念

#### 1. 代理人分類（Agent Taxonomy）

| 類型 | 職責 | 溝通特徵 |
|------|------|----------|
| **Orchestrator** | 流程編排、路由決策 | 廣播、點對多 |
| **Specialist** | 領域專精任務執行 | 點對點、請求-回應 |
| **Router** | 意圖分類與轉發 | 單入多出 |
| **Guardian** | 安全審核、合規檢查 | 攔截式、同步阻塞 |
| **Observer** | 日誌、指標、告警 | 訂閱式、非同步 |
| **Human Proxy** | 人機協作介面 | Escalation、Approval |

#### 2. 溝通拓撲模式

**Hub-and-Spoke（星型）**
- 適用：≤5 代理人、中央編排場景
- 優點：簡單、易觀測、單點控制
- 缺點：Orchestrator 成為瓶頸

**Peer-to-Peer（點對點）**
- 適用：對等協作、去中心化決策
- 優點：彈性高、無單點故障
- 缺點：複雜度高、難以全域觀測

**Hierarchical（層級式）**
- 適用：大型系統、職責分層明確
- 優點：職責清晰、可分段擴展
- 缺點：跨層溝通延遲

**Blackboard（黑板模式）**
- 適用：多代理人共享知識、迭代求解
- 優點：鬆耦合、知識累積
- 缺點：需要強大的 Shared Context 管理

**Event-Driven（事件驅動）**
- 適用：高吞吐、非同步解耦
- 優點：可擴展、容錯性好
- 缺點：除錯複雜、最終一致性

#### 3. Message Envelope 標準結構

```json
{
  "envelope": {
    "message_id": "uuid-v4",
    "correlation_id": "uuid-v4",
    "trace_id": "uuid-v4",
    "span_id": "uuid-v4",
    "timestamp": "ISO-8601",
    "version": "1.0.0",
    "source_agent": "agent-name",
    "target_agent": "agent-name | broadcast",
    "message_type": "request | response | event | error",
    "qos": "at-least-once",
    "ttl_ms": 30000,
    "idempotency_key": "optional-uuid"
  },
  "payload": {},
  "metadata": {
    "tenant_id": "optional",
    "session_id": "uuid-v4",
    "priority": "normal | high | critical"
  }
}
```

#### 4. Handoff Protocol 設計模式

**Direct Handoff**：Agent A 完成後直接呼叫 Agent B
- 適用：線性流水線、低延遲

**Queued Handoff**：透過 Message Queue 非同步交接
- 適用：削峰填谷、長時間任務

**Competitive Handoff**：多個 Specialist 競爭處理
- 適用：負載均衡、容錯

**Supervised Handoff**：Orchestrator 監督交接品質
- 適用：高可靠性場景

#### 5. 狀態與記憶分層

| 層級 | 儲存 | TTL | 用途 |
|------|------|-----|------|
| **Ephemeral** | In-Memory | Session | 當前對話上下文 |
| **Session** | Redis/Cache | 24h | 跨回合狀態 |
| **Persistent** | DB/Vector Store | 永久/可配置 | 使用者偏好、歷史 |
| **Shared Blackboard** | Event Store | 任務週期 | 多代理人協作狀態 |

#### 6. 失敗處理框架

```
錯誤偵測 → 分類 → 重試策略 → 降級 → 告警 → DLQ
```

| 錯誤類型 | 重試 | 降級 |
|----------|------|------|
| Timeout | 指數退避 3 次 | 返回部分結果 + 標記 incomplete |
| Rate Limit | 等待 + Jitter | 排隊 + 通知使用者 |
| Validation Error | 不重試 | 返回具體欄位錯誤 |
| Agent Unavailable | 熔斷 30s | 切換備援 Agent |
| Fatal Error | 不重試 | Escalate to Human |

#### 7. ADR 模板

```markdown
# ADR-NNN: [決策標題]

## 狀態
提議中 | 已接受 | 已棄用

## 背景
[問題描述]

## 決策
[選擇的方案]

## 替代方案
1. [方案 A] — 拒絕原因
2. [方案 B] — 拒絕原因

## 後果
- 正面：[...]
- 負面：[...]

## 可觀測性影響
[Trace/Metric 變更]
```

#### 8. 可觀測性三支柱

- **Logging**：結構化 JSON Log，含 trace_id 串聯
- **Metrics**：`agent_request_duration_ms`、`handoff_success_rate`、`dlq_depth`
- **Tracing**：OpenTelemetry 相容的 Span 傳遞

### 設計工作流程（7 步驟）

1. **Stakeholder Mapping** — 識別代理人角色與人類參與點
2. **Topology Selection** — 比較 2-3 種拓撲，產出 ADR
3. **Contract Definition** — 定義所有 Message Schema
4. **Flow Design** — 繪製序列圖，標註同步/非同步
5. **Resilience Design** — 失敗矩陣 + Circuit Breaker 配置
6. **Observability Design** — Log/Metric/Trace 規格
7. **Implementation Checklist** — 分 Phase 的工程任務清單