## 🛠️ 專業框架與方法論

### Ironclaw 通訊架構原則（ACAP）

**A** — **Atomic Messages**：訊息不可再分則不應合併；複合意圖拆為 saga steps。
**C** — **Contract-First**：OpenAPI/JSON Schema 先於 prompt 設計。
**A** — **Auditable**：每步有 causation_id，支援 distributed tracing。
**P** — **Partitioned Context**：context 按職責分片，禁止 global prompt soup。

### 通訊模式選型矩陣

| 模式 | 適用場景 | 延遲 | 複雜度 | 可觀測性 |
|------|----------|------|--------|----------|
| **Orchestrator-Worker** | 明確 DAG 工作流 | 中 | 低 | 高 |
| **Pub/Sub Event Bus** | 鬆耦合、多訂閱者 | 低–中 | 中 | 高 |
| **Blackboard** | 探索性推理、共識形成 | 高 | 高 | 中 |
| **Hierarchical Delegation** | 大型任務分解 | 中–高 | 中 | 高 |
| **Peer Mesh** | 對等協商、少見 | 變動大 | 很高 | 低 |

### 標準訊息封包（Ironclaw Envelope）
```json
{
  "envelope_version": "1.0",
  "message_type": "task.delegate",
  "schema_version": "2024-06-01",
  "message_id": "uuid-v7",
  "correlation_id": "uuid-v7",
  "causation_id": "uuid-v7|null",
  "sender": { "agent_id": "orchestrator.main", "instance_id": "pod-abc" },
  "recipient": { "agent_id": "worker.research", "routing_key": "capability:web_research" },
  "timestamp": "ISO-8601",
  "deadline_ms": 30000,
  "retry_policy": { "max_attempts": 3, "backoff": "exponential" },
  "trace_context": { "trace_id": "...", "span_id": "..." },
  "payload": {},
  "metadata": { "priority": "normal", "idempotency_key": "..." }
}
```

### Handoff 協議（7-Step）
1. **Intent Declaration** — 發送方宣告目標與成功標準
2. **Capability Match** — 接收方確認能力與資源
3. **Context Package** — 傳遞最小必要 context（含 redaction log）
4. **Execution** — 附 deadline 與 heartbeat
5. **Result Envelope** — 結構化結果 + confidence + evidence refs
6. **Ack/Nack** — 發送方確認或請求修正
7. **Archive** — 寫入 audit store，更新 saga state

### MCP 整合分層
- **L1 Gateway MCP**：認證、rate limit、schema 驗證
- **L2 Domain MCP**：業務工具（CRM、DB、搜索）
- **L3 Sandbox MCP**：高風險操作隔離執行

代理僅透過 L1 發起 tool call；禁止 worker 直連 L3。

### 可靠性模式庫
- **Saga + Compensation**：長事務分散式回滾
- **Outbox Pattern**：訊息與狀態原子寫入
- **Circuit Breaker**：連續失敗 → 開路 → 半開探測
- **Bulkhead**：按 agent pool 隔離資源
- **Poison Message Handler**：超過 max_delivery → DLQ + alert

### 可觀測性標準 Metrics
- `agent_message_latency_p99`
- `handoff_success_rate`
- `schema_validation_failure_total`
- `saga_compensation_triggered_total`
- `context_token_bytes_histogram`

### 參考架構分層
```
┌─────────────────────────────────────┐
│  Human / API Gateway                │
├─────────────────────────────────────┤
│  Orchestrator (Ironclaw Core)       │
│  - routing, saga, policy engine     │
├─────────────────────────────────────┤
│  Agent Runtime Pool                 │
│  - role-bound workers + memory      │
├─────────────────────────────────────┤
│  Message Bus + Contract Registry    │
├─────────────────────────────────────┤
│  MCP Gateway + Tool Adapters        │
├─────────────────────────────────────┤
│  Observability (OTel + Audit Log)   │
└─────────────────────────────────────┘
```