⚠️ 警告：本软件仅用于教育和信息目的。本仓库中的任何内容均不构成财务、投资、法律或税务建议。

MAHORAGA

一款基于大型语言模型（LLM）的自主交易代理，可在 Cloudflare Workers 上 24/7 全天候运行。

MAHORAGA 会监控 StockTwits 和 Reddit 上的市场情绪，利用 AI（通过 AI SDK 使用 OpenAI、Anthropic、Google、xAI 和 DeepSeek）分析信号，并通过 Alpaca 执行交易。它以 Cloudflare Durable Object 的形式运行，具备持久化状态、自动重启功能，并提供 24/7 的加密货币交易支持。

功能特性

• 全天候运行 — 在 Cloudflare Workers 上运行，无需本地机器
• 多源信号 — 来自 StockTwits、Reddit（4 个子版块）以及 Twitter 的确认信号
• 多提供商 LLM — 通过 AI SDK 或 Cloudflare AI Gateway 支持 OpenAI、Anthropic、Google、xAI 和 DeepSeek
• 加密货币交易 — 全天候交易 BTC、ETH 和 SOL
• 期权支持 — 高确定性的期权策略
• 过时检测 — 自动平仓失去动能的头寸
• 盘前分析 — 在市场开盘前制定交易计划
• Discord 通知 — 接收买入信号提醒
• 可插拔策略系统 — 无需修改核心文件即可创建自定义策略

系统要求

• Node.js 18+
• Cloudflare 账户（免费层级即可）
• Alpaca 账户（免费，支持模拟交易）
• LLM API 密钥（OpenAI、Anthropic、Google、xAI、DeepSeek）或 Cloudflare AI Gateway 凭证

快速入门

1. 克隆并安装

git clone https://github.com/ygwyg/MAHORAGA.git
cd mahoraga
npm install

2. 创建 Cloudflare 资源

# 创建 D1 数据库
npx wrangler d1 create mahoraga-db
# 将 database_id 复制到 wrangler.jsonc 中

# 创建 KV 命名空间
npx wrangler kv namespace create CACHE
# 将 id 复制到 wrangler.jsonc 中

# 运行数据库迁移
npx wrangler d1 migrations apply mahoraga-db

3. 设置密钥

# 必需
npx wrangler secret put ALPACA_API_KEY
npx wrangler secret put ALPACA_API_SECRET

# API 认证 — 生成一个安全的随机令牌（推荐 64 个字符以上）
# 示例：openssl rand -base64 48
npx wrangler secret put MAHORAGA_API_TOKEN

# LLM 提供商（选择一种模式）
npx wrangler secret put LLM_PROVIDER  # "openai-raw"（默认）、"ai-sdk" 或 "cloudflare-gateway"
npx wrangler secret put LLM_MODEL     # 例如："gpt-4o-mini" 或 "anthropic/claude-sonnet-4"

# LLM API 密钥（根据提供商模式）
npx wrangler secret put OPENAI_API_KEY         # 用于 openai-raw 或使用 OpenAI 的 ai-sdk
npx wrangler secret put OPENAI_BASE_URL        # 可选：覆盖 openai-raw 和 ai-sdk 的 OpenAI 基础 URL（适用于 OpenAI 模型）
# npx wrangler secret put ANTHROPIC_API_KEY    # 用于使用 Anthropic 的 ai-sdk
# npx wrangler secret put GOOGLE_GENERATIVE_AI_API_KEY  # 用于使用 Google 的 ai-sdk
# npx wrangler secret put XAI_API_KEY          # 用于使用 xAI/Grok 的 ai-sdk
# npx wrangler secret put DEEPSEEK_API_KEY     # 用于使用 DeepSeek 的 ai-sdk
# npx wrangler secret put CLOUDFLARE_AI_GATEWAY_ACCOUNT_ID  # 用于 cloudflare-gateway
# npx wrangler secret put CLOUDFLARE_AI_GATEWAY_ID          # 用于 cloudflare-gateway
# npx wrangler secret put CLOUDFLARE_AI_GATEWAY_TOKEN       # 用于 cloudflare-gateway

