khakhasshi · Copilot · Jan 21, 2026 · Jan 21, 2026 · Jan 21, 2026
diff --git a/README.md b/README.md
@@ -1,4 +1,10 @@
-# 🎯 Real-Time  Trading Monitor & Order Executor
+# 🎯 Real-Time Trading Monitor & Order Executor
+
+[English](#english-version) | [中文](#chinese-version)
+
+<a id="chinese-version"></a>
+
+## 中文版本
 
 该项目是一个基于 Longbridge API 实时拉取 **NVDA（英伟达）/当然也可以是其他标的美股数据/**，并通过 **键盘控制下单** 的 Python 程序，集成了可视化图表、持仓追踪和订单提交功能，适合用于交易策略测试与人工盯盘辅助操作。
 
@@ -23,28 +29,61 @@
 .
 ├── main.py             # 主程序
 ├── quote.json          # 用于缓存实时行情的临时文件（需提前创建）
+├── requirements.txt    # 项目依赖列表
 ├── README.md           # 使用说明
+└── LICENSE             # MIT 许可证
 ```
 
+## 📋 系统要求
+
+- Python 3.7+
+- 稳定的网络连接
+- Longbridge 开发者账号
+
 ## 🚀 安装步骤
 
-1. **安装依赖包**
+1. **克隆项目**
+
+```bash
+git clone https://github.com/khakhasshi/LongBridge_Fast_Submit.git
+cd LongBridge_Fast_Submit
+```
+
+2. **安装依赖包**
+
+方法一：使用 requirements.txt（推荐）
+
+```bash
+pip install -r requirements.txt
+```
+
+方法二：手动安装
 
 ```bash
 pip install longport matplotlib pynput
 ```
 
-2. **注册 Longbridge API**
+3. **注册 Longbridge API**
 
 前往 [https://open.longportapp.com/zh-CN/account](https://open.longportapp.com/zh-CN/account) 注册开发者账号，获取以下信息：
 
 - `APP Key`
 - `APP Secret`
 - `Access Token`
 
-将它们填入代码中的 `config = Config(...)` 中。
+4. **配置 API 密钥**
+
+在 `main.py` 中找到以下部分，将你的 API 密钥填入：
 
-3. **创建缓存文件**
+```python
+config = Config(
+    app_key="your_app_key_here",       # 替换为你的 APP Key
+    app_secret="your_app_secret_here", # 替换为你的 APP Secret
+    access_token="your_access_token"   # 替换为你的 Access Token
+)
+```
+
+5. **创建缓存文件**
 
 在项目目录下创建一个空的 `quote.json` 文件：
 
@@ -95,18 +134,244 @@ interval=100             # 动画刷新频率 (ms)
 ## 🛑 注意事项
 
 - 请确保网络连接稳定，避免 API 请求失败。
-- 避免在真实账户下频繁下单，建议先在模拟账户测试。
+- **强烈建议先在模拟账户测试**，避免在真实账户下频繁下单造成损失。
 - 持仓信息不记录历史，只追踪当前一次下单情况。
+- 本程序仅供学习和测试用途，实际交易请谨慎操作。
+- 请遵守当地法律法规和交易所规则。
+
+## ⚠️ 已知问题
+
+- 持仓追踪功能在某些情况下可能不显示信息（BUG）
+- 建议参考手机 App 上的成交价格和盈亏进行核对
+- 欢迎大佬帮忙修复相关 bug
+
+## 🔧 故障排除
+
+### 问题1：API 连接失败
+- 检查网络连接是否正常
+- 确认 API 密钥是否正确填写
+- 检查 Longbridge 服务是否正常运行
+
+### 问题2：quote.json 文件错误
+- 确保已创建空的 quote.json 文件
+- 检查文件权限是否正确
+
+### 问题3：键盘监听无响应
+- 确保程序窗口获得焦点
+- 检查键盘监听权限（macOS 可能需要授权）
+
+### 问题4：图表不更新
+- 检查 API 调用是否成功
+- 查看控制台是否有错误信息
+- 确认市场是否开盘
 
 ## 📌 未来可拓展方向
 
 - 添加止盈/止损逻辑
 - 增加自动交易策略
 - 多标的支持（可自定义）
 - 持仓记录保存与分析
+- 修复持仓显示 BUG
+- 增加订单历史记录
+- 支持多账户管理
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📄 许可证
+
+本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情
 
 ---
 
 如需协助或有任何建议，欢迎提 issue 或联系项目开发者。
 
 Happy Trading! 📈💻
+
+---
+
+## English Version
+
+This is a Python-based real-time trading monitor and order execution system built on the Longbridge API. It provides real-time price tracking for **NVDA (NVIDIA)** or other US stocks, with **keyboard-controlled order submission**, integrated visualization charts, position tracking, and order submission features. Ideal for trading strategy testing and manual monitoring assistance.
+
+## 📦 Features
+
+- ⏱ Real-time quotes (NVDA.US, up to 10 times per second)
+- 📉 Three chart views:
+  - All price history
+  - Last 5 minutes price movement
+  - Last 60 seconds price movement
+- 💼 Position tracking:
+  - Display long/short position info, entry price, current price, real-time P&L (for reference only; known display bugs exist - check mobile app for accurate prices)
+- ⌨️ Keyboard trading:
+  - `N` key for long (Buy)
+  - `M` key for short (Sell)
+  - `Q` key to quit
+- 🎮 Real-time interaction + dynamic chart updates
+
+## 🧱 Project Structure
+
+```bash
+.
+├── main.py             # Main program
+├── quote.json          # Temporary file for caching real-time quotes (needs to be created)
+├── requirements.txt    # Project dependencies
+├── README.md           # Documentation
+└── LICENSE             # MIT License
+```
+
+## 📋 Prerequisites
+
+- Python 3.7+
+- Stable internet connection
+- Longbridge developer account
+
+## 🚀 Installation
+
+1. **Clone the repository**
+
+```bash
+git clone https://github.com/khakhasshi/LongBridge_Fast_Submit.git
+cd LongBridge_Fast_Submit
+```
+
+2. **Install dependencies**
+
+Method 1: Using requirements.txt (recommended)
+
+```bash
+pip install -r requirements.txt
+```
+
+Method 2: Manual installation
+
+```bash
+pip install longport matplotlib pynput
+```
+
+3. **Register for Longbridge API**
+
+Visit [https://open.longportapp.com/zh-CN/account](https://open.longportapp.com/zh-CN/account) to register for a developer account and obtain:
+
+- `APP Key`
+- `APP Secret`
+- `Access Token`
+
+4. **Configure API credentials**
+
+In `main.py`, locate and fill in your API credentials:
+
+```python
+config = Config(
+    app_key="your_app_key_here",       # Replace with your APP Key
+    app_secret="your_app_secret_here", # Replace with your APP Secret
+    access_token="your_access_token"   # Replace with your Access Token
+)
+```
+
+5. **Create cache file**
+
+Create an empty `quote.json` file in the project directory:
+
+```bash
+touch quote.json
+```
+
+## 🎯 Usage
+
+After running the program, a chart window will appear with console prompts:
+
+```
+Press N to Buy (long), M to Sell (short), Q to Quit.
+```
+
+- Press `N`: Submit a **long** market order (25 shares)
+- Press `M`: Submit a **short** market order (25 shares)
+- Press `Q`: Exit the program
+
+## 📊 Visualization Interface
+
+The chart has four areas:
+
+- 📈 Top left: Full price history
+- ⏱ Top right: Last 5 minutes price movement
+- ⏱ Bottom left: Last 60 seconds price movement
+- 💼 Bottom right: Current position info (direction, entry price, current price, P&L)
+
+## ⚙️ Configuration
+
+You can modify trading parameters in the `position` dictionary:
+
+```python
+position = {
+    'type': None,
+    'entry_price': None,
+    'quantity': 25  # Shares per buy/sell order
+}
+```
+
+Quote fetching and chart refresh rate is set to 0.1 seconds:
+
+```python
+time.sleep(0.1)          # Fetch frequency
+interval=100             # Animation refresh rate (ms)
+```
+
+## 🛑 Important Notes
+
+- Ensure stable network connection to avoid API request failures.
+- **Strongly recommended to test with a demo account first** to avoid losses from frequent real account trading.
+- Position info does not track history, only current single order.
+- This program is for learning and testing purposes only. Trade carefully in real scenarios.
+- Comply with local laws, regulations, and exchange rules.
+
+## ⚠️ Known Issues
+
+- Position tracking feature may not display information in certain cases (BUG)
+- Recommend cross-checking with mobile app for accurate trade prices and P&L
+- Contributions to fix these bugs are welcome!
+
+## 🔧 Troubleshooting
+
+### Issue 1: API Connection Failed
+- Check network connection
+- Verify API credentials are correct
+- Confirm Longbridge service is running
+
+### Issue 2: quote.json File Error
+- Ensure empty quote.json file is created
+- Check file permissions
+
+### Issue 3: Keyboard Not Responding
+- Ensure program window has focus
+- Check keyboard listener permissions (macOS may require authorization)
+
+### Issue 4: Chart Not Updating
+- Check if API calls are successful
+- Look for error messages in console
+- Confirm market is open
+
+## 📌 Future Enhancements
+
+- Add take-profit/stop-loss logic
+- Implement automated trading strategies
+- Multi-symbol support (customizable)
+- Position history tracking and analysis
+- Fix position display bugs
+- Add order history records
+- Support multi-account management
+
+## 🤝 Contributing
+
+Issues and Pull Requests are welcome!
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
+
+---
+
+For assistance or suggestions, feel free to open an issue or contact the project developer.
+
+Happy Trading! 📈💻
diff --git a/requirements.txt b/requirements.txt
@@ -0,0 +1,3 @@
+longport>=0.2.0
+matplotlib>=3.5.0
+pynput>=1.7.6