# AGENT.md - AI 代理协作指南：每周钱包 Review

> 本文档供 AI 代理（如 Claude）与人类协作完成每周钱包 review。人类从云端提供数据，AI 代理在本地分析并给出建议。
>
> 流程严格遵循原作者（GitHub: jaxperro）的方法论。

---

## 概览

```
每周五 Review 流程：

人类从云端拉数据 → AI 代理分析 → 人类决策 → 人类在云端执行

  ┌─────────────┐     ┌──────────────┐     ┌──────────┐     ┌──────────────┐
  │ 人类：从云端  │     │ AI：分析 5 个  │     │ 人类：   │     │ 人类：在云端  │
  │ 拉取 6 份数据 │ ──→ │ 维度 + 给建议 │ ──→ │ 最终决策 │ ──→ │ 执行变更     │
  └─────────────┘     └──────────────┘     └──────────┘     └──────────────┘
```

---

## 第一部分：钱包筛选的完整链路

### 三层结构

```
第一层：watch_sharps.json（自动，每天变）
  daily.sh 自动筛选：enumerate → collect → skill → conviction_scan → validate_timing
  产出：统计上"费后可复制"的钱包列表（最近 35 个）
  含义：这些钱包 PAST 表现好（in-sample）
  ⚠️ 不能直接用这个排名选钱包！copy_pnl 是历史数据算的

第二层：backtest.json（手动，相对稳定）
  人类从 watch_sharps 里挑候选，放进 backtest.json
  daily.sh 每天对 backtest.json 里的钱包跑 portfolio.py 前瞻回测
  含义：这些钱包的 FORWARD 表现被持续追踪（out-of-sample）
  ⚠️ 这是决策的核心数据源

第三层：copybot.paper.json / config.live.json（手动，最终跟单）
  从 backtest.json 里挑表现好的放进跟单配置
  bot 实际跟这些钱包的信念单
  含义：这些是"上场名单"
```

### 关键区别：copy_pnl vs 前瞻 realized

| | copy_pnl（watch_sharps.json） | realized（portfolio.json） |
|---|---|---|
| 是什么 | 用历史数据模拟"如果跟着赚多少" | 实际回测"过去 30 天跟了之后赚多少" |
| 数据类型 | in-sample（用同一批数据算的） | out-of-sample（前瞻测试） |
| 可信度 | ⚠️ 会骗人 | ✅ 真实 |
| 实例 | oliman2 copy_pnl #1 (+4735) | oliman2 前瞻 realized -$143 |

**实例证明**：oliman2 在 watch_sharps 里 copy_pnl 排名 #1，但前瞻 30 天实际亏 $143。leegunner copy_pnl #2，前瞻亏 $180。**前瞻 realized 才是决策依据。**

---

## 第二部分：每周五 Review 流程

### 第 1 步：人类从云端拉取 6 份数据

人类在服务器上跑以下命令，把输出复制给 AI 代理：

#### 数据 1：前瞻盈亏排名（最重要）

```bash
cd /opt/winning-wallet-finder/live && python3 portfolio.py --days 30 && python3 -c "
import json
d = json.load(open('portfolio.json'))
live_names = {'Kruto2027','0xbadaf319','1kto1m','Vahan88','LSB1','EdwardIN','lma0o0o0o','Coteykens'}
ws = d.get('wallets', [])
print('=== 30天前瞻盈亏排名 ===')
for w in sorted(ws, key=lambda x: x.get('realized',0), reverse=True):
    name = w.get('name','?')
    tag = 'LIVE' if name in live_names else 'bench'
    wr = w.get('won',0)/(w.get('bets',1))*100 if w.get('bets',0) > 0 else 0
    print(f'{name:20s} bets={w.get(\"bets\",0):3d} W={w.get(\"won\",0):2d} L={w.get(\"lost\",0):2d} S={w.get(\"sold\",0):2d} realized=\${w.get(\"realized\",0):+9.2f} winrate={wr:.0f}% [{tag}]')
print(f'\n总计: equity \${d[\"equity\"]:,.0f} | realized \${d[\"realized\"]:+,.0f} | {d[\"resolved_count\"]} resolved')
"
```

