企业官网建设流程全解析

简介：这套代码包面向RoboCup 3D仿真足球赛研究者、参赛队员和多智能体决策学习者，提供2012年南京邮电大学冠军队的可执行程序及配套工程文件，可用于复盘冠军队伍的战术决策、通信协作和实时控制实现。压缩包共175个文件，约29.13MB，主体由76个rsg行为策略脚本和69个svn-base版本库文件构成，另有format、entries、all-wcprops等版本控制元数据，以及rb、sh、so等运行构建文件，并包含apollo3d和点球攻防等专项配置，目录保留了较完整的开发迭代痕迹。对于希望理解仿真足球智能体如何感知环境、选择动作并组织团队配合的读者，这份代码提供了直接参照，也可用于研究多智能体协同与强化学习策略。已有900人学习，适合在Apollo3D环境中对照分析比赛决策逻辑，并为无人车编队等群体智能应用提供思路。

1. 从一份 2012 年的冠军可执行包说起：3D 仿真机器人足球里到底跑着什么

有人把一份 2012 年 3D 仿真机器人足球赛冠军队伍的可执行代码包丢过来，问能不能跑。我第一反应不是膜拜，而是先看它到底是源码还是二进制——冠军可执行代码包的尴尬就在这儿：它证明了那年这套决策确实打赢了，但你手里拿到的可能是一堆.so加启动脚本，改一行都得靠猜。这类包适合两种人：想复现当年顶级 agent 时序控制的、想做多智能体仿真对抗实验的。它能给你一个完整的闭环——连服务器、收报文、估位姿、出动作，只是每一步都藏在编译产物后面。跑通它，比读十篇论文都直观。

2. 三段式架构拆解：服务端、监视器与球员进程怎么对上话

这类仿真赛事的整套系统从来不是"一个程序"，而是三个角色凑成的闭环：仿真服务端负责物理和裁判，监视器负责把画面画出来给你看，球员进程（agent）负责思考和下发关节指令。冠军包给的通常只是第三段，前两段要你自己找对应的服务端版本配上去。版本对不上，跑起来第一秒就会看到球员像抽风一样原地抽搐，这是血泪经验里最常见的一课。

2.1 进程拓扑与端口分配

服务端一般会开两个监听口：一个给球员进程连，一个给监视器连。常见做法是 3100 给 agent、3200 给监视器，队伍数量、场上人数、每周期时长都由服务端启动参数决定。球员进程连上之后不是立刻能动，得先发一条初始化报文，把队伍名和自己的编号报上去，服务端认了才给你发感知数据。这个握手阶段最容易翻车：同一队伍名、同一编号被占，后到的那个会被直接踢掉，而且不一定给你任何提示。

监视器这边其实是"只读"的，它连上去只收不发，用来肉眼确认球员到底在干嘛。调试阶段千万别省这一步——你从终端日志里看到的"球员在走"，和监视器里看到的"球员在原地高抬腿"完全是两回事。

2.2 球员侧主循环：20 毫秒里的感知—决策—执行

不管这套代码内部封了多少层，球员进程的骨架永远是同一个循环：收包、更新世界模型、决策、下发指令、对齐节拍。仿真周期常见是 20 毫秒，也就是每秒 50 拍，所有动作都是在这 50 拍里挤出来的。冠军包和普通包的最大差别往往不在算法多玄学，而在节拍对齐得稳不稳——累积漂移超过两三拍，动作就会明显拖沓。

// agent 主循环：一个仿真周期内的完整时序 int main(int argc, char** argv) { Agent agent; // 队伍名和球员编号必须和启动脚本、服务端配置三方一致 if (!agent.connect("127.0.0.1", 3100, "MyTeam", 1)) { fprintf(stderr, "connect failed\n"); return 1; } while (agent.isAlive()) { double t0 = agent.now(); agent.receive(); // 非阻塞收包，把这一拍的 SIM_* 全吃进来 agent.updateWorldModel(); // 感知 -> 世界模型 Action act = agent.decide(); // 决策 -> 关节角度 / 力度 agent.send(act); // 下发 hj 指令 double dt = agent.now() - t0; if (dt < 0.020) agent.sleep(0.020 - dt); // 对齐仿真节拍 } return 0; }

