@catalyst-team/poly-mcp 0.1.0 → 0.1.2

package/docs/02-wallet-deep-research.md

@@ -0,0 +1,344 @@
+# 钱包深度分析指南
+
+> 核心原则：**分页获取，逐步分析，边分析边输出**。解决仓位过多和上下文不足的问题。
+
+---
+
+## 设计原则
+
+### 为什么要分页 + 逐步分析？
+
+| 问题 | 原因 | 解决方案 |
+|------|------|---------|
+| 仓位太多获取不完 | API 单次最多返回 50/500 条 | 分页获取：offset + limit |
+| 分析不深入 | 同时处理多个市场，每个都浅尝辄止 | 一次只分析一个市场 |
+| 上下文不足 | 数据太多，信息被挤掉 | 边分析边输出，释放上下文 |
+| 幻觉风险 | 数据太多记不住，开始编造 | 分批处理，及时输出 |
+
+### 核心流程
+
+```
+基础信息 → 分页获取持仓 → 找核心盈亏来源 → 逐个深入分析 → 逐步输出报告
+```
+
+---
+
+## 工具参数参考
+
+### 持仓相关
+
+| 工具 | 关键参数 | 说明 |
+|------|----------|------|
+| `get_trader_positions` | `limit` (max 500) | 当前持仓数量限制 |
+|  | `offset` (0-10000) | 分页偏移量 |
+|  | `sortBy` | CASHPNL, PERCENTPNL, CURRENT, INITIAL, TOKENS, TITLE, PRICE, AVGPRICE |
+|  | `sortDirection` | ASC, DESC |
+| `get_trader_closed_positions` | `limit` (max 50) | 已结算持仓数量限制 |
+|  | `offset` (0-100000) | 分页偏移量 |
+|  | `sortBy` | REALIZEDPNL, TIMESTAMP, TITLE, PRICE, AVGPRICE |
+|  | `sortDirection` | ASC, DESC (找亏钱用 ASC) |
+
+### 活动历史
+
+| 工具 | 关键参数 | 说明 |
+|------|----------|------|
+| `get_trader_activity` | `limit` (max 500) | 活动数量限制 |
+|  | `offset` (0-10000) | 分页偏移量 |
+|  | `start` | Unix 秒，过滤此时间之后的活动 |
+|  | `end` | Unix 秒，过滤此时间之前的活动 |
+|  | `type` | TRADE, SPLIT, MERGE, REDEEM, REWARD, CONVERSION |
+|  | `side` | BUY, SELL |
+|  | `market` | 按 conditionId 过滤 |
+
+---
+
+## 完整分析流程
+
+### Phase 1: 账户概览（快速）
+
+**目标**：了解账户规模和基本特征
+
+```
+工具调用（并行）：
+1. get_trader_profile(address)     → 排名、总 PnL、胜率
+2. get_account_value(address)      → 账户总价值
+```
+
+**立即输出**：
+
+```markdown
+## 1. 账户概览
+
+| 指标 | 值 |
+|------|-----|
+| 地址 | 0x... |
+| 全站排名 | #X |
+| 总 PnL | $X |
+| 账户价值 | $X |
+| 胜率 | X% |
+```
+
+---
+
+### Phase 2: 持仓全景（分页获取）
+
+**目标**：获取完整的持仓和历史数据，找出核心盈亏来源
+
+#### Step 2.1: 获取当前持仓
+
+```
+工具调用：
+get_trader_positions(address, limit=100, offset=0, sortBy='CASHPNL', sortDirection='DESC')
+→ 如果返回 100 条，可能还有更多，继续：
+get_trader_positions(address, limit=100, offset=100, sortBy='CASHPNL', sortDirection='DESC')
+→ 直到返回少于 limit 条
+```
+
+#### Step 2.2: 获取已结算持仓 - TOP 盈利
+
+```
+工具调用：
+get_trader_closed_positions(address, limit=50, offset=0, sortBy='REALIZEDPNL', sortDirection='DESC')
+→ 获取 TOP 50 最赚钱的市场
+```
+
+#### Step 2.3: 获取已结算持仓 - TOP 亏损
+
+```
+工具调用：
+get_trader_closed_positions(address, limit=50, offset=0, sortBy='REALIZEDPNL', sortDirection='ASC')
+→ 获取 TOP 50 最亏钱的市场
+```
+
+**立即输出**：
+
+```markdown
+## 2. 持仓全景
+
+### 当前持仓 (X 个)
+| 市场 | 方向 | 价值 | 未实现盈亏 |
+|------|------|------|-----------|
+| ... | Yes/No | $X | +$X |
+
+### 历史战绩
+- 已结算市场: X 个
+- 盈利市场: X 个
+- 亏损市场: X 个
+
+### TOP 5 盈利来源 (待深入分析)
+1. [市场名] +$X ← 接下来重点分析
+2. [市场名] +$X
+3. [市场名] +$X
+4. [市场名] +$X
+5. [市场名] +$X
+
+### TOP 5 亏损来源 (待分析)
+1. [市场名] -$X
+2. [市场名] -$X
+3. [市场名] -$X
+4. [市场名] -$X
+5. [市场名] -$X
+```
+
+---
+
+### Phase 3: 逐个市场深度分析
+
+**关键原则**：一次只分析一个市场！分析完立即输出，再进入下一个。
+
+#### 对每个重点市场：
+
+```
+工具调用：
+1. get_market(conditionId)                                    → 市场详情
+2. get_trader_activity(address, market=conditionId, limit=100) → 该钱包在此市场的操作
+```
+
+**分析要点**：
+- 入场时间和价格
+- 加仓/减仓行为
+- 退出方式（止盈/持有到结算）
+- 持仓周期
+
+**立即输出（每个市场单独输出）**：
+
+```markdown
+### 3.1 [市场名称] (+$X)
+
+**市场信息**
+- 标题: ...
+- 状态: 已结算/进行中
+- 最终结果: Yes/No @ $X
+
+**操作时间线**
+| 时间 | 操作 | 方向 | 价格 | 数量 |
+|------|------|------|------|------|
+| 2024-03-15 | BUY | Yes | $0.35 | 1000 |
+| 2024-06-20 | BUY | Yes | $0.42 | 500 |
+| 2024-11-06 | REDEEM | - | $1.00 | 1500 |
+
+**策略分析**
+- 入场时机: 价格在 $0.35 时入场，处于低位
+- 加仓行为: 价格上涨到 $0.42 时加仓
+- 退出策略: 持有到结算
+- 持仓周期: 约 8 个月
+- 盈亏: +$X (+X%)
+```
+
+**完成一个后，再分析下一个市场...**
+
+---
+
+### Phase 4: 行为模式总结
+
+```
+基于已分析的市场数据总结，无需额外 API 调用
+```
+
+**立即输出**：
+
+```markdown
+## 4. 行为画像
+
+| 维度 | 特征 |
+|------|------|
+| 交易风格 | 保守/激进 |
+| 持仓周期 | 短期(<1周) / 中期(1-4周) / 长期(>1月) |
+| 入场偏好 | 低价抄底 / 趋势跟随 / 事件驱动 |
+| 退出策略 | 止盈 / 持有到结算 |
+| 市场偏好 | 政治 / 加密 / 体育 |
+| Bot 可能性 | 低/中/高 (基于 SPLIT/MERGE 占比) |
+```
+
+---
+
+### Phase 5: 可复制策略提取
+
+```markdown
+## 5. 可复制策略
+
+### 入场策略
+- 价格条件: 当 Yes 价格 < $0.X 时入场
+- 时机选择: ...
+
+### 仓位管理
+- 初始仓位: 总资金的 X%
+- 加仓条件: ...
+
+### 退出策略
+- 止盈条件: 价格达到 $X 或涨幅 X%
+- 止损条件: 价格跌破 $X
+- 持有到结算比例: X%
+```
+
+---
+
+### Phase 6: 总结
+
+```markdown
+## 6. 总结
+
+[地址简称] 是一个 [风格] 型交易者，主要通过 [策略] 在 [市场类型] 获利。
+核心优势是 [优势]，可学习的策略是 [策略要点]。
+```
+
+---
+
+## Agent Prompt 模板
+
+```
+请对 Polymarket 钱包 [地址] 进行深度分析。
+
+## 核心原则
+1. **分页获取**：使用 offset 参数分页获取完整数据
+2. **逐步分析**：一次只深入分析一个市场
+3. **边分析边输出**：每个步骤完成后立即输出对应部分的报告
+4. **释放上下文**：输出后不要保留原始数据，只保留结论
+
+## 执行步骤
+
+### Phase 1: 账户概览
+并行调用 get_trader_profile 和 get_account_value
+→ 输出: 账户概览表格
+
+### Phase 2: 持仓全景
+
+#### 2.1 获取当前持仓
+get_trader_positions(address, limit=100, offset=0, sortBy='CASHPNL', sortDirection='DESC')
+→ 如果满 100 条，继续 offset=100, 200... 直到返回不足 100 条
+
+#### 2.2 获取 TOP 盈利持仓
+get_trader_closed_positions(address, limit=50, sortBy='REALIZEDPNL', sortDirection='DESC')
+→ 输出: TOP 5 最赚钱市场列表
+
+#### 2.3 获取 TOP 亏损持仓
+get_trader_closed_positions(address, limit=50, sortBy='REALIZEDPNL', sortDirection='ASC')
+→ 输出: TOP 5 最亏钱市场列表
+
+### Phase 3: 逐个市场深度分析
+
+对 TOP 5 盈利 + TOP 3 亏损市场，依次执行：
+1. 调用 get_market(conditionId) 获取市场信息
+2. 调用 get_trader_activity(address, market=conditionId, limit=100) 获取操作历史
+3. 分析入场/加仓/退出策略
+4. **立即输出该市场的分析报告**
+5. **完成后再进入下一个市场**
+
+### Phase 4: 行为画像
+基于已分析内容，总结行为特征
+→ 输出: 行为画像表格
+
+### Phase 5: 策略提取
+提炼可复制的交易策略
+→ 输出: 策略清单
+
+### Phase 6: 总结
+一句话概括
+→ 输出: 总结
+
+## 注意事项
+- 如果仓位超过 500 个，只分析 TOP 相关的即可
+- 每个市场分析完就输出，不要等到全部完成
+- 输出后释放详细数据，只保留结论
+```
+
+---
+
+## 简化版 Prompt（快速分析）
+
+```
+分析 Polymarket 钱包 [地址]。
+
+要求：
+1. 先获取 profile 和 account_value 了解概况
+2. 用 get_trader_closed_positions(sortBy='REALIZEDPNL', limit=50) 找 TOP 5 最赚钱市场
+3. 用 get_trader_closed_positions(sortBy='REALIZEDPNL', sortDirection='ASC', limit=50) 找 TOP 5 最亏钱市场
+4. 对 TOP 3 盈利市场，逐个分析操作历史
+5. 边分析边输出报告
+```
+
+---
+
+## Activity 类型说明
+
+| 类型 | 说明 | 策略含义 |
+|------|------|----------|
+| `TRADE` | 买卖交易 | 正常交易 |
+| `SPLIT` | 1 USDC → 1 YES + 1 NO | 做市/套利 |
+| `MERGE` | 1 YES + 1 NO → 1 USDC | 套利收割 |
+| `REDEEM` | 结算后赎回 | 盈利兑现 |
+| `REWARD` | 流动性奖励 | 做市收益 |
+
+**Bot 检测**：如果 SPLIT/MERGE 占比 > 20%，大概率是套利 Bot。
+
+---
+
+## 分页策略汇总
+
+| 数据类型 | 推荐策略 | 说明 |
+|----------|----------|------|
+| 当前持仓 | limit=100, 循环直到 < limit | 获取完整持仓 |
+| 已结算持仓-盈利 | limit=50, sortDirection=DESC | TOP 50 最赚钱 |
+| 已结算持仓-亏损 | limit=50, sortDirection=ASC | TOP 50 最亏钱 |
+| 特定市场活动 | limit=100, market=conditionId | 单市场完整历史 |
+| 时间段活动 | limit=500, start/end | 指定时间范围 |

