@openfinclaw/findoo-alpha-plugin 2026.3.12

package/index.ts

@@ -0,0 +1,115 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { A2AClient } from "./src/a2a-client.js";
+import { resolveConfig } from "./src/config.js";
+import { extractSummary, PendingTaskTracker } from "./src/pending-task-tracker.js";
+import { registerTools } from "./src/register-tools.js";
+
+const findooPlugin = {
+  id: "findoo-alpha-plugin",
+  name: "Findoo Alpha",
+  description:
+    "Bridge to LangGraph strategy-agent via A2A protocol — " +
+    "37 professional financial analysis skills covering A-shares, US/HK equities, crypto, macro, and risk.",
+  kind: "financial" as const,
+
+  register(api: OpenClawPluginApi) {
+    const config = resolveConfig(api);
+    const log = api.logger;
+
+    // ── License Gate: no key → skip all registration ──
+    if (!config.apiKey) {
+      log.warn(
+        "Findoo: license key not configured — plugin inactive. " +
+          "Set FINDOO_API_KEY env var or configure in Control UI → Plugins → Findoo.",
+      );
+      return;
+    }
+
+    log.info(`findoo-alpha: connecting to ${config.strategyAgentUrl}`);
+    log.info(`findoo-alpha: assistant ${config.strategyAssistantId}`);
+
+    // Shared A2AClient instance (used by both tools and tracker)
+    const a2a = new A2AClient(config.strategyAgentUrl, config.strategyAssistantId);
+
+    // Verify connectivity at startup (non-blocking)
+    fetch(`${config.strategyAgentUrl}/ok`, {
+      signal: AbortSignal.timeout(5_000),
+    })
+      .then((r) => {
+        if (r.ok) {
+          log.info("findoo-alpha: strategy-agent is reachable ✓");
+        } else {
+          log.warn(`findoo-alpha: strategy-agent returned ${r.status}`);
+        }
+      })
+      .catch((err) => {
+        log.warn(
+          `findoo-alpha: strategy-agent unreachable (${err instanceof Error ? err.message : err}). Tools will retry on use.`,
+        );
+      });
+
+    // ── enqueueSystemEvent bridge (heartbeat push) ──
+    type RuntimeServices = {
+      system?: {
+        enqueueSystemEvent?: (
+          text: string,
+          options: { sessionKey: string; contextKey?: string },
+        ) => void;
+      };
+    };
+
+    const runtime = api.runtime as unknown as RuntimeServices | undefined;
+    const enqueueSystemEvent = runtime?.system?.enqueueSystemEvent;
+
+    // ── PendingTaskTracker (background stream consumer) ──
+    let tracker: PendingTaskTracker | undefined;
+
+    if (enqueueSystemEvent) {
+      tracker = new PendingTaskTracker({
+        a2aClient: a2a,
+        timeoutMs: config.taskTimeoutMs,
+        log: (level, msg) => {
+          if (level === "warn" || level === "error") log.warn(msg);
+          else log.info(msg);
+        },
+
+        onTaskCompleted(task, result) {
+          const summary = extractSummary(result);
+          enqueueSystemEvent(`[findoo] 深度分析完成 — "${task.query.slice(0, 40)}"\n\n${summary}`, {
+            sessionKey: "main",
+            contextKey: "findoo-analysis",
+          });
+        },
+
+        onTaskFailed(task, error) {
+          enqueueSystemEvent(`[findoo] 分析任务失败 — "${task.query.slice(0, 40)}": ${error}`, {
+            sessionKey: "main",
+            contextKey: "findoo-analysis",
+          });
+        },
+      });
+
+      log.info(
+        `findoo-alpha: task tracker ready (timeout=${config.taskTimeoutMs}ms, stream-based)`,
+      );
+    } else {
+      log.info(
+        "findoo-alpha: enqueueSystemEvent not available, tracker disabled (async results won't be pushed)",
+      );
+    }
+
+    // Register A2A-bridged tools
+    registerTools(api, config, a2a, tracker);
+
+    // Expose service for cross-plugin consumption
+    api.runtime?.services?.set("fin-strategy-agent", {
+      id: "fin-strategy-agent",
+      getConfig: () => ({
+        url: config.strategyAgentUrl,
+        assistantId: config.strategyAssistantId,
+      }),
+    });
+  },
+};
+
+export default findooPlugin;

