内容
# HyperTrade
<p align="center">
<strong>用于加密货币交易研究的生产级代理运行时</strong>
</p>
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="许可证" /></a>
<a href="#"><img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python" /></a>
<a href="#"><img src="https://img.shields.io/badge/FastAPI-0.104+-009688.svg" alt="FastAPI" /></a>
<a href="#"><img src="https://img.shields.io/badge/React-18+-61DAFB.svg" alt="React" /></a>
<a href="#"><img src="https://img.shields.io/badge/TypeScript-5.0+-3178C6.svg" alt="TypeScript" /></a>
<a href="#"><img src="https://img.shields.io/badge/PostgreSQL-14+-4169E1.svg" alt="PostgreSQL" /></a>
<a href="#"><img src="https://img.shields.io/badge/status-production--verified-success.svg" alt="状态" /></a>
</p>
<p align="center">
<a href="README.zh-CN.md">中文文档</a> ·
<a href="README.en.md">英文摘要</a> ·
<a href="docs/architecture/33-system-architecture.md">架构</a> ·
<a href="docs/documentation-index.md">文档</a> ·
<a href="docs/api-reference.md">API</a> ·
<a href="docs/user-manual.md">用户手册</a> ·
<a href="docs/developer-guide.md">开发者指南</a>
</p>
---
## 概述
HyperTrade 是一个自主托管、受监管的加密货币市场研究代理运行时。它将开放式研究目标转化为具有版本控制计划、可 bounded 步骤、证据、预算、操作控制和可审计交付的**任务**。模型可以提出工作，但不能扩展权限、伪造证据或授权交易。
它连接大型语言模型的推理能力与受监管的市场数据、策略/回测事实、模拟状态观察和风险控制的测试网络意图摘要。结果是一个受控的研究循环——从自然语言问题到有证据支持的策略迭代——而不是无人值守的交易机器人。
> 📖 从 [系统架构](docs/architecture/33-system-architecture.md) 开始，然后使用 [可视化架构图](docs/architecture/19-hypertrade-architecture-diagram.md) 和 [专业运行时技术设计](docs/architecture/31-professional-agent-runtime-v2-technical-design.md) 来了解实现细节。
### HyperTrade 拥有 - 以及它不做的事情
| HyperTrade 拥有 | 它刻意不做的事情 |
| --- | --- |
| 任务生命周期、工具治理、证据/工件引用、研究编排、审计和操作交付 | 承诺盈利、提供投资建议或启用无人值守的实盘交易 |
| 经过审查的能力目录，涵盖市场、知识、策略/回测、模拟和测试网络读取表面 | 将模型文本视为证据或让规划器授予自己工具/权限 |
| 与 BitPro 的稳定 MCP/API 集成 | 直接读取 BitPro 的数据库或复制 BitPro 的交易业务逻辑 |
| 人工审查的研究和隔离的策略代码验证 | 启用主网执行；当前任务能力受治理读取 |
### 核心能力
| 领域 | 能力 |
|--------|-----------|
| **市场情报** | 实时 OKX SWAP 数据、多源指标、全球市场状态分类 |
| **策略研究** | Backtrader 回测、多变量实验、带有自动门控的证据库 |
| **模拟交易** | 具有暂停/恢复/关闭/重置控制的完整生命周期模拟 |
| **测试网络执行** | 具有风险检查的 OKX 测试网络订单批准门控（V1 中主网被阻止） |
| **BitPro 集成** | 用于策略生命周期、回测诊断和模拟监控的 MCP 适配器 |
| **知识系统** | 使用 pgvector 和审计内存持久性的 `docs/knowledge` RAG 检索 |
| **治理** | 策略强制工具注册、批准门、幂等性、确定性评估 |
> **免责声明**：存储库中的任何内容都不构成投资建议。V1 中主网实时订单执行被阻止。
---
## 架构概览
~~~mermaid
flowchart LR
U["操作员/外部代理"] --> S["Web · CLI · TUI · 桌面端<br/>REST / SSE"]
S --> C["任务控制 API"]
C --> M["任务运行时<br/>计划 · 上下文 · 验证 · 交付"]
W["SQL 租赁工作器"] --> M
M --> G["审查能力目录<br/>受监管的工具执行器"]
M --> D[("PostgreSQL + pgvector<br/>事件 · 投影 · 审计")]
G --> X["OKX · RAG · 内存<br/>BitPro MCP/API"]
C --> B["隔离策略沙盒<br/>摘要绑定 UDS"]
~~~
PostgreSQL 中的任务账本是规范的工作流状态。Web、CLI、Textual TUI 和桌面客户端是服务器状态的投影；SSE 光标允许它们在不创建第二个任务状态机情况下重新连接。每个步骤都编译一个有界的上下文包，仅执行审查的能力，验证源/工件出处，并记录验证的观察、明确的未知数、可恢复的故障或有界的重规划。
参见 [完整的系统架构](docs/architecture/33-system-architecture.md) 以了解数据流、信任边界、部署模型和贡献者规则。
### 技术栈
| 层 | 技术 |
|-------|-------------|
| **运行时** | Python 3.12+、FastAPI、SQLAlchemy、Alembic |
| **代理引擎** | 任务运行时、提供者支持的有界规划器、审查能力目录、策略强制工具执行 |
| **前端** | React 18、TypeScript 5、Vite、TanStack Query、Recharts |
| **数据库** | PostgreSQL 14+，带有 pgvector（或用于开发的 SQLite） |
| **LLM 提供者** | Vide Coding（opus-4.6）、DeepSeek、OpenAI、Codex、OpenRouter、Qwen |
| **回测** | Backtrader |
| **基础设施** | Docker Compose、Nginx、PostgreSQL 租赁、GitHub Actions CI/CD |
### 代理能力
| 能力 | 描述 | 状态 |
|-----------|-------------|--------|
| 自然语言 | 自由形式提示路由到 LLM 规划器，自动选择工具 | 生产就绪 |
| 工具调用 | 基于注册的执行，范围、批准和幂等性强制 | 生产就绪 |
| 市场情报 | OKX SWAP 报价、蜡烛图、资金、未平仓量、相对强度指标 | 生产就绪 |
| 全球市场 | 跨资产状态分类（股票、波动性、外汇、利率） | 生产就绪 |
| RAG | 基于 pgvector 的知识文档引用搜索 | 生产就绪 |
| 内存 | 带有标签、置信度评分和重要性权重的审计观察 | 生产就绪 |
| 策略研究 | Backtrader 回测、多变量实验、证据库 | 生产就绪 |
| BitPro 集成 | 用于策略生命周期、回测诊断和模拟监控的 MCP 适配器 | 生产就绪 |
| 模拟交易 | 具有完整生命周期控制的模拟执行 | 生产就绪 |
| 测试网络执行 | 具有风险验证的 OKX 测试网络订单批准门控 | 生产就绪 |
| 监控和警报 | 模拟策略、连接器健康状况、库新鲜度的只读监视器 | 生产就绪 |
| 评估套件 | 工具选择、RAG、内存、风险、报告质量的确定性评估 | 生产就绪 |
| 代理任务操作系统 | 持久会话、任务、检查点、光标事件、控制、租赁和恢复 | 生产就绪 |
| 专业任务运行时 | 严格的任务/计划/步骤合同、不可变事件、硬预算、安全分类的入口、目录有界市场/策略/模拟/测试网络读取、任务优先的 CLI/TUI/Web 投影和隔离的策略沙盒服务 | 生产验证：任务 V2 完整切换；只读沙盒和工作器金丝雀已通过 |
| 研究触发器 | 具有配额、去重和杀死开关的持久时间表/状态/漂移/数据/评估触发器 | 生产就绪（默认禁用） |
| 世界模型 | 投资组合状态跟踪和防御行动调度 | 实验中 |
---
## 快速入门
### 先决条件
- **Python 3.12+**，带有 [`uv`](https://github.com/astral-sh/uv) 包管理器
- **Node.js 18+**，带有 `pnpm`
- 至少一个聊天提供者的 **API 密钥**（Vide Coding、DeepSeek、OpenAI 等）
- **PostgreSQL 14+**，带有 pgvector（推荐）或用于开发的 SQLite
### 设置
```bash
git clone git@github.com:Shadowell/HyperTrade.git
cd HyperTrade
cp .env.example .env
# 使用您的 API 密钥编辑 .env
# 同主机 Docker 部署通常使用下面的 BitPro MCP 端点：
# BITPRO_REMOTE_MCP_URL=http://host.docker.internal:8889/api/v2/mcp/
```
### 启动
**后端**（API 服务器）：
```bash
uv run uvicorn hypertrade.main:app --app-dir backend/src --host 0.0.0.0 --port 3334
```
**前端**（Web 控制台）：
```bash
npm exec --yes pnpm@10 -- -C frontend install
npm exec --yes pnpm@10 -- -C frontend dev
```
**CLI**（命令行界面）：
```bash
uv run ht --local
```
### 访问点
| 服务 | URL |
|---------|-----|
| Web 控制台 | http://localhost:3333/harness |
| API 文档（Swagger） | http://localhost:3334/docs |
| 健康检查 | http://localhost:3334/api/health |
### Docker（PostgreSQL + pgvector）
```bash
docker compose up -d postgres
export DATABASE_URL="postgresql://hypertrade:hypertrade@localhost:5432/hypertrade"
uv run alembic upgrade head
```
---
## 使用
### 市场研究
```bash
# 自然语言查询
uv run hypertrade --local ask "看下目前市场的热度怎么样"
# 结构化命令
/price ETH
/candles BTC 1H 120
/compare ETH SOL BTC
/global-market # 跨资产状态快照
```
### 策略研究
```bash
/research 研究ETH趋势突破策略 # 创建研究记录
/backtest # 运行 Backtrader 回测
/experiment 不同参数动量策略 # 多变量实验
/strategy library momentum_v1 # 查询聚合证据
/validations list # 列出鲁棒性决策
/validations show rvld_xxx # 检查场景和硬门控
```
### BitPro 集成
```bash
# 查询回测性能
查看 BitPro 回测收益大于100%的策略有哪些
# 检查回测详情
查看 BitPro 回测 result 196 的权益曲线和交易证据
# 监控实时模拟策略
监控 BitPro 所有运行中的模拟盘策略，列出异常和数据缺口
```
### 模拟交易
```bash
/paper # 状态概览
/paper pause BTC # 暂停策略
/paper resume # 恢复所有
/paper close # 关闭仓位
/paper reset # 重置模拟
```
### 测试网络执行（批准门控）
```bash
/live intent ETH buy 0.01 reason="API smoke test"
/live intents # 列出待处理意图
/live approve loi_abc123 # 批准执行
/live execute loi_abc123 # 提交到 OKX 测试网络
```
### RAG 和内存
```bash
/rag 风控 # 知识库的语义搜索
/memory search tag:strategy # 查询审计内存
```
### API 访问
```bash
# 流式代理运行
curl -N -X POST http://localhost:3334/api/agent/runs/stream \
-H "Content-Type: application/json" \
-d '{"prompt":"请做行情归纳"}'
# RAG 搜索
curl "http://localhost:3334/api/rag/search?query=风控&limit=5"
# 内存查询
curl "http://localhost:3334/api/memory?query=市场&limit=10"
# 市场快照
curl http://localhost:3334/api/global-market/snapshot
```
### 持久代理会话和任务
每个新的本地或 API 代理运行都由持久会话和任务支持。`AgentRun` 保留不变的执行尝试，而任务拥有暂停、恢复、取消、重试、分支、预算、检查点、租赁和恢复状态。
```bash
/sessions
/tasks
/task task_abc123
/task task_abc123 pause "operator review"
/task task_abc123 resume "review completed"
```
任务事件可以通过 `GET /api/agent/tasks/{task_id}/events?after=<sequence>` 或 `GET /api/agent/tasks/{task_id}/stream` 的 SSE 进行光标寻址。控制 API 需要经过身份验证的管理员、原因和幂等键。提供者超时变为结构化的可重试任务错误，而不是未捕获的 HTTP 500 响应。
---
## 文档
| 文档 | 描述 |
|----------|-------------|
| [系统架构](docs/architecture/33-system-architecture.md) | 规范的系统上下文、运行时层、信任边界、数据流、部署模型和贡献者规则 |
| [API 参考](docs/api-reference.md) | 完整的 REST/SSE API 文档 |
| [用户手册](docs/user-manual.md) | 所有界面（CLI、Web、API）的操作员指南 |
| [开发者指南](docs/developer-guide.md) | 使用工具、提供者、连接器扩展 HyperTrade |
| [文档索引](docs/documentation-index.md) | 完整文档地图 |
| [架构文档](docs/architecture/) | 系统设计、运行时合同、集成边界和实现决策 |
| [产品规格](docs/spec.md) | 愿景、范围和路线图 |
| [知识库](docs/knowledge/) | 操作员指南和最佳实践 |
| [运行手册](docs/runbooks/) | 部署、监控、事件响应 |
所有主要文档均有中文翻译。
---
## 开发
### 质量门控
```bash
./scripts/check.sh # 完整套件：测试、lint、类型检查
uv run pytest tests/ -v # 运行特定测试
```
### 代码标准
**Python**：
```bash
uv run ruff format . # 自动格式化
uv run ruff check . # Lint
uv run mypy backend/src # 类型检查
```
**前端**：
```bash
npm exec --yes pnpm@10 -- -C frontend lint
npm exec --yes pnpm@10 -- -C frontend format
```
### 评估套件
确定性评估守护进程防止工具选择、RAG 引用、内存行为、风险拒绝、BitPro 源代码使用和报告质量等方面的回归。
```bash
uv run ht --local /evals
curl http://localhost:3334/api/evals/status
```
所需的门控目前涵盖 40 个确定性案例：14 个遗留代理合同和 26 个版本的研究操作系统案例，适用于固定质量队列、任务恢复、角色/节点顺序、证据、可复制性和预算、故障、光标重放、隐私和工具安全。
---
## 致谢
感谢所有贡献者对 HyperTrade 的支持。
# /triggers kill on|off <reason>
生产环境在 `RESEARCH_TRIGGERS_ENABLED=true` 被明确设置之前保持惰性。每次触发仍会重新验证活跃的授权和有界的零回测预算。
Sprint 104 实现了受管制的 Memory 断言和无代码的 Skill 生命周期。断言需要活跃的 Evidence V2 和人工审查；冲突和过期的来源在正常 Memory 搜索期间关闭。Skills 需要静态策略、HMAC 验证的隔离评估和单独的管理员批准，才能进入匹配的角色提示。它们不能添加工具、执行代码或扩大纸质/实时权限。操作员通过 Web Memory 管理、TUI 管理选项卡或 CLI 中的 `/assertions` 和 `/skills` 审查相同的状态。生产验收通过；空的 `SKILL_EVAL_ATTESTATION_SECRET` 有意阻止评估导入，直到服务器操作员配置共享的隔离评估密钥。
Sprint 105 实现了投资组合级别的策略生命周期审查。它保留了明确的未知数据、有界的对齐回报相关性/共享暴露摘要和不可变的 人工接受/拒绝/保持记录。操作员使用 Web `/harness/portfolio`、Textual 投资组合选项卡、REST `/api/portfolio/assessments*` 或 CLI `/portfolio-v2`（`/pv2`）。每个建议仅限于观察、定向研究或命名的人工审查；自动资本、重新平衡、暂停/启动、促销和订单操作被禁止。生产验收在 Alembic `0018` 上通过；空卡烟雾仍然是 `needs_data`，具有明确的未知数，不执行任何生命周期或交易操作。
Sprint 107 将 StrategyCard 创建移动到不可变的 ExperimentManifest 边界。使用 CLI `/cards` 或 Web/TUI 策略和投资组合界面来检查稳定版本、完整性、缺失的来源和固定的研究漏斗。卡快照和审查决策仅为审计投影；它们不能创建纸质会话、下订单或分配资本。在 Alembic `0019` 上通过生产验收：三个历史 Manifests 产生了 一个血统、三个版本和三个不可变的快照，重复协调是幂等的，并且没有纸质或执行侧计数更改。 Gate F 已关闭；Sprint 108 是下一个活跃的切片。
Sprint 108 从批准的 BitPro MCP 读取合约中构建有界的 PortfolioObservationWindow 和数据质量摘要。HyperTrade 仅存储源引用和统计数据，而不是完整的权益、回报、头寸、交易或订单系列；缺失/过时的输入仍为明确的未知数。数据平面不能启动纸质交易、下达实时订单或更改资本。操作员通过 Web 投资组合、Textual、REST `/api/portfolio/observation-windows*` 或 CLI `/windows list|capture|show|diff` 检查或捕获相同的服务器投影。 PortfolioAssessment 现在引用不可变的窗口 ID/内容哈希，而不是独立解释监视器快照。在 Alembic `0020` 上通过生产验收：固定的三卡分母产生了一个可用的和两个明确的无窗口策略，重放是幂等的，并且持久的摘要不包含原始序列键。 Sprint 109 是下一个活跃的切片。
Sprint 109 仅在市场、符号、时间范围、成本模型、水平和桶相同时，对提交的纸质证据进行分组。 Champion/Challenger/Watch 输出是过期的审查提案，而不是回报排名或执行指令。生产验收保留了所有三个卡，但正确返回了 `needs_data`，0 个可比较的成员和 0 个提案，因为没有完整的 comparable 纸质 cohort 存在；重建是幂等的，并且纸质/实时计数未更改。 Gate G 已关闭，提供 Sprint 110 使用的有管制的输入边界。
Sprint 110 将接受的、未过期的 cohort 标签变成不可变的假设投资组合场景。只有等权重、证据完整、反向波动率和上限风险预算代理模板存在；权重为 Decimal，上限为 1，而成本、压力测试和订单影响仍为明确的假设。人工审查记录仅研究意图，不能分配资本或创建订单。生产验收保留了三卡分母，并正确返回了 `needs_data`，0 个合格成员和 0 个场景；幂等性、有效载荷隔离和未更改的纸质/实时计数关闭了 Gate H 和 Sprint 106–110 路线图。
---
## 部署
通过 GitHub Actions 自动部署到自托管的运行器，在推送到 `main` 时触发。
```bash
# 手动部署
ssh hypertrade-server
sudo -u hypertrade /opt/hypertrade/deploy/deploy.sh
# 部署后验证
curl -fsS http://localhost:3334/api/health
hypertrade ask "看下ETH行情"
```
有关详细的部署和监控程序，请参阅 [Runbooks](docs/runbooks/)。
---
## 安全
- **密钥**：通过环境变量管理和 API 密钥、令牌和凭证；从不提交
- **BitPro 边界**：所有 BitPro 访问仅通过稳定的 MCP/API 合约
- **审计轨迹**：每个工具执行都记录时间戳、有效载荷和出处
- **幂等性**：写入操作需要幂等键
- **批准门控**：Testnet 订单和破坏性操作的人工参与
- **Testnet First**：V1 中阻止主网实时执行
---
## 路线图
### 当前（V2）
| 倡议 | 状态 |
|-----------|--------|
| World Model — 投资组合状态和防御行动 | 进行中 |
| Global Market — 跨资产状态分类 | 生产环境 |
| Vide Coding (opus-4.6) 提供商 | 生产环境 |
| 增强的输出格式 | 已完成 |
| 代理会话和任务 OS | 生产环境 |
| 研究证据 V2 合约 | 生产环境 |
| 多代理研究图 V1 | 生产环境 |
| 可复制的实验账本 | 生产环境 |
| 健壮性验证套件 | 生产环境 |
| 代理研究评估基础 | 生产环境 |
| 代理研究质量关闭 | 生产环境（Sprint 106） |
| StrategyCard V2 和研究漏斗 | 生产环境（Sprint 107） |
| 投资组合证据数据平面 | 生产环境（Sprint 108） |
| Champion–Challenger 纸质孵化 | 生产环境（Sprint 109） |
| Shadow 投资组合治理 | 生产环境（Sprint 110） |
| 专业代理运行时 V2 | Sprint 116 已完成：Mission V2 是生产默认；旧版写入归档 |
### 计划中（V3+）
- [研究运营和 Shadow 投资组合路线图](docs/architecture/29-research-operations-shadow-portfolio-roadmap.md)
- [专业代理运行时 V2 路线图](docs/architecture/30-professional-agent-runtime-v2-roadmap.md)
- [专业代理运行时 V2 技术设计](docs/architecture/31-professional-agent-runtime-v2-technical-design.md)
- 自定义策略 DSL
- 多交易所支持（Binance，Bybit）
- 高级风险建模（VaR，CVaR）
- 主网执行框架（待治理）
---
## 贡献
1. 在 `docs/contracts/` 中审查活跃的冲刺范围
2. 将更改限制在合约范围内
3. 在提交前运行 `./scripts/check.sh`
4. 提交到 `main`（当前工作流中没有功能分支）
5. 推送触发自动 CI/CD 部署
有关详细的贡献指南，请参阅 [开发者指南](docs/developer-guide.md)。
---
## 致谢
使用以下优秀项目和服务构建：
[OKX API](https://www.okx.com/docs-v5/) · [Backtrader](https://www.backtrader.com/) · [FastAPI](https://fastapi.tiangolo.com/) · [LangGraph](https://langchain-ai.github.io/langgraph/) · [React](https://reactjs.org/) · [Vite](https://vitejs.dev/) · [pgvector](https://github.com/pgvector/pgvector) · [Alembic](https://alembic.sqlalchemy.org/)
---
<div align="center">
**[文档](docs/documentation-index.md)** · **[用户手册](docs/user-manual.md)** · **[开发者指南](docs/developer-guide.md)** · **[API 参考](docs/api-reference.md)**
</div>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器