docs: add AGENT.md - AI agent collaboration guide for weekly wallet review

Complete guide for human-AI collaboration on weekly Friday bench review: - Part 1: Full wallet screening chain (3 layers: watch_sharps -> backtest -> live) with copy_pnl vs forward realized explanation (oliman2/leegunner lesson) - Part 2: Weekly Friday review process (5 steps with exact commands) - Step 1: Human pulls 6 data sets from server (exact commands) - Step 2: AI analyzes 5 dimensions (forward P&L, copy_pnl, conv_win, seasonal, floor) - Step 3: AI outputs structured recommendation - Step 4: Human makes final decision - Step 5: Human executes on server (promote/demote/pin commands) - Part 3: Log analysis guide (how to discover wallet niches, floor drift, CASH!=CHAIN, RTDS issues from logs) - Part 4: Data checklist (8 items human must provide from cloud) - Part 5: AI agent work rules (input format, analysis rules, output format) - Appendix: Current status snapshot (8 live + 7 bench with forward P&L)
2026-07-21 08:59:45 +08:00
parent 8656e528af
commit ad0e6dd923
1 changed files with 511 additions and 0 deletions
@@ -0,0 +1,511 @@
+# 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：季节性催化剂（权重 ★★）
+
+**数据来源**：需要人类提供信息（AI 代理无法自动判断）
+
+**人类需要告诉 AI**：
+- 某钱包主要交易什么类型的市场（电竞/足球/BTC/政治等）
+- 是否有即将到来的赛事/事件（如 Esports World Cup、世界杯、选举等）
+
+**判断规则**：
+- niche 有赛季/事件即将开始 -> 加分（如 AIcAIc 在电竞赛季）
+- niche 赛季结束 -> 减分
+- niche 是 5min BTC 等超短周期市场 -> ❌ 永不跟（跟单来不及）
+
+#### 维度 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，跟单来不及）
+
+---
+
+## 附录：当前状态快照（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 后更新。