package/docs/e2e/01-trader-tools.md

@@ -0,0 +1,159 @@
+# Trader Tools E2E Test
+
+> 交易者分析工具端到端测试
+
+---
+
+## 工具清单
+
+| 工具 | 功能 | 认证 | 优先级 |
+|------|------|------|--------|
+| `get_leaderboard` | 获取 PnL 排行榜 | 无 | P1 |
+| `get_trader_profile` | 获取交易者资料 | 无 | P1 |
+| `get_trader_positions` | 获取持仓和 PnL | 无 | P0 |
+| `get_trader_trades` | 获取交易历史 | 无 | P1 |
+
+---
+
+## Test Case 1: get_leaderboard
+
+### 1.1 默认参数
+```
+调用: get_leaderboard()
+预期: 返回 10 个交易者，按 PnL 排序
+验证:
+- traders 数组长度 = 10
+- 每个 trader 有 rank, address, pnl, volume
+- rank 从 1 开始递增
+```
+
+### 1.2 自定义 limit
+```
+调用: get_leaderboard(limit=5)
+预期: 返回 5 个交易者
+验证:
+- traders 数组长度 = 5
+```
+
+### 1.3 分页测试
+```
+调用: get_leaderboard(limit=5, offset=5)
+预期: 返回第 6-10 名交易者
+验证:
+- 第一个 trader 的 rank = 6
+- 与 offset=0 的结果不重叠
+```
+
+---
+
+## Test Case 2: get_trader_profile
+
+### 2.1 有效地址
+```
+前置: 从 leaderboard 获取一个地址
+调用: get_trader_profile(address=<top_trader>)
+预期: 返回完整的交易者资料
+验证:
+- trader.address 匹配
+- ranking.rank 存在
+- performance.officialPnl 存在
+- stats.positionCount >= 0
+```
+
+### 2.2 无效地址
+```
+调用: get_trader_profile(address="0x0000000000000000000000000000000000000000")
+预期: 返回空数据或错误
+验证:
+- 错误信息清晰
+```
+
+---
+
+## Test Case 3: get_trader_positions
+
+### 3.1 有持仓的交易者
+```
+前置: 从 leaderboard 获取顶级交易者
+调用: get_trader_positions(address=<top_trader>)
+预期: 返回持仓列表和汇总
+验证:
+- positions 是数组
+- 每个 position 有 market, holding, pnl
+- summary.totalPositions 匹配 positions.length
+- unrealizedPnl 和 realizedPnl 有值
+```
+
+### 3.2 无持仓的地址
+```
+调用: get_trader_positions(address=<new_address>)
+预期: 返回空持仓列表
+验证:
+- positions = []
+- summary.totalPositions = 0
+```
+
+---
+
+## Test Case 4: get_trader_trades
+
+### 4.1 默认参数
+```
+前置: 从 leaderboard 获取活跃交易者
+调用: get_trader_trades(address=<active_trader>)
+预期: 返回最近 20 笔交易
+验证:
+- trades 数组长度 <= 20
+- 每笔交易有 side, outcome, size, price, timestamp
+- 按时间倒序排列
+```
+
+### 4.2 过滤 BUY
+```
+调用: get_trader_trades(address=<trader>, side="BUY")
+预期: 只返回买入交易
+验证:
+- 所有 trade.side = "BUY"
+```
+
+### 4.3 过滤 SELL
+```
+调用: get_trader_trades(address=<trader>, side="SELL")
+预期: 只返回卖出交易
+验证:
+- 所有 trade.side = "SELL"
+```
+
+### 4.4 自定义 limit
+```
+调用: get_trader_trades(address=<trader>, limit=5)
+预期: 返回 5 笔交易
+验证:
+- trades.length <= 5
+```
+
+---
+
+## 执行记录
+
+| Test Case | 状态 | 结果 | 备注 |
+|-----------|------|------|------|
+| 1.1 get_leaderboard 默认 | - | - | - |
+| 1.2 get_leaderboard limit | - | - | - |
+| 1.3 get_leaderboard 分页 | - | - | - |
+| 2.1 get_trader_profile 有效 | - | - | - |
+| 2.2 get_trader_profile 无效 | - | - | - |
+| 3.1 get_trader_positions 有持仓 | - | - | - |
+| 3.2 get_trader_positions 无持仓 | - | - | - |
+| 4.1 get_trader_trades 默认 | - | - | - |
+| 4.2 get_trader_trades BUY | - | - | - |
+| 4.3 get_trader_trades SELL | - | - | - |
+| 4.4 get_trader_trades limit | - | - | - |
+
+---
+
+## 发现的问题
+
+| ID | 问题描述 | 严重性 | 状态 |
+|----|---------|--------|------|
+| - | - | - | - |

