docs: document four-exchange env sync script usage

Add docs/env-sync-scripts.md; cross-link from deploy README, feature docs, README, and script headers.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -18,7 +18,9 @@ cd crypto_monitor
 
 会为各子项目创建 `.venv`、安装依赖、从 `.env.example` 生成 `.env`（不覆盖已有）。详见 **[deploy/README.md](./deploy/README.md)**。
 
-计仓模式（以损定仓 / 全仓杠杆，四所统一）：见 **[docs/position-sizing-mode.md](./docs/position-sizing-mode.md)**。
+四所 `.env` 同步脚本（计仓 + 自动划转）：见 **[docs/env-sync-scripts.md](./docs/env-sync-scripts.md)**。  
+计仓模式（以损定仓 / 全仓杠杆）：见 **[docs/position-sizing-mode.md](./docs/position-sizing-mode.md)**。  
+每日自动划转（双向归集至目标 U）：见 **[docs/auto-transfer-daily.md](./docs/auto-transfer-daily.md)**。
 
 ---
 

deploy/README.md

@@ -85,31 +85,37 @@ bash deploy/setup_env.sh
 3. 服务器长期运行见各目录 **《部署文档.md》**（SSH SOCKS、PM2）。
 4. **多账户中控**（`manual_trading_hub`）：编辑 `manual_trading_hub/.env`（`HUB_PASSWORD`、`HUB_BRIDGE_TOKEN` 等与四实例一致），再 `pm2 start ecosystem.config.cjs`；验收 `bash manual_trading_hub/scripts/verify_hub_deploy.sh`。详见 [manual_trading_hub/部署文档.md](../manual_trading_hub/部署文档.md)、[常见问题.md](../manual_trading_hub/常见问题.md)。
 
-## 四所 `.env` 自动划转项（已有 .env 时）
+## 四所 `.env` 同步脚本（已有 .env 时）
 
-`AUTO_TRANSFER_AMOUNT` 等为交易账户目标余额（北京时间 8 点自动划入/划出，**持仓中不划转**并微信通知），与 `DAILY_START_CAPITAL` **独立**。若服务器上已有 `.env`，可合并写入（不覆盖 API 密钥）：
+在仓库根目录用 Python 脚本**补全或更新**四所 `crypto_monitor_*` 下的 `.env`（不覆盖 API 密钥；无 `.env` 的目录会跳过）。
 
 ```bash
-# 计仓 + 划转一次同步（缺项补全，不覆盖已有 API 与自定义值）
+cd /path/to/crypto_monitor
+git pull
+
+# 推荐：计仓 + 自动划转 一次补全
 python scripts/sync_four_exchange_env.py
-# 或仅划转：缺 AUTO_TRANSFER_AMOUNT 时默认 50（否则沿用已有 / DAILY_START_CAPITAL）
+
-python scripts/sync_four_exchange_transfer_env.py --set-amount 50 --enable-auto-transfer
+# 预览
+python scripts/sync_four_exchange_env.py --dry-run
+
+# 常见：划转目标 50U 并开启 + 计仓补全
+python scripts/sync_four_exchange_env.py --set-transfer-amount 50 --enable-auto-transfer
+
+# 无仓后切全仓杠杆
+python scripts/sync_four_exchange_env.py --set-mode full_margin
+
 pm2 restart crypto-monitor-binance crypto-monitor-okx crypto-monitor-gate crypto-monitor-gate-bot
 ```
 
-详见 [docs/auto-transfer-daily.md](../docs/auto-transfer-daily.md)。
+| 脚本 | 作用 |
+|------|------|
+| `scripts/sync_four_exchange_env.py` | 一键：计仓 + 划转 |
+| `scripts/sync_four_exchange_transfer_env.py` | 仅自动划转 |
+| `scripts/sync_four_exchange_position_sizing_env.py` | 仅计仓模式 |
 
-## 四所 `.env` 计仓模式项（已有 .env 时）
+**完整参数、缺项默认值与示例**见 **[docs/env-sync-scripts.md](../docs/env-sync-scripts.md)**。  
-
+功能说明：[计仓模式](../docs/position-sizing-mode.md)、[每日自动划转](../docs/auto-transfer-daily.md)。
-`POSITION_SIZING_MODE` / `FULL_MARGIN_BUFFER_RATIO` 仅能通过 env 切换；切换模式前须**无持仓**：
-
-```bash
-python scripts/sync_four_exchange_position_sizing_env.py
-# 无仓后切全仓：python scripts/sync_four_exchange_position_sizing_env.py --set-mode full_margin
-pm2 restart crypto-monitor-binance crypto-monitor-okx crypto-monitor-gate crypto-monitor-gate-bot
-```
-
-详见 [docs/position-sizing-mode.md](../docs/position-sizing-mode.md)。
 
 ## 依赖说明
 

