第 14 課：多代理自動化
學習目標
完成本課程後，您將能夠：
- 設計 Claude Code 的多代理架構
- 實作自動代理協調系統
- 建立代理之間的通訊協定
- 建構自主協作的編排腳本
- 處理代理之間的衝突和解決方案
- 監控和管理多代理工作流程
先決條件
- 完成第 1-13 課 - 完整掌握 Claude Code
- Shell 腳本經驗 - 用於編排腳本
- 系統架構知識 - 瞭解分散式系統
- 進階使用案例 - 需要並行工作的複雜專案
預估時間： 45 分鐘 難度： 進階
瞭解多代理 Claude Code
多代理自動化意味著執行多個 Claude Code 實例，它們自主地協作處理專案的不同方面。
為什麼使用多個代理？
並行化：
單一代理：功能需要 4 小時
├─ 後端：2 小時
├─ 前端：1.5 小時
└─ 測試：30 分鐘
總計：4 小時（循序）
多代理：功能需要 1.5 小時
├─ 後端代理：2 小時（並行）
├─ 前端代理：1.5 小時（並行）
└─ 測試代理：30 分鐘（之後）
總計：2 小時（並行任務最大值 + 相依性）
專業化：
- 資料庫代理：Schema、遷移、優化專家
- API 代理：端點、REST、GraphQL 專家
- 前端代理：React、Vue、UI/UX 專家
- 測試代理：pytest、jest、覆蓋率專家
- 文件代理：技術寫作專家
韌性：
- 如果一個代理失敗，其他代理繼續
- 獨立的錯誤恢復
- 優雅降級
代理架構模式
模式 1：階層式（協調器-工作者）
協調器代理
├─→ 工作者代理 1（後端）
├─→ 工作者代理 2（前端）
└─→ 工作者代理 3（測試）
模式 2：管線（階段式）
代理 1（設計）→ 代理 2（實作）→ 代理 3（測試）→ 代理 4（部署）
模式 3：點對點（協作）
代理 A（後端）←↔→ 代理 B（前端）
↕ ↕
共享狀態（API 契約）
通訊協定
代理需要通訊方式。讓我們從簡單到進階來建構它們。
層級 1：基於檔案的訊息傳遞（最簡單）
工作原理： 代理讀取/寫入檔案進行協調。
設定：
project/
├── .agents/
│ ├── coordinator.md # 協調器狀態
│ ├── backend-status.md # 後端代理狀態
│ ├── frontend-status.md # 前端代理狀態
│ ├── messages.md # 訊息佇列
│ └── shared-state.json # 共享資料
└── src/
實作：
1. 建立代理啟動腳本：
scripts/start-agent.sh：
#!/bin/bash
AGENT_NAME=$1
PROJECT_DIR=$2
cd "$PROJECT_DIR"
# 建立代理工作區
mkdir -p .agents
# 啟動具有代理特定情境的 Claude Code
claude << EOF
# 代理身分
您是在 $PROJECT_DIR 工作的 $AGENT_NAME 代理。
# 通訊
- 從以下位置讀取您的狀態：.agents/$AGENT_NAME-status.md
- 將更新寫入：.agents/$AGENT_NAME-status.md
- 透過以下位置傳送訊息：.agents/messages.md
- 檢查協調器：.agents/coordinator.md
# 角色
$(cat .agents/roles/$AGENT_NAME.md)
# 開始工作
等待協調器的指示。
EOF
2. 建立協調器腳本：
scripts/orchestrate.sh：
#!/bin/bash
PROJECT_DIR=$(pwd)
# 初始化代理系統
mkdir -p .agents/roles
# 定義代理角色
cat > .agents/roles/backend.md << 'EOF'
# 後端代理角色
您負責：
- API 端點
- 業務邏輯
- 資料庫操作
- 後端測試
工作流程：
1. 讀取 .agents/coordinator.md 獲取任務
2. 實作您分配的功能
3. 更新 .agents/backend-status.md 顯示進度
4. 完成時使用 "[Backend]" 前綴提交
EOF
cat > .agents/roles/frontend.md << 'EOF'
# 前端代理角色
您負責：
- UI 元件
- 狀態管理
- 使用者互動
- 前端測試
工作流程：
1. 讀取 .agents/coordinator.md 獲取任務
2. 監控 backend-status.md 獲取 API 變更
3. 實作 UI 元件
4. 更新 .agents/frontend-status.md 顯示進度
5. 完成時使用 "[Frontend]" 前綴提交
EOF
# 初始化協調器狀態
cat > .agents/coordinator.md << 'EOF'
# 協調器狀態
## 目前任務：使用者認證功能
### 後端代理
- 狀態：待處理
- 任務：實作登入/登出端點
- 相依性：無
- 需要的輸出：具有 login/logout 函式的 auth.py
### 前端代理
- 狀態：等待中
- 任務：建立登入表單元件
- 相依性：後端 API 端點
- 需要的輸出：LoginForm.jsx 元件
### 通訊協定
1. 後端完成 → 更新 backend-status.md → 前端啟動
2. 前端完成 → 更新 frontend-status.md → 通知協調器
3. 兩者完成 → 整合測試 → 完成
## 訊息
（目前留空）
EOF
# 在背景啟動代理
gnome-terminal -- bash -c "cd $PROJECT_DIR && scripts/start-agent.sh backend $PROJECT_DIR" &
gnome-terminal -- bash -c "cd $PROJECT_DIR && scripts/start-agent.sh frontend $PROJECT_DIR" &
echo "代理已啟動。使用以下命令監控："
echo " tail -f .agents/backend-status.md"
echo " tail -f .agents/frontend-status.md"
3. 建立監控腳本：
scripts/monitor-agents.sh：
#!/bin/bash
watch -n 2 'echo "=== 代理狀態 ===" && \
echo "" && \
echo "=== 後端 ===" && \
cat .agents/backend-status.md 2>/dev/null || echo "未啟動" && \
echo "" && \
echo "=== 前端 ===" && \
cat .agents/frontend-status.md 2>/dev/null || echo "未啟動" && \
echo "" && \
echo "=== 協調器 ===" && \
cat .agents/coordinator.md 2>/dev/null || echo "未初始化"'
用法：
# 啟動多代理系統
./scripts/orchestrate.sh
# 在另一個終端機監控
./scripts/monitor-agents.sh
層級 2：MCP 伺服器訊息匯流排（穩健）
工作原理： 建立一個代理用來交換訊息的 MCP 伺服器。
1. 建立 MCP 訊息伺服器：
mcp-message-bus/server.py：
#!/usr/bin/env python3
"""
用於代理通訊的 MCP 訊息匯流排
作為集中式訊息佇列和協調系統。
"""
import json
import os
from datetime import datetime
from pathlib import Path
from typing import Dict, List, Optional
class MessageBus:
def __init__(self, state_dir: str = ".agents/message-bus"):
self.state_dir = Path(state_dir)
self.state_dir.mkdir(parents=True, exist_ok=True)
self.messages_file = self.state_dir / "messages.json"
self.status_file = self.state_dir / "status.json"
self.lock_file = self.state_dir / "lock"
def send_message(self, from_agent: str, to_agent: str, message: dict):
"""從一個代理傳送訊息到另一個代理。"""
messages = self._load_messages()
messages.append({
'id': f"msg_{len(messages)}_{datetime.now().timestamp()}",
'from': from_agent,
'to': to_agent,
'message': message,
'timestamp': datetime.now().isoformat(),
'status': 'pending'
})
self._save_messages(messages)
return messages[-1]['id']
def get_messages(self, agent_name: str, unread_only: bool = True):
"""取得代理的訊息。"""
messages = self._load_messages()
agent_messages = [m for m in messages if m['to'] == agent_name]
if unread_only:
agent_messages = [m for m in agent_messages if m['status'] == 'pending']
return agent_messages
def mark_read(self, message_id: str):
"""將訊息標記為已讀。"""
messages = self._load_messages()
for msg in messages:
if msg['id'] == message_id:
msg['status'] = 'read'
self._save_messages(messages)
def update_status(self, agent_name: str, status: dict):
"""更新代理狀態。"""
statuses = self._load_statuses()
statuses[agent_name] = {
**statuses.get(agent_name, {}),
**status,
'last_update': datetime.now().isoformat()
}
self._save_statuses(statuses)
def get_status(self, agent_name: Optional[str] = None):
"""取得代理狀態。"""
statuses = self._load_statuses()
if agent_name:
return statuses.get(agent_name, {})
return statuses
def get_all_agents(self):
"""取得所有活動代理的清單。"""
statuses = self._load_statuses()
return list(statuses.keys())
def _load_messages(self) -> List:
if self.messages_file.exists():
return json.loads(self.messages_file.read_text())
return []
def _save_messages(self, messages: List):
self.messages_file.write_text(json.dumps(messages, indent=2))
def _load_statuses(self) -> Dict:
if self.status_file.exists():
return json.loads(self.status_file.read_text())
return {}
def _save_statuses(self, statuses: Dict):
self.status_file.write_text(json.dumps(statuses, indent=2))
# MCP 伺服器介面（簡化）
def handle_message_bus_request(request: dict) -> dict:
"""處理傳入的訊息匯流排請求。"""
bus = MessageBus()
action = request.get('action')
if action == 'send':
result = bus.send_message(
request['from'],
request['to'],
request['message']
)
return {'success': True, 'message_id': result}
elif action == 'receive':
messages = bus.get_messages(request['agent'])
return {'success': True, 'messages': messages}
elif action == 'update_status':
bus.update_status(request['agent'], request['status'])
return {'success': True}
elif action == 'get_status':
status = bus.get_status(request.get('agent'))
return {'success': True, 'status': status}
elif action == 'list_agents':
agents = bus.get_all_agents()
return {'success': True, 'agents': agents}
else:
return {'success': False, 'error': '未知動作'}
if __name__ == '__main__':
# 簡單的 CLI 介面用於測試
import sys
if len(sys.argv) < 2:
print("用法：server.py <動作> [引數...]")
sys.exit(1)
action = sys.argv[1]
if action == 'send' and len(sys.argv) >= 4:
from_agent = sys.argv[2]
to_agent = sys.argv[3]
message = {'text': ' '.join(sys.argv[4:])}
result = handle_message_bus_request({
'action': 'send',
'from': from_agent,
'to': to_agent,
'message': message
})
print(f"訊息已傳送：{result['message_id']}")
elif action == 'receive' and len(sys.argv) >= 3:
agent = sys.argv[2]
result = handle_message_bus_request({
'action': 'receive',
'agent': agent
})
print(f"訊息：{json.dumps(result['messages'], indent=2)}")
elif action == 'status':
result = handle_message_bus_request({
'action': 'get_status',
'agent': sys.argv[2] if len(sys.argv) > 2 else None
})
print(f"狀態：{json.dumps(result['status'], indent=2)}")
2. 在 Claude Code 配置中註冊為 MCP 伺服器：
~/.config/claude-code/settings.json：
{
"mcpServers": {
"message-bus": {
"command": "python3",
"args": ["/path/to/mcp-message-bus/server.py"],
"env": {
"MESSAGE_BUS_DIR": ".agents/message-bus"
}
}
}
}
3. 代理使用訊息匯流排：
後端代理：
您：使用 message-bus MCP 伺服器。傳送訊息給前端代理：
「我已完成 /api/login 端點。它接受 POST 與 email/password
並返回 JWT token。端點已準備好整合。」
前端代理：
您：檢查 message-bus 來自後端代理的訊息。
[接收訊息]
您：太好了！我現在將建立呼叫 /api/login 的登入表單元件。
我將在 localStorage 中處理 JWT token。
層級 3：HTTP/WebSocket API（進階）
對於生產系統，建構適當的 HTTP API：
agent-coordinator/api.py：
from flask import Flask, request, jsonify
from message_bus import MessageBus
app = Flask(__name__)
bus = MessageBus()
@app.route('/send', methods=['POST'])
def send_message():
"""傳送訊息給代理。"""
data = request.json
msg_id = bus.send_message(data['from'], data['to'], data['message'])
return jsonify({'message_id': msg_id})
@app.route('/receive/<agent_name>', methods=['GET'])
def receive_messages(agent_name):
"""取得代理的待處理訊息。"""
messages = bus.get_messages(agent_name)
return jsonify({'messages': messages})
@app.route('/status/<agent_name>', methods=['GET', 'PUT'])
def agent_status(agent_name):
"""取得或更新代理狀態。"""
if request.method == 'PUT':
bus.update_status(agent_name, request.json)
return jsonify({'success': True})
else:
status = bus.get_status(agent_name)
return jsonify(status)
@app.route('/agents', methods=['GET'])
def list_agents():
"""列出所有代理。"""
agents = bus.get_all_agents()
return jsonify({'agents': agents})
if __name__ == '__main__':
app.run(port=5555)
代理使用 curl 通訊：
# 傳送訊息
curl -X POST http://localhost:5555/send \
-H "Content-Type: application/json" \
-d '{"from": "backend", "to": "frontend", "message": {"text": "API 就緒"}}'
# 檢查訊息
curl http://localhost:5555/receive/frontend
完整多代理系統
讓我們建構一個具有 4 個代理的完整自動化系統。
系統架構
┌─────────────────────────────────────────────────────────┐
│ 協調器（主終端機） │
│ - 啟動所有代理 │
│ - 監控進度 │
│ - 處理衝突 │
└────────┬────────────────────────────────────────────────┘
│
├──────────────────┬──────────────────┬──────────────────┐
│ │ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ 後端 │ │前端 │ │ 測試 │ │ 文件 │
│ 代理 │ │ 代理 │ │ 代理 │ │ 代理 │
└────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
│ │ │ │
└──────────────────┴──────────────────┴──────────────────┘
│
┌─────────▼──────────┐
│ 訊息匯流排 (MCP) │
│ + 共用檔案 │
└─────────────────────┘
實作
1. 建立專案結構：
multi-agent-project/
├── .agents/
│ ├── roles/ # 代理角色定義
│ ├── workspace/ # 代理工作目錄
│ │ ├── backend/
│ │ ├── frontend/
│ │ ├── tests/
│ │ └── docs/
│ └── state/ # 共用狀態
├── src/
├── scripts/
│ ├── orchestrate.sh # 主協調器
│ ├── start-agent.sh # 代理啟動器
│ ├── monitor.sh # 狀態監控器
│ └── resolve-conflicts.sh # 衝突處理器
└── claude-agents.json # 代理配置
2. 代理配置：
claude-agents.json：
{
"agents": [
{
"name": "backend",
"role": "後端開發",
"specialty": "API、資料庫、業務邏輯",
"terminal": "1",
"working_dir": ".agents/workspace/backend",
"dependencies": [],
"output": "src/backend/",
"startup_prompt": "從閱讀 specs/api.md 中的 API 規格開始"
},
{
"name": "frontend",
"role": "前端開發",
"specialty": "UI 元件、狀態管理",
"terminal": "2",
"working_dir": ".agents/workspace/frontend",
"dependencies": ["backend"],
"output": "src/frontend/",
"startup_prompt": "等待後端代理完成 API，然後建構 UI"
},
{
"name": "tests",
"role": "測試與 QA",
"specialty": "單元測試、整合測試",
"terminal": "3",
"working_dir": ".agents/workspace/tests",
"dependencies": ["backend", "frontend"],
"output": "tests/",
"startup_prompt": "等待實作，然後建立完整測試"
},
{
"name": "docs",
"role": "文件",
"specialty": "API 文件、使用者指南",
"terminal": "4",
"working_dir": ".agents/workspace/docs",
"dependencies": ["backend", "frontend"],
"output": "docs/",
"startup_prompt": "在完成時記錄實作"
}
],
"communication": {
"method": "mcp",
"message_bus": "message-bus",
"update_interval": 5
},
"coordination": {
"mode": "hierarchical",
"conflict_resolution": "human-in-loop",
"checkpoint_interval": 300
}
}
3. 協調器腳本：
scripts/orchestrate.sh：
#!/bin/bash
set -e
PROJECT_ROOT=$(pwd)
CONFIG_FILE="$PROJECT_ROOT/claude-agents.json"
AGENTS_DIR="$PROJECT_ROOT/.agents"
echo "🚀 啟動多代理 Claude Code 系統"
echo "============================================="
# 載入配置
if [ ! -f "$CONFIG_FILE" ]; then
echo "❌ 錯誤：找不到 claude-agents.json"
exit 1
fi
# 初始化工作區
echo "📁 初始化工作區..."
mkdir -p "$AGENTS_DIR"/{roles,workspace,state}
# 提取代理計數
AGENT_COUNT=$(jq '.agents | length' "$CONFIG_FILE")
echo "📊 找到 $AGENT_COUNT 個代理要啟動"
# 啟動代理的函式
start_agent() {
local index=$1
local agent_name=$(jq -r ".agents[$index].name" "$CONFIG_FILE")
local role=$(jq -r ".agents[$index].role" "$CONFIG_FILE")
local working_dir=$(jq -r ".agents[$index].working_dir" "$CONFIG_FILE")
local terminal=$(jq -r ".agents[$index].terminal" "$CONFIG_FILE")
local startup_prompt=$(jq -r ".agents[$index].startup_prompt" "$CONFIG_FILE")
local dependencies=$(jq -r ".agents[$index].dependencies | join(\", \")" "$CONFIG_FILE")
echo "🤖 啟動代理：$agent_name ($role)"
# 建立代理工作區
mkdir -p "$PROJECT_ROOT/$working_dir"
# 建立角色檔案
cat > "$AGENTS_DIR/roles/$agent_name.md" << EOF
# $agent_name 代理
## 角色
$role
## 相依性
$([ -n "$dependencies" ] && echo "$dependencies" || echo "無")
## 指示
1. 監控 .agents/state/coordinator.md 獲取任務
2. 透過 message-bus MCP 伺服器傳送更新
3. 在 .agents/state/$agent_name-status.md 更新您的狀態
4. 使用 "[$agent_name]" 前綴提交您的工作
## 初始任務
$startup_prompt
## 通訊
- 使用 message-bus MCP 與其他代理通訊
- 每 30 秒檢查一次訊息
- 在 1 分鐘內回應查詢
EOF
# 在新終端機啟動 Claude Code
# 注意：終端機命令因作業系統而異
if command -v gnome-terminal &> /dev/null; then
gnome-terminal --title="$agent_name Agent" -- bash -c "
cd '$PROJECT_ROOT'
claude << AGENT_EOF
# 代理初始化
您是 $agent_name 代理。
$(cat "$AGENTS_DIR/roles/$agent_name.md")
# 現在開始工作。
等待進一步指示。
AGENT_EOF
exec bash
" &
elif command -v tmux &> /dev/null; then
tmux new-window -n "$agent_name" "cd '$PROJECT_ROOT' && claude"
else
# 後備：在背景執行
(
cd '$PROJECT_ROOT'
claude << AGENT_EOF
# 代理初始化
您是 $agent_name 代理。
$(cat "$AGENTS_DIR/roles/$agent_name.md")
# 現在開始工作。
AGENT_EOF
) &
fi
# 記錄代理 PID
echo $! > "$AGENTS_DIR/state/$agent_name.pid"
}
# 啟動所有代理
for ((i=0; i<$AGENT_COUNT; i++)); do
start_agent $i
sleep 2 # 錯開啟動
done
echo ""
echo "✅ 所有代理已啟動！"
echo ""
echo "📊 使用以下命令監控代理："
echo " ./scripts/monitor.sh"
echo ""
echo "🛑 使用以下命令停止代理："
echo " ./scripts/stop.sh"
echo ""
echo "💬 與代理通訊："
echo " ./scripts/talk-to-agent.sh <agent-name>"
echo ""
# 在當前終端機啟動協調器
echo "🎯 啟動協調器..."
cat > "$AGENTS_DIR/state/coordinator.md" << 'EOF'
# 協調器狀態
## 活動代理
- backend：實作 API
- frontend：建構 UI（等待後端）
- tests：建立測試（等待實作）
- docs：撰寫文件（等待實作）
## 目前任務
建構使用者認證系統
## 工作流程
1. 後端代理實作登入/註冊端點
2. 前端代理建構登入表單
3. 測試代理建立測試套件
4. 文件代理撰寫 API 文件
## 進度
- 後端：0%
- 前端：0%
- 測試：0%
- 文件：0%
EOF
# 啟動監控器
./scripts/monitor.sh
4. 監控腳本：
scripts/monitor.sh：
#!/bin/bash
clear
echo "🤖 多代理 Claude Code 監控器"
echo "=================================="
echo ""
while true; do
clear
echo "🤖 多代理 Claude Code 監控器"
echo "=================================="
echo ""
echo "時間：$(date '+%Y-%m-%d %H:%M:%S')"
echo ""
# 檢查代理程序
echo "📊 代理狀態："
echo "---------------"
if [ -d ".agents/state" ]; then
for pidfile in .agents/state/*.pid; do
if [ -f "$pidfile" ]; then
agent_name=$(basename "$pidfile" .pid)
pid=$(cat "$pidfile")
if ps -p "$pid" > /dev/null 2>&1; then
echo "✅ $agent_name：執行中（PID：$pid）"
else
echo "❌ $agent_name：已停止"
fi
fi
done
fi
echo ""
# 顯示代理狀態檔案
echo "📋 代理進度："
echo "-----------------"
for statusfile in .agents/state/*-status.md; do
if [ -f "$statusfile" ]; then
agent_name=$(basename "$statusfile" -status.md)
echo "### $agent_name："
tail -n 5 "$statusfile" | sed 's/^/ /'
echo ""
fi
done
# 顯示協調器狀態
echo "🎯 協調器："
echo "--------------"
if [ -f ".agents/state/coordinator.md" ]; then
tail -n 10 ".agents/state/coordinator.md" | sed 's/^/ /'
fi
echo ""
# 顯示最近訊息
echo "💬 最近訊息："
echo "------------------"
if [ -f ".agents/state/messages.json" ]; then
jq -r '.[-3:] | .[] | "\(.from) → \(.to): \(.message.text // .message)"' \
.agents/state/messages.json 2>/dev/null | sed 's/^/ /' || echo " 尚無訊息"
fi
echo ""
# 顯示衝突
echo "⚠️ 衝突："
echo "-------------"
if [ -f ".agents/state/conflicts.json" ]; then
jq -r '.[] | "- \(.type): \(.description)"' \
.agents/state/conflicts.json 2>/dev/null | sed 's/^/ /' || echo " 無衝突"
else
echo " 無"
fi
echo ""
sleep 5
done
5. 衝突解決腳本：
scripts/resolve-conflicts.sh：
#!/bin/bash
echo "🔧 代理衝突解決"
echo "============================"
echo ""
# 檢查衝突
if [ ! -f ".agents/state/conflicts.json" ]; then
echo "✅ 未偵測到衝突"
exit 0
fi
CONFLICT_COUNT=$(jq '. | length' .agents/state/conflicts.json)
if [ "$CONFLICT_COUNT" -eq 0 ]; then
echo "✅ 未偵測到衝突"
exit 0
fi
echo "⚠️ 發現 $CONFLICT_COUNT 個衝突"
echo ""
jq -r '.[] | "\n### \(.type)\n代理：\(.agents | join(", "))\n描述：\(.description)\n選項：\n\(.options | .[] | "- \(.action): \(.description)")"' \
.agents/state/conflicts.json
echo ""
echo "選擇解決方案："
echo "1. 開啟檔案並手動合併"
echo "2. 讓代理 A 獲勝"
echo "3. 讓代理 B 獲勝"
echo "4. 建立混合解決方案"
echo "5. 升級給人類"
read -p "選擇選項 (1-5): " choice
case $choice in
1)
echo "開啟檔案進行手動合併..."
# 開啟編輯器並顯示衝突檔案
;;
2|3)
echo "套用解決方案..."
# 套用所選代理的版本
;;
4)
echo "建立混合解決方案..."
# 要求 Claude 建立混合方案
;;
5)
echo "⚠️ 衝突升級給人類"
echo "請檢閱並手動解決"
;;
esac
用法
1. 啟動多代理系統：
./scripts/orchestrate.sh
2. 觀看代理工作： 監控器顯示即時進度：
🤖 多代理 Claude Code 監控器
==================================
時間：2025-02-04 14:30:45
📊 代理狀態：
---------------
✅ backend：執行中（PID：12345）
✅ frontend：執行中（PID：12346）
✅ tests：執行中（PID：12347）
✅ docs：執行中（PID：12348）
📋 代理進度：
-----------------
### backend:
✓ 已建立 auth.py
✓ 已實作登入端點
→ 正在處理登出端點
### frontend:
⏳ 等待後端 API 完成
### tests:
⏳ 等待實作
### docs:
⏳ 等待實作
💬 最近訊息：
------------------
backend → frontend：「登入 API 就緒於 /api/login」
backend → coordinator：「登入端點完成」
3. 代理自動通訊：
後端代理完成任務：
您：更新您的狀態並通知前端代理
Claude：[更新 backend-status.md]
[使用 message-bus MCP 傳送訊息]
[通知協調器]
前端代理接收訊息：
Claude：[檢查 message-bus]
[來自後端的新訊息：「登入 API 就緒」]
[開始前端實作]
進階模式
模式 1：動態代理生成
根據需要生成新代理：
scripts/spawn-agent.sh：
#!/bin/bash
# 生成臨時專業代理
AGENT_TYPE=$1
TASK=$2
case $AGENT_TYPE in
"security")
ROLE="安全專家"
;;
"performance")
ROLE="效能優化專家"
;;
"database")
ROLE="資料庫管理員"
;;
*)
echo "未知代理類型：$AGENT_TYPE"
exit 1
esac
# 使用臨時角色生成代理
gnome-terminal -- bash -c "
claude << EOF
您是臨時 $ROLE 代理。
任務：$TASK
完成此任務，然後：
1. 記錄您的變更
2. 透過 message-bus 傳送結果
3. 完成時退出
EOF
"
用法：
./scripts/spawn-agent.sh security "審計認證程式碼的漏洞"
模式 2：階層式團隊
建立代理團隊：
前端團隊負責人
├─→ 元件代理
├─→ 狀態管理代理
└─→ 樣式代理
後端團隊負責人
├─→ API 代理
├─→ 資料庫代理
└─→ 認證代理
實作：
# 啟動團隊負責人
./scripts/orchestrate.sh --mode=leaders-only
# 團隊負責人生成其團隊成員
# 前端負責人生成元件、狀態、樣式代理
# 後端負責人生成 API、資料庫、認證代理
模式 3：同儕審查系統
代理相互審查工作：
實作代理 → 審查代理 → 修正代理
↑ ↓
└──────────────────────┘
（反覆直到批准）
腳本： scripts/setup-review-cycle.sh
#!/bin/bash
# 代理 1：實作
./scripts/start-agent.sh implementer "建構功能 X"
# 代理 2：審查
./scripts/start-agent.sh reviewer "審查功能 X 實作"
# 如果審查者發現問題：
# - 傳送訊息給實作者
# - 實作者修正
# - 審查者再次審查
# 反覆直到批准
衝突解決
當代理不同意時，您需要策略。
偵測
代理向協調器報告衝突：
// .agents/state/conflicts.json
[
{
"type": "naming_conflict",
"agents": ["backend", "frontend"],
"description": "使用者物件的不同命名",
"backend_version": {"name": "User", "fields": ["id", "email"]},
"frontend_version": {"name": "UserProfile", "fields": ["id", "email"]},
"options": [
{"action": "use_backend", "description": "使用後端命名，更新前端"},
{"action": "use_frontend", "description": "使用前端命名，更新後端"},
{"action": "create_alias", "description": "建立 UserProfile 作為 User 的別名"}
]
}
]
解決策略
1. 自動（基於規則）
{
"resolution_rules": [
{
"conflict_type": "naming_conflict",
"priority": "backend_wins",
"reason": "後端是真相來源"
},
{
"conflict_type": "api_conflict",
"priority": "human_decision",
"reason": "需要架構決策"
}
]
}
2. 投票（民主）
# 讓所有代理投票決定解決方案
./scripts/vote-on-resolution.sh "naming_conflict"
3. 人類在迴圈中
# 暫停代理，詢問人類決定
./scripts/escalate-to-human.sh "naming_conflict"
最佳實踐
1. 清楚的代理邊界
✅ 好：
後端代理：API、資料庫、業務邏輯
前端代理：UI、狀態、使用者互動
❌ 壞：
代理 1：所有事情
代理 2：也是所有事情（衝突！）
2. 相依性管理
定義清楚的相依性：
{
"agent": "frontend",
"dependencies": ["backend"],
"wait_condition": "backend-status.md 包含 '[READY]'"
}
3. 通訊頻率
在協調和開銷之間取得平衡：
- 高頻率（5秒）：關鍵路徑任務
- 中頻率（30秒）：正常協作
- 低頻率（5分鐘）：非同步任務
4. 狀態管理
使用不可變狀態：
state-v1.json
state-v2.json
state-v3.json
而不是：
state.json（不斷變化）
5. 監控和記錄
記錄所有事情：
.agents/logs/
├── backend-2025-02-04.log
├── frontend-2025-02-04.log
└── coordinator-2025-02-04.log
真實範例：電子商務功能
讓我們用 4 個代理建構完整的購物車功能。
設定：
mkdir multi-agent-ecommerce
cd multi-agent-ecommerce
# 初始化多代理系統
./scripts/init-multi-agent.sh
配置： claude-agents.json
{
"agents": [
{
"name": "database",
"role": "資料庫 Schema 設計師",
"tasks": [
"設計 cart_items 表格",
"建立遷移",
"新增索引"
]
},
{
"name": "backend",
"role": "API 開發者",
"dependencies": ["database"],
"tasks": [
"POST /api/cart（新增項目）",
"GET /api/cart（取得項目）",
"DELETE /api/cart/:id（移除項目）",
"PUT /api/cart/:id（更新數量）"
]
},
{
"name": "frontend",
"role": "UI 開發者",
"dependencies": ["backend"],
"tasks": [
"購物車元件",
"新增至購物車按鈕",
"購物車頁面",
"數量控制"
]
},
{
"name": "tests",
"role": "QA 工程師",
"dependencies": ["backend", "frontend"],
"tasks": [
"API 整合測試",
"前端單元測試",
"使用 Playwright 的 E2E 測試"
]
}
]
}
執行：
./scripts/orchestrate.sh
# 觀看代理工作：
# 1. 資料庫代理建立 schema（5 分鐘）
# 2. 後端代理建構 API（與 DB 並行，等待 schema）（15 分鐘）
# 3. 前端代理建構 UI（並行，等待 API）（20 分鐘）
# 4. 測試代理建立測試（等待實作）（10 分鐘）
# 總時間：~35 分鐘（vs 循序 50+ 分鐘）
監控器輸出：
🤖 多代理監控器
=====================
✅ database：Schema 已建立
→ cart_items 表格已設計
→ 遷移檔案已建立
→ 索引已新增
✅ backend：API 端點就緒
→ POST /api/cart ✓
→ GET /api/cart ✓
→ DELETE /api/cart/:id ✓
→ PUT /api/cart/:id ✓
✅ frontend：UI 元件已建構
→ 購物車元件 ✓
→ 新增至購物車按鈕 ✓
→ 購物車頁面 ✓
✅ tests：測試套件完成
→ API 測試通過（15/15）
→ 前端測試通過（8/8）
→ E2E 測試通過（5/5）
🎉 34 分鐘內功能完成！
✅ 檢查您的理解
-
多個 Claude Code 代理的主要好處是什麼？
- 它們更便宜
- 並行化和專業化
- 它們使用較少記憶體
- 不需要設定
-
代理之間最簡單的通訊方法是什麼？
- WebSocket
- 基於檔案的訊息傳遞
- HTTP API
- 心靈感應
-
協調器做什麼？
- 撰寫所有程式碼
- �調和監控代理
- 只處理衝突
- 什麼都不做
-
True or False： 代理可以在沒有協調的情況下完全獨立工作。
- True
- False - 它們需要協調以避免衝突
-
代理衝突的好策略是什麼？
- 讓它們打鬥
- 清楚的優先順序規則或人類在迴圈中
- 忽略衝突
- 停止所有代理
答案： 1-b, 2-b, 3-b, 4-False, 5-b
總結
在本課程中，您學到了：
- 多代理架構 - 階層式、管線、點對點
- 通訊協定 - 基於檔案、MCP 訊息匯流排、HTTP API
- 編排 - 啟動、監控、停止代理
- 自動化腳本 - 完整系統實作
- 衝突解決 - 偵測和解決策略
- 真實工作流程 - 實用電子商務範例
下一步
嘗試：
- 從 2 個代理開始（後端 + 前端）
- 新增第三個代理（測試）
- 建構自訂通訊協定
- 為您的領域建立專業代理
- 實作自動衝突解決
進階閱讀
恭喜！您已掌握最進階的 Claude Code 技術！🎉