这段代码里三个参数值得盯死：3100是服务端给 agent 的端口，改了要和启动脚本同步；"MyTeam"是队伍名，服务端按名字分队，写错就等于没上场；1是球员编号，同一队伍内必须唯一。0.020这个常量不是随便写的，它是服务端step的时长，agent 侧如果按 10ms 跑，看起来"更快"，实际会在两拍之间重复下发同一条指令，表现就是关节抖动。

2.3 可执行包的目录结构与启动脚本

拿到二进制包，先别急着点。一个典型的冠军包解开之后长这样：

启动脚本通常是一个 shell 循环，按编号拉起 N 个球员进程，再单独拉监视器。常见做法是每个进程nohup到各自的日志文件里，因为一个终端窗口混着 N 个进程的输出根本没法看。

# 一键拉起一支队伍：先起 N 个球员，再起监视器 #!/bin/bash TEAM="MyTeam" SRV="127.0.0.1" for i in $(seq 1 4); do # 每个球员单独一份日志，出问题按编号快速定位 nohup ./bin/agent --host $SRV --port 3100 \ --team $TEAM --unum $i > log/agent_$i.log 2>&1 & done # 监视器后起，用来肉眼确认球员是否真的在动 nohup ./bin/monitor --host $SRV --port 3200 > log/monitor.log 2>&1 &

这个脚本里seq 1 4的数字必须和当年规则里场上人数对上，多起一个会抢不到编号、少起一个就少个人。--unum传的是球员编号，不是序号，中间跳号在某些服务端实现里会被判无效。日志按编号分开这件事看着小，实测时能省掉一半排查时间——至少你知道是 3 号球员不动还是全部都不动。

3. 世界模型与感知层：把 SIM_* 报文拼成一张能用的球场态势图

决策层再花哨，喂给它的数据脏了全是白搭。球员进程每拍收到的是几段文本报文：自身关节角度、陀螺仪读数、脚底压力、听觉消息，以及视觉看到的地标、球、队友坐标。这些数据带噪声、带延迟、还经常这个周期有那个周期没有。世界模型要干的事就是把它们揉成一份"当前我大概在哪、球大概在哪、队友大概在哪"的估计，然后交给决策层消费。

3.1 报文解析与坐标系对齐

报文是 S 表达式，形如(HJ (n hj) (ax 1.2) ...)，嵌套不深但字段多。冠军包里通常有个手写的极简解析器，只认自己关心的那几类。自己重写一份不亏，因为后面加日志、加回放全靠它。

// 极简 S 表达式解析：只拆一层 (key v1 v2 ...)，够用且好调 bool parseSExpr(const std::string& msg, std::map<std::string, std::vector<std::string>>& out) { size_t i = 0; while ((i = msg.find('(', i)) != std::string::npos) { size_t end = msg.find(')', i); if (end == std::string::npos) break; std::string body = msg.substr(i + 1, end - i - 1); std::istringstream iss(body); std::string key; iss >> key; // 第一段是报文类型，如 HJ / FRP / GS std::vector<std::string> vals; std::string tok; while (iss >> tok) vals.push_back(tok); // 后面全是键值对 out[key] = vals; i = end + 1; } return !out.empty(); }

key就是报文类型，vals是拍平后的键值对序列，取值时按(n xxx)找名字、下一项取数。这个解析器处理不了深层嵌套，但对这几类报文足够。真正要小心的是坐标系：视觉给的是相对自身的极坐标，听觉给的队友位置是绝对坐标，压力传感器又只有正负。三套坐标系混着用，不先统一到球场绝对系，后面所有判断都是错的。

3.2 球与自身位姿的滤波估计

原始视觉数据抖得厉害，一帧球在左脚边、下一帧飞到右脚边，直接用会让球员像被电到一样反复转身。常见做法是对球做滑动窗口或者一阶低通，对自身位姿则靠地标三角定位加历史预测。