#### 数据 2：watch_sharps 候选排名

```bash
cat /opt/winning-wallet-finder/live/watch_sharps.json | python3 -c "
import sys,json
data=json.load(sys.stdin)
data.sort(key=lambda w: w.get('copy_pnl',0), reverse=True)
print('=== watch_sharps 候选排名 ===')
for i,w in enumerate(data):
    name = w.get('name') or w.get('wallet','')[:10]
    win = w.get('conv_win')
    winstr = f'{win:.0f}%' if win is not None else '?'
    print(f'#{i+1:2d} {name:20s} copy_pnl+{w.get(\"copy_pnl\",0):5d} conv_win={winstr} fwd_win={w.get(\"fwd_win\",0):.0f}%')
print(f'\n总共 {len(data)} 个候选')
"
```

#### 数据 3：当前跟单配置

```bash
echo "=== copybot.paper.json ===" && python3 -c "
import json
cfg = json.load(open('/opt/winning-wallet-finder/live/copybot.paper.json'))
for w in cfg['wallets']:
    pin = f' PIN={w[\"floor_pin\"]}' if w.get('floor_pin') else ''
    print(f'{w[\"name\"]:20s} floor=\${w.get(\"floor\",0):.0f}{pin}')
" && echo "=== config.live.json ===" && python3 -c "
import json
cfg = json.load(open('/opt/winning-wallet-finder/config.live.json'))
print(f'bankroll: \${cfg[\"bankroll_usd\"]}')
for w in cfg['wallets']:
    pin = f' PIN={w[\"floor_pin\"]}' if w.get('floor_pin') else ''
    print(f'{w[\"name\"]:20s} floor=\${w.get(\"floor\",0):.0f}{pin}')
"
```

#### 数据 4：bench 观察区

```bash
python3 -c "
import json
live = {w['wallet'].lower() for w in json.load(open('/opt/winning-wallet-finder/live/copybot.paper.json'))['wallets']}
bt = json.load(open('/opt/winning-wallet-finder/live/backtest.json'))
bench = [w.get('name', w['wallet'][:10]) for w in bt['wallets'] if w['wallet'].lower() not in live]
print('bench 观察区:', ', '.join(bench))
print(f'backtest.json 总共 {len(bt[\"wallets\"])} 个钱包')
"
```

#### 数据 5：live bot 最近表现

```bash
journalctl -u copybot-live --since "7 days ago" --no-pager | grep -E "^\[.*\] \[" | tail -20
```

#### 数据 6：sync_floors 警告（floor 漂移）

```bash
grep -E "floor.*->|⚠.*floor" /opt/winning-wallet-finder/live/daily.log | tail -10
```

### 第 2 步：AI 代理分析（5 个维度）

AI 代理拿到 6 份数据后，按以下 5 个维度分析每个钱包：

#### 维度 1：前瞻盈亏（权重 ★★★★★）

**数据来源**：数据 1 的 realized 列

**判断规则**：
- `realized > 0` 且笔数 ≥ 10 -> ✅ 保留
- `realized > 0` 但笔数 < 5 -> ⚠️ 样本不足，保留但观察
- `realized < 0` 连续 2 周 -> ❌ 降级到 bench
- `realized < 0` 第一周 -> ⚠️ 警告，下周再看

**对比基准**：LIVE 钱包的前瞻盈亏 vs bench 钱包的前瞻盈亏。如果某个 bench 钱包的前瞻盈亏明显高于某个 LIVE 钱包，考虑替换。

#### 维度 2：copy_pnl（权重 ★★★★）

**数据来源**：数据 2 的 copy_pnl 列

**判断规则**：
- copy_pnl > 0 且排名靠前 -> 候选
- copy_pnl 跌出 watch_sharps -> ❌ 被自动淘汰，必须踢
- ⚠️ copy_pnl 高 ≠ 前瞻好（oliman2 的教训）

#### 维度 3：信念胜率 conv_win（权重 ★★★）

**数据来源**：数据 2 的 conv_win 列

