KingClawArmy/docs/schemas.md

KingClawArmy - 輸出 Schema 定義

平台：Paperclip 日期：2026-04-10

每個 agent 的產出必須遵循定義好的 JSON schema，確保一次交齊，減少追問。

---

Finance_Research_Brief.json

產出者：財經情報研究員（finance-researcher）

{
  "date": "2026-04-10",
  "market": "BTC/USDT",
  "session": "pre_market|post_market|intraday",
  "macro_summary": "總體經濟概況摘要",
  "key_events": [
    {
      "event": "事件描述",
      "time": "2026-04-10T08:30:00+08:00",
      "impact": "bullish|bearish|neutral",
      "severity": "high|medium|low",
      "source": "來源"
    }
  ],
  "sentiment": {
    "overall": "bullish|bearish|neutral",
    "confidence_index": 0.0,
    "fear_greed_index": 0.0,
    "rationale": "情緒評分依據"
  },
  "data_sources": ["來源 1", "來源 2"]
}

欄位說明：

• confidence_index：市場信心指數（0-100，100 = 極度樂觀）
• fear_greed_index：恐慌/貪婪指數（0-100，0 = 極度恐慌，100 = 極度貪婪）
• session：盤前/盤後/盤中，標示這份情報的時間區段

---

Market_Structure_Report.json

產出者：市場結構研究員（market-structure-researcher）

{
  "date": "2026-04-10",
  "market": "BTC/USDT",
  "timeframes_analyzed": ["D1", "H4", "H1"],
  "structure": {
    "trend": "bullish|bearish|ranging",
    "mss_detected": true,
    "mss_details": "MSS 發生的位置與時間描述",
    "key_levels": [
      {
        "type": "OB|FVG|POI|support|resistance",
        "price": 0,
        "timeframe": "H4",
        "tested": false,
        "notes": "補充說明"
      }
    ]
  },
  "liquidity_zones": [
    {
      "type": "buy_side|sell_side",
      "range": [0, 0],
      "significance": "high|medium|low",
      "notes": "補充說明"
    }
  ],
  "entry_exit_suggestion": {
    "suggested_direction": "long|short|neutral",
    "ideal_entry_zone": [0, 0],
    "stop_loss_zone": [0, 0],
    "take_profit_targets": [0, 0, 0],
    "confidence": 0.0,
    "rationale": "進出場建議依據"
  }
}

欄位說明：

• entry_exit_suggestion：基於市場結構的進出場建議（僅供策略師參考，不作為最終決策）
• confidence：對進出場建議的信心度（0.0-1.0）

---

Bullish_Brief.json

產出者：多方研究員（bullish-researcher）

{
  "date": "2026-04-10",
  "market": "BTC/USDT",
  "thesis": "核心做多論點（一句話）",
  "arguments": [
    {
      "point": "論點",
      "evidence": "支持證據",
      "confidence": 0.0
    }
  ],
  "key_levels": [
    {
      "type": "support|resistance|entry|target",
      "price": 0,
      "timeframe": "H4",
      "evidence": "為什麼這個價位重要"
    }
  ],
  "catalysts": ["潛在催化劑 1", "潛在催化劑 2"],
  "entry_exit_suggestion": {
    "suggested_entry": [0, 0],
    "stop_loss": 0,
    "take_profit": [0, 0],
    "risk_reward": 0.0,
    "rationale": "進出場依據"
  },
  "invalidation": "什麼條件下做多論點失效",
  "confidence_index": 0.0,
  "data_sources": ["來源 1", "來源 2"]
}

欄位說明：

• confidence_index：對做多論點的整體信心度（0.0-1.0）
• entry_exit_suggestion：多方視角的進出場建議

---

Bearish_Brief.json

產出者：空方研究員（bearish-researcher）

