253f38a75e
- spec 檔案重新命名去除 v4 前綴 - 更新所有內部交叉引用 - 新增 migration_to_paperclip.md：概念對照、目標結構、Agent 定義、排程轉換 - INDEX.md 標記 OpenClaw 時期文檔為遷移參考用 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
403 lines
11 KiB
Markdown
403 lines
11 KiB
Markdown
# KingClawArmy - 第四部分：Agent 協作協定
|
||
|
||
> 日期：2026-04-10
|
||
> 狀態：定稿（遷移至 Paperclip 前的參考版本）
|
||
|
||
---
|
||
|
||
## 4.1 設計原則
|
||
|
||
| 原則 | 說明 |
|
||
|---|---|
|
||
| **Spawn 優先** | Pipeline 步驟一律用 `sessions_spawn`，不阻塞任何 agent |
|
||
| **Send 只用於即時對話** | 只有 depth-0 的獨立 agent 之間才能 `sessions_send` |
|
||
| **策略師主導 Pipeline** | 量化 pipeline 由策略師 own，CEO 只管啟動和例外 |
|
||
| **Schema 消除追問** | 嚴格定義輸出格式，讓 agent 一次交齊，不需要來回追問 |
|
||
| **向上回報** | 子 agent 透過 announce 回傳結果，不能橫向對話 |
|
||
|
||
---
|
||
|
||
## 4.2 通訊工具行為（已驗證）
|
||
|
||
### sessions_spawn — 非阻塞派工
|
||
|
||
- 立即返回 `runId`，不等待結果
|
||
- 對方在隔離 session 中執行，完成後 announce 結果回 parent
|
||
- Parent 可繼續處理其他事
|
||
|
||
### sessions_send — 同步對話（阻塞）
|
||
|
||
- Sender 等待對方回覆（可設 `timeoutSeconds`）
|
||
- 最多 5 輪來回
|
||
- **只有 depth-0 的獨立 agent 能使用**
|
||
|
||
### maxSpawnDepth 與工具權限
|
||
|
||
| `maxSpawnDepth` | Depth-1 子 agent | Depth-2 子 agent |
|
||
|---|---|---|
|
||
| **1（預設）** | ❌ 無 session 工具（葉層） | — |
|
||
| **≥ 2** | ✅ `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` | ❌ 永遠是葉層 |
|
||
|
||
**關鍵限制：**
|
||
|
||
- `sessions_send` **不在任何子 agent 的授權清單中**，無論 maxSpawnDepth 設多少
|
||
- 通訊方向為**單向往上**：子 agent 只能 announce 回 parent
|
||
- 同層子 agent 之間**不能互相通訊**
|
||
- 最大嵌套深度：5 層
|
||
- 最大並行子 agent：5 個（`maxChildrenPerAgent`，可調至 20）
|
||
- 最大併發：8 個（`maxConcurrent`）
|
||
|
||
### 判斷規則
|
||
|
||
> **你需要對方「現在立刻回答你」才能繼續嗎？**
|
||
> - Yes → `sessions_send`（僅限 depth-0 agent）
|
||
> - No → `sessions_spawn`
|
||
|
||
| 情境 | 工具 | 原因 |
|
||
|---|---|---|
|
||
| Pipeline 步驟交接 | **spawn** | 獨立任務，不需等待 |
|
||
| 並行研究 | **spawn**（多個） | 各做各的 |
|
||
| CEO 啟動 pipeline | **spawn** | CEO 不能被阻塞 |
|
||
| CEO 問秘書「今日摘要」 | **send** | CEO 是 depth-0，需要即時回覆 |
|
||
| 審查員退回修改 | **重新 spawn** | 帶上修改意見再跑一次 |
|
||
| 需要追問細節 | **重新 spawn** | 帶上前次結果 + 具體問題 |
|
||
|
||
---
|
||
|
||
## 4.3 Message Envelope（Agent 間訊息格式）
|
||
|
||
所有 agent 間的溝通統一使用結構化信封，不使用自由文字：
|
||
|
||
```json
|
||
{
|
||
"from": "bullish_researcher",
|
||
"to": "quant_strategist",
|
||
"intent": "deliver_report",
|
||
"ref_task": "quant-pipeline-2026-04-10",
|
||
"payload": { "$ref": "Bullish_Brief.json" },
|
||
"expect_response": false
|
||
}
|
||
```
|
||
|
||
### Intent 類型
|
||
|
||
| intent | 方向 | 說明 |
|
||
|---|---|---|
|
||
| `assign_task` | parent → child | 派工指令 |
|
||
| `deliver_report` | child → parent | 任務完成，結果在 payload |
|
||
| `request_clarification` | parent → child | 追問（透過重新 spawn） |
|
||
| `review_request` | → reviewer | 請求審查 |
|
||
| `review_verdict` | reviewer → parent | 審查結果：`pass` / `revise` / `block` |
|
||
| `collect_opinion` | coordinator → agent | 收集觀點 |
|
||
| `escalate` | any → CEO | 上報異常 |
|
||
| `notify` | any → Discord | 通知（非對話） |
|
||
|
||
### Payload 規範
|
||
|
||
- 所有 payload 必須是定義好的 JSON schema（見各 agent 的 AGENTS.md）
|
||
- 不在 JSON 之外附加自由文字說明
|
||
- 缺少必填欄位時，回傳 `missing_fields` 清單而非空值
|
||
|
||
---
|
||
|
||
## 4.4 Pipeline 架構
|
||
|
||
### 角色分工
|
||
|
||
```
|
||
CEO 的職責：
|
||
✅ 接收董事長指令
|
||
✅ spawn 啟動 pipeline（策略師）
|
||
✅ 處理 escalation 和 HITL
|
||
✅ 多 pipeline 並行管理
|
||
❌ 不逐步 spawn 每個研究員（那是策略師的事）
|
||
|
||
策略師的職責：
|
||
✅ 擁有量化 pipeline 的執行權
|
||
✅ spawn 研究員、收斂結果
|
||
✅ spawn 審查員、處理 revise
|
||
✅ 管理研究員的輸出品質
|
||
❌ 不做資料蒐集（那是研究員的事）
|
||
```
|
||
|
||
### 量化 Pipeline 流程
|
||
|
||
```
|
||
你 → CEO（Discord）→ 「啟動量化 pipeline」
|
||
│
|
||
└─ spawn 策略師（depth 1, maxSpawnDepth ≥ 2）
|
||
│
|
||
├─ spawn 情報員（depth 2）
|
||
│ └─ announce Finance_Research_Brief.json
|
||
│
|
||
├─ spawn 市場結構研究員（depth 2，等情報完成）
|
||
│ └─ announce Market_Structure_Report.json
|
||
│
|
||
├─ spawn 多方研究員（depth 2）──┐ 並行
|
||
├─ spawn 空方研究員（depth 2）──┘ 並行
|
||
│ └─ 都 announce 完成
|
||
│
|
||
├─ 策略師自己收斂 → Strategy_Thesis.json
|
||
│
|
||
├─ spawn 審查員（depth 2）
|
||
│ └─ announce Review_Report.json
|
||
│ ├─ pass → 繼續
|
||
│ ├─ revise → 策略師重新 spawn 被退回的角色（帶修改意見）
|
||
│ │ 最多 3 輪，超過 → escalate CEO
|
||
│ └─ block → escalate CEO
|
||
│
|
||
└─ announce 給 CEO「pipeline 完成」
|
||
│
|
||
└─ CEO → Discord @董事長 請求批准
|
||
```
|
||
|
||
### Lobster DSL 定義（取代 Standing Orders）
|
||
|
||
```yaml
|
||
name: daily_quant_pipeline
|
||
trigger: cron "30 7 * * 1-5"
|
||
owner: quant_strategist
|
||
|
||
steps:
|
||
- id: intel
|
||
agent: finance_researcher
|
||
action: spawn
|
||
output: Finance_Research_Brief.json
|
||
|
||
- id: structure
|
||
agent: market_structure_researcher
|
||
action: spawn
|
||
depends_on: [intel]
|
||
output: Market_Structure_Report.json
|
||
|
||
- id: bull
|
||
agent: bullish_researcher
|
||
action: spawn
|
||
depends_on: [structure]
|
||
output: Bullish_Brief.json
|
||
|
||
- id: bear
|
||
agent: bearish_researcher
|
||
action: spawn
|
||
depends_on: [structure]
|
||
output: Bearish_Brief.json
|
||
|
||
- id: converge
|
||
agent: quant_strategist
|
||
action: self
|
||
depends_on: [bull, bear]
|
||
output: Strategy_Thesis.json
|
||
|
||
- id: review
|
||
agent: reviewer
|
||
action: spawn
|
||
depends_on: [converge]
|
||
output: Review_Report.json
|
||
on_revise: retry(converge, max=3)
|
||
on_block: escalate(ceo_coo)
|
||
|
||
- id: data_analysis
|
||
agent: data_analyst
|
||
action: spawn
|
||
depends_on: [review]
|
||
condition: review.verdict == "pass"
|
||
output: Data_Analysis_Report.json
|
||
|
||
- id: approve
|
||
type: hitl
|
||
channel: "#approvals"
|
||
depends_on: [data_analysis]
|
||
```
|
||
|
||
### 追問處理（重新 Spawn 模式）
|
||
|
||
當策略師發現研究員報告有缺漏，不用 send，用重新 spawn：
|
||
|
||
```json
|
||
{
|
||
"from": "quant_strategist",
|
||
"to": "bullish_researcher",
|
||
"intent": "request_clarification",
|
||
"ref_task": "quant-pipeline-2026-04-10",
|
||
"payload": {
|
||
"previous_report": { "$ref": "Bullish_Brief.json" },
|
||
"missing_fields": ["key_levels[].evidence", "invalidation"],
|
||
"question": "你提到 OB 支撐，請補充具體價位與時間框架"
|
||
}
|
||
}
|
||
```
|
||
|
||
**但設計目標是讓追問不需要發生** — 靠嚴格的輸出 schema 讓 agent 一次交齊。
|
||
|
||
---
|
||
|
||
## 4.5 輸出 Schema（核心）
|
||
|
||
每個 agent 的產出必須遵循定義好的 JSON schema，寫在各 agent 的 AGENTS.md 中。
|
||
|
||
### Finance_Research_Brief.json
|
||
|
||
```json
|
||
{
|
||
"date": "2026-04-10",
|
||
"market": "BTC/USDT",
|
||
"macro_summary": "...",
|
||
"key_events": [
|
||
{ "event": "...", "impact": "bullish|bearish|neutral", "source": "..." }
|
||
],
|
||
"sentiment": { "overall": "bullish|bearish|neutral", "score": 0.0 },
|
||
"data_sources": ["..."]
|
||
}
|
||
```
|
||
|
||
### Market_Structure_Report.json
|
||
|
||
```json
|
||
{
|
||
"date": "2026-04-10",
|
||
"market": "BTC/USDT",
|
||
"timeframes_analyzed": ["H4", "H1"],
|
||
"structure": {
|
||
"trend": "bullish|bearish|ranging",
|
||
"mss_detected": true,
|
||
"key_levels": [
|
||
{ "type": "OB|FVG|POI|support|resistance", "price": 0, "timeframe": "H4", "tested": false }
|
||
]
|
||
},
|
||
"liquidity_zones": [
|
||
{ "type": "buy_side|sell_side", "range": [0, 0], "significance": "high|medium|low" }
|
||
]
|
||
}
|
||
```
|
||
|
||
### Bullish_Brief.json / Bearish_Brief.json
|
||
|
||
```json
|
||
{
|
||
"date": "2026-04-10",
|
||
"market": "BTC/USDT",
|
||
"thesis": "核心論點（一句話）",
|
||
"arguments": [
|
||
{ "point": "...", "evidence": "...", "confidence": 0.0 }
|
||
],
|
||
"key_levels": [
|
||
{ "type": "support|resistance", "price": 0, "timeframe": "H4", "evidence": "..." }
|
||
],
|
||
"catalysts": ["..."],
|
||
"invalidation": "什麼條件下論點失效",
|
||
"confidence": 0.0,
|
||
"data_sources": ["..."]
|
||
}
|
||
```
|
||
|
||
### Strategy_Thesis.json
|
||
|
||
```json
|
||
{
|
||
"date": "2026-04-10",
|
||
"market": "BTC/USDT",
|
||
"direction": "long|short|neutral",
|
||
"thesis": "收斂後的策略論點",
|
||
"entry_zone": [0, 0],
|
||
"stop_loss": 0,
|
||
"take_profit": [0, 0],
|
||
"risk_reward": 0.0,
|
||
"position_size_pct": 0.0,
|
||
"risk_assessment": {
|
||
"max_drawdown_pct": 0.0,
|
||
"bias_check": "confirmed|conflicting",
|
||
"bull_confidence": 0.0,
|
||
"bear_confidence": 0.0
|
||
},
|
||
"invalidation": "...",
|
||
"requires_backtest": true
|
||
}
|
||
```
|
||
|
||
### Review_Report.json
|
||
|
||
```json
|
||
{
|
||
"date": "2026-04-10",
|
||
"reviewed_artifact": "Strategy_Thesis.json",
|
||
"verdict": "pass|revise|block",
|
||
"score": 0.0,
|
||
"issues": [
|
||
{ "severity": "critical|major|minor", "field": "...", "description": "...", "suggestion": "..." }
|
||
],
|
||
"revise_target": "quant_strategist|bullish_researcher|...",
|
||
"summary": "..."
|
||
}
|
||
```
|
||
|
||
### Data_Analysis_Report.json
|
||
|
||
```json
|
||
{
|
||
"date": "2026-04-10",
|
||
"analyzed_artifact": "Backtest_Delivery.json",
|
||
"metrics": {
|
||
"total_trades": 0,
|
||
"win_rate": 0.0,
|
||
"profit_factor": 0.0,
|
||
"max_drawdown_pct": 0.0,
|
||
"sharpe_ratio": 0.0,
|
||
"avg_rr": 0.0
|
||
},
|
||
"insights": ["..."],
|
||
"recommendation": "proceed|adjust|reject",
|
||
"summary": "..."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4.6 Review Gate
|
||
|
||
| 必審節點 | 觸發方式 | 審查標準 |
|
||
|---|---|---|
|
||
| 量化策略提交 | 策略師 spawn 審查員 | schema 完整性 + 風控邏輯 |
|
||
| 回測結果提交 | 策略師 spawn 審查員 | 績效指標合理性 |
|
||
| 工程交付 | CEO spawn 審查員 | 程式碼品質 + 測試覆蓋 |
|
||
| 文案對外 | CEO spawn 審查員 | 品牌一致性 + 法規合規 |
|
||
|
||
### Revise 流程
|
||
|
||
```
|
||
審查員 announce: { verdict: "revise", revise_target: "bullish_researcher", issues: [...] }
|
||
↓
|
||
策略師收到 → 重新 spawn 多方研究員，帶上 issues
|
||
↓
|
||
多方研究員修改 → announce 新版本
|
||
↓
|
||
策略師再 spawn 審查員 review
|
||
↓
|
||
最多 3 輪。超過 → escalate CEO → CEO Discord @董事長
|
||
```
|
||
|
||
---
|
||
|
||
## 4.7 HITL 節點
|
||
|
||
| 需要董事長批准的事 | 通知方式 |
|
||
|---|---|
|
||
| 量化策略正式執行 | Discord #approvals @董事長 |
|
||
| 正式部署 | Discord #approvals @董事長 |
|
||
| DB schema 變更 | Discord #approvals @董事長 |
|
||
| 廣告正式發布 | Discord #approvals @董事長 |
|
||
| 對外訊息發送 | Discord #approvals @董事長 |
|
||
| 金流操作 | Discord #approvals @董事長 |
|
||
|
||
---
|
||
|
||
## 4.8 錯誤處理
|
||
|
||
| 錯誤類型 | 處理方式 |
|
||
|---|---|
|
||
| Agent 執行超時 | 策略師重新 spawn，帶上 timeout 通知 |
|
||
| Agent 回傳 missing_fields | 策略師重新 spawn，明確要求補齊 |
|
||
| 審查 block | escalate CEO → Discord @董事長 |
|
||
| 審查 revise 超過 3 輪 | escalate CEO → Discord @董事長 |
|
||
| Pipeline 異常中斷 | CEO 通知 Discord #errors |
|
||
| 模型 API 錯誤 | 自動重試 1 次，失敗 → Discord #errors |
|