## 🧰 專業框架與方法論

### 溝通拓撲模式庫（Topology Pattern Catalog）

| 模式 | 適用場景 | 關鍵風險 |
|------|----------|----------|
| **Central Orchestrator** | 任務分解、嚴格流程控制、高可觀測性需求 | 單點故障、Planner Token 膨脹 |
| **Supervisor-Worker** | 專業分工明確、子任務可並行 | Worker 結果整合複雜度 |
| **Blackboard / Shared State** | 多代理人協作同一複雜問題、需共享累積知識 | 狀態一致性、競爭寫入 |
| **Pub/Sub Event Bus** | 鬆耦合、事件驅動、多訂閱者 | 順序保證、Exactly-once 難題 |
| **Pipeline / Chain** | 線性資料轉換（ETL、內容生產流水線） | 錯誤級聯、難以並行 |
| **Peer Mesh / Debate** | 需要多視角驗證、共識達成 | 收斂時間、成本倍增 |
| **Router / Intent Dispatcher** | 入口分流、動態選擇 Specialist | 路由準確率、冷啟動 |

### 訊息信封標準（Message Envelope Standard）

```json
{
  "envelope": {
    "schema_version": "1.0.0",
    "message_id": "uuid-v4",
    "correlation_id": "uuid-v4",
    "trace_id": "uuid-v4",
    "timestamp": "ISO-8601",
    "sender": {
      "agent_id": "string",
      "role": "string",
      "model": "string"
    },
    "recipient": {
      "agent_id": "string",
      "routing_key": "optional"
    },
    "intent": "TASK_ASSIGN | RESULT_RETURN | CLARIFY | ESCALATE | HEARTBEAT",
    "priority": "LOW | NORMAL | HIGH | CRITICAL",
    "ttl_ms": 30000,
    "reply_to": "optional-queue-or-callback"
  },
  "payload": {},
  "metadata": {
    "retry_count": 0,
    "parent_message_id": "optional"
  }
}
```

### 架構決策紀錄模板（ADR Lite）

```markdown
## ADR-XXX: [決策標題]
- **狀態**: Proposed | Accepted | Deprecated
- **背景**: [為何需要此決策]
- **決策**: [選擇的方案]
- **替代方案**: [曾考慮的其他選項]
- **取捨**: [Gain vs Pain]
- **後果**: [對效能、成本、維運的影響]
```

### 設計流程（Hermes Design Workflow）

```
Phase 0: Discovery
  └─ 盤點 Stakeholders、SLA、合規約束、現有系統

Phase 1: Topology Selection
  └─ 選型 + 繪製 C4 Container / Flow Diagram

Phase 2: Contract Definition
  └─ 定義每條通訊邊的 Request/Response Schema

Phase 3: Resilience Layer
  └─ Timeout、Retry、DLQ、Fallback、Chaos Scenarios

Phase 4: Observability & Ops
  └─ Logging、Tracing、Metrics、Runbook

Phase 5: Evolution Plan
  └─ Versioning、A/B Agent、Canary Routing
```

### 技術棧映射參考

| 需求 | 推薦方案 |
|------|----------|
| 有狀態工作流 | LangGraph, Temporal, AWS Step Functions |
| 角色協作框架 | CrewAI, AutoGen, Microsoft Agent Framework |
| 訊息佇列 | Redis Streams, RabbitMQ, Kafka, AWS SQS |
| 狀態儲存 | Redis, PostgreSQL JSONB, DynamoDB |
| Tracing | OpenTelemetry, LangSmith, Langfuse |
| Schema 驗證 | JSON Schema, Pydantic, Zod |

### 反模式清單（Anti-Patterns）

- **Telephone Game**：代理人層層轉述自然語言，導致語意漂移 → 改用 Structured Handoff
- **God Context**：每次對話傳遞完整歷史 → 改用 Summary + Reference ID
- **Silent Failure**：下游失敗但上游不知情 → 強制 Error Envelope 回傳
- **Tool Sprawl**：所有代理人擁有全部工具 → 依 Role 限制 Tool Manifest
- **Prompt Entanglement**：業務邏輯寫死在 Prompt 而無法版本化 → 抽離為 Config / Policy Layer

### 評估指標（Architecture Health Metrics）

- **E2E Latency P95**：端到端任務完成延遲
- **Handoff Success Rate**：跨代理人交接成功率
- **Context Compression Ratio**：摘要後 Token 節省比例
- **Escalation Rate**：需人工介入比例
- **Loop Detection Count**：循環委派觸發次數