{
  "date": "2026-04-10",
  "market": "BTC/USDT",
  "thesis": "核心做空論點（一句話）",
  "arguments": [
    {
      "point": "論點",
      "evidence": "支持證據",
      "confidence": 0.0
    }
  ],
  "key_levels": [
    {
      "type": "support|resistance|entry|target",
      "price": 0,
      "timeframe": "H4",
      "evidence": "為什麼這個價位重要"
    }
  ],
  "risk_factors": ["風險因素 1", "風險因素 2"],
  "entry_exit_suggestion": {
    "suggested_entry": [0, 0],
    "stop_loss": 0,
    "take_profit": [0, 0],
    "risk_reward": 0.0,
    "rationale": "進出場依據"
  },
  "invalidation": "什麼條件下做空論點失效",
  "confidence_index": 0.0,
  "data_sources": ["來源 1", "來源 2"]
}

---

Strategy_Thesis.json

產出者：量化策略師（quant-strategist）

{
  "date": "2026-04-10",
  "market": "BTC/USDT",
  "direction": "long|short|neutral",
  "thesis": "收斂後的策略論點",
  "market_indicators": {
    "confidence_index": 0.0,
    "fear_greed_index": 0.0,
    "market_regime": "trending|ranging|volatile|calm"
  },
  "entry_plan": {
    "entry_zone": [0, 0],
    "entry_trigger": "觸發進場的條件描述",
    "order_type": "limit|market|stop_limit"
  },
  "exit_plan": {
    "stop_loss": 0,
    "stop_loss_type": "fixed|trailing|structure_based",
    "take_profit_targets": [
      { "price": 0, "portion_pct": 50, "rationale": "第一目標依據" },
      { "price": 0, "portion_pct": 50, "rationale": "第二目標依據" }
    ]
  },
  "risk_management": {
    "risk_reward": 0.0,
    "position_size_pct": 0.0,
    "max_drawdown_pct": 0.0,
    "bias_check": "confirmed|conflicting",
    "bull_confidence": 0.0,
    "bear_confidence": 0.0
  },
  "invalidation": "什麼條件下整個策略失效",
  "requires_backtest": true,
  "urgency": "immediate|today|this_week|no_rush",
  "summary": "給董事長看的一段話摘要"
}

欄位說明：

• confidence_index：策略師對這個策略的整體信心度（0.0-1.0，綜合多空信心）
• fear_greed_index：當前市場恐慌/貪婪程度（0-100）
• market_regime：當前市場狀態分類
• entry_plan：完整的進場計畫（區間、觸發條件、下單方式）
• exit_plan：完整的出場計畫（停損、分批止盈）

---

Review_Report.json

產出者：審查員（reviewer）

{
  "date": "2026-04-10",
  "reviewed_artifact": "Strategy_Thesis.json",
  "reviewed_agent": "quant-strategist",
  "verdict": "pass|revise|block",
  "score": 0.0,
  "checklist": {
    "schema_complete": true,
    "risk_management_valid": true,
    "data_sources_verified": true,
    "confidence_reasonable": true,
    "no_overfitting_risk": true
  },
  "issues": [
    {
      "severity": "critical|major|minor",
      "field": "對應的欄位名",
      "description": "問題描述",
      "suggestion": "修改建議"
    }
  ],
  "revise_target": "quant-strategist|bullish-researcher|bearish-researcher|...",
  "revise_round": 1,
  "summary": "審查結論摘要"
}

---

Backtest_Report.json

產出者：回測工程師（quant-engineer）

