@openfinclaw/openfinclaw-strategy 0.0.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Peter Steinberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# @openfinclaw/openfinclaw-strategy
+
+FinClaw Commons - 量化策略开发平台插件。连接 hub.openfinclaw.ai 策略网络，支持策略创建、验证、发布、Fork。
+
+## 安装
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/cryptoSUN2049/openFinclaw/main/scripts/install-finclaw.sh | bash
+```
+
+或手动安装：
+
+```bash
+openclaw plugins install @openfinclaw/openfinclaw-strategy
+```
+
+## 快速开始（无需 API Key）
+
+```bash
+# 查看排行榜
+openclaw strategy leaderboard
+
+# 查看收益榜 Top 10
+openclaw strategy leaderboard returns --limit 10
+
+# 查看策略详情
+openclaw strategy show <strategy-id> --remote
+```
+
+## 功能概览
+
+| 功能       | 工具                   | 需要 API Key |
+| ---------- | ---------------------- | ------------ |
+| 排行榜查询 | `skill_leaderboard`    | 否           |
+| 策略详情   | `skill_get_info`       | 否           |
+| 本地验证   | `skill_validate`       | 否           |
+| 本地列表   | `skill_list_local`     | 否           |
+| 策略 Fork  | `skill_fork`           | **是**       |
+| 策略发布   | `skill_publish`        | **是**       |
+| 发布查询   | `skill_publish_verify` | **是**       |
+
+### AI 工具列表
+
+| 工具                   | 说明                                   | API Key  |
+| ---------------------- | -------------------------------------- | -------- |
+| `skill_leaderboard`    | 查询排行榜（综合/收益/风控/人气/新星） | 不需要   |
+| `skill_get_info`       | 获取 Hub 策略公开详情                  | 不需要   |
+| `skill_validate`       | 本地验证策略包（FEP v1.2）             | 不需要   |
+| `skill_list_local`     | 列出本地策略                           | 不需要   |
+| `skill_fork`           | 从 Hub 下载策略到本地                  | **需要** |
+| `skill_publish`        | 发布策略 ZIP 到 Hub，自动触发回测      | **需要** |
+| `skill_publish_verify` | 查询发布状态和回测报告                 | **需要** |
+
+## CLI 命令
+
+```bash
+# 查看排行榜（无需 API Key）
+openclaw strategy leaderboard
+openclaw strategy leaderboard returns --limit 10
+
+# 从 Hub Fork 策略（需要 API Key）
+openclaw strategy fork <strategy-id>
+
+# 列出本地策略
+openclaw strategy list
+
+# 查看策略详情
+openclaw strategy show <name-or-id> [--remote]
+
+# 删除本地策略
+openclaw strategy remove <name-or-id> --force
+```
+
+### 排行榜类型
+
+| 榜单类型    | 说明           |
+| ----------- | -------------- |
+| `composite` | 综合榜（默认） |
+| `returns`   | 收益榜         |
+| `risk`      | 风控榜         |
+| `popular`   | 人气榜         |
+| `rising`    | 新星榜         |
+
+## 配置
+
+Fork 和发布策略需要 API Key（从 https://hub.openfinclaw.ai 获取）：
+
+```bash
+openclaw config set plugins.entries.openfinclaw.config.skillApiKey YOUR_API_KEY
+```
+
+或使用环境变量：
+
+```bash
+export SKILL_API_KEY=YOUR_API_KEY
+export SKILL_API_URL=https://hub.openfinclaw.ai
+```
+
+### ⚠️ API Key 安全提醒
+
+**重要：请勿泄露你的 Hub API Key！**
+
+- API Key 以 `fch_` 开头，**仅用于** hub.openfinclaw.ai 接口校验
+- **不要**将 API Key 提交到 Git 仓库或公开分享
+- **不要**在公开聊天、截图、代码示例中暴露真实的 API Key
+- 如果怀疑 Key 已泄露，请立即在 Hub 个人设置中重新生成
+
+### 配置选项
+
+| 配置项             | 环境变量                   | 说明                         | 默认值                       |
+| ------------------ | -------------------------- | ---------------------------- | ---------------------------- |
+| `skillApiKey`      | `SKILL_API_KEY`            | Hub API Key（Fork/发布需要） | 可选                         |
+| `skillApiUrl`      | `SKILL_API_URL`            | Hub 服务地址                 | `https://hub.openfinclaw.ai` |
+| `requestTimeoutMs` | `SKILL_REQUEST_TIMEOUT_MS` | 请求超时                     | `60000`                      |
+
+## Skills
+
+### openfinclaw (入口)
+
+平台入口 skill，帮助用户了解 Hub 平台、安装插件、使用工具链。
+
+### skill-publish
+
+发布策略到 Hub：
+
+```
+用户: "发布我的策略到服务器"
+Agent:
+1. skill_validate(dirPath) → 本地验证
+2. [打包 ZIP]
+3. skill_publish(filePath) → 获取 submissionId
+4. skill_publish_verify(submissionId) → 轮询直到完成
+5. 返回回测报告
+```
+
+### strategy-builder
+
+自然语言生成策略：
+
+```
+用户: "帮我创建一个 BTC 定投策略，每周买入 100 美元"
+Agent:
+1. 生成 fep.yaml 配置
+2. 生成 scripts/strategy.py 代码
+3. 可选：验证并打包
+```
+
+### strategy-fork
+
+从 Hub 下载策略：
+
+```
+用户: "帮我下载那个收益 453% 的 BTC 策略"
+Agent:
+1. skill_leaderboard() → 查看排行榜
+2. skill_get_info(strategyId) → 查看详情
+3. skill_fork(strategyId) → 下载到本地
+4. 返回本地路径供编辑
+```
+
+## 本地存储
+
+策略存储在 `~/.openfinclaw/workspace/strategies/`：
+
+```
+~/.openfinclaw/workspace/strategies/
+└── 2026-03-16/
+    ├── btc-adaptive-dca-34a5792f/   # Fork 来的策略
+    │   ├── fep.yaml
+    │   ├── scripts/strategy.py
+    │   └── .fork-meta.json
+    └── my-new-strategy/             # 自建策略
+        └── ...
+```
+
+## 链接
+
+- **Hub 平台**: https://hub.openfinclaw.ai
+- **排行榜**: https://hub.openfinclaw.ai/leaderboard
+- **获取 API Key**: https://hub.openfinclaw.ai/dashboard
+- **GitHub**: https://github.com/cryptoSUN2049/openFinclaw
+
+## License
+
+MIT