docs/auto-transfer-daily.md

@@ -21,17 +21,25 @@ AUTO_TRANSFER_TO=swap
 AUTO_TRANSFER_BJ_HOUR=8
 ```
 
+`AUTO_TRANSFER_AMOUNT` 与 `DAILY_START_CAPITAL`（每日开仓基数）**独立**。
+
 API Key 须具备万向划转权限（与手动划转相同）。
 
-## 部署
+## 用脚本更新四所 `.env`
+
+详见 **[env-sync-scripts.md](./env-sync-scripts.md)**。常用命令：
 
 ```bash
 git pull
-# 四所补全划转项（已有值保留）
+
+# 仅补全划转相关项
 python scripts/sync_four_exchange_transfer_env.py
+
 # 目标 50U 并开启自动划转
 python scripts/sync_four_exchange_transfer_env.py --set-amount 50 --enable-auto-transfer
-# 计仓 + 划转一并同步
+
+# 计仓 + 划转一并补全
 python scripts/sync_four_exchange_env.py --set-transfer-amount 50 --enable-auto-transfer
+
 pm2 restart crypto-monitor-binance crypto-monitor-okx crypto-monitor-gate crypto-monitor-gate-bot
 ```

docs/env-sync-scripts.md

@@ -0,0 +1,116 @@
+# 四所 `.env` 同步脚本说明
+
+在**仓库根目录**执行。仅处理四所实例目录下的 `.env`，**不覆盖** API 密钥与已存在的自定义值；若某目录无 `.env` 会 `SKIP`（需先 `cp .env.example .env`）。
+
+| 目录 |
+|------|
+| `crypto_monitor_binance` |
+| `crypto_monitor_okx` |
+| `crypto_monitor_gate` |
+| `crypto_monitor_gate_bot` |
+
+修改 `.env` 后须 **`pm2 restart`** 对应实例后生效。
+
+---
+
+## 一键同步（推荐）
+
+`scripts/sync_four_exchange_env.py`：依次执行**计仓** + **自动划转** 两个子脚本。
+
+```bash
+cd /path/to/crypto_monitor
+git pull
+
+# 仅补全缺失项（已有值保留）
+python scripts/sync_four_exchange_env.py
+
+# 预览，不写文件
+python scripts/sync_four_exchange_env.py --dry-run
+
+# 划转目标 50U 并开启自动划转（计仓仍只补缺失项）
+python scripts/sync_four_exchange_env.py --set-transfer-amount 50 --enable-auto-transfer
+
+# 无仓后切换全仓杠杆（须先确认交易所无持仓）
+python scripts/sync_four_exchange_env.py --set-mode full_margin
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--dry-run` | 只打印将做的变更，不写 `.env` |
+| `--set-mode risk\|full_margin` | 强制四所 `POSITION_SIZING_MODE` |
+| `--set-transfer-amount U` | 强制四所 `AUTO_TRANSFER_AMOUNT` |
+| `--enable-auto-transfer` | 强制四所 `AUTO_TRANSFER_ENABLED=true` |
+
+---
+
+## 仅自动划转
+
+`scripts/sync_four_exchange_transfer_env.py`
+
+行为说明见 [auto-transfer-daily.md](./auto-transfer-daily.md)。
+
+```bash
+# 补全缺失项
+python scripts/sync_four_exchange_transfer_env.py
+python scripts/sync_four_exchange_transfer_env.py --dry-run
+
+# 目标 50U 并开启
+python scripts/sync_four_exchange_transfer_env.py --set-amount 50 --enable-auto-transfer
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--dry-run` | 预览 |
+| `--set-amount U` | 强制 `AUTO_TRANSFER_AMOUNT` |
+| `--enable-auto-transfer` | 强制 `AUTO_TRANSFER_ENABLED=true` |
+
+**缺项默认**（未使用 `--set-amount` 且文件中无该键时）：
+
+1. 若已有 `AUTO_TRANSFER_AMOUNT` → 保留  
+2. 否则若存在 `DAILY_START_CAPITAL` → 沿用其值  
+3. 否则 → **50**
+
+补全时会写入（若缺失）：`AUTO_TRANSFER_FROM=funding`、`AUTO_TRANSFER_TO=swap`、`TRANSFER_CCY=USDT`、`AUTO_TRANSFER_BJ_HOUR=8`；币安额外补 `BINANCE_FUNDING_INCLUDE_SPOT=false`。
+
+---
+
+## 仅计仓模式
+
+`scripts/sync_four_exchange_position_sizing_env.py`
+
+行为说明见 [position-sizing-mode.md](./position-sizing-mode.md)。
+
+```bash
+# 补全缺失项（默认 risk、FULL_MARGIN_BUFFER_RATIO=0.98）
+python scripts/sync_four_exchange_position_sizing_env.py
+python scripts/sync_four_exchange_position_sizing_env.py --dry-run
+
+# 无仓后切全仓
+python scripts/sync_four_exchange_position_sizing_env.py --set-mode full_margin
+
+# 无仓后切回以损定仓
+python scripts/sync_four_exchange_position_sizing_env.py --set-mode risk
+
+# 强制缓冲比例
+python scripts/sync_four_exchange_position_sizing_env.py --set-buffer 0.98
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--dry-run` | 预览 |
+| `--set-mode risk\|full_margin` | 强制 `POSITION_SIZING_MODE`（**须无持仓**后 restart） |
+| `--set-buffer RATIO` | 强制 `FULL_MARGIN_BUFFER_RATIO` |
+
+---
+
+## 部署后重启
+
+```bash
+pm2 restart crypto-monitor-binance crypto-monitor-okx crypto-monitor-gate crypto-monitor-gate-bot
+```
+
+## 相关文档
+
+- [计仓模式](./position-sizing-mode.md)
+- [每日自动划转](./auto-transfer-daily.md)
+- [部署说明](../deploy/README.md)

docs/position-sizing-mode.md

@@ -32,13 +32,24 @@ FULL_MARGIN_BUFFER_RATIO=0.98
 - 关键位：箱体突破、收敛突破、斐波自动单（添加时拒绝；已存在则启动时撤销）。
 - 趋势回调、顺势加仓（策略入口返回明确错误）。
 
-## 部署
+## 用脚本更新四所 `.env`
+
+详见 **[env-sync-scripts.md](./env-sync-scripts.md)**。常用命令：
 
 ```bash
 git pull
