@openfinclaw/openfinclaw-strategy 0.0.11 → 0.1.1

package/src/strategy/client.ts

@@ -0,0 +1,44 @@
+/**
+ * Hub API client for strategy operations.
+ * Handles HTTP requests to hub.openfinclaw.ai
+ */
+import type { UnifiedPluginConfig } from "../types.js";
+
+/**
+ * HTTP request helper for Hub API.
+ */
+export async function hubApiRequest(
+  config: UnifiedPluginConfig,
+  method: "GET" | "POST",
+  pathSegments: string,
+  options?: { body?: Record<string, unknown>; searchParams?: Record<string, string> },
+): Promise<{ status: number; data: unknown }> {
+  const url = new URL(`${config.hubApiUrl}/api/v1${pathSegments}`);
+  if (options?.searchParams) {
+    for (const [k, v] of Object.entries(options.searchParams)) {
+      url.searchParams.set(k, v);
+    }
+  }
+
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (config.apiKey) headers["Authorization"] = `Bearer ${config.apiKey}`;
+
+  const response = await fetch(url.toString(), {
+    method,
+    headers,
+    body: options?.body ? JSON.stringify(options.body) : undefined,
+    signal: AbortSignal.timeout(config.requestTimeoutMs),
+  });
+
+  const rawText = await response.text();
+  let data: unknown = rawText;
+  if (rawText && rawText.trim().startsWith("{")) {
+    try {
+      data = JSON.parse(rawText);
+    } catch {
+      data = { raw: rawText };
+    }
+  }
+
+  return { status: response.status, data };
+}

package/src/{fork.ts → strategy/fork.ts}

@@ -11,15 +11,15 @@ import {
   writeForkMeta,
   parseStrategyId,
   formatDate,
-} from "./strategy-storage.js";
+} from "./storage.js";
 import type {
-  SkillApiConfig,
+  UnifiedPluginConfig,
   ForkOptions,
   ForkResult,
   HubPublicEntry,
   ForkAndDownloadResponse,
-} from "./types.js";
-import type { ForkMeta } from "./types.js";
+} from "../types.js";
+import type { ForkMeta } from "../types.js";
 
 const HUB_BASE_URL = "https://hub.openfinclaw.ai";
 