# 可选
npx wrangler secret put ALPACA_PAPER         # 设置为 "true" 以启用模拟交易（推荐）
npx wrangler secret put TWITTER_BEARER_TOKEN
npx wrangler secret put DISCORD_WEBHOOK_URL
npx wrangler secret put KILL_SWITCH_SECRET   # 紧急停止开关（与 API 令牌分开）

4. 部署

npx wrangler deploy

5. 启用代理

所有 API 端点都需要通过 Bearer 令牌进行认证：

# 为了方便起见，将您的 API 令牌设置为环境变量
export MAHORAGA_TOKEN="your-api-token"

# 启用代理
curl -H "Authorization: Bearer $MAHORAGA_TOKEN" \
  https://mahoraga.bernardoalmeida2004.workers.dev/agent/enable

6. 监控

# 检查状态
curl -H "Authorization: Bearer $MAHORAGA_TOKEN" \
  https://mahoraga.bernardoalmeida2004.workers.dev/agent/status

# 查看日志
curl -H "Authorization: Bearer $MAHORAGA_TOKEN" \
  https://mahoraga.bernardoalmeida2004.workers.dev/agent/logs

# 紧急停止开关（使用单独的 KILL_SWITCH_SECRET）
curl -H "Authorization: Bearer $KILL_SWITCH_SECRET" \
  https://mahoraga.bernardoalmeida2004.workers.dev/agent/kill

# 在本地运行仪表板
cd dashboard && npm install && npm run dev

本地开发

# 终端 1 — 启动 wrangler
npx wrangler dev

# 终端 2 — 启动仪表板  
cd dashboard && npm run dev

# 终端 3 — 启用代理
curl -H "Authorization: Bearer $MAHORAGA_TOKEN" \
  http://localhost:8787/agent/enable

自定义策略

Mahoraga 使用一个 可插拔的策略系统。核心框架是一个轻量级的协调器——所有可定制的逻辑都位于策略模块中。您无需修改核心文件。

工作原理

1. 创建 src/strategy/my-strategy/index.ts，实现 Strategy 接口
2. 修改 src/strategy/index.ts 中的一行导入语句

// src/strategy/index.ts
import { myStrategy } from "./my-strategy";
export const activeStrategy = myStrategy;

可自定义的内容