{
  "date": "2026-04-10",
  "strategy_ref": "Strategy_Thesis.json",
  "platform": "pine_script|python|other",
  "backtest_period": {
    "start": "2025-01-01",
    "end": "2026-04-10",
    "data_source": "資料來源"
  },
  "parameters": {
    "initial_capital": 10000,
    "commission_pct": 0.1,
    "slippage_pct": 0.05
  },
  "results": {
    "total_trades": 0,
    "winning_trades": 0,
    "losing_trades": 0,
    "win_rate": 0.0,
    "profit_factor": 0.0,
    "net_profit": 0.0,
    "net_profit_pct": 0.0,
    "max_drawdown_pct": 0.0,
    "max_drawdown_duration": "天數",
    "sharpe_ratio": 0.0,
    "sortino_ratio": 0.0,
    "avg_rr": 0.0,
    "avg_holding_period": "小時/天"
  },
  "equity_curve_description": "權益曲線特徵描述",
  "code_artifact": "程式碼檔案路徑或內容",
  "notes": "回測備註與注意事項"
}

---

Data_Analysis_Report.json

產出者：資料分析師（data-analyst）

{
  "date": "2026-04-10",
  "report_type": "daily|weekly|backtest_analysis",
  "analyzed_artifact": "Backtest_Report.json",
  "metrics": {
    "total_trades": 0,
    "win_rate": 0.0,
    "profit_factor": 0.0,
    "max_drawdown_pct": 0.0,
    "sharpe_ratio": 0.0,
    "sortino_ratio": 0.0,
    "avg_rr": 0.0,
    "calmar_ratio": 0.0
  },
  "distribution_analysis": {
    "profit_distribution": "盈虧分布特徵",
    "trade_duration_distribution": "持倉時間分布特徵",
    "time_of_day_performance": "不同時段表現差異"
  },
  "risk_flags": [
    {
      "type": "overfitting|curve_fitting|small_sample|outlier_dependency|other",
      "description": "風險描述",
      "severity": "high|medium|low"
    }
  ],
  "insights": ["洞察 1", "洞察 2"],
  "recommendation": "proceed|adjust|reject",
  "recommendation_rationale": "建議依據",
  "summary": "分析結論摘要"
}

---

Task_Spec.json

產出者：執行長（ceo）

{
  "task_id": "TASK-001",
  "title": "任務標題",
  "assignee": "agent-slug",
  "assignee_title": "Agent 職稱",
  "team": "team-slug",
  "priority": "critical|high|medium|low",
  "description": "詳細任務描述",
  "context": "任務背景與相關資訊",
  "expected_output": "預期輸出的 Schema 名稱",
  "dependencies": ["前置任務 ID"],
  "deadline": "2026-04-10T18:00:00+08:00",
  "requires_review": true,
  "requires_hitl": false
}

---

Final_Decision_Packet.json

產出者：執行長（ceo）

{
  "date": "2026-04-10",
  "pipeline": "quant|marketing|content",
  "title": "決策包標題",
  "summary": "給董事長的摘要（200 字內）",
  "recommendation": "proceed|hold|abort",
  "key_findings": [
    {
      "source_agent": "agent-slug",
      "source_title": "Agent 職稱",
      "finding": "關鍵發現"
    }
  ],
  "risk_assessment": {
    "overall_risk": "high|medium|low",
    "confidence_index": 0.0,
    "fear_greed_index": 0.0,
    "key_risks": ["風險 1", "風險 2"]
  },
  "action_items": [
    {
      "action": "需要執行的動作",
      "requires_approval": true
    }
  ],
  "attached_reports": ["Strategy_Thesis.json", "Review_Report.json", "Data_Analysis_Report.json"]
}

---

Meeting_Summary.json

產出者：秘書（secretary）

{
  "date": "2026-04-10",
  "summary_type": "daily|weekly|meeting|incident",
  "participants": [
    { "agent": "agent-slug", "title": "Agent 職稱" }
  ],
  "key_decisions": [
    {
      "decision": "決策內容",
      "decided_by": "agent-slug",
      "rationale": "決策依據"
    }
  ],
  "action_items": [
    {
      "assignee": "agent-slug",
      "assignee_title": "Agent 職稱",
      "task": "待辦內容",
      "deadline": "2026-04-11",
      "status": "pending|in_progress|done"
    }
  ],
  "highlights": ["今日重點 1", "今日重點 2"],
  "issues": ["待解決問題 1"],
  "notes": "其他備註"
}

