vault: add comprehensive Trading Agents usage guide with API reference and quant tips

2 - Projects/Trading-Agents/Trading Agents 使用指南.md

@@ -0,0 +1,293 @@
+---
+created: "2026-03-21"
+type: resource
+status: active
+tags: [trading, multi-agent, openclaw, openbb, guide, investment]
+---
+
+# Trading Agents 使用指南
+
+如何使用投资分析 Agent 系统和 OpenBB Invest API 进行专业级投资分析。
+
+---
+
+## 一、系统架构总览
+
+```
+         你 (Discord Stock Guild)
+              │
+              ▼
+     ┌─────────────────┐
+     │ invest-analyst   │  ← 编排者 + 最终裁判
+     │ (stock bot)      │     唯一对外输出的 agent
+     └────────┬────────┘
+              │ sessions_spawn
+     ┌────────┼────────────────┐
+     ▼        ▼        ▼       ▼
+  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
+  │ Bull │ │ Bear │ │ Hawk │ │ Dove │
+  │ 🐂   │ │ 🐻   │ │ 🦅   │ │ 🕊️   │
+  └──────┘ └──────┘ └──────┘ └──────┘
+  后台运行   后台运行   后台运行   后台运行
+  (无Discord输出)
+
+  数据来源：openbb-invest-api (K8s: invest-api.k8s.home)
+            132+ 端点, 覆盖技术/基本面/情感/宏观/量化
+```
+
+### Agent 角色
+
+| Agent | 身份 | 职责 | Discord |
+|-------|------|------|---------|
+| **invest-analyst** | 编排者/裁判 | 接收用户指令，收集数据，调度辩论，输出最终裁决 | ✅ 在线，响应用户 |
+| **invest-bull** | 多方研究员 | 构建看多论点，引用数据支持上行空间 | ❌ 后台 |
+| **invest-bear** | 空方研究员 | 构建看空论点，揭示风险和高估 | ❌ 后台 |
+| **invest-hawk** | 激进风控 | 大仓位、紧止损、追求超额收益 | ❌ 后台 |
+| **invest-dove** | 保守风控 | 小仓位、分批建仓、保护本金 | ❌ 后台 |
+
+### 通信协议
+
+- **用户 → invest-analyst**：Discord 消息（Stock Guild #general）
+- **invest-analyst → 辩论 agent**：`sessions_spawn`（后台，非阻塞）
+- **辩论 agent → invest-analyst**：自动 announce（结果推送回来）
+- **辩论 agent → Discord**：❌ 不输出（Discord 已禁用）
+
+---
+
+## 二、可用的 Skill（7 个）
+
+### 分析类 Skill
+
+| Skill | 触发方式 | 用途 | 端点数 |
+|-------|---------|------|--------|
+| **trade-analyze** | `/trade-analyze {TICKER}` | 完整辩论分析 → BUY/SELL/HOLD | 8 |
+| **market-analysis** | `/market-analysis {TICKER}` | 技术面分析（14种指标） | 15 |
+| **fundamental-analysis** | `/fundamental-analysis {TICKER}` | 基本面+量化风险 | 16 |
+| **sentiment-analysis** | `/sentiment-analysis {TICKER}` | 情感+smart money | 16 |
+| **macro-analysis** | `/macro-analysis {TICKER}` | 宏观环境+利率+衰退指标 | 23 |
+
+### 组合类 Skill
+
+| Skill | 触发方式 | 用途 | 端点数 |
+|-------|---------|------|--------|
+| **portfolio-review** | `/portfolio-review` | 组合优化+相关性+聚类 | 6+ |
+| **strategy-backtest** | `/strategy-backtest {TICKER}` | 策略回测验证 | 4 |
+
+### 通用 Skill
+
+| Skill | 用途 |
+|-------|------|
+| **invest-api** | 直接调用任何 API 端点（132+），用于快速查询 |
+
+---
+
+## 三、使用场景
+
+### 场景 1：快速查询（直接回答，不触发辩论）
+
+```
+帮我看看 AAPL 现在什么价格
+NVDA 的 RSI 多少
+最近有什么股票在涨
+下周有哪些公司发财报
+美国 CPI 最新数据
+```
+
+invest-analyst 直接用 invest-api skill 回答，不调用辩论 agent。
+
+### 场景 2：深度辩论分析
+
+```
+/trade-analyze NVDA
+帮我深度分析一下 AMZN 要不要买
+全面分析 TSLA
+```
+
+完整流程：
+1. invest-analyst 收集 8 类数据（summary, technical, sentiment, macro, upgrades, shorts, CAPM, Sortino）
+2. spawn invest-bull → 构建 Bull Case（等待 announce）
+3. spawn invest-bear → 反驳 Bull（等待 announce）
+4. spawn invest-bull → 最终反驳 Bear（等待 announce）
+5. spawn invest-hawk → 激进风控评估（等待 announce）
+6. spawn invest-dove → 保守风控评估（等待 announce）
+7. invest-analyst 综合裁决 → 输出 Trading Verdict
+
+**输出**：一份完整的 Trading Verdict，包含 BUY/SELL/HOLD 决策、入场计划、Bull/Bear 核心论点、Hawk/Dove 风控建议。
+
+### 场景 3：单维度深入分析
+
+```
+/market-analysis NVDA     ← 只看技术面（14种指标全开）
+/fundamental-analysis NVDA ← 只看基本面+量化风险
+/sentiment-analysis NVDA   ← 只看情感+smart money
+/macro-analysis NVDA       ← 只看宏观环境
+```
+
+不触发辩论，直接生成结构化报告。
+
+### 场景 4：投资组合管理
+
+```
+/portfolio-review          ← 分析我的持仓（从 MEMORY.md 读取）
+帮我看看我的组合怎么优化
+AAPL 和 MSFT 相关性高吗
+帮我找和 NVDA 类似的股票
+```
+
+使用 HRP 优化、相关性矩阵、t-SNE 聚类、相似度搜索。
+
+### 场景 5：策略回测验证
+
+```
+/strategy-backtest NVDA    ← 回测 SMA 交叉 + RSI + 买入持有
+如果我用 RSI 策略买 AAPL 一年回报怎么样
+```
+
+对比 3 种策略 vs 买入持有基准，输出 Sharpe、最大回撤、胜率。
+
+---
+
+## 四、OpenBB Invest API 端点速查
+
+### 个股分析（用 symbol 查询）
+
+| 类别 | 关键端点 | 专业用法 |
+|------|---------|---------|
+| **行情** | `/stock/{s}/summary` | 一次拿到 quote+profile+metrics+financials |
+| **技术** | `/stock/{s}/technical` | 复合指标 + 14 种独立指标 |
+| **风险** | `/stock/{s}/capm` | Alpha = 超额收益，Beta = 市场敏感度 |
+| **风险** | `/stock/{s}/sortino` | 下行风险（比 Sharpe 更好） |
+| **风险** | `/stock/{s}/normality` | 正态性检验 → 决定用 Sharpe 还是 Omega |
+| **风险** | `/stock/{s}/rolling/skew` | 负偏度 = 崩盘风险上升 |
+| **情感** | `/stock/{s}/sentiment` | 多源复合评分 |
+| **内幕** | `/stock/{s}/insider-trades` | CEO 买 = 强信号 |
+| **做空** | `/stock/{s}/shorts/interest` | Days to cover > 5 = 潜在挤空 |
+| **暗池** | `/darkpool/{s}/otc` | 机构大宗交易活动 |
+
+### 宏观分析（全市场视角）
+
+| 类别 | 关键端点 | 专业用法 |
+|------|---------|---------|
+| **利率** | `/fixed-income/yield-curve` | 倒挂 = 最强衰退预警 |
+| **利率** | `/fixed-income/spreads` | 信用利差扩大 = 市场压力 |
+| **通胀** | `/macro/pce` | Fed 偏好指标，比 CPI 更重要 |
+| **衰退** | `/economy/surveys/sloos` | 最强衰退领先指标（6-12月提前） |
+| **衰退** | `/macro/cli` | < 100 且下降 = 衰退警告 |
+| **恐慌** | `/macro/overview` → VIX | > 30 = 恐慌（反向买入信号） |
+| **估值** | `/index/sp500-multiples` | 历史 PE 对比判断市场贵不贵 |
+
+### 量化风险指标使用指南
+
+```
+Sharpe > 1.0     → 好（风险调整后正收益）
+Sortino > Sharpe → 好（正偏度，上行多于下行）
+Omega > 1.0      → 好（收益概率 > 损失概率）
+
+Normality p < 0.05 → 非正态 → Sharpe/VaR 不可靠，用 Sortino/Omega
+Unit Root p < 0.05 → 有趋势 → 技术分析有效
+Unit Root p > 0.05 → 随机游走 → 别信技术指标
+
+Rolling Skew < 0 且下降 → 崩盘风险上升 → 减仓
+Rolling Kurtosis > 3 且上升 → 极端事件概率增加 → 加宽止损
+```
+
+### 组合与回测
+
+| 类别 | 关键端点 | 专业用法 |
+|------|---------|---------|
+| **优化** | `/portfolio/optimize` | HRP 权重（比等权更好的风险调整） |
+| **风险** | `/portfolio/risk-parity` | 每个持仓贡献相等风险 |
+| **相关性** | `/portfolio/correlation` | > 0.8 = 冗余，< 0.2 = 好的分散 |
+| **聚类** | `/portfolio/cluster` | 发现隐藏的相关性（同一类型的股票） |
+| **回测** | `/backtest/sma-crossover` | 趋势跟踪策略验证 |
+| **回测** | `/backtest/rsi` | 均值回归策略验证 |
+| **回测** | `/backtest/momentum` | 多股轮动策略验证 |
+
+---
+
+## 五、辩论流程编排细节
+
+### sessions_spawn 调用链
+
+```
+invest-analyst
+  │
+  ├─ spawn invest-bull (task: "build bull case with data: ...")
+  │   └─ announce → invest-analyst 收到 Bull 论点
+  │
+  ├─ spawn invest-bear (task: "counter Bull: {Bull论点}, data: ...")
+  │   └─ announce → invest-analyst 收到 Bear 论点
+  │
+  ├─ spawn invest-bull (task: "final rebuttal to Bear: {Bear论点}")
+  │   └─ announce → invest-analyst 收到 Bull 最终反驳
+  │
+  ├─ spawn invest-hawk (task: "aggressive risk for proposal: {方案}")
+  │   └─ announce → invest-analyst 收到 Hawk 评估
+  │
+  ├─ spawn invest-dove (task: "conservative risk, Hawk said: {Hawk评估}")
+  │   └─ announce → invest-analyst 收到 Dove 评估
+  │
+  └─ 综合 5 个 announce → 输出最终 Trading Verdict
+```
+
+### 关键约束
+
+- **最多 5 次 spawn**：Bull(2) + Bear(1) + Hawk(1) + Dove(1)
+- **顺序执行**：等待每个 announce 后才 spawn 下一个
+- **超时处理**：spawn 超时 → 跳过，降低置信度
+- **单一输出**：只有 invest-analyst 发到 Discord
+
+### 为什么不用 sessions_send
+
+| 问题 | sessions_send | sessions_spawn |
+|------|--------------|----------------|
+| Gateway 死锁 | ❌ 同进程内自连超时 | ✅ 独立 lane |
+| 轮次控制 | ⚠️ 需要 REPLY_SKIP | ✅ 一次性任务 |
+| Discord 输出 | ⚠️ 可能泄露到频道 | ✅ 完全后台 |
+
+详见 [[Trading Agents 调试与优化记录]] 的 Gateway WebSocket 修复章节。
+
+---
+
+## 六、日常使用 Tips
+
+### 快速决策流程
+
+```
+1. 先快速查看：帮我看看 NVDA 现在怎么样
+2. 如果感兴趣：/trade-analyze NVDA（完整辩论）
+3. 验证决策：/strategy-backtest NVDA（回测确认）
+4. 检查组合影响：/portfolio-review（看相关性和权重）
+```
+
+### 每日简报（自动）
+
+invest-analyst 有 cron 任务，工作日 08:00 自动生成：
+- 组合 P&L 摘要
+- 宏观概览（Fed rate, VIX, S&P 500）
+- 持仓新闻和情感变化
+- 即将到来的财报
+- BUY/SELL 信号
+
+### 记忆系统
+
+invest-analyst 会记住：
+- 你的持仓（MEMORY.md）
+- 每次分析的决策（memory/YYYY-MM-DD.md）
+- 历史建议和胜率
+
+告诉它更新持仓：
+```
+我买了 50 股 NVDA，成本 $170
+我卖掉了 AAPL 的全部持仓
+```
+
+---
+
+## Related
+
+- [[Trading Agents 混合架构方案]]
+- [[Trading Agents 部署记录]]
+- [[Trading Agents 调试与优化记录]]
+- [[TradingAgents 原始架构分析]]
+- [[OpenClaw 部署配置分析]]