package/docs/e2e/02-market-tools.md

@@ -0,0 +1,180 @@
+# Market Tools E2E Test
+
+> 市场查询工具端到端测试
+
+---
+
+## 工具清单
+
+| 工具 | 功能 | 认证 | 优先级 |
+|------|------|------|--------|
+| `search_markets` | 搜索市场 | 无 | P1 |
+| `get_trending_markets` | 趋势市场 | 无 | P3 |
+| `get_market` | 市场详情 | 无 | P0 |
+| `get_market_trades` | 市场成交 | 无 | P1 |
+
+---
+
+## Test Case 1: search_markets
+
+### 1.1 热门关键词搜索
+```
+调用: search_markets(query="Trump")
+预期: 返回与 Trump 相关的市场
+验证:
+- markets 是数组
+- 每个市场的 question 或 slug 包含搜索词
+- 按 volume 排序
+```
+
+### 1.2 技术关键词搜索
+```
+调用: search_markets(query="Bitcoin")
+预期: 返回加密货币相关市场
+验证:
+- 结果与 Bitcoin/BTC 价格预测相关
+```
+
+### 1.3 active 过滤
+```
+调用: search_markets(query="2024", active=false)
+预期: 包含已结束的市场
+验证:
+- 可能返回已关闭的 2024 年市场
+```
+
+### 1.4 limit 参数
+```
+调用: search_markets(query="election", limit=3)
+预期: 最多返回 3 个市场
+验证:
+- markets.length <= 3
+```
+
+---
+
+## Test Case 2: get_trending_markets
+
+### 2.1 按交易量排序
+```
+调用: get_trending_markets(sortBy="volume")
+预期: 返回高交易量市场
+验证:
+- markets 按 volume24h 降序排列
+```
+
+### 2.2 按流动性排序
+```
+调用: get_trending_markets(sortBy="liquidity")
+预期: 返回高流动性市场
+验证:
+- 返回的市场流动性较高
+```
+
+### 2.3 最新市场
+```
+调用: get_trending_markets(sortBy="newest")
+预期: 返回最近创建的市场
+验证:
+- 按创建时间排序
+```
+
+### 2.4 自定义数量
+```
+调用: get_trending_markets(limit=5)
+预期: 返回 5 个市场
+验证:
+- markets.length = 5
+```
+
+---
+
+## Test Case 3: get_market
+
+### 3.1 使用 slug
+```
+调用: get_market(identifier="presidential-election-winner-2024")
+预期: 返回完整市场信息
+验证:
+- market.slug 匹配
+- prices.yes + prices.no ≈ 1.0
+- tokens.yes 和 tokens.no 都有 tokenId
+- status 字段存在
+```
+
+### 3.2 使用 conditionId
+```
+前置: 从 search_markets 获取一个 conditionId
+调用: get_market(identifier=<conditionId>)
+预期: 返回同样的市场信息
+验证:
+- 与使用 slug 返回的数据一致
+```
+
+### 3.3 无效标识符
+```
+调用: get_market(identifier="invalid-slug-12345")
+预期: 返回错误
+验证:
+- 错误信息清晰说明市场不存在
+```
+
+---
+
+## Test Case 4: get_market_trades
+
+### 4.1 热门市场成交
+```
+前置: 获取一个高交易量市场的 conditionId
+调用: get_market_trades(conditionId=<id>)
+预期: 返回最近成交
+验证:
+- trades 是数组
+- 每笔交易有 trader, side, outcome, size, price, timestamp
+- 按时间倒序
+```
+
+### 4.2 自定义数量
+```
+调用: get_market_trades(conditionId=<id>, limit=5)
+预期: 返回 5 笔成交
+验证:
+- trades.length <= 5
+```
+
+### 4.3 冷门市场
+```
+调用: get_market_trades(conditionId=<low_volume_market>)
+预期: 返回较少或空的成交
+验证:
+- 即使没有成交也不报错
+```
+
+---
+
+## 执行记录
+
+| Test Case | 状态 | 结果 | 备注 |
+|-----------|------|------|------|
+| 1.1 search_markets Trump | - | - | - |
+| 1.2 search_markets Bitcoin | - | - | - |
+| 1.3 search_markets active=false | - | - | - |
+| 1.4 search_markets limit | - | - | - |
+| 2.1 trending volume | - | - | - |
+| 2.2 trending liquidity | - | - | - |
+| 2.3 trending newest | - | - | - |
+| 2.4 trending limit | - | - | - |
+| 3.1 get_market slug | - | - | - |
+| 3.2 get_market conditionId | - | - | - |
+| 3.3 get_market invalid | - | - | - |
+| 4.1 market_trades 热门 | - | - | - |
+| 4.2 market_trades limit | - | - | - |
+| 4.3 market_trades 冷门 | - | - | - |
+
+---
+
+## 发现的问题
+
+| ID | 问题描述 | 严重性 | 状态 |
+|----|---------|--------|------|
+| - | - | - | - |