## 🧠 Skills & Frameworks

### 1. IronClaw 通訊思維模型
把系統拆成四層，避免全部邏輯擠在對話循環：

| 層級 | 職責 | 典型元件 |
|------|------|----------|
| Interaction | 人機入口、會話狀態 | Gateway / UI Adapter |
| Coordination | 任務分解、路由、策略 | Orchestrator / Planner / Router |
| Specialists | 領域 Agent、技能執行 | Worker Agents |
| Tools & Data | 外部 API、DB、RAG、執行器 | Tool Broker / Connectors |

**原則**：跨層用穩定 envelope；同層可用較豐富的領域訊息，但禁止 Specialist 任意直連其他 Specialist（除非明確允許的 peer mesh 且有策略守衛）。

### 2. 拓樸決策矩陣

| 模式 | 適用 | 風險 | 緩解 |
|------|------|------|------|
| Hub-and-Spoke（中心協調） | 任務流程清晰、需強治理 | 中心瓶頸、單點故障 | 水平擴展 Orchestrator + 無狀態化 |
| Pub/Sub 事件網 | 多消費者、解耦演進 | 順序與重複消費 | 分區鍵、幂等鍵、消費者組 |
| Hierarchical（層級委派） | 大型組織式 Agent 群 | 層級延遲、責任模糊 | 明確 SLA 與 escalate 規則 |
| Pipeline / Choreography | 固定多階段加工 | 難追全局狀態 | correlation + 狀態投影 |
| Controlled Mesh | 少數對等協作 | 爆炸性連線 | 允許清單 + 策略代理 |

### 3. 標準訊息 Envelope（建議欄位）
```json
{
  "message_id": "ulid-or-uuid",
  "type": "task.assign|task.result|event.progress|control.cancel",
  "version": "1.0.0",
  "timestamp": "ISO-8601",
  "trace_id": "...",
  "correlation_id": "...",
  "causation_id": "...",
  "source": {"agent_id": "...", "role": "orchestrator"},
  "target": {"agent_id": "..."} ,
  "tenant_id": "...",
  "priority": 0,
  "ttl_ms": 30000,
  "idempotency_key": "...",
  "payload": {},
  "error": null
}
```

### 4. 協議設計檢查表
- **語意**：指令 vs 事件 vs 查詢是否分開命名空間
- **同步性**：RPC 風格 vs fire-and-forget vs stream
- **排序**：是否需要 per-entity 順序
- **幂等**：重複投遞是否安全
- **超時層級**：agent 推理 timeout vs 通道 timeout vs 業務 deadline
- **取消**：cancel 是否可傳播、是否可補償
- **背壓**：隊列長度、拒絕策略、降級回應
- **死信**：DLQ 分類、重放工具、告警
- **權限**：誰可發哪類 type、跨租戶是否禁止
- **版本**：header 版本 vs payload schema 版本

### 5. 與 LLM 特性對齊的架構技巧
- **把非確定性關在 Specialist 內**：協議層保持確定、可測。
- **結構化輸出閘道**：Agent 產出先經 schema validator，再進入 bus。
- **工具呼叫中介化**：Tool Broker 統一鑑權、配額、審計，避免每個 Agent 各自握 key。
- **人類在環（HITL）**：審批點作為一等公民訊息類型，而非 ad-hoc 聊天。
- **記憶分層**：工作記憶（session）、情節記憶（task）、長期記憶（store）分通道，避免「全塞 context」。

### 6. 常見反模式（一眼識破）
- 全域共享可寫記憶當通訊媒介
- 無版本的「自由 JSON」互相拋
- Orchestrator 同步串行呼叫所有 Agent 且無超時
- 用聊天歷史當唯一狀態真相
- 錯誤只回自然语言，沒有 machine-readable error code
- 為了「彈性」允許任意 Agent 動態註冊並呼叫任意工具

### 7. 交付物模板
1. **Context & Goals**（SLA、流量、合規）
2. **Role Map**（Agent 清單與禁止事項）
3. **Topology Diagram**（Mermaid）
4. **Message Catalog**（type 表）
5. **Sequence for Happy Path + Failure Path**
6. **Observability Plan**
7. **Security & Tenancy**
8. **Migration / Rollout**
9. **Open Questions**

### 8. 快速決策口訣
> **誰可以對誰說話？說什麼形狀的話？失敗誰負責？怎麼證明發生過？**
四問答不出來，就還不是架構，只是想法。