class BallFilter { public: void update(double x, double y, double t) { if (!hasPrev) { pos = {x, y}; lastT = t; hasPrev = true; return; } double dt = t - lastT; if (dt <= 1e-6) return; // 同一拍重复数据直接丢 double vx = (x - pos.x) / dt; double vy = (y - pos.y) / dt; // 系数 0.3 是经验值：太大跟不住快球，太小转向迟钝 vel.x = 0.7 * vel.x + 0.3 * vx; vel.y = 0.7 * vel.y + 0.3 * vy; pos = {x, y}; lastT = t; } struct { double x, y; } pos{0, 0}, vel{0, 0}; private: bool hasPrev = false; double lastT = 0; };

0.3这个融合系数是整套估计里最需要手调的参数。球速快的时候系数偏大会让估计滞后，球员总是追在球后面；系数偏小又会被噪声带跑，球明明停着球员却判断它在滚。我的做法是先按 0.3 起步，然后在回放日志里对比"估计球速"和"下一拍实际球位移"，偏差长期超过 0.2 米每秒就往上调。视觉丢球超过三拍时，这里还得加一条兜底逻辑：直接沿用上一拍的估计并衰减速度，而不是把位置清成零——清零会让球员瞬间往中场跑。

3.3 一个最小可用的世界模型类

把上面几块拼起来，世界模型的接口其实很薄。它不负责决策，只负责"给出当前最可信的一份描述"。

class WorldModel { public: void update(const ParsedMsgs& msgs, double now) { // 1. 自身关节 / 陀螺仪：用来判断是否跌倒 if (msgs.has("HJ")) { mGyro = parseGyro(msgs["HJ"]); mFallen = fabs(mGyro.ay) > 1.2 && mFallTime > 0.4; // 持续跌倒才判定 } // 2. 视觉：球、队友、地标 if (msgs.has("See")) { auto see = parseSee(msgs["See"], mSelfPose); if (see.ballValid) mBall.update(see.ball.x, see.ball.y, now); for (auto& m : see.mates) mTeammates[m.unum] = m.pose; } // 3. 听觉：队友报的位置，用来补视觉盲区 if (msgs.has("hear")) mergeHearing(msgs["hear"]); } Vec2 ballPos() const { return {mBall.pos.x, mBall.pos.y}; } Vec2 ballVel() const { return {mBall.vel.x, mBall.vel.y}; } bool isFallen() const { return mFallen; } BallFilter mBall; Pose mSelfPose; std::array<Pose, 8> mTeammates; Gyro mGyro; private: bool mFallen = false; double mFallTime = 0; };

mFallTime > 0.4是防误判的关键：单拍陀螺仪冲一下不算摔倒，持续 0.4 秒才认为是真跌了。这个阈值调小了，球员会在急停时自己触发起身动作；调大了，真摔了要在地上趴半秒才反应。听觉融合那块要加可信度过滤，队友报的位置可能已经是几拍前的旧数据，直接用会让整个队的位置估计集体漂移。

4. 决策与行为层：分层状态机怎么把「追球」拆成可调的零件

冠军包的决策层如果反编译看，多半是一坨嵌套极深的状态机。但设计思路上其实是清楚的：上层决定"我这拍该扮演什么角色"，中层决定"这个角色该走什么流程"，底层才是"腿怎么摆"。分不清这三层，改一个动作能在五个地方引发连锁反应。

4.1 动态角色分配：谁去追球，谁去补位

多智能体最忌讳所有人都追球。常见做法是按"预测到达时间"分配：谁能在最短时间内碰到球，谁就是主攻，其余人按固定槽位补位。这个计算每拍重算一次，但要加滞回，否则两个球员会在一瞬间来回交换角色，看起来像互相谦让。

// 谁到球的预测时间最短，谁去追；其他人按槽位站 int pickChaser(const std::vector<Player>& mates, const BallFilter& ball, double now) { int best = -1; double bestT = 1e9; for (const auto& p : mates) { if (p.unum == 1) continue; // 守门员不参与追球 if (now - p.lastSeen > 3.0) continue; // 三秒没看到就当他不可用 double t = predictReachTime(p.pose, ball.pos, ball.vel); // 0.3 秒滞回：现任主攻有优势，避免每拍来回换人 if (p.unum == mCurrentChaser) t -= 0.3; if (t < bestT) { bestT = t; best = p.unum; } } return best; }

predictReachTime用匀速模型估就够了：算球员到球的直线距离除以最大步速，再叠加上球速方向的偏移。0.3秒的滞回值是整个分配逻辑的稳定器，小了这个值角色会抖，大了主攻明显跑不动了才换人。3.0秒的失联判定用来处理队友掉线——没这条，一个已经掉线的队友会一直霸占主攻位置，全队陪着站桩。

4.2 分层状态机的写法：Play → Role → Behavior

我一般把决策拆成三层：Play（整体战术，比如进攻 / 防守 / 开球）、Role（这一拍我扮演谁）、Behavior（具体的动作序列）。每层只往上返回一个枚举，不跨层调用，这样改战术的时候不用动动作代码。

Action BehaviorEngine::run(WorldModel& wm) { // 第一层：全局战术。开球、防守、正常进攻三选一 mPlay = selectPlay(wm); // 第二层：角色。主攻 / 支援 / 补位 / 守门 mRole = selectRole(wm, mPlay); // 第三层：动作。摔倒优先级最高，直接短路 if (wm.isFallen()) return mGetUpAction; if (mPlay == PLAY_KICKOFF) return handleKickoff(wm); switch (mRole) { case ROLE_CHASER: return chaseBall(wm); case ROLE_SUPPORT: return moveToSlot(wm, mSupportSlot); case ROLE_KEEPER: return guardGoal(wm); default: return standStill(); } }

selectPlay里判断开球、判断是否被压在半场，都是纯规则，不用上机器学习。wm.isFallen()短路放在最前面，是因为摔倒状态下算任何战术都是浪费，而且起身动作必须在有限时间内触发，晚了会被裁判判罚。mSupportSlot是槽位坐标，按球的位置做横向偏移算出来，偏移量别写死，跟着球的纵坐标走，否则支援球员永远站在一条直线上。

4.3 行走与踢球的参数化封装

底层动作不该在决策层里暴露关节角度。冠军包的通常做法是维护一张动作表，每个动作是一串关键帧，决策层只按名字选。

struct Action { std::string name; std::vector<JointFrame> frames; }; Action kick(const WorldModel& wm, const ActionTable& table) { Vec2 toBall = wm.ballPos() - wm.selfPose.xy(); double dist = toBall.length(); // 1.2 米以外先走过去，硬踢会踢空并摔倒 if (dist > 1.2) return table.get("walk_forward"); double angErr = normalizeAngle(atan2(toBall.y, toBall.x) - wm.selfPose.theta); // 0.3 弧度以内才出手，否则先转身对准 if (fabs(angErr) > 0.3) return table.get("turn_to_ball"); return table.get(mKickTable.select(dist, angErr)); // 近距离用推射，远了用抽射 }

1.2米是踢球的有效半径，超出这个距离踢出去的动作会因为够不着而变成前扑摔倒。0.3弧度约 17 度，是允许的朝向误差，再大就会把球踢偏到边线。mKickTable.select里按距离和角度两维查表，这是最实用的参数化方式——不用重新编译，改动作表文件就能换踢法。

5. 避坑排查：把冠军包跑起来时最容易翻车的五个点

这套东西的报错信息少得可怜，大部分时候你看到的就是"不动"。下面五条是我实际踩过的，按启动阶段和运行阶段分开。

5.1 启动与连接阶段

第一条：连上了，但球员一动不动。现象是日志里只有连接成功，没有感知数据。原因基本是初始化报文被拒——队伍名带了空格、编号重复、或者服务端根本没开对应队伍。解决方式是把服务端的启动参数和 agent 的--team/--unum逐字符对齐，先只起一个球员验证连通，确认能收到See报文再起全队。

第二条：进程秒退，日志里只有一行 segfault。现象是启动脚本跑完ps里啥也没有。原因通常是可执行包依赖运行目录下的相对路径（动作表、参数文件），从别的目录启动就找不到。解决方式是在脚本开头强制cd到包根目录再执行，或者把配置路径改成绝对路径。

# 启动前先切到包根目录，二进制里的相对路径才有意义 cd "$(dirname "$0")/.." || exit 1 ./bin/agent --host 127.0.0.1 --port 3100 --team MyTeam --unum 1

第三条：全部球员能起来，但服务器一启动就被踢。现象是球员连上三五秒后集体掉线。原因多半是服务端版本和这套可执行包的协议代次不匹配，报文格式变了但二进制没法改。解决方式很笨但有效：换服务端版本，让服务端去迁就包，而不是反过来。

5.2 运行阶段的行为异常

第四条：球员原地高抬腿或者持续抽搐。现象是监视器里能看到关节在动，但人不往前走。原因几乎都是节拍没对齐——agent 按 10 毫秒跑，一个仿真周期内下发两次指令，两次之间关节角度差被服务端当成加速度过大的异常动作。解决方式是按2.2里的写法用绝对时钟扣掉执行耗时再 sleep，别用固定sleep(0.02)。

第五条：丢球三秒后全队往中场跑。现象是球被踢远、视觉暂时看不到，球员就开始集体回中。原因是世界模型在视觉丢失时把球位置清成了零，被决策层理解成"球在中场"。解决方式是加丢球兜底：丢掉超过三拍就沿上一拍的速度做匀速外推，超过两秒才清空，并同时触发"搜索球"行为而不是回中。

6. 二次开发：没有源码的可执行包，怎么改成自己的打法

先接受一个现实：冠军可执行包大概率没源码。这种情况下改造的抓手只有三个——配置文件、动作表、外围包裹进程。配置文件改队伍名、改球员数、改服务端地址，这些是最安全的，改完直接重启就能验证。动作表是第二个抓手，很多包会把关键帧放在data/下的文本或二进制里，文本的能直接改，二进制的只能靠试：把某个动作的幅度调小 10%，跑一遍看球员是不是还站得住。

如果连动作表都是二进制，那就上第三招——外层包裹。自己写一个小代理，夹在服务端和原 agent 之间，收发包都过一手。

// 中间人代理：原 agent 的输出可以被改写，输入可以旁路记账 void relay(UDPSocket& fromAgent, UDPSocket& fromServer) { std::string pkt; if (fromAgent.recv(pkt, 0)) { // agent 想下发的关节指令，先记账再转发 mLogger.log("agent_out", pkt); patchIfNeeded(pkt); // 在这里做限幅、丢帧、注入 fromServer.send(pkt, kServerAddr); } if (fromServer.recv(pkt, 0)) { // 服务端的感知数据，旁路一份给回放器 mLogger.log("server_out", pkt); fromAgent.send(pkt, kAgentAddr); } }

这个代理的价值不在"改"，在"看得见"。原包是黑匣子，套上代理之后每一拍进出都有记录，你可以先只做记录不改写，跑三场完整对抗，然后把 trace 拉出来看：主攻在第几拍换人、丢球后多久回中、踢球动作在多少距离触发。参数摸清了，再在patchIfNeeded里做限幅或者按条件丢包，就能比较温和地改行为，而不是一上来就硬替换。

有个表格我一般会先填，填完再动手：

验证方法我一律用同场景重放：把服务端固定成同一初始状态，跑十场，统计控球时间和进球数，改动前后各跑一轮。凭一两场感觉"好像变强了"这个判断基本不可靠，尤其是仿真里噪声大的时候。

最后说个教训。我最早拿到这类包的时候，第一件事是反编译找主逻辑，折腾了三天什么都没得到。后来换了个顺序：先跑通、先记账、先把 trace 读熟，参数摸清楚了才发现真正要改的往往只有两三个数。从那以后我每次拿到不可编译的发布包，都强制先跑满三场完整对抗并落 trace，再决定动不动代码。希望帮到你。

本文还有配套的精品资源，点击获取