@@ -28,10 +28,10 @@ const HUB_BASE_URL = "https://hub.openfinclaw.ai";
  * GET /api/v1/skill/public/{id}
  */
 export async function fetchStrategyInfo(
-  config: SkillApiConfig,
+  config: UnifiedPluginConfig,
   strategyId: string,
 ): Promise<{ success: boolean; data?: HubPublicEntry; error?: string }> {
-  const url = new URL(`${config.baseUrl}/api/v1/skill/public/${strategyId}`);
+  const url = new URL(`${config.hubApiUrl}/api/v1/skill/public/${strategyId}`);
 
   const headers: Record<string, string> = {
     Accept: "application/json",
@@ -84,18 +84,19 @@ export async function fetchStrategyInfo(
  * POST /api/v1/skill/entries/{id}/fork-and-download
  */
 export async function forkAndDownloadFromHub(
-  config: SkillApiConfig,
+  config: UnifiedPluginConfig,
   strategyId: string,
   options?: ForkOptions,
 ): Promise<{ success: boolean; data?: ForkAndDownloadResponse; error?: string }> {
   if (!config.apiKey) {
     return {
       success: false,
-      error: "API key is required for fork operation. Set SKILL_API_KEY environment variable.",
+      error:
+        "API key is required for fork operation. Set OPENFINCLAW_API_KEY environment variable.",
     };
   }
 
-  const url = new URL(`${config.baseUrl}/api/v1/skill/entries/${strategyId}/fork-and-download`);
+  const url = new URL(`${config.hubApiUrl}/api/v1/skill/entries/${strategyId}/fork-and-download`);
 
   const body: Record<string, unknown> = {};
   if (options?.name) body.name = options.name;
@@ -208,7 +209,7 @@ export async function extractZipToDir(
  * Flow: fetchStrategyInfo → forkAndDownloadFromHub → downloadFromSignedUrl → extract
  */
 export async function forkStrategy(
-  config: SkillApiConfig,
+  config: UnifiedPluginConfig,
   strategyIdInput: string,
   options?: ForkOptions,
 ): Promise<ForkResult> {
@@ -339,4 +340,4 @@ export async function forkStrategy(
  */
 export function buildHubUrl(strategyId: string): string {
   return `${HUB_BASE_URL}/strategy/${strategyId}`;
-}
+}

package/src/{strategy-storage.ts → strategy/storage.ts}

@@ -1,7 +1,11 @@
+/**
+ * Local strategy storage management.
+ * Handles reading/writing strategy metadata and listing local strategies.
+ */
 import fs from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
-import type { ForkMeta, CreatedMeta, LocalStrategy, StrategyPerformance } from "./types.js";
+import type { ForkMeta, CreatedMeta, LocalStrategy } from "../types.js";
 
 const WORKSPACE_DIRNAME = "workspace";
 const STRATEGIES_DIRNAME = "strategies";
@@ -30,10 +34,6 @@ export function getStrategiesRoot(): string {
 
 /**
  * Generate a slugified directory name from strategy name.
- * - Lowercase
- * - Spaces/underscores to hyphens
- * - Remove special characters
- * - Max 40 characters
  */
 export function slugifyName(name: string): string {
   return name
@@ -73,7 +73,6 @@ export function generateCreatedDirName(name: string): string {
 
 /**
  * Create date directory under strategies root.
- * Returns the full path to the date directory.
  */
 export function createDateDir(baseDir: string, date?: string): string {
   const dateStr = date ?? formatDate(new Date());
@@ -300,4 +299,4 @@ export function parseStrategyId(input: string): string {
   }
 
   return trimmed.toLowerCase();
-}
+}

package/src/strategy/tools.ts

@@ -0,0 +1,524 @@
+/**
+ * Strategy tools registration.
+ * Tools: skill_publish, skill_publish_verify, skill_validate, skill_leaderboard, skill_fork, skill_list_local, skill_get_info
+ */
+import { readFile } from "node:fs/promises";
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openfinclaw/plugin-sdk";
+import { hubApiRequest } from "./client.js";
+import { forkStrategy, fetchStrategyInfo } from "./fork.js";
+import { listLocalStrategies } from "./storage.js";
+import { validateStrategyPackage } from "./validate.js";
+import type { UnifiedPluginConfig, BoardType, LeaderboardResponse } from "../types.js";
+
+/** JSON tool result helper. */
+function json(payload: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }],
+    details: payload,
+  };
+}
+
+const NO_API_KEY =
+  "API key not configured. Set apiKey in plugin config or OPENFINCLAW_API_KEY env var.";
+
+/**
+ * Register strategy tools.
+ */
+export function registerStrategyTools(
+  api: OpenClawPluginApi,
+  config: UnifiedPluginConfig,
+): void {
+  // ── skill_publish ──
+  api.registerTool(
+    {
+      name: "skill_publish",
+      label: "Publish skill to server",
+      description:
+        "Publish a strategy ZIP to the skill server. The server will automatically run backtest. Returns submissionId and backtestTaskId for polling.",
+      parameters: Type.Object({
+        filePath: Type.String({
+          description: "Path to the strategy ZIP file (must contain fep.yaml)",
+        }),
+        visibility: Type.Optional(
+          Type.Unsafe<"public" | "private" | "unlisted">({
+            type: "string",
+            enum: ["public", "private", "unlisted"],
+            description: "Override visibility from fep.yaml",
+          }),
+        ),
+      }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        try {
+          const filePath = String(params.filePath ?? "").trim();
+          if (!filePath) return json({ success: false, error: "filePath is required" });
+
+          if (!config.apiKey) {
+            return json({
+              success: false,
+              error: NO_API_KEY,
+            });
+          }
+
+          const resolvedPath = api.resolvePath(filePath);
+          const buf = await readFile(resolvedPath);
+          const base64Content = buf.toString("base64");
+
+          const body: Record<string, unknown> = { content: base64Content };
+          if (
+            params.visibility === "public" ||
+            params.visibility === "private" ||
+            params.visibility === "unlisted"
+          ) {
+            body.visibility = params.visibility;
+          }
+
+          const { status, data } = await hubApiRequest(config, "POST", "/skill/publish", {
+            body,
+          });
+
+          if (status >= 200 && status < 300) {
+            const resp = data as {
+              slug?: string;
+              entryId?: string;
+              version?: string;
+              status?: string;
+              message?: string;
+              submissionId?: string;
+              backtestTaskId?: string | null;
+              backtestStatus?: string | null;
+              creditsEarned?: { action?: string; amount?: number; message?: string };
+            };
+
+            const lines: string[] = [];
+            lines.push("Skill 发布成功！");
+            lines.push("");
+            lines.push(`- Slug: ${resp.slug ?? "(未知)"}`);
+            lines.push(`- Entry ID: ${resp.entryId ?? "(未知)"}`);
+            lines.push(`- Version: ${resp.version ?? "(未知)"}`);
+            if (resp.backtestTaskId) lines.push(`- Backtest Task ID: ${resp.backtestTaskId}`);
+            if (resp.creditsEarned?.amount) lines.push(`- 获得 ${resp.creditsEarned.amount} FC`);
+            lines.push("");
+            lines.push("使用 skill_publish_verify 工具查询回测状态和获取完整报告。");
+
+            return {
+              content: [{ type: "text" as const, text: lines.join("\n") }],
+              details: { success: true, ...resp },
+            };
+          }
+
+          return json({
+            success: false,
+            status,
+            error:
+              (data as { code?: string; message?: string })?.message ??
+              (data as { detail?: string })?.detail ??
+              data,
+          });
+        } catch (err) {
+          return json({
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      },
+    },
+    { names: ["skill_publish"] },
+  );
+
+  // ── skill_publish_verify ──
+  api.registerTool(
+    {
+      name: "skill_publish_verify",
+      label: "Verify skill publish result",
+      description:
+        "Check publish and backtest status by submissionId or backtestTaskId. Returns full backtest report when completed.",
+      parameters: Type.Object({
+        submissionId: Type.Optional(
+          Type.String({ description: "Submission ID from skill_publish response" }),
+        ),
+        backtestTaskId: Type.Optional(
+          Type.String({ description: "Backtest task ID from skill_publish response" }),
+        ),
+      }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        try {
+          const submissionId = String(params.submissionId ?? "").trim() || undefined;
+          const backtestTaskId = String(params.backtestTaskId ?? "").trim() || undefined;
+
+          if (!submissionId && !backtestTaskId) {
+            return json({
+              success: false,
+              error: "Either submissionId or backtestTaskId is required",
+            });
+          }
+
+          if (!config.apiKey) {
+            return json({
+              success: false,
+              error: NO_API_KEY,
+            });
+          }
+
+          const searchParams: Record<string, string> = {};
+          if (submissionId) searchParams.submissionId = submissionId;
+          if (backtestTaskId) searchParams.backtestTaskId = backtestTaskId;
+
+          const { status, data } = await hubApiRequest(config, "GET", "/skill/publish/verify", {
+            searchParams,
+          });
+
+          if (status >= 200 && status < 300) {
+            const resp = data as Record<string, unknown>;
+            const lines: string[] = [];
+            lines.push("发布验证结果：");
+            lines.push(`- Slug: ${resp.slug ?? "(未知)"}`);
+            lines.push(`- Version: ${resp.version ?? "(未知)"}`);
+            lines.push(`- Backtest Status: ${resp.backtestStatus ?? "(未知)"}`);
+
+            if (resp.backtestStatus === "completed" && resp.backtestReport) {
+              const perf = (resp.backtestReport as Record<string, unknown>).performance as
+                | Record<string, unknown>
+                | undefined;
+              if (perf) {
+                lines.push("");
+                lines.push("回测报告摘要：");
+                if (typeof perf.totalReturn === "number")
+                  lines.push(`- 总收益率: ${(perf.totalReturn * 100).toFixed(2)}%`);
+                if (typeof perf.sharpe === "number")
+                  lines.push(`- 夏普比率: ${perf.sharpe.toFixed(3)}`);
+                if (typeof perf.maxDrawdown === "number")
+                  lines.push(`- 最大回撤: ${(perf.maxDrawdown * 100).toFixed(2)}%`);
+                if (typeof perf.winRate === "number")
+                  lines.push(`- 胜率: ${perf.winRate.toFixed(1)}%`);
+              }
+            }
+
+            return {
+              content: [{ type: "text" as const, text: lines.join("\n") }],
+              details: { success: true, ...resp },
+            };
+          }
+
+          return json({
+            success: false,
+            status,
+            error:
+              (data as { code?: string; message?: string })?.message ??
+              (data as { detail?: string })?.detail ??
+              data,
+          });
+        } catch (err) {
+          return json({
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      },
+    },
+    { names: ["skill_publish_verify"] },
+  );
+
+  // ── skill_validate ──
+  api.registerTool(
+    {
+      name: "skill_validate",
+      label: "Validate strategy package (FEP v2.0)",
+      description:
+        "Validate a strategy package directory per FEP v2.0 before zipping and publishing.",
+      parameters: Type.Object({
+        dirPath: Type.String({
+          description: "Path to strategy package directory (must contain fep.yaml)",
+        }),
+      }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        try {
+          const dirPath = String(params.dirPath ?? "").trim();
+          if (!dirPath)
+            return json({ success: false, valid: false, errors: ["dirPath is required"] });
+          const resolved = api.resolvePath(dirPath);
+          const result = await validateStrategyPackage(resolved);
+          return json({
+            success: result.valid,
+            valid: result.valid,
+            errors: result.errors,
+            warnings: result.warnings,
+          });
+        } catch (err) {
+          return json({
+            success: false,
+            valid: false,
+            errors: [err instanceof Error ? err.message : String(err)],
+          });
+        }
+      },
+    },
+    { names: ["skill_validate"] },
+  );
+
+  // ── skill_leaderboard ──
+  api.registerTool(
+    {
+      name: "skill_leaderboard",
+      label: "Get Hub leaderboard",
+      description: "Query strategy leaderboard from hub.openfinclaw.ai. No API key required.",
+      parameters: Type.Object({
+        boardType: Type.Optional(
+          Type.Unsafe<BoardType>({
+            type: "string",
+            enum: ["composite", "returns", "risk", "popular", "rising"],
+            description: "Leaderboard type: composite (default), returns, risk, popular, rising",
+          }),
+        ),
+        limit: Type.Optional(
+          Type.Number({ description: "Number of results (max 100, default 20)" }),
+        ),
+        offset: Type.Optional(Type.Number({ description: "Offset for pagination" })),
+      }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        try {
+          const boardType = (params.boardType as BoardType) || "composite";
+          const limit = Math.min(Math.max(Number(params.limit) || 20, 1), 100);
+          const offset = Math.max(Number(params.offset) || 0, 0);
+
+          const url = new URL(`${config.hubApiUrl}/api/v1/skill/leaderboard/${boardType}`);
+          url.searchParams.set("limit", String(limit));
+          url.searchParams.set("offset", String(offset));
+
+          const response = await fetch(url.toString(), {
+            method: "GET",
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(config.requestTimeoutMs),
+          });
+
+          const rawText = await response.text();
+          let data: unknown;
+          if (rawText && rawText.trim().startsWith("{")) {
+            try {
+              data = JSON.parse(rawText);
+            } catch {
+              data = { raw: rawText };
+            }
+          }
+
+          if (response.status < 200 || response.status >= 300) {
+            const errorData = data as { error?: { message?: string }; message?: string };
+            return json({
+              success: false,
+              error: errorData.error?.message ?? errorData.message ?? `HTTP ${response.status}`,
+            });
+          }
+
+          const leaderboard = data as LeaderboardResponse;
+          const boardNames: Record<string, string> = {
+            composite: "综合榜",
+            returns: "收益榜",
+            risk: "风控榜",
+            popular: "人气榜",
+            rising: "新星榜",
+          };
+
+          const lines: string[] = [];
+          lines.push(
+            `${boardNames[boardType] || boardType} Top ${leaderboard.strategies.length} (共 ${leaderboard.total} 个策略):`,
+          );
+          lines.push("");
+
+          for (const s of leaderboard.strategies) {
+            const perf = s.performance || {};
+            const returnStr =
+              typeof perf.returnSincePublish === "number"
+                ? `收益: ${(perf.returnSincePublish * 100).toFixed(1)}%`
+                : "收益: --";
+            const sharpeStr =
+              typeof perf.sharpeRatio === "number"
+                ? `夏普: ${perf.sharpeRatio.toFixed(2)}`
+                : "夏普: --";
+            const author = s.author?.displayName || "未知";
+            const hubUrl = `https://hub.openfinclaw.ai/strategy/${s.id}`;
+            lines.push(
+              `#${String(s.rank).padStart(2)}  [${s.name}](${hubUrl})  ${returnStr}  ${sharpeStr}  作者: ${author}`,
+            );
+          }
+
+          lines.push("");
+          lines.push("使用 skill_get_info <id> 查看策略详情");
+          lines.push("使用 skill_fork <id> 下载策略到本地");
+
+          return {
+            content: [{ type: "text" as const, text: lines.join("\n") }],
+            details: { success: true, ...leaderboard },
+          };
+        } catch (err) {
+          return json({
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      },
+    },
+    { names: ["skill_leaderboard"] },
+  );
+
+  // ── skill_fork ──
+  api.registerTool(
+    {
+      name: "skill_fork",
+      label: "Fork strategy from Hub",
+      description:
+        "Fork a public strategy from hub.openfinclaw.ai to local directory. Requires API key.",
+      parameters: Type.Object({
+        strategyId: Type.String({
+          description: "Strategy ID from Hub (UUID or Hub URL)",
+        }),
+        name: Type.Optional(Type.String({ description: "Name for the forked strategy" })),
+        targetDir: Type.Optional(Type.String({ description: "Custom target directory" })),
+      }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        try {
+          const strategyId = String(params.strategyId ?? "").trim();
+          if (!strategyId) return json({ success: false, error: "strategyId is required" });
+
+          if (!config.apiKey) {
+            return json({
+              success: false,
+              error: "API key is required for fork operation.",
+            });
+          }
+
+          const result = await forkStrategy(config, strategyId, {
+            name: params.name ? String(params.name) : undefined,
+            targetDir: params.targetDir ? String(params.targetDir) : undefined,
+          });
+
+          if (result.success) {
+            const lines: string[] = [];
+            lines.push("策略 Fork 成功！");
+            lines.push(`- 原策略: ${result.sourceName} (${result.sourceId})`);
+            lines.push(`- 本地路径: ${result.localPath}`);
+            lines.push("");
+            lines.push("下一步:");
+            lines.push(`- 编辑策略: code ${result.localPath}/scripts/strategy.py`);
+
+            return {
+              content: [{ type: "text" as const, text: lines.join("\n") }],
+              details: result,
+            };
+          }
+
+          return json({ success: false, error: result.error ?? "Failed to fork strategy" });
+        } catch (err) {
+          return json({
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      },
+    },
+    { names: ["skill_fork"] },
+  );
+
+  // ── skill_list_local ──
+  api.registerTool(
+    {
+      name: "skill_list_local",
+      label: "List local strategies",
+      description: "List all strategies downloaded or created locally, organized by date.",
+      parameters: Type.Object({}),
+      async execute() {
+        try {
+          const strategies = await listLocalStrategies();
+
+          if (strategies.length === 0) {
+            return {
+              content: [
+                {
+                  type: "text" as const,
+                  text: "本地暂无策略。\n\n使用 skill_fork 从 Hub 下载策略。",
+                },
+              ],
+              details: { success: true, strategies: [] },
+            };
+          }
+
+          const lines: string[] = [];
+          lines.push(`本地策略列表 (共 ${strategies.length} 个):`);
+
+          let currentDate = "";
+          for (const s of strategies) {
+            if (s.dateDir !== currentDate) {
+              currentDate = s.dateDir;
+              lines.push(`${s.dateDir}/`);
+            }
+            const typeLabel = s.type === "forked" ? "(forked)" : "(created)";
+            lines.push(`  ${s.name}  ${typeLabel}`);
+          }
+
+          return {
+            content: [{ type: "text" as const, text: lines.join("\n") }],
+            details: { success: true, strategies },
+          };
+        } catch (err) {
+          return json({
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      },
+    },
+    { names: ["skill_list_local"] },
+  );
+
+  // ── skill_get_info ──
+  api.registerTool(
+    {
+      name: "skill_get_info",
+      label: "Get strategy info from Hub",
+      description:
+        "Fetch detailed information about a strategy from hub.openfinclaw.ai. No API key required.",
+      parameters: Type.Object({
+        strategyId: Type.String({ description: "Strategy ID from Hub (UUID or Hub URL)" }),
+      }),
+      async execute(_toolCallId: string, params: Record<string, unknown>) {
+        try {
+          const strategyId = String(params.strategyId ?? "").trim();
+          if (!strategyId) return json({ success: false, error: "strategyId is required" });
+
+          const result = await fetchStrategyInfo(config, strategyId);
+
+          if (result.success && result.data) {
+            const info = result.data;
+            const lines: string[] = [];
+            lines.push("策略信息:");
+            lines.push(`- ID: ${info.id}`);
+            lines.push(`- 名称: ${info.name}`);
+            if (info.author?.displayName) lines.push(`- 作者: ${info.author.displayName}`);
+            if (info.backtestResult) {
+              lines.push("");
+              lines.push("绩效指标:");
+              if (typeof info.backtestResult.totalReturn === "number")
+                lines.push(`- 总收益率: ${(info.backtestResult.totalReturn * 100).toFixed(2)}%`);
+              if (typeof info.backtestResult.sharpe === "number")
+                lines.push(`- 夏普比率: ${info.backtestResult.sharpe.toFixed(3)}`);
+            }
+            lines.push("");
+            lines.push(`Hub URL: https://hub.openfinclaw.ai/strategy/${info.id}`);
+
+            return {
+              content: [{ type: "text" as const, text: lines.join("\n") }],
+              details: { success: true, ...info },
+            };
+          }
+
+          return json({ success: false, error: result.error ?? "Failed to fetch strategy info" });
+        } catch (err) {
+          return json({
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      },
+    },
+    { names: ["skill_get_info"] },
+  );
+}