开发

贡献者工作流：开发环境、测试套件、lint 与类型检查。

准备开发环境

前置条件：EVA Client 源码、uv，以及 Python 3.10+。详见安装页面。下列命令在项目根目录执行；[dev] 附加项会拉入 pytest、ruff、pyright。

bash

# 创建并启用 venv
uv venv --python 3.10 --system-site-packages .venv
source .venv/bin/activate

# 安装 EVA Client 与贡献者工具
uv pip install -e ".[dev]"

每个新开的 shell 都要重新执行 source .venv/bin/activate。代理导致安装卡住时，用 unset http_proxy https_proxy 清除。

在项目根目录运行，改完代码后、提交前都应执行：

bash

# 全部测试
pytest

# 跳过 slow IK 测试
pytest -m "not slow"

# 单一目录
pytest tests/integration/web

带 slow 标记的测试依赖可选 IK 库；缺失时自动跳过，干净机器仍可通过。

目录	检查内容
`tests/config/`	配置加载与合并；策略与机器人选择。
`tests/comms/`	策略服务器传输与网络数据流。
`tests/ik/`	IK 求解器，含 slow 测试。
`tests/strategy/`	推理策略与动作缓冲区。
`tests/transport/`·`tests/recorder/`	ROS 传输层与 episode 记录器。
`tests/integration/web/`	通过 HTTP 端到端驱动 Web 控制台。

无需安装 ROS 或接入硬件——机器人侧已被伪造。

tests/integration/web/ 会启动真实的控制台服务器，通过 HTTP 驱动，不需要 ROS、不需要硬件、不需要策略服务器——机器人传输层与策略均已被打桩。编写或修复此类测试时使用该目录下的辅助函数。

tests/manual/ 下是 pytest 之外的独立端到端脚本：

bash

PYTHONPATH=src python tests/manual/<脚本>.py

脚本	流程
`verify_eval_flow_e2e.py`	完整 EVAL 运行：开始、录制、打分、续跑、打分规则。
`verify_eval_rollout.py`	打分边界情况与同一次试验的重测。
`verify_eval_lerobot_meta.py`	试验分数与备注被写入录制数据集。
`viser_track_chunk.py`	交互式 3D 工具：录制手部路径，查看解算关节运动的跟随精度。

提交前运行：

bash

# lint，再自动修复
ruff check .
ruff check --fix .

# 格式化
ruff format .

# 类型检查
pyright

运行一次 pre-commit install 启用 pre-commit 钩子，提交时自动跑 ruff。

CLAUDE.md（同一文件亦可作为 AGENTS.md 访问）是贡献者指南。关键规则：