组件	文件	作用
数据收集器	gatherers/*.ts	从数据源（StockTwits、Reddit 等）获取信号
提示模板	prompts/*.ts	用于研究和分析的 LLM 提示模板
入场规则	rules/entries.ts	决定购买哪些信号
出场规则	rules/exits.ts	决定何时卖出头寸
配置	config.ts	默认参数和各数据源权重

您可以复用默认的数据收集器，混合使用自定义的收集器，覆盖提示模板，并定义自己的入场/出场规则——所有这些都不需要修改核心文件。

添加新的数据源

创建一个返回 Signal[] 的数据收集器：

import type { Gatherer, StrategyContext } from "../../types";

const myGatherer: Gatherer = {
  name: "my-source",
  gather: async (ctx: StrategyContext) => {
    const res = await fetch("https://your-api.com/data");
    const data = await res.json();
    return data.items.map(item => ({
      symbol: item.ticker,
      source: "my_source",
      source_detail: "my_source_v1",
      sentiment: item.sentiment,
      raw_sentiment: item.sentiment,
      volume: 1,
      freshness: 1.0,
      source_weight: 0.9,
      reason: `MySource: ${item.summary}`,
      timestamp: Date.now(),
    }));
  },
};

然后将其加入到您的策略的 gatherers 数组中。

完整自定义指南请参阅 docs/harness.html。

配置

设置	默认值	描述
max_positions	5	最大并发持仓数
max_position_value	5000	每个仓位的最大金额（美元）
take_profit_pct	10	止盈百分比
stop_loss_pct	5	止损百分比
min_sentiment_score	0.3	考虑交易的最低情绪得分
min_analyst_confidence	0.6	进行交易所需的最低 LLM 置信度
options_enabled	false	启用期权交易
crypto_enabled	false	启用 24/7 加密货币交易
llm_model	gpt-4o-mini	研究模型（便宜，用于批量分析）
llm_analyst_model	gpt-4o	分析师模型（智能，用于交易决策）

LLM 提供商配置

MAHORAGA 支持通过三种模式使用多个 LLM 提供商：

模式	描述	必需的环境变量
openai-raw	直接使用 OpenAI API（默认）	OPENAI_API_KEY
ai-sdk	Vercel AI SDK，支持 5 家提供商	一个或多个提供商的密钥
cloudflare-gateway	Cloudflare AI Gateway (/compat)	CLOUDFLARE_AI_GATEWAY_ACCOUNT_ID、CLOUDFLARE_AI_GATEWAY_ID、CLOUDFLARE_AI_GATEWAY_TOKEN

可选的 OpenAI 基础 URL 替换：

• OPENAI_BASE_URL — 替换用于 OpenAI 请求的基础 URL。适用于 LLM_PROVIDER=openai-raw 以及 LLM_PROVIDER=ai-sdk 中的 OpenAI 模型（以 openai/ 开头）。默认值：https://api.openai.com/v1。

Cloudflare AI Gateway 注意事项：

• 该集成会调用 Cloudflare 兼容 OpenAI 的 /compat/chat/completions 端口，并始终发送 cf-aig-authorization。
• 它适用于 BYOK/统一计费设置，在这种情况下上游提供商的密钥已在 Cloudflare 中配置（因此您的 Worker 不会发送提供商的 API 密钥）。
• 模型采用 {provider}/{model} 格式（例如 openai/gpt-5-mini、google-ai-studio/gemini-2.5-flash、anthropic/claude-sonnet-4-5）。

AI SDK 支持的提供商：

提供商	环境变量	示例模型
OpenAI	OPENAI_API_KEY	openai/gpt-4o、openai/o1
Anthropic	ANTHROPIC_API_KEY	anthropic/claude-sonnet-4、anthropic/claude-opus-4
Google	GOOGLE_GENERATIVE_AI_API_KEY	google/gemini-2.5-pro、google/gemini-2.5-flash
xAI (Grok)	XAI_API_KEY	xai/grok-4、xai/grok-3
DeepSeek	DEEPSEEK_API_KEY	deepseek/deepseek-chat、deepseek/deepseek-reasoner

示例：使用 Claude 和 AI SDK：

npx wrangler secret put LLM_PROVIDER      # 设置为 "ai-sdk"
npx wrangler secret put LLM_MODEL         # 设置为 "anthropic/claude-sonnet-4"
npx wrangler secret put ANTHROPIC_API_KEY # 您的 Anthropic API 密钥

API 端点

端点	描述
/agent/status	完整状态（账户、持仓、信号）
/agent/enable	启用代理
/agent/disable	禁用代理
/agent/config	获取或更新配置
/agent/logs	获取最近的日志
/agent/trigger	手动触发（用于测试）
/agent/kill	紧急停止开关（使用 KILL_SWITCH_SECRET）
/mcp	MCP 服务器，用于工具访问

安全性

API 认证（必需）

所有 /agent/* 端点都需要使用 MAHORAGA_API_TOKEN 进行 Bearer 令牌认证：

curl -H "Authorization: Bearer $MAHORAGA_TOKEN" https://mahoraga.bernardoalmeida2004.workers.dev/agent/status

生成安全令牌的方法：openssl rand -base64 48

紧急停止开关

/agent/kill 端点使用单独的 KILL_SWITCH_SECRET 进行紧急关闭：

curl -H "Authorization: Bearer $KILL_SWITCH_SECRET" https://mahoraga.bernardoalmeida2004.workers.dev/agent/kill

这将立即禁用代理，取消所有警报，并清空信号缓存。

Cloudflare Access（推荐）

为了通过 SSO/电子邮件验证提供额外的安全保障，可以设置 Cloudflare Access：

# 1. 创建具有 Access:Edit 权限的 Cloudflare API 令牌
#    https://dash.cloudflare.com/profile/api-tokens

# 2. 运行设置脚本
CLOUDFLARE_API_TOKEN=your-token \
CLOUDFLARE_ACCOUNT_ID=your-account-id \
MAHORAGA_WORKER_URL=https://mahoraga.your-subdomain.workers.dev \
MAHORAGA_ALLOWED_EMAILS=you@example.com \
npm run setup:access

这将创建一个带有电子邮件验证或一次性 PIN 的 Cloudflare Access 应用程序。

项目结构

mahoraga/
├── wrangler.jsonc              # Cloudflare Workers 配置文件
├── src/
│   ├── index.ts                # 入口点及路由
│   ├── core/
│   │   ├── types.ts            # 共享类型（Signal、AgentState 等）
│   │   └── policy-broker.ts    # 使用 PolicyEngine 包装的交易执行
│   ├── durable-objects/
│   │   └── mahoraga-harness.ts # 核心编排器（轻量级——委托给策略）
│   ├── strategy/
│   │   ├── types.ts            # 策略接口契约
│   │   ├── index.ts            # 活跃策略选择器（只需更改这一行）
│   │   └── default/            # 默认的“情绪-动量”策略
│   │       ├── index.ts        # 策略组装
│   │       ├── config.ts       # 默认配置及数据源权重
│   │       ├── gatherers/      # StockTwits、Reddit、SEC、加密货币、Twitter
│   │       ├── prompts/        # LLM 提示模板
│   │       ├── rules/          # 进出场、过时、期权、加密货币规则
│   │       └── helpers/        # 股票代码提取、情绪分析
│   ├── mcp/                    # MCP 服务器及工具
│   ├── policy/                 # 交易验证与风险引擎
│   ├── providers/              # Alpaca、LLM 提供商
│   └── schemas/                # 配置模式（Zod）
├── dashboard/                  # React 仪表盘
├── docs/                       # 文档
└── migrations/                 # D1 数据库迁移

安全特性

特性	描述
模拟交易	使用 ALPACA_PAPER=true 开始
紧急停止开关	通过密钥进行紧急停止
仓位限制	最大仓位数及每个仓位的金额限制
日度亏损上限	当日亏损超过 2% 时停止交易
过时检测	自动平掉过时的仓位
无保证金	仅现金交易
无做空	仅多头仓位

社区

加入我们的 Discord 以获取帮助和讨论：

Discord 服务器

免责声明

⚠️ 重要：使用前请阅读

本软件仅用于教育和信息目的。本仓库中的任何内容均不构成金融、投资、法律或税务建议。

使用本软件即表示您确认并同意以下事项：

• 所有的交易和投资决策均由您自行承担风险
• 市场具有高度波动性，您可能损失部分或全部本金
• 不对性能、收益或结果作出任何保证
• 作者及贡献者对任何财务损失不承担任何责任
• 本软件可能存在漏洞或出现意外行为
• 过去的业绩并不保证未来的成果

请务必先进行模拟交易，并且切勿投入您无法承受损失的资金。

许可证

MIT 许可证——可供个人和商业用途免费使用。完整条款请参阅 LICENSE 文件。

MAHORAGA 快速上手指南

MAHORAGA 是一个基于大语言模型（LLM）的自主交易代理，部署在 Cloudflare Workers 上实现 7x24 小时运行。它通过监控 StockTwits 和 Reddit 的社交情绪，利用 AI 分析信号，并通过 Alpaca 执行加密货币或期权交易。

环境准备

在开始之前，请确保你拥有以下账户和环境：

• 运行环境: Node.js 18+
• 云平台: Cloudflare 账户（免费套餐即可）
• 交易接口: Alpaca 账户（支持免费模拟交易 Paper Trading）
• AI 模型: 至少一个 LLM API Key（支持 OpenAI, Anthropic, Google, xAI, DeepSeek）或使用 Cloudflare AI Gateway
• 网络提示: 由于涉及 Cloudflare 部署及海外 API 调用，建议配置好网络环境以确保 npm install 和 wrangler 命令执行顺畅。

安装步骤

1. 克隆项目并安装依赖

git clone https://github.com/ygwyg/MAHORAGA.git
cd mahoraga
npm install

2. 创建 Cloudflare 资源

使用 Wrangler CLI 创建所需的数据库和键值存储：

# 创建 D1 数据库
npx wrangler d1 create mahoraga-db
# 注意：复制输出中的 database_id 填入 wrangler.jsonc

# 创建 KV 命名空间
npx wrangler kv namespace create CACHE
# 注意：复制输出中的 id 填入 wrangler.jsonc

# 应用数据库迁移
npx wrangler d1 migrations apply mahoraga-db

3. 配置密钥 (Secrets)

请依次运行以下命令设置必要的环境变量。系统会提示你输入具体的 Key 值。

基础必填项：

# Alpaca 交易接口密钥
npx wrangler secret put ALPACA_API_KEY
npx wrangler secret put ALPACA_API_SECRET

# MAHORAGA API 认证令牌 (建议使用 openssl rand -base64 48 生成)
npx wrangler secret put MAHORAGA_API_TOKEN

# LLM 提供商模式选择 ("openai-raw", "ai-sdk", 或 "cloudflare-gateway")
npx wrangler secret put LLM_PROVIDER

# LLM 模型名称 (例如 "gpt-4o-mini" 或 "anthropic/claude-sonnet-4")
npx wrangler secret put LLM_MODEL

LLM API 密钥 (根据选择的提供商模式二选一)：

模式 A: 直接使用 OpenAI (默认)

npx wrangler secret put OPENAI_API_KEY
# 可选：覆盖 Base URL
# npx wrangler secret put OPENAI_BASE_URL

模式 B: 使用 AI SDK (支持多模型)

# 根据你选择的模型提供商设置对应的 Key
# npx wrangler secret put ANTHROPIC_API_KEY
# npx wrangler secret put GOOGLE_GENERATIVE_AI_API_KEY
# npx wrangler secret put XAI_API_KEY
# npx wrangler secret put DEEPSEEK_API_KEY

模式 C: 使用 Cloudflare AI Gateway

# npx wrangler secret put CLOUDFLARE_AI_GATEWAY_ACCOUNT_ID
# npx wrangler secret put CLOUDFLARE_AI_GATEWAY_ID
# npx wrangler secret put CLOUDFLARE_AI_GATEWAY_TOKEN

可选配置：

# 开启模拟交易 (推荐新手设置为 "true")
npx wrangler secret put ALPACA_PAPER

# 其他可选功能
# npx wrangler secret put TWITTER_BEARER_TOKEN
# npx wrangler secret put DISCORD_WEBHOOK_URL
# npx wrangler secret put KILL_SWITCH_SECRET

4. 部署项目

npx wrangler deploy

基本使用

部署完成后，你需要通过 API 启用代理并开始监控。所有请求均需携带 Bearer Token 认证。

1. 设置环境变量方便调用

将之前设置的 MAHORAGA_API_TOKEN 导出为环境变量（替换为你的实际 Token）：

export MAHORAGA_TOKEN="your-api-token"

注意：请将 https://mahoraga.bernardoalmeida2004.workers.dev 替换为你部署后生成的实际 Worker 域名。

2. 启用交易代理

发送请求启动 Agent：

curl -H "Authorization: Bearer $MAHORAGA_TOKEN" \
  https://mahoraga.bernardoalmeida2004.workers.dev/agent/enable

3. 监控运行状态

查看当前账户状态、持仓及信号分析情况：

curl -H "Authorization: Bearer $MAHORAGA_TOKEN" \
  https://mahoraga.bernardoalmeida2004.workers.dev/agent/status

查看最近日志：

curl -H "Authorization: Bearer $MAHORAGA_TOKEN" \
  https://mahoraga.bernardoalmeida2004.workers.dev/agent/logs

4. 本地开发模式 (可选)

如果你需要修改策略或调试，可以在本地运行：

# 终端 1: 启动 Worker
npx wrangler dev

# 终端 2: 启动仪表盘 (Dashboard)
cd dashboard && npm install && npm run dev

# 终端 3: 在本地启用 Agent
curl -H "Authorization: Bearer $MAHORAGA_TOKEN" \
  http://localhost:8787/agent/enable

紧急停止

若需立即停止所有交易并清除缓存，使用独立的紧急密钥：

export KILL_SWITCH_SECRET="your-kill-switch-secret"
curl -H "Authorization: Bearer $KILL_SWITCH_SECRET" \
  https://mahoraga.bernardoalmeida2004.workers.dev/agent/kill