AGENTS.md

walk-these-ways-go2 是一个面向 Unitree Go2 的 sim-to-real 强化学习项目，主要工作是在原 walk-these-ways 思路上适配 Go2，并通过 Unitree SDK2、LCM、Python 推理脚本实现真实机器人部署。

仓库大体分为几块：

• go2_gym：训练环境、Go2 配置、奖励和仿真相关代码。
• go2_gym_learn：强化学习训练框架相关代码。
• go2_gym_deploy：部署侧代码，包括 LCM agent、状态估计、遥控器映射、C++ Unitree SDK2 桥接程序。
• scripts：训练、play、测试入口。
• runs、logs、media、resources：预训练模型、日志、图片和机器人资源。

Codex 可以协助的改进方向

1. 文档和上手体验

Codex 可以把 README 中的安装、训练、PC 部署、Jetson 部署流程拆成更清晰的文档结构，例如：

• docs/install_pc.md
• docs/train.md
• docs/deploy_pc.md
• docs/deploy_jetson.md
• docs/troubleshooting.md
• docs/safety.md

目前 README 已经覆盖了很多关键信息，但内容较长，而且训练、部署、安全提示、Jetson 环境、已知问题都混在一起。Codex 可以帮助整理成更适合新用户查找的文档，并补充常见错误排查，比如 LCM 未安装、网卡名错误、sport_mode 未关闭、模型路径不匹配、CUDA/PyTorch 版本不兼容等。

2. 环境和依赖管理

项目对 Isaac Gym、PyTorch、CUDA、LCM、Unitree SDK2、Jetson 环境都有依赖。Codex 可以帮助维护：

• Conda 环境文件，例如 environment.yml。
• PC 和 Jetson 分开的依赖说明。
• C++ 构建依赖检查脚本。
• Python 包版本约束整理。
• 安装前自检脚本，例如检查 CUDA、PyTorch、LCM、网卡、模型文件是否存在。

这类改进可以降低用户复现门槛，也能减少 issue 中关于环境配置的重复问题。

3. Docker 和 Jetson 部署

README 里 Docker 部分仍是待完成项。Codex 可以协助补全：

• 面向 PC 训练/推理的 Dockerfile。
• 面向 Jetson Orin 的 Dockerfile 或构建说明。
• Docker Compose 示例。
• 容器访问网卡、LCM、Unitree SDK2 的注意事项。
• 镜像构建和运行命令文档。

这会让项目更容易在不同机器上复现，尤其适合机器人项目中常见的“环境能不能跑起来”的问题。

4. 部署安全和运行保护

真实机器人部署代码里已经有一些安全机制，例如姿态角超限进入 damping mode、遥控器组合键切换模式等。Codex 可以帮助进一步梳理和增强：

• 把安全阈值、PD 参数、默认姿态等硬编码值集中配置化。
• 增加启动前 checklist 和运行时状态打印。
• 增加 LCM/DDS 消息超时检测。
• 增加模型推理异常、LCM 断连、SDK2 断连时的安全降级逻辑。
• 把遥控器按键映射整理成单独文档或配置表。

这类工作不一定改变算法，但对真实机器人部署的可靠性很重要。

5. 代码结构和可维护性

目前项目中训练、部署、SDK2 桥接、配置和实验产物混在同一个仓库里。Codex 可以协助做温和的结构整理，例如：

• 把重复或硬编码的路径封装成配置。
• 把部署脚本中的模型路径、最大速度、LCM URL、实验名改为命令行参数。
• 给关键模块补类型标注和更清楚的函数边界。
• 清理遗留注释、未使用代码和 Go1 迁移痕迹。
• 将 Go2 关节顺序转换、遥控器模式、LCM topic 名称集中管理。

这些改进可以让后续贡献者更容易读懂代码，也降低误改核心部署逻辑的风险。

6. 测试和 CI

机器人项目很难完全自动化测试，但 Codex 可以先补轻量级检查：

• Python import smoke test。
• 配置文件加载测试。
• LCM message encode/decode 测试。
• CMake 配置阶段检查。
• 关键脚本的 --help 或 dry-run 检查。
• GitHub Actions 中的格式检查、静态检查、基础构建检查。

这类测试不需要真实机器人，也可以尽早发现路径错误、依赖缺失、语法错误和接口变更。

7. 仓库体积和版本管理

快速阅读时可以看到仓库中包含一些构建目录、日志、预训练模型或二进制产物。Codex 可以帮助：

• 检查 .gitignore 是否覆盖所有生成文件。
• 评估是否把大文件迁移到 GitHub Releases、Git LFS 或外部下载链接。
• 清理误提交的 build 目录、缓存文件、临时模型。
• 建立“源码仓库”和“模型/数据产物”的边界。

这会让 clone、fork、review、CI 都更轻量。

8. 训练配置和实验管理

Codex 可以帮助把训练入口和配置管理做得更清楚：

• 给 scripts/train.py、scripts/play.py 增加参数化入口。
• 整理 Go2 训练配置说明。
• 标注哪些参数适合普通用户调整，哪些参数不建议随便改。
• 生成实验记录模板，包括训练命令、commit hash、模型路径、环境版本、主要指标。

这能帮助维护者和使用者更容易复现实验结果。

9. Issue 和社区维护

项目已有不少用户关注，Codex 可以帮助维护社区协作材料：

• Issue 模板：环境问题、部署问题、训练问题、Bug report。
• PR 模板：说明测试方式、机器人实机验证情况、安全影响。
• FAQ：把高频问题沉淀到文档。
• Roadmap：例如 Docker、Jetson、SDK2 更新、模型发布、真实机器人安全验证。

这些内容可以减少维护者重复回复，也让贡献者更容易提交有效信息。

可以优先做的低风险事项

如果希望从小步开始，建议 Codex 优先协助做这些：

1. 拆分和重写文档，让安装、训练、部署、安全说明更清晰。
2. 增加 environment.yml 和依赖自检脚本。
3. 把部署脚本里的模型路径、网卡、LCM URL、速度上限改成命令行参数。
4. 清理或隔离 build 目录、临时模型、大文件产物。
5. 增加基础 CI：Python 语法检查、import 检查、CMake 配置检查。
6. 补全 Docker/Jetson 部署文档。

总结

Codex 对这个项目最有价值的帮助，不一定是直接修改强化学习算法，而是提升项目的工程化程度：让环境更容易搭建、部署更安全、配置更清楚、文档更可维护、贡献流程更稳定。对于真实机器人项目，这些改进会直接降低复现成本和使用风险。