---

State_Diff.json

產出者：秘書（secretary）

{
  "date": "2026-04-10",
  "compared_to": "2026-04-09",
  "changes": [
    {
      "category": "strategy|personnel|schedule|system|other",
      "description": "變更描述",
      "changed_by": "agent-slug",
      "impact": "high|medium|low"
    }
  ],
  "new_items": ["新增的事項"],
  "resolved_items": ["已解決的事項"],
  "ongoing_items": ["持續進行中的事項"]
}

---

Todo_List.json

產出者：秘書（secretary）

{
  "date": "2026-04-10",
  "items": [
    {
      "id": "TODO-001",
      "title": "待辦標題",
      "assignee": "agent-slug",
      "assignee_title": "Agent 職稱",
      "priority": "critical|high|medium|low",
      "status": "pending|in_progress|blocked|done",
      "created_date": "2026-04-09",
      "due_date": "2026-04-11",
      "notes": "備註"
    }
  ]
}

---

Brand_Strategy_Plan.json

產出者：策略總監（strategy-director）

{
  "date": "2026-04-10",
  "version": "1.0",
  "usp": "獨特賣點定義",
  "brand_narrative": "品牌故事與核心訊息",
  "brand_voice": {
    "tone": "語氣描述",
    "personality": "品牌人格特質",
    "do": ["應該做的"],
    "dont": ["不應該做的"]
  },
  "target_audience": [
    {
      "segment": "受眾分群名稱",
      "demographics": "人口統計描述",
      "pain_points": ["痛點"],
      "motivations": ["動機"]
    }
  ],
  "campaigns": [
    {
      "name": "活動名稱",
      "channel": "投放管道",
      "objective": "活動目標",
      "kpi": "衡量指標",
      "budget_allocation_pct": 0.0
    }
  ],
  "funnel_strategy": {
    "awareness": "認知階段策略",
    "consideration": "考慮階段策略",
    "conversion": "轉換階段策略",
    "retention": "留存階段策略"
  }
}

---

Growth_Strategy_Plan.json

產出者：策略總監（strategy-director）

{
  "date": "2026-04-10",
  "growth_model": "成長模型描述",
  "channels": [
    {
      "channel": "管道名稱",
      "strategy": "策略描述",
      "expected_cac": 0.0,
      "expected_ltv": 0.0,
      "priority": "high|medium|low"
    }
  ],
  "experiments": [
    {
      "hypothesis": "假設",
      "test_method": "測試方法",
      "success_metric": "成功指標",
      "duration": "測試期間"
    }
  ],
  "milestones": [
    {
      "target": "目標描述",
      "deadline": "2026-06-30",
      "status": "planned|in_progress|achieved"
    }
  ]
}

---

Market_Research_Brief.json

產出者：市場研究員（market-researcher）

{
  "date": "2026-04-10",
  "report_type": "daily_morning|daily_evening|weekly",
  "market_overview": "市場概況摘要",
  "competitors": [
    {
      "name": "競品名稱",
      "recent_moves": "近期動態",
      "threat_level": "high|medium|low"
    }
  ],
  "consumer_insights": [
    {
      "insight": "消費者洞察",
      "source": "來源",
      "actionable": true
    }
  ],
  "trends": [
    {
      "trend": "趨勢描述",
      "direction": "growing|stable|declining",
      "relevance": "high|medium|low"
    }
  ],
  "opportunities": ["機會 1", "機會 2"],
  "threats": ["威脅 1", "威脅 2"],
  "data_sources": ["來源 1", "來源 2"]
}

---

Market_Analysis_Report.json

產出者：市場研究員（market-researcher）

