gavindiaz/winning-wallet-finder
1
0
Fork 0
Code Issues Pull Requests Actions 52 Packages Projects Releases Wiki Activity

docs: add 同步作者代码指南.md - upstream sync guide

Browse Source 
Complete guide for syncing original author's code while preserving our
customizations. Covers:
- When to sync (monthly or when author publishes major updates)
- What's ours vs author's (table of files + handling)
- Why we discard our patches (author's fixes are better)
- 5-step sync process (sync-upstream.sh -> server update -> bankroll ->
  wallet config -> verify)
- Post-sync checklist (12 items)
- sync-upstream.sh OUR_FILES list (must update when adding new custom files)
- FAQ (7 common post-sync issues)
- File relationship diagram (GitHub -> Gitea -> server)
This commit is contained in:
gavindiaz
2026-07-21 07:54:43 +08:00
parent f5e136b874
commit 93d7fe76b6
1 changed files with 295 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
同步作者代码指南.md
+295
View File
@@ -0,0 +1,295 @@
# 同步原作者代码指南
> 原作者（GitHub: jaxperro/winning-wallet-finder）会持续更新代码。本文档说明如何安全地拉取作者的最新代码，同时保留我们的定制（dashboard、healthcheck、文档、钱包配置）。
>
> 适用于：任何接手这个项目的人类工程师或 AI 代理。
---
## 什么时候需要同步
- 原作者发布重大更新（bug 修复、新功能、性能优化）
- 我们遇到了作者已经解决的问题
- 定期同步（建议每月一次）
## 同步前必须了解
### 我们的代码 vs 原作者的代码
| 类型 | 文件 | 谁的 | 同步时怎么处理 |
|------|------|------|---------------|
| **核心代码** | copybot.py, copytrade.py, redeem.py | 原作者的 | **用作者的最新版**（丢弃我们的临时修复） |
| **筛选代码** | live/skill.py, conviction_scan.py, validate_timing.py | 原作者的 | **用作者的最新版** |
| **我们的 UI** | live/serve_dashboard.py, live/bot_dashboard.html | 我们的 | **保留我们的**（作者没有这些文件） |
| **我们的脚本** | host/mihomo-healthcheck.sh, live/sync_live_floors.py | 我们的 | **保留我们的** |
| **我们的文档** | DEPLOY.md, 日常使用.md, 问题排查与踩坑记录.md 等 | 我们的 | **保留我们的** |
| **配置** | config.live.json, live/copybot.paper.json | 我们的 | **保留我们的**（钱包列表 + bankroll） |
| **运行时数据** | copybot_state*.json, copybot_fills*.jsonl, live/copybot_live*.json | 自动生成 | **不跟踪**（.gitignore 已排除） |
### 为什么丢弃我们的临时修复
我们之前对 copybot.py 做过临时修复（late fill、cash anchor），但原作者的更新通常**从架构层面解决了同样的问题**，比我们的补丁更好：
| 我们的临时修复 | 原作者的正式修复 |
|---|---|
| late fill 重新查询 | FAK per-niche re-quote retry |
| cash anchor 自动对齐 | chain-balance gates |
| auto-absorb（已回滚，有 bug） | ghost purge + chain-clamped exits |
**同步时直接用作者的代码，丢掉我们的补丁。**
---
## 同步步骤
### 前提
本地仓库已配置两个 remote：
- `origin` -> 你的 Gitea 仓库
- `github` -> 原作者的 GitHub 仓库
如果没有 github remote：
```bash
git remote add github https://github.com/jaxperro/winning-wallet-finder.git
```
### 第 1 步：本地同步
在本地（Windows）跑同步脚本：
```bash
# 如果是 Windows，用 Git Bash 跑（需要代理访问 GitHub）
HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 bash sync-upstream.sh
```
`sync-upstream.sh` 自动完成：
1. 备份我们的定制文件到 `/tmp/wwf-ours/`
2. 拉取作者最新代码（`github/main`）
3. 恢复我们的定制文件
4. 推送到 Gitea
如果推送被拒（bot 自动 commit 导致）：
```bash
git push origin sync-upstream:main --force
```
### 第 2 步：服务器更新
SSH 上服务器，跑：
```bash
# 1. 停 bot
systemctl stop copybot-live copybot-paper
# 2. 拉新代码
cd /opt/winning-wallet-finder
git fetch origin
git reset --hard origin/main
# 3. 清 state（重要！git reset 会恢复作者的 state 文件）
rm -f copybot_state.json copybot_state.live.json copybot_fills.jsonl copybot_fills.live.jsonl live/copybot_live.json live/copybot_live_real.json
# 4. 更新健康检查脚本
cp host/mihomo-healthcheck.sh /opt/mihomo-healthcheck.sh
chmod +x /opt/mihomo-healthcheck.sh
# 5. 检查配置是否还在（config.live.json 是 gitignored，不会被覆盖）
ls -la config.live.json live/copybot.paper.json
```
### 第 3 步：更新 bankroll（如果链上余额变了）
```bash
# 查链上实际 pUSD 余额
export LIVE_PRIVATE_KEY=$(grep LIVE_PRIVATE_KEY /etc/copybot/live.env | cut -d= -f2-)
export HTTPS_PROXY=http://127.0.0.1:7890
python3 -c "from polymarket import SecureClient; c=SecureClient.create(private_key='$LIVE_PRIVATE_KEY'); b=c.get_balance_allowance(asset_type='COLLATERAL'); print('链上 pUSD: %.2f' % (b.balance/1e6)); c.close()"
# 用查到的数字更新 bankroll（替换 X.XX）
sed -i 's/"bankroll_usd": [0-9.]*/"bankroll_usd": X.XX/' config.live.json
```
### 第 4 步：检查钱包配置
确认 config.live.json 和 copybot.paper.json 的钱包列表一致：
```bash
echo "=== live ==="
python3 -c "import json; [print(w['name']) for w in json.load(open('config.live.json'))['wallets']]"
echo "=== paper ==="
python3 -c "import json; [print(w['name']) for w in json.load(open('live/copybot.paper.json'))['wallets']]"
```
如果不一致（作者的 reset 覆盖了我们的钱包），用我们的 8 个钱包重新配置：
```bash
python3 -c "
import json
wallets = [
{'wallet': '0xe8ca3f758c93f44f3ec210542ab78afb7c0bcccb', 'name': 'Kruto2027', 'class': 'volume', 'floor': 80.0},
{'wallet': '0xbadaf319415c17f28824a43ae0cd912b9d84d874', 'name': '0xbadaf319', 'class': 'volume', 'floor': 42.0},
{'wallet': '0xa1d57d329227c75b12b09f927fb3d6d6ef8f1343', 'name': '1kto1m', 'class': 'volume', 'floor': 332.0},
{'wallet': '0x2d462b29127b919ae4c085e03be44ae7077e3e2d', 'name': 'Vahan88', 'class': 'volume', 'floor': 245.0},
{'wallet': '0x41558102a796ba971c7567cad41c307e59f8fa41', 'name': 'LSB1', 'class': 'volume', 'floor': 315.0},
{'wallet': '0x0c3e55cf50a00a7e74fabd8584c6fdde21603c4c', 'name': 'EdwardIN', 'class': 'volume', 'floor': 25.0},
{'wallet': '0x82d2e4dbb0a849ff8e2f5380719769145648beea', 'name': 'lma0o0o0o', 'class': 'volume', 'floor': 25.0},
{'wallet': '0x69b9bd4fa27813091fcfe726541f2fd7baa3a5d5', 'name': 'Coteykens', 'class': 'volume', 'floor': 25.0},
]
for path in ['config.live.json', 'live/copybot.paper.json']:
cfg = json.load(open(path))
cfg['wallets'] = wallets
json.dump(cfg, open(path, 'w'), indent=2)
print(f'{path}: 8 wallets configured')
"
chown wwf:wwf config.live.json live/copybot.paper.json
```
> 钱包列表请根据当时 watch_sharps.json 的排名调整，不要盲目用上面的地址。
### 第 5 步：启动 + 验证
```bash
# 修权限
chown wwf:wwf config.live.json live/copybot.paper.json
# 启动
systemctl start copybot-paper
systemctl start copybot-live
sleep 15
# 验证
echo "=== paper ==="
journalctl -u copybot-paper --since "15 seconds ago" --no-pager | grep -E "bankroll|watching"
echo "=== live ==="
journalctl -u copybot-live --since "15 seconds ago" --no-pager | grep -E "bankroll|watching|armed|rtds|CASH"
```
预期：
- 两个 bot 都 `watching 8 wallets`
- live bot `armed`
- `rtds: connected`
- 无 `CASH≠CHAIN` 警告（如果 bankroll 设对了）
---
## 同步后检查清单
- [ ] 两个 bot 都 `active (running)`
- [ ] `watching 8 wallets`
- [ ] `armed`（live bot）
- [ ] `rtds: connected`
- [ ] `user-ws: connected`
- [ ] 无 `CASH≠CHAIN` 警告
- [ ] dashboard 能打开（`http://服务器IP:18080/`）
- [ ] dashboard 的 PAPER/LIVE 切换正常
- [ ] dashboard 的"系统健康"面板全绿
- [ ] 代理正常（`/opt/mihomo-healthcheck.sh && echo "正常"`）
- [ ] config.live.json 和 copybot.paper.json 钱包列表一致
---
## sync-upstream.sh 的定制文件清单
脚本会自动备份和恢复以下文件：
```bash
OUR_FILES=(
"live/serve_dashboard.py" # 我们的 dashboard 服务
"live/bot_dashboard.html" # 我们的中文界面
"host/mihomo-healthcheck.sh" # 我们的代理健康检查
"live/sync_live_floors.py" # 我们的 floor 同步脚本
"DEPLOY.md" # 部署指南
"USAGE.md" # 项目使用手册
"日常使用.md" # 日常运维手册
"问题排查与踩坑记录.md" # 踩坑记录
"mihomo代理部署教程.md" # 代理教程
"云端架构.md" # 架构说明
"实盘配置.md" # 实盘配置
"常用命令.md" # 命令速查
"项目流程.md" # 项目流程
"钱包筛选流程.md" # 筛选流程
)
```
如果以后新增了定制文件，**必须加到 `sync-upstream.sh` 的 `OUR_FILES` 数组里**，否则同步时会丢失。
---
## 常见问题
### Q: 同步后 bot 启动报 GEO-BLOCKED
代理节点切到了禁单地区。手动切回日本节点：
```bash
curl -s -X PUT http://127.0.0.1:9090/proxies/GLOBAL -H "Content-Type: application/json" -d '{"name":"🇯🇵日本高速06|BGP|CTCU"}'
```
### Q: 同步后 config.live.json 不见了
config.live.json 是 gitignored 的，`git reset --hard` 不会删它。如果真没了，从模板创建：
```bash
cp config.live.example.json config.live.json
# 然后改 bankroll + 钱包
```
### Q: 同步后 CASH≠CHAIN 警告
bankroll 跟链上余额不一致。查链上余额并更新：
```bash
export LIVE_PRIVATE_KEY=$(grep LIVE_PRIVATE_KEY /etc/copybot/live.env | cut -d= -f2-)
export HTTPS_PROXY=http://127.0.0.1:7890
python3 -c "from polymarket import SecureClient; c=SecureClient.create(private_key='$LIVE_PRIVATE_KEY'); b=c.get_balance_allowance(asset_type='COLLATERAL'); print('%.2f' % (b.balance/1e6)); c.close()"
# 用查到的数字更新 bankroll
sed -i 's/"bankroll_usd": [0-9.]*/"bankroll_usd": 查到的数字/' config.live.json
# 清 state 重启
systemctl stop copybot-live
rm -f copybot_state.live.json copybot_fills.live.jsonl live/copybot_live_real.json
systemctl start copybot-live
```
### Q: 同步后钱包列表变了（变成作者的）
`git reset --hard` 恢复了作者的 copybot.paper.json。用我们的钱包重新配置（见第 4 步）。
### Q: sync-upstream.sh 推送被拒
bot 自动 commit 导致远程有新 commit。强制推送：
```bash
git push origin sync-upstream:main --force
```
### Q: 同步后 daily.sh 报错（缺 edge.py 或 recorder/ingest.py）
作者新增的步骤。如果缺依赖会 `skip`（不影响主流程）。如果要完整运行，按作者的 README 安装依赖。
### Q: 怎么看作者改了什么
```bash
git fetch github
git log --oneline github/main -20 | grep -v "skip ci"
git diff main github/main --stat
git diff main github/main -- copybot.py | head -200
```
---
## 文件关系图
```
原作者 GitHub (github/main)
│
│ sync-upstream.sh
│ 1. 备份我们的文件
│ 2. 拉作者代码
│ 3. 恢复我们的文件
│ 4. 推到 Gitea
▼
我们的 Gitea (origin/main)
│
│ 服务器 git pull
▼
服务器 /opt/winning-wallet-finder/
├── 作者的代码（copybot.py 等）
├── 我们的 UI（serve_dashboard.py 等）
├── 我们的配置（config.live.json）
└── 运行时数据（state/feed，gitignored）
```