startgg-query-skill

🎮 Start.gg Tournament Data Query

通过 start.gg 的 GraphQL API 查询赛事数据：搜索赛事、读取赛事/项目（event）信息、参赛者（entrants）、分组/池子（phaseGroup/pool）、对阵（sets）与排名（standings）。

✅ 使用前检查

在执行任何查询前，先检查环境变量 STARTGG_API_KEY 是否存在：

• 如果没有：先提示用户提供 key（并说明获取入口 https://start.gg/settings/developer 以及如何设置 STARTGG_API_KEY），不要继续调用工具或发起 API 请求。
• 如果有：再继续执行查询。

🔑 Setup

1. 在 https://start.gg/settings/developer 获取 API token
2. 设置环境变量（不要硬编码）：

   export STARTGG_API_KEY="your_token_here"
   

📡 API Endpoint

| Property | Value | |---|---| | Endpoint | https://api.start.gg/gql/alpha | | Method | POST | | Auth Header | Authorization: Bearer $STARTGG_API_KEY | | Content-Type | application/json |

✅ 推荐工具用法（优先）

优先使用工具的高阶 action，而不是直接拼 GraphQL：

• search_tournaments(name, per_page)：按名称搜索赛事，拿到 slug
• get_tournament(slug)：根据 slug 获取赛事与 events 列表
• list_event_entrants(event_id, page, per_page)：分页列出参赛者
• search_event_entrants(event_id, name, page, per_page)：在参赛者中按名称过滤（使用 filter: { name: ... }）
• seed_pool(seed_id)：由 seedId 获取所在 pool/phaseGroup（phaseGroup.displayIdentifier）
• phasegroup_sets(phase_group_id, page, per_page)：获取某个 pool 的对阵（sets）
• event_standings(event_id, page, per_page)：获取项目排名

如遇 schema 不支持或字段不够，再使用 gql(query, variables) 执行原始 GraphQL。

⚠️ Pitfalls & Corrections

• Slug 格式：赛事 slug 需要 tournament/ 前缀：ceo-2026 ❌ → tournament/ceo-2026 ✅
• Entrant 搜索：用 filter: { name: "..." }，不要用 search/names
• 字段路径：gamerTag 在 Entrant.participants[].gamerTag；pool 在 Seed.phaseGroup.displayIdentifier
• Connection 类型：phaseGroups、entrants、sets、standings 这类字段要用 .nodes 拿列表
• 分页：用 page 与 perPage 翻页；未开赛/未锁定报名可能返回空列表

🔄 Typical Workflow

1. 搜索赛事 → 拿 slug
2. 用 slug 查赛事 → 拿 events（event IDs）
3. 用 event ID 查 entrants → 找到选手 → 拿 seedId
4. 用 seedId 查 pool（phaseGroup）→ 拿 displayIdentifier
5. 用 phaseGroup 查 sets 或用 event 查 standings