**判断规则**：
- conv_win > 70% -> 优秀
- conv_win 50-70% -> 正常
- conv_win < 40% -> ⚠️ 信念单胜率低，谨慎
- conv_win < 25% -> ❌ 建议踢（如 BikesAreTheBikes 21%）

#### 维度 4：季节性催化剂 + niche 分析（权重 ★★）

**数据来源**：需要人类提供信息（AI 代理无法自动判断）+ 服务器上查 cache

**人类需要告诉 AI**：
- 某钱包主要交易什么类型的市场（电竞/足球/BTC/政治等）
- 是否有即将到来的赛事/事件（如 Esports World Cup、世界杯、选举等）

**在服务器上查钱包 niche**：
```bash
python3 -c "
import cache
bets = cache.get_bets('WALLET_ADDRESS')
from collections import Counter
titles = [b.get('title','?')[:30] for b in bets[-50:]]
# 看最近 50 笔交易的市场类型
for t in titles[-20:]:
    print(t)
"
```

**判断规则**：
- niche 是 ITF 网球 / 三级电竞（CCT CS、Dota 2 EPL）-> ✅ 强 edge 信号（作者研究发现真正的 edge 集中在这些市场）
- niche 有赛季/事件即将开始 -> 加分（如 AIcAIc 在电竞赛季）
- niche 赛季结束 -> 减分
- niche 是 5min BTC Up/Down -> ❌ 永不跟（结算比跟单快，跟不上）
- niche 是高频 scalp（买入后几秒卖出）-> ❌ 不跟（scalper 的胜率是假的，复制后亏钱）
- 持仓时间 > 7 天才结算 -> ⚠️ 长持仓杀死复利（如 leegunner 7.6 天持仓，前瞻亏 $180）
- 入场价集中在 0.40-0.60 -> ✅ 真正的 50/50 市场（edge 来源）
- 入场价集中在 > 0.90 -> ⚠️ favorite-rider（赔率薄，手续费吃掉利润）

**作者的研究结论（FINDINGS.md）**：
- 最赚钱的钱包做的是低级别网球 + 三级电竞，入场价 ~0.50，提前 ~160 小时入场
- 这可能是"内幕信息"（比赛操纵相关），但因为入场早所以可以被复制
- **edge 可能随时消失**：作者的一个顶级钱包在分析过程中突然从 API 消失了
- 每个月都可能是 edge 的最后一个月，每周重新评估，赚钱了就取出来

#### 维度 5：floor 稳定性（权重 ★）

**数据来源**：数据 6 的 sync_floors 警告

**判断规则**：
- 无警告 -> 正常
- `⚠ floor X->Y` 漂移 > 15% -> 建议钉死 floor_pin
- 已有 floor_pin -> 不受影响

### 第 3 步：AI 代理输出建议

AI 代理根据 5 个维度的分析，输出一份结构化建议：

```
=== 每周 Bench Review 建议 ===

当前 LIVE 钱包评估：
  [钱包名] 前瞻+$XXX 笔数XX 胜率XX% -> ✅保留 / ⚠️观察 / ❌降级
  ...

bench 晋升候选：
  [钱包名] 前瞻+$XXX 笔数XX 胜率XX% -> ⬆️建议晋升 / ❌不建议
  ...

floor 调整建议：
  [钱包名] floor $XX -> $YY 漂移大，建议钉 floor_pin=XX
  ...

季节性提醒：
  [钱包名] 的 [niche] 赛季 [即将开始/即将结束]
  ...

本周操作建议：
  1. [具体操作]
  2. [具体操作]
  ...
```

### 第 4 步：人类决策

人类根据 AI 建议做最终决策。AI 只建议，人类拍板。

### 第 5 步：人类在云端执行

#### 晋升（bench -> live）

