diff --git a/.github/ISSUE_TEMPLATE/bounty_claim.md b/.github/ISSUE_TEMPLATE/bounty_claim.md new file mode 100644 index 00000000..b8fc97eb --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bounty_claim.md @@ -0,0 +1,93 @@ +--- +name: Bounty Claim +about: Claim a bounty task or propose a new bounty +title: '[BOUNTY CLAIM] ' +labels: bounty +assignees: '' +--- + +## 💰 Bounty Information + +**Claiming existing bounty?** +- Issue #: +- Bounty amount: + +**OR proposing new bounty?** +- Proposed feature/fix: +- Estimated effort: [Small / Medium / Large] + +--- + +## 👤 About You + +**Name/Username:** + +**Contact:** +- GitHub: @your_username +- Telegram: @your_telegram (optional) +- Email: your@email.com (optional) + +**Relevant Experience:** +- +- +- + +--- + +## 📋 Implementation Plan + +### 1. Approach + +- How will you implement this? +- What components will be affected? +- Any dependencies or libraries needed? + +### 2. Timeline +- **Start date:** +- **Estimated completion:** +- **Milestones:** + - [ ] Week 1: ... + - [ ] Week 2: ... + - [ ] Week 3: ... + +### 3. Deliverables +- [ ] Working code (merged PR) +- [ ] Unit tests (if applicable) +- [ ] Documentation updates +- [ ] Demo video/screenshots + +--- + +## 🔍 Questions for Maintainers + + + +1. +2. +3. + +--- + +## 📚 References + + + +- + +--- + +## ✅ Acknowledgment + +By claiming this bounty, I acknowledge that: +- [ ] I have read the [Contributing Guide](../../CONTRIBUTING.md) +- [ ] I will follow the [Code of Conduct](../../CODE_OF_CONDUCT.md) +- [ ] I understand the acceptance criteria +- [ ] My contribution will be licensed under MIT License +- [ ] Payment is subject to successful PR merge + +--- + +**For maintainers:** +- [ ] Bounty claim approved +- [ ] Issue assigned to claimant +- [ ] Timeline agreed upon diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..e41f17b0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,47 @@ +--- +name: Bug Report +about: Report a bug to help us improve NOFX +title: '[BUG] ' +labels: bug +assignees: '' +--- + +## 🐛 Bug Description + + +## 📋 Steps to Reproduce +1. Go to '...' +2. Click on '...' +3. Run command '...' +4. See error + +## ✅ Expected Behavior + + +## ❌ Actual Behavior + + +## 📸 Screenshots / Logs + + +``` +Paste logs here +``` + +## 💻 Environment +- **OS:** [e.g. macOS 13, Ubuntu 22.04, Windows 11] +- **Go Version:** [e.g. 1.21.5] +- **Node.js Version:** [e.g. 18.17.0] +- **NOFX Version/Commit:** [e.g. v3.0.0 or commit hash] +- **Deployment Method:** [Docker / Manual / PM2] +- **Exchange:** [Binance / Hyperliquid / Aster] + +## 🔧 Additional Context + + +- Does this happen consistently or intermittently? +- Did it work before? When did it break? +- Any recent configuration changes? + +## ✋ Possible Solution + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..8fd87aeb --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,153 @@ +# Pull Request + +## 📝 Description + + + +## 🎯 Type of Change + + + +- [ ] 🐛 Bug fix (non-breaking change which fixes an issue) +- [ ] ✨ New feature (non-breaking change which adds functionality) +- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] 📝 Documentation update +- [ ] 🎨 Code style update (formatting, renaming) +- [ ] ♻️ Refactoring (no functional changes) +- [ ] ⚡ Performance improvement +- [ ] ✅ Test update +- [ ] 🔧 Build/config change + +## 🔗 Related Issues + + + +- Closes # +- Related to # + +## 📋 Changes Made + + + +- Change 1 +- Change 2 +- Change 3 + +## 🧪 Testing + +### Manual Testing + + + +- [ ] Tested locally (manual verification) +- [ ] Tested on testnet (for exchange integrations) +- [ ] Tested with different configurations +- [ ] Verified no existing functionality broke + +### Test Environment + +- **OS:** [e.g. macOS, Ubuntu] +- **Go Version:** [e.g. 1.21.5] +- **Exchange:** [if applicable] + +### Test Results + + + +``` +Test output here +``` + +## 📸 Screenshots / Demo + + + + + +**Before:** + + +**After:** + + +## ✅ Checklist + + + +### Code Quality + +- [ ] My code follows the project's code style ([Contributing Guide](../CONTRIBUTING.md)) +- [ ] I have performed a self-review of my code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] My changes generate no new warnings or errors +- [ ] Code compiles successfully (`go build` / `npm run build`) +- [ ] I have run `go fmt` (for Go code) + +### Testing + +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally +- [ ] I have tested on testnet (for trading/exchange changes) + +### Documentation + +- [ ] I have updated the documentation accordingly +- [ ] I have updated the README if needed +- [ ] I have added inline code comments where necessary +- [ ] I have updated type definitions (for TypeScript changes) + +### Git + +- [ ] My commits follow the conventional commits format (`feat:`, `fix:`, etc.) +- [ ] I have rebased my branch on the latest `dev` branch +- [ ] There are no merge conflicts + +## 🔒 Security Considerations + + + +- [ ] No API keys or secrets are hardcoded +- [ ] User inputs are properly validated +- [ ] No SQL injection vulnerabilities introduced +- [ ] Authentication/authorization properly handled +- [ ] N/A (not security-related) + +## ⚡ Performance Impact + + + +- [ ] No significant performance impact +- [ ] Performance improved +- [ ] Performance may be impacted (explain below) + + + +## 📚 Additional Notes + + + +--- + +## For Bounty Claims + + + +- [ ] This PR is for bounty issue # +- [ ] All acceptance criteria from the bounty issue are met +- [ ] I have included a demo video/screenshots +- [ ] I am ready for payment upon merge + +**Payment Details:** + +--- + +## 🙏 Reviewer Notes + + + +--- + +**By submitting this PR, I confirm that:** +- [ ] I have read the [Contributing Guidelines](../CONTRIBUTING.md) +- [ ] I agree to the [Code of Conduct](../CODE_OF_CONDUCT.md) +- [ ] My contribution is licensed under the MIT License diff --git a/.gitignore b/.gitignore index 4dc2afc9..ad0d2a5b 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,9 @@ *.iml *.xml +# AI 工具 +.claude/ + # 编译产物 nofx-auto *.exe diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..f520303d --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,203 @@ +# Changelog + +All notable changes to the NOFX project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +**Languages:** [English](CHANGELOG.md) | [中文](CHANGELOG.zh-CN.md) + +--- + +## [Unreleased] + +### Added +- Documentation system with multi-language support (EN/CN/RU/UK) +- Complete getting-started guides (Docker, PM2, Custom API) +- Architecture documentation with system design details +- User guides with FAQ and troubleshooting +- Community documentation with bounty programs + +### Changed +- Reorganized documentation structure into logical categories +- Updated all README files with proper navigation links + +--- + +## [3.0.0] - 2025-10-30 + +### Added - Major Architecture Transformation 🚀 + +**Complete System Redesign - Web-Based Configuration Platform** + +This is a **major breaking update** that completely transforms NOFX from a static config-based system to a modern web-based trading platform. + +#### Database-Driven Architecture +- SQLite integration replacing static JSON config +- Persistent storage with automatic timestamps +- Foreign key relationships and triggers for data consistency +- Separate tables for AI models, exchanges, traders, and system config + +#### Web-Based Configuration Interface +- Complete web-based configuration management (no more JSON editing) +- AI Model setup through web interface (DeepSeek/Qwen API keys) +- Exchange management (Binance/Hyperliquid credentials) +- Dynamic trader creation (combine any AI model with any exchange) +- Real-time control (start/stop traders without system restart) + +#### Flexible Architecture +- Separation of concerns (AI models and exchanges independent) +- Mix & match capability (unlimited combinations) +- Scalable design (support for unlimited traders) +- Clean slate approach (no default traders) + +#### Enhanced API Layer +- RESTful design with complete CRUD operations +- New endpoints: + - `GET/PUT /api/models` - AI model configuration + - `GET/PUT /api/exchanges` - Exchange configuration + - `POST/DELETE /api/traders` - Trader management + - `POST /api/traders/:id/start|stop` - Trader control +- Updated documentation for all API endpoints + +#### Modernized Codebase +- Type safety with proper separation of configuration types +- Database abstraction with prepared statements +- Comprehensive error handling and validation +- Better code organization (database, API, business logic) + +### Changed +- **BREAKING**: Old `config.json` files no longer used +- Configuration must be done through web interface +- Much easier setup and better UX +- No more server restarts for configuration changes + +### Why This Matters +- 🎯 **User Experience**: Much easier to configure and manage +- 🔧 **Flexibility**: Create any combination of AI models and exchanges +- 📊 **Scalability**: Support for complex multi-trader setups +- 🔒 **Reliability**: Database ensures data persistence and consistency +- 🚀 **Future-Proof**: Foundation for advanced features + +--- + +## [2.0.2] - 2025-10-29 + +### Fixed - Critical Bug Fixes: Trade History & Performance Analysis + +#### PnL Calculation - Major Error Fixed +- **Fixed**: PnL now calculated as actual USDT amount instead of percentage only +- Previously ignored position size and leverage (e.g., 100 USDT @ 5% = 1000 USDT @ 5%) +- Now: `PnL (USDT) = Position Value × Price Change % × Leverage` +- Impact: Win rate, profit factor, and Sharpe ratio now accurate + +#### Position Tracking - Missing Critical Data +- **Fixed**: Open position records now store quantity and leverage +- Previously only stored price and time +- Essential for accurate PnL calculations + +#### Position Key Logic - Long/Short Conflict +- **Fixed**: Changed from `symbol` to `symbol_side` format +- Now properly distinguishes between long and short positions +- Example: `BTCUSDT_long` vs `BTCUSDT_short` + +#### Sharpe Ratio Calculation - Code Optimization +- **Changed**: Replaced custom Newton's method with `math.Sqrt` +- More reliable, maintainable, and efficient + +### Why This Matters +- Historical trade statistics now show real USDT profit/loss +- Performance comparison between different leverage trades is accurate +- AI self-learning mechanism receives correct feedback +- Multi-position tracking (long + short simultaneously) works correctly + +--- + +## [2.0.2] - 2025-10-29 + +### Fixed - Aster Exchange Precision Error + +- Fixed Aster exchange precision error (code -1111) +- Improved price and quantity formatting to match exchange requirements +- Added detailed precision processing logs for debugging +- Enhanced all order functions with proper precision handling + +#### Technical Details +- Added `formatFloatWithPrecision` function +- Price and quantity formatted according to exchange specifications +- Trailing zeros removed to optimize API requests + +--- + +## [2.0.1] - 2025-10-29 + +### Fixed - ComparisonChart Data Processing + +- Fixed ComparisonChart data processing logic +- Switched from cycle_number to timestamp grouping +- Resolved chart freezing issue when backend restarts +- Improved chart data display (shows all historical data chronologically) +- Enhanced debugging logs + +--- + +## [2.0.0] - 2025-10-28 + +### Added - Major Updates + +- AI self-learning mechanism (historical feedback, performance analysis) +- Multi-trader competition mode (Qwen vs DeepSeek) +- Binance-style UI (complete interface imitation) +- Performance comparison charts (real-time ROI comparison) +- Risk control optimization (per-coin position limit adjustment) + +### Fixed + +- Fixed hardcoded initial balance issue +- Fixed multi-trader data sync issue +- Optimized chart data alignment (using cycle_number) + +--- + +## [1.0.0] - 2025-10-27 + +### Added - Initial Release + +- Basic AI trading functionality +- Decision logging system +- Simple Web interface +- Support for Binance Futures +- DeepSeek and Qwen AI model integration + +--- + +## How to Use This Changelog + +### For Users +- Check the [Unreleased] section for upcoming features +- Review version sections to understand what changed +- Follow migration guides for breaking changes + +### For Contributors +When making changes, add them to the [Unreleased] section under appropriate categories: +- **Added** - New features +- **Changed** - Changes to existing functionality +- **Deprecated** - Features that will be removed +- **Removed** - Features that were removed +- **Fixed** - Bug fixes +- **Security** - Security fixes + +When releasing a new version, move [Unreleased] items to a new version section with date. + +--- + +## Links + +- [Documentation](docs/README.md) +- [Contributing Guidelines](CONTRIBUTING.md) +- [Security Policy](SECURITY.md) +- [GitHub Repository](https://github.com/tinkle-community/nofx) + +--- + +**Last Updated:** 2025-11-01 diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md new file mode 100644 index 00000000..0bfdab3d --- /dev/null +++ b/CHANGELOG.zh-CN.md @@ -0,0 +1,203 @@ +# 更新日志 + +NOFX 项目的所有重要更改都将记录在此文件中。 + +本文件格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)， +本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 + +**语言:** [English](CHANGELOG.md) | [中文](CHANGELOG.zh-CN.md) + +--- + +## [未发布] + +### 新增 +- 多语言文档系统（英文/中文/俄语/乌克兰语） +- 完整的快速开始指南（Docker、PM2、自定义 API） +- 架构文档，包含系统设计细节 +- 用户指南，包含 FAQ 和故障排除 +- 社区文档，包含悬赏计划 + +### 变更 +- 重组文档结构为逻辑分类 +- 更新所有 README 文件，添加适当的导航链接 + +--- + +## [3.0.0] - 2025-10-30 + +### 新增 - 重大架构变革 🚀 + +**系统完全重新设计 - 基于 Web 的配置平台** + +这是一个**重大破坏性更新**，将 NOFX 从基于静态配置的系统完全转变为现代化的 Web 交易平台。 + +#### 数据库驱动架构 +- SQLite 集成，取代静态 JSON 配置 +- 持久化存储，自动时间戳 +- 外键关系和触发器确保数据一致性 +- 为 AI 模型、交易所、交易员和系统配置分离表结构 + +#### 基于 Web 的配置界面 +- 完整的 Web 配置管理（无需编辑 JSON） +- 通过 Web 界面设置 AI 模型（DeepSeek/Qwen API 密钥） +- 交易所管理（Binance/Hyperliquid 凭证） +- 动态创建交易员（结合任意 AI 模型和交易所） +- 实时控制（无需重启即可启动/停止交易员） + +#### 灵活架构 +- 关注点分离（AI 模型和交易所独立） +- 混合搭配能力（无限组合） +- 可扩展设计（支持无限交易员） +- 清洁起点（无默认交易员） + +#### 增强的 API 层 +- RESTful 设计，完整的 CRUD 操作 +- 新端点： + - `GET/PUT /api/models` - AI 模型配置 + - `GET/PUT /api/exchanges` - 交易所配置 + - `POST/DELETE /api/traders` - 交易员管理 + - `POST /api/traders/:id/start|stop` - 交易员控制 +- 更新所有 API 端点文档 + +#### 现代化代码库 +- 类型安全，适当分离配置类型 +- 数据库抽象，使用预处理语句 +- 全面的错误处理和验证 +- 更好的代码组织（数据库、API、业务逻辑） + +### 变更 +- **破坏性变更**：不再使用旧的 `config.json` 文件 +- 必须通过 Web 界面进行配置 +- 设置更简单，用户体验更好 +- 配置更改无需重启服务器 + +### 为什么重要 +- 🎯 **用户体验**：配置和管理更容易 +- 🔧 **灵活性**：创建 AI 模型和交易所的任意组合 +- 📊 **可扩展性**：支持复杂的多交易员设置 +- 🔒 **可靠性**：数据库确保数据持久性和一致性 +- 🚀 **面向未来**：为高级功能奠定基础 + +--- + +## [2.0.2] - 2025-10-29 + +### 修复 - 关键错误修复：交易历史和性能分析 + +#### 盈亏计算 - 重大错误修复 +- **修复**：盈亏现在计算为实际 USDT 金额，而不是仅百分比 +- 之前忽略了仓位大小和杠杆（例如，100 USDT @ 5% = 1000 USDT @ 5%） +- 现在：`盈亏 (USDT) = 仓位价值 × 价格变化 % × 杠杆` +- 影响：胜率、盈利因子和夏普比率现在准确 + +#### 仓位跟踪 - 缺失关键数据 +- **修复**：持仓记录现在存储数量和杠杆 +- 之前只存储价格和时间 +- 这对准确的盈亏计算至关重要 + +#### 仓位键逻辑 - 多空冲突 +- **修复**：从 `symbol` 改为 `symbol_side` 格式 +- 现在正确区分多头和空头仓位 +- 示例：`BTCUSDT_long` vs `BTCUSDT_short` + +#### 夏普比率计算 - 代码优化 +- **变更**：用 `math.Sqrt` 替换自定义牛顿法 +- 更可靠、可维护和高效 + +### 为什么重要 +- 历史交易统计现在显示真实的 USDT 盈亏 +- 不同杠杆交易之间的性能比较准确 +- AI 自学习机制接收正确的反馈 +- 多仓位跟踪（同时多空）正常工作 + +--- + +## [2.0.2] - 2025-10-29 + +### 修复 - Aster 交易所精度错误 + +- 修复 Aster 交易所精度错误（代码 -1111） +- 改进价格和数量格式化以匹配交易所要求 +- 添加详细的精度处理日志用于调试 +- 增强所有订单函数的精度处理 + +#### 技术细节 +- 添加 `formatFloatWithPrecision` 函数 +- 根据交易所规范格式化价格和数量 +- 删除尾随零以优化 API 请求 + +--- + +## [2.0.1] - 2025-10-29 + +### 修复 - ComparisonChart 数据处理 + +- 修复 ComparisonChart 数据处理逻辑 +- 从 cycle_number 切换到时间戳分组 +- 解决后端重启时图表冻结问题 +- 改进图表数据显示（按时间顺序显示所有历史数据） +- 增强调试日志 + +--- + +## [2.0.0] - 2025-10-28 + +### 新增 - 重大更新 + +- AI 自学习机制（历史反馈、性能分析） +- 多交易员竞赛模式（Qwen vs DeepSeek） +- 币安风格 UI（完整界面仿制） +- 性能比较图表（实时 ROI 比较） +- 风险控制优化（每币种仓位限制调整） + +### 修复 + +- 修复硬编码初始余额问题 +- 修复多交易员数据同步问题 +- 优化图表数据对齐（使用 cycle_number） + +--- + +## [1.0.0] - 2025-10-27 + +### 新增 - 初始版本 + +- 基础 AI 交易功能 +- 决策日志系统 +- 简单的 Web 界面 +- 支持币安合约 +- DeepSeek 和 Qwen AI 模型集成 + +--- + +## 如何使用本更新日志 + +### 用户 +- 查看 [未发布] 部分了解即将推出的功能 +- 查看版本部分了解变更内容 +- 遵循破坏性变更的迁移指南 + +### 贡献者 +进行更改时，将它们添加到 [未发布] 部分的相应类别下： +- **新增** - 新功能 +- **变更** - 现有功能的变更 +- **弃用** - 即将删除的功能 +- **移除** - 已删除的功能 +- **修复** - 错误修复 +- **安全** - 安全修复 + +发布新版本时，将 [未发布] 项目移动到带日期的新版本部分。 + +--- + +## 链接 + +- [文档](docs/README.md) +- [贡献指南](CONTRIBUTING.md) +- [安全策略](SECURITY.md) +- [GitHub 仓库](https://github.com/tinkle-community/nofx) + +--- + +**最后更新:** 2025-11-01 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..d1c34065 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,237 @@ +# Contributor Covenant Code of Conduct / 贡献者公约行为准则 + +**Languages:** [English](#english) | [中文](#中文) + +--- + +# English + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at: + + +You can also report via: +- **Telegram:** Direct message to [@Web3Tinkle](https://t.me/Web3Tinkle) +- **Twitter:** DM to [@nofx_ai](https://x.com/nofx_ai) + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations + +--- + +# 中文 + +## 我们的承诺 + +作为成员、贡献者和领导者，我们承诺使社区中的每个人都不受骚扰，无论其年龄、体型、明显或不明显的残疾、种族、性别特征、性别认同和表达、经验水平、教育程度、社会经济地位、国籍、个人外貌、种族、种姓、肤色、宗教或性认同和取向如何。 + +我们承诺以有助于开放、友好、多元、包容和健康社区的方式行事和互动。 + +## 我们的标准 + +有助于为我们的社区创造积极环境的行为示例包括： + +* 对他人表现出同理心和善意 +* 尊重不同的意见、观点和经验 +* 给予并优雅地接受建设性反馈 +* 接受责任并向受我们错误影响的人道歉，并从经验中学习 +* 关注不仅对我们个人最好，而且对整个社区最好的事情 + +不可接受的行为示例包括： + +* 使用性化的语言或图像，以及任何形式的性关注或性挑逗 +* 挑衅、侮辱性或贬损性评论，以及人身或政治攻击 +* 公开或私下骚扰 +* 未经他人明确许可，发布他人的私人信息，如物理地址或电子邮件地址 +* 在专业环境中可能被合理认为不适当的其他行为 + +## 执行责任 + +社区领导者负责阐明和执行我们可接受行为的标准，并将对他们认为不适当、威胁性、冒犯性或有害的任何行为采取适当和公平的纠正措施。 + +社区领导者有权利和责任删除、编辑或拒绝不符合本行为准则的评论、提交、代码、wiki 编辑、问题和其他贡献，并在适当时传达审核决定的原因。 + +## 范围 + +本行为准则适用于所有社区空间，也适用于个人在公共空间正式代表社区的情况。代表我们社区的示例包括使用官方电子邮件地址、通过官方社交媒体账户发布信息，或在线上或线下活动中担任指定代表。 + +## 执行 + +可以向负责执行的社区领导者报告滥用、骚扰或其他不可接受行为的实例： + + +您也可以通过以下方式报告： +- **Telegram:** 直接消息 [@Web3Tinkle](https://t.me/Web3Tinkle) +- **Twitter:** 私信 [@nofx_ai](https://x.com/nofx_ai) + +所有投诉都将得到迅速和公正的审查和调查。 + +所有社区领导者都有义务尊重任何事件报告者的隐私和安全。 + +## 执行指南 + +社区领导者将遵循这些社区影响指南来确定他们认为违反本行为准则的任何行动的后果： + +### 1. 纠正 + +**社区影响**：使用不适当的语言或其他被认为在社区中不专业或不受欢迎的行为。 + +**后果**：社区领导者的私下书面警告，说明违规的性质和解释为什么行为不适当。可能要求公开道歉。 + +### 2. 警告 + +**社区影响**：通过单一事件或一系列行动违规。 + +**后果**：警告并说明持续行为的后果。在指定时间内不与相关人员互动，包括不主动与执行行为准则的人互动。这包括避免在社区空间以及外部渠道（如社交媒体）的互动。违反这些条款可能导致临时或永久禁令。 + +### 3. 临时禁令 + +**社区影响**：严重违反社区标准，包括持续的不当行为。 + +**后果**：在指定时间内临时禁止与社区进行任何形式的互动或公开交流。在此期间，不允许与相关人员进行公开或私下互动，包括不主动与执行行为准则的人互动。违反这些条款可能导致永久禁令。 + +### 4. 永久禁令 + +**社区影响**：表现出违反社区标准的模式，包括持续的不当行为、对个人的骚扰，或对个人类别的攻击或贬低。 + +**后果**：永久禁止在社区内进行任何形式的公开互动。 + +## 归属 + +本行为准则改编自 [贡献者公约][homepage] 2.1 版，可在 +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1] 获取。 + +社区影响指南受到 [Mozilla 行为准则执行阶梯][Mozilla CoC] 的启发。 + +有关本行为准则的常见问题解答，请参阅 [https://www.contributor-covenant.org/faq][FAQ]。翻译版本可在 [https://www.contributor-covenant.org/translations][translations] 获取。 + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..5175fc6a --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Tinkle Community (NOFX Project) + +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. diff --git a/README.md b/README.md index 7ac4f409..0fa6210e 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,36 @@ [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Backed by Amber.ac](https://img.shields.io/badge/Backed%20by-Amber.ac-orange.svg)](https://amber.ac) -**Languages:** [English](README.md) | [中文](README.zh-CN.md) | [Українська](README.uk.md) | [Русский](README.ru.md) +**Languages:** [English](README.md) | [中文](docs/i18n/zh-CN/README.md) | [Українська](docs/i18n/uk/README.md) | [Русский](docs/i18n/ru/README.md) **Official Twitter:** [@nofx_ai](https://x.com/nofx_ai) +**📚 Documentation:** [Docs Home](docs/README.md) | [Getting Started](docs/getting-started/README.md) | [Changelog](CHANGELOG.md) | [Contributing](CONTRIBUTING.md) | [Security](SECURITY.md) + +--- + +## 📑 Table of Contents + +- [🚀 Universal AI Trading Operating System](#-universal-ai-trading-operating-system) +- [👥 Developer Community](#-developer-community) +- [🆕 What's New](#-whats-new-latest-update) +- [📸 Screenshots](#-screenshots) +- [✨ Current Implementation](#-current-implementation---crypto-markets) +- [🔮 Roadmap](#-roadmap---universal-market-expansion) +- [🏗️ Technical Architecture](#️-technical-architecture) +- [💰 Register Binance Account](#-register-binance-account-save-on-fees) +- [🚀 Quick Start](#-quick-start) +- [📖 AI Decision Flow](#-ai-decision-flow) +- [🧠 AI Self-Learning](#-ai-self-learning-example) +- [📊 Web Interface Features](#-web-interface-features) +- [🎛️ API Endpoints](#️-api-endpoints) +- [⚠️ Important Risk Warnings](#️-important-risk-warnings) +- [🛠️ Common Issues](#️-common-issues) +- [📈 Performance Tips](#-performance-optimization-tips) +- [🔄 Changelog](#-changelog) +- [📄 License](#-license) +- [🤝 Contributing](#-contributing) + --- ## 🚀 Universal AI Trading Operating System @@ -168,78 +194,50 @@ NOFX is currently **fully operational in cryptocurrency markets** with the follo ## 🔮 Roadmap - Universal Market Expansion -Our proven crypto infrastructure is being extended to: +NOFX is on a mission to become the **Universal AI Trading Operating System** for all financial markets. -- **📈 Stock Markets**: US equities, A-shares, Hong Kong stocks -- **📊 Futures Markets**: Commodity futures, index futures -- **🎯 Options Trading**: Equity options, crypto options -- **💱 Forex Markets**: Major currency pairs, cross rates +**Vision:** Same architecture. Same agent framework. All markets. -**Same architecture. Same agent framework. All markets.** +**Expansion Markets:** +- 📈 **Stock Markets**: US equities, A-shares, Hong Kong stocks +- 📊 **Futures Markets**: Commodity futures, index futures +- 🎯 **Options Trading**: Equity options, crypto options +- 💱 **Forex Markets**: Major currency pairs, cross rates + +**Upcoming Features:** +- Enhanced AI capabilities (GPT-4, Claude 3, Gemini Pro, flexible prompt templates) +- New exchange integrations (OKX, Bybit, Lighter, EdgeX + CEX/Perp-DEX) +- Project structure refactoring (high cohesion, low coupling, SOLID principles) +- Security enhancements (AES-256 encryption for API keys, RBAC, 2FA improvements) +- User experience improvements (mobile-responsive, TradingView charts, alert system) + +📖 **For detailed roadmap and timeline, see:** +- **English:** [Roadmap Documentation](docs/roadmap/README.md) +- **中文:** [路线图文档](docs/roadmap/README.zh-CN.md) --- ## 🏗️ Technical Architecture -``` -nofx/ -├── main.go # Program entry (multi-trader manager) -├── config.json # Configuration file (API keys, ~~multi-trader config~~) (Trader config via web interface) -│ -├── api/ # HTTP API service -│ └── server.go # Gin framework, RESTful API -│ -├── trader/ # Trading core -│ ├── auto_trader.go # Auto trading main controller (single trader) -│ └── binance_futures.go # Binance futures API wrapper -│ -├── manager/ # Multi-trader management -│ └── trader_manager.go # Manages multiple trader instances -│ -├── mcp/ # Model Context Protocol - AI communication -│ └── client.go # AI API client (DeepSeek/Qwen integration) -│ -├── decision/ # AI decision engine -│ └── engine.go # Decision logic with historical feedback -│ -├── market/ # Market data fetching -│ └── data.go # Market data & technical indicators (K-line, RSI, MACD) -│ -├── pool/ # Coin pool management -│ └── coin_pool.go # AI500 + OI Top merged pool -│ -├── logger/ # Logging system -│ └── decision_logger.go # Decision recording + performance analysis -│ -├── decision_logs/ # Decision log storage -│ ├── qwen_trader/ # Qwen trader logs -│ └── deepseek_trader/ # DeepSeek trader logs -│ -└── web/ # React frontend - ├── src/ - │ ├── components/ # React components - │ │ ├── EquityChart.tsx # Equity curve chart - │ │ ├── ComparisonChart.tsx # Multi-AI comparison chart - │ │ └── CompetitionPage.tsx # Competition leaderboard - │ ├── lib/api.ts # API call wrapper - │ ├── types/index.ts # TypeScript types - │ ├── index.css # Binance-style CSS - │ └── App.tsx # Main app - └── package.json -``` +NOFX is built with a modern, modular architecture: -### Core Dependencies +- **Backend:** Go with Gin framework, SQLite database +- **Frontend:** React 18 + TypeScript + Vite + TailwindCSS +- **Multi-Exchange Support:** Binance, Hyperliquid, Aster DEX +- **AI Integration:** DeepSeek, Qwen, and custom OpenAI-compatible APIs +- **State Management:** Zustand for frontend, database-driven for backend +- **Real-time Updates:** SWR with 5-10s polling intervals -**Backend (Go)** -- `github.com/adshao/go-binance/v2` - Binance API client -- `github.com/markcheno/go-talib` - Technical indicator calculation (TA-Lib) -- `github.com/gin-gonic/gin` - HTTP API framework +**Key Features:** +- 🗄️ Database-driven configuration (no more JSON editing) +- 🔐 JWT authentication with optional 2FA support +- 📊 Real-time performance tracking and analytics +- 🤖 Multi-AI competition mode with live comparison +- 🔌 RESTful API for all configuration and monitoring -**Frontend (React + TypeScript)** -- `react` + `react-dom` - UI framework -- `recharts` - Chart library (equity curve, comparison charts) -- `swr` - Data fetching and caching -- `tailwindcss` - CSS framework +📖 **For detailed architecture documentation, see:** +- **English:** [Architecture Documentation](docs/architecture/README.md) +- **中文:** [架构文档](docs/architecture/README.zh-CN.md) --- @@ -326,8 +324,8 @@ Open your browser and visit: **http://localhost:3000** ``` **📖 For detailed Docker deployment guide, troubleshooting, and advanced configuration:** -- **English**: See [DOCKER_DEPLOY.en.md](DOCKER_DEPLOY.en.md) -- **中文**: 查看 [DOCKER_DEPLOY.md](DOCKER_DEPLOY.md) +- **English**: See [docs/getting-started/docker-deploy.en.md](docs/getting-started/docker-deploy.en.md) +- **中文**: 查看 [docs/getting-started/docker-deploy.zh-CN.md](docs/getting-started/docker-deploy.zh-CN.md) --- @@ -436,7 +434,7 @@ go build -o nofx ``` ╔════════════════════════════════════════════════════════════╗ -║ 🤖 AI多模型交易系统 - 支持 DeepSeek & Qwen ║ +║ 🤖 AI多模型交易系统 - 支持 DeepSeek & Qwen ║ ╚════════════════════════════════════════════════════════════╝ 🤖 数据库中的AI交易员配置: @@ -688,12 +686,12 @@ The leverage settings control the maximum leverage the AI can use for each trade ~~**Configuration format:**~~ -~~```json +```json "leverage": { "btc_eth_leverage": 5, // Maximum leverage for BTC and ETH "altcoin_leverage": 5 // Maximum leverage for all other coins } -```~~ +``` *Note: Leverage is now configured through the web interface* @@ -715,20 +713,20 @@ The leverage settings control the maximum leverage the AI can use for each trade **Examples:** ~~**Safe configuration (subaccount or conservative):**~~ -~~```json +```json "leverage": { "btc_eth_leverage": 5, "altcoin_leverage": 5 } -```~~ +``` ~~**Aggressive configuration (main account only):**~~ -~~```json +```json "leverage": { "btc_eth_leverage": 20, "altcoin_leverage": 15 } -```~~ +``` *Note: Leverage configuration is now done through the web interface* @@ -915,109 +913,100 @@ Should return: `{"status":"ok"}` Each decision cycle (default 3 minutes), the system executes the following intelligent process: -``` -┌──────────────────────────────────────────────────────────┐ -│ 1. 📊 Analyze Historical Performance (last 20 cycles) │ -├──────────────────────────────────────────────────────────┤ -│ ✓ Calculate overall win rate, avg profit, P/L ratio │ -│ ✓ Per-coin statistics (win rate, avg P/L in USDT) │ -│ ✓ Identify best/worst performing coins │ -│ ✓ List last 5 trade details with accurate PnL │ -│ ✓ Calculate Sharpe ratio for risk-adjusted performance │ -│ 📌 NEW (v2.0.2): Accurate USDT PnL with leverage │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 2. 💰 Get Account Status │ -├──────────────────────────────────────────────────────────┤ -│ • Total equity & available balance │ -│ • Number of open positions & unrealized P/L │ -│ • Margin usage rate (AI manages up to 90%) │ -│ • Daily P/L tracking & drawdown monitoring │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 3. 🔍 Analyze Existing Positions (if any) │ -├──────────────────────────────────────────────────────────┤ -│ • For each position, fetch latest market data │ -│ • Calculate real-time technical indicators: │ -│ - 3min K-line: RSI(7), MACD, EMA20 │ -│ - 4hour K-line: RSI(14), EMA20/50, ATR │ -│ • Track position holding duration (e.g., "2h 15min") │ -│ 📌 NEW (v2.0.2): Shows how long each position held │ -│ • Display: Entry price, current price, P/L%, duration │ -│ • AI evaluates: Should hold or close? │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 4. 🎯 Evaluate New Opportunities (candidate coins) │ -├──────────────────────────────────────────────────────────┤ -│ • Fetch coin pool (2 modes): │ -│ 🌟 Default Mode: BTC, ETH, SOL, BNB, XRP, etc. │ -│ ⚙️ Advanced Mode: AI500 (top 20) + OI Top (top 20) │ -│ • Merge & deduplicate candidate coins │ -│ • Filter: Remove low liquidity (<15M USD OI value) │ -│ • Batch fetch market data + technical indicators │ -│ • Calculate volatility, trend strength, volume surge │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 5. 🧠 AI Comprehensive Decision (DeepSeek/Qwen) │ -├──────────────────────────────────────────────────────────┤ -│ • Review historical feedback: │ -│ - Recent win rate & profit factor │ -│ - Best/worst coins performance │ -│ - Avoid repeating mistakes │ -│ • Analyze all raw sequence data: │ -│ - 3min price序列, 4hour K-line序列 │ -│ - Complete indicator sequences (not just latest) │ -│ 📌 NEW (v2.0.2): AI has full freedom to analyze │ -│ • Chain of Thought (CoT) reasoning process │ -│ • Output structured decisions: │ -│ - Action: close_long/close_short/open_long/open_short│ -│ - Coin symbol, quantity, leverage │ -│ - Stop-loss & take-profit levels (≥1:2 ratio) │ -│ • Decision: Wait/Hold/Close/Open │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 6. ⚡ Execute Trades │ -├──────────────────────────────────────────────────────────┤ -│ • Priority order: Close existing → Then open new │ -│ • Risk checks before execution: │ -│ - Position size limits (1.5x for altcoins, 10x BTC) │ -│ - No duplicate positions (same coin + direction) │ -│ - Margin usage within 90% limit │ -│ • Auto-fetch & apply Binance LOT_SIZE precision │ -│ • Execute orders via Binance Futures API │ -│ • After closing: Auto-cancel all pending orders │ -│ • Record actual execution price & order ID │ -│ 📌 Track position open time for duration calculation │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 7. 📝 Record Complete Logs & Update Performance │ -├──────────────────────────────────────────────────────────┤ -│ • Save decision log to decision_logs/{trader_id}/ │ -│ • Log includes: │ -│ - Complete Chain of Thought (CoT) │ -│ - Input prompt with all market data │ -│ - Structured decision JSON │ -│ - Account snapshot (balance, positions, margin) │ -│ - Execution results (success/failure, prices) │ -│ • Update performance database: │ -│ - Match open/close pairs by symbol_side key │ -│ 📌 NEW: Prevents long/short conflicts │ -│ - Calculate accurate USDT PnL: │ -│ PnL = Position Value × Price Δ% × Leverage │ -│ 📌 NEW: Considers quantity + leverage │ -│ - Store: quantity, leverage, open time, close time │ -│ - Update win rate, profit factor, Sharpe ratio │ -│ • Performance data feeds back into next cycle │ -└──────────────────────────────────────────────────────────┘ - ↓ - (Repeat every 3-5 min) -``` +### Step 1: 📊 Analyze Historical Performance (last 20 cycles) +- ✓ Calculate overall win rate, avg profit, P/L ratio +- ✓ Per-coin statistics (win rate, avg P/L in USDT) +- ✓ Identify best/worst performing coins +- ✓ List last 5 trade details with accurate PnL +- ✓ Calculate Sharpe ratio for risk-adjusted performance +- 📌 **NEW (v2.0.2)**: Accurate USDT PnL with leverage + +**↓** + +### Step 2: 💰 Get Account Status +- Total equity & available balance +- Number of open positions & unrealized P/L +- Margin usage rate (AI manages up to 90%) +- Daily P/L tracking & drawdown monitoring + +**↓** + +### Step 3: 🔍 Analyze Existing Positions (if any) +- For each position, fetch latest market data +- Calculate real-time technical indicators: + - 3min K-line: RSI(7), MACD, EMA20 + - 4hour K-line: RSI(14), EMA20/50, ATR +- Track position holding duration (e.g., "2h 15min") +- 📌 **NEW (v2.0.2)**: Shows how long each position held +- Display: Entry price, current price, P/L%, duration +- AI evaluates: Should hold or close? + +**↓** + +### Step 4: 🎯 Evaluate New Opportunities (candidate coins) +- Fetch coin pool (2 modes): + - 🌟 **Default Mode**: BTC, ETH, SOL, BNB, XRP, etc. + - ⚙️ **Advanced Mode**: AI500 (top 20) + OI Top (top 20) +- Merge & deduplicate candidate coins +- Filter: Remove low liquidity (<15M USD OI value) +- Batch fetch market data + technical indicators +- Calculate volatility, trend strength, volume surge + +**↓** + +### Step 5: 🧠 AI Comprehensive Decision (DeepSeek/Qwen) +- Review historical feedback: + - Recent win rate & profit factor + - Best/worst coins performance + - Avoid repeating mistakes +- Analyze all raw sequence data: + - 3min price sequences, 4hour K-line sequences + - Complete indicator sequences (not just latest) + - 📌 **NEW (v2.0.2)**: AI has full freedom to analyze +- Chain of Thought (CoT) reasoning process +- Output structured decisions: + - Action: `close_long` / `close_short` / `open_long` / `open_short` + - Coin symbol, quantity, leverage + - Stop-loss & take-profit levels (≥1:2 ratio) +- Decision: Wait / Hold / Close / Open + +**↓** + +### Step 6: ⚡ Execute Trades +- Priority order: Close existing → Then open new +- Risk checks before execution: + - Position size limits (1.5x for altcoins, 10x BTC) + - No duplicate positions (same coin + direction) + - Margin usage within 90% limit +- Auto-fetch & apply Binance LOT_SIZE precision +- Execute orders via Binance Futures API +- After closing: Auto-cancel all pending orders +- Record actual execution price & order ID +- 📌 Track position open time for duration calculation + +**↓** + +### Step 7: 📝 Record Complete Logs & Update Performance +- Save decision log to `decision_logs/{trader_id}/` +- Log includes: + - Complete Chain of Thought (CoT) + - Input prompt with all market data + - Structured decision JSON + - Account snapshot (balance, positions, margin) + - Execution results (success/failure, prices) +- Update performance database: + - Match open/close pairs by `symbol_side` key + - 📌 **NEW**: Prevents long/short conflicts + - Calculate accurate USDT PnL: + - `PnL = Position Value × Price Δ% × Leverage` + - 📌 **NEW**: Considers quantity + leverage + - Store: quantity, leverage, open time, close time + - Update win rate, profit factor, Sharpe ratio +- Performance data feeds back into next cycle + +**↓** + +**🔄 (Repeat every 3-5 min)** ### Key Improvements in v2.0.2 @@ -1229,145 +1218,19 @@ sudo apt-get install libta-lib0-dev ## 🔄 Changelog -### v3.0.0 (2025-10-30) - Major Architecture Transformation +📖 **For detailed version history and updates, see:** -**🚀 Complete System Redesign - Web-Based Configuration Platform** +- **English:** [CHANGELOG.md](CHANGELOG.md) +- **中文:** [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md) -This is a **major breaking update** that completely transforms NOFX from a static config-based system to a modern web-based trading platform. +**Latest Release:** v3.0.0 (2025-10-30) - Major Architecture Transformation -**Revolutionary Changes:** - -**1. Database-Driven Architecture** -- ✅ **SQLite Integration**: Replaced static JSON config with SQLite database -- ✅ **Persistent Storage**: All configurations stored in database with automatic timestamps -- ✅ **Data Integrity**: Foreign key relationships and triggers for data consistency -- ✅ **Schema Design**: Separate tables for AI models, exchanges, traders, and system config - -**2. Web-Based Configuration Interface** -- ✅ **No More JSON Editing**: Complete web-based configuration management -- ✅ **AI Model Setup**: Configure DeepSeek/Qwen API keys through web interface -- ✅ **Exchange Management**: Set up Binance/Hyperliquid credentials independently -- ✅ **Dynamic Trader Creation**: Create traders by combining any AI model with any exchange -- ✅ **Real-Time Control**: Start/stop traders without system restart - -**3. Flexible Architecture** -- ✅ **Separation of Concerns**: AI models and exchanges configured independently -- ✅ **Mix & Match**: Create unlimited combinations (e.g., Qwen + Binance, DeepSeek + Hyperliquid) -- ✅ **Scalable Design**: Support for unlimited traders and configurations -- ✅ **Clean Slate**: No default traders - create only what you need - -**4. Enhanced API Layer** -- ✅ **RESTful Design**: Complete CRUD operations for all configuration entities -- ✅ **New Endpoints**: - - `GET/PUT /api/models` - AI model configuration - - `GET/PUT /api/exchanges` - Exchange configuration - - `POST/DELETE /api/traders` - Trader management - - `POST /api/traders/:id/start|stop` - Trader control -- ✅ **Updated Documentation**: All API endpoints documented - -**5. Modernized Codebase** -- ✅ **Type Safety**: Proper separation of legacy and new configuration types -- ✅ **Database Abstraction**: Clean database layer with prepared statements -- ✅ **Error Handling**: Comprehensive error handling and validation -- ✅ **Code Organization**: Better separation between database, API, and business logic - -**Migration Notes:** -- ⚠️ **Breaking Change**: Old ~~`config.json`~~ files are no longer used -- ⚠️ **Fresh Start**: All configurations must be redone through web interface -- ✅ **Easier Setup**: Web-based configuration is much more user-friendly -- ✅ **Better UX**: No more server restarts for configuration changes - -**Why This Update Matters:** -- 🎯 **User Experience**: Much easier to configure and manage -- 🔧 **Flexibility**: Create any combination of AI models and exchanges -- 📊 **Scalability**: Support for complex multi-trader setups -- 🔒 **Reliability**: Database ensures data persistence and consistency -- 🚀 **Future-Proof**: Foundation for advanced features like trader templates, backtesting, etc. - -### v2.0.2 (2025-10-29) - -**Critical Bug Fixes - Trade History & Performance Analysis:** - -This version fixes **critical calculation errors** in the historical trade record and performance analysis system that significantly affected profitability statistics. - -**1. PnL Calculation - Major Error Fixed** (logger/decision_logger.go) -- **Problem**: Previously calculated PnL as percentage only, completely ignoring position size and leverage - - Example: 100 USDT position earning 5% and 1000 USDT position earning 5% both showed `5.0` as profit - - This made performance analysis completely inaccurate -- **Solution**: Now calculates actual USDT profit amount - ``` - PnL (USDT) = Position Value × Price Change % × Leverage - Example: 1000 USDT × 5% × 20x = 1000 USDT actual profit - ``` -- **Impact**: Win rate, profit factor, and Sharpe ratio now based on accurate USDT amounts - -**2. Position Tracking - Missing Critical Data** -- **Problem**: Open position records only stored price and time, missing quantity and leverage -- **Solution**: Now stores complete trade data: - - `quantity`: Position size (in coins) - - `leverage`: Leverage multiplier (e.g., 20x) - - These are essential for accurate PnL calculations - -**3. Position Key Logic - Long/Short Conflict** -- **Problem**: Used `symbol` as position key, causing data conflicts when holding both long and short - - Example: BTCUSDT long and BTCUSDT short would overwrite each other -- **Solution**: Changed to `symbol_side` format (e.g., `BTCUSDT_long`, `BTCUSDT_short`) - - Now properly distinguishes between long and short positions - -**4. Sharpe Ratio Calculation - Code Optimization** -- **Problem**: Used custom Newton's method for square root calculation -- **Solution**: Replaced with standard library `math.Sqrt` - - More reliable, maintainable, and efficient - -**Why This Update Matters:** -- ✅ Historical trade statistics now show **real USDT profit/loss** instead of meaningless percentages -- ✅ Performance comparison between different leverage trades is now accurate -- ✅ AI self-learning mechanism receives correct historical feedback -- ✅ Profit factor and Sharpe ratio calculations are now meaningful -- ✅ Multi-position tracking (long + short simultaneously) works correctly - -**Recommendation**: If you were running the system before this update, your historical statistics were inaccurate. After updating to v2.0.2, new trades will be calculated correctly. - -### v2.0.2 (2025-10-29) - -**Bug Fixes:** -- ✅ Fixed Aster exchange precision error (code -1111: "Precision is over the maximum defined for this asset") -- ✅ Improved price and quantity formatting to match exchange precision requirements -- ✅ Added detailed precision processing logs for debugging -- ✅ Enhanced all order functions (OpenLong, OpenShort, CloseLong, CloseShort, SetStopLoss, SetTakeProfit) with proper precision handling - -**Technical Details:** -- Added `formatFloatWithPrecision` function to convert float64 to strings with correct precision -- Price and quantity parameters are now formatted according to exchange's `pricePrecision` and `quantityPrecision` specifications -- Trailing zeros are removed from formatted values to optimize API requests - -### v2.0.1 (2025-10-29) - -**Bug Fixes:** -- ✅ Fixed ComparisonChart data processing logic - switched from cycle_number to timestamp grouping -- ✅ Resolved chart freezing issue when backend restarts and cycle_number resets -- ✅ Improved chart data display - now shows all historical data points chronologically -- ✅ Enhanced debugging logs for better troubleshooting - -### v2.0.0 (2025-10-28) - -**Major Updates:** -- ✅ AI self-learning mechanism (historical feedback, performance analysis) -- ✅ Multi-trader competition mode (Qwen vs DeepSeek) -- ✅ Binance-style UI (complete Binance interface imitation) -- ✅ Performance comparison charts (real-time ROI comparison) -- ✅ Risk control optimization (per-coin position limit adjustment) - -**Bug Fixes:** -- Fixed hardcoded initial balance issue -- Fixed multi-trader data sync issue -- Optimized chart data alignment (using cycle_number) - -### v1.0.0 (2025-10-27) -- Initial release -- Basic AI trading functionality -- Decision logging system -- Simple Web interface +**Recent Highlights:** +- 🚀 Complete system redesign with web-based configuration +- 🗄️ Database-driven architecture (SQLite) +- 🎨 No more JSON editing - all configuration through web interface +- 🔧 Mix & match AI models with any exchange +- 📊 Enhanced API layer with comprehensive endpoints --- @@ -1379,10 +1242,14 @@ MIT License - See [LICENSE](LICENSE) file for details ## 🤝 Contributing -Issues and Pull Requests are welcome! +We welcome contributions from the community! See our comprehensive guides: -### Development Guide +- **📖 [Contributing Guide](CONTRIBUTING.md)** - Complete development workflow, code standards, and PR process +- **🤝 [Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines and standards +- **💰 [Bounty Program](docs/community/bounty-guide.md)** - Earn rewards for contributions +- **🔒 [Security Policy](SECURITY.md)** - Report vulnerabilities responsibly +**Quick Start:** 1. Fork the project 2. Create feature branch (`git checkout -b feature/AmazingFeature`) 3. Commit changes (`git commit -m 'Add some AmazingFeature'`) diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..1052d013 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,469 @@ +# Security Policy / 安全政策 + +**Languages:** [English](#english) | [中文](#中文) + +--- + +# English + +## 🛡️ Security Overview + +NOFX is an AI-powered trading system that handles real funds and API credentials. We take security seriously and appreciate the security community's efforts to responsibly disclose vulnerabilities. + +**Critical Areas:** +- 🔑 API key storage and handling +- 💰 Trading execution and fund management +- 🔐 Authentication and authorization +- 🗄️ Database security (SQLite) +- 🌐 Web interface and API endpoints + +--- + +## 📋 Supported Versions + +We provide security updates for the following versions: + +| Version | Supported | Notes | +| ------- | ------------------ | -------------------- | +| 3.x | ✅ Fully supported | Current stable release | +| 2.x | ⚠️ Limited support | Security fixes only | +| < 2.0 | ❌ Not supported | Please upgrade | + +**Recommendation:** Always use the latest stable release (v3.x) for best security. + +--- + +## 🔒 Reporting a Vulnerability + +### ⚠️ Please DO NOT Publicly Disclose + +If you discover a security vulnerability in NOFX, please **DO NOT**: +- ❌ Open a public GitHub Issue +- ❌ Discuss it on social media (Twitter, Reddit, etc.) +- ❌ Share it in Telegram/Discord groups +- ❌ Post it on security forums before we've had time to fix it + +Public disclosure before a fix is available puts all users at risk. + +### ✅ Responsible Disclosure Process + +**Step 1: Report Privately** + +Contact core team directly: +- **Tinkle:** [@Web3Tinkle on Twitter](https://x.com/Web3Tinkle) (DM) + +**Alternative:** Encrypted communication via [Keybase](https://keybase.io/) (if available) + +**Step 2: Include These Details** + +```markdown +Subject: [SECURITY] Brief description of vulnerability + +## Vulnerability Description +Clear explanation of the security issue + +## Affected Components +- Which parts of the system are affected? +- Which versions are vulnerable? + +## Reproduction Steps +1. Step-by-step instructions +2. Sample code or commands (if applicable) +3. Expected vs actual behavior + +## Potential Impact +- Can funds be stolen? +- Can API keys be leaked? +- Can accounts be compromised? +- Rate the severity: Critical / High / Medium / Low + +## Suggested Fix (Optional) +If you have ideas for fixing it, please share! + +## Your Information +- Name (or pseudonym) +- Contact info for follow-up +- If you want public credit (yes/no) +``` + +**Step 3: Wait for Our Response** + +We will: +- ✅ Acknowledge receipt within **24 hours** +- ✅ Provide initial assessment within **72 hours** +- ✅ Keep you updated on fix progress +- ✅ Notify you before public disclosure + +--- + +## ⏱️ Response Timeline + +| Stage | Timeline | Action | +|-------|----------|--------| +| **Acknowledgment** | 24 hours | Confirm we received your report | +| **Initial Assessment** | 72 hours | Verify vulnerability, rate severity | +| **Fix Development** | 7-30 days | Depends on complexity and severity | +| **Testing** | 3-7 days | Verify fix doesn't break functionality | +| **Public Disclosure** | After fix deployed | Publish security advisory | + +**Critical vulnerabilities** (fund theft, credential leaks) are prioritized and may be fixed within 48 hours. + +--- + +## 💰 Security Bounty Program (Optional) + +We offer rewards for valid security vulnerabilities: + +| Severity | Criteria | Reward | +|----------|----------|--------| +| **🔴 Critical** | Fund theft, API key extraction, RCE | **$500-1000 USD** | +| **🟠 High** | Authentication bypass, unauthorized trading | **$200-500 USD** | +| **🟡 Medium** | Information disclosure, XSS, CSRF | **$100-200 USD** | +| **🟢 Low** | Security improvements, minor issues | **$50-100 USD or Recognition** | + +**Note:** Bounty amounts are at maintainers' discretion based on: +- Severity and impact +- Quality of report +- Ease of exploitation +- Number of affected users + +**Out of Scope (No Bounty):** +- Issues in third-party libraries (report to them directly) +- Social engineering attacks +- DoS/DDoS attacks +- Issues requiring physical access +- Previously known/reported vulnerabilities + +--- + +## 🔐 Security Best Practices (For Users) + +To keep your NOFX deployment secure: + +### 1. API Key Management +```bash +# ✅ DO: Use environment variables +export BINANCE_API_KEY="your_key" +export BINANCE_SECRET_KEY="your_secret" + +# ❌ DON'T: Hardcode in source files +api_key = "abc123..." # NEVER DO THIS +``` + +### 2. Database Security +```bash +# ✅ Set proper permissions +chmod 600 nofx.db +chmod 600 config.json + +# ❌ DON'T: Leave files world-readable +chmod 777 nofx.db # NEVER DO THIS +``` + +### 3. Network Security +```bash +# ✅ Use firewall to restrict API access +# Only allow localhost to access API server +iptables -A INPUT -p tcp --dport 8080 -s 127.0.0.1 -j ACCEPT +iptables -A INPUT -p tcp --dport 8080 -j DROP + +# ❌ DON'T: Expose API to public internet without authentication +``` + +### 4. Use Subaccounts +- Create dedicated Binance subaccount for trading +- Limit maximum balance +- Restrict withdrawal permissions +- Use IP whitelist + +### 5. Test on Testnet First +- Hyperliquid: Use testnet mode +- Binance: Use testnet API (https://testnet.binancefuture.com) +- Never test with real funds initially + +### 6. Regular Updates +```bash +# Check for updates regularly +git pull origin main +go build -o nofx + +# Subscribe to security advisories +# Watch GitHub releases: https://github.com/tinkle-community/nofx/releases +``` + +--- + +## 🚨 Security Advisories + +Past security advisories will be published here: + +### 2025-XX-XX: [Title] +- **Severity:** [Critical/High/Medium/Low] +- **Affected Versions:** [x.x.x - x.x.x] +- **Fixed in:** [x.x.x] +- **Description:** [Brief description] +- **Mitigation:** [How to protect yourself] + +*No security advisories have been published yet.* + +--- + +## 🙏 Security Researchers Hall of Fame + +We thank the following security researchers for responsibly disclosing vulnerabilities: + +*No reports have been submitted yet. Be the first!* + +--- + +## 📚 Additional Resources + +**Security Documentation:** +- [OWASP Top 10](https://owasp.org/www-project-top-ten/) +- [CWE Top 25](https://cwe.mitre.org/top25/) +- [Binance API Security Best Practices](https://www.binance.com/en/support/faq/360002502072) + +**Audit Reports:** +- No third-party audits completed yet +- Self-audit checklist: [TODO: Add link] + +--- + +## 📞 Contact + +**For security issues ONLY:** +- 🐦 **Twitter DM:** [@Web3Tinkle](https://x.com/Web3Tinkle) + +**For general questions:** +- See [CONTRIBUTING.md](CONTRIBUTING.md) +- Join [Telegram Community](https://t.me/nofx_dev_community) + +--- + +**Thank you for helping keep NOFX secure!** 🔒 + +--- + +# 中文 + +## 🛡️ 安全概述 + +NOFX 是一个处理真实资金和 API 凭证的 AI 交易系统。我们非常重视安全，并感谢安全社区负责任地披露漏洞的努力。 + +**关键领域：** +- 🔑 API 密钥存储和处理 +- 💰 交易执行和资金管理 +- 🔐 身份验证和授权 +- 🗄️ 数据库安全（SQLite） +- 🌐 Web 界面和 API 端点 + +--- + +## 📋 支持的版本 + +我们为以下版本提供安全更新： + +| 版本 | 支持状态 | 说明 | +| ------- | ------------------ | -------------------- | +| 3.x | ✅ 完全支持 | 当前稳定版本 | +| 2.x | ⚠️ 有限支持 | 仅安全修复 | +| < 2.0 | ❌ 不支持 | 请升级 | + +**建议：** 始终使用最新的稳定版本（v3.x）以获得最佳安全性。 + +--- + +## 🔒 报告漏洞 + +### ⚠️ 请勿公开披露 + +如果您在 NOFX 中发现安全漏洞，请**不要**： +- ❌ 公开创建 GitHub Issue +- ❌ 在社交媒体上讨论（Twitter、Reddit 等） +- ❌ 在 Telegram/Discord 群组中分享 +- ❌ 在我们有时间修复之前发布到安全论坛 + +在修复可用之前公开披露会使所有用户面临风险。 + +### ✅ 负责任的披露流程 + +**步骤 1：私下报告** + +直接联系核心团队： +- **Tinkle:** [@Web3Tinkle on Twitter](https://x.com/Web3Tinkle)（私信） + +**替代方案：** 通过 [Keybase](https://keybase.io/) 加密通信（如果可用） + +**步骤 2：包含这些详细信息** + +```markdown +主题：[SECURITY] 漏洞简要描述 + +## 漏洞描述 +清楚解释安全问题 + +## 受影响的组件 +- 系统的哪些部分受到影响？ +- 哪些版本存在漏洞？ + +## 复现步骤 +1. 逐步说明 +2. 示例代码或命令（如果适用） +3. 预期行为 vs 实际行为 + +## 潜在影响 +- 资金是否可能被盗？ +- API 密钥是否可能泄露？ +- 账户是否可能被入侵？ +- 严重程度评级：严重 / 高 / 中 / 低 + +## 建议修复（可选） +如果您有修复的想法，请分享！ + +## 您的信息 +- 姓名（或化名） +- 后续联系信息 +- 是否希望公开致谢（是/否） +``` + +**步骤 3：等待我们的回复** + +我们将： +- ✅ 在 **24 小时**内确认收到 +- ✅ 在 **72 小时**内提供初步评估 +- ✅ 告知您修复进展 +- ✅ 在公开披露前通知您 + +--- + +## ⏱️ 响应时间表 + +| 阶段 | 时间线 | 行动 | +|-------|----------|--------| +| **确认** | 24 小时 | 确认我们收到了您的报告 | +| **初步评估** | 72 小时 | 验证漏洞，评估严重程度 | +| **修复开发** | 7-30 天 | 取决于复杂性和严重程度 | +| **测试** | 3-7 天 | 验证修复不会破坏功能 | +| **公开披露** | 修复部署后 | 发布安全公告 | + +**严重漏洞**（资金盗窃、凭证泄露）会优先处理，可能在 48 小时内修复。 + +--- + +## 💰 安全奖励计划（可选） + +我们为有效的安全漏洞提供奖励： + +| 严重程度 | 标准 | 奖励 | +|----------|----------|--------| +| **🔴 严重** | 资金盗窃、API 密钥提取、RCE | **$500-1000 USD** | +| **🟠 高** | 认证绕过、未授权交易 | **$200-500 USD** | +| **🟡 中** | 信息泄露、XSS、CSRF | **$100-200 USD** | +| **🟢 低** | 安全改进、小问题 | **$50-100 USD 或致谢** | + +**注意：** 奖励金额由维护者根据以下因素酌情决定： +- 严重性和影响 +- 报告质量 +- 利用难易度 +- 受影响用户数量 + +**不在范围内（无奖励）：** +- 第三方库的问题（直接向他们报告） +- 社会工程攻击 +- DoS/DDoS 攻击 +- 需要物理访问的问题 +- 已知/已报告的漏洞 + +--- + +## 🔐 安全最佳实践（用户指南） + +保护您的 NOFX 部署安全： + +### 1. API 密钥管理 +```bash +# ✅ 正确：使用环境变量 +export BINANCE_API_KEY="your_key" +export BINANCE_SECRET_KEY="your_secret" + +# ❌ 错误：在源文件中硬编码 +api_key = "abc123..." # 永远不要这样做 +``` + +### 2. 数据库安全 +```bash +# ✅ 设置适当的权限 +chmod 600 nofx.db +chmod 600 config.json + +# ❌ 不要：让文件全局可读 +chmod 777 nofx.db # 永远不要这样做 +``` + +### 3. 网络安全 +```bash +# ✅ 使用防火墙限制 API 访问 +# 仅允许本地访问 API 服务器 +iptables -A INPUT -p tcp --dport 8080 -s 127.0.0.1 -j ACCEPT +iptables -A INPUT -p tcp --dport 8080 -j DROP + +# ❌ 不要：在没有身份验证的情况下将 API 暴露到公共互联网 +``` + +### 4. 使用子账户 +- 为交易创建专用的 Binance 子账户 +- 限制最大余额 +- 限制提现权限 +- 使用 IP 白名单 + +### 5. 先在测试网上测试 +- Hyperliquid：使用测试网模式 +- Binance：使用测试网 API (https://testnet.binancefuture.com) +- 最初永远不要用真实资金测试 + +### 6. 定期更新 +```bash +# 定期检查更新 +git pull origin main +go build -o nofx + +# 订阅安全公告 +# 关注 GitHub 发布：https://github.com/tinkle-community/nofx/releases +``` + +--- + +## 🚨 安全公告 + +过去的安全公告将在此发布： + +### 2025-XX-XX: [标题] +- **严重程度：** [严重/高/中/低] +- **受影响版本：** [x.x.x - x.x.x] +- **已修复版本：** [x.x.x] +- **描述：** [简要描述] +- **缓解措施：** [如何保护自己] + +*尚未发布任何安全公告。* + +--- + +## 🙏 安全研究员名人堂 + +我们感谢以下安全研究员负责任地披露漏洞： + +*尚未收到任何报告。成为第一个！* + +--- + +## 📞 联系方式 + +**仅限安全问题：** +- 🐦 **Twitter 私信：** [@Web3Tinkle](https://x.com/Web3Tinkle) + +**一般问题：** +- 加入 [Telegram 社区](https://t.me/nofx_dev_community) + +--- + +**感谢您帮助保持 NOFX 的安全！** 🔒 diff --git a/docs/MIGRATION_GUIDE.md b/docs/MIGRATION_GUIDE.md new file mode 100644 index 00000000..1f4dad42 --- /dev/null +++ b/docs/MIGRATION_GUIDE.md @@ -0,0 +1,242 @@ +# 📦 Documentation Migration Guide + +## What Changed? + +NOFX documentation has been reorganized into a structured `docs/` directory for better organization and navigation. + +## 🗺️ File Locations (Old → New) + +### Deployment Guides +- `DOCKER_DEPLOY.en.md` → `docs/getting-started/docker-deploy.en.md` +- `DOCKER_DEPLOY.md` → `docs/getting-started/docker-deploy.zh-CN.md` +- `PM2_DEPLOYMENT.md` → `docs/getting-started/pm2-deploy.md` +- `CUSTOM_API.md` → `docs/getting-started/custom-api.md` + +### Community Docs +- `HOW_TO_POST_BOUNTY.md` → `docs/community/bounty-guide.md` +- `INTEGRATION_BOUNTY_HYPERLIQUID.md` → `docs/community/bounty-hyperliquid.md` +- `INTEGRATION_BOUNTY_ASTER.md` → `docs/community/bounty-aster.md` + +### Internationalization +- `README.zh-CN.md` → `docs/i18n/zh-CN/README.md` +- `README.ru.md` → `docs/i18n/ru/README.md` +- `README.uk.md` → `docs/i18n/uk/README.md` +- `常见问题.md` → `docs/guides/faq.zh-CN.md` + +### Root Directory (Unchanged) +These stay in the root for GitHub recognition: +- `README.md` ✅ (stays in root) +- `LICENSE` ✅ (stays in root) +- `CONTRIBUTING.md` ✅ (stays in root) +- `CODE_OF_CONDUCT.md` ✅ (stays in root) +- `SECURITY.md` ✅ (stays in root) + +## 🎯 Why This Change? + +### Before (❌ Problems) +``` +nofx/ +├── README.md +├── README.zh-CN.md +├── README.ru.md +├── README.uk.md +├── DOCKER_DEPLOY.md +├── DOCKER_DEPLOY.en.md +├── PM2_DEPLOYMENT.md +├── CUSTOM_API.md +├── HOW_TO_POST_BOUNTY.md +├── INTEGRATION_BOUNTY_HYPERLIQUID.md +├── INTEGRATION_BOUNTY_ASTER.md +├── 常见问题.md +└── ... (15+ markdown files in root!) +``` + +**Issues:** +- 😵 Too cluttered (15+ files in root) +- 🔍 Hard to find specific docs +- 🌍 Mixed languages +- 📚 No clear organization + +### After (✅ Benefits) +``` +nofx/ +├── README.md # Project homepage +├── LICENSE # Legal (GitHub needs it here) +├── CONTRIBUTING.md # GitHub auto-links +├── CODE_OF_CONDUCT.md # GitHub auto-links +├── SECURITY.md # GitHub auto-links +│ +└── docs/ # 📚 Documentation hub + ├── README.md # Documentation home + ├── getting-started/ # 🚀 Setup guides + ├── guides/ # 📘 User guides + ├── community/ # 👥 Contribution docs + ├── i18n/ # 🌍 Translations + └── architecture/ # 🏗️ Technical docs +``` + +**Benefits:** +- ✅ Clean root directory +- ✅ Logical categorization +- ✅ Easy navigation +- ✅ Scalable structure +- ✅ Professional appearance + +## 📚 New Documentation Structure + +### Root Level +Files GitHub needs to see: +- `README.md` - Main project page +- `LICENSE` - Open source license +- `CONTRIBUTING.md` - Contributor guide +- `CODE_OF_CONDUCT.md` - Community standards +- `SECURITY.md` - Security policy + +### docs/ Level + +**Navigation:** +- `docs/README.md` - **Start here!** Main documentation hub + +**Categories:** + +1. **`getting-started/`** - Deployment and setup + - Docker deployment (EN/中文) + - PM2 deployment + - Custom API configuration + +2. **`guides/`** - Usage guides and tutorials + - FAQ (中文) + - Troubleshooting (planned) + - Configuration examples (planned) + +3. **`community/`** - Contribution and bounties + - Bounty guide + - Active bounty tasks + - Contributor recognition + +4. **`i18n/`** - International translations + - `zh-CN/` - Simplified Chinese + - `ru/` - Russian + - `uk/` - Ukrainian + +5. **`architecture/`** - Technical documentation + - System design (planned) + - API reference (planned) + - Database schema (planned) + +## 🔗 Updating Your Links + +### If you bookmarked old links: + +| Old Link | New Link | +|----------|----------| +| `DOCKER_DEPLOY.en.md` | `docs/getting-started/docker-deploy.en.md` | +| `README.zh-CN.md` | `docs/i18n/zh-CN/README.md` | +| `HOW_TO_POST_BOUNTY.md` | `docs/community/bounty-guide.md` | + +### If you linked in your own docs: + +**Update relative links:** +```markdown + +[Docker Deployment](DOCKER_DEPLOY.en.md) + + +[Docker Deployment](docs/getting-started/docker-deploy.en.md) +``` + +**GitHub URLs automatically redirect!** +- Old: `github.com/tinkle-community/nofx/blob/main/DOCKER_DEPLOY.en.md` +- Will redirect to: `github.com/.../docs/getting-started/docker-deploy.en.md` + +## 🛠️ For Contributors + +### Cloning/Pulling Latest + +```bash +# Pull latest changes +git pull origin dev + +# Your old bookmarks still work! +# Git tracked the file moves (git mv) +``` + +### Finding Documentation + +**Use the navigation hub:** +1. Start at [docs/README.md](README.md) +2. Browse by category +3. Use the quick navigation section + +**Or search:** +```bash +# Find all markdown docs +find docs -name "*.md" + +# Search content +grep -r "keyword" docs/ +``` + +### Adding New Documentation + +**Follow the structure:** + +```bash +# Getting started guides +docs/getting-started/your-guide.md + +# User guides +docs/guides/your-tutorial.md + +# Community docs +docs/community/your-doc.md + +# Translations +docs/i18n/ja/README.md # Japanese example +``` + +**Update navigation:** +- Add link in relevant category README +- Add to `docs/README.md` main hub + +## 📝 Commit Messages + +This reorganization was committed as: + +``` +docs: reorganize documentation into structured docs/ directory + +- Move deployment guides to docs/getting-started/ +- Move community docs to docs/community/ +- Move translations to docs/i18n/ +- Create navigation hub at docs/README.md +- Update all internal links in README.md +- Add GitHub issue/PR templates + +BREAKING CHANGE: Direct links to moved files will need updating +(though GitHub redirects should work) + +Closes #XXX +``` + +## 🆘 Need Help? + +**Can't find a document?** +1. Check [docs/README.md](README.md) navigation hub +2. Search GitHub repo +3. Ask in [Telegram](https://t.me/nofx_dev_community) + +**Link broken?** +- Report in [GitHub Issues](https://github.com/tinkle-community/nofx/issues) +- We'll fix it ASAP! + +**Want to contribute docs?** +- See [Contributing Guide](../CONTRIBUTING.md) +- Check [docs/community/](community/README.md) + +--- + +**Migration Date:** 2025-11-01 +**Maintainers:** Tinkle Community + +[← Back to Documentation Home](README.md) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..72ea76b2 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,192 @@ +# 📚 NOFX Documentation Center / 文档中心 + +Welcome to the NOFX documentation! This page helps you find the right documentation quickly. + +欢迎来到 NOFX 文档中心！本页面帮助您快速找到所需文档。 + +--- + +## 🚀 Getting Started / 快速开始 + +**New to NOFX? Start here!** + +| Document | Description | 描述 | +|----------|-------------|------| +| [Main README](../README.md) | Project overview, features, quick start | 项目概述、功能、快速入门 | +| [Getting Started Index (EN)](getting-started/README.md) | All deployment options | 所有部署选项 | +| [Getting Started Index (中文)](getting-started/README.zh-CN.md) | 所有部署选项 | All deployment options | +| [Docker Deployment (EN)](getting-started/docker-deploy.en.md) | Deploy with Docker (recommended) | Docker 部署（推荐） | +| [Docker Deployment (中文)](getting-started/docker-deploy.zh-CN.md) | Docker 部署指南（中文） | Docker deployment guide | +| [PM2 Deployment (EN)](getting-started/pm2-deploy.en.md) | Deploy with PM2 process manager | PM2 进程管理器部署 | +| [PM2 Deployment (中文)](getting-started/pm2-deploy.md) | PM2 部署指南（中文） | PM2 deployment guide | +| [Custom API (EN)](getting-started/custom-api.en.md) | Connect custom AI API providers | 连接自定义 AI API | +| [Custom API (中文)](getting-started/custom-api.md) | 连接自定义 AI API 提供商 | Custom AI provider guide | + +**Quick Links:** +- 📖 See all options → [Getting Started](getting-started/README.md) / [快速开始](getting-started/README.zh-CN.md) +- 🐳 Want easiest setup? → [Docker (EN)](getting-started/docker-deploy.en.md) / [Docker (中文)](getting-started/docker-deploy.zh-CN.md) +- 🔧 Advanced user? → [PM2 (EN)](getting-started/pm2-deploy.en.md) / [PM2 (中文)](getting-started/pm2-deploy.md) +- 🤖 Custom AI model? → [Custom API (EN)](getting-started/custom-api.en.md) / [自定义 API](getting-started/custom-api.md) + +--- + +## 📘 User Guides / 使用指南 + +**Learn how to use NOFX effectively** + +| Document | Description | 描述 | +|----------|-------------|------| +| [User Guides Index (EN)](guides/README.md) | All usage guides and tips | 所有使用指南和技巧 | +| [User Guides Index (中文)](guides/README.zh-CN.md) | 所有使用指南和技巧 | All usage guides and tips | +| [FAQ (English)](guides/faq.en.md) | Frequently asked questions | 常见问题解答 | +| [FAQ (中文)](guides/faq.zh-CN.md) | 常见问题解答 | Frequently asked questions | +| Troubleshooting *(coming soon)* | Common issues and solutions | 故障排查 | +| Configuration Guide *(coming soon)* | Advanced configuration options | 高级配置选项 | +| Trading Strategies *(coming soon)* | AI trading strategy examples | AI 交易策略示例 | + +--- + +## 👥 Community & Contributing / 社区与贡献 + +**Join the community and contribute!** + +| Document | Description | 描述 | +|----------|-------------|------| +| [Code of Conduct](../CODE_OF_CONDUCT.md) | Community guidelines | 社区行为准则 | +| [Security Policy](../SECURITY.md) | Report security vulnerabilities | 报告安全漏洞 | +| [Bounty Guide](community/bounty-guide.md) | How to post bounty tasks | 如何发布悬赏任务 | +| [Hyperliquid Bounty](community/bounty-hyperliquid.md) | Hyperliquid integration bounty | Hyperliquid 集成悬赏 | +| [Aster Bounty](community/bounty-aster.md) | Aster DEX integration bounty | Aster DEX 集成悬赏 | + +**Get Involved:** +- 💬 [Telegram Community](https://t.me/nofx_dev_community) +- 🐦 [Twitter @nofx_ai](https://x.com/nofx_ai) +- 🐛 [Report Issues](https://github.com/tinkle-community/nofx/issues) + +--- + +## 🌍 International / 国际化文档 + +**Documentation in other languages** + +| Language | Main README | Status | +|----------|-------------|--------| +| 🇨🇳 Chinese (中文) | [README.md](i18n/zh-CN/README.md) | ✅ Complete | +| 🇷🇺 Russian (Русский) | [README.md](i18n/ru/README.md) | ✅ Complete | +| 🇺🇦 Ukrainian (Українська) | [README.md](i18n/uk/README.md) | ✅ Complete | +| 🇬🇧 English | [README.md](../README.md) | ✅ Complete | + +--- + +## 🏗️ Architecture & Development / 架构与开发 + +**For developers who want to understand the internals** + +| Document | Description | 描述 | +|----------|-------------|------| +| [Architecture Overview (EN)](architecture/README.md) | System architecture, modules, and design | 系统架构、模块和设计 | +| [Architecture Overview (中文)](architecture/README.zh-CN.md) | 系统架构、模块和设计 | System architecture overview | +| API Reference *(coming soon)* | HTTP API documentation | HTTP API 文档 | +| Database Schema *(coming soon)* | SQLite database structure | SQLite 数据库结构 | +| Testing Guide *(coming soon)* | How to write tests | 如何编写测试 | + +--- + +## 🗺️ Roadmap / 路线图 + +**NOFX's strategic development plan and market expansion** + +| Document | Description | 描述 | +|----------|-------------|------| +| [Roadmap (EN)](roadmap/README.md) | Short-term and long-term roadmap, feature timeline | 短期和长期路线图、功能时间表 | +| [Roadmap (中文)](roadmap/README.zh-CN.md) | 短期和长期路线图、功能时间表 | Strategic development plan | + +**Roadmap Highlights:** +- 📈 **Short-term (Q2-Q3 2025)**: Advanced risk management, multi-AI ensemble, new exchange integrations +- 🚀 **Long-term (2026)**: Universal market expansion (stocks, futures, options, forex), reinforcement learning, enterprise features + +--- + +## 📄 Legal & Policies / 法律与政策 + +| Document | Description | 描述 | +|----------|-------------|------| +| [License (MIT)](../LICENSE) | Open source license | 开源许可证 | +| [Changelog (EN)](../CHANGELOG.md) | Version history and updates | 版本历史和更新 | +| [Changelog (中文)](../CHANGELOG.zh-CN.md) | 版本历史和更新 | Version history and updates | +| [Security Policy](../SECURITY.md) | Vulnerability disclosure | 漏洞披露政策 | +| [Code of Conduct](../CODE_OF_CONDUCT.md) | Community standards | 社区标准 | + +--- + +## 🔍 Quick Navigation / 快速导航 + +**Find what you need fast:** + +### I want to... +- 🚀 **Get started quickly** → [Getting Started](getting-started/README.md) / [快速开始](getting-started/README.zh-CN.md) +- 🐛 **Report a bug** → [GitHub Issues](https://github.com/tinkle-community/nofx/issues/new) +- 💡 **Suggest a feature** → [Feature Request](https://github.com/tinkle-community/nofx/issues/new?template=feature_request.md) +- 🔒 **Report security issue** → [Security Policy](../SECURITY.md) +- 💰 **Claim a bounty** → [Bounty Guide](community/bounty-guide.md) +- 🤝 **Contribute code** → [Contributing Guide](../CONTRIBUTING.md) +- 💬 **Ask questions** → [Telegram Community](https://t.me/nofx_dev_community) + +### I'm looking for... +- 🏗️ **System architecture** → [Architecture (EN)](architecture/README.md) / [架构文档](architecture/README.zh-CN.md) +- 🗺️ **Product roadmap** → [Roadmap (EN)](roadmap/README.md) / [路线图](roadmap/README.zh-CN.md) +- 📊 **API documentation** → Coming soon +- 🧪 **Testing guide** → Coming soon +- 🔧 **Configuration examples** → [Custom API (EN)](getting-started/custom-api.en.md) / [自定义 API](getting-started/custom-api.md) +- 🌐 **Multi-language docs** → [International section](#-international--国际化文档) + +--- + +## 📚 Documentation Status + +| Category | Status | Last Updated | +|----------|--------|--------------| +| Getting Started | ✅ Complete | 2025-11-01 | +| User Guides | ✅ Complete | 2025-11-01 | +| Community | ✅ Complete | 2025-11-01 | +| Architecture | ✅ Complete | 2025-11-01 | +| Roadmap | ✅ Complete | 2025-11-01 | +| API Reference | 📋 Planned | - | + +**Legend:** +- ✅ Complete - Documentation is ready +- 🚧 In Progress - Being written +- 📋 Planned - On the roadmap +- ⚠️ Outdated - Needs update + +--- + +## 🆘 Need Help? + +**Can't find what you're looking for?** + +1. **Search GitHub Issues** - Someone might have asked already +2. **Join Telegram** - [NOFX Developer Community](https://t.me/nofx_dev_community) +3. **Ask on Twitter** - Mention [@nofx_ai](https://x.com/nofx_ai) +4. **Create an Issue** - [New Issue](https://github.com/tinkle-community/nofx/issues/new) + +--- + +## 🤝 Contributing to Documentation + +Found an error or want to improve the docs? + +1. **Small fixes** - Click "Edit" on GitHub and submit PR +2. **New documentation** - Create an issue first to discuss +3. **Translations** - See [Contributing Guide](../CONTRIBUTING.md) + +**Documentation Contributors:** +- All documentation follows [Markdown Guide](https://www.markdownguide.org/) +- Use clear, concise language +- Include code examples where helpful +- Add screenshots for UI-related docs + +--- + +**Last Updated:** 2025-11-01 +**Maintained by:** [Tinkle Community](https://github.com/tinkle-community) diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 00000000..2c1a2f6f --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,570 @@ +# 🏗️ NOFX Architecture Documentation + +**Language:** [English](README.md) | [中文](README.zh-CN.md) + +Technical documentation for developers who want to understand NOFX internals. + +--- + +## 📋 Overview + +NOFX is a full-stack AI trading platform with: +- **Backend:** Go (Gin framework, SQLite) +- **Frontend:** React/TypeScript (Vite, TailwindCSS) +- **Architecture:** Microservice-inspired modular design + +--- + +## 📁 Project Structure + +``` +nofx/ +├── main.go # Program entry (multi-trader manager) +├── config.json # ~~Multi-trader config~~ (Now via web interface) +├── trading.db # SQLite database (traders, models, exchanges) +│ +├── api/ # HTTP API service +│ └── server.go # Gin framework, RESTful API +│ +├── trader/ # Trading core +│ ├── auto_trader.go # Auto trading main controller +│ ├── interface.go # Unified trader interface +│ ├── binance_futures.go # Binance API wrapper +│ ├── hyperliquid_trader.go # Hyperliquid DEX wrapper +│ └── aster_trader.go # Aster DEX wrapper +│ +├── manager/ # Multi-trader management +│ └── trader_manager.go # Manages multiple trader instances +│ +├── config/ # Configuration & database +│ └── database.go # SQLite operations and schema +│ +├── auth/ # Authentication +│ └── jwt.go # JWT token management & 2FA +│ +├── mcp/ # Model Context Protocol - AI communication +│ └── client.go # AI API client (DeepSeek/Qwen/Custom) +│ +├── decision/ # AI decision engine +│ ├── engine.go # Decision logic with historical feedback +│ └── prompt_manager.go # Prompt template system +│ +├── market/ # Market data fetching +│ └── data.go # Market data & technical indicators (TA-Lib) +│ +├── pool/ # Coin pool management +│ └── coin_pool.go # AI500 + OI Top merged pool +│ +├── logger/ # Logging system +│ └── decision_logger.go # Decision recording + performance analysis +│ +├── decision_logs/ # Decision log storage (JSON files) +│ ├── {trader_id}/ # Per-trader logs +│ └── {timestamp}.json # Individual decisions +│ +└── web/ # React frontend + ├── src/ + │ ├── components/ # React components + │ │ ├── EquityChart.tsx # Equity curve chart + │ │ ├── ComparisonChart.tsx # Multi-AI comparison chart + │ │ └── CompetitionPage.tsx # Competition leaderboard + │ ├── lib/api.ts # API call wrapper + │ ├── types/index.ts # TypeScript types + │ ├── stores/ # Zustand state management + │ ├── index.css # Binance-style CSS + │ └── App.tsx # Main app + ├── package.json # Frontend dependencies + └── vite.config.ts # Vite configuration +``` + +--- + +## 🔧 Core Dependencies + +### Backend (Go) + +| Package | Purpose | Version | +|---------|---------|---------| +| `github.com/gin-gonic/gin` | HTTP API framework | v1.9+ | +| `github.com/adshao/go-binance/v2` | Binance API client | v2.4+ | +| `github.com/markcheno/go-talib` | Technical indicators (TA-Lib) | Latest | +| `github.com/mattn/go-sqlite3` | SQLite database driver | v1.14+ | +| `github.com/golang-jwt/jwt/v5` | JWT authentication | v5.0+ | +| `github.com/pquerna/otp` | 2FA/TOTP support | v1.4+ | +| `golang.org/x/crypto` | Password hashing (bcrypt) | Latest | + +### Frontend (React + TypeScript) + +| Package | Purpose | Version | +|---------|---------|---------| +| `react` + `react-dom` | UI framework | 18.3+ | +| `typescript` | Type safety | 5.8+ | +| `vite` | Build tool | 6.0+ | +| `recharts` | Charts (equity, comparison) | 2.15+ | +| `swr` | Data fetching & caching | 2.2+ | +| `zustand` | State management | 5.0+ | +| `tailwindcss` | CSS framework | 3.4+ | +| `lucide-react` | Icon library | Latest | + +--- + +## 🗂️ System Architecture + +### High-Level Overview + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ PRESENTATION LAYER │ +│ React SPA (Vite + TypeScript + TailwindCSS) │ +│ - Competition dashboard, trader management UI │ +│ - Real-time charts (Recharts), authentication pages │ +└──────────────────────────────────────────────────────────────────┘ + ↓ HTTP/JSON API +┌──────────────────────────────────────────────────────────────────┐ +│ API LAYER (Gin Router) │ +│ /api/traders, /api/status, /api/positions, /api/decisions │ +│ Authentication middleware (JWT), CORS handling │ +└──────────────────────────────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────────────┐ +│ BUSINESS LOGIC LAYER │ +│ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────┐ │ +│ │ TraderManager │ │ DecisionEngine │ │ MarketData │ │ +│ │ - Multi-trader │ │ - AI reasoning │ │ - K-lines │ │ +│ │ orchestration │ │ - Risk control │ │ - Indicators │ │ +│ └──────────────────┘ └──────────────────┘ └────────────────┘ │ +└──────────────────────────────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────────────┐ +│ DATA ACCESS LAYER │ +│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │ +│ │ SQLite DB │ │ File Logger │ │ External APIs │ │ +│ │ - Traders │ │ - Decisions │ │ - Binance │ │ +│ │ - Models │ │ - Performance│ │ - Hyperliquid │ │ +│ │ - Exchanges │ │ analysis │ │ - Aster │ │ +│ └──────────────┘ └──────────────┘ └────────────────────┘ │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Component Diagram + +*(Coming soon: detailed component interaction diagram)* + +--- + +## 📚 Core Modules + +### 1. Trader System (`trader/`) + +**Purpose:** Trading execution layer with multi-exchange support + +**Key Files:** +- `auto_trader.go` - Main trading orchestrator (100+ lines) +- `interface.go` - Unified trader interface +- `binance_futures.go` - Binance API wrapper +- `hyperliquid_trader.go` - Hyperliquid DEX wrapper +- `aster_trader.go` - Aster DEX wrapper + +**Design Pattern:** Strategy pattern with interface-based abstraction + +**Example:** +```go +type ExchangeClient interface { + GetAccount() (*AccountInfo, error) + GetPositions() ([]*Position, error) + CreateOrder(*OrderParams) (*Order, error) + // ... more methods +} +``` + +--- + +### 2. Decision Engine (`decision/`) + +**Purpose:** AI-powered trading decision making + +**Key Files:** +- `engine.go` - Decision logic with historical feedback +- `prompt_manager.go` - Template system for AI prompts + +**Features:** +- Chain-of-Thought reasoning +- Historical performance analysis +- Risk-aware decision making +- Multi-model support (DeepSeek, Qwen, custom) + +**Flow:** +``` +Historical Data → Prompt Generation → AI API Call → +Decision Parsing → Risk Validation → Execution +``` + +--- + +### 3. Market Data System (`market/`) + +**Purpose:** Fetch and analyze market data + +**Key Files:** +- `data.go` - Market data fetching and technical indicators + +**Features:** +- Multi-timeframe K-line data (3min, 4hour) +- Technical indicators via TA-Lib: + - EMA (20, 50) + - MACD + - RSI (7, 14) + - ATR (volatility) +- Open Interest tracking + +--- + +### 4. Manager (`manager/`) + +**Purpose:** Multi-trader orchestration + +**Key Files:** +- `trader_manager.go` - Manages multiple trader instances + +**Responsibilities:** +- Trader lifecycle (start, stop, restart) +- Resource allocation +- Concurrent execution coordination + +--- + +### 5. API Server (`api/`) + +**Purpose:** HTTP API for frontend communication + +**Key Files:** +- `server.go` - Gin framework RESTful API + +**Endpoints:** +``` +GET /api/traders # List all traders +POST /api/traders # Create trader +POST /api/traders/:id/start # Start trader +GET /api/status # System status +GET /api/positions # Current positions +GET /api/decisions/latest # Recent decisions +``` + +--- + +### 6. Database Layer (`config/`) + +**Purpose:** SQLite data persistence + +**Key Files:** +- `database.go` - Database operations and schema + +**Tables:** +- `users` - User accounts (with 2FA support) +- `ai_models` - AI model configurations +- `exchanges` - Exchange credentials +- `traders` - Trader instances +- `equity_history` - Performance tracking +- `system_config` - Application settings + +--- + +### 7. Authentication (`auth/`) + +**Purpose:** User authentication and authorization + +**Features:** +- JWT token-based auth +- 2FA with TOTP (Google Authenticator) +- Bcrypt password hashing +- Admin mode (simplified single-user) + +--- + +## 🔄 Request Flow Examples + +### Example 1: Create New Trader + +``` +User Action (Frontend) + ↓ +POST /api/traders + ↓ +API Server (auth middleware) + ↓ +Database.CreateTrader() + ↓ +TraderManager.StartTrader() + ↓ +AutoTrader.Run() → goroutine + ↓ +Response: {trader_id, status} +``` + +### Example 2: Trading Decision Cycle + +``` +AutoTrader (every 3-5 min) + ↓ +1. FetchAccountStatus() + ↓ +2. GetOpenPositions() + ↓ +3. FetchMarketData() → TA-Lib indicators + ↓ +4. AnalyzeHistory() → last 20 trades + ↓ +5. GeneratePrompt() → full context + ↓ +6. CallAI() → DeepSeek/Qwen + ↓ +7. ParseDecision() → structured output + ↓ +8. ValidateRisk() → position limits, margin + ↓ +9. ExecuteOrders() → exchange API + ↓ +10. LogDecision() → JSON file + database +``` + +--- + +## 📊 Data Flow + +### Market Data Flow + +``` +Exchange API + ↓ +market.FetchKlines() + ↓ +TA-Lib.Calculate(EMA, MACD, RSI) + ↓ +DecisionEngine (as context) + ↓ +AI Model (reasoning) +``` + +### Decision Logging Flow + +``` +AI Response + ↓ +decision_logger.go + ↓ +JSON file: decision_logs/{trader_id}/{timestamp}.json + ↓ +Database: performance tracking + ↓ +Frontend: /api/decisions/latest +``` + +--- + +## 🗄️ Database Schema + +### Core Tables + +**users** +```sql +- id (INTEGER PRIMARY KEY) +- username (TEXT UNIQUE) +- password_hash (TEXT) +- totp_secret (TEXT) +- is_admin (BOOLEAN) +- created_at (DATETIME) +``` + +**ai_models** +```sql +- id (INTEGER PRIMARY KEY) +- name (TEXT) +- model_type (TEXT) -- deepseek, qwen, custom +- api_key (TEXT) +- api_url (TEXT) +- enabled (BOOLEAN) +``` + +**traders** +```sql +- id (TEXT PRIMARY KEY) +- name (TEXT) +- ai_model_id (INTEGER FK) +- exchange_id (INTEGER FK) +- initial_balance (REAL) +- current_equity (REAL) +- status (TEXT) -- running, stopped +- created_at (DATETIME) +``` + +*(More details: database-schema.md - coming soon)* + +--- + +## 🔌 API Reference + +### Authentication + +**POST /api/auth/login** +```json +Request: { + "username": "string", + "password": "string", + "totp_code": "string" // optional +} + +Response: { + "token": "jwt_token", + "user": {...} +} +``` + +### Trader Management + +**GET /api/traders** +```json +Response: { + "traders": [ + { + "id": "string", + "name": "string", + "status": "running|stopped", + "balance": 1000.0, + "roi": 5.2 + } + ] +} +``` + +*(Full API reference: api-reference.md - coming soon)* + +--- + +## 🧪 Testing Architecture + +### Current State +- ⚠️ No unit tests yet +- ⚠️ Manual testing only +- ⚠️ Testnet verification + +### Planned Testing Strategy + +**Unit Tests (Priority 1)** +``` +trader/binance_futures_test.go +- Mock API responses +- Test precision handling +- Validate order construction +``` + +**Integration Tests (Priority 2)** +``` +- End-to-end trading flow (testnet) +- Multi-trader scenarios +- Database operations +``` + +**Frontend Tests (Priority 3)** +``` +- Component tests (Vitest + React Testing Library) +- API integration tests +- E2E tests (Playwright) +``` + +*(Testing guide: testing-guide.md - coming soon)* + +--- + +## 🔧 Development Tools + +### Build & Run + +```bash +# Backend +go build -o nofx +./nofx + +# Frontend +cd web +npm run dev + +# Docker +docker compose up --build +``` + +### Code Quality + +```bash +# Format Go code +go fmt ./... + +# Lint (if configured) +golangci-lint run + +# Type check TypeScript +cd web && npm run build +``` + +--- + +## 📈 Performance Considerations + +### Backend +- **Concurrency:** Each trader runs in separate goroutine +- **Database:** SQLite (good for <100 traders) +- **API Rate Limits:** Handled per exchange +- **Memory:** ~50-100MB per trader + +### Frontend +- **Data Fetching:** SWR with 5-10s polling +- **State:** Zustand (lightweight) +- **Bundle Size:** ~500KB (gzipped) + +--- + +## 🔮 Future Architecture Plans + +### Planned Improvements + +1. **Microservices Split** (if scaling needed) + - Separate decision engine service + - Market data service + - Execution service + +2. **Database Migration** + - Mysql for production (>100 traders) + - Redis for caching + +3. **Event-Driven Architecture** + - WebSocket for real-time updates + - Message queue (RabbitMQ/NATS) + +4. **Kubernetes Deployment** + - Helm charts + - Auto-scaling + - High availability + +--- + +## 🆘 For Developers + +**Want to contribute?** +- Read [Contributing Guide](../../CONTRIBUTING.md) +- Check [Open Issues](https://github.com/tinkle-community/nofx/issues) +- Join [Telegram Community](https://t.me/nofx_dev_community) + +**Need clarification?** +- Open a [GitHub Discussion](https://github.com/tinkle-community/nofx/discussions) +- Ask in Telegram + +--- + +## 📚 Related Documentation + +- [Getting Started](../getting-started/README.md) - Setup and deployment +- [Contributing](../../CONTRIBUTING.md) - How to contribute +- [Community](../community/README.md) - Bounties and recognition + +--- + +[← Back to Documentation Home](../README.md) diff --git a/docs/architecture/README.zh-CN.md b/docs/architecture/README.zh-CN.md new file mode 100644 index 00000000..36732b09 --- /dev/null +++ b/docs/architecture/README.zh-CN.md @@ -0,0 +1,570 @@ +# 🏗️ NOFX 架构文档 + +**语言:** [English](README.md) | [中文](README.zh-CN.md) + +为希望了解 NOFX 内部实现的开发者提供的技术文档。 + +--- + +## 📋 概述 + +NOFX 是一个全栈 AI 交易平台： +- **后端：** Go (Gin 框架, SQLite) +- **前端：** React/TypeScript (Vite, TailwindCSS) +- **架构：** 微服务启发的模块化设计 + +--- + +## 📁 项目结构 + +``` +nofx/ +├── main.go # 程序入口（多交易员管理器） +├── config.json # ~~多交易员配置~~ (现通过Web界面) +├── trading.db # SQLite 数据库（交易员、模型、交易所） +│ +├── api/ # HTTP API 服务 +│ └── server.go # Gin 框架，RESTful API +│ +├── trader/ # 交易核心 +│ ├── auto_trader.go # 自动交易主控制器 +│ ├── interface.go # 统一交易员接口 +│ ├── binance_futures.go # Binance API 包装器 +│ ├── hyperliquid_trader.go # Hyperliquid DEX 包装器 +│ └── aster_trader.go # Aster DEX 包装器 +│ +├── manager/ # 多交易员管理 +│ └── trader_manager.go # 管理多个交易员实例 +│ +├── config/ # 配置与数据库 +│ └── database.go # SQLite 操作和模式 +│ +├── auth/ # 认证 +│ └── jwt.go # JWT token 管理 & 2FA +│ +├── mcp/ # Model Context Protocol - AI 通信 +│ └── client.go # AI API 客户端（DeepSeek/Qwen/自定义） +│ +├── decision/ # AI 决策引擎 +│ ├── engine.go # 带历史反馈的决策逻辑 +│ └── prompt_manager.go # 提示词模板系统 +│ +├── market/ # 市场数据获取 +│ └── data.go # 市场数据与技术指标（TA-Lib） +│ +├── pool/ # 币种池管理 +│ └── coin_pool.go # AI500 + OI Top 合并池 +│ +├── logger/ # 日志系统 +│ └── decision_logger.go # 决策记录 + 性能分析 +│ +├── decision_logs/ # 决策日志存储（JSON 文件） +│ ├── {trader_id}/ # 每个交易员的日志 +│ └── {timestamp}.json # 单个决策 +│ +└── web/ # React 前端 + ├── src/ + │ ├── components/ # React 组件 + │ │ ├── EquityChart.tsx # 权益曲线图表 + │ │ ├── ComparisonChart.tsx # 多 AI 对比图表 + │ │ └── CompetitionPage.tsx # 竞赛排行榜 + │ ├── lib/api.ts # API 调用包装器 + │ ├── types/index.ts # TypeScript 类型 + │ ├── stores/ # Zustand 状态管理 + │ ├── index.css # Binance 风格样式 + │ └── App.tsx # 主应用 + ├── package.json # 前端依赖 + └── vite.config.ts # Vite 配置 +``` + +--- + +## 🔧 核心依赖 + +### 后端 (Go) + +| 包 | 用途 | 版本 | +|---------|---------|---------| +| `github.com/gin-gonic/gin` | HTTP API 框架 | v1.9+ | +| `github.com/adshao/go-binance/v2` | Binance API 客户端 | v2.4+ | +| `github.com/markcheno/go-talib` | 技术指标（TA-Lib） | 最新 | +| `github.com/mattn/go-sqlite3` | SQLite 数据库驱动 | v1.14+ | +| `github.com/golang-jwt/jwt/v5` | JWT 认证 | v5.0+ | +| `github.com/pquerna/otp` | 2FA/TOTP 支持 | v1.4+ | +| `golang.org/x/crypto` | 密码哈希（bcrypt） | 最新 | + +### 前端 (React + TypeScript) + +| 包 | 用途 | 版本 | +|---------|---------|---------| +| `react` + `react-dom` | UI 框架 | 18.3+ | +| `typescript` | 类型安全 | 5.8+ | +| `vite` | 构建工具 | 6.0+ | +| `recharts` | 图表（权益、对比） | 2.15+ | +| `swr` | 数据获取与缓存 | 2.2+ | +| `zustand` | 状态管理 | 5.0+ | +| `tailwindcss` | CSS 框架 | 3.4+ | +| `lucide-react` | 图标库 | 最新 | + +--- + +## 🗂️ 系统架构 + +### 高层架构概览 + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ 表现层 │ +│ React SPA (Vite + TypeScript + TailwindCSS) │ +│ - 竞赛仪表板、交易员管理 UI │ +│ - 实时图表 (Recharts)、认证页面 │ +└──────────────────────────────────────────────────────────────────┘ + ↓ HTTP/JSON API +┌──────────────────────────────────────────────────────────────────┐ +│ API 层 (Gin Router) │ +│ /api/traders, /api/status, /api/positions, /api/decisions │ +│ 认证中间件 (JWT)、CORS 处理 │ +└──────────────────────────────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────────────┐ +│ 业务逻辑层 │ +│ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────┐ │ +│ │ TraderManager │ │ DecisionEngine │ │ MarketData │ │ +│ │ - 多交易员 │ │ - AI 推理 │ │ - K线数据 │ │ +│ │ 编排 │ │ - 风险控制 │ │ - 技术指标 │ │ +│ └──────────────────┘ └──────────────────┘ └────────────────┘ │ +└──────────────────────────────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────────────┐ +│ 数据访问层 │ +│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │ +│ │ SQLite DB │ │ 文件日志 │ │ 外部 APIs │ │ +│ │ - Traders │ │ - Decisions │ │ - Binance │ │ +│ │ - Models │ │ - Performance│ │ - Hyperliquid │ │ +│ │ - Exchanges │ │ analysis │ │ - Aster │ │ +│ └──────────────┘ └──────────────┘ └────────────────────┘ │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### 组件图 + +*（即将推出：详细的组件交互图）* + +--- + +## 📚 核心模块 + +### 1. 交易系统 (`trader/`) + +**用途：** 支持多交易所的交易执行层 + +**关键文件：** +- `auto_trader.go` - 主交易编排器（100+ 行） +- `interface.go` - 统一的交易员接口 +- `binance_futures.go` - Binance API 包装器 +- `hyperliquid_trader.go` - Hyperliquid DEX 包装器 +- `aster_trader.go` - Aster DEX 包装器 + +**设计模式：** 基于接口抽象的策略模式 + +**示例：** +```go +type ExchangeClient interface { + GetAccount() (*AccountInfo, error) + GetPositions() ([]*Position, error) + CreateOrder(*OrderParams) (*Order, error) + // ... 更多方法 +} +``` + +--- + +### 2. 决策引擎 (`decision/`) + +**用途：** AI 驱动的交易决策制定 + +**关键文件：** +- `engine.go` - 带历史反馈的决策逻辑 +- `prompt_manager.go` - AI 提示词模板系统 + +**特性：** +- 思维链推理 +- 历史表现分析 +- 风险感知决策 +- 多模型支持（DeepSeek、Qwen、自定义） + +**流程：** +``` +历史数据 → 提示词生成 → AI API 调用 → +决策解析 → 风险验证 → 执行 +``` + +--- + +### 3. 市场数据系统 (`market/`) + +**用途：** 获取和分析市场数据 + +**关键文件：** +- `data.go` - 市场数据获取和技术指标 + +**特性：** +- 多时间周期 K线数据（3分钟、4小时） +- 通过 TA-Lib 计算技术指标： + - EMA (20, 50) + - MACD + - RSI (7, 14) + - ATR（波动率） +- 持仓量跟踪 + +--- + +### 4. 管理器 (`manager/`) + +**用途：** 多交易员编排 + +**关键文件：** +- `trader_manager.go` - 管理多个交易员实例 + +**职责：** +- 交易员生命周期（启动、停止、重启） +- 资源分配 +- 并发执行协调 + +--- + +### 5. API 服务器 (`api/`) + +**用途：** 前端通信的 HTTP API + +**关键文件：** +- `server.go` - Gin 框架 RESTful API + +**端点：** +``` +GET /api/traders # 列出所有交易员 +POST /api/traders # 创建交易员 +POST /api/traders/:id/start # 启动交易员 +GET /api/status # 系统状态 +GET /api/positions # 当前持仓 +GET /api/decisions/latest # 最近决策 +``` + +--- + +### 6. 数据库层 (`config/`) + +**用途：** SQLite 数据持久化 + +**关键文件：** +- `database.go` - 数据库操作和模式 + +**表：** +- `users` - 用户账户（支持 2FA） +- `ai_models` - AI 模型配置 +- `exchanges` - 交易所凭证 +- `traders` - 交易员实例 +- `equity_history` - 绩效跟踪 +- `system_config` - 应用程序设置 + +--- + +### 7. 认证 (`auth/`) + +**用途：** 用户认证和授权 + +**特性：** +- 基于 JWT token 的认证 +- 使用 TOTP 的 2FA（Google Authenticator） +- Bcrypt 密码哈希 +- 管理员模式（简化的单用户模式） + +--- + +## 🔄 请求流程示例 + +### 示例 1：创建新交易员 + +``` +用户操作（前端） + ↓ +POST /api/traders + ↓ +API 服务器（认证中间件） + ↓ +Database.CreateTrader() + ↓ +TraderManager.StartTrader() + ↓ +AutoTrader.Run() → goroutine + ↓ +响应: {trader_id, status} +``` + +### 示例 2：交易决策周期 + +``` +AutoTrader（每 3-5 分钟） + ↓ +1. FetchAccountStatus() + ↓ +2. GetOpenPositions() + ↓ +3. FetchMarketData() → TA-Lib 指标 + ↓ +4. AnalyzeHistory() → 最近 20 笔交易 + ↓ +5. GeneratePrompt() → 完整上下文 + ↓ +6. CallAI() → DeepSeek/Qwen + ↓ +7. ParseDecision() → 结构化输出 + ↓ +8. ValidateRisk() → 仓位限制、保证金 + ↓ +9. ExecuteOrders() → 交易所 API + ↓ +10. LogDecision() → JSON 文件 + 数据库 +``` + +--- + +## 📊 数据流 + +### 市场数据流 + +``` +交易所 API + ↓ +market.FetchKlines() + ↓ +TA-Lib.Calculate(EMA, MACD, RSI) + ↓ +DecisionEngine（作为上下文） + ↓ +AI 模型（推理） +``` + +### 决策日志流 + +``` +AI 响应 + ↓ +decision_logger.go + ↓ +JSON 文件: decision_logs/{trader_id}/{timestamp}.json + ↓ +数据库: 绩效跟踪 + ↓ +前端: /api/decisions/latest +``` + +--- + +## 🗄️ 数据库架构 + +### 核心表 + +**users** +```sql +- id (INTEGER PRIMARY KEY) +- username (TEXT UNIQUE) +- password_hash (TEXT) +- totp_secret (TEXT) +- is_admin (BOOLEAN) +- created_at (DATETIME) +``` + +**ai_models** +```sql +- id (INTEGER PRIMARY KEY) +- name (TEXT) +- model_type (TEXT) -- deepseek, qwen, custom +- api_key (TEXT) +- api_url (TEXT) +- enabled (BOOLEAN) +``` + +**traders** +```sql +- id (TEXT PRIMARY KEY) +- name (TEXT) +- ai_model_id (INTEGER FK) +- exchange_id (INTEGER FK) +- initial_balance (REAL) +- current_equity (REAL) +- status (TEXT) -- running, stopped +- created_at (DATETIME) +``` + +*（更多详情：database-schema.md - 即将推出）* + +--- + +## 🔌 API 参考 + +### 认证 + +**POST /api/auth/login** +```json +请求: { + "username": "string", + "password": "string", + "totp_code": "string" // 可选 +} + +响应: { + "token": "jwt_token", + "user": {...} +} +``` + +### 交易员管理 + +**GET /api/traders** +```json +响应: { + "traders": [ + { + "id": "string", + "name": "string", + "status": "running|stopped", + "balance": 1000.0, + "roi": 5.2 + } + ] +} +``` + +*（完整 API 参考：api-reference.md - 即将推出）* + +--- + +## 🧪 测试架构 + +### 当前状态 +- ⚠️ 尚无单元测试 +- ⚠️ 仅手动测试 +- ⚠️ 测试网验证 + +### 计划的测试策略 + +**单元测试（优先级 1）** +``` +trader/binance_futures_test.go +- 模拟 API 响应 +- 测试精度处理 +- 验证订单构造 +``` + +**集成测试（优先级 2）** +``` +- 端到端交易流程（测试网） +- 多交易员场景 +- 数据库操作 +``` + +**前端测试（优先级 3）** +``` +- 组件测试（Vitest + React Testing Library） +- API 集成测试 +- E2E 测试（Playwright） +``` + +*（测试指南：testing-guide.md - 即将推出）* + +--- + +## 🔧 开发工具 + +### 构建与运行 + +```bash +# 后端 +go build -o nofx +./nofx + +# 前端 +cd web +npm run dev + +# Docker +docker compose up --build +``` + +### 代码质量 + +```bash +# 格式化 Go 代码 +go fmt ./... + +# Lint（如果配置） +golangci-lint run + +# TypeScript 类型检查 +cd web && npm run build +``` + +--- + +## 📈 性能考虑 + +### 后端 +- **并发：** 每个交易员在独立的 goroutine 中运行 +- **数据库：** SQLite（适用于 <100 个交易员） +- **API 速率限制：** 按交易所处理 +- **内存：** 每个交易员 ~50-100MB + +### 前端 +- **数据获取：** SWR，5-10 秒轮询 +- **状态：** Zustand（轻量级） +- **包大小：** ~500KB（gzipped） + +--- + +## 🔮 未来架构计划 + +### 计划改进 + +1. **微服务拆分**（如需扩展） + - 独立的决策引擎服务 + - 市场数据服务 + - 执行服务 + +2. **数据库迁移** + - 生产环境使用 Mysql (>100 个交易员） + - Redis 缓存 + +3. **事件驱动架构** + - WebSocket 实时更新 + - 消息队列（RabbitMQ/NATS） + +4. **Kubernetes 部署** + - Helm charts + - 自动扩展 + - 高可用性 + +--- + +## 🆘 开发者资源 + +**想要贡献？** +- 阅读[贡献指南](../../CONTRIBUTING.md) +- 查看[开放问题](https://github.com/tinkle-community/nofx/issues) +- 加入 [Telegram 社区](https://t.me/nofx_dev_community) + +**需要澄清？** +- 开启 [GitHub 讨论](https://github.com/tinkle-community/nofx/discussions) +- 在 Telegram 提问 + +--- + +## 📚 相关文档 + +- [快速开始](../getting-started/README.zh-CN.md) - 设置和部署 +- [贡献指南](../../CONTRIBUTING.md) - 如何贡献 +- [社区](../community/README.md) - 悬赏和认可 + +--- + +[← 返回文档首页](../README.md) diff --git a/docs/community/README.md b/docs/community/README.md new file mode 100644 index 00000000..497e10c5 --- /dev/null +++ b/docs/community/README.md @@ -0,0 +1,233 @@ +# 👥 NOFX Community + +Welcome to the NOFX community! This section contains everything you need to contribute and participate. + +--- + +## 🤝 How to Contribute + +### Getting Started + +1. **Read the Guides** + - [Contributing Guide](../../CONTRIBUTING.md) - Complete contribution workflow + - [Code of Conduct](../../CODE_OF_CONDUCT.md) - Community standards + - [Security Policy](../../SECURITY.md) - Report vulnerabilities + +2. **Find Something to Work On** + - Browse [GitHub Issues](https://github.com/tinkle-community/nofx/issues) + - Look for `good first issue` label + - Check out [bounty tasks](#-bounty-program) + +3. **Join the Community** + - 💬 [Telegram Developer Community](https://t.me/nofx_dev_community) + - 🐦 [Twitter @nofx_ai](https://x.com/nofx_ai) + - 🐙 [GitHub Discussions](https://github.com/tinkle-community/nofx/discussions) + +--- + +## 💰 Bounty Program + +### Active Bounties + +NOFX offers bounties for valuable contributions: + +| Category | Reward Range | Examples | +|----------|--------------|----------| +| 🥇 Major Features | $500-1000 | Exchange integration, core architecture | +| 🥈 Medium Features | $200-500 | WebSocket support, new AI models | +| 🥉 Small Features | $50-200 | Bug fixes, UI improvements, documentation | + +### How to Claim Bounties + +**📖 Complete Guide:** [bounty-guide.md](bounty-guide.md) + +**Quick Steps:** +1. Find issue tagged `[BOUNTY]` +2. Comment with your proposal +3. Wait for approval +4. Work on the task +5. Submit PR with demo +6. Get paid after merge! + +### Current Bounty Tasks + +| Task | Reward | Difficulty | Status | +|------|--------|------------|--------| +| [Hyperliquid Integration](bounty-hyperliquid.md) | TBD | Hard | 🟡 Open | +| [Aster DEX Integration](bounty-aster.md) | TBD | Medium | ✅ Completed | + +--- + +## 🏆 Recognition + +### Ways to Get Recognized + +**Contributor Levels:** +- 🌟 **Active Contributor** - Submit quality PRs +- ⭐ **Trusted Contributor** - 3+ merged PRs, given review rights +- 💎 **Core Team** - Top contributors, invited by maintainers + +**Benefits:** +- Listed in README and release notes +- Direct access to maintainer discussions +- Priority support for your issues +- Invitation to private roadmap planning + +### Hall of Fame + +**Top Contributors:** +- Coming soon! Be the first! 🚀 + +--- + +## 📋 Contribution Types + +### Code Contributions +- New exchange integrations +- AI model adapters +- Bug fixes and improvements +- Performance optimizations + +**Required:** +- ✅ Code compiles and runs +- ✅ Follows code style guidelines +- ✅ Includes basic tests (preferred) +- ✅ Updates documentation if needed + +### Documentation +- Tutorial writing +- Translation (中文, Русский, Українська) +- FAQ updates +- Video guides + +**Rewards:** +- $50-200 for comprehensive guides +- Recognition in docs +- Contributor badge + +### Testing & QA +- Bug reports with reproduction steps +- Security vulnerability reports (see [Security Policy](../../SECURITY.md)) +- Testnet verification +- Performance testing + +**Rewards:** +- $50-500 for critical bug finds +- Up to $1000 for security vulnerabilities +- Recognition in security hall of fame + +--- + +## 🌍 Community Channels + +### Primary Channels + +| Platform | Purpose | Link | +|----------|---------|------| +| 💬 Telegram | Real-time chat, questions | [Join](https://t.me/nofx_dev_community) | +| 🐙 GitHub | Issues, PRs, discussions | [Visit](https://github.com/tinkle-community/nofx) | +| 🐦 Twitter | Announcements, updates | [@nofx_ai](https://x.com/nofx_ai) | + +### Core Team + +- **Tinkle** - [@Web3Tinkle](https://x.com/Web3Tinkle) +- **Zack** - [@0x_ZackH](https://x.com/0x_ZackH) + +**Contact:** +- Technical questions → Telegram or GitHub Issues +- Business inquiries → Twitter DM to core team +- Security reports → [SECURITY.md](../../SECURITY.md) + +--- + +## 📅 Community Events + +### Regular Activities +- **Weekly Updates** - Development progress (Telegram) +- **Monthly AMA** - Ask maintainers anything +- **Quarterly Roadmap** - Future plans discussion + +### Upcoming Events +- *No scheduled events yet* + +**Want to organize an event?** +- Contact core team on Telegram +- Propose in GitHub Discussions +- Tweet and tag @nofx_ai + +--- + +## 🎓 Learning Resources + +### For Contributors + +**Understanding NOFX:** +- [System Architecture](../architecture/README.md) *(coming soon)* +- [API Reference](../architecture/api-reference.md) *(coming soon)* +- [Database Schema](../architecture/database-schema.md) *(coming soon)* + +**Learning Materials:** +- Go programming: [Tour of Go](https://go.dev/tour/) +- React/TypeScript: [React Docs](https://react.dev/) +- Trading basics: [Binance Academy](https://academy.binance.com/) + +### Recommended Reading + +1. **Before Contributing:** + - [Contributing Guide](../../CONTRIBUTING.md) + - [Code of Conduct](../../CODE_OF_CONDUCT.md) + +2. **For Exchange Integration:** + - [Hyperliquid Bounty](bounty-hyperliquid.md) + - [Aster Bounty](bounty-aster.md) + - Existing code: `trader/binance_futures.go` + +3. **For AI Features:** + - [Custom API Guide](../getting-started/custom-api.md) + - MCP client code: `mcp/client.go` + - Decision engine: `decision/engine.go` + +--- + +## 🛡️ Community Guidelines + +### Our Values +- **Respect** - Treat everyone with courtesy +- **Transparency** - Open communication and decisions +- **Quality** - High standards for contributions +- **Collaboration** - Work together, help each other + +### Not Acceptable +- ❌ Harassment or discrimination +- ❌ Spam or self-promotion +- ❌ Sharing malicious code +- ❌ Violating [Code of Conduct](../../CODE_OF_CONDUCT.md) + +**Violations will result in:** +1. Warning +2. Temporary ban +3. Permanent ban (serious cases) + +--- + +## 📊 Community Stats + +| Metric | Count | +|--------|-------| +| GitHub Stars | Check [repo](https://github.com/tinkle-community/nofx) | +| Contributors | 21+ | +| Open Issues | Check [issues](https://github.com/tinkle-community/nofx/issues) | +| Merged PRs | Check [pulls](https://github.com/tinkle-community/nofx/pulls?q=is%3Apr+is%3Amerged) | + +--- + +## 🚀 Quick Links + +- **Want to contribute code?** → [Contributing Guide](../../CONTRIBUTING.md) +- **Want to claim bounty?** → [Bounty Guide](bounty-guide.md) +- **Found a security issue?** → [Security Policy](../../SECURITY.md) +- **Have questions?** → [Telegram Community](https://t.me/nofx_dev_community) + +--- + +[← Back to Documentation Home](../README.md) diff --git a/INTEGRATION_BOUNTY_ASTER.md b/docs/community/bounty-aster.md similarity index 100% rename from INTEGRATION_BOUNTY_ASTER.md rename to docs/community/bounty-aster.md diff --git a/HOW_TO_POST_BOUNTY.md b/docs/community/bounty-guide.md similarity index 100% rename from HOW_TO_POST_BOUNTY.md rename to docs/community/bounty-guide.md diff --git a/INTEGRATION_BOUNTY_HYPERLIQUID.md b/docs/community/bounty-hyperliquid.md similarity index 100% rename from INTEGRATION_BOUNTY_HYPERLIQUID.md rename to docs/community/bounty-hyperliquid.md diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md new file mode 100644 index 00000000..c35926f9 --- /dev/null +++ b/docs/getting-started/README.md @@ -0,0 +1,127 @@ +# 🚀 Getting Started with NOFX + +**Language:** [English](README.md) | [中文](README.zh-CN.md) + +This section contains all the documentation you need to get NOFX up and running. + +## 📋 Deployment Options + +Choose the method that best fits your needs: + +### 🐳 Docker Deployment (Recommended) + +**Best for:** Beginners, quick setup, production deployments + +- **English:** [docker-deploy.en.md](docker-deploy.en.md) +- **中文:** [docker-deploy.zh-CN.md](docker-deploy.zh-CN.md) + +**Pros:** +- ✅ One-command setup +- ✅ All dependencies included +- ✅ Easy to update and manage +- ✅ Isolated environment + +**Quick Start:** +```bash +cp config.example.jsonc config.json +./start.sh start --build +``` + +--- + +### 🔧 PM2 Deployment + +**Best for:** Advanced users, development, custom setups + +- **English:** [pm2-deploy.en.md](pm2-deploy.en.md) +- **中文:** [pm2-deploy.md](pm2-deploy.md) + +**Pros:** +- ✅ Direct process control +- ✅ Better for development +- ✅ Lower resource usage +- ✅ More flexible + +**Quick Start:** +```bash +go build -o nofx +cd web && npm install && npm run build +pm2 start ecosystem.config.js +``` + +--- + +## 🤖 AI Configuration + +### Custom AI Providers + +- **English:** [custom-api.en.md](custom-api.en.md) +- **中文:** [custom-api.md](custom-api.md) + +Use custom AI models or third-party OpenAI-compatible APIs: +- Custom DeepSeek endpoints +- Self-hosted models +- Other LLM providers + +--- + +## 🔑 Prerequisites + +Before starting, ensure you have: + +### For Docker Method: +- ✅ Docker 20.10+ +- ✅ Docker Compose V2 + +### For Manual Method: +- ✅ Go 1.21+ +- ✅ Node.js 18+ +- ✅ TA-Lib library +- ✅ PM2 (optional) + +--- + +## 📚 Next Steps + +After deployment: + +1. **Configure AI Models** → Web interface at http://localhost:3000 +2. **Set Up Exchange** → Add Binance/Hyperliquid credentials +3. **Create Traders** → Combine AI models with exchanges +4. **Start Trading** → Monitor performance in dashboard + +--- + +## ⚠️ Important Notes + +**Before Trading:** +- ⚠️ Test on testnet first +- ⚠️ Start with small amounts +- ⚠️ Understand the risks +- ⚠️ Read [Security Policy](../../SECURITY.md) + +**API Keys:** +- 🔑 Never commit API keys to git +- 🔑 Use environment variables +- 🔑 Restrict IP access +- 🔑 Enable 2FA on exchanges + +--- + +## 🆘 Troubleshooting + +**Common Issues:** + +1. **Docker build fails** → Check Docker version, update to 20.10+ +2. **TA-Lib not found** → `brew install ta-lib` (macOS) or `apt-get install libta-lib0-dev` (Ubuntu) +3. **Port 8080 in use** → Change `API_PORT` in .env file +4. **Frontend won't connect** → Check backend is running on port 8080 + +**Need more help?** +- 📖 [FAQ](../guides/faq.zh-CN.md) +- 💬 [Telegram Community](https://t.me/nofx_dev_community) +- 🐛 [GitHub Issues](https://github.com/tinkle-community/nofx/issues) + +--- + +[← Back to Documentation Home](../README.md) diff --git a/docs/getting-started/README.zh-CN.md b/docs/getting-started/README.zh-CN.md new file mode 100644 index 00000000..aafe5cfb --- /dev/null +++ b/docs/getting-started/README.zh-CN.md @@ -0,0 +1,125 @@ +# 🚀 NOFX 快速开始 + +本节包含让 NOFX 运行起来所需的所有文档。 + +## 📋 部署选项 + +选择最适合您的方式： + +### 🐳 Docker 部署（推荐） + +**适合：** 初学者、快速部署、生产环境 + +- **中文文档：** [docker-deploy.zh-CN.md](docker-deploy.zh-CN.md) +- **English:** [docker-deploy.en.md](docker-deploy.en.md) + +**优势：** +- ✅ 一键启动 +- ✅ 包含所有依赖 +- ✅ 易于更新和管理 +- ✅ 隔离环境 + +**快速开始：** +```bash +cp config.example.jsonc config.json +./start.sh start --build +``` + +--- + +### 🔧 PM2 部署 + +**适合：** 进阶用户、开发环境、自定义设置 + +- **中文文档：** [pm2-deploy.md](pm2-deploy.md) +- **English:** [pm2-deploy.en.md](pm2-deploy.en.md) + +**优势：** +- ✅ 直接进程控制 +- ✅ 更适合开发 +- ✅ 资源占用更低 +- ✅ 更灵活 + +**快速开始：** +```bash +go build -o nofx +cd web && npm install && npm run build +pm2 start ecosystem.config.js +``` + +--- + +## 🤖 AI 配置 + +### 自定义 AI 提供商 + +- **中文文档：** [custom-api.md](custom-api.md) +- **English:** [custom-api.en.md](custom-api.en.md) + +使用自定义 AI 模型或第三方 OpenAI 兼容 API： +- 自定义 DeepSeek 端点 +- 本地部署的模型 +- 其他 LLM 提供商 + +--- + +## 🔑 环境要求 + +开始之前，请确保已安装： + +### Docker 方式： +- ✅ Docker 20.10+ +- ✅ Docker Compose V2 + +### 手动部署方式： +- ✅ Go 1.21+ +- ✅ Node.js 18+ +- ✅ TA-Lib 库 +- ✅ PM2（可选） + +--- + +## 📚 下一步 + +部署完成后： + +1. **配置 AI 模型** → 访问 Web 界面 http://localhost:3000 +2. **设置交易所** → 添加 Binance/Hyperliquid 凭证 +3. **创建交易员** → 将 AI 模型与交易所结合 +4. **开始交易** → 在仪表板中监控表现 + +--- + +## ⚠️ 重要提示 + +**交易前：** +- ⚠️ 先在测试网测试 +- ⚠️ 从小金额开始 +- ⚠️ 了解风险 +- ⚠️ 阅读[安全策略](../../SECURITY.md) + +**API 密钥：** +- 🔑 永远不要提交 API 密钥到 git +- 🔑 使用环境变量 +- 🔑 限制 IP 访问 +- 🔑 在交易所启用 2FA + +--- + +## 🆘 故障排除 + +**常见问题：** + +1. **Docker 构建失败** → 检查 Docker 版本，更新到 20.10+ +2. **找不到 TA-Lib** → `brew install ta-lib` (macOS) 或 `apt-get install libta-lib0-dev` (Ubuntu) +3. **端口 8080 被占用** → 在 .env 文件中更改 `API_PORT` +4. **前端无法连接** → 检查后端是否在端口 8080 上运行 + +**需要更多帮助？** +- 📖 [常见问题](../guides/faq.zh-CN.md) +- 💬 [Telegram 社区](https://t.me/nofx_dev_community) +- 🐛 [GitHub Issues](https://github.com/tinkle-community/nofx/issues) + +--- + +[← 返回文档首页](../README.md) diff --git a/docs/getting-started/custom-api.en.md b/docs/getting-started/custom-api.en.md new file mode 100644 index 00000000..44c8a05c --- /dev/null +++ b/docs/getting-started/custom-api.en.md @@ -0,0 +1,207 @@ +# Custom AI API Usage Guide + +## Features + +NOFX now supports using any OpenAI-compatible API format, including: +- OpenAI official API (gpt-4o, gpt-4-turbo, etc.) +- OpenRouter (access to multiple models) +- Locally deployed models (Ollama, LM Studio, etc.) +- Other OpenAI-compatible API services + +## Configuration Method + +~~Add trader using custom API in `config.json` (deprecated):~~ + +*Note: Custom APIs and traders are now configured through the Web interface. config.json only retains basic settings.* + +```json +{ + "traders": [ + { + "id": "trader_custom", + "name": "My Custom AI Trader", + "ai_model": "custom", + "exchange": "binance", + + "binance_api_key": "your_binance_api_key", + "binance_secret_key": "your_binance_secret_key", + + "custom_api_url": "https://api.openai.com/v1", + "custom_api_key": "sk-your-openai-api-key", + "custom_model_name": "gpt-4o", + + "initial_balance": 1000, + "scan_interval_minutes": 3 + } + ] +} +``` + +## Configuration Fields + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `ai_model` | string | ✅ | Set to `"custom"` to enable custom API | +| `custom_api_url` | string | ✅ | API Base URL (without `/chat/completions`). Special usage: If ending with `#`, use full URL (no auto path append) | +| `custom_api_key` | string | ✅ | API key | +| `custom_model_name` | string | ✅ | Model name (e.g. `gpt-4o`, `claude-3-5-sonnet`, etc.) | + +## Usage Examples + +### 1. OpenAI Official API + +```json +{ + "ai_model": "custom", + "custom_api_url": "https://api.openai.com/v1", + "custom_api_key": "sk-proj-xxxxx", + "custom_model_name": "gpt-4o" +} +``` + +### 2. OpenRouter + +```json +{ + "ai_model": "custom", + "custom_api_url": "https://openrouter.ai/api/v1", + "custom_api_key": "sk-or-xxxxx", + "custom_model_name": "anthropic/claude-3.5-sonnet" +} +``` + +### 3. Local Ollama + +```json +{ + "ai_model": "custom", + "custom_api_url": "http://localhost:11434/v1", + "custom_api_key": "ollama", + "custom_model_name": "llama3.1:70b" +} +``` + +### 4. Azure OpenAI + +```json +{ + "ai_model": "custom", + "custom_api_url": "https://your-resource.openai.azure.com/openai/deployments/your-deployment", + "custom_api_key": "your-azure-api-key", + "custom_model_name": "gpt-4" +} +``` + +### 5. Using Full Custom Path (append #) + +For certain special API endpoints that already include the full path (including `/chat/completions` or other custom paths), you can append `#` at the end of the URL to force using the full URL: + +```json +{ + "ai_model": "custom", + "custom_api_url": "https://api.example.com/v2/ai/chat/completions#", + "custom_api_key": "your-api-key", + "custom_model_name": "custom-model" +} +``` + +**Note**: The `#` will be automatically removed, and the actual request will be sent to `https://api.example.com/v2/ai/chat/completions` + +## Compatibility Requirements + +Custom APIs must: +1. Support OpenAI Chat Completions format +2. Accept `POST` requests to `/chat/completions` endpoint (or append `#` at URL end for custom path) +3. Support `Authorization: Bearer {api_key}` authentication +4. Return standard OpenAI response format + +## Important Notes + +1. **URL Format**: `custom_api_url` should be the Base URL, system will auto-append `/chat/completions` + - ✅ Correct: `https://api.openai.com/v1` + - ❌ Wrong: `https://api.openai.com/v1/chat/completions` + - 🔧 **Special usage**: If you need to use a full custom path (without auto-appending `/chat/completions`), append `#` at the URL end + - Example: `https://api.example.com/custom/path/chat/completions#` + - System will automatically remove `#` and use the full URL directly + +2. **Model Name**: Ensure `custom_model_name` exactly matches the model name supported by your API provider + +3. **API Key**: Some locally deployed models may not require a real API key, you can fill in any string + +4. **Timeout Settings**: Default timeout is 120 seconds, may need adjustment if model response is slow + +## Multi-AI Comparison Trading + +You can configure multiple traders with different AIs for comparison: + +```json +{ + "traders": [ + { + "id": "deepseek_trader", + "ai_model": "deepseek", + "deepseek_key": "sk-xxxxx", + ... + }, + { + "id": "gpt4_trader", + "ai_model": "custom", + "custom_api_url": "https://api.openai.com/v1", + "custom_api_key": "sk-xxxxx", + "custom_model_name": "gpt-4o", + ... + }, + { + "id": "claude_trader", + "ai_model": "custom", + "custom_api_url": "https://openrouter.ai/api/v1", + "custom_api_key": "sk-or-xxxxx", + "custom_model_name": "anthropic/claude-3.5-sonnet", + ... + } + ] +} +``` + +## Troubleshooting + +### Issue: Configuration Validation Failed + +**Error Message**: `使用自定义API时必须配置custom_api_url` (custom_api_url must be configured when using custom API) + +**Solution**: After setting `ai_model: "custom"`, ensure you also configure: +- `custom_api_url` +- `custom_api_key` +- `custom_model_name` + +### Issue: API Call Failed + +**Possible Causes**: +1. URL format error + - Normal usage: Should not include `/chat/completions` (system will auto-append) + - Special usage: If full path is needed, remember to append `#` at URL end +2. Invalid API key +3. Incorrect model name +4. Network connection issues + +**Debug Method**: Check error messages in logs, usually includes HTTP status code and error details + +## Backward Compatibility + +Existing `deepseek` and `qwen` configurations are unaffected and can continue to be used: + +```json +{ + "ai_model": "deepseek", + "deepseek_key": "sk-xxxxx" +} +``` + +Or + +```json +{ + "ai_model": "qwen", + "qwen_key": "sk-xxxxx" +} +``` diff --git a/CUSTOM_API.md b/docs/getting-started/custom-api.md similarity index 100% rename from CUSTOM_API.md rename to docs/getting-started/custom-api.md diff --git a/DOCKER_DEPLOY.en.md b/docs/getting-started/docker-deploy.en.md similarity index 100% rename from DOCKER_DEPLOY.en.md rename to docs/getting-started/docker-deploy.en.md diff --git a/DOCKER_DEPLOY.md b/docs/getting-started/docker-deploy.zh-CN.md similarity index 100% rename from DOCKER_DEPLOY.md rename to docs/getting-started/docker-deploy.zh-CN.md diff --git a/docs/getting-started/pm2-deploy.en.md b/docs/getting-started/pm2-deploy.en.md new file mode 100644 index 00000000..428bef88 --- /dev/null +++ b/docs/getting-started/pm2-deploy.en.md @@ -0,0 +1,303 @@ +# NoFX Trading Bot - PM2 Deployment Guide + +Complete guide for local development and production deployment using PM2. + +## 🚀 Quick Start + +### 1. Install PM2 + +```bash +npm install -g pm2 +``` + +### 2. One-Command Launch + +```bash +./pm2.sh start +``` + +That's it! Frontend and backend will start automatically. + +--- + +## 📋 All Commands + +### Service Management + +```bash +# Start services +./pm2.sh start + +# Stop services +./pm2.sh stop + +# Restart services +./pm2.sh restart + +# View status +./pm2.sh status + +# Delete services +./pm2.sh delete +``` + +### Log Viewing + +```bash +# View all logs (live) +./pm2.sh logs + +# Backend logs only +./pm2.sh logs backend + +# Frontend logs only +./pm2.sh logs frontend +``` + +### Build & Compile + +```bash +# Compile backend +./pm2.sh build + +# Recompile backend and restart +./pm2.sh rebuild +``` + +### Monitoring + +```bash +# Open PM2 monitoring dashboard (real-time CPU/Memory) +./pm2.sh monitor +``` + +--- + +## 📊 Access URLs + +After successful startup: + +- **Frontend Web Interface**: http://localhost:3000 +- **Backend API**: http://localhost:8080 +- **Health Check**: http://localhost:8080/api/health + +--- + +## 🔧 Configuration Files + +### pm2.config.js + +PM2 configuration file, defines frontend and backend startup parameters: + +```javascript +const path = require('path'); + +module.exports = { + apps: [ + { + name: 'nofx-backend', + script: './nofx', // Go binary + cwd: __dirname, // Dynamically get current directory + autorestart: true, + max_memory_restart: '500M' + }, + { + name: 'nofx-frontend', + script: 'npm', + args: 'run dev', // Vite dev server + cwd: path.join(__dirname, 'web'), // Dynamically join path + autorestart: true, + max_memory_restart: '300M' + } + ] +}; +``` + +**After modifying configuration, restart is required:** +```bash +./pm2.sh restart +``` + +--- + +## 📝 Log File Locations + +- **Backend Logs**: `./logs/backend-error.log` and `./logs/backend-out.log` +- **Frontend Logs**: `./web/logs/frontend-error.log` and `./web/logs/frontend-out.log` + +--- + +## 🔄 Startup on Boot + +Set PM2 to start on boot: + +```bash +# 1. Start services +./pm2.sh start + +# 2. Save current process list +pm2 save + +# 3. Generate startup script +pm2 startup + +# 4. Follow the instructions to execute command (requires sudo) +``` + +**Disable startup on boot:** +```bash +pm2 unstartup +``` + +--- + +## 🛠️ Common Operations + +### Restart After Code Changes + +**Backend changes:** +```bash +./pm2.sh rebuild # Auto compile and restart +``` + +**Frontend changes:** +```bash +./pm2.sh restart # Vite will auto hot-reload, no restart needed +``` + +### View Real-time Resource Usage + +```bash +./pm2.sh monitor +``` + +### View Detailed Information + +```bash +pm2 info nofx-backend # Backend details +pm2 info nofx-frontend # Frontend details +``` + +### Clear Logs + +```bash +pm2 flush +``` + +--- + +## 🐛 Troubleshooting + +### Service Startup Failed + +```bash +# 1. View detailed errors +./pm2.sh logs + +# 2. Check port usage +lsof -i :8080 # Backend port +lsof -i :3000 # Frontend port + +# 3. Manual compile test +go build -o nofx +./nofx +``` + +### Backend Won't Start + +```bash +# ~~Check if config.json exists~~ +# ~~ls -l config.json~~ + +# Check if database file exists +ls -l trading.db + +# Check permissions +chmod +x nofx + +# Run manually to see errors +./nofx +``` + +### Frontend Not Accessible + +```bash +# Check node_modules +cd web && npm install + +# Manual start test +npm run dev +``` + +--- + +## 🎯 Production Environment Recommendations + +### 1. Use Production Mode + +Modify `pm2.config.js`: + +```javascript +{ + name: 'nofx-frontend', + script: 'npm', + args: 'run preview', // Change to preview (requires npm run build first) + env: { + NODE_ENV: 'production' + } +} +``` + +### 2. Increase Instances (Load Balancing) + +```javascript +{ + name: 'nofx-backend', + script: './nofx', + instances: 2, // Start 2 instances + exec_mode: 'cluster' +} +``` + +### 3. Auto Restart Strategy + +```javascript +{ + autorestart: true, + max_restarts: 10, + min_uptime: '10s', + max_memory_restart: '500M' +} +``` + +--- + +## 📦 Comparison with Docker Deployment + +| Feature | PM2 Deployment | Docker Deployment | +|---------|---------------|-------------------| +| Startup Speed | ⚡ Fast | 🐌 Slower | +| Resource Usage | 💚 Low | 🟡 Medium | +| Isolation | 🟡 Medium | 💚 High | +| Use Case | Dev/Single-machine | Production/Cluster | +| Configuration Complexity | 💚 Simple | 🟡 Medium | + +**Recommendations:** +- **Development Environment**: Use `./pm2.sh` +- **Production Environment**: Use `./start.sh` (Docker) + +--- + +## 🆘 Getting Help + +```bash +./pm2.sh help +``` + +Or check PM2 official documentation: https://pm2.keymetrics.io/ + +--- + +## 📄 License + +MIT diff --git a/PM2_DEPLOYMENT.md b/docs/getting-started/pm2-deploy.md similarity index 100% rename from PM2_DEPLOYMENT.md rename to docs/getting-started/pm2-deploy.md diff --git a/docs/guides/README.md b/docs/guides/README.md new file mode 100644 index 00000000..9b5e72b1 --- /dev/null +++ b/docs/guides/README.md @@ -0,0 +1,138 @@ +# 📘 NOFX User Guides + +**Language:** [English](README.md) | [中文](README.zh-CN.md) + +Comprehensive guides to help you use NOFX effectively. + +--- + +## 📚 Available Guides + +### 🔧 Basic Usage + +| Guide | Description | Status | +|-------|-------------|--------| +| [FAQ (English)](faq.en.md) | Frequently asked questions | ✅ Available | +| [FAQ (中文)](faq.zh-CN.md) | 常见问题解答 | ✅ Available | +| Configuration Guide | Advanced settings and options | 🚧 Coming Soon | +| Trading Strategies | AI trading strategy examples | 🚧 Coming Soon | + +--- + +## 🐛 Troubleshooting + +### Common Issues + +**Issue: TA-Lib not found** +```bash +# macOS +brew install ta-lib + +# Ubuntu/Debian +sudo apt-get install libta-lib0-dev +``` + +**Issue: Precision error** +- System auto-handles LOT_SIZE from exchange +- Check network connection +- Verify exchange API is accessible + +**Issue: AI API timeout** +- Check API key validity +- Verify network connection +- Check API balance/credits +- Timeout is set to 120 seconds + +**Issue: Frontend can't connect** +- Ensure backend is running (http://localhost:8080) +- Check if port 8080 is available +- Check browser console for errors + +--- + +## 📖 Usage Tips + +### Best Practices + +**1. Risk Management** +- Start with small amounts (100-500 USDT) +- Use subaccounts for additional safety +- Set reasonable leverage limits +- Monitor daily loss limits + +**2. Performance Monitoring** +- Check decision logs regularly +- Analyze win rate and profit factor +- Review AI reasoning (Chain of Thought) +- Track equity curve trends + +**3. Configuration** +- Test on testnet first +- Gradually increase trading amounts +- Adjust scan intervals (3-5 minutes recommended) +- Use default coin list for beginners + +--- + +## 🎯 Advanced Topics + +### Multi-Trader Competition +Run multiple AI models simultaneously: +- Qwen vs DeepSeek head-to-head +- Compare performance in real-time +- Identify best-performing strategies + +### Custom Coin Pools +- Use external API for coin selection +- Combine AI500 + OI Top data +- Filter by liquidity and volume + +### Exchange Integration +- Binance Futures (CEX) +- Hyperliquid (DEX) +- Aster DEX (Binance-compatible) + +--- + +## 📊 Understanding Metrics + +### Key Performance Indicators + +**Win Rate** +- Percentage of profitable trades +- Target: >50% for consistent profit + +**Profit Factor** +- Ratio of gross profit to gross loss +- Target: >1.5 (1.5:1 or better) + +**Sharpe Ratio** +- Risk-adjusted return measure +- Higher is better (>1.0 is good) + +**Maximum Drawdown** +- Largest peak-to-trough decline +- Keep under 20% for safety + +--- + +## 🔗 Related Documentation + +- [Getting Started (EN)](../getting-started/README.md) - Initial setup +- [Getting Started (中文)](../getting-started/README.zh-CN.md) - 初始设置 +- [Community](../community/README.md) - Contributing and bounties +- [FAQ (English)](faq.en.md) - Common questions +- [FAQ (中文)](faq.zh-CN.md) - 常见问题 + +--- + +## 🆘 Need Help? + +**Can't find what you need?** +- 💬 [Telegram Community](https://t.me/nofx_dev_community) +- 🐛 [GitHub Issues](https://github.com/tinkle-community/nofx/issues) +- 🐦 [Twitter @nofx_ai](https://x.com/nofx_ai) + +--- + +[← Back to Documentation Home](../README.md) diff --git a/docs/guides/README.zh-CN.md b/docs/guides/README.zh-CN.md new file mode 100644 index 00000000..2e358f6b --- /dev/null +++ b/docs/guides/README.zh-CN.md @@ -0,0 +1,137 @@ +# 📘 NOFX 使用指南 + +**语言:** [English](README.md) | [中文](README.zh-CN.md) + +帮助您有效使用 NOFX 的综合指南。 + +--- + +## 📚 可用指南 + +### 🔧 基础使用 + +| 指南 | 描述 | 状态 | +|------|------|------| +| [FAQ (中文)](faq.zh-CN.md) | 常见问题解答 | ✅ 可用 | +| [FAQ (English)](faq.en.md) | Frequently asked questions | ✅ 可用 | +| 配置指南 | 高级设置和选项 | 🚧 即将推出 | +| 交易策略 | AI 交易策略示例 | 🚧 即将推出 | + +--- + +## 🐛 故障排除 + +### 常见问题 + +**问题：找不到 TA-Lib** +```bash +# macOS +brew install ta-lib + +# Ubuntu/Debian +sudo apt-get install libta-lib0-dev +``` + +**问题：精度错误** +- 系统自动处理交易所的 LOT_SIZE +- 检查网络连接 +- 验证交易所 API 可访问 + +**问题：AI API 超时** +- 检查 API 密钥有效性 +- 验证网络连接 +- 检查 API 余额/额度 +- 超时设置为 120 秒 + +**问题：前端无法连接** +- 确保后端正在运行 (http://localhost:8080) +- 检查端口 8080 是否可用 +- 检查浏览器控制台错误 + +--- + +## 📖 使用技巧 + +### 最佳实践 + +**1. 风险管理** +- 从小金额开始（100-500 USDT） +- 使用子账户增加安全性 +- 设置合理的杠杆限制 +- 监控每日亏损限制 + +**2. 性能监控** +- 定期检查决策日志 +- 分析胜率和盈利因子 +- 审查 AI 推理（思维链） +- 跟踪权益曲线趋势 + +**3. 配置** +- 先在测试网测试 +- 逐步增加交易金额 +- 调整扫描间隔（推荐 3-5 分钟） +- 初学者使用默认币种列表 + +--- + +## 🎯 进阶主题 + +### 多交易员竞赛 +同时运行多个 AI 模型： +- Qwen vs DeepSeek 对决 +- 实时比较性能 +- 识别表现最佳的策略 + +### 自定义币种池 +- 使用外部 API 进行币种选择 +- 结合 AI500 + OI Top 数据 +- 按流动性和交易量过滤 + +### 交易所集成 +- Binance Futures（中心化交易所） +- Hyperliquid（去中心化交易所） +- Aster DEX（兼容 Binance） + +--- + +## 📊 理解指标 + +### 关键性能指标 + +**胜率（Win Rate）** +- 盈利交易的百分比 +- 目标：>50% 以获得稳定盈利 + +**盈利因子（Profit Factor）** +- 总盈利与总亏损的比率 +- 目标：>1.5（1.5:1 或更好） + +**夏普比率（Sharpe Ratio）** +- 风险调整后的收益衡量 +- 越高越好（>1.0 为良好） + +**最大回撤（Maximum Drawdown）** +- 从峰值到谷值的最大跌幅 +- 为安全起见保持在 20% 以下 + +--- + +## 🔗 相关文档 + +- [快速开始](../getting-started/README.zh-CN.md) - 初始设置 +- [社区](../community/README.md) - 贡献和悬赏 +- [FAQ 中文](faq.zh-CN.md) - 常见问题 +- [FAQ English](faq.en.md) - Common questions + +--- + +## 🆘 需要帮助？ + +**找不到您需要的内容？** +- 💬 [Telegram 社区](https://t.me/nofx_dev_community) +- 🐛 [GitHub Issues](https://github.com/tinkle-community/nofx/issues) +- 🐦 [Twitter @nofx_ai](https://x.com/nofx_ai) + +--- + +[← 返回文档首页](../README.md) diff --git a/docs/guides/faq.en.md b/docs/guides/faq.en.md new file mode 100644 index 00000000..7b31142d --- /dev/null +++ b/docs/guides/faq.en.md @@ -0,0 +1,25 @@ +# Frequently Asked Questions + +## Binance Position Mode Error (code=-4061) + +**Error Message**: `Order's position side does not match user's setting` + +**Cause**: The system requires Hedge Mode (dual position), but your Binance account is set to One-way Mode. + +### Solution + +1. Login to [Binance Futures Trading Platform](https://www.binance.com/en/futures/BTCUSDT) + +2. Click **⚙️ Preferences** in the top right corner + +3. Select **Position Mode** + +4. Switch to **Hedge Mode** (Dual Position) + +5. Confirm the change + +**Note**: You must close all open positions before switching modes. + +--- + +For more issues, check [GitHub Issues](https://github.com/tinkle-community/nofx/issues) diff --git a/常见问题.md b/docs/guides/faq.zh-CN.md similarity index 100% rename from 常见问题.md rename to docs/guides/faq.zh-CN.md diff --git a/docs/i18n/README.md b/docs/i18n/README.md new file mode 100644 index 00000000..7668cfb6 --- /dev/null +++ b/docs/i18n/README.md @@ -0,0 +1,231 @@ +# 🌍 International Documentation / 国际化文档 + +NOFX documentation is available in multiple languages. + +NOFX 文档提供多种语言版本。 + +--- + +## 📚 Available Languages / 可用语言 + +| Language | Main README | Status | Maintainers | +|----------|-------------|--------|-------------| +| 🇬🇧 **English** | [README.md](../../README.md) | ✅ Complete | Core Team | +| 🇨🇳 **Chinese (中文)** | [README.md](zh-CN/README.md) | ✅ Complete | Community | +| 🇷🇺 **Russian (Русский)** | [README.md](ru/README.md) | ✅ Complete | Community | +| 🇺🇦 **Ukrainian (Українська)** | [README.md](uk/README.md) | ✅ Complete | Community | + +--- + +## 🔗 Quick Access / 快速访问 + +### English 🇬🇧 +- **Main README:** [../../README.md](../../README.md) +- **Contributing:** [../../CONTRIBUTING.md](../../CONTRIBUTING.md) +- **Security:** [../../SECURITY.md](../../SECURITY.md) + +### 中文 🇨🇳 +- **主 README:** [zh-CN/README.md](zh-CN/README.md) +- **贡献指南:** [../../CONTRIBUTING.md](../../CONTRIBUTING.md#中文) +- **安全政策:** [../../SECURITY.md](../../SECURITY.md#中文) +- **常见问题:** [../guides/faq.zh-CN.md](../guides/faq.zh-CN.md) + +### Русский 🇷🇺 +- **Основной README:** [ru/README.md](ru/README.md) +- **Руководство по участию:** [../../CONTRIBUTING.md](../../CONTRIBUTING.md) +- **Политика безопасности:** [../../SECURITY.md](../../SECURITY.md) + +### Українська 🇺🇦 +- **Головний README:** [uk/README.md](uk/README.md) +- **Посібник із внесків:** [../../CONTRIBUTING.md](../../CONTRIBUTING.md) +- **Політика безпеки:** [../../SECURITY.md](../../SECURITY.md) + +--- + +## 🤝 Help with Translations / 帮助翻译 + +### Want to Contribute Translations? / 想要贡献翻译？ + +We welcome translation contributions! / 我们欢迎翻译贡献！ + +**What needs translation? / 需要翻译什么？** +- ✅ Main README (complete for 4 languages) +- 🚧 Deployment guides (partial) +- 📋 User guides (needed) +- 📋 Contributing guide (needed for RU/UK) + +**How to contribute translations? / 如何贡献翻译？** + +1. **Check existing translations / 检查现有翻译** + - Browse this directory + - See what's missing + +2. **Claim a translation task / 认领翻译任务** + - Open a GitHub Issue + - Title: `[TRANSLATION] Document name to Language` + - Example: `[TRANSLATION] CONTRIBUTING.md to Chinese` + +3. **Submit translation / 提交翻译** + - Follow [Contributing Guide](../../CONTRIBUTING.md) + - Place file in appropriate language folder + - Keep formatting and structure consistent + +4. **Get recognized / 获得认可** + - Listed as translator in credits + - Eligible for contributor badges + - Possible bounty rewards ($50-200) + +--- + +## 📝 Translation Guidelines / 翻译指南 + +### File Naming Convention / 文件命名规范 + +**Pattern:** `document-name.{language-code}.md` + +**Examples:** +``` +README.md → en (default) +docker-deploy.zh-CN.md → Chinese +docker-deploy.ru.md → Russian +faq.zh-CN.md → Chinese FAQ +``` + +**Language Codes:** +- `en` - English (default, no suffix needed) +- `zh-CN` - Simplified Chinese +- `ru` - Russian +- `uk` - Ukrainian +- `ja` - Japanese *(future)* +- `ko` - Korean *(future)* + +### Quality Standards / 质量标准 + +**Must have / 必须具备:** +- ✅ Accurate technical terms +- ✅ Natural, fluent language +- ✅ Consistent terminology +- ✅ Preserved formatting (markdown) +- ✅ Working internal links + +**Avoid / 避免:** +- ❌ Machine translation without review +- ❌ Inconsistent terminology +- ❌ Broken links or formatting +- ❌ Cultural insensitivity + +### Technical Terms / 技术术语 + +**Keep in English (don't translate):** +- API, HTTP, REST, JSON +- Docker, Kubernetes +- GitHub, Git, Pull Request +- Specific tool names (Binance, Hyperliquid) + +**Example - Chinese:** +- ✅ "启动 Docker 容器" (start Docker container) +- ❌ "启动 多克 容器" (transliterated Docker) + +--- + +## 🌐 Request a New Language / 请求新语言 + +### Want NOFX in your language? / 希望 NOFX 支持你的语言？ + +**Steps / 步骤:** + +1. **Check if it's planned / 检查是否已计划** + - See list below + - Search GitHub Issues + +2. **Create a request / 创建请求** + - Open GitHub Issue + - Title: `[TRANSLATION REQUEST] Language name` + - Explain: Number of potential users, your willingness to help + +3. **Volunteer to help / 志愿帮助** + - Offer to translate + - Find other speakers to review + - Commit to maintaining updates + +### Planned Languages / 计划中的语言 + +| Language | Status | Need Volunteers? | +|----------|--------|------------------| +| 🇯🇵 Japanese | 📋 Planned | ✅ Yes | +| 🇰🇷 Korean | 📋 Planned | ✅ Yes | +| 🇪🇸 Spanish | 📋 Planned | ✅ Yes | +| 🇫🇷 French | 📋 Planned | ✅ Yes | +| 🇩🇪 German | 📋 Planned | ✅ Yes | + +--- + +## 👥 Translation Team / 翻译团队 + +### Current Translators / 当前翻译者 + +| Language | Translators | Status | +|----------|-------------|--------| +| 🇨🇳 Chinese | Community | Active | +| 🇷🇺 Russian | Community | Active | +| 🇺🇦 Ukrainian | Community | Active | + +**Want to join the team? / 想加入团队？** +- Contact on [Telegram](https://t.me/nofx_dev_community) +- Open an issue on GitHub +- DM [@nofx_ai](https://x.com/nofx_ai) on Twitter + +--- + +## 📊 Translation Progress / 翻译进度 + +### Document Coverage / 文档覆盖率 + +| Document | EN | 中文 | РУ | УК | +|----------|----|----|----|----| +| Main README | ✅ | ✅ | ✅ | ✅ | +| CONTRIBUTING | ✅ | ✅ | 🚧 | 🚧 | +| CODE_OF_CONDUCT | ✅ | ✅ | 🚧 | 🚧 | +| SECURITY | ✅ | ✅ | 🚧 | 🚧 | +| Docker Deploy | ✅ | ✅ | ❌ | ❌ | +| FAQ | ✅ | ✅ | ❌ | ❌ | + +**Legend / 图例:** +- ✅ Complete / 完成 +- 🚧 In Progress / 进行中 +- ❌ Not Started / 未开始 + +--- + +## 🎯 Priority Translations / 优先翻译 + +**High Priority / 高优先级:** +1. CONTRIBUTING.md (all languages) +2. Docker deployment guides +3. FAQ sections + +**Medium Priority / 中优先级:** +1. User guides +2. Troubleshooting docs +3. API reference + +**Low Priority / 低优先级:** +1. Architecture docs (technical, less urgent) +2. Advanced configuration guides + +--- + +## 🆘 Translation Help / 翻译帮助 + +**Questions? / 有问题？** +- 💬 Ask in [Telegram Community](https://t.me/nofx_dev_community) +- 🐙 Open a [GitHub Issue](https://github.com/tinkle-community/nofx/issues) +- 📧 Contact maintainers + +**Resources / 资源:** +- [Contributing Guide](../../CONTRIBUTING.md) - How to submit +- [Markdown Guide](https://www.markdownguide.org/) - Formatting reference + +--- + +[← Back to Documentation Home](../README.md) diff --git a/README.ru.md b/docs/i18n/ru/README.md similarity index 66% rename from README.ru.md rename to docs/i18n/ru/README.md index 2d2e6ff3..2feaa824 100644 --- a/README.ru.md +++ b/docs/i18n/ru/README.md @@ -6,10 +6,29 @@ [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Backed by Amber.ac](https://img.shields.io/badge/Backed%20by-Amber.ac-orange.svg)](https://amber.ac) -**Языки / Languages:** [English](README.md) | [中文](README.zh-CN.md) | [Українська](README.uk.md) | [Русский](README.ru.md) +**Языки / Languages:** [English](../../../README.md) | [中文](../zh-CN/README.md) | [Українська](../uk/README.md) | [Русский](../ru/README.md) **Официальный Twitter:** [@nofx_ai](https://x.com/nofx_ai) +**📚 Документация:** [Главная](../../README.md) | [Начало работы](../../getting-started/README.md) | [Журнал изменений](../../../CHANGELOG.zh-CN.md) | [Сообщество](../../community/README.md) + +--- + +## 📑 Содержание + +- [🚀 Универсальная AI Торговая Операционная Система](#-универсальная-ai-торговая-операционная-система) +- [👥 Сообщество Разработчиков](#-сообщество-разработчиков) +- [🆕 Что Нового](#-что-нового) +- [📸 Скриншоты](#-скриншоты) +- [✨ Текущая Реализация - Криптовалютные Рынки](#-текущая-реализация---криптовалютные-рынки) +- [🔮 Дорожная Карта](#-дорожная-карта---расширение-на-универсальные-рынки) +- [🏗️ Техническая Архитектура](#️-техническая-архитектура) +- [🚀 Быстрый Старт](#-быстрый-старт) +- [📊 Функции Web-интерфейса](#-функции-web-интерфейса) +- [⚠️ Важные Предупреждения о Рисках](#️-важные-предупреждения-о-рисках) +- [🛠️ Общие Проблемы](#️-общие-проблемы) +- [🔄 Журнал Изменений](#-журнал-изменений) + --- ## 🚀 Универсальная AI Торговая Операционная Система @@ -74,7 +93,7 @@ NOFX теперь поддерживает **три основные биржи* **Быстрый старт:** 1. Получите приватный ключ MetaMask (удалите префикс `0x`) -2. Установите `"exchange": "hyperliquid"` в config.json +2. ~~Установите `"exchange": "hyperliquid"` в config.json~~ *Настройте через веб-интерфейс* 3. Добавьте `"hyperliquid_private_key": "your_key"` 4. Начните торговать! @@ -109,15 +128,19 @@ NOFX теперь поддерживает **три основные биржи* ## 📸 Скриншоты ### 🏆 Режим конкуренции - Битва AI в реальном времени -![Страница конкуренции](screenshots/competition-page.png) +![Страница конкуренции](../../../screenshots/competition-page.png) *Лидерборд с несколькими AI и графики сравнения производительности в реальном времени показывают битву Qwen против DeepSeek* ### 📊 Детали трейдера - Полная торговая панель -![Страница деталей](screenshots/details-page.png) +![Страница деталей](../../../screenshots/details-page.png) *Профессиональный торговый интерфейс с кривыми капитала, живыми позициями и логами решений AI с раскрываемыми входными промптами и цепочкой рассуждений* --- +> 📘 **Примечание**: Это упрощенная русская версия README. Для получения полной технической документации, включая архитектуру системы, API-интерфейсы и расширенные конфигурации, см. [Английскую версию](../../../README.md) или [Китайскую версию](../zh-CN/README.md). + +--- + ## ✨ Основные возможности ### 🏆 Режим конкуренции нескольких AI @@ -173,6 +196,55 @@ NOFX теперь поддерживает **три основные биржи* --- +## 🔮 Дорожная Карта - Расширение на Универсальные Рынки + +Миссия NOFX - стать **Универсальной AI Торговой Операционной Системой** для всех финансовых рынков. + +**Видение:** Та же архитектура. Та же агентная структура. Все рынки. + +**Расширение на Рынки:** +- 📈 **Фондовые Рынки**: Акции США, A-акции, Гонконгская биржа +- 📊 **Рынки Фьючерсов**: Товарные фьючерсы, индексные фьючерсы +- 🎯 **Опционная Торговля**: Опционы на акции, крипто опционы +- 💱 **Рынки Форекс**: Основные валютные пары, кросс-курсы + +**Предстоящие Функции:** +- Расширенные AI возможности (GPT-4, Claude 3, Gemini Pro, гибкие шаблоны промптов) +- Новые интеграции бирж (OKX, Bybit, Lighter, EdgeX + CEX/Perp-DEX) +- Рефакторинг структуры проекта (высокая связность, низкая связанность, принципы SOLID) +- Улучшения безопасности (AES-256 шифрование API ключей, RBAC, улучшения 2FA) +- Улучшения пользовательского опыта (мобильный интерфейс, графики TradingView, система оповещений) + +📖 **Для подробной дорожной карты и сроков см.:** +- **English:** [Roadmap Documentation](../../roadmap/README.md) +- **中文:** [路线图文档](../../roadmap/README.zh-CN.md) + +--- + +## 🏗️ Техническая Архитектура + +NOFX построен на современной модульной архитектуре: + +- **Backend:** Go с фреймворком Gin, база данных SQLite +- **Frontend:** React 18 + TypeScript + Vite + TailwindCSS +- **Поддержка Бирж:** Binance, Hyperliquid, Aster DEX +- **Интеграция AI:** DeepSeek, Qwen и пользовательские OpenAI-совместимые API +- **Управление Состоянием:** Zustand для фронтенда, на основе базы данных для бэкенда +- **Обновления в Реальном Времени:** SWR с интервалами опроса 5-10 секунд + +**Ключевые Особенности:** +- 🗄️ Конфигурация на основе базы данных (больше никакого редактирования JSON) +- 🔐 JWT аутентификация с опциональной поддержкой 2FA +- 📊 Отслеживание производительности и аналитика в реальном времени +- 🤖 Режим конкуренции Multi-AI с живым сравнением +- 🔌 RESTful API для всех настроек и мониторинга + +📖 **Для подробной документации по архитектуре см.:** +- **Русский:** [Документация по Архитектуре](../../architecture/README.md) +- **中文:** [架构文档](../../architecture/README.zh-CN.md) + +--- + ## 💰 Регистрация аккаунта Binance (Экономьте на комиссиях!) Перед использованием этой системы вам нужен аккаунт Binance Futures. **Используйте нашу реферальную ссылку для получения скидки на комиссии:** @@ -824,103 +896,73 @@ curl http://localhost:8080/api/health Каждый цикл принятия решений (по умолчанию 3 минуты), система работает по следующему процессу: -``` -┌──────────────────────────────────────────────────────────┐ -│ 1. 📊 Анализ исторической производительности │ -│ (последние 20 циклов) │ -├──────────────────────────────────────────────────────────┤ -│ ✓ Расчет общего процента выигрышей, средней прибыли, │ -│ соотношения прибыли/убытка │ -│ ✓ Статистика по каждой монете (процент выигрышей, │ -│ средний P/L в USDT) │ -│ ✓ Определение лучших/худших монет по производительности │ -│ ✓ Список деталей последних 5 сделок с точным P/L │ -│ ✓ Расчет коэффициента Шарпа для оценки риска │ -│ 📌 НОВОЕ (v2.0.2): Точный P/L в USDT с учетом плеча │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 2. 💰 Получение состояния аккаунта │ -├──────────────────────────────────────────────────────────┤ -│ • Капитал аккаунта, доступный баланс, нереализованный │ -│ P/L │ -│ • Количество позиций, общий P/L (реализованный + │ -│ нереализованный) │ -│ • Использование маржи (текущее/максимальное) │ -│ • Индикаторы оценки риска │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 3. 🔍 Анализ существующих позиций (если есть) │ -├──────────────────────────────────────────────────────────┤ -│ • Получение рыночных данных для каждой позиции │ -│ (3-минутные + 4-часовые свечи) │ -│ • Расчет технических индикаторов (RSI, MACD, EMA) │ -│ • Отображение длительности удержания позиции │ -│ (например, "удерживается 2 часа 15 минут") │ -│ • AI определяет, нужно ли закрыть (тейк-профит, │ -│ стоп-лосс или корректировка) │ -│ 📌 НОВОЕ (v2.0.2): Отслеживание длительности позиции │ -│ помогает AI решать │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 4. 🎯 Оценка новых возможностей (пул кандидатов монет) │ -├──────────────────────────────────────────────────────────┤ -│ • Получение топ-20 монет с высоким рейтингом AI500 │ -│ • Получение топ-20 монет с самым быстрым ростом OI │ -│ • Объединение, удаление дубликатов, фильтрация монет с │ -│ низкой ликвидностью (OI < 15M USD) │ -│ • Массовое получение рыночных данных и технических │ -│ индикаторов │ -│ • Подготовка полных последовательностей сырых данных │ -│ для каждой монеты-кандидата │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 5. 🧠 Комплексное решение AI │ -├──────────────────────────────────────────────────────────┤ -│ • Просмотр исторической обратной связи (процент │ -│ выигрышей, коэффициент P/L, лучшие/худшие монеты) │ -│ • Получение всех данных последовательностей (свечи, │ -│ индикаторы, открытый интерес) │ -│ • Анализ Chain of Thought │ -│ • Вывод решения: закрыть/открыть/удерживать/наблюдать │ -│ • Включает параметры плеча, размера, стоп-лосса, │ -│ тейк-профита │ -│ 📌 НОВОЕ (v2.0.2): AI может свободно анализировать │ -│ сырые последовательности, не ограничен заранее │ -│ определенными индикаторами │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 6. ⚡ Исполнение сделок │ -├──────────────────────────────────────────────────────────┤ -│ • Приоритизация: сначала закрытие, затем открытие │ -│ • Автоматическая адаптация точности (правила LOT_SIZE) │ -│ • Предотвращение накопления позиций (отклонение │ -│ дублирования монета/направление) │ -│ • Автоматическая отмена всех ордеров после закрытия │ -│ • Запись времени открытия для отслеживания │ -│ длительности позиции │ -│ 📌 НОВОЕ (v2.0.2): Отслеживание времени открытия │ -│ позиции │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 7. 📝 Запись логов │ -├──────────────────────────────────────────────────────────┤ -│ • Сохранение полной записи решения в decision_logs/ │ -│ • Включает цепочку рассуждений, JSON решения, снимок │ -│ аккаунта, результаты исполнения │ -│ • Хранение полных данных позиции (количество, плечо, │ -│ время открытия/закрытия) │ -│ • Использование ключей symbol_side для предотвращения │ -│ конфликтов лонг/шорт │ -│ 📌 НОВОЕ (v2.0.2): Предотвращение конфликтов при │ -│ удержании лонг + шорт, учет количества + плеча │ -└──────────────────────────────────────────────────────────┘ -``` +### Шаг 1: 📊 Анализ исторической производительности (последние 20 циклов) +- ✓ Расчет общего процента выигрышей, средней прибыли, соотношения прибыли/убытка +- ✓ Статистика по каждой монете (процент выигрышей, средний P/L в USDT) +- ✓ Определение лучших/худших монет по производительности +- ✓ Список деталей последних 5 сделок с точным P/L +- ✓ Расчет коэффициента Шарпа для оценки риска +- 📌 **НОВОЕ (v2.0.2)**: Точный P/L в USDT с учетом плеча + +**↓** + +### Шаг 2: 💰 Получение состояния аккаунта +- Капитал аккаунта, доступный баланс, нереализованный P/L +- Количество позиций, общий P/L (реализованный + нереализованный) +- Использование маржи (текущее/максимальное) +- Индикаторы оценки риска + +**↓** + +### Шаг 3: 🔍 Анализ существующих позиций (если есть) +- Получение рыночных данных для каждой позиции (3-минутные + 4-часовые свечи) +- Расчет технических индикаторов (RSI, MACD, EMA) +- Отображение длительности удержания позиции (например, "удерживается 2 часа 15 минут") +- AI определяет, нужно ли закрыть (тейк-профит, стоп-лосс или корректировка) +- 📌 **НОВОЕ (v2.0.2)**: Отслеживание длительности позиции помогает AI решать + +**↓** + +### Шаг 4: 🎯 Оценка новых возможностей (пул кандидатов монет) +- Получение пула монет (2 режима): + - 🌟 **Режим по умолчанию**: BTC, ETH, SOL, BNB, XRP и т.д. + - ⚙️ **Расширенный режим**: AI500 (топ-20) + OI Top (топ-20) +- Объединение, удаление дубликатов, фильтрация монет с низкой ликвидностью (OI < 15M USD) +- Массовое получение рыночных данных и технических индикаторов +- Подготовка полных последовательностей сырых данных для каждой монеты-кандидата + +**↓** + +### Шаг 5: 🧠 Комплексное решение AI +- Просмотр исторической обратной связи (процент выигрышей, коэффициент P/L, лучшие/худшие монеты) +- Получение всех данных последовательностей (свечи, индикаторы, открытый интерес) +- Анализ Chain of Thought +- Вывод решения: закрыть/открыть/удерживать/наблюдать +- Включает параметры плеча, размера, стоп-лосса, тейк-профита +- 📌 **НОВОЕ (v2.0.2)**: AI может свободно анализировать сырые последовательности, не ограничен заранее определенными индикаторами + +**↓** + +### Шаг 6: ⚡ Исполнение сделок +- Приоритизация: сначала закрытие, затем открытие +- Автоматическая адаптация точности (правила LOT_SIZE) +- Предотвращение накопления позиций (отклонение дублирования монета/направление) +- Автоматическая отмена всех ордеров после закрытия +- Запись времени открытия для отслеживания длительности позиции +- 📌 Отслеживание времени открытия позиции + +**↓** + +### Шаг 7: 📝 Запись логов +- Сохранение полной записи решения в `decision_logs/` +- Включает цепочку рассуждений, JSON решения, снимок аккаунта, результаты исполнения +- Хранение полных данных позиции (количество, плечо, время открытия/закрытия) +- Использование ключей `symbol_side` для предотвращения конфликтов лонг/шорт +- 📌 **НОВОЕ (v2.0.2)**: Предотвращение конфликтов при удержании лонг + шорт, учет количества + плеча + +**↓** + +**🔄 (Повтор каждые 3-5 минут)** ### Ключевые улучшения в v2.0.2 @@ -1058,263 +1100,24 @@ sudo apt-get install libta-lib0-dev --- -## 🔄 История изменений +## 🔄 Журнал Изменений -```json -{ - "traders": [ - { - "id": "qwen_trader", - "name": "Qwen AI Trader", - "ai_model": "qwen", - "binance_api_key": "ВАШ_BINANCE_API_KEY", - "binance_secret_key": "ВАШ_BINANCE_SECRET_KEY", - "use_qwen": true, - "qwen_key": "sk-xxxxx", - "scan_interval_minutes": 3, - "initial_balance": 1000.0 - }, - { - "id": "deepseek_trader", - "name": "DeepSeek AI Trader", - "ai_model": "deepseek", - "binance_api_key": "ВАШ_BINANCE_API_KEY_2", - "binance_secret_key": "ВАШ_BINANCE_SECRET_KEY_2", - "use_qwen": false, - "deepseek_key": "sk-xxxxx", - "scan_interval_minutes": 3, - "initial_balance": 1000.0 - } - ], - "use_default_coins": false, - "coin_pool_api_url": "http://x.x.x.x:xxx/api/ai500/list?auth=ВАШ_AUTH", - "oi_top_api_url": "http://x.x.x.x:xxx/api/oi/top?auth=ВАШ_AUTH", - "api_server_port": 8080 -} -``` +📖 **Для подробной истории версий и обновлений см.:** -**Примечания к конфигурации:** -- `traders`: Настройте 1-N трейдеров (один AI или соревнование нескольких AI) -- `id`: Уникальный идентификатор трейдера (используется для директории логов) -- `ai_model`: "qwen" или "deepseek" -- `binance_api_key/secret_key`: Каждый трейдер использует независимый аккаунт Binance -- `initial_balance`: Начальный баланс (для расчета P/L%) -- `scan_interval_minutes`: Цикл принятия решений (рекомендуется 3-5 минут) -- `use_default_coins`: **true** = Использовать 8 основных монет по умолчанию | **false** = Использовать API пул монет (рекомендуется для новичков: true) -- `coin_pool_api_url`: API пула монет AI500 (опционально, игнорируется при use_default_coins=true) -- `oi_top_api_url`: API открытого интереса OI Top (опционально, если пусто, данные OI Top пропускаются) +- **Русский:** [CHANGELOG.zh-CN.md](../../../CHANGELOG.zh-CN.md) +- **English:** [CHANGELOG.md](../../../CHANGELOG.md) -**Список монет по умолчанию** (когда `use_default_coins: true`): -- BTC, ETH, SOL, BNB, XRP, DOGE, ADA, HYPE +**Последняя Версия:** v3.0.0 (2025-10-30) - Масштабная Трансформация Архитектуры -### 5. Запуск системы - -**Запуск backend (система AI торговли + API сервер):** - -```bash -go build -o nofx -./nofx -``` - -**Запуск frontend (веб-панель):** - -Откройте новый терминал: - -```bash -cd web -npm run dev -``` - -**Доступ к интерфейсу:** -``` -Веб-панель: http://localhost:3000 -API сервер: http://localhost:8080 -``` - -### 6. Остановка системы - -Нажмите `Ctrl+C` в обоих терминалах - ---- - -## ⚠️ Важные предупреждения о рисках - -### Торговые риски - -1. **Рынки криптовалют чрезвычайно волатильны**, решения AI не гарантируют прибыль -2. **Торговля фьючерсами использует плечо**, убытки могут превысить основную сумму -3. **Экстремальные рыночные условия** могут привести к ликвидации -4. **Комиссии за финансирование** могут повлиять на стоимость удержания -5. **Риск ликвидности**: Некоторые монеты могут испытывать проскальзывание - -### Технические риски - -1. **Задержка сети** может вызвать проскальзывание цены -2. **Лимиты API** могут повлиять на исполнение сделок -3. **Тайм-ауты AI API** могут вызвать сбои решений -4. **Системные ошибки** могут вызвать неожиданное поведение - -### Рекомендации по использованию - -✅ **Рекомендуется** -- Используйте только средства, потерю которых вы можете позволить для тестирования -- Начните с небольших сумм (рекомендуется 100-500 USDT) -- Регулярно проверяйте состояние работы системы -- Отслеживайте изменения баланса счета -- Анализируйте логи решений AI для понимания стратегии - -❌ **Не рекомендуется** -- Инвестировать все средства или заемные деньги -- Запускать без присмотра на длительные периоды -- Слепо доверять решениям AI -- Использовать без понимания системы -- Запускать во время экстремальной волатильности рынка - ---- - -## 🛠️ Частые проблемы - -### 1. Ошибка компиляции: TA-Lib не найдена - -**Решение**: Установите библиотеку TA-Lib -```bash -# macOS -brew install ta-lib - -# Ubuntu -sudo apt-get install libta-lib0-dev -``` - -### 2. Ошибка точности: Точность превышает максимум - -**Решение**: Система автоматически обрабатывает точность из Binance LOT_SIZE. Если ошибка сохраняется, проверьте сетевое подключение. - -### 3. Тайм-аут AI API - -**Решение**: -- Проверьте правильность API ключа -- Проверьте сетевое подключение (может потребоваться прокси) -- Тайм-аут системы установлен на 120 секунд - -### 4. Frontend не может подключиться к backend - -**Решение**: -- Убедитесь, что backend запущен (http://localhost:8080) -- Проверьте, не занят ли порт 8080 -- Проверьте ошибки в консоли браузера - -### 5. Сбой API пула монет - -**Решение**: -- API пула монет опционален -- Если API не работает, система использует основные монеты по умолчанию (BTC, ETH и т.д.) -- Проверьте URL API и параметр auth в config.json - ---- - -## 📄 Лицензия - -Лицензия MIT - См. файл [LICENSE](LICENSE) для деталей - ---- - -## 🤝 Вклад в проект - -Приветствуются Issues и Pull Requests! - -### Руководство по разработке - -1. Сделайте Fork проекта -2. Создайте ветку функции (`git checkout -b feature/AmazingFeature`) -3. Зафиксируйте изменения (`git commit -m 'Add some AmazingFeature'`) -4. Отправьте в ветку (`git push origin feature/AmazingFeature`) -5. Откройте Pull Request - ---- - -## 📬 Контакты - -- **Twitter/X**: [@Web3Tinkle](https://x.com/Web3Tinkle) -- **GitHub Issues**: [Создать Issue](https://github.com/tinkle-community/nofx/issues) - ---- - -## 🙏 Благодарности - -- [Binance API](https://binance-docs.github.io/apidocs/futures/en/) - Binance Futures API -- [DeepSeek](https://platform.deepseek.com/) - DeepSeek AI API -- [Qwen](https://dashscope.aliyuncs.com/) - Alibaba Cloud Qwen -- [TA-Lib](https://ta-lib.org/) - Библиотека технических индикаторов -- [Recharts](https://recharts.org/) - Библиотека графиков React - ---- - -## 🔄 История изменений - -### v2.0.2 (2025-10-29) - -**Критические исправления ошибок - История сделок и анализ производительности:** - -Эта версия исправляет **критические ошибки расчета** в системе исторических записей сделок и анализа производительности, которые значительно влияли на статистику прибыльности. - -**1. Расчет P/L - Исправление крупной ошибки** (logger/decision_logger.go) -- **Проблема**: Ранее P/L рассчитывался только как процент, полностью игнорируя размер позиции и плечо - - Пример: Позиция 100 USDT с доходом 5% и позиция 1000 USDT с доходом 5% обе показывали `5.0` как прибыль - - Это делало анализ производительности полностью неточным -- **Решение**: Теперь рассчитывается фактическая прибыль в USDT - ``` - P/L (USDT) = Стоимость позиции × Изменение цены % × Плечо - Пример: 1000 USDT × 5% × 20x = 1000 USDT фактической прибыли - ``` -- **Влияние**: Процент выигрышей, коэффициент прибыли и коэффициент Шарпа теперь основаны на точных суммах USDT - -**2. Отслеживание позиций - Отсутствие критических данных** -- **Проблема**: Записи открытых позиций хранили только цену и время, пропуская количество и плечо -- **Решение**: Теперь хранит полные торговые данные: - - `quantity`: Размер позиции (в монетах) - - `leverage`: Множитель плеча (например, 20x) - - Эти данные необходимы для точного расчета P/L - -**3. Логика ключа позиции - Конфликт Long/Short** -- **Проблема**: Использовался `symbol` как ключ позиции, что вызывало конфликты данных при одновременном удержании лонгов и шортов - - Пример: BTCUSDT лонг и BTCUSDT шорт перезаписывали друг друга -- **Решение**: Изменено на формат `symbol_side` (например, `BTCUSDT_long`, `BTCUSDT_short`) - - Теперь правильно различает лонг и шорт позиции - -**4. Расчет коэффициента Шарпа - Оптимизация кода** -- **Проблема**: Использовался пользовательский метод Ньютона для расчета квадратного корня -- **Решение**: Заменен на стандартную библиотеку `math.Sqrt` - - Более надежный, поддерживаемый и эффективный - -**Почему это обновление важно:** -- ✅ Историческая статистика сделок теперь показывает **реальную прибыль/убыток в USDT** вместо бессмысленных процентов -- ✅ Сравнение производительности между сделками с разным плечом теперь точно -- ✅ Механизм самообучения AI получает правильную историческую обратную связь -- ✅ Расчеты коэффициента прибыли и коэффициента Шарпа теперь имеют смысл -- ✅ Отслеживание нескольких позиций (лонг + шорт одновременно) теперь работает правильно - -**Рекомендация**: Если вы запускали систему до этого обновления, ваша историческая статистика была неточной. После обновления до v2.0.2, новые сделки будут рассчитываться правильно. - -### v2.0.1 (2025-10-29) - -**Исправления ошибок:** -- ✅ Исправлена логика обработки данных ComparisonChart - переход от группировки по cycle_number к timestamp -- ✅ Решена проблема замораживания графика при перезапуске backend и сбросе cycle_number -- ✅ Улучшено отображение данных графика - теперь показывает все исторические точки в хронологическом порядке -- ✅ Улучшенные отладочные логи для лучшей диагностики - -### v2.0.0 (2025-10-28) - -**Основные обновления:** -- ✅ Механизм самообучения AI (исторический анализ, анализ производительности) -- ✅ Режим конкуренции нескольких трейдеров (Qwen vs DeepSeek) -- ✅ UI в стиле Binance (полная имитация интерфейса Binance) -- ✅ Графики сравнения производительности (сравнение ROI в реальном времени) -- ✅ Оптимизация контроля рисков (корректировка лимита позиции по монетам) - ---- - -**Последнее обновление**: 2025-10-29 (v2.0.2) +**Недавние Основные Моменты:** +- 🚀 Полная переработка системы с веб-конфигурацией +- 🗄️ Архитектура на основе базы данных (SQLite) +- 🎨 Никакого редактирования JSON - вся конфигурация через веб-интерфейс +- 🔧 Комбинируйте AI модели с любой биржей +- 📊 Расширенный API слой с комплексными эндпоинтами +- 🔐 Аутентификация JWT + поддержка 2FA +- 🌐 Поддержка кастомных API (совместимых с OpenAI) +- 📈 Система шаблонов промптов с удаленной аутентификацией **⚡ Исследуйте возможности количественной торговли с силой AI!** diff --git a/README.uk.md b/docs/i18n/uk/README.md similarity index 68% rename from README.uk.md rename to docs/i18n/uk/README.md index 0ec6d5df..19d506ef 100644 --- a/README.uk.md +++ b/docs/i18n/uk/README.md @@ -6,10 +6,30 @@ [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Backed by Amber.ac](https://img.shields.io/badge/Backed%20by-Amber.ac-orange.svg)](https://amber.ac) -**Мови / Languages:** [English](README.md) | [中文](README.zh-CN.md) | [Українська](README.uk.md) | [Русский](README.ru.md) +**Мови / Languages:** [English](../../../README.md) | [中文](../zh-CN/README.md) | [Українська](../uk/README.md) | [Русский](../ru/README.md) **Офіційний Twitter:** [@nofx_ai](https://x.com/nofx_ai) +**📚 Документація:** [Головна](../../README.md) | [Початок роботи](../../getting-started/README.md) | [Спільнота](../../community/README.md) | [Журнал Змін](../../../CHANGELOG.md) + +--- + +## 📑 Зміст + +- [🚀 Універсальна AI Торгова Операційна Система](#-універсальна-ai-торгова-операційна-система) +- [👥 Спільнота розробників](#-спільнота-розробників) +- [🆕 Останні оновлення](#-останні-оновлення) +- [🏗️ Технічна Архітектура](#️-технічна-архітектура) +- [📸 Системні Скріншоти](#-системні-скріншоти) +- [🎮 Швидкий Старт](#-швидкий-старт) +- [📊 AI Модель](#-ai-модель) +- [📈 Огляд Продуктивності](#-огляд-продуктивності) +- [📄 Ліцензія](#-ліцензія) +- [🤝 Внесок у проєкт](#-внесок-у-проєкт) +- [📬 Контакти](#-контакти) +- [🙏 Подяки](#-подяки) +- [🔄 Журнал Змін](#-журнал-змін) + --- ## 🚀 Універсальна AI Торгова Операційна Система @@ -74,7 +94,7 @@ NOFX тепер підтримує **три основні біржі**: Binance **Швидкий старт:** 1. Отримайте приватний ключ MetaMask (видаліть префікс `0x`) -2. Встановіть `"exchange": "hyperliquid"` в config.json +2. ~~Встановіть `"exchange": "hyperliquid"` в config.json~~ *Налаштуйте через веб-інтерфейс* 3. Додайте `"hyperliquid_private_key": "your_key"` 4. Почніть торгувати! @@ -109,15 +129,19 @@ NOFX тепер підтримує **три основні біржі**: Binance ## 📸 Скриншоти ### 🏆 Режим змагання - Битва AI в реальному часі -![Сторінка змагання](screenshots/competition-page.png) +![Сторінка змагання](../../../screenshots/competition-page.png) *Лідерборд з кількома AI та графіки порівняння продуктивності в реальному часі показують битву Qwen проти DeepSeek* ### 📊 Деталі трейдера - Повна торгова панель -![Сторінка деталей](screenshots/details-page.png) +![Сторінка деталей](../../../screenshots/details-page.png) *Професійний торговий інтерфейс з кривими капіталу, живими позиціями та логами рішень AI з розкриваємими вхідними промптами та ланцюгом міркувань* --- +> 📘 **Примітка**: Це спрощена українська версія README. Для отримання повної технічної документації, включаючи архітектуру системи, API-інтерфейси та розширені конфігурації, див. [Англійську версію](../../../README.md) або [Китайську версію](../zh-CN/README.md). + +--- + ## ✨ Основні можливості ### 🏆 Режим змагання кількох AI @@ -173,6 +197,57 @@ NOFX тепер підтримує **три основні біржі**: Binance --- +## 🔮 Дорожня Карта - Розширення на Універсальні Ринки + +Місія NOFX - стати **Універсальною AI Торговою Операційною Системою** для всіх фінансових ринків. + +**Бачення:** Та сама архітектура. Та сама агентна структура. Всі ринки. + +**Розширення на Ринки:** +- 📈 **Фондові Ринки**: Акції США, A-акції, Гонконгська біржа +- 📊 **Ринки Ф'ючерсів**: Товарні ф'ючерси, індексні ф'ючерси +- 🎯 **Опціонна Торгівля**: Опціони на акції, крипто опціони +- 💱 **Ринки Форекс**: Основні валютні пари, крос-курси + +**Майбутні Функції:** +- Розширені AI можливості (GPT-4, Claude 3, Gemini Pro, гнучкі шаблони промптів) +- Нові інтеграції бірж (OKX, Bybit, Lighter, EdgeX + CEX/Perp-DEX) +- Рефакторинг структури проєкту (висока зв'язність, низька зчепленість, принципи SOLID) +- Покращення безпеки (AES-256 шифрування API ключів, RBAC, покращення 2FA) +- Покращення користувацького досвіду (мобільний інтерфейс, графіки TradingView, система сповіщень) + +📖 **Для детальної дорожньої карти та термінів див.:** +- **English:** [Roadmap Documentation](../../roadmap/README.md) +- **中文:** [路线图文档](../../roadmap/README.zh-CN.md) + +--- + +## 🏗️ Технічна Архітектура + +NOFX побудовано на сучасній модульній архітектурі: + +- **Backend:** Go з фреймворком Gin, база даних SQLite +- **Frontend:** React 18 + TypeScript + Vite + TailwindCSS +- **AI інтеграція:** DeepSeek, Qwen, кастомні API (сумісні з OpenAI) +- **Підтримка бірж:** Binance Futures, Hyperliquid DEX, Aster DEX +- **Аутентифікація:** JWT токени + підтримка 2FA +- **Управління станом:** Zustand (легковагове) +- **Отримання даних:** SWR з опитуванням 5-10с +- **Графіки:** Recharts для кривих капіталу та порівнянь + +**Ключові особливості:** +- 🔧 Архітектура на основі бази даних (конфігурація через веб-інтерфейс, без JSON) +- 🎯 Комбінуйте будь-яку AI модель з будь-якою біржею +- 📊 RESTful API з комплексними ендпоінтами +- 🔐 Безпечне управління облікових даних +- 📈 Система шаблонів промптів з віддаленою аутентифікацією + +📖 **Детальна документація по архітектурі:** +- **English:** [Architecture Documentation](../../architecture/README.md) +- **中文:** [架构文档](../../architecture/README.zh-CN.md) + +--- + ## 💰 Реєстрація акаунта Binance (Заощаджуйте на комісіях!) Перед використанням цієї системи вам потрібен акаунт Binance Futures. **Використовуйте наше реферальне посилання для отримання знижки на комісії:** @@ -824,104 +899,73 @@ curl http://localhost:8080/api/health Кожен цикл прийняття рішень (за замовчуванням 3 хвилини), система працює за наступним процесом: -``` -┌──────────────────────────────────────────────────────────┐ -│ 1. 📊 Аналіз історичної продуктивності │ -│ (останні 20 циклів) │ -├──────────────────────────────────────────────────────────┤ -│ ✓ Розрахунок загального відсотка виграшів, середнього │ -│ прибутку, співвідношення прибутку/збитку │ -│ ✓ Статистика по кожній монеті (відсоток виграшів, │ -│ середній P/L в USDT) │ -│ ✓ Визначення найкращих/найгірших монет за │ -│ продуктивністю │ -│ ✓ Список деталей останніх 5 угод з точним P/L │ -│ ✓ Розрахунок коефіцієнта Шарпа для оцінки ризику │ -│ 📌 НОВЕ (v2.0.2): Точний P/L в USDT з врахуванням │ -│ плеча │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 2. 💰 Отримання стану акаунта │ -├──────────────────────────────────────────────────────────┤ -│ • Капітал акаунта, доступний баланс, нереалізований │ -│ P/L │ -│ • Кількість позицій, загальний P/L (реалізований + │ -│ нереалізований) │ -│ • Використання маржі (поточне/максимальне) │ -│ • Індикатори оцінки ризику │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 3. 🔍 Аналіз існуючих позицій (якщо є) │ -├──────────────────────────────────────────────────────────┤ -│ • Отримання ринкових даних для кожної позиції │ -│ (3-хвилинні + 4-годинні свічки) │ -│ • Розрахунок технічних індикаторів (RSI, MACD, EMA) │ -│ • Відображення тривалості утримання позиції │ -│ (наприклад, "утримується 2 години 15 хвилин") │ -│ • AI визначає, чи потрібно закрити (тейк-профіт, │ -│ стоп-лосс або коригування) │ -│ 📌 НОВЕ (v2.0.2): Відстеження тривалості позиції │ -│ допомагає AI вирішувати │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 4. 🎯 Оцінка нових можливостей (пул кандидатів монет) │ -├──────────────────────────────────────────────────────────┤ -│ • Отримання топ-20 монет з високим рейтингом AI500 │ -│ • Отримання топ-20 монет з найшвидшим зростанням OI │ -│ • Об'єднання, видалення дублікатів, фільтрація монет з │ -│ низькою ліквідністю (OI < 15M USD) │ -│ • Масове отримання ринкових даних та технічних │ -│ індикаторів │ -│ • Підготовка повних послідовностей сирих даних для │ -│ кожної монети-кандидата │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 5. 🧠 Комплексне рішення AI │ -├──────────────────────────────────────────────────────────┤ -│ • Перегляд історичного зворотного зв'язку (відсоток │ -│ виграшів, коефіцієнт P/L, найкращі/найгірші монети) │ -│ • Отримання всіх даних послідовностей (свічки, │ -│ індикатори, відкритий інтерес) │ -│ • Аналіз Chain of Thought │ -│ • Вивід рішення: закрити/відкрити/утримувати/спостерігати │ -│ • Включає параметри плеча, розміру, стоп-лосса, │ -│ тейк-профіта │ -│ 📌 НОВЕ (v2.0.2): AI може вільно аналізувати сирі │ -│ послідовності, не обмежений заздалегідь визначеними │ -│ індикаторами │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 6. ⚡ Виконання угод │ -├──────────────────────────────────────────────────────────┤ -│ • Пріоритизація: спочатку закриття, потім відкриття │ -│ • Автоматична адаптація точності (правила LOT_SIZE) │ -│ • Запобігання накопиченню позицій (відхилення │ -│ дублювання монета/напрямок) │ -│ • Автоматична відміна всіх ордерів після закриття │ -│ • Запис часу відкриття для відстеження тривалості │ -│ позиції │ -│ 📌 НОВЕ (v2.0.2): Відстеження часу відкриття позиції │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 7. 📝 Запис логів │ -├──────────────────────────────────────────────────────────┤ -│ • Збереження повного запису рішення в decision_logs/ │ -│ • Включає ланцюг міркувань, JSON рішення, знімок │ -│ акаунта, результати виконання │ -│ • Зберігання повних даних позиції (кількість, плече, │ -│ час відкриття/закриття) │ -│ • Використання ключів symbol_side для запобігання │ -│ конфліктів лонг/шорт │ -│ 📌 НОВЕ (v2.0.2): Запобігання конфліктів при утриманні │ -│ лонг + шорт, врахування кількості + плеча │ -└──────────────────────────────────────────────────────────┘ -``` +### Крок 1: 📊 Аналіз історичної продуктивності (останні 20 циклів) +- ✓ Розрахунок загального відсотка виграшів, середнього прибутку, співвідношення прибутку/збитку +- ✓ Статистика по кожній монеті (відсоток виграшів, середній P/L в USDT) +- ✓ Визначення найкращих/найгірших монет за продуктивністю +- ✓ Список деталей останніх 5 угод з точним P/L +- ✓ Розрахунок коефіцієнта Шарпа для оцінки ризику +- 📌 **НОВЕ (v2.0.2)**: Точний P/L в USDT з врахуванням плеча + +**↓** + +### Крок 2: 💰 Отримання стану акаунта +- Капітал акаунта, доступний баланс, нереалізований P/L +- Кількість позицій, загальний P/L (реалізований + нереалізований) +- Використання маржі (поточне/максимальне) +- Індикатори оцінки ризику + +**↓** + +### Крок 3: 🔍 Аналіз існуючих позицій (якщо є) +- Отримання ринкових даних для кожної позиції (3-хвилинні + 4-годинні свічки) +- Розрахунок технічних індикаторів (RSI, MACD, EMA) +- Відображення тривалості утримання позиції (наприклад, "утримується 2 години 15 хвилин") +- AI визначає, чи потрібно закрити (тейк-профіт, стоп-лосс або коригування) +- 📌 **НОВЕ (v2.0.2)**: Відстеження тривалості позиції допомагає AI вирішувати + +**↓** + +### Крок 4: 🎯 Оцінка нових можливостей (пул кандидатів монет) +- Отримання пулу монет (2 режими): + - 🌟 **Режим за замовчуванням**: BTC, ETH, SOL, BNB, XRP тощо + - ⚙️ **Розширений режим**: AI500 (топ-20) + OI Top (топ-20) +- Об'єднання, видалення дублікатів, фільтрація монет з низькою ліквідністю (OI < 15M USD) +- Масове отримання ринкових даних та технічних індикаторів +- Підготовка повних послідовностей сирих даних для кожної монети-кандидата + +**↓** + +### Крок 5: 🧠 Комплексне рішення AI +- Перегляд історичного зворотного зв'язку (відсоток виграшів, коефіцієнт P/L, найкращі/найгірші монети) +- Отримання всіх даних послідовностей (свічки, індикатори, відкритий інтерес) +- Аналіз Chain of Thought +- Вивід рішення: закрити/відкрити/утримувати/спостерігати +- Включає параметри плеча, розміру, стоп-лосса, тейк-профіта +- 📌 **НОВЕ (v2.0.2)**: AI може вільно аналізувати сирі послідовності, не обмежений заздалегідь визначеними індикаторами + +**↓** + +### Крок 6: ⚡ Виконання угод +- Пріоритизація: спочатку закриття, потім відкриття +- Автоматична адаптація точності (правила LOT_SIZE) +- Запобігання накопиченню позицій (відхилення дублювання монета/напрямок) +- Автоматична відміна всіх ордерів після закриття +- Запис часу відкриття для відстеження тривалості позиції +- 📌 Відстеження часу відкриття позиції + +**↓** + +### Крок 7: 📝 Запис логів +- Збереження повного запису рішення в `decision_logs/` +- Включає ланцюг міркувань, JSON рішення, знімок акаунта, результати виконання +- Зберігання повних даних позиції (кількість, плече, час відкриття/закриття) +- Використання ключів `symbol_side` для запобігання конфліктів лонг/шорт +- 📌 **НОВЕ (v2.0.2)**: Запобігання конфліктів при утриманні лонг + шорт, врахування кількості + плеча + +**↓** + +**🔄 (Повтор кожні 3-5 хвилин)** ### Ключові покращення в v2.0.2 @@ -950,6 +994,7 @@ curl http://localhost:8080/api/health ## ⚠️ Важливі попередження про ризики ### Торговельні ризики +``` { "id": "qwen_trader", "name": "Qwen AI Trader", @@ -1013,6 +1058,7 @@ npm run dev ``` **Доступ до інтерфейсу:** + ``` Веб-панель: http://localhost:3000 API сервер: http://localhost:8080 @@ -1024,184 +1070,26 @@ API сервер: http://localhost:8080 --- -## ⚠️ Важливі попередження про ризики - -### Торговельні ризики - -1. **Ринки криптовалют надзвичайно волатильні**, рішення AI не гарантують прибуток -2. **Торгівля ф'ючерсами використовує плече**, збитки можуть перевищити основну суму -3. **Екстремальні ринкові умови** можуть призвести до ліквідації -4. **Комісії за фінансування** можуть вплинути на вартість утримання -5. **Ризик ліквідності**: Деякі монети можуть відчувати проковзування - -### Технічні ризики - -1. **Затримка мережі** може викликати проковзування ціни -2. **Ліміти API** можуть вплинути на виконання угод -3. **Тайм-аути AI API** можуть викликати збої рішень -4. **Системні помилки** можуть викликати неочікувану поведінку - -### Рекомендації щодо використання - -✅ **Рекомендується** -- Використовуйте лише кошти, втрату яких ви можете дозволити для тестування -- Почніть з невеликих сум (рекомендується 100-500 USDT) -- Регулярно перевіряйте стан роботи системи -- Відстежуйте зміни балансу рахунку -- Аналізуйте логи рішень AI для розуміння стратегії - -❌ **Не рекомендується** -- Інвестувати всі кошти або позичені гроші -- Запускати без нагляду на тривалі періоди -- Сліпо довіряти рішенням AI -- Використовувати без розуміння системи -- Запускати під час екстремальної волатильності ринку - --- -## 🛠️ Часті проблеми +## 🔄 Журнал Змін -### 1. Помилка компіляції: TA-Lib не знайдена +📖 **Для детальної історії версій та оновлень див.:** -**Рішення**: Встановіть бібліотеку TA-Lib -```bash -# macOS -brew install ta-lib +- **Українська:** [CHANGELOG.zh-CN.md](../../../CHANGELOG.zh-CN.md) +- **English:** [CHANGELOG.md](../../../CHANGELOG.md) -# Ubuntu -sudo apt-get install libta-lib0-dev -``` +**Остання Версія:** v3.0.0 (2025-10-30) - Масштабна Трансформація Архітектури -### 2. Помилка точності: Точність перевищує максимум - -**Рішення**: Система автоматично обробляє точність з Binance LOT_SIZE. Якщо помилка зберігається, перевірте мережеве підключення. - -### 3. Тайм-аут AI API - -**Рішення**: -- Перевірте правильність API ключа -- Перевірте мережеве підключення (може знадобитися проксі) -- Тайм-аут системи встановлено на 120 секунд - -### 4. Frontend не може підключитися до backend - -**Рішення**: -- Переконайтеся, що backend запущено (http://localhost:8080) -- Перевірте, чи не зайнятий порт 8080 -- Перевірте помилки в консолі браузера - -### 5. Збій API пулу монет - -**Рішення**: -- API пулу монет опціонален -- Якщо API не працює, система використовує основні монети за замовчуванням (BTC, ETH тощо) -- Перевірте URL API та параметр auth в config.json - ---- - -## 📄 Ліцензія - -Ліцензія MIT - Див. файл [LICENSE](LICENSE) для деталей - ---- - -## 🤝 Внесок у проєкт - -Вітаються Issues та Pull Requests! - -### Керівництво з розробки - -1. Зробіть Fork проєкту -2. Створіть гілку функції (`git checkout -b feature/AmazingFeature`) -3. Зафіксуйте зміни (`git commit -m 'Add some AmazingFeature'`) -4. Надішліть до гілки (`git push origin feature/AmazingFeature`) -5. Відкрийте Pull Request - ---- - -## 📬 Контакти - -- **Twitter/X**: [@Web3Tinkle](https://x.com/Web3Tinkle) -- **GitHub Issues**: [Створити Issue](https://github.com/tinkle-community/nofx/issues) - ---- - -## 🙏 Подяки - -- [Binance API](https://binance-docs.github.io/apidocs/futures/en/) - Binance Futures API -- [DeepSeek](https://platform.deepseek.com/) - DeepSeek AI API -- [Qwen](https://dashscope.aliyuncs.com/) - Alibaba Cloud Qwen -- [TA-Lib](https://ta-lib.org/) - Бібліотека технічних індикаторів -- [Recharts](https://recharts.org/) - Бібліотека графіків React - ---- - -## 🔄 Історія змін - -### v2.0.2 (2025-10-29) - -**Критичні виправлення помилок - Історія угод та аналіз продуктивності:** - -Ця версія виправляє **критичні помилки розрахунку** в системі історичних записів угод та аналізу продуктивності, які значно впливали на статистику прибутковості. - -**1. Розрахунок P/L - Виправлення великої помилки** (logger/decision_logger.go) -- **Проблема**: Раніше P/L розраховувався лише як відсоток, повністю ігноруючи розмір позиції та плече - - Приклад: Позиція 100 USDT з доходом 5% та позиція 1000 USDT з доходом 5% обидві показували `5.0` як прибуток - - Це робило аналіз продуктивності повністю неточним -- **Рішення**: Тепер розраховується фактичний прибуток в USDT - ``` - P/L (USDT) = Вартість позиції × Зміна ціни % × Плече - Приклад: 1000 USDT × 5% × 20x = 1000 USDT фактичного прибутку - ``` -- **Вплив**: Відсоток виграшів, коефіцієнт прибутку та коефіцієнт Шарпа тепер засновані на точних сумах USDT - -**2. Відстеження позицій - Відсутність критичних даних** -- **Проблема**: Записи відкритих позицій зберігали лише ціну та час, пропускаючи кількість та плече -- **Рішення**: Тепер зберігає повні торгові дані: - - `quantity`: Розмір позиції (в монетах) - - `leverage`: Множник плеча (наприклад, 20x) - - Ці дані необхідні для точного розрахунку P/L - -**3. Логіка ключа позиції - Конфлікт Long/Short** -- **Проблема**: Використовувався `symbol` як ключ позиції, що викликало конфлікти даних при одночасному утриманні лонгів та шортів - - Приклад: BTCUSDT лонг та BTCUSDT шорт перезаписували один одного -- **Рішення**: Змінено на формат `symbol_side` (наприклад, `BTCUSDT_long`, `BTCUSDT_short`) - - Тепер правильно розрізняє лонг та шорт позиції - -**4. Розрахунок коефіцієнта Шарпа - Оптимізація коду** -- **Проблема**: Використовувався користувацький метод Ньютона для розрахунку квадратного кореня -- **Рішення**: Замінено на стандартну бібліотеку `math.Sqrt` - - Більш надійний, підтримуваний та ефективний - -**Чому це оновлення важливе:** -- ✅ Історична статистика угод тепер показує **реальний прибуток/збиток в USDT** замість безглуздих відсотків -- ✅ Порівняння продуктивності між угодами з різним плечем тепер точне -- ✅ Механізм самонавчання AI отримує правильний історичний зворотний зв'язок -- ✅ Розрахунки коефіцієнта прибутку та коефіцієнта Шарпа тепер мають сенс -- ✅ Відстеження кількох позицій (лонг + шорт одночасно) тепер працює правильно - -**Рекомендація**: Якщо ви запускали систему до цього оновлення, ваша історична статистика була неточною. Після оновлення до v2.0.2, нові угоди будуть розраховуватися правильно. - -### v2.0.1 (2025-10-29) - -**Виправлення помилок:** -- ✅ Виправлено логіку обробки даних ComparisonChart - перехід від групування по cycle_number до timestamp -- ✅ Вирішено проблему заморожування графіка при перезапуску backend та скиданні cycle_number -- ✅ Покращено відображення даних графіка - тепер показує всі історичні точки в хронологічному порядку -- ✅ Покращені відладочні логи для кращої діагностики - -### v2.0.0 (2025-10-28) - -**Основні оновлення:** -- ✅ Механізм самонавчання AI (історичний аналіз, аналіз продуктивності) -- ✅ Режим змагання кількох трейдерів (Qwen vs DeepSeek) -- ✅ UI в стилі Binance (повна імітація інтерфейсу Binance) -- ✅ Графіки порівняння продуктивності (порівняння ROI в реальному часі) -- ✅ Оптимізація контролю ризиків (коригування ліміту позиції по монетах) - ---- - -**Останнє оновлення**: 2025-10-29 (v2.0.2) +**Недавні Основні Моменти:** +- 🚀 Повна переробка системи з веб-конфігурацією +- 🗄️ Архітектура на основі бази даних (SQLite) +- 🎨 Ніякого редагування JSON - вся конфігурація через веб-інтерфейс +- 🔧 Комбінуйте AI моделі з будь-якою біржею +- 📊 Розширений API шар з комплексними ендпоінтами +- 🔐 Аутентифікація JWT + підтримка 2FA +- 🌐 Підтримка кастомних API (сумісних з OpenAI) +- 📈 Система шаблонів промптів з віддаленою аутентифікацією **⚡ Досліджуйте можливості кількісної торгівлі з силою AI!** diff --git a/README.zh-CN.md b/docs/i18n/zh-CN/README.md similarity index 71% rename from README.zh-CN.md rename to docs/i18n/zh-CN/README.md index 75be2f64..29d69c8e 100644 --- a/README.zh-CN.md +++ b/docs/i18n/zh-CN/README.md @@ -6,10 +6,38 @@ [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Backed by Amber.ac](https://img.shields.io/badge/Backed%20by-Amber.ac-orange.svg)](https://amber.ac) -**语言 / Languages:** [English](README.md) | [中文](README.zh-CN.md) | [Українська](README.uk.md) | [Русский](README.ru.md) +**语言 / Languages:** [English](../../../README.md) | [中文](../zh-CN/README.md) | [Українська](../uk/README.md) | [Русский](../ru/README.md) **官方推特:** [@nofx_ai](https://x.com/nofx_ai) +**📚 文档中心:** [文档首页](../../README.md) | [快速开始](../../getting-started/README.zh-CN.md) | [更新日志](../../../CHANGELOG.zh-CN.md) | [社区指南](../../community/README.md) + +--- + +## 📑 目录 + +- [🚀 通用AI交易操作系统](#-通用ai交易操作系统) +- [👥 开发者社区](#-开发者社区) +- [🆕 最新更新](#-最新更新) +- [📸 系统截图](#-系统截图) +- [✨ 当前实现](#-当前实现---加密货币市场) +- [🔮 路线图](#-路线图---通用市场扩展) +- [🏗️ 技术架构](#️-技术架构) +- [💰 注册币安账户](#-注册币安账户省手续费) +- [🚀 快速开始](#-快速开始) +- [📖 AI决策流程](#-ai决策流程) +- [🧠 AI自我学习示例](#-ai自我学习示例) +- [📊 Web界面功能](#-web界面功能) +- [🎛️ API接口](#️-api接口) +- [📝 决策日志格式](#-决策日志格式) +- [🔧 风险控制详解](#-风险控制详解) +- [⚠️ 重要风险提示](#️-重要风险提示) +- [🛠️ 常见问题](#️-常见问题) +- [📈 性能优化建议](#-性能优化建议) +- [🔄 更新日志](#-更新日志) +- [📄 开源协议](#-开源协议) +- [🤝 贡献指南](#-贡献指南) + --- ## 🚀 通用AI交易操作系统 @@ -109,11 +137,11 @@ NOFX现已支持**三大交易所**：Binance、Hyperliquid和Aster DEX！ ## 📸 系统截图 ### 🏆 竞赛模式 - AI实时对战 -![竞赛页面](screenshots/competition-page.png) +![竞赛页面](../../../screenshots/competition-page.png) *多AI排行榜和实时性能对比图表，展示Qwen vs DeepSeek实时交易对战* ### 📊 交易详情 - 完整交易仪表盘 -![详情页面](screenshots/details-page.png) +![详情页面](../../../screenshots/details-page.png) *专业交易界面，包含权益曲线、实时持仓、AI决策日志，支持展开查看输入提示词和AI思维链推理过程* --- @@ -168,78 +196,50 @@ NOFX 目前已在**加密货币市场全面运行**，具备以下经过验证 ## 🔮 路线图 - 通用市场扩展 -我们经过验证的加密货币基础设施正在扩展到： +NOFX 的使命是成为所有金融市场的**通用 AI 交易操作系统**。 -- **📈 股票市场**：美股、A股、港股 -- **📊 期货市场**：商品期货、指数期货 -- **🎯 期权交易**：股票期权、加密期权 -- **💱 外汇市场**：主要货币对、交叉盘 +**愿景：** 相同架构。相同智能体框架。所有市场。 -**相同架构。相同智能体框架。所有市场。** +**扩展市场：** +- 📈 **股票市场**：美股、A股、港股 +- 📊 **期货市场**：商品期货、指数期货 +- 🎯 **期权交易**：股票期权、加密期权 +- 💱 **外汇市场**：主要货币对、交叉盘 + +**即将推出的功能：** +- 增强AI能力（GPT-4、Claude 3、Gemini Pro、灵活prompt模板） +- 新交易所集成（OKX、Bybit、Lighter、EdgeX + CEX/Perp-DEX） +- 项目结构重构（高内聚低耦合、SOLID原则） +- 安全性增强（API密钥AES-256加密、RBAC、2FA改进） +- 用户体验改进（移动端响应式、TradingView图表、告警系统） + +📖 **详细路线图和时间表，请参阅：** +- **中文:** [路线图文档](../../roadmap/README.zh-CN.md) +- **English:** [Roadmap Documentation](../../roadmap/README.md) --- ## 🏗️ 技术架构 -``` -nofx/ -├── main.go # 程序入口（多trader管理器） -├── config.json # 配置文件（API密钥、~~多trader配置~~）(交易员配置通过Web界面) -│ -├── api/ # HTTP API服务 -│ └── server.go # Gin框架，RESTful API -│ -├── trader/ # 交易核心 -│ ├── auto_trader.go # 自动交易主控（单trader） -│ └── binance_futures.go # 币安合约API封装 -│ -├── manager/ # 多trader管理 -│ └── trader_manager.go # 管理多个trader实例 -│ -├── mcp/ # Model Context Protocol - AI通信 -│ └── client.go # AI API客户端（DeepSeek/Qwen集成） -│ -├── decision/ # AI决策引擎 -│ └── engine.go # 决策逻辑（含历史反馈） -│ -├── market/ # 市场数据获取 -│ └── data.go # 市场数据与技术指标（K线、RSI、MACD） -│ -├── pool/ # 币种池管理 -│ └── coin_pool.go # AI500 + OI Top合并池 -│ -├── logger/ # 日志系统 -│ └── decision_logger.go # 决策记录 + 表现分析 -│ -├── decision_logs/ # 决策日志存储 -│ ├── qwen_trader/ # Qwen trader日志 -│ └── deepseek_trader/ # DeepSeek trader日志 -│ -└── web/ # React前端 - ├── src/ - │ ├── components/ # React组件 - │ │ ├── EquityChart.tsx # 收益率曲线图 - │ │ ├── ComparisonChart.tsx # 多AI对比图 - │ │ └── CompetitionPage.tsx # 竞赛排行榜 - │ ├── lib/api.ts # API调用封装 - │ ├── types/index.ts # TypeScript类型 - │ ├── index.css # Binance风格样式 - │ └── App.tsx # 主应用 - └── package.json -``` +NOFX 采用现代化的模块化架构： -### 核心依赖 +- **后端：** Go + Gin 框架，SQLite 数据库 +- **前端：** React 18 + TypeScript + Vite + TailwindCSS +- **多交易所支持：** Binance、Hyperliquid、Aster DEX +- **AI 集成：** DeepSeek、Qwen 及自定义 OpenAI 兼容 API +- **状态管理：** 前端 Zustand，后端数据库驱动 +- **实时更新：** SWR，5-10 秒轮询间隔 -**后端 (Go)** -- `github.com/adshao/go-binance/v2` - 币安API客户端 -- `github.com/markcheno/go-talib` - 技术指标计算（TA-Lib） -- `github.com/gin-gonic/gin` - HTTP API框架 +**核心特性：** +- 🗄️ 数据库驱动的配置（无需编辑 JSON） +- 🔐 JWT 认证，支持可选的 2FA +- 📊 实时性能跟踪和分析 +- 🤖 多 AI 竞赛模式，实时对比 +- 🔌 RESTful API，完整的配置和监控 -**前端 (React + TypeScript)** -- `react` + `react-dom` - UI框架 -- `recharts` - 图表库（收益率曲线、对比图） -- `swr` - 数据获取和缓存 -- `tailwindcss` - CSS框架 +📖 **详细架构文档，请查看：** +- **中文版：** [架构文档](../../architecture/README.zh-CN.md) +- **English:** [Architecture Documentation](../../architecture/README.md) --- @@ -420,9 +420,9 @@ cd .. ~~**步骤1**：复制并重命名示例配置文件~~ -~~```bash +```bash cp config.example.jsonc config.json -```~~ +``` ~~**步骤2**：编辑`config.json`填入您的API密钥~~ @@ -897,79 +897,73 @@ curl http://localhost:8080/api/health 每个决策周期（默认3分钟），系统按以下流程运行： -``` -┌──────────────────────────────────────────────────────────┐ -│ 1. 📊 分析历史表现（最近20个周期） │ -├──────────────────────────────────────────────────────────┤ -│ ✓ 计算整体胜率、平均盈利、盈亏比 │ -│ ✓ 统计各币种表现（胜率、平均USDT盈亏） │ -│ ✓ 识别最佳/最差币种 │ -│ ✓ 列出最近5笔交易详情（含准确盈亏金额） │ -│ ✓ 计算夏普比率衡量风险调整后收益 │ -│ 📌 新增 (v2.0.2): 考虑杠杆的准确USDT盈亏计算 │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 2. 💰 获取账户状态 │ -├──────────────────────────────────────────────────────────┤ -│ • 账户净值、可用余额、未实现盈亏 │ -│ • 持仓数量、总盈亏（已实现+未实现） │ -│ • 保证金使用率（current/maximum） │ -│ • 风险评估指标 │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 3. 🔍 分析现有持仓（如果有） │ -├──────────────────────────────────────────────────────────┤ -│ • 获取每个持仓的市场数据（3分钟+4小时K线） │ -│ • 计算技术指标（RSI、MACD、EMA） │ -│ • 显示持仓时长（例如"持仓时长2小时15分钟"） │ -│ • AI判断是否需要平仓（止盈、止损或调整） │ -│ 📌 新增 (v2.0.2): 追踪持仓时长帮助AI决策 │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 4. 🎯 评估新机会（候选币种池） │ -├──────────────────────────────────────────────────────────┤ -│ • 获取AI500高评分币种（前20个） │ -│ • 获取OI Top持仓增长币种（前20个） │ -│ • 合并去重，过滤低流动性币种（持仓量<15M USD） │ -│ • 批量获取市场数据和技术指标 │ -│ • 为每个候选币种准备完整的原始数据序列 │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 5. 🧠 AI综合决策 │ -├──────────────────────────────────────────────────────────┤ -│ • 查看历史反馈（胜率、盈亏比、最佳/最差币种） │ -│ • 接收所有原始序列数据（K线、指标、持仓量） │ -│ • Chain of Thought 思维链分析 │ -│ • 输出决策：平仓/开仓/持有/观望 │ -│ • 包含杠杆、仓位、止损、止盈参数 │ -│ 📌 新增 (v2.0.2): AI可自由分析原始序列，不受预定义指标限制 │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 6. ⚡ 执行交易 │ -├──────────────────────────────────────────────────────────┤ -│ • 优先级排序：先平仓，再开仓 │ -│ • 精度自动适配（LOT_SIZE规则） │ -│ • 防止仓位叠加（同币种同方向拒绝开仓） │ -│ • 平仓后自动取消所有挂单 │ -│ • 记录开仓时间用于持仓时长追踪 │ -│ 📌 新增 (v2.0.2): 追踪持仓开仓时间 │ -└──────────────────────────────────────────────────────────┘ - ↓ -┌──────────────────────────────────────────────────────────┐ -│ 7. 📝 记录日志 │ -├──────────────────────────────────────────────────────────┤ -│ • 保存完整决策记录到 decision_logs/ │ -│ • 包含思维链、决策JSON、账户快照、执行结果 │ -│ • 存储完整持仓数据（数量、杠杆、开/平仓时间） │ -│ • 使用symbol_side键值防止多空冲突 │ -│ 📌 新增 (v2.0.2): 防止多空持仓冲突，考虑数量+杠杆 │ -└──────────────────────────────────────────────────────────┘ -``` +### 步骤1: 📊 分析历史表现（最近20个周期） +- ✓ 计算整体胜率、平均盈利、盈亏比 +- ✓ 统计各币种表现（胜率、平均USDT盈亏） +- ✓ 识别最佳/最差币种 +- ✓ 列出最近5笔交易详情（含准确盈亏金额） +- ✓ 计算夏普比率衡量风险调整后收益 +- 📌 **新增 (v2.0.2)**: 考虑杠杆的准确USDT盈亏计算 + +**↓** + +### 步骤2: 💰 获取账户状态 +- 账户净值、可用余额、未实现盈亏 +- 持仓数量、总盈亏（已实现+未实现） +- 保证金使用率（current/maximum） +- 风险评估指标 + +**↓** + +### 步骤3: 🔍 分析现有持仓（如果有） +- 获取每个持仓的市场数据（3分钟+4小时K线） +- 计算技术指标（RSI、MACD、EMA） +- 显示持仓时长（例如"持仓时长2小时15分钟"） +- AI判断是否需要平仓（止盈、止损或调整） +- 📌 **新增 (v2.0.2)**: 追踪持仓时长帮助AI决策 + +**↓** + +### 步骤4: 🎯 评估新机会（候选币种池） +- 获取币种池（2种模式）： + - 🌟 **默认模式**: BTC、ETH、SOL、BNB、XRP等 + - ⚙️ **高级模式**: AI500（前20） + OI Top（前20） +- 合并去重，过滤低流动性币种（持仓量<15M USD） +- 批量获取市场数据和技术指标 +- 为每个候选币种准备完整的原始数据序列 + +**↓** + +### 步骤5: 🧠 AI综合决策 +- 查看历史反馈（胜率、盈亏比、最佳/最差币种） +- 接收所有原始序列数据（K线、指标、持仓量） +- Chain of Thought 思维链分析 +- 输出决策：平仓/开仓/持有/观望 +- 包含杠杆、仓位、止损、止盈参数 +- 📌 **新增 (v2.0.2)**: AI可自由分析原始序列，不受预定义指标限制 + +**↓** + +### 步骤6: ⚡ 执行交易 +- 优先级排序：先平仓，再开仓 +- 精度自动适配（LOT_SIZE规则） +- 防止仓位叠加（同币种同方向拒绝开仓） +- 平仓后自动取消所有挂单 +- 记录开仓时间用于持仓时长追踪 +- 📌 追踪持仓开仓时间 + +**↓** + +### 步骤7: 📝 记录日志 +- 保存完整决策记录到 `decision_logs/` +- 包含思维链、决策JSON、账户快照、执行结果 +- 存储完整持仓数据（数量、杠杆、开/平仓时间） +- 使用 `symbol_side` 键值防止多空冲突 +- 📌 **新增 (v2.0.2)**: 防止多空持仓冲突，考虑数量+杠杆 + +**↓** + +**🔄 （每3-5分钟重复一次）** ### v2.0.2的核心改进 @@ -1248,77 +1242,19 @@ sudo apt-get install libta-lib0-dev ## 🔄 更新日志 -### v2.0.2 (2025-10-29) +📖 **详细的版本历史和更新，请查看：** -**关键Bug修复 - 交易历史记录与性能分析：** +- **中文版：** [CHANGELOG.zh-CN.md](../../../CHANGELOG.zh-CN.md) +- **English:** [CHANGELOG.md](../../../CHANGELOG.md) -本版本修复了历史交易记录和性能分析系统中的**严重计算错误**，这些错误严重影响了盈利统计的准确性。 +**最新版本：** v3.0.0 (2025-10-30) - 重大架构变革 -**1. 盈亏计算 - 重大错误修复** (logger/decision_logger.go) -- **问题**：之前只用百分比计算盈亏，完全忽略了仓位大小和杠杆倍数 - - 示例：100 USDT仓位赚5%和1000 USDT仓位赚5%都显示`5.0`作为盈利 - - 这导致性能分析完全不准确 -- **解决方案**：现在计算实际USDT盈亏金额 - ``` - 盈亏(USDT) = 仓位价值 × 价格变化% × 杠杆倍数 - 示例: 1000 USDT × 5% × 20倍 = 1000 USDT实际盈利 - ``` -- **影响**：胜率、盈亏比和夏普比率现在基于准确的USDT金额计算 - -**2. 持仓追踪 - 缺失关键数据** -- **问题**：开仓记录只存储了价格和时间，缺少数量和杠杆 -- **解决方案**：现在存储完整交易数据： - - `quantity`: 持仓数量（币数） - - `leverage`: 杠杆倍数（如20倍） - - 这些是准确计算盈亏的必要数据 - -**3. 持仓键值逻辑 - 多空冲突** -- **问题**：使用`symbol`作为持仓键值，导致同时持有多空仓时数据冲突 - - 示例：BTCUSDT多头和BTCUSDT空头会互相覆盖 -- **解决方案**：改为`symbol_side`格式（如`BTCUSDT_long`、`BTCUSDT_short`） - - 现在可以正确区分多空持仓 - -**4. 夏普比率计算 - 代码优化** -- **问题**：使用自定义的牛顿迭代法计算平方根 -- **解决方案**：替换为标准库`math.Sqrt` - - 更可靠、易维护且高效 - -**为什么这次更新很重要：** -- ✅ 历史交易统计现在显示**真实的USDT盈亏**而不是无意义的百分比 -- ✅ 不同杠杆倍数的交易对比现在准确了 -- ✅ AI自我学习机制接收到正确的历史反馈 -- ✅ 盈亏比和夏普比率计算现在有意义了 -- ✅ 多持仓追踪（同时持有多空）现在正常工作 - -**建议**：如果您在此更新前运行过系统，您的历史统计数据是不准确的。更新到v2.0.2后，新的交易将被正确计算。 - -### v2.0.1 (2025-10-29) - -**Bug修复:** -- ✅ 修复ComparisonChart数据处理逻辑 - 从cycle_number分组改为timestamp分组 -- ✅ 解决后端重启导致cycle_number重置时图表冻结的问题 -- ✅ 改进图表数据显示 - 现在按时间顺序显示所有历史数据点 -- ✅ 增强调试日志，便于问题排查 - -### v2.0.0 (2025-10-28) - -**重大更新:** -- ✅ AI自我学习机制（历史反馈、表现分析） -- ✅ 多Trader竞赛模式（Qwen vs DeepSeek） -- ✅ Binance风格UI（完整模仿币安界面） -- ✅ 性能对比图表（收益率实时对比） -- ✅ 风险控制优化（单币种仓位上限调整） - -**Bug修复:** -- 修复初始余额硬编码问题 -- 修复多trader数据同步问题 -- 优化图表数据对齐（使用cycle_number） - -### v1.0.0 (2025-10-27) -- 初始版本发布 -- 基础AI交易功能 -- 决策日志系统 -- 简单Web界面 +**近期亮点：** +- 🚀 完整系统重新设计，基于Web的配置平台 +- 🗄️ 数据库驱动架构（SQLite） +- 🎨 无需编辑JSON - 全部通过Web界面配置 +- 🔧 AI模型与交易所任意组合 +- 📊 增强的API层，提供全面的端点 --- diff --git a/docs/roadmap/README.md b/docs/roadmap/README.md new file mode 100644 index 00000000..9f203ff1 --- /dev/null +++ b/docs/roadmap/README.md @@ -0,0 +1,292 @@ +# 🗺️ NOFX Roadmap + +**Language:** [English](README.md) | [中文](README.zh-CN.md) + +Strategic plan for NOFX development and universal market expansion. + +--- + +## 📋 Overview + +NOFX is on a mission to become the **Universal AI Trading Operating System** for all financial markets. Our proven infrastructure on crypto markets is being extended to stocks, futures, options, forex, and beyond. + +**Vision:** Same architecture. Same agent framework. All markets. + +--- + +## 🎯 Short-Term Roadmap + +### Phase 1: Core Infrastructure Enhancement + +#### 1.1 Security Enhancements +**Goal:** Protect sensitive data and reduce security vulnerabilities + +- **Credential Management** + - [ ] Implement AES-256 encryption for API keys in database + - [ ] Add encryption for private keys (Hyperliquid, Aster) + - [ ] Use hardware security module (HSM) support for production + - [ ] Implement key rotation mechanism + - [ ] Add audit logging for all credential access + +- **Application Security** + - [ ] Input validation and sanitization (prevent SQL injection, XSS) + - [ ] Rate limiting for API endpoints + - [ ] CORS policy configuration + - [ ] JWT token expiration and refresh mechanism + - [ ] Implement RBAC (Role-Based Access Control) for multi-user support + - [ ] Add IP whitelisting for API access + - [ ] Security headers (CSP, HSTS, X-Frame-Options) + +- **Operational Security** + - [ ] Secure password hashing (bcrypt with salt) + - [ ] 2FA enhancement (backup codes, multiple TOTP devices) + - [ ] Session management (auto-logout, concurrent session limits) + - [ ] Secrets management (environment variables, vault integration) + - [ ] Regular dependency vulnerability scanning + +#### 1.2 Enhanced AI Capabilities +**Goal:** Richer prompts, flexible configuration, support for more AI models + +- **Prompt System Overhaul** + - [ ] Template engine for dynamic prompt generation + - [ ] Multi-language prompt support (chain-of-thought, few-shot, zero-shot) + - [ ] Market condition-based prompt switching (bull, bear, sideways) + - [ ] Historical performance feedback integration in prompts + - [ ] Prompt versioning and A/B testing framework + - [ ] User-customizable prompt templates via web interface + +- **AI Model Integration** + - [ ] OpenAI GPT-4/GPT-4 Turbo support + - [ ] Anthropic Claude 3 (Opus, Sonnet, Haiku) integration + - [ ] Google Gemini Pro support + - [ ] Local LLM support (Llama, Mistral via Ollama) + - [ ] Multi-model ensemble (voting, weighted average) + - [ ] Model performance tracking and auto-selection + - [ ] Fallback mechanism when primary model fails + +- **AI Decision Engine** + - [ ] Confidence scoring for each decision + - [ ] Explanation generation (why this trade?) + - [ ] Risk assessment integration in AI reasoning + - [ ] Market regime detection (trend, mean-reversion, high volatility) + - [ ] Cross-validation with technical indicators + +#### 1.3 Exchange Integration Expansion +**Goal:** Support more CEX and popular perp-DEX, both spot and futures + +- **Centralized Exchanges (CEX)** + - [ ] **OKX** - Futures + Spot trading + - [ ] **Bybit** - Futures + Spot trading + - [ ] **Bitget** - Futures + Spot trading + - [ ] **Gate.io** - Futures + Spot trading + - [ ] **KuCoin** - Futures + Spot trading + - [ ] Unified CEX interface for easy addition of new exchanges + +- **Decentralized Perpetual Exchanges (Perp-DEX)** + - [x] **Hyperliquid** (Ethereum L1) - High-performance orderbook DEX (✅ Supported) + - [x] **Aster** (Multi-chain) - Binance-compatible API DEX (✅ Supported) + - [ ] **Lighter** (Arbitrum) - Gasless orderbook DEX with off-chain matching + - [ ] **EdgeX** (Multi-chain) - Professional derivatives DEX + - [ ] Unified DEX interface for consistent integration + - [ ] Enhanced Hyperliquid integration (testnet support, advanced order types) + - [ ] Enhanced Aster integration (cross-chain support, wallet management) + +- **Spot + Futures Support** + - [ ] Dual-mode trading (spot arbitrage, futures hedging) + - [ ] Cross-exchange arbitrage detection + - [ ] Unified position tracking across spot and futures + - [ ] Auto-conversion between spot and perpetual strategies + +- **Exchange Infrastructure** + - [ ] **Trading Data Analysis API Integration** (In-house developed) + - [ ] AI500 integration - In-house AI-powered coin selection model + - [ ] OI (Open Interest) Analysis - Real-time open interest tracking and anomaly detection + - [ ] NetFlow Analysis - On-chain fund flow analysis for market sentiment + - [ ] Market sentiment aggregator - Combine multiple data sources for enhanced AI decision making + - [ ] Custom indicator API - Support for proprietary technical indicators + - [ ] Automatic precision handling (quantity, price decimals) + - [ ] Order type abstraction (market, limit, stop-loss, take-profit) + - [ ] Unified error handling and retry logic + - [ ] WebSocket support for real-time data + - [ ] Rate limit management per exchange + +#### 1.4 Project Structure Refactoring +**Goal:** Clear hierarchy, high cohesion, low coupling, easy to extend and maintain + +- **Architecture Redesign** + - [ ] Implement layered architecture (Presentation → Business Logic → Data Access) + - [ ] Apply SOLID principles (especially Liskov Substitution Principle for exchange adapters) + - [ ] Extract common interfaces for all exchange implementations + - [ ] Separate concerns: trading logic, data fetching, decision making, execution + - [ ] Implement dependency injection for better testability + +- **Code Organization** + - [ ] Refactor monolithic modules into smaller, focused packages + - [ ] Create abstract base classes for traders, exchanges, AI models + - [ ] Implement factory pattern for exchange/AI model creation + - [ ] Standardize error handling and logging across all modules + - [ ] Remove circular dependencies and improve import structure + +- **Configuration Management** + - [ ] Centralize all configuration in structured config files + - [ ] Implement hot-reload for non-critical configuration changes + - [ ] Validate configurations at startup with clear error messages + - [ ] Support environment-specific configs (dev/staging/production) + +#### 1.5 User Experience Improvements +**Goal:** Enhanced web interface, better monitoring, and alerting system + +- **Web Interface Enhancements** + - [ ] Mobile-responsive design (tablet and phone support) + - [ ] Dark/Light theme toggle with user preference saving + - [ ] Advanced charting with TradingView widget integration + - [ ] Real-time WebSocket updates (replace polling for positions/orders) + - [ ] Drag-and-drop dashboard customization + - [ ] Multi-language support (EN, CN, RU, UK) + +- **Configuration Interface** + - [ ] Visual strategy builder (no-code flow diagram) + - [ ] Live configuration preview before saving + - [ ] Configuration templates for common strategies + - [ ] Bulk trader management (start/stop multiple traders) + - [ ] Exchange credential testing (verify before saving) + - [ ] AI model testing interface (test prompts before deployment) + +- **Monitoring & Analytics** + - [ ] Real-time performance dashboard with key metrics + - [ ] Equity curve visualization (per trader, per exchange, overall) + - [ ] Drawdown analysis and risk metrics + - [ ] Trade history with filtering and search + - [ ] P&L breakdown by symbol, time period, strategy + - [ ] Comparison view (multiple traders side-by-side) + - [ ] Export functionality (CSV, JSON, PDF reports) + +- **Alert & Notification System** + - [ ] Multi-channel alerts (Email, Telegram, Discord, Webhook) + - [ ] Configurable alert rules (profit threshold, loss limit, error detection) + - [ ] Alert priority levels (critical, warning, info) + - [ ] Alert history and acknowledgment tracking + - [ ] Daily/Weekly performance summary emails + - [ ] System health monitoring (API connectivity, database status) + +### Phase 2: Testing & Stability + +#### 2.1 Quality Assurance +- [ ] Comprehensive unit test coverage (>80%) +- [ ] Integration tests for all exchange adapters +- [ ] Load testing (100+ concurrent traders) +- [ ] Security audit (API key encryption, SQL injection prevention) + +#### 2.2 Documentation +- [ ] Complete API reference documentation +- [ ] Video tutorials for beginners +- [ ] Strategy development guide +- [ ] Troubleshooting playbook + +#### 2.3 Community Features +- [ ] Public strategy marketplace (share/sell strategies) +- [ ] Leaderboard with verified performance +- [ ] Community forum integration +- [ ] Bug bounty program + +--- + +## 🚀 Long-Term Roadmap + +### Phase 3: Universal Market Expansion + +**Goal:** Extend the proven crypto trading infrastructure to all major financial markets. + +#### 3.1 Stock Markets +- [ ] US Equities (Interactive Brokers, Alpaca Markets) +- [ ] Asian Markets (A-shares, Hong Kong, Japan) +- [ ] Fundamental analysis integration (earnings, P/E, dividends) +- [ ] AI-powered stock screening + +#### 3.2 Futures Markets +- [ ] Commodity Futures (Energy, Metals, Agriculture) +- [ ] Index Futures (S&P 500, NASDAQ, Dow Jones, VIX) +- [ ] Rollover management and spread trading + +#### 3.3 Options Trading +- [ ] Options chain data and Greeks calculation +- [ ] Equity, Index, and Crypto options +- [ ] Options strategy builder + +#### 3.4 Forex Markets +- [ ] Major currency pairs and exotic pairs +- [ ] Interest rate analysis and carry trade support + +--- + +### Phase 4: Advanced AI & Automation + +**Goal:** Implement cutting-edge AI technologies for autonomous trading. + +- [ ] Multi-Agent orchestration (specialized agents with dynamic coordination) +- [ ] Reinforcement Learning (DQN, PPO, transfer learning) +- [ ] Alternative data integration (social sentiment, news, on-chain analytics) + +--- + +### Phase 5: Enterprise & Scaling + +**Goal:** Scale infrastructure for institutional use and high-volume trading. + +- [ ] Database migration (PostgreSQL/MySQL, Redis, TimescaleDB) +- [ ] Microservices architecture with Kubernetes deployment +- [ ] Multi-user RBAC and white-label solutions +- [ ] Advanced analytics and compliance reporting + +--- + +## 📊 Key Metrics & Milestones + +### Short-Term Targets +- [ ] **100+** supported trading pairs across all exchanges +- [ ] **10,000+** active trader instances +- [ ] **5+** new exchange integrations +- [ ] **80%+** test coverage +- [ ] **99.9%** uptime + +### Long-Term Targets +- [ ] **All major asset classes** supported (crypto, stocks, futures, options, forex) +- [ ] **50,000+** active users +- [ ] **Enterprise tier** launched +- [ ] **Institutional partnerships** established + +--- + +## 🤝 Community Involvement + +We welcome community contributions to accelerate our roadmap: + +- **Vote on Features**: Join our [Telegram community](https://t.me/nofx_dev_community) to vote on priority features +- **Contribute Code**: Check our [Contributing Guide](../../CONTRIBUTING.md) +- **Bug Bounties**: Report issues and earn rewards +- **Strategy Sharing**: Share your successful strategies + +--- + +## 📝 Roadmap Updates + +This roadmap is reviewed and updated quarterly based on: +- Community feedback +- Market demands +- Technical feasibility +- Resource availability + +**Last Updated:** 2025-11-01 + +--- + +## 📚 Related Documentation + +- [Architecture Documentation](../architecture/README.md) - Technical architecture details +- [Getting Started](../getting-started/README.md) - Setup and deployment +- [Contributing Guide](../../CONTRIBUTING.md) - How to contribute +- [Changelog](../../CHANGELOG.md) - Version history + +--- + +[← Back to Documentation Home](../README.md) diff --git a/docs/roadmap/README.zh-CN.md b/docs/roadmap/README.zh-CN.md new file mode 100644 index 00000000..a34921dd --- /dev/null +++ b/docs/roadmap/README.zh-CN.md @@ -0,0 +1,292 @@ +# 🗺️ NOFX 路线图 + +**语言:** [English](README.md) | [中文](README.zh-CN.md) + +NOFX 发展和通用市场扩展的战略规划。 + +--- + +## 📋 概述 + +NOFX 的使命是成为所有金融市场的**通用 AI 交易操作系统**。我们在加密货币市场上经过验证的基础设施正在扩展到股票、期货、期权、外汇等领域。 + +**愿景：** 相同架构。相同智能体框架。所有市场。 + +--- + +## 🎯 短期路线图 + +### 阶段1: 核心基础设施增强 + +#### 1.1 安全性增强 +**目标：** 保护敏感数据，减少安全漏洞 + +- **凭证管理** + - [ ] 为数据库中的API密钥实现AES-256加密 + - [ ] 为私钥（Hyperliquid、Aster）添加加密 + - [ ] 为生产环境支持硬件安全模块（HSM） + - [ ] 实现密钥轮换机制 + - [ ] 为所有凭证访问添加审计日志 + +- **应用安全** + - [ ] 输入验证和清理（防止SQL注入、XSS攻击） + - [ ] API端点的速率限制 + - [ ] CORS策略配置 + - [ ] JWT令牌过期和刷新机制 + - [ ] 实现RBAC（基于角色的访问控制）支持多用户 + - [ ] 添加API访问的IP白名单 + - [ ] 安全头部（CSP、HSTS、X-Frame-Options） + +- **运营安全** + - [ ] 安全密码哈希（bcrypt加盐） + - [ ] 2FA增强（备份码、多个TOTP设备） + - [ ] 会话管理（自动登出、并发会话限制） + - [ ] 密钥管理（环境变量、vault集成） + - [ ] 定期依赖项漏洞扫描 + +#### 1.2 增强AI能力 +**目标：** 更丰富的prompts、灵活配置、支持更多AI模型 + +- **Prompt系统全面改造** + - [ ] 动态prompt生成的模板引擎 + - [ ] 多语言prompt支持（思维链、few-shot、zero-shot） + - [ ] 基于市场状况的prompt切换（牛市、熊市、震荡） + - [ ] 在prompts中集成历史绩效反馈 + - [ ] Prompt版本控制和A/B测试框架 + - [ ] 通过Web界面自定义prompt模板 + +- **AI模型集成** + - [ ] OpenAI GPT-4/GPT-4 Turbo支持 + - [ ] Anthropic Claude 3（Opus、Sonnet、Haiku）集成 + - [ ] Google Gemini Pro支持 + - [ ] 本地LLM支持（通过Ollama的Llama、Mistral） + - [ ] 多模型集成（投票、加权平均） + - [ ] 模型性能跟踪和自动选择 + - [ ] 主模型失败时的降级机制 + +- **AI决策引擎** + - [ ] 每个决策的置信度评分 + - [ ] 解释生成（为什么做这笔交易？） + - [ ] AI推理中的风险评估集成 + - [ ] 市场状态检测（趋势、均值回归、高波动） + - [ ] 与技术指标的交叉验证 + +#### 1.3 交易所集成扩展 +**目标：** 支持更多CEX和流行的perp-DEX，现货和合约 + +- **中心化交易所（CEX）** + - [ ] **OKX** - 合约 + 现货交易 + - [ ] **Bybit** - 合约 + 现货交易 + - [ ] **Bitget** - 合约 + 现货交易 + - [ ] **Gate.io** - 合约 + 现货交易 + - [ ] **KuCoin** - 合约 + 现货交易 + - [ ] 统一的CEX接口，便于添加新交易所 + +- **去中心化永续交易所（Perp-DEX）** + - [x] **Hyperliquid**（Ethereum L1）- 高性能订单簿DEX（✅ 已支持） + - [x] **Aster**（多链）- Binance兼容API的DEX（✅ 已支持） + - [ ] **Lighter**（Arbitrum）- 无Gas订单簿DEX，链下撮合 + - [ ] **EdgeX**（多链）- 专业衍生品DEX + - [ ] 统一的DEX接口，保证集成一致性 + - [ ] 增强Hyperliquid集成（测试网支持、高级订单类型） + - [ ] 增强Aster集成（跨链支持、钱包管理） + +- **现货 + 合约支持** + - [ ] 双模式交易（现货套利、合约对冲） + - [ ] 跨交易所套利检测 + - [ ] 现货和合约的统一持仓跟踪 + - [ ] 现货和永续策略之间的自动转换 + +- **交易所基础设施** + - [ ] **交易数据分析API集成**（自研） + - [ ] AI500集成 - 自研AI选币模型 + - [ ] OI（持仓量）分析 - 实时持仓量跟踪和异常检测 + - [ ] NetFlow分析 - 链上资金流向分析，用于市场情绪判断 + - [ ] 市场情绪聚合器 - 整合多个数据源，增强AI决策能力 + - [ ] 自定义指标API - 支持专有技术指标 + - [ ] 自动精度处理（数量、价格小数位） + - [ ] 订单类型抽象（市价、限价、止损、止盈） + - [ ] 统一的错误处理和重试逻辑 + - [ ] 实时数据的WebSocket支持 + - [ ] 每个交易所的速率限制管理 + +#### 1.4 项目结构重构 +**目标：** 清晰层次、高内聚低耦合、易于扩展和维护 + +- **架构重新设计** + - [ ] 实现分层架构（表现层 → 业务逻辑层 → 数据访问层） + - [ ] 应用SOLID原则（特别是里氏替换原则用于交易所适配器） + - [ ] 为所有交易所实现提取通用接口 + - [ ] 分离关注点：交易逻辑、数据获取、决策制定、执行 + - [ ] 实现依赖注入以提高可测试性 + +- **代码组织** + - [ ] 将单体模块重构为更小、更专注的包 + - [ ] 为traders、exchanges、AI模型创建抽象基类 + - [ ] 实现工厂模式用于交易所/AI模型的创建 + - [ ] 标准化所有模块的错误处理和日志记录 + - [ ] 消除循环依赖并改进导入结构 + +- **配置管理** + - [ ] 将所有配置集中到结构化配置文件中 + - [ ] 实现非关键配置的热重载 + - [ ] 启动时验证配置并提供清晰的错误消息 + - [ ] 支持环境特定配置（dev/staging/production） + +#### 1.5 用户体验改进 +**目标：** 增强Web界面、更好的监控和告警系统 + +- **Web界面增强** + - [ ] 移动端响应式设计（平板和手机支持） + - [ ] 深色/浅色主题切换并保存用户偏好 + - [ ] TradingView小部件集成的高级图表 + - [ ] 实时WebSocket更新（替代持仓/订单的轮询） + - [ ] 拖拽式仪表板自定义 + - [ ] 多语言支持（EN、CN、RU、UK） + +- **配置界面** + - [ ] 可视化策略构建器（无代码流程图） + - [ ] 保存前的实时配置预览 + - [ ] 常用策略的配置模板 + - [ ] 批量trader管理（启动/停止多个traders） + - [ ] 交易所凭证测试（保存前验证） + - [ ] AI模型测试界面（部署前测试prompts） + +- **监控与分析** + - [ ] 实时性能仪表板和关键指标 + - [ ] 权益曲线可视化（每个trader、每个交易所、总体） + - [ ] 回撤分析和风险指标 + - [ ] 带过滤和搜索的交易历史 + - [ ] 按币种、时间段、策略的盈亏分解 + - [ ] 比较视图（多个traders并排） + - [ ] 导出功能（CSV、JSON、PDF报告） + +- **告警与通知系统** + - [ ] 多渠道告警（Email、Telegram、Discord、Webhook） + - [ ] 可配置的告警规则（利润阈值、亏损限制、错误检测） + - [ ] 告警优先级（严重、警告、信息） + - [ ] 告警历史和确认跟踪 + - [ ] 每日/每周性能摘要邮件 + - [ ] 系统健康监控（API连接、数据库状态） + +### 阶段2: 测试与稳定性 + +#### 2.1 质量保证 +- [ ] 全面的单元测试覆盖率（>80%） +- [ ] 所有交易所适配器的集成测试 +- [ ] 负载测试（100+并发交易者） +- [ ] 安全审计（API密钥加密、SQL注入防护） + +#### 2.2 文档 +- [ ] 完整的API参考文档 +- [ ] 新手视频教程 +- [ ] 策略开发指南 +- [ ] 故障排查手册 + +#### 2.3 社区功能 +- [ ] 公开策略市场（分享/出售策略） +- [ ] 经过验证的绩效排行榜 +- [ ] 社区论坛集成 +- [ ] 漏洞赏金计划 + +--- + +## 🚀 长期路线图 + +### 阶段3: 通用市场扩展 + +**目标：** 将经过验证的加密货币交易基础设施扩展到所有主要金融市场。 + +#### 3.1 股票市场 +- [ ] 美股（Interactive Brokers、Alpaca Markets） +- [ ] 亚洲市场（A股、香港、日本） +- [ ] 基本面分析集成（财报、市盈率、股息） +- [ ] AI驱动的股票筛选 + +#### 3.2 期货市场 +- [ ] 商品期货（能源、金属、农产品） +- [ ] 指数期货（标普500、纳斯达克、道琼斯、VIX） +- [ ] 展期管理和价差交易 + +#### 3.3 期权交易 +- [ ] 期权链数据和Greeks计算 +- [ ] 股票、指数和加密期权 +- [ ] 期权策略构建器 + +#### 3.4 外汇市场 +- [ ] 主要货币对和稀有货币对 +- [ ] 利率分析和套息交易支持 + +--- + +### 阶段4: 高级AI与自动化 + +**目标：** 实现前沿AI技术用于自主交易。 + +- [ ] 多智能体编排（专业化智能体与动态协调） +- [ ] 强化学习（DQN、PPO、迁移学习） +- [ ] 替代数据集成（社交情绪、新闻、链上分析） + +--- + +### 阶段5: 企业级与扩展 + +**目标：** 扩展基础设施以支持机构使用和高频交易。 + +- [ ] 数据库迁移（PostgreSQL/MySQL、Redis、TimescaleDB） +- [ ] 微服务架构与Kubernetes部署 +- [ ] 多用户RBAC和白标解决方案 +- [ ] 高级分析和合规报告 + +--- + +## 📊 关键指标与里程碑 + +### 短期目标 +- [ ] 所有交易所支持**100+**交易对 +- [ ] **10,000+**活跃交易者实例 +- [ ] **5+**新交易所集成 +- [ ] **80%+**测试覆盖率 +- [ ] **99.9%**正常运行时间 + +### 长期目标 +- [ ] 支持**所有主要资产类别**（加密、股票、期货、期权、外汇） +- [ ] **50,000+**活跃用户 +- [ ] **企业级**版本发布 +- [ ] 建立**机构合作伙伴关系** + +--- + +## 🤝 社区参与 + +我们欢迎社区贡献来加速我们的路线图： + +- **功能投票**: 加入我们的[Telegram社区](https://t.me/nofx_dev_community)投票优先功能 +- **贡献代码**: 查看我们的[贡献指南](../../CONTRIBUTING.md) +- **漏洞赏金**: 报告问题并获得奖励 +- **策略分享**: 分享你的成功策略 + +--- + +## 📝 路线图更新 + +本路线图根据以下因素每季度审查和更新： +- 社区反馈 +- 市场需求 +- 技术可行性 +- 资源可用性 + +**最后更新:** 2025-11-01 + +--- + +## 📚 相关文档 + +- [架构文档](../architecture/README.zh-CN.md) - 技术架构详情 +- [快速开始](../getting-started/README.zh-CN.md) - 设置和部署 +- [贡献指南](../../CONTRIBUTING.md) - 如何贡献 +- [更新日志](../../CHANGELOG.zh-CN.md) - 版本历史 + +--- + +[← 返回文档主页](../README.md)