0800tim/tournamental

# Tournamental [](LICENSE) [](https://www.npmjs.com/package/@tournamental/bracket-engine) [](https://github.com/0800tim/tournamental/issues) [](https://github.com/0800tim/tournamental/commits/main) [](https://discord.gg/tournamental) 域名：**tournamental.com**。需要时进行品牌扩展：**Tournamental，经验证的锦标赛预言家网络**。 ## 最新发布 - **npm 包已上线**，在 [`@tournamental/*`](https://www.npmjs.com/search?q=%40tournamental) 下 -- `spec`、`bracket-engine`、`social-cards`，以及 `plugin-sdk`（开发中）。 - **MCP 服务器已上线**，地址为 [`mcp.tournamental.com`](https://mcp.tournamental.com)，以便 Claude、Cursor、Windsurf 和其他模型上下文协议客户端能够读取实时的 Tournamental 状态。 - **工程博客 + 插件 SDK** -- [`tournamental.com/engineering`](https://tournamental.com/engineering) 上的工程日志现已成为构建者的规范入口，[`packages/plugin-sdk/`](packages/plugin-sdk) 中的插件 SDK 允许您无需 fork 核心代码即可添加渲染器、计分器、数据源、身份提供者、分享卡牌管道、赔率源和联盟路由器。 ## 20分钟内基于Tournamental构建 1. 阅读 [The Tournamental stack at a glance](https://tournamental.com/engineering/2026-05-13-stack-at-a-glance)，获取“六步指南：在 Tournamental 之上'凭感觉编码'你的应用”。 2. 选择你需要的 npm 包： - [`@tournamental/spec`](https://www.npmjs.com/package/@tournamental/spec) -- 规范的 JSON 消息规范。 - [`@tournamental/bracket-engine`](https://www.npmjs.com/package/@tournamental/bracket-engine) -- 级联和计分引擎。 - [`@tournamental/social-cards`](https://www.npmjs.com/package/@tournamental/social-cards) -- OG、领奖台和分享卡牌渲染器。 - [`@tournamental/plugin-sdk`](https://www.npmjs.com/package/@tournamental/plugin-sdk) -- 社区构建模式的插件契约。 3. 将你的 AI 代理（Claude、Cursor、Windsurf）连接到 [`mcp.tournamental.com`](https://mcp.tournamental.com) 的 MCP 服务器，这样它就能读取实时状态，无需你先编写 fetch 层。 4. 浏览 [`tournamental.com/api`](https://tournamental.com/api) 上的聚合 API 参考（Scalar UI，支持按服务深度链接）。每个服务的 OpenAPI 快照位于 [`docs/api/`](docs/api/) 下，供离线使用。 5. 交付它，为贡献池提交一个 PR，并在 [Show and Tell](https://github.com/0800tim/tournamental/discussions/categories/show-and-tell) 中发布。 ## 阅读工程日志 如果你是一名 AI 代理或人类工程师，刚来到这个仓库并试图弄清楚在哪里接入，请从 **[tournamental.com/engineering](https://tournamental.com/engineering)** 的工程日志开始，而不是从 docs 文件夹。第一篇文章 [The Tournamental stack at a glance](https://tournamental.com/engineering/2026-05-13-stack-at-a-glance) 映射了每个服务和包，并为你提供了“六步指南：在 Tournamental 之上'凭感觉编码'你的应用”的演练。后续文章深入探讨特定子系统（渲染器、计分、链上、插件、性能）。RSS 地址为 `/engineering/rss.xml`。公共问答请访问 [GitHub Discussions](https://github.com/0800tim/tournamental/discussions)。 ## Tournamental 是什么 一款实时锦标赛智能游戏。用户预测比赛结果和整个锦标赛的对阵图，在结果公布前锁定预测，并根据实时市场隐含概率赚取积分——因此正确预测一个隐含胜率为 25% 的冷门，比预测一个 90% 的热门更有价值。每个锁定的预测都有时间戳，并被提交到区块链 Merkle 批次（一个 **VStamp**）中，因此排行榜是可验证且防篡改的。用户建立长期的 **Prediction IQ**，这成为一种可携带的声誉资产。 3D 比赛渲染器（最初作为独立框架“SimulatedSports”进行规范）是观看伴随界面——球员、球、球场、风格化头像、通过 ElevenLabs 混音的实时解说，所有这些都由一个规范化的 JSON 规范流驱动，通过 Cloudflare 分发。预测游戏和渲染器是独立的层，共享同一个规范的比赛流。 核心亮点： ## 单图展示核心架构 ``` Producers (mock, video→AI, tracking feed, StatsBomb replay) │ spec stream (JSON) ▼ Stream server (origin) │ chunks + manifest ▼ Cloudflare CDN ──▶ Match renderer (web, R3F) │ │ events ▼ ┌────────────────────────────┐ ┌─────────────────────┐ │ Game service (predictions, │ ───▶ │ VStamp service │ │ leaderboards, badges, │ │ (Merkle batching, │ │ pools — Redis + flat JSON) │ │ Polygon + OTS) │ └─────────────┬──────────────┘ └─────────────────────┘ │ pub/sub ▼ ┌────────────────────────────┐ ┌─────────────────────┐ │ Tournament Bot (Telegram, │ │ Clip pipeline │ │ identity, notifications, │ │ (headless renderer │ │ group leaderboards) │ │ + ffmpeg → IG/TT/ │ └────────────────────────────┘ │ YT/X/Telegram) │ └─────────────────────┘ ``` ## 仓库结构 ``` SimulatedSports/ working folder name; consumer brand is "Tournamental" ├── README.md this file ├── Tournamental Pitch.md one-page elevator pitch ├── REVIEW.md docs-pack readiness audit ├── CLAUDE.md orchestrator + agent operations entrypoint ├── AGENT-PROMPTS.md copy-paste starter prompts for code agents ├── CONTRIBUTING.md contributor guide (humans + agents) ├── IDEAS.md backlog parking lot ├── sessions/ per-session work notes ├── docs/ detailed design docs (start here) │ ├── 01-vision-and-scope.md what we're building and not building │ ├── 02-spec.md the JSON message spec (the contract) │ ├── 03-architecture.md end-to-end system design │ ├── 04-renderer.md Next.js + React Three Fiber renderer │ ├── 05-mock-producer.md synthetic match generator │ ├── 06-video-ingest.md video → JSON pipeline (CV + LLM) │ ├── 07-avatars-and-assets.md player likeness, jerseys, animations │ ├── 08-cdn-distribution.md Cloudflare CDN, chunking, cache │ ├── 09-agent-task-breakdown.md parallel work plan for code agents │ ├── 10-roadmap.md weekend MVP and beyond │ ├── 11-historic-data-sources.md free data research; AR-FR 2022 plan │ ├── 12-odds-and-predictions.md odds, predictions, leaderboards, sweepstakes │ ├── 13-telegram-bot-and-auth.md Tournament Bot — auth (Telegram + email + TOTP + passkeys), notifications │ ├── 14-clip-generation-and-social.md auto-clips → TikTok / Reels / Shorts / Telegram │ ├── 15-tournamental-brand-and-positioning.md Tournamental brand, taglines, NZ regulatory framing, monetisation overview │ ├── 16-game-modes-and-scoring.md 10 game modes, scoring formula, personality leaderboards │ ├── 17-vstamp-and-prediction-iq.md blockchain verification + Prediction IQ reputation │ ├── 18-monetization.md affiliate routing + sponsorship + Pro + B2B + creator + data licensing │ ├── 19-open-source-and-contributor-revenue.md Apache 2.0, Tournamental, Drips Network revshare │ ├── 20-identity-humanness-bots.md multi-provider OAuth, Humanness Score, bot policy, friend graph │ └── 21-onchain-sweepstakes-oracle.md user-organised on-chain pools + Tournamental-as-oracle (Polygon/Base) ├── spec/ │ ├── types.ts canonical TypeScript types │ └── examples/ sample JSON payloads └── prompts/ LLM prompts (frame-analyzer, commentary-extractor) ``` ## npm 包 工作空间包自 2026-05-13 起在 `@tournamental` 作用域下发布到 npm。此 monorepo 内的应用（`apps/web`、`apps/marketing`、`apps/game` 及类似项目）保持为 `@vtorn/*`，因为它们是内部部署目标且不发布。 公共包： - `@tournamental/spec` -- 每个生产者和渲染器的规范消息规范。 - `@tournamental/bracket-engine` -- 用于 bracket prophet 流程的级联和计分引擎。 - `@tournamental/social-cards` -- OG、领奖台和分享卡牌渲染器。 - `@tournamental/plugin-sdk` -- 社区构建模式的插件契约（开发中）。 ## v0.2 演示目标：2022 年世界杯决赛 首个非模拟演示重现了 **2022年世界杯决赛 阿根廷 3–3 法国（点球 4–2）**，由 **StatsBomb Open Data**（免费，在 GitHub 上，包含每场比赛的事件 + 360° 定格画面）驱动。球员照片来自 Wikidata / Wikimedia Commons。完整计划请参见 [docs/11-historic-data-sources.md](docs/11-historic-data-sources.md)。Tournamental 特色：每位观众都可以在观看渲染回放的同时预测比赛，根据 2022 年的隐含概率计分（我们拥有该 StatsBomb 数据），并带走一个可验证的 VStamp，记录其最佳预测。 ## 文档 - **AI 和贡献者的蜂巢思维索引**：[`docs/README.md`](docs/README.md)。从这里开始。 - **Tournamental 特定术语表**：[`docs/glossary.md`](docs/glossary.md)。 - **添加应用、路由、调试 PR、处理合并冲突、功能标志、文档更新的操作手册**：[`docs/playbook/`](docs/playbook/)。 - **包含每个服务 Swagger UI URL 和已提交的 OpenAPI 3.0 规范的 API 参考**：[`docs/api/README.md`](docs/api/README.md)。 ## API - **公共 API 门户** 位于 [`tournamental.com/api`](https://tournamental.com/api)，一个聚合的 Scalar 渲染参考，涵盖 monorepo 中每个公共 Fastify 服务，通过 `/api/` 进行深度链接。从已提交的 `docs/api/*.openapi.json` 快照构建，因此可以离线工作。架构请参见 [`docs/53-api-portal.md`](docs/53-api-portal.md)。 - **每个服务的快照** 提交在 [`docs/api/`](docs/api/) 下，由 `pnpm --filter @vtorn/ run openapi:snapshot`（现有 `dump-openapi` 脚本的别名）重新生成。 ## 代码代理快速入门 `docs/` 中的每个文档都旨在供单独的代码代理拾取并独立实现。代理任务分解位于 [docs/09-agent-task-breakdown.md](docs/09-agent-task-breakdown.md)，它标识了哪些文档是阻塞的，哪些可以并行运行，以及每个代理必须遵守的契约表面。 现在有十三个代理（A–M）： - **A–E** — 比赛流关键路径（规范、模拟生产者、流服务器、渲染器、规范客户端）。 - **F–I** — 比赛流并行工作（视频摄取、CDN 部署、头像、演示站点）。 - **J** — 游戏服务：预测、排行榜、徽章、池。 - **K** — Tournament Bot：Telegram + 邮件 + TOTP + Passkey 认证、通知、群组排行榜。 - **L** — 剪辑管道：无头渲染器 → MP4 变体 → 社交发布。 - **M** — VStamp 服务：Merkle 批处理、Polygon 锚定、OpenTimestamps 证明。 关键路径“可观看的演示”仍然是第一个周末的工作（代理 A–E + 最小的 H）。完整的 Tournamental 启动（包含预测、机器人、VStamp 和剪辑分发）是一个由代码代理并行团队进行的 2-4 周工作包——大致相当于一个锦标赛窗口（如 2026 年世界杯）的时间范围。 ## 10 分钟构建插件 Tournamental 附带一个插件 SDK，以便第三方可以无需 fork 核心代码即可添加替代渲染器、计分器、数据源、身份提供者、解说语音、分享卡牌管道、赔率源或联盟路由器。v0.1 中有八个扩展点是一等公民。 快速入门： - SDK：[`packages/plugin-sdk/`](packages/plugin-sdk) + [`packages/plugin-sdk/README.md`](packages/plugin-sdk/README.md) - 参考插件：[`packages/plugins/example-cel-shaded-renderer/`](packages/plugins/example-cel-shaded-renderer) - 完整架构文档：[`docs/28-plugin-architecture.md`](docs/28-plugin-architecture.md) - 通过 Drips 进行收入分成：[`docs/19-open-source-and-contributor-revenue.md`](docs/19-open-source-and-contributor-revenue.md) ``` pnpm add @tournamental/plugin-sdk # 创建 plugin.json 声明 `provides: ["renderer"]` (或其他能力) # 从 src/index.ts 导出一个默认的 PluginFactory # 将其放入 plugins/ 用于开发，或发布到 npm 作用域 @tournamental-plugin/* ``` 插件在应用启动时动态加载。许可证必须是 Apache-2.0、MIT、BSD-2-Clause 或 BSD-3-Clause（清单模式会拒绝其他所有许可证）。在 `packages/plugins/*` 或 `@tournamental-plugin/*` npm 作用域下发布的插件，根据 [文档 19](docs/19-open-source-and-contributor-revenue.md) 获得上游 Drips 资金库的份额。 ## 部署 CI/CD 采用构建槽蓝绿部署：构建到 `-staging`，在私有端口上进行冒烟测试，原子交换到 `-prod`，PM2 重载。最坏情况下感知停机时间约 2-3 秒。适用于所有 monorepo 应用。 - 架构：[docs/47-cicd-pipeline.md](docs/47-cicd-pipeline.md) - 部署运行手册：[docs/cicd/01-deploy-runbook.md](docs/cicd/01-deploy-runbook.md) - 回滚：[docs/cicd/02-rollback-runbook.md](docs/cicd/02-rollback-runbook.md) - 事故标记：[docs/cicd/03-incident-flag-runbook.md](docs/cicd/03-incident-flag-runbook.md) - 密钥轮换：[docs/cicd/04-secrets-rotation-runbook.md](docs/cicd/04-secrets-rotation-runbook.md) 顶级脚本：`pnpm deploy:staging --apps=marketing`、`pnpm deploy:promote`、`pnpm deploy:rollback --app=marketing --buildKind=astro`。 ## 定位（简版） Tournamental 是**免费游玩**的。积分不可兑换现金。我们绝不充当体育博彩公司。我们显示公开市场赔率（Polymarket、The Odds API）作为计分难度的数据层；我们仅在用户所在地区合法的情况下，才向受监管的运营商展示联盟链接。抽奖池被追踪但非托管——用户在平台外结算。详细的监管框架（包括新西兰特定的 Polymarket/Kalshi 情况）请参见 [docs/15-tournamental-brand-and-positioning.md](docs/15-tournamental-brand-and-positioning.md)。 ## 免责声明 本项目仅用于教育和演示目的。Tournamental 不提供或促成真钱投注。消费受版权保护的广播、抓取付费数据源或重新发布授权跟踪流的生产者实现，由运行它们的运营商负责，而非本框架。运营商有责任确认其所在司法管辖区任何市场数据展示或联盟链接放置的合法性。 ## 许可证与结构 Tournamental 在 **Apache 2.0**（代码）和 **CC-BY-4.0**（文档）下**100% 开源**。品牌、商标和官方 `@TournamentalBot` Telegram 身份由 **Tournamental** 拥有，*不*授权给 fork——请参见 `TRADEMARK.md`。任何人都可以 fork 该协议，运行自己的实例，设置自己的联盟目的地，构建自己的世界。 **贡献者收入分成。** 净联盟收入（及其他货币化渠道）的固定百分比流向一个公共 Drips Network 资金库，该资金库按季度向有积分的贡献者流式支付 USDC。代码合并、接受的 RFC、基于平台构建的游戏、漏洞披露和主要审查都为该池赚取收益。**这是收入分成，不是股权。** 完整设计和贡献者入门请参见 [docs/19-open-source-and-contributor-revenue.md](docs/19-open-source-and-contributor-revenue.md)。 **可比较的结构。** Optimism、Filecoin、Mozilla、Linux Foundation、Radworks。基金会支持的开放协议，品牌和资金库由实体控制，贡献者通过链上流式支付进行收入分成。 资产包（头像、体育场模型、球衣纹理）遵循其原始创建者的许可证；框架本身不包含任何资产包。 ## 子处理器 生产环境的 Tournamental 界面依赖以下第三方服务。新贡献者在发布任何涉及用户数据的内容之前，应了解数据流边界。同一列表出现在 [SECURITY.md](SECURITY.md) 中，用于安全披露上下文。 - **Supabase** -- 托管的 Postgres + 认证（用户记录、会话、预测、排行榜）。 - **Cloudflare** -- DNS、CDN、Workers、Tunnel、WAF；每个 Tournamental 界面的公共边缘。 - **Aiva SMS** -- 认证流程中用于 OTP 交付的 SMS 和 WhatsApp 网关。 - **GoHighLevel** -- 用于辛迪加注册和营销自动化的 CRM。 - **npm registry** -- `@tournamental/*` 包的分发渠道。 - **GitHub** -- 源代码托管、问题、讨论、发布和安全公告。 - **Drips Network** -- 链上贡献者收入资金库（以太坊 + L2）。 - **Polymarket** -- 用于难度计分的只读预测市场赔率。 - **StatsBomb Open Data** -- 用于回放演示的只读历史比赛数据。 子处理器的变更作为独立 PR 发布，并附带 CHANGELOG 条目和 SECURITY.md 更新。 ## 社区 - **Discussions** -- 在 [GitHub Discussions](https://github.com/0800tim/tournamental/discussions) 上交流想法、寻求帮助和展示。模板位于 [`.github/DISCUSSION_TEMPLATE/`](.github/DISCUSSION_TEMPLATE/)。 - **Discord** -- 在 [discord.gg/tournamental](https://discord.gg/tournamental) 实时聊天（邀请链接将在公开发布时最终确定，参见 [docs/55-public-launch-checklist.md](docs/55-public-launch-checklist.md)）。 - **行为准则** -- [Contributor Covenant 2.1](CODE_OF_CONDUCT.md)。向 `0800tim@gmail.com` 报告违规行为。 - **安全** -- [SECURITY.md](

标签：3D渲染, CMS安全, DNS解析, JavaScript, MCP协议, npm包, Oracle网络, TypeScript, Web3, 区块链游戏, 去中心化应用, 威胁情报, 安全插件, 开发者工具, 开源项目, 技术栈集成, 插件SDK, 搜索引擎查询, 暗色界面, 游戏开发, 游戏渲染器, 电子竞技, 社区驱动, 自动化攻击, 锦标赛预测, 预测市场, 验证系统