```bash
cd /opt/winning-wallet-finder

python3 -c "
import json
promote_name = 'WALLET_NAME'  # 改成要晋升的

bt = json.load(open('live/backtest.json'))
promote = next((w for w in bt['wallets'] if w.get('name') == promote_name), None)
if not promote:
    print(f'{promote_name} not found in backtest.json'); exit(1)

for path in ['live/copybot.paper.json', 'config.live.json']:
    cfg = json.load(open(path))
    if not any(w['wallet'].lower() == promote['wallet'].lower() for w in cfg['wallets']):
        cfg['wallets'].append({'wallet': promote['wallet'], 'name': promote['name'],
                                'class': 'volume', 'floor': 25.0})
        json.dump(cfg, open(path, 'w'), indent=2)
        print(f'{path}: added {promote_name}')
"

chown wwf:wwf live/copybot.paper.json config.live.json
systemctl restart copybot-paper copybot-live
sleep 10
journalctl -u copybot-live --since "10 seconds ago" --no-pager | grep "watching"
```

#### 降级（live -> bench）

钱包留在 backtest.json 继续观察，只从跟单配置里删除：

```bash
cd /opt/winning-wallet-finder

python3 -c "
import json
demote_name = 'WALLET_NAME'  # 改成要降级的

for path in ['live/copybot.paper.json', 'config.live.json']:
    cfg = json.load(open(path))
    old = [w['name'] for w in cfg['wallets']]
    cfg['wallets'] = [w for w in cfg['wallets'] if w['name'] != demote_name]
    json.dump(cfg, open(path, 'w'), indent=2)
    print(f'{path}: {old} -> {[w[\"name\"] for w in cfg[\"wallets\"]]}')
"

chown wwf:wwf live/copybot.paper.json config.live.json
systemctl restart copybot-paper copybot-live
```

#### 钉死 floor_pin

```bash
python3 -c "
import json
pin_name = 'WALLET_NAME'
pin_value = 80.0

for path in ['live/copybot.paper.json', 'config.live.json']:
    cfg = json.load(open(path))
    for w in cfg['wallets']:
        if w['name'] == pin_name:
            w['floor'] = pin_value
            w['floor_pin'] = pin_value
            print(f'{path}: {pin_name} floor_pin = {pin_value}')
    json.dump(cfg, open(path, 'w'), indent=2)
"

chown wwf:wwf live/copybot.paper.json config.live.json
systemctl restart copybot-paper copybot-live
```

#### 更新 setup_wallets.py（记录变更）

改完钱包后，同步更新 `live/setup_wallets.py` 里的 `OUR_WALLETS` 数组，下次 sync-upstream 时不会丢。

---

## 第三部分：日志分析

### 怎么从日志发现问题

#### 问题 1：钱包不跟单（FOLLOW 但不 OPEN）

```bash
# 看某个钱包最近的信号和跟单情况
journalctl -u copybot-live --since "24 hours ago" --no-pager | grep "WALLET_NAME"
```

日志关键字：
- `FOLLOW` = 检测到信号，准备跟
- `skip` = 跳过（看原因：`< conviction floor` / `book unreliable` / `held before`）
- `OPEN` = 下单了
- `PENDING` = 订单挂起中
- `pending expired unfilled` = 订单没成交
- `re-quote retry` = FAK 重试（作者新代码）
- `MISS` = 信号太晚（跟不上了）

**分析示例**：
```
FOLLOW Vahan88: BUY JA Gaming @ 0.330 ($26)       <- 信号到了
BUY JA Gaming · ... - skip (held before we started) <- 但之前持仓过，不跟
```
结论：这个市场之前跟过又卖了，bot 不重复跟。正常。

```
FOLLOW LSB1: BUY Over @ 0.930 ($347)              <- 信号到了
OPEN Over · ... - skip (book unreliable spread 0.12) <- 价差太宽
```
结论：作者已删除 spread skip，如果还看到这个说明代码没更新。

#### 问题 2：CASH≠CHAIN

```bash
journalctl -u copybot-live --since "24 hours ago" --no-pager | grep "CASH≠CHAIN"
```

- `CASH≠CHAIN $+0.02` -> 正常（手续费舍入）
- `CASH≠CHAIN $+1.00` -> 有订单未追踪，需要修（见问题排查文档）
- 作者新代码有 chain-balance gates，应该自动处理

#### 问题 3：RTDS 断线

```bash
journalctl -u copybot-live --since "24 hours ago" --no-pager | grep "rtds"
```

- `rtds: connected` -> 正常
- `rtds: stream down - reconnect` -> 断线重连中
- `⚠ rtds down` -> 持续断线，重启 bot

