代码架构与 IPO

我们的智能体跑台遵循一条贯穿始终的 (I) 输入 - (P) 处理 - (O) 输出 解耦主干：

1. 物理环境层 (run_game.py)

这是真正控制谷歌足球底层沙箱命运的神之手，承载着每一个物理动作的执行效力。

(I) Input: 接收从网关打回来的 action_id (0-18)。
(P) Process: 引擎根据牛顿运动定律等物理法则进行内部运算。为了保证大模型不需要像肌肉记忆那样操作每一帧，我们引入了 interval（跳帧）。即在 LLM 未给出新指令的空白帧里，持续复用（或重置为 0）当前的动作 ID。
(O) Output: 吐出 reward (奖励得分信号) 和包含全场 22 名球员 XYZ 坐标与当前球权的 Raw Observation Dict。

大模型是没有视觉感知的，所以我们需要在这里充当它的眼睛。我们把生硬的数学大坐标数组，转化为有感情的人类态势小语段。

(I) Input: 环境层抛出的 Raw Observation 坐标字典。
(P) Process: 代码会遍历我方持球状态、最近防守人距离、我方与敌方的阵型结构。同时根据先验规则判断是否有传球阻碍，以及前场是否有开罗的接应队友。
(O) Output: 提炼为高度浓缩的 态势字符串描述 (Text Description)。如：“我方1号距离球门较远，周围有2名防守球员包夹...”

这部分是调动云端无尽算力池的枢纽，我们支持 OpenAI-compatible 等各种标准化 RESTful API 的打桩调用。

(I) Input: 将固化好的“足球技战术指南 (System Prompt)”与上面新鲜出炉的“态势字符串”做拼接，并组合上最近的 Working Memory。
(P) Process: 通过 HTTPS 外发调用大模型。考虑到 API 的网络波动，我们实现了一套基于指数退避算法的并发重试机制（默认重试 5 次，规避 429 和 5xx 等偶发故障）。
(O) Output: LLM 会从云端返回含有复杂内部剖析的纯文本或 JSON 串。

为了对付极其容易在最后一公里“耍滑头”（输出非标准结构）的大语言模型，这里设置了三道防线。

(I) Input: LLM 回传回来的凌乱输出流 raw_response_string。
(P) Process:
- 第一道防线：正则提取 {...} 纯 JSON 块进行反序列化。
- 第二道防线：如果第一道崩了，强行在上下文搜索形如 action: 11 的孤立数字挂载。
- 第三道防线：如果前两道全崩，则尝试命中“传球”、“射门”等语义关键词池。
- 如果全军覆没，Fallback 判定：让小人罚站不动 (action_id = 0)。
(O) Output: 安全合法的 action_id (0-18)。

如果你不满足于单一跑通，这里就是量产机器人的终极评估测试间！

(I) Input: 一份配置好的候选模型参赛花名册 MODELS_TO_TEST。
(P) Process: 脚本为每一个参赛者建立沙箱化 YAML 配置文件，按序启动单次 Python 隔离进程进行对抗，并由内置 Logger 事无巨细地写入他们每一次推理的耗时和响应文本。
(O) Output: 在每个独立空间吐出一份 final_report.json，经合并后变为整个生态的 data.json 与前端静态 Leaderboard。