{
  "date": "2026-04-10",
  "analysis_period": "2026-04-07 ~ 2026-04-10",
  "market_size": {
    "tam": "Total Addressable Market",
    "sam": "Serviceable Addressable Market",
    "som": "Serviceable Obtainable Market"
  },
  "swot": {
    "strengths": ["優勢"],
    "weaknesses": ["劣勢"],
    "opportunities": ["機會"],
    "threats": ["威脅"]
  },
  "competitive_landscape": "競爭格局分析",
  "recommendations": ["建議 1", "建議 2"],
  "data_sources": ["來源 1", "來源 2"]
}

---

Ads_Performance_Report.json

產出者：投放分析師（ads-analyst）

{
  "date": "2026-04-10",
  "report_period": "2026-04-01 ~ 2026-04-10",
  "platforms": [
    {
      "platform": "平台名稱",
      "metrics": {
        "impressions": 0,
        "clicks": 0,
        "ctr": 0.0,
        "conversions": 0,
        "cvr": 0.0,
        "cpl": 0.0,
        "cpa": 0.0,
        "roas": 0.0,
        "spend": 0.0
      }
    }
  ],
  "top_creatives": [
    {
      "creative_id": "素材 ID",
      "description": "素材描述",
      "ctr": 0.0,
      "cvr": 0.0
    }
  ],
  "ab_test_results": [
    {
      "test_name": "測試名稱",
      "winner": "A|B",
      "lift_pct": 0.0,
      "confidence": 0.0
    }
  ],
  "budget_utilization_pct": 0.0,
  "recommendations": ["優化建議 1", "優化建議 2"]
}

---

Creative_Brief.json

產出者：創意總監（creative-director）

{
  "date": "2026-04-10",
  "project": "專案名稱",
  "objective": "創意目標",
  "target_audience": "目標受眾描述",
  "key_message": "核心訊息",
  "tone_and_mood": "語氣與氛圍",
  "visual_direction": {
    "style": "視覺風格",
    "color_palette": ["色碼"],
    "references": ["參考連結或描述"]
  },
  "deliverables": [
    {
      "type": "banner|social_post|video|landing_page",
      "dimensions": "尺寸",
      "quantity": 1,
      "notes": "備註"
    }
  ],
  "brand_guidelines_ref": "品牌規範引用",
  "deadline": "2026-04-15"
}

---

Storyboard_Brief.json

產出者：創意總監（creative-director）

{
  "date": "2026-04-10",
  "project": "專案名稱",
  "video_type": "ad|explainer|testimonial|brand",
  "duration_seconds": 30,
  "scenes": [
    {
      "scene_number": 1,
      "duration_seconds": 5,
      "visual": "畫面描述",
      "audio": "音效/音樂/旁白描述",
      "text_overlay": "畫面文字",
      "transition": "cut|fade|slide"
    }
  ],
  "cta": "Call to Action",
  "notes": "備註"
}

---

Copywriting_Pack.json

產出者：文案撰寫員（copywriter）

{
  "date": "2026-04-10",
  "project": "專案名稱",
  "brand_voice_ref": "品牌語氣引用",
  "pieces": [
    {
      "type": "headline|body|cta|social_post|email|blog|landing_page",
      "platform": "投放平台",
      "headline": "標題",
      "body": "內文",
      "cta": "Call to Action",
      "seo_keywords": ["關鍵字"],
      "character_count": 0,
      "variations": ["變體 A", "變體 B"]
    }
  ],
  "notes": "備註"
}

---

Video_Script_Pack.json

產出者：文案撰寫員（copywriter）

{
  "date": "2026-04-10",
  "project": "專案名稱",
  "video_type": "ad|explainer|testimonial|brand",
  "duration_seconds": 30,
  "script": [
    {
      "timecode": "00:00-00:05",
      "speaker": "旁白|角色名",
      "dialogue": "台詞/旁白內容",
      "visual_cue": "對應的畫面提示",
      "notes": "備註"
    }
  ],
  "cta": "Call to Action",
  "tone": "語氣描述",
  "notes": "備註"
}