#### 问题 4：某个钱包的 floor 漂移

```bash
# 看 sync_floors 的输出
grep "floor" /opt/winning-wallet-finder/live/daily.log | tail -10
```

- `pinned 8 trusted-p80 floors` -> 正常
- `⚠ floor X->Y (p80) - was this a manual edit?` -> 漂移大，考虑钉 floor_pin

### 怎么看某个钱包交易什么市场

```bash
# 看某个钱包最近的交易（从 cache 查）
python3 -c "
import cache
bets = cache.get_bets('WALLET_ADDRESS')
# 看最近 20 笔的市场名
for b in bets[-20:]:
    print(b.get('title','?')[:60], f'\${b.get(\"size\",0):.0f}', b.get('outcome','?'))
"
```

**用途**：
- 发现钱包的 niche（电竞/足球/BTC 等）
- 判断 niche 是否有季节性
- 发现 5min BTC 等不适合跟单的市场

---

## 第四部分：需要人类从云端提供的数据清单

每周五 review 时，人类需要从服务器拉取以下数据给 AI 代理：

| 编号 | 数据 | 命令 | 用途 |
|------|------|------|------|
| 1 | 前瞻盈亏排名 | `portfolio.py --days 30` + 解析脚本 | **核心决策依据** |
| 2 | watch_sharps 排名 | `cat watch_sharps.json \| python3 ...` | 候选池 + copy_pnl + conv_win |
| 3 | 当前跟单配置 | 读 copybot.paper.json + config.live.json | 确认当前 LIVE 列表 + floor |
| 4 | bench 观察区 | 读 backtest.json | 确认 bench 列表 |
| 5 | live bot 周表现 | `journalctl -u copybot-live --since "7 days ago"` | 跟单情况 + 异常 |
| 6 | floor 漂移警告 | `grep floor daily.log` | floor 稳定性 |
| 7 | 链上余额 | `python3 -c "from polymarket import SecureClient..."` | 确认资金状况 |
| 8 | 季节性信息 | 人类自行判断 | 电竞赛季/体育赛事/选举等 |

> 数据 1-6 用命令拉取，数据 7 用链上查询，数据 8 需要人类根据常识提供。

---

## 第五部分：AI 代理的工作规范

### 输入

人类会提供上述 6-8 份数据的输出文本。

### 分析规则

1. **前瞻盈亏是第一优先级**：realized > 0 才考虑保留，realized < 0 连续 2 周建议踢
2. **copy_pnl 只是参考**：不能单独用 copy_pnl 排名做决策（oliman2 教训）
3. **信念胜率辅助判断**：conv_win < 25% 是危险信号
4. **季节性需要人类输入**：AI 不能自己判断赛事时间
5. **floor 漂移 > 15% 建议钉 pin**：防止 paper/live 门槛不一致
6. **不跟 5min BTC 等超短周期市场**：跟单延迟来不及
7. **新钱包 floor 先设 $25**：等 sync_floors.py 自动算 p80

### 输出格式

```
=== 每周 Bench Review 报告 ===
日期：YYYY-MM-DD

一、LIVE 钱包评估（当前 N 个）
  1. [钱包名]
     前瞻: +$XXX (XX 笔, 胜率 XX%)
     copy_pnl: +XXXX (排名 #X)
     conv_win: XX%
     floor: $XX (pin: yes/no)
     判定: ✅保留 / ⚠️观察 / ❌降级
     理由: ...

  ...

二、BENCH 晋升候选
  1. [钱包名]
     前瞻: +$XXX (XX 笔)
     判定: ⬆️建议晋升 / ❌不建议
     理由: ...

  ...

三、FLOOR 调整建议
  [钱包名] $XX -> $YY (漂移 XX%) 建议钉 floor_pin=XX
  ...

四、季节性提醒
  ...

五、本周操作建议
  1. [具体操作 + 命令]
  2. ...
  （或：本周无需调整）
```

### 注意事项