package/openclaw.plugin.json

@@ -0,0 +1,42 @@
+{
+  "id": "findoo-alpha-plugin",
+  "name": "Findoo Alpha",
+  "description": "Alpha discovery bridge to LangGraph strategy-agent via A2A protocol — financial analysis, strategy design, risk assessment, portfolio management.",
+  "kind": "financial",
+  "version": "2026.3.12",
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "Findoo license key (required). Also accepted via FINDOO_API_KEY env var."
+      },
+      "strategyAgentUrl": {
+        "type": "string",
+        "description": "Strategy Agent service URL (LangGraph A2A). Default: http://43.128.100.43:5085"
+      },
+      "strategyAssistantId": {
+        "type": "string",
+        "description": "LangGraph assistant UUID to route A2A calls to."
+      }
+    }
+  },
+  "uiHints": {
+    "apiKey": {
+      "label": "License Key",
+      "help": "Findoo 分析服务授权密钥",
+      "placeholder": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+    },
+    "strategyAgentUrl": {
+      "label": "Strategy Agent URL",
+      "help": "LangGraph A2A 策略分析服务地址",
+      "placeholder": "http://43.128.100.43:5085"
+    },
+    "strategyAssistantId": {
+      "label": "Assistant ID",
+      "help": "LangGraph assistant UUID",
+      "placeholder": "d2310a07-b552-453c-a8bb-7b9b86de6b23"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@openfinclaw/findoo-alpha-plugin",
+  "version": "2026.3.12",
+  "description": "Strategy Agent bridge — A2A protocol integration for LangGraph strategy-agent (37 financial analysis skills)",
+  "keywords": [
+    "a2a",
+    "agent",
+    "finance",
+    "langgraph",
+    "strategy"
+  ],
+  "homepage": "https://github.com/cryptoSUN2049/openFinclaw#readme",
+  "type": "module",
+  "main": "./index.ts",
+  "dependencies": {
+    "@sinclair/typebox": "0.34.48"
+  },
+  "devDependencies": {
+    "openfinclaw": "workspace:*"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "@openfinclaw/findoo-alpha-plugin"
+    }
+  }
+}

package/skills/findoo-analyze/skill.md

@@ -0,0 +1,53 @@
+# Findoo — 专业金融分析 Agent
+
+Findoo 是远程部署的深度金融分析 Agent，具备多步推理、交叉验证、策略回测和报告生成能力。通过 `fin_analyze` 工具调用。
+
+## 路由规则（最重要）
+
+**默认规则：所有金融问题优先使用 `fin_analyze`。**
+
+只有在以下情况下才绕过 Findoo、直接使用 `fin_stock` / `fin_crypto` / `fin_macro` / `fin_index`：
+
+- 用户明确只需要一个数据点（报价、点位、汇率）
+- 回答只需要一句话、一个数字
+- 示例："茅台现在多少钱"、"BTC 价格"、"沪深300点位"、"美元兑人民币汇率"
+
+**以下情况必须使用 `fin_analyze`（即使看起来"不复杂"）：**
+
+| 触发信号                         | 示例                           |
+| -------------------------------- | ------------------------------ |
+| 包含"分析/评估/诊断/研究"        | "帮我分析茅台"、"评估持仓风险" |
+| 包含"怎么样/怎么看/如何"         | "NVDA 怎么样"、"港股怎么看"    |
+| 包含"能不能/适不适合/值不值得"   | "现在能加仓吗"、"值不值得买"   |
+| 包含"对比/比较"                  | "茅台和五粮液比"、"SPY vs QQQ" |
+| 包含"为什么/原因"                | "为什么跌这么多"、"涨的原因"   |
+| 包含"策略/回测/配置"             | "设计轮动策略"、"回测均线"     |
+| 包含"筛选/推荐/选"               | "选几只高股息股"、"推荐 ETF"   |
+| 包含"报告/周报/总结"             | "出一份研究报告"、"本周总结"   |
+| 包含"龙虎榜/游资/北向/南向/资金" | "今天龙虎榜"、"游资在买什么"   |
+| 包含"周期/阶段/趋势/拐点"        | "BTC什么周期"、"见底了吗"      |
+| 包含"风险/套利/对冲"             | "可转债套利"、"资金费率"       |
+| 涉及多个标的或市场               | "A股和港股怎么选"、"中美利差"  |
+| 需要解读、判断或建议             | 任何非纯数据查询               |
+
+## Agent 能力概览
+
+37 个专业 skill：
+
+- **A股** (14 skills) — 个股X-ray五维诊断、游资追踪(雷达/跟单/画像三层)、龙虎榜、概念周期、可转债、打新、北向资金、估值定投、财报季、因子筛选
+- **美股** (5 skills) — DCF估值+期权、ETF对比、GICS板块轮动、财报季IV、股息策略
+- **港股** (5 skills) — HSI估值脉搏、南向资金alpha、中概互联、高息策略
+- **加密** (5 skills) — BTC周期、DeFi收益、资金费率套利、山寨季、稳定币流向
+- **跨资产** (8 skills) — 宏观周期、风险监控、因子筛选、衍生品、ETF/基金、通用数据查询
+- **策略回测** — 量化策略设计、历史回测、参数优化、研究报告生成
+
+## 多轮对话
+
+支持 `thread_id` 保持上下文，适用于渐进式深入分析：
+
+```
+fin_analyze(query="分析茅台")
+fin_analyze(query="和五粮液对比", thread_id="...")
+fin_analyze(query="回测均线策略", thread_id="...")
+fin_analyze(query="生成报告", thread_id="...")
+```