package/index.test.ts

@@ -0,0 +1,269 @@
+/**
+ * Unit tests for openfinclaw plugin: registration, config resolution, and tool execution with mocked HTTP.
+ */
+import type { OpenClawPluginApi } from "openfinclaw/plugin-sdk";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import plugin from "./index.js";
+
+vi.mock("node:fs/promises", () => ({
+  readFile: vi.fn(),
+}));
+const { readFile } = await import("node:fs/promises");
+
+type Tool = {
+  execute: (id: string, params: Record<string, unknown>) => Promise<unknown>;
+};
+
+function parseResult(result: unknown): Record<string, unknown> {
+  const details = (result as { details?: Record<string, unknown> }).details;
+  if (details) return details;
+  const content = (result as { content: Array<{ text: string }> }).content?.[0]?.text;
+  if (!content) return {};
+  try {
+    return JSON.parse(content) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+function createFakeApi(pluginConfig: Record<string, unknown>): {
+  api: OpenClawPluginApi;
+  tools: Map<string, Tool>;
+} {
+  const tools = new Map<string, Tool>();
+  const api = {
+    id: "openfinclaw",
+    name: "OpenFinClaw",
+    source: "test",
+    config: {},
+    pluginConfig,
+    runtime: { version: "test", services: new Map() },
+    logger: { info() {}, warn() {}, error() {}, debug() {} },
+    registerTool(tool: { name: string; execute: Tool["execute"] }) {
+      tools.set(tool.name, tool);
+    },
+    registerHook() {},
+    registerHttpHandler() {},
+    registerHttpRoute() {},
+    registerChannel() {},
+    registerGatewayMethod() {},
+    registerCli() {},
+    registerService() {},
+    registerProvider() {},
+    registerCommand() {},
+    resolvePath: (p: string) => p,
+    on() {},
+  } as unknown as OpenClawPluginApi;
+
+  return { api, tools };
+}
+
+describe("openfinclaw plugin", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
+    vi.restoreAllMocks();
+  });
+
+  it("has correct plugin metadata", () => {
+    expect(plugin.id).toBe("openfinclaw");
+    expect(plugin.name).toBe("OpenFinClaw");
+  });
+
+  it("registers all 3 tools", () => {
+    const { api, tools } = createFakeApi({});
+    plugin.register(api);
+
+    expect(tools.size).toBe(7);
+    expect(tools.has("skill_publish")).toBe(true);
+    expect(tools.has("skill_publish_verify")).toBe(true);
+    expect(tools.has("skill_validate")).toBe(true);
+  });
+
+  it("skill_publish_verify returns success when API returns 200 with submissionId", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: async () =>
+        JSON.stringify({
+          submissionId: "sub-123",
+          slug: "test-strategy",
+          version: "1.0.0",
+          backtestStatus: "completed",
+          backtestCompleted: true,
+          backtestReport: { performance: { totalReturn: 0.1, sharpe: 1.2 } },
+        }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { api, tools } = createFakeApi({
+      skillApiUrl: "http://skill.example",
+      skillApiKey: "fch_test_key",
+    });
+    plugin.register(api);
+
+    const result = parseResult(
+      await tools.get("skill_publish_verify")!.execute("call-1", { submissionId: "sub-123" }),
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.slug).toBe("test-strategy");
+    expect(result.backtestStatus).toBe("completed");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toContain("/api/v1/skill/publish/verify");
+    expect(url).toContain("submissionId=sub-123");
+    expect((init.headers as Record<string, string>)["Authorization"]).toBe("Bearer fch_test_key");
+  });
+
+  it("skill_publish_verify returns success when API returns 200 with backtestTaskId", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: async () =>
+        JSON.stringify({
+          submissionId: "sub-456",
+          backtestTaskId: "bt-789",
+          backtestStatus: "processing",
+          backtestCompleted: false,
+        }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { api, tools } = createFakeApi({
+      skillApiUrl: "http://skill.example",
+      skillApiKey: "fch_test_key",
+    });
+    plugin.register(api);
+
+    const result = parseResult(
+      await tools.get("skill_publish_verify")!.execute("call-2", { backtestTaskId: "bt-789" }),
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.backtestStatus).toBe("processing");
+    const [url] = fetchMock.mock.calls[0] as [string];
+    expect(url).toContain("backtestTaskId=bt-789");
+  });
+
+  it("skill_publish requires filePath and apiKey", async () => {
+    const { api, tools } = createFakeApi({});
+    plugin.register(api);
+
+    const result = parseResult(
+      await tools.get("skill_publish")!.execute("call-3", { filePath: "" }),
+    );
+
+    expect(result.success).toBe(false);
+    expect(String(result.error)).toContain("filePath is required");
+  });
+
+  it("skill_publish returns error when apiKey is not configured", async () => {
+    const { api, tools } = createFakeApi({ skillApiUrl: "http://skill.example" });
+    plugin.register(api);
+
+    const result = parseResult(
+      await tools.get("skill_publish")!.execute("call-4", { filePath: "/tmp/test.zip" }),
+    );
+
+    expect(result.success).toBe(false);
+    expect(String(result.error)).toContain("API key not configured");
+  });
+
+  it("skill_publish sends POST with base64 content", async () => {
+    vi.mocked(readFile).mockResolvedValue(Buffer.from("fake-zip-content"));
+
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 201,
+      text: async () =>
+        JSON.stringify({
+          slug: "test-skill",
+          entryId: "entry-uuid",
+          version: "1.0.0",
+          status: "completed",
+          submissionId: "sub-new",
+          backtestTaskId: "bt-new",
+          backtestStatus: "completed",
+        }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { api, tools } = createFakeApi({
+      skillApiUrl: "http://skill.example",
+      skillApiKey: "fch_test_key",
+    });
+    plugin.register(api);
+
+    const result = await tools.get("skill_publish")!.execute("call-5", {
+      filePath: "/tmp/strategy.zip",
+      visibility: "public",
+    });
+
+    const details = (result as { details: Record<string, unknown> }).details;
+    expect(details.success).toBe(true);
+    expect(details.slug).toBe("test-skill");
+    expect(details.submissionId).toBe("sub-new");
+    expect(readFile).toHaveBeenCalledWith("/tmp/strategy.zip");
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toContain("/api/v1/skill/publish");
+    expect(init.method).toBe("POST");
+    const body = JSON.parse(init.body as string);
+    expect(body.content).toBe("ZmFrZS16aXAtY29udGVudA==");
+    expect(body.visibility).toBe("public");
+    expect((init.headers as Record<string, string>)["Authorization"]).toBe("Bearer fch_test_key");
+  });
+
+  it("returns error when submissionId and backtestTaskId both missing for verify", async () => {
+    const { api, tools } = createFakeApi({ skillApiKey: "fch_test" });
+    plugin.register(api);
+
+    const result = parseResult(await tools.get("skill_publish_verify")!.execute("call-6", {}));
+
+    expect(result.success).toBe(false);
+    expect(String(result.error)).toContain("Either submissionId or backtestTaskId is required");
+  });
+
+  it("uses env SKILL_API_KEY when plugin config has no skillApiKey", async () => {
+    vi.stubEnv("SKILL_API_KEY", "fch_env_key");
+
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: async () => JSON.stringify({ submissionId: "sub-1", backtestStatus: "completed" }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { api, tools } = createFakeApi({ skillApiUrl: "http://skill.example" });
+    plugin.register(api);
+
+    await tools.get("skill_publish_verify")!.execute("call-7", { submissionId: "sub-1" });
+
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect((init.headers as Record<string, string>)["Authorization"]).toBe("Bearer fch_env_key");
+  });
+
+  describe("skill_validate", () => {
+    it("returns invalid when dirPath is missing", async () => {
+      const { api, tools } = createFakeApi({});
+      plugin.register(api);
+      const result = parseResult(await tools.get("skill_validate")!.execute("v1", { dirPath: "" }));
+      expect(result.valid).toBe(false);
+      expect(result.success).toBe(false);
+      expect(Array.isArray(result.errors) && result.errors.length > 0).toBe(true);
+    });
+
+    it("returns invalid when fep.yaml is missing", async () => {
+      vi.mocked(readFile).mockRejectedValue(new Error("ENOENT"));
+
+      const { api, tools } = createFakeApi({});
+      plugin.register(api);
+      const result = parseResult(
+        await tools.get("skill_validate")!.execute("v2", { dirPath: "/tmp/empty" }),
+      );
+      expect(result.valid).toBe(false);
+      expect(result.errors).toBeDefined();
+      expect((result.errors as string[]).some((e: string) => e.includes("fep.yaml"))).toBe(true);
+    });
+  });
+});