- AI 代理只做**建议**，不做**决策**--人类拍板
- 如果数据不完整（如某个钱包没有前瞻数据），明确指出缺失
- 如果发现异常（如 CASH≠CHAIN、RTDS 断线），在报告里提醒
- 如果 backtest.json 里缺少某个 LIVE 钱包，提醒人类添加
- 不要建议跟 imwalkinghere（5min BTC，跟单来不及）
- **不要只看 copy_pnl 排名**：oliman2 copy_pnl #1 但前瞻亏 $143；leegunner copy_pnl #2 但前瞻亏 $180。前瞻 realized 才是决策依据
- **注意 niche**：ITF 网球/三级电竞 = 真正 edge；5min BTC/高频 scalp = 不能跟；长持仓（>7天）杀死复利
- **edge 可能消失**：钱包可能突然从 API 消失，每周重新评估，赚钱了建议人类取出来
- **胜率是骗人的**：Polymarket 的胜率有幸存者偏差，90% 显示可能是 48% 实际。只有 Copy P&L 是真实的
- **小资金要集中**：$1k 跟 10 个钱包会亏（资金不够覆盖信号），跟 5-8 个高信念钱包更好

### 前瞻盈亏会每天变（重要！）

**前瞻 30d 盈亏是滚动窗口，每天都会变。** 某个钱包今天 +$500、明天可能变成 -$200，这不代表钱包变差了，只是 30 天窗口移动了 + floor 可能被 sync_floors.py 重新算了。

**为什么数字会变**：
1. 30 天窗口每天往后移一天，新的交易数据进来，旧的出去
2. `sync_floors.py` 每天重算 p80 门槛，不同门槛 = 不同信念单被选中 = 不同盈亏
3. `git reset --hard` 会恢复作者的 backtest.json（可能有不同的 floor 配置），导致回测结果不同

**判断规则**：
- 某一周前瞻负 -> ⚠️ 观察，不急着踢
- 连续 2 周前瞻负 -> ❌ 降级到 bench
- 连续 3 周前瞻负 -> ❌ 踢出
- 某钱包突然从 +$500 变成 -$500 -> 查日志看是不是 floor 漂移太大（需要钉 floor_pin）
- **不要因为一天的数据变化就换钱包**--看几周的趋势

**这就是为什么每周五做 bench review 而不是每天看**：单天的数据波动大，一周的趋势才可靠。

---

## 附录：当前状态快照（2026-07-21）

### LIVE 跟单（8 个）

| 钱包 | 前瞻 30d | copy_pnl | conv_win | floor | floor_pin | niche |
|------|---------|----------|----------|-------|-----------|-------|
| EdwardIN | +$972 | +818 | 89% | $25 | - | 综合 |
| Vahan88 | +$615 | +3549 | 86% | $245 | - | 板球/体育 |
| LSB1 | +$574 | +1281 | 91% | $315 | - | 瑞典足球 |
| Kruto2027 | +$557 | +2274 | 67% | $80 | ✅ 80 | 综合 |
| 1kto1m | +$503 | +531 | 98% | $332 | - | BTC Up/Down |
| 0xbadaf319 | +$368 | +1370 | 78% | $42 | - | 综合 |
| lma0o0o0o | +$305 | +667 | 71% | $25 | - | 待观察 |
| Coteykens | 待确认 | +413 | 62% | $25 | - | 待观察 |

### BENCH 观察（7 个）

| 钱包 | 前瞻 30d | 状态 | 备注 |
|------|---------|------|------|
| imwalkinghere | +$263 | ❌ 永不跟 | 5min BTC，结算比跟单快 |
| 0xb0E43B | +$66 | 观察 | 作者 bench rev 5 |
| BikesAreTheBikes | +$26 | 观察 | conv_win 21% 偏低 |
| gkmgkldfmg | +$23 | 观察 | 被 daily 淘汰出 watch_sharps |
| AIcAIc | -$24 | 观察 | 作者 07-16 重新加入（电竞赛季） |
| oliman2 | -$143 | ❌ 不跟 | copy_pnl #1 但前瞻亏 |
| JuiceFarm | -$161 | ❌ 不跟 | 前瞻亏 |
| leegunner | -$180 | ❌ 不跟 | copy_pnl #2 但前瞻亏 |

> 此快照每周五 review 后更新。