-# 四所 .env 补全计仓 + 划转（已有值不覆盖）
+
+# 仅补全计仓相关项（缺省 risk、缓冲 0.98）
+python scripts/sync_four_exchange_position_sizing_env.py
+
+# 无仓后切换全仓
+python scripts/sync_four_exchange_position_sizing_env.py --set-mode full_margin
+
+# 无仓后切回以损定仓
+python scripts/sync_four_exchange_position_sizing_env.py --set-mode risk
+
+# 计仓 + 划转一并补全
 python scripts/sync_four_exchange_env.py
-# 或仅计仓：python scripts/sync_four_exchange_position_sizing_env.py
+
-# 无仓后切换全仓：python scripts/sync_four_exchange_position_sizing_env.py --set-mode full_margin
 pm2 restart crypto-monitor-binance crypto-monitor-okx crypto-monitor-gate crypto-monitor-gate-bot
 ```

scripts/sync_four_exchange_env.py

@@ -10,6 +10,8 @@
 子脚本可单独运行：
   python scripts/sync_four_exchange_position_sizing_env.py
   python scripts/sync_four_exchange_transfer_env.py
+
+完整说明见 docs/env-sync-scripts.md
 """
 from __future__ import annotations
 

scripts/sync_four_exchange_position_sizing_env.py

@@ -10,6 +10,8 @@
 
 切换 POSITION_SIZING_MODE 须在交易所无持仓后执行，并 pm2 restart 对应实例。
 不修改 API 密钥与其它自定义项；若 .env 不存在则跳过（请先从 .env.example 复制）。
+
+完整说明见 docs/env-sync-scripts.md
 """
 from __future__ import annotations
 

scripts/sync_four_exchange_transfer_env.py

@@ -9,6 +9,8 @@
   python scripts/sync_four_exchange_transfer_env.py --enable-auto-transfer
 
 不修改 API 密钥与其它自定义项；若 .env 不存在则跳过（请先从 .env.example 复制）。
+
+完整说明见 docs/env-sync-scripts.md
 """
 from __future__ import annotations