dekun
b733e551a0
Add scripts/normalize_ambiguous_unicode.py; fix corrupted patch_instance_theme_templates.py. Preserves curly quotes in string literals; removes Git homoglyph warnings on .env.example. Co-authored-by: Cursor <cursoragent@cursor.com>
148 lines
5.5 KiB
Markdown
148 lines
5.5 KiB
Markdown
# lib/ 共用模块结构
|
|
|
|
三所实例与中控共用的 Python 库,模板与静态资源统一放在仓库根目录的 **`lib/`** 下.部署单元(`crypto_monitor_*`,`manual_trading_hub`)仍保持独立目录与 PM2 配置不变.
|
|
|
|
**重构前快照 Git 标签**:`pre-lib-modularization`(可用 `git checkout pre-lib-modularization` 查看旧布局).
|
|
**移除 gate_bot 前快照 Git 标签**:`pre-remove-gate-bot`.
|
|
|
|
---
|
|
|
|
## 顶层目录
|
|
|
|
```
|
|
crypto_monitor/
|
|
├── crypto_monitor_binance/ # 三所:各自 app + .env + PM2
|
|
├── crypto_monitor_gate/
|
|
├── crypto_monitor_okx/
|
|
├── manual_trading_hub/ # 中控 + 子代理 agent
|
|
│
|
|
├── lib/ # 共用模块(本说明)
|
|
│ ├── strategy/
|
|
│ ├── key_monitor/
|
|
│ ├── trade/
|
|
│ ├── hub/
|
|
│ ├── ai/
|
|
│ ├── instance/
|
|
│ ├── exchange/
|
|
│ ├── common/
|
|
│ └── paths.py
|
|
│
|
|
├── brand/ # 各所共用图标
|
|
├── docs/
|
|
├── deploy/
|
|
├── scripts/
|
|
├── tests/
|
|
├── requirements.txt
|
|
└── README.md
|
|
```
|
|
|
|
---
|
|
|
|
## lib/ 子包说明
|
|
|
|
| 子包 | 职责 | 主要模块 |
|
|
|------|------|----------|
|
|
| **`lib/strategy/`** | 策略交易(顺势加仓,趋势回调,快照与记录) | `strategy_register.py`,`strategy_trend_register.py`,`strategy_db.py`,`strategy_roll_*`,`strategy_trend_*` |
|
|
| **`lib/strategy/templates/`** | 策略页 Jinja 模板(原 `strategy_templates/`) | `strategy_trading_page.html`,`strategy_roll_panel.html` 等 |
|
|
| **`lib/key_monitor/`** | 关键位监控,斐波,假突破,止盈止损方案 | `key_monitor_lib.py`,`fib_key_monitor_lib.py`,`key_sl_tp_lib.py` 等 |
|
|
| **`lib/trade/`** | 下单监控展示,计仓,账户风控,手动 SL/TP | `order_monitor_display_lib.py`,`position_sizing_lib.py`,`account_risk_lib.py` 等 |
|
|
| **`lib/hub/`** | 中控 API,K 线,归档,计仓器,SSO/Bridge | `hub_bridge.py`,`hub_kline_store.py`,`hub_trades_lib.py` 等 |
|
|
| **`lib/ai/`** | AI 复盘与文本生成 | `ai_client.py`,`ai_review_lib.py` |
|
|
| **`lib/instance/`** | 中控 iframe 嵌入,导航,复盘图表 | `instance_embed_lib.py`,`focus_chart_lib.py`,`journal_chart_lib.py` |
|
|
| **`lib/instance/templates/`** | 嵌入页片段(原 `embed_templates/`) | `embed_page_fragment.html` |
|
|
| **`lib/exchange/`** | 特定交易所工具 | `gate_transfer_lib.py`,`okx_orders_lib.py` 等 |
|
|
| **`lib/common/`** | 跨功能小工具 | `form_submit_lib.py`,`wechat_notify_lib.py` 等 |
|
|
| **`lib/common/static/`** | 三所与中控共用的 JS/CSS(原根目录 `static/`) | `instance_theme.js`,`strategy_roll.js` 等 |
|
|
|
|
> **说明**:`hub_*` 命名表示「中控侧能力或行情聚合」,但部分模块(如 `hub_volume_rank_lib`,`hub_market_info_lib`)三所 `app.py` 也会调用,并非中控独占.
|
|
|
|
---
|
|
|
|
## 路径辅助函数
|
|
|
|
`lib/paths.py` 集中维护资源目录,避免硬编码:
|
|
|
|
```python
|
|
from lib.paths import strategy_templates_dir, embed_templates_dir, common_static_dir
|
|
|
|
strategy_templates_dir() # .../lib/strategy/templates
|
|
embed_templates_dir() # .../lib/instance/templates
|
|
common_static_dir() # .../lib/common/static
|
|
```
|
|
|
|
可选传入 `repo_root`(字符串或 `Path`),默认使用 `lib/` 的上级目录即仓库根.
|
|
|
|
---
|
|
|
|
## Python 导入约定
|
|
|
|
各部署目录在启动时将 **仓库根** 加入 `sys.path`(与重构前相同):
|
|
|
|
```python
|
|
_REPO_ROOT = os.path.dirname(BASE_DIR) # 或 Path(__file__).resolve().parent.parent
|
|
if _REPO_ROOT not in sys.path:
|
|
sys.path.insert(0, _REPO_ROOT)
|
|
```
|
|
|
|
之后使用 **`lib.<子包>.<模块>`** 形式导入,例如:
|
|
|
|
```python
|
|
from lib.strategy.strategy_db import init_strategy_tables
|
|
from lib.key_monitor.key_monitor_lib import check_key_monitors
|
|
from lib.hub.hub_bridge import install_on_app
|
|
from lib.ai.ai_client import ai_review
|
|
```
|
|
|
|
策略注册仍在各所 `app.py` 末尾:
|
|
|
|
```python
|
|
from lib.strategy.strategy_register import install_strategy_trading
|
|
from lib.strategy.strategy_trend_register import install_strategy_trend
|
|
|
|
install_strategy_trading(app, _REPO_ROOT, app_module=sys.modules[__name__])
|
|
install_strategy_trend(app, _REPO_ROOT, app_module=sys.modules[__name__])
|
|
```
|
|
|
|
---
|
|
|
|
## 静态资源与 URL
|
|
|
|
- 三所页面仍通过 **`/static/...`** 访问共用脚本;`hub_bridge.install_instance_theme_static` 从 `lib/common/static/` 提供部分根级静态路由.
|
|
- 各所目录下 **`static/`**(图标,上传图片等)仍为实例私有,未迁入 `lib/`.
|
|
- 中控 `manual_trading_hub/hub.py` 通过 `_REPO_ROOT / "lib" / "common" / "static"` 挂载与三所共用的 badge,复盘 JS 等.
|
|
|
|
---
|
|
|
|
## 测试
|
|
|
|
在仓库根执行(需将根目录置于 Python 路径,或从根目录运行):
|
|
|
|
```bash
|
|
cd /opt/crypto_monitor
|
|
python -m unittest discover -s tests -p "test_*.py"
|
|
```
|
|
|
|
测试文件内统一 `from lib.<子包>.<模块> import ...`.使用 `@patch` 时目标写完整模块路径,例如 `lib.hub.hub_calculator_lib._resolve_market`.
|
|
|
|
---
|
|
|
|
## 迁移脚本
|
|
|
|
一次性迁移由 `scripts/migrate_to_lib.py` 完成(移动文件 + 批量改写 import).**不要在已迁移后的仓库上重复执行**.
|
|
|
|
---
|
|
|
|
## 后续可选整理
|
|
|
|
- 三所 `app.py` 体量接近,可逐步抽取公共 `exchange_app` 基座(改动面大,单独规划).
|
|
- `manual_trading_hub/okx_orders_lib.py` 为 agent 本地副本,可与 `lib/exchange/okx_orders_lib.py` 合并去重.
|
|
- 可引入 `pyproject.toml` + `pip install -e .`,替代 `sys.path.insert`(长期维护更规范).
|
|
|
|
---
|
|
|
|
## 相关文档
|
|
|
|
- [README.md](../README.md) — 总览与部署
|
|
- [策略交易说明.md](../策略交易说明.md)
|
|
- [manual_trading_hub/使用说明.md](../manual_trading_hub/使用说明.md)
|