sportsdata-agents

# 体育数据代理 [](https://github.com/DanielTomaro13/sportsdata-agents/actions/workflows/ci.yml) [](https://github.com/DanielTomaro13/sportsdata-agents/releases/latest) [](./LICENSE) > **文档：** [架构与系统设计](docs/ARCHITECTURE.md) · > [仓库结构](docs/STRUCTURE.md) · [代理列表](docs/AGENTS.md) · > [操作指南](docs/OPERATING.md) · [安全与成本控制](docs/SECURITY.md) · > [更新应用程序](docs/UPDATING.md) · [下一步骤](docs/NEXT_STEPS.md) · > [发布](RELEASE.md)。这些文档由 `docs_keeper`运维代理维护。 一个基于代理的平台，它将 [`sportsdata-mcp`](https://github.com/DanielTomaro13/sportsdata-mcp) 工具目录转化为 **您需要的任何桌面** —— 跨投注者的 **交易桌面**，**体育分析/教练团队**，**幻想桌面**，或自定义组合。它是一个由多个LLM代理组成的团队，共享一个数据骨干：它们收集和分析体育数据，建模结果，比较赔率，优化幻想阵容，并跟踪性能 —— **您可以启用适合您需求的代理和模块**。一个独立的工程团队维护代码库，通过CI门控的PR。 您可以从 **我们构建的模块中选择并组装** 工作空间 —— 比赛分析，幻想，赛车，交易/投注等。没有任何模块是特权的：交易模块和教练模块是目录中的平等公民。交易/投注只是一个模块（且受管辖），因此没有它的工作空间是一个纯分析工具（更大的市场，更低的合规性表面）。 > ### 仅提供建议 —— 没有代理会下注或转移资金。 > 平台 **提供信息**。它提供建议，您要求的统计数据，以及您可以选择下注的赔率（带有赌注，投注额和理由）。 **您始终采取行动**。这是一个研究和分析工具，而不是投注运营商。 ## 设计 🛠️ **[`BUILD_PLAN.md`](docs/history/BUILD_PLAN.md)** —— 技术，分阶段实施计划清单（P0 → P4，里程碑，出口门）。 🖥️ **[`P4_DESKTOP_PLAN.md`](docs/history/P4_DESKTOP_PLAN.md)** —— P4重新规划：可下载的桌面应用程序（用户机器上的Cursor样式的壳）—— 壳选项，进程/存储/秘密架构，权衡，修订后的里程碑。 📐 **[`PLAN.md`](docs/history/PLAN.md)** —— 完整架构：两平面设计，代理列表，用户可自定义的代理规格格式，数据模型，编排和模型选择，沙盒，接口（CLI → Slack → 网页），多租户/SaaS就绪，自我改进循环，交付路线图，以及 **决策登记** ，包含每个选择的利弊。 ## 已构建（P0–P4完成 - 可下载的桌面应用程序） **代理团队** （`src/sportsdata_agents/specs/`中的27个规格 - 20个产品，7个运维）：一个编排器，负责路由和委托；赔率/统计数据专家，负责实时数据平面；一个 **赛车分析师** （赛车卡，结果，跨投注胜/名次）和一个 **预测市场分析师** （Kalshi/Polymarket + 交换-vs-投注边缘）；一个建模代理（通用模型开发 - 特征，校准，Brier/log-loss，逻辑回归，XGBoost技能）；一个价值侦察员（vig移除，+EV检测，跨投注最佳价格）；一个回测器（入场时间纪律，CLV vs 关闭）；一个 bankroll 管理器，投注跟踪器和投注通知器（仅建议）；一个市场管理员，负责维护市场词典作为数据；一个 **套利猎人** （确定性跨投注套利，包括交换-vs-投注）；一个新闻侦察员，负责X/官方馈送；一个幻想顾问；一个Slack管理器；一个数据分析代理（沙盒`run_python`）；一个 **通才** ，负责增长平台（编写可重用的技能，构建新的代理，因为它了解您的需求）；一个礼宾服务 —— 加上七个运维代理（健康，改进者，审查者，评估，分类，站点管理器，文档管理员）在单独的运维平面上。 每个答案都是 **有根据的** （数字必须来自工具结果 - 确定性验证器检查），**有来源的** （每个工具调用的出处），**有预算的** （每个团队运行一个成本上限），并且 **有审计的** （当配置运行/工具调用/成本到数据库中）。 **赔率仓库** （`agents ingest`）：发现驱动的，捕获所有内容的摄取，跨越 **10个投注者** —— Sportsbet，TAB，Unibet/Kambi，Entain（Ladbrokes/Neds），Pinnacle，PointsBet，BetR，FanDuel（美国体育博彩 + 赛车）—— 加上 **两个预测市场** （Kalshi，Polymarket）—— 分为五个层级： - **热** （5–30分钟）：每个提供商的发现路由 → 所有体育，所有比赛，主要 + 内联市场 —— 没有硬编码，新比赛/体育比赛自动出现； - **完整投注** （60分钟）：每个比赛的所有市场（旋转窗口超过兆字节规模的每个比赛管道）； - **赛车** （~3分钟）：TAB，Sportsbet，BetR，PointsBet，Unibet，FanDuel的胜+名次卡， soonest 比赛优先； - **赛车期货** （60分钟）：TAB，Sportsbet，PointsBet，Unibet的 ante-post 杯/嘉年华直接赔率； - **预测市场** （15分钟）：Kalshi和Polymarket交换报价作为小数赔率（1/价格）—— 事件合约像任何投注者的板块一样读取（Polymarket的Gamma边缘是地理门控；馈送运行在边缘答案的位置）。 体育期货（冠军获胜者，Brownlow，NFL/MLB期货，…）骑在热层上：Kambi `competitions.json`，Sportsbet的Outrights路由，Entain/BetR/TAB内联。 标准化器从不按市场名称过滤 —— `canonical_market()`仅 *重命名* 到共享键（h2h/spread/total/win/place），由 **数据字典** 驱动（打包种子 + 管理员维护的本地覆盖；合并安全性在工具中强制执行：资格市场永远不能别名成基类）。原始观察结果登陆 `odds_snapshots` （可修剪；带有解析的广告开始时间）；仅 **change-point** 的`prices`系列是模型和回测读取的内容。 **事件解析** （`agents resolve`）：确定性，无LLM的映射每个投注者的私有事件ID到共享的比赛（模糊子集团队令牌匹配，交换容忍，事件的广告开始时间窗口；模糊计数并跳过，从不猜测）。该连接支持 `cross_book_prices` （每个选择跨每个映射投注者的最佳价格），解析感知回测结算（在任何投注者下记录的结果结算其系列，侧向方向在投注者的列表顺序之间转换），以及 `find_fixture` / `best_prices` 代理工具。 **量化循环**：`save_model` 拒绝未校准的模型 → `record_predictions` （可回溯的`predicted_at`；侧向选择必须命名其投注者）→ `run_backtest` （平面投注，重播，无展望：入口是预测时的盛行价格；CLV vs 关闭，或vs 锐利基准通过 `clv_book="Pinnacle"` ）→ `agents results` 从赛车结果 + 官方NBA/AFL/NRL记分板结算 → `agents eval` 门控黄金指标（校准，CLV回测，基础，事件解析）针对已提交的基线。 ## 快速入门 ```bash # 1) 数据平面（兄弟checkout，其自己的venv） git clone https://github.com/DanielTomaro13/sportsdata-mcp.git cd sportsdata-mcp && python -m venv .venv && .venv/bin/pip install -e . && cd .. # 2) 代理平面 git clone https://github.com/DanielTomaro13/sportsdata-agents.git cd sportsdata-agents && python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]" # 3) 配置（.env - 见.env.example） # - 一个模型密钥：ANTHROPIC_API_KEY / OPENROUTER_API_KEY / GEMINI_API_KEY / # GROQ_API_KEY / OPENAI_API_KEY （Gemini + Groq有免费层） # - 指向数据平面二进制文件： # SPORTSDATA_AGENTS_MCP_COMMAND=["/abs/path/to/sportsdata-mcp/.venv/bin/sportsdata-mcp"] # 4) 数据库（审计行 + 赔率仓库）。SQLite开箱即用： # SPORTSDATA_AGENTS_DATABASE_URL="sqlite+aiosqlite:////path/to/warehouse.db" # 或通过docker compose up -d；然后： .venv/bin/alembic upgrade head # 5) 与团队交流 .venv/bin/agents run "使用MLB数据：Aaron Judge效力于哪支队伍？" .venv/bin/agents chat # 交互式REPL（/exit退出） .venv/bin/agents run "..." --agent value_scout # 一个代理而不是团队 .venv/bin/agents list && .venv/bin/agents lint # 规格目录 + 验证 ``` ### 数据循环 ```bash .venv/bin/agents ingest --once # 所有到期馈送的单个捕获周期 .venv/bin/agents ingest --once --feed tab_racing_futures # 单个馈送 .venv/bin/agents ingest --loop # 调度循环（每个馈送的节奏） .venv/bin/agents schedule --cron 60 # 指挥家：一个cron行程运行所有内容 .venv/bin/agents schedule --status # 每个作业状态，失败，节奏 .venv/bin/agents schedule --dry-run # 此时间点将运行的内容 .venv/bin/agents ingest --once --prune 90 # 原始快照的保留期 .venv/bin/agents resolve # 映射投注者事件 -> 共享比赛 .venv/bin/agents resolve --dry-run # 无写入计数 .venv/bin/agents results # 结算：赛车结果 + 联赛决赛（每天cron） # 一级NBA/AFL/NRL/MLB；ESPN记分板用于其他比赛 .venv/bin/agents steward # 市场管理员字典审计（每周cron） .venv/bin/agents dictionary-promote --write # 将管理员覆盖写入提交的种子 .venv/bin/agents movement --event <id> # 单个事件的变更点系列 .venv/bin/agents eval --baseline src/sportsdata_agents/evals/baseline.json .venv/bin/agents refresh-books # 每周：重新验证投注者ID ``` 摄取工作器将MCP作为作用域子进程运行，每个提供者组，并容忍每个馈送的失败（一个投注者宕机从未使周期中断）。已知例外，按策略或上游故障：NBA CDN（聚合器 - 仅记录投注）；Betfair（公共密钥从澳大利亚返回无价格；代码已准备好用于身份验证密钥）；Entain赛车GraphQL（上游持久查询漂移；Entain *体育* REST - 包括其直接赔率 - 未受影响）。 ## 测试 ```bash .venv/bin/pytest # 离线套件（默认：非实时，非评估） - CI运行此测试 .venv/bin/pytest -m live # 真实MCP + 真实模型（需要密钥；约几美分或免费层） .venv/bin/pytest -m eval # 黄金评估案例，按事实准确性评分 .venv/bin/ruff check . && .venv/bin/mypy src # 其他两个门控 ``` ## 状态 **P4完成 - 代码已准备好交付。** 平台是一个 **可下载的桌面应用程序** （“Cursor for sports data”模型）：`agents app` 在用户机器上以监督进程运行网关 + 指挥家 - 他们自己的计算，他们自己的仓库，他们自己的赔率捕获，BYO模型密钥。在P0-3（运维平面及其合并的自我改进PR，线路监视器 + **跨投注套利观察** ，带有诚实度量，预测市场与投注者一起，幻想+代理构建器+Discord），P4新增了：**网页聊天UI** ，带有学习技能面板（所有内容都是免费和开源的 - 旧层/许可机制已失效，请参见 [`docs/SECURITY.md`](docs/SECURITY.md)）；**macOS打包和签名管道** （标签→ notarized DMG，仅待Apple Developer ID）；**OTA数据馈送** ；守护进程强化（DNS-重新绑定防护，崩溃重启监督）；**通用** 增长循环；以及 **操作员控制台** （`agents config|costs|ops status` + 应用内操作员面板，由 **签名操作员许可声明** 授权 - 在发布构建中，`SPORTSDATA_OPERATOR`环境变量被忽略；请参见 [`docs/SECURITY.md`](docs/SECURITY.md)）。聊天UI已经发展成为一个完整的 **代理工作台** ：提供者开启/关闭切换，可扩展的每个回复推理轨迹，代理活动视图，实时监视器面板（套利/线路移动/价值警报），每个代理模型固定，每个对话模型+数据提供者范围，以及应用内市场，跳转到浏览器（应用内无支付逻辑）。剩下的上线内容是账户设置，不是代码 - 请参见 [`docs/NEXT_STEPS.md`](docs/NEXT_STEPS.md)， [`docs/history/BUILD_PLAN.md`](docs/history/BUILD_PLAN.md)中的里程碑日志，以及 [`POST_DEV.md`](./POST_DEV.md)中已构建但已关闭的内容。 --- 在 [MIT License](./LICENSE) 下开源。版权所有 (c) 2026 Daniel Tomaro。