@openfinclaw/openfinclaw-strategy 2026.4.2 → 2026.4.9

package/src/tournament/orchestrator.ts

@@ -0,0 +1,238 @@
+/**
+ * Tournament orchestrator — code-driven daily tournament flow.
+ * Deterministic orchestration: cron → ticker → spawn subagents → collect → format → send.
+ * LLM only handles analysis inside each subagent.
+ * @module openfinclaw/tournament/orchestrator
+ */
+import type { TournamentDb, TournamentStrategy } from "./db.js";
+import { type TournamentRole, buildAgentTask } from "./prompts.js";
+
+// ── Types ─────────────────────────────────────────────────────────────────
+
+export interface TournamentConfig {
+  /** Maximum concurrent tournament agents (default: 3) */
+  maxAgents: number;
+  /** Subagent timeout in seconds (default: 600 = 10 min) */
+  subagentTimeoutSeconds: number;
+  /** Consecutive skips before alerting (default: 3) */
+  alertAfterSkips: number;
+  /** Session key for sending messages */
+  sessionKey: string;
+}
+
+export interface SpawnResult {
+  status: "accepted" | "forbidden" | "error";
+  childSessionKey?: string;
+  runId?: string;
+  error?: string;
+}
+
+export interface OrchestratorDeps {
+  db: TournamentDb;
+  /** Get today's top mover ticker symbol */
+  selectTicker: () => Promise<string>;
+  /** Spawn a subagent session */
+  spawnSubagent: (params: {
+    task: string;
+    label: string;
+    runTimeoutSeconds: number;
+  }) => Promise<SpawnResult>;
+  /** Push a message to the user's channel */
+  enqueueSystemEvent: (text: string, options: { sessionKey: string; contextKey?: string }) => void;
+  /** Wake the agent to deliver the message */
+  requestHeartbeatNow: (options?: { reason?: string; sessionKey?: string }) => void;
+  /** Wait for subagent results (poll DB for tournament_result submissions) */
+  waitForResults: (
+    roundId: string,
+    expectedCount: number,
+    timeoutMs: number,
+  ) => Promise<TournamentStrategy[]>;
+  logger: {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+  config: TournamentConfig;
+}
+
+// ── Orchestrator ──────────────────────────────────────────────────────────
+
+export class TournamentOrchestrator {
+  constructor(private deps: OrchestratorDeps) {}
+
+  /**
+   * Run the daily tournament. Called by cron hook.
+   * Pure code flow — no LLM involvement in orchestration.
+   */
+  async runDailyTournament(): Promise<void> {
+    const { db, config, logger } = this.deps;
+
+    // 1. Idempotent check
+    const today = new Date().toISOString().slice(0, 10);
+    const roundId = `round-${today.replace(/-/g, "")}`;
+    const existing = db.getRound(roundId);
+    if (existing && existing.status !== "pending") {
+      logger.info(`[tournament] Round ${roundId} already ${existing.status}, skipping`);
+      return;
+    }
+
+    // 2. Select today's ticker
+    let ticker: string;
+    try {
+      ticker = await this.deps.selectTicker();
+    } catch (err) {
+      logger.error(`[tournament] Failed to select ticker: ${err}`);
+      db.createRound({ id: roundId, date: today, ticker: "UNKNOWN" });
+      db.updateRoundStatus(roundId, "skipped", `Ticker selection failed: ${err}`);
+      this.checkConsecutiveFailures();
+      return;
+    }
+
+    // 3. Create round record
+    db.createRound({ id: roundId, date: today, ticker });
+    logger.info(`[tournament] Starting round ${roundId} for ${ticker}`);
+
+    // 4. Spawn 3 subagents in parallel
+    const roles: TournamentRole[] = ["bull", "bear", "contrarian"];
+    const spawnResults = await Promise.allSettled(
+      roles.map((role) =>
+        this.deps.spawnSubagent({
+          task: buildAgentTask(role, ticker, roundId),
+          label: `tournament-${role}`,
+          runTimeoutSeconds: config.subagentTimeoutSeconds,
+        }),
+      ),
+    );
+
+    // 5. Check spawn results
+    const spawned: Array<{ role: TournamentRole; result: SpawnResult }> = [];
+    for (let i = 0; i < roles.length; i++) {
+      const r = spawnResults[i];
+      if (r.status === "fulfilled" && r.value.status === "accepted") {
+        spawned.push({ role: roles[i], result: r.value });
+        logger.info(`[tournament] ${roles[i]} agent spawned: ${r.value.runId ?? "ok"}`);
+      } else {
+        const reason =
+          r.status === "rejected"
+            ? String(r.reason)
+            : ((r.value as SpawnResult).error ?? r.value.status);
+        logger.warn(`[tournament] ${roles[i]} agent spawn failed: ${reason}`);
+      }
+    }
+
+    if (spawned.length < 2) {
+      db.updateRoundStatus(roundId, "skipped", `Only ${spawned.length}/3 agents spawned`);
+      logger.warn(`[tournament] Round ${roundId} skipped: insufficient agents`);
+      this.checkConsecutiveFailures();
+      return;
+    }
+
+    // 6. Wait for subagent results (they call tournament_result tool)
+    const timeoutMs = config.subagentTimeoutSeconds * 1000 + 30_000; // extra 30s buffer
+    let strategies: TournamentStrategy[];
+    try {
+      strategies = await this.deps.waitForResults(roundId, spawned.length, timeoutMs);
+    } catch (err) {
+      logger.error(`[tournament] Result collection failed: ${err}`);
+      db.updateRoundStatus(roundId, "skipped", `Result collection failed: ${err}`);
+      this.checkConsecutiveFailures();
+      return;
+    }
+
+    if (strategies.length < 2) {
+      db.updateRoundStatus(roundId, "skipped", `Only ${strategies.length} strategies submitted`);
+      logger.warn(`[tournament] Round ${roundId} skipped: insufficient strategies`);
+      this.checkConsecutiveFailures();
+      return;
+    }
+
+    // 7. Format and send results
+    const message = this.formatMessage(ticker, roundId, strategies);
+    this.deps.enqueueSystemEvent(message, {
+      sessionKey: config.sessionKey,
+      contextKey: `tournament:${roundId}:result`,
+    });
+    this.deps.requestHeartbeatNow({ reason: "tournament-result", sessionKey: config.sessionKey });
+
+    db.updateRoundStatus(roundId, "completed");
+    logger.info(`[tournament] Round ${roundId} completed with ${strategies.length} strategies`);
+  }
+
+  /** Check for consecutive failures and send alert if threshold reached. */
+  private checkConsecutiveFailures(): void {
+    const { db, config, logger } = this.deps;
+    const consecutiveSkips = db.countConsecutiveSkips();
+    if (consecutiveSkips >= config.alertAfterSkips) {
+      const alertMsg =
+        `⚠️ Strategy Tournament 已连续 ${consecutiveSkips} 天跳过。\n` +
+        "请检查 DeepAgent API 配置和网络连接。";
+      this.deps.enqueueSystemEvent(alertMsg, {
+        sessionKey: config.sessionKey,
+        contextKey: `tournament:alert:consecutive-skip-${consecutiveSkips}`,
+      });
+      this.deps.requestHeartbeatNow({ reason: "tournament-alert", sessionKey: config.sessionKey });
+      logger.warn(`[tournament] Alert sent: ${consecutiveSkips} consecutive skips`);
+    }
+  }
+
+  /** Format tournament results as a human-readable message. */
+  private formatMessage(ticker: string, roundId: string, strategies: TournamentStrategy[]): string {
+    const header = `🏆 策略锦标赛 — ${ticker} (${roundId})\n${"═".repeat(50)}`;
+
+    const roleEmoji: Record<string, string> = {
+      bull: "🐂",
+      bear: "🐻",
+      contrarian: "🔄",
+    };
+
+    const sections = strategies.map((s) => {
+      const emoji = roleEmoji[s.agent_name] ?? "📊";
+      const lines = [`${emoji} ${s.agent_name.toUpperCase()} (信心: ${s.confidence}%)`];
+      lines.push(s.thesis);
+      if (s.entry_price != null)
+        lines.push(`入场: ${s.entry_price} | 出场: ${s.exit_price} | 止损: ${s.stop_loss}`);
+      if (s.sharpe != null)
+        lines.push(
+          `Sharpe: ${s.sharpe.toFixed(2)} | 回撤: ${((s.max_drawdown ?? 0) * 100).toFixed(1)}% | 收益: ${((s.total_return ?? 0) * 100).toFixed(1)}%`,
+        );
+      return lines.join("\n");
+    });
+
+    const footer = [
+      "─".repeat(50),
+      "选择你认为最佳的策略：",
+      "  /pick bull | /pick bear | /pick contrarian",
+      "查看排行榜: /tournament leaderboard",
+    ].join("\n");
+
+    return [header, ...sections, footer].join("\n\n");
+  }
+}
+
+/**
+ * Default waitForResults implementation: poll DB every 15 seconds.
+ * Subagents call tournament_result tool which writes to DB.
+ */
+export function createDbPoller(db: TournamentDb): OrchestratorDeps["waitForResults"] {
+  return async (
+    roundId: string,
+    expectedCount: number,
+    timeoutMs: number,
+  ): Promise<TournamentStrategy[]> => {
+    const pollInterval = 15_000;
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+      const strategies = db.getStrategies(roundId);
+      if (strategies.length >= expectedCount) return strategies;
+      if (strategies.length >= 2) {
+        // If we have at least 2 and are past 75% of timeout, accept what we have
+        if (Date.now() > deadline - timeoutMs * 0.25) return strategies;
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+
+    // Return whatever we have at timeout
+    return db.getStrategies(roundId);
+  };
+}

package/src/tournament/prompts.ts

@@ -0,0 +1,65 @@
+/**
+ * Tournament subagent task prompt templates.
+ * Each role is constrained to a different analytical framework
+ * to produce genuinely diverse strategies.
+ * @module openfinclaw/tournament/prompts
+ */
+
+export type TournamentRole = "bull" | "bear" | "contrarian";
+
+/**
+ * Build the task prompt for a tournament subagent.
+ * This is the `task` parameter passed to `sessions_spawn`.
+ */
+export function buildAgentTask(role: TournamentRole, ticker: string, roundId: string): string {
+  const rolePrompts: Record<TournamentRole, string> = {
+    bull: `你是看多分析师 🐂。分析 ${ticker}：
+1. 调用 fin_deepagent_research 进行深度分析，聚焦动量指标（EMA 交叉、突破形态、成交量确认）
+2. 基于分析结果，生成看多交易策略：入场价、出场价、止损价、仓位比例
+3. 调用 tournament_result 提交结果，参数如下：
+   - round_id: "${roundId}"
+   - agent_name: "bull"
+   - thesis: 你的分析论点（1 段，150 字以内）
+   - entry_price, exit_price, stop_loss, position_pct: 策略参数
+   - confidence: 0-100 的信心分数
+   - sharpe, max_drawdown, total_return: 如有回测数据则填入
+约束：只使用动量和趋势类指标（EMA, MACD, 突破, 成交量）`,
+
+    bear: `你是看空分析师 🐻。分析 ${ticker}：
+1. 调用 fin_deepagent_research 进行深度分析，聚焦风险指标（RSI 超买、布林带收缩、波动率）
+2. 基于分析结果，生成看空或对冲策略：入场价、出场价、止损价、仓位比例
+3. 调用 tournament_result 提交结果，参数如下：
+   - round_id: "${roundId}"
+   - agent_name: "bear"
+   - thesis: 你的分析论点（1 段，150 字以内）
+   - entry_price, exit_price, stop_loss, position_pct: 策略参数
+   - confidence: 0-100 的信心分数
+   - sharpe, max_drawdown, total_return: 如有回测数据则填入
+约束：只使用均值回归和风险类指标（RSI, 布林带, ATR, VIX 相关性）`,
+
+    contrarian: `你是逆向分析师 🔄。分析 ${ticker}：
+1. 调用 fin_deepagent_research 进行深度分析，聚焦情绪和资金流（新闻情绪反转、异常期权活动、资金流向）
+2. 基于分析结果，生成逆势策略：入场价、出场价、止损价、仓位比例
+3. 调用 tournament_result 提交结果，参数如下：
+   - round_id: "${roundId}"
+   - agent_name: "contrarian"
+   - thesis: 你的分析论点（1 段，150 字以内）
+   - entry_price, exit_price, stop_loss, position_pct: 策略参数
+   - confidence: 0-100 的信心分数
+   - sharpe, max_drawdown, total_return: 如有回测数据则填入
+约束：只使用情绪和资金流类指标（新闻情绪、期权异动、资金流入/流出）`,
+  };
+
+  return rolePrompts[role];
+}
+
+/**
+ * Build the system prompt addendum for the main agent.
+ * Injected via before_prompt_build hook.
+ */
+export function buildOrchestratorPrompt(): string {
+  return `你有 Strategy Tournament 锦标赛功能。
+- 当用户说 "/pick bull|bear|contrarian" 时，调用 tournament_pick 工具记录选择
+- 当用户说 "/tournament leaderboard" 或询问锦标赛排名时，调用 tournament_leaderboard 工具
+- 锦标赛每日自动运行，你不需要手动触发`;
+}

package/src/tournament/tools.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Unit tests for tournament tools.
+ * @module openfinclaw/tournament/tools.test
+ */
+import { DatabaseSync } from "node:sqlite";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { TournamentDb, ensureTournamentSchema } from "./db.js";
+
+/**
+ * Minimal tool executor for testing.
+ * Collects registered tools and lets tests call them directly.
+ */
+class ToolCollector {
+  tools = new Map<
+    string,
+    { execute: (id: string, params: Record<string, unknown>) => Promise<unknown> }
+  >();
+
+  registerTool(factory: unknown, opts?: unknown) {
+    const tool =
+      typeof factory === "function" ? (factory as (ctx: unknown) => unknown)(null) : factory;
+    const t = tool as {
+      name: string;
+      execute: (id: string, params: Record<string, unknown>) => Promise<unknown>;
+    };
+    const names = (opts as { names?: string[] } | undefined)?.names ?? [t.name];
+    for (const name of names) {
+      this.tools.set(name, t);
+    }
+  }
+
+  async call(
+    name: string,
+    params: Record<string, unknown>,
+  ): Promise<{ content: Array<{ type: string; text: string }>; details: unknown }> {
+    const tool = this.tools.get(name);
+    if (!tool) throw new Error(`Tool not found: ${name}`);
+    return tool.execute("test-call-id", params) as Promise<{
+      content: Array<{ type: string; text: string }>;
+      details: unknown;
+    }>;
+  }
+}
+
+/** Extract parsed details from tool result. */
+function details(result: { details: unknown }): Record<string, unknown> {
+  if (typeof result.details === "string") return JSON.parse(result.details);
+  return result.details as Record<string, unknown>;
+}
+
+describe("tournament tools", () => {
+  let db: DatabaseSync;
+  let tdb: TournamentDb;
+  let collector: ToolCollector;
+
+  beforeEach(async () => {
+    db = new DatabaseSync(":memory:");
+    db.exec("PRAGMA journal_mode = WAL");
+    ensureTournamentSchema(db);
+    tdb = new TournamentDb(db);
+
+    collector = new ToolCollector();
+    const { registerTournamentTools } = await import("./tools.js");
+    registerTournamentTools(collector.registerTool.bind(collector), () => tdb);
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  describe("tournament_pick", () => {
+    it("records valid pick", async () => {
+      tdb.createRound({ id: "round-20260331", date: "2026-03-31", ticker: "AAPL" });
+      tdb.updateRoundStatus("round-20260331", "completed");
+      tdb.saveStrategy({
+        round_id: "round-20260331",
+        agent_name: "bull",
+        thesis: "test",
+        confidence: 80,
+        entry_price: null,
+        exit_price: null,
+        stop_loss: null,
+        position_pct: null,
+        sharpe: 1.5,
+        max_drawdown: null,
+        total_return: null,
+        raw_result: null,
+      });
+
+      const result = await collector.call("tournament_pick", {
+        agent_name: "bull",
+        user_id: "tg:123",
+        session_key: "agent:main",
+      });
+      const d = details(result);
+      expect(d.agent_name).toBe("bull");
+      expect(d.message).toContain("BULL");
+    });
+
+    it("rejects invalid agent name", async () => {
+      tdb.createRound({ id: "round-20260331", date: "2026-03-31", ticker: "AAPL" });
+      tdb.updateRoundStatus("round-20260331", "completed");
+
+      const result = await collector.call("tournament_pick", {
+        agent_name: "invalid",
+        user_id: "tg:123",
+        session_key: "agent:main",
+      });
+      const d = details(result);
+      expect(d.error).toBe(true);
+    });
+
+    it("returns error when no active round", async () => {
+      const result = await collector.call("tournament_pick", {
+        agent_name: "bull",
+        user_id: "tg:123",
+        session_key: "agent:main",
+      });
+      const d = details(result);
+      expect(d.error).toBe(true);
+      expect(d.message).toContain("没有活跃");
+    });
+
+    it("handles duplicate pick idempotently", async () => {
+      tdb.createRound({ id: "round-20260331", date: "2026-03-31", ticker: "AAPL" });
+      tdb.updateRoundStatus("round-20260331", "completed");
+
+      await collector.call("tournament_pick", {
+        agent_name: "bull",
+        user_id: "tg:123",
+        session_key: "agent:main",
+      });
+      const result = await collector.call("tournament_pick", {
+        agent_name: "bear",
+        user_id: "tg:123",
+        session_key: "agent:main",
+      });
+      const d = details(result);
+      expect(d.message).toContain("已经");
+    });
+
+    it("allows different users to pick same round", async () => {
+      tdb.createRound({ id: "round-20260331", date: "2026-03-31", ticker: "AAPL" });
+      tdb.updateRoundStatus("round-20260331", "completed");
+
+      const r1 = await collector.call("tournament_pick", {
+        agent_name: "bull",
+        user_id: "tg:111",
+        session_key: "agent:main",
+      });
+      const r2 = await collector.call("tournament_pick", {
+        agent_name: "bear",
+        user_id: "tg:222",
+        session_key: "agent:main",
+      });
+      expect(details(r1).agent_name).toBe("bull");
+      expect(details(r2).agent_name).toBe("bear");
+    });
+  });
+
+  describe("tournament_leaderboard", () => {
+    it("returns formatted ranking with data", async () => {
+      tdb.recordWin("bull", 2.0);
+      tdb.recordWin("bear", 1.0);
+      tdb.recordWin("contrarian", 3.0);
+
+      const result = await collector.call("tournament_leaderboard", {});
+      const d = details(result);
+      expect(d.message).toContain("排行榜");
+      expect((d.agents as Array<{ name: string }>)[0].name).toBe("contrarian");
+    });
+
+    it("returns empty message when no data", async () => {
+      const result = await collector.call("tournament_leaderboard", {});
+      const d = details(result);
+      expect(d.message).toContain("还没有");
+    });
+  });
+
+  describe("tournament_result", () => {
+    it("stores strategy with all fields", async () => {
+      tdb.createRound({ id: "round-20260331", date: "2026-03-31", ticker: "AAPL" });
+
+      const result = await collector.call("tournament_result", {
+        round_id: "round-20260331",
+        agent_name: "bull",
+        thesis: "Strong momentum signals",
+        entry_price: 150,
+        exit_price: 165,
+        stop_loss: 145,
+        position_pct: 0.25,
+        confidence: 85,
+        sharpe: 1.5,
+        max_drawdown: -0.08,
+        total_return: 0.12,
+      });
+
+      const d = details(result);
+      expect(d.agent_name).toBe("bull");
+
+      const strategies = tdb.getStrategies("round-20260331");
+      expect(strategies).toHaveLength(1);
+      expect(strategies[0].confidence).toBe(85);
+      expect(strategies[0].sharpe).toBe(1.5);
+    });
+
+    it("rejects invalid confidence range", async () => {
+      tdb.createRound({ id: "round-20260331", date: "2026-03-31", ticker: "AAPL" });
+
+      const result = await collector.call("tournament_result", {
+        round_id: "round-20260331",
+        agent_name: "bull",
+        thesis: "test",
+        confidence: 150,
+      });
+      const d = details(result);
+      expect(d.error).toBe(true);
+      expect(d.message).toContain("0-100");
+    });
+  });
+});