From 93d7fe76b640d4034eec7e8889918176a4947a29 Mon Sep 17 00:00:00 2001 From: gavindiaz Date: Tue, 21 Jul 2026 07:54:43 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20add=20=E5=90=8C=E6=AD=A5=E4=BD=9C?= =?UTF-8?q?=E8=80=85=E4=BB=A3=E7=A0=81=E6=8C=87=E5=8D=97.md=20-=20upstream?= =?UTF-8?q?=20sync=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- 同步作者代码指南.md | 295 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 295 insertions(+) create mode 100644 同步作者代码指南.md diff --git a/同步作者代码指南.md b/同步作者代码指南.md new file mode 100644 index 00000000..b28201f5 --- /dev/null +++ b/同步作者代码指南.md @@ -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） +```