# 同步原作者代码指南

> 原作者（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）
```