package/src/a2a-client.ts

@@ -0,0 +1,287 @@
+/**
+ * A2A (Agent-to-Agent) Protocol Client
+ *
+ * Implements Google A2A standard (JSON-RPC 2.0) for communicating
+ * with LangGraph strategy-agent.
+ *
+ * Protocol: POST /a2a/{assistant_id}
+ * Methods:  message/send, message/stream, tasks/get
+ */
+
+export type A2ATextPart = { kind: "text"; text: string };
+export type A2ADataPart = { kind: "data"; data: Record<string, unknown> };
+export type A2APart = A2ATextPart | A2ADataPart;
+
+export type A2AMessage = {
+  role: "user" | "assistant";
+  parts: A2APart[];
+  messageId: string;
+};
+
+export type A2ARequest = {
+  jsonrpc: "2.0";
+  id: string;
+  method: "message/send" | "message/stream" | "tasks/get";
+  params: {
+    message?: A2AMessage;
+    thread?: { threadId: string };
+    id?: string;
+    contextId?: string;
+  };
+};
+
+export type A2AResponse = {
+  jsonrpc: "2.0";
+  id: string;
+  result?: Record<string, unknown>;
+  error?: { code: number; message: string };
+};
+
+/** A single parsed SSE event from message/stream */
+export type A2AStreamEvent = {
+  kind: "task" | "status-update" | "artifact-update" | "error" | "unknown";
+  status?: { state: string; message?: Record<string, unknown> };
+  final: boolean;
+  raw: Record<string, unknown>;
+};
+
+export class A2AClient {
+  constructor(
+    private baseUrl: string,
+    private assistantId: string,
+  ) {}
+
+  /**
+   * Send a message to the strategy agent via A2A protocol.
+   */
+  async sendMessage(
+    text: string,
+    options?: {
+      data?: Record<string, unknown>;
+      threadId?: string;
+      timeoutMs?: number;
+    },
+  ): Promise<A2AResponse> {
+    const parts: A2APart[] = [{ kind: "text", text }];
+    if (options?.data) {
+      parts.push({ kind: "data", data: options.data });
+    }
+
+    const body: A2ARequest = {
+      jsonrpc: "2.0",
+      id: `req-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      method: "message/send",
+      params: {
+        message: {
+          role: "user",
+          parts,
+          messageId: `msg-${Date.now()}`,
+        },
+        ...(options?.threadId ? { thread: { threadId: options.threadId } } : {}),
+      },
+    };
+
+    const resp = await fetch(`${this.baseUrl}/a2a/${this.assistantId}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(body),
+      signal: options?.timeoutMs ? AbortSignal.timeout(options.timeoutMs) : undefined,
+    });
+
+    if (!resp.ok) {
+      throw new Error(`A2A request failed: ${resp.status} ${resp.statusText}`);
+    }
+
+    return (await resp.json()) as A2AResponse;
+  }
+
+  /**
+   * Send a message via A2A SSE stream (message/stream).
+   * Yields parsed events; the final event has `final: true`.
+   */
+  async *sendMessageStream(
+    text: string,
+    options?: {
+      data?: Record<string, unknown>;
+      threadId?: string;
+      timeoutMs?: number;
+    },
+  ): AsyncGenerator<A2AStreamEvent> {
+    const parts: A2APart[] = [{ kind: "text", text }];
+    if (options?.data) {
+      parts.push({ kind: "data", data: options.data });
+    }
+
+    const body: A2ARequest = {
+      jsonrpc: "2.0",
+      id: `req-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      method: "message/stream",
+      params: {
+        message: {
+          role: "user",
+          parts,
+          messageId: `msg-${Date.now()}`,
+        },
+        ...(options?.threadId ? { thread: { threadId: options.threadId } } : {}),
+      },
+    };
+
+    const resp = await fetch(`${this.baseUrl}/a2a/${this.assistantId}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "text/event-stream",
+      },
+      body: JSON.stringify(body),
+      signal: options?.timeoutMs ? AbortSignal.timeout(options.timeoutMs) : undefined,
+    });
+
+    if (!resp.ok) {
+      throw new Error(`A2A stream request failed: ${resp.status} ${resp.statusText}`);
+    }
+
+    if (!resp.body) {
+      throw new Error("A2A stream response has no body");
+    }
+
+    // Parse SSE line by line from the ReadableStream
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        // Keep the last partial line in buffer
+        buffer = lines.pop() ?? "";
+
+        let currentData = "";
+
+        for (const line of lines) {
+          // Heartbeat comment — ignore
+          if (line.startsWith(":")) continue;
+          // Empty line = end of event block
+          if (line.trim() === "") {
+            if (currentData) {
+              const event = A2AClient.parseStreamData(currentData);
+              currentData = "";
+              yield event;
+              if (event.final) return;
+            }
+            continue;
+          }
+          if (line.startsWith("data: ")) {
+            currentData += line.slice(6);
+          }
+          // "event:" lines are informational; we derive kind from the data payload
+        }
+      }
+
+      // Flush remaining data in buffer
+      if (buffer.trim().startsWith("data: ")) {
+        const event = A2AClient.parseStreamData(buffer.trim().slice(6));
+        yield event;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  /**
+   * Consume the stream until final event, return the completed result
+   * as an A2AResponse (same shape as sendMessage for drop-in replacement).
+   */
+  async collectStreamResult(
+    text: string,
+    options?: {
+      data?: Record<string, unknown>;
+      threadId?: string;
+      timeoutMs?: number;
+    },
+  ): Promise<A2AResponse> {
+    let lastEvent: A2AStreamEvent | undefined;
+
+    for await (const event of this.sendMessageStream(text, options)) {
+      lastEvent = event;
+      if (event.kind === "error") {
+        const errMsg =
+          (event.raw as Record<string, unknown>)?.error ??
+          event.status?.message ??
+          "Unknown stream error";
+        return {
+          jsonrpc: "2.0",
+          id: "",
+          error: {
+            code: -1,
+            message: typeof errMsg === "string" ? errMsg : JSON.stringify(errMsg),
+          },
+        };
+      }
+    }
+
+    if (!lastEvent) {
+      return {
+        jsonrpc: "2.0",
+        id: "",
+        error: { code: -1, message: "No events received from stream" },
+      };
+    }
+
+    // Extract result from the final event's status.message or raw payload
+    const result = lastEvent.status?.message ?? lastEvent.raw;
+    return { jsonrpc: "2.0", id: "", result: result as Record<string, unknown> };
+  }
+
+  /** Parse a JSON data payload from an SSE event into an A2AStreamEvent */
+  private static parseStreamData(data: string): A2AStreamEvent {
+    try {
+      const parsed = JSON.parse(data) as { result?: Record<string, unknown>; error?: unknown };
+
+      if (parsed.error) {
+        return { kind: "error", final: true, raw: parsed as Record<string, unknown> };
+      }
+
+      const result = parsed.result ?? {};
+      const kind = (result.kind as string) ?? "unknown";
+      const status = result.status as
+        | { state: string; message?: Record<string, unknown> }
+        | undefined;
+      const final = (result.final as boolean) ?? false;
+
+      return { kind: kind as A2AStreamEvent["kind"], status, final, raw: result };
+    } catch {
+      return { kind: "unknown", final: false, raw: { unparsed: data } };
+    }
+  }
+
+  /**
+   * Get task status/result by task ID.
+   */
+  async getTask(taskId: string, contextId?: string): Promise<A2AResponse> {
+    const body: A2ARequest = {
+      jsonrpc: "2.0",
+      id: `req-${Date.now()}`,
+      method: "tasks/get",
+      params: { id: taskId, ...(contextId ? { contextId } : {}) },
+    };
+
+    const resp = await fetch(`${this.baseUrl}/a2a/${this.assistantId}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    return (await resp.json()) as A2AResponse;
+  }
+}

package/src/config.ts

@@ -0,0 +1,60 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+export type PluginConfig = {
+  apiKey: string;
+  strategyAgentUrl: string;
+  strategyAssistantId: string;
+  requestTimeoutMs: number;
+  pollIntervalMs: number;
+  taskTimeoutMs: number;
+};
+
+function readEnv(keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = process.env[key]?.trim();
+    if (value) return value;
+  }
+  return undefined;
+}
+
+const DEFAULT_STRATEGY_AGENT_URL = "http://43.128.100.43:5085";
+const DEFAULT_ASSISTANT_ID = "d2310a07-b552-453c-a8bb-7b9b86de6b23";
+
+export function resolveConfig(api: OpenClawPluginApi): PluginConfig {
+  const raw = api.pluginConfig as Record<string, unknown> | undefined;
+
+  const strategyAgentUrl =
+    (typeof raw?.strategyAgentUrl === "string" ? raw.strategyAgentUrl : undefined) ??
+    readEnv(["STRATEGY_AGENT_URL", "OPENFINCLAW_STRATEGY_AGENT_URL"]) ??
+    DEFAULT_STRATEGY_AGENT_URL;
+
+  const strategyAssistantId =
+    (typeof raw?.strategyAssistantId === "string" ? raw.strategyAssistantId : undefined) ??
+    readEnv(["STRATEGY_ASSISTANT_ID", "OPENFINCLAW_STRATEGY_ASSISTANT_ID"]) ??
+    DEFAULT_ASSISTANT_ID;
+
+  const timeoutRaw = raw?.requestTimeoutMs ?? readEnv(["OPENFINCLAW_STRATEGY_TIMEOUT_MS"]);
+  const timeout = Number(timeoutRaw);
+
+  const pollRaw = raw?.pollIntervalMs ?? readEnv(["OPENFINCLAW_FINDOO_POLL_INTERVAL_MS"]);
+  const pollInterval = Number(pollRaw);
+
+  const taskTimeoutRaw = raw?.taskTimeoutMs ?? readEnv(["OPENFINCLAW_FINDOO_TASK_TIMEOUT_MS"]);
+  const taskTimeout = Number(taskTimeoutRaw);
+
+  const apiKey =
+    (typeof raw?.apiKey === "string" ? raw.apiKey : undefined) ??
+    readEnv(["FINDOO_API_KEY", "OPENFINCLAW_FINDOO_API_KEY"]) ??
+    "";
+
+  return {
+    apiKey,
+    strategyAgentUrl: strategyAgentUrl.replace(/\/+$/, ""),
+    strategyAssistantId,
+    requestTimeoutMs: Number.isFinite(timeout) && timeout >= 5000 ? Math.floor(timeout) : 120_000,
+    pollIntervalMs:
+      Number.isFinite(pollInterval) && pollInterval >= 5000 ? Math.floor(pollInterval) : 15_000,
+    taskTimeoutMs:
+      Number.isFinite(taskTimeout) && taskTimeout >= 60_000 ? Math.floor(taskTimeout) : 1_200_000,
+  };
+}