Hafiz Muhammad

项目名称
PadelFlow

团队成员

Alfin
Hafiz

问题陈述

组织 Americano 和 Mexicano 板式网球锦标赛的过程是手动且容易出错的。组织者必须手动安排比赛、跟踪比分，并在排名发生变化时重新计算积分榜——随着参赛人数增加，这一过程变得更加困难，而在实时比赛中，随着回合完成和排名变化，情况会变得更糟。
拟议解决方案

主要思路：PadelFlow – 一个由 Google 开源权重 Gemma 4 26B 驱动的 AI 赋能的板式网球锦标赛管理平台，运行于 Model Garden。
目标用户：需要快速设置、公平排赛和实时记分的 Americano 和 Mexicano 板式网球锦标赛组织者。
核心用户体验：组织者输入描述锦标赛的提示词 -> AI 提取锦标赛详情并推荐场地 -> 比赛自动生成 -> 组织者通过带有实时记分和实时排行榜的仪表板实时管理赛事。
预期成果/效益：即时锦标赛设置，无需手动排赛，自动化公平比赛轮换，以及实时排行榜准确性。
Gemma 集成
Gemma (gemma-4-26b-a4b-it-maas) 部署在 Google Cloud Vertex AI 和 Vertex AI Model Garden 的 3 个专业代理节点上：

ai_tournament_generator（AI 锦标赛生成器）：解析自然语言输入，提取锦标赛参数，强制要求必须信息（选手人数、比赛类型、场地），并在缺少必须信息时运行多轮挑战循环。
ai_venue_finder（AI 场地查找器）：根据用户位置查询推荐具有球场容量的板式网球场地。
tournament_advisor_chat（锦标赛顾问聊天代理）：一个专业的对话式 AI 端点（/api/ai/chat），回答关于 Americano 与 Mexicano 规则、轮换策略和选手配对建议的问题。
代理开发工作流
Antigravity 使用

全栈架构：搭建并构建了 Python 3.12 FastAPI 后端、ADK 2.x 代理运行器、A2A 协议路由和 Cloud Firestore 存储层。
锦标赛算法：在 padel_logic.py 中设计了 Americano 双人轮换矩阵数学和 Mexicano 基于动态排名的排赛逻辑。
UI 重构与现代美学：将前端重构为编辑级体育科技界面，支持暗/亮主题、电视转播风格的计分板和响应式布局。
多轮 AI 验证：创建多轮挑战循环，防止在提示详情缺失时出现幻觉或通用场地名称。
技能与 MCP 集成

google-agents-cli-workflow & google-agents-cli-adk-code：端到端 ADK 开发生命周期、代理/运行器代码模式和 A2A 端点定义。
google-agents-cli-deploy：Cloud Run 部署自动化和服务管理。
firebase-firestore：集成 Cloud Firestore SDK 以实现持久锦标赛存储。
web_application_development：设计系统令牌、暗/亮主题 CSS 变量、排版和可访问性最佳实践。
开发影响
实现了 100% 测试通过率（13/13 单元和集成测试）、100% 多轮可靠性（防止幻觉场地建议）、100% 比分完整性（通过严格验证）和零数据丢失（通过跨容器重启的实时 Firestore 持久性）。
Google Cloud 架构

客户端：原生 HTML5、CSS3 自定义属性（带有 HSL 令牌的暗/亮主题）、现代 ES6+ JavaScript（app.js）。
AI 后端：Python 3.12 + FastAPI + Google ADK 2.x + google-genai Python SDK，调用 Vertex AI 上的 gemma-4-26b-a4b-it-maas。
数据流：用户提示词 -> POST /api/ai/generate-tournament -> Vertex AI 上的 Gemma -> 结构化 JSON（锦标赛详情）-> padel_logic.py（配对逻辑）-> Cloud Firestore 存储 -> 仪表板（赛程、实时比分、排行榜）。
功能

工作特性：AI 锦标赛生成器、AI 场地查找器、锦标赛顾问聊天代理、自动 Americano/Mexicano 比赛生成、带胜者检测和比赛锁定的实时比赛记分、实时排行榜、锦标赛仪表板、锦标赛进度跟踪、自动最终排名和冠军宣布。
主要用户流程：组织者用自然语言描述锦标赛 -> AI 填充锦标赛表单并确认场地 -> 比赛自动生成 -> 组织者跟踪每场比赛的实时比分 -> 排行榜自动更新 -> 锦标赛以最终排名和冠军结束。
已知限制：需要与 Google Cloud Vertex AI 服务建立活动连接以进行 AI 提示生成和场地发现；需要支持 ES6 模块、Flexbox/Grid 和 CSS 变量的现代浏览器；每场比赛总分（score_a + score_b）不能超过 21。
项目链接

公共仓库：https://github.com/alfinwijaya/padel-flow
已部署应用：padel-flow-134929710348.us-central1.run.app（Google Cloud Run，us-central1）
公共 YouTube 演示：[插入 URL]
演示必须公开，时长不超过三分钟，并展示主要用户流程。
运行说明

uv tool install google-agents-cli
cd /home/devstar9594/padel-flow
agents-cli install

.env: GOOGLE_CLOUD_PROJECT=kodingdeepdive0826-9594, REGION=us-central1, GOOGLE_CLOUD_LOCATION=global

uv run python -m uvicorn app.fast_api_app:app --host 0.0.0.0 --port 8000 --reload # 运行于 http://localhost:8000
uv run pytest tests/unit tests/integration
agents-cli deploy -d cloud_run --service-name padel-flow --region us-central1 --project kodingdeepdive0826-9594 --no-confirm-project