Rerun 仓库开发协作指南：面向 LLM/Agent 的构建、代码生成、测试与架构全流程

Rerun 仓库开发协作指南面向 LLM/Agent 的构建、代码生成、测试与架构全流程【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本文基于 Rerun 仓库根目录的 AGENTS.md原CLAUDE.md整理而成是该仓库为 LLM/Agent 开发者提供的官方协作手册。Rerun 是一套面向机器人、空间 AI、计算机视觉等领域的时间感知多模态数据栈通过 Python、Rust、C 三种 SDK 记录图像、点云、张量等富数据再用 Viewer 进行可视化。读完本文你将掌握在该仓库内进行构建、运行、代码生成、格式化、测试与快照管理的完整命令体系理解re_type_definitions → codegen的代码生成管线与_ext扩展模式并学会借助 MCP 服务器驱动运行中的 Viewer 界面从而能够以 Agent 身份高效、合规地参与开发。仓库概览与协作前提Rerun 采用多语言、多 crate 的单仓库monorepo结构。对 LLM/Agent 而言进入仓库后首先要记住三条底线规则禁止手改生成文件所有由 codegen 生成的文件顶部都带有 DO NOT EDIT 标记必须通过修改定义源并重新运行代码生成来更新详见下文代码生成系统一节。变更 crate 需要同步文档新增、删除或重命名 crate 时必须同步更新 ARCHITECTURE.md 中的 crate 表格并提醒作者手动更新其中的 crate 组织结构图FigJam 导出图。提交 PR/Issue 需披露 LLM 身份不要主动开 PR 或 Issue除非被明确要求提交时遵循仓库的 PR/Issue 模板并如实披露你是 LLM。仓库的完整架构细节见 ARCHITECTURE.md构建细节见 BUILD.md测试约定见 TESTING.md。构建系统pixi 统一管理任务与依赖Rerun 使用 pixi 中。运行方式统一为pixi run TASKpixi run TASK后附加的 CLI 参数会被透传给任务命令本身。可用pixi task list列出全部任务。pixi.toml 中定义了多个环境environments核心区别如下default基础环境只做 Rust 开发时该环境就够用Python 运行时依赖放在独立的 uv 环境中管理见下文Python 开发工作流。cpp用于构建依赖 Crerun-sdk的代码会引入系统 C/C 编译器注意该环境当前会破坏 macOS 上 web viewer 的构建因此不要在与 viewer 构建相关的环境中启用它。coverage测试覆盖率工具链cargo-llvm-cov cargo-nextest独立成环境以保持默认环境的精简。构建命令任务作用pixi run py-build构建 Python SDK 到本地 .venv底层走 uv maturinpixi run rerun-build编译原生 viewer不含 web viewer即 Wasmpixi run rerun-build-web编译 web viewerWasm 目标pixi run cpp-build-all构建全部 C 产物pixi run py-build-release以 release 模式构建 Python SDKpixi run py-build-web-viewer构建带 web viewer 与 server 特性的 Python SDKpixi run rerun-build-fast用 Cranelift codegen 后端快速编译 viewer需 nightly toolchain 的rustc-codegen-cranelift-preview组件运行命令任务作用pixi run rerun编译并运行 viewer可附加参数指定要查看的 .rrd 文件pixi run uvpy script.py运行 Python 脚本自动带上 rerun SDKcargo run -p package_name运行特定 Rust 示例例如cargo run -p dnapixi run rerun-cli只编译并运行rerun-cli工具本身不重新编译 viewer适合跑快速命令pixi run rerun-perfrelease 模式下运行带 Tracy profiler 性能遥测的 viewer以pixi run rerun为例其底层命令是cargo run --package rerun-cli --no-default-features --features release_no_web_viewer --即编译并运行 rerun-clirerun二进制内含原生 Viewer。需要调试性能时可改用pixi run rerun-perf-debug它额外启用了rerun/perf_telemetry_tracy特性。格式化与代码检查任务作用pixi run rs-fmt格式化所有 Rust 文件修改代码后必须执行pixi run py-fmt格式化 Python 文件先 ruff check --fix再 ruff formatpixi run cpp-fmt格式化 C 文件clang-formatpixi run toml-fmt格式化 TOML 文件taplopixi run format/pixi run fmt一键执行上述全部格式化任务pixi run lint-rerun file校验各类自定义代码约定不传文件则检查全部pixi run rs-check运行 scripts/ci/rust_checks.py 做 Rust 检查pixi run fast-lint快速 lint 脚本注意rs-fmt的特殊性cargo fmt --all只能看到各 crate 的lib.rs/main.rs可达文件而 docs/snippets/all 下的.rs片段是被build.rs拷贝进 crate 的原文件永远不会被cargo fmt格式化因此rs-fmt会用 docs/snippets/rustfmt.tomlmax_width80对这些片段单独执行 rustfmt。环境自检进入仓库环境后建议先运行pixi run check-env执行 scripts/check_env.py确认环境配置正确。若出现 PyO3 配置错误运行pixi run ensure-pyo3-build-cfg修复见下文重要注意事项。测试与快照管理仓库明确建议使用cargo nextest而非cargo test输出更好、支持并行并约定始终使用--all-features除非有明确理由不使用使用--no-fail-fast以便单次运行收集全部失败。典型命令示例cargo clippy -p crate_name # 构建前先跑 Rust 检查 cargo nextest run --all-features --no-fail-fast -p re_view_spatialinsta 文本快照文本型快照使用insta随普通 Rust 测试运行。失败后可用cargo insta review审查需先cargo install cargo-insta。图像对比测试图像对比测试用于把渲染结果与仓库中检入的参考图对比实现方式是egui_kittest的Harness::snapshot配合TestContext见 crates/tests/re_test_context来 mock viewer。相关约定结果保存到tests/snapshots/失败会生成diff.png更新参考图设置环境变量UPDATE_SNAPSHOTS1重新运行从失败的 CI 更新参考图运行 scripts/update_snapshots_from_ci.sh一键批量更新所有 Rust 快照pixi run rs-update-snapshot-tests内部同时设置INSTA_UPDATEalways与UPDATE_SNAPSHOTS1。Python 侧还有对应的pixi run py-update-snapshot-testsinline-snapshot 与 syrupy 的.ambr快照以及汇总两者的pixi run update-snapshot-tests。另外仓库用git-lfs管理测试快照等大文件首次使用需安装并执行git lfs install。驱动运行中的 egui UIMCP 服务器仓库为 Agent 提供了两套 MCPModel Context Protocol服务器让 Agent 可以直接看和点击运行中的 UI而不是靠读代码猜界面rerun viewer-mcp通过 gRPC 驱动一个正在运行的 Rerun Viewer。具体用法见 docs/content/reference/viewer/mcp.md。egui-mcp驱动任意以EGUI_INSPECTION1启动的 egui 应用包括示例程序和 headless 的egui_kittestharness暴露attach、query_tree、click、type_text、screenshot、wait_for等工具。两者的配置都写在仓库根目录的 .mcp.json 中{ mcpServers: { rerun: { command: ./target/debug/re-viewer-mcp, args: [] }, egui: { command: egui-mcp } } }从源码看re_viewer_mcp 是一个架设在两套协议之间的桥接 crate见 lib.rsAgent 通过 MCPJSON-RPC over stdio与该服务器通信服务器再把每个工具调用转成一次对 ViewerViewerControlService的 gRPC 调用re_protos的viewer.protoViewer 在它自己的 SDK 连接端口上提供该服务。工具分两组query_tree、screenshot、click等 egui UI 工具直接复用egui_mcp的实现viewer_state、set_time、close_recordings等 Rerun 专属工具各自映射到同一服务的不同 RPC。该服务器有两个入口独立二进制re-viewer-mcp见 main.rs和rerun viewer-mcpCLI 子命令通常推荐后者。典型的 Agent 操作循环是以EGUI_INSPECTION1启动应用调用attach默认 host127.0.0.1、端口5719连接调用query_tree找到目标 widget用click/type_text操作 UI调用带save_path的screenshot截图并查看图片验证效果。几个实用要点egui-mcp要求应用持续绘制帧——macOS 上窗口化应用不能被遮挡因此尽量优先使用 headless harnessheadlessegui_kittestharness 可通过egui_inspection::attach_from_env(harness.ctx, label)接入。可直接运行的示例EGUI_INSPECTION1 cargo run -p re_agent_ui --example agent_app -- --headless。egui-mcp工具需要从kittest_inspector项目安装cargo install。如果要把 MCP 客户端如 Claude Code、Codex接入rerun viewer-mcp可参考 docs/content/reference/viewer/mcp.md 中的配置示例其核心形态是claude mcp add rerun -- rerun viewer-mcp默认情况下 Agent 用connect工具挑选 Viewer也可在启动时直接传--endpoint http://127.0.0.1:9876预先绑定某个 Viewer 的 gRPC 地址。代码生成系统这是 Rerun 多语言 SDK 的根基。核心原则是绝不要直接编辑生成文件——所有生成文件顶部都有 DO NOT EDIT 标记。类型定义流程re_type_definitions → pixi run codegen → 生成代码Rust/Python/C 文档docs/content/reference/types/类型定义位于 crates/build/re_type_definitions/rerun/encodings/*.def.rs底层类型Vec3D、Mat4x4 等components/*.def.rs组件类型Position3D、Color 等archetypes/*.def.rs原型Points3D、Image 等blueprint/*.def.rsBlueprint 系统的类型。codegen 的实现位于 crates/build/re_types_builder/其 README 明确说明它把re_type_definitions中Rust 子集形式编写的类型定义翻译成各语言代码运行pixi run codegen即可生成。修改定义后运行pixi run codegen底层命令为cargo run --package re_types_builder --重新生成代码。re_type_definitions中的定义文件本身不是可执行代码而是被re_types_builder解析的 DSL。以 points3d.def.rs 为例可以看到#[rerun::rerun_type]、#[rerun(required)]、#[rerun(recommended)]、#[rerun(optional)]等属性宏标注每个字段的角色。代码生成是三语言联动的改动一处re_type_definitionsRust、Python、C 的 SDK 会同时更新re_types_builder的codegen子模块分别包含 rust / python / cpp 三个后端。protobuf/gRPC 类型则由pixi run codegen-protos走独立的re_protos_builder流程。扩展模式_ext 文件要给生成类型补充自定义功能不要改生成文件而是创建_ext文件codegen 会自动把它们合并进生成类Rustfilename_ext.rscodegen 自动导入Pythonfilename_ext.py与生成类混合Cfilename_ext.cpp自动编译并包含部分内容可被 codegen 标记为拷入头文件。仓库中的实例很多例如 points3d_ext.rs 为Points3D增加了从.ply文件创建点云的from_ply构造器支持从x/y/z读取位置、从red/green/blue读取颜色等属性。架构概览Crate 组织仓库按分层目录组织 crate详见 ARCHITECTURE.mdcrates/ ├── build/ # 代码生成re_types_builder ├── store/ # 数据类型、存储、查询 ├── top/ # 面向用户的 SDK 与 CLI └── viewer/ # Viewer UI 与渲染依赖规则是只能依赖本层或更下层由 scripts/check_crate_layers.py 在 CI 中强制校验dev-dependency 豁免测试可以引用任意层。ARCHITECTURE.md中的 crate 依赖图与 crate 表格都由cargo metadata生成新增/删除/重命名 crate 后需运行pixi run crate-graph重新生成CI 里的pixi run crate-graph-check当前是关闭的graphviz 在 macOS 与 Linux 上布局略有差异所以最后谁重新生成了图谁就决定了检查是否通过——需要手动保证一致性。类型系统三层级类型系统由re_type_definitions生成分三个层级Encodingsrerun.encodings.*基础类型如 Vec3D、ColorComponentsrerun.components.*具名语义包装如 Position3D、RadiusArchetypesrerun.archetypes.*组件的集合如 Points3D、Image。每个 archetype 都会声明组件的三类角色必选required必须提供、推荐recommended有良好默认值、可选optional纯粹可选。以Points3D为例必须提供positions推荐colors与radii允许可选的labels此外从 points3d.def.rs 还能看到show_labels、point_shading、class_ids、keypoint_ids等更多可选组件。数据流SDK记录 archetype ↓ 编码为 Apache Arrow LogMsg编码后的数据 ↓ 传输gRPC / 文件 / 内存 re_chunk_store索引化的时序数据库 ↓ 查询 Viewer即时模式渲染数据以 Apache Arrow 列式格式编码、传输与存储详见 re_log_encoding 与 re_chunk_store即Arrow 原生原则。底层消息类型是LogMsg见 re_log_typesSDK 侧通过RecordingStream把 archetype 编码成 LogMsg 后送入各种 sink文件、gRPC、内存缓冲。Blueprint 系统Blueprint 是 Viewer 的配置层作为独立的 storere_entity_db存储使用 blueprint timeline定义视图布局、可见性、逐实体覆盖、视图属性与记录数据使用同一套类型系统基本路径层级为/viewport/、/view/{uuid}/、/container/{uuid}/。Visualizers 与即时模式每种视图类型Spatial3D、TimeSeries 等都注册有对应的 visualizer决定哪些实体/archetype 可以被可视化每帧执行查询数据 → 处理 → 生成渲染命令例如 Points3DVisualizer、LineStripsVisualizer、MeshVisualizer。整个 Viewer 采用即时模式immediate mode每帧从零开始查询 store 并重新渲染不做状态管理回调因此 blueprint 状态始终与屏幕所见一致。其代价是需要持续优化查询与渲染性能ARCHITECTURE.md 中提到未来计划做查询与渲染提交的缓存以便支撑数百万点级别的大数据集。代码约定与文档规范通用约定错误与日志消息中把错误放最前面、文件路径放最后例如Failed to import: {err}\nFile path: {path}便于复制粘贴时剥离长路径或敏感路径优先使用format!({x})而不是format!({}, x)日志调用同理不写毫无信息量的 trivial 注释行文风格em/en dash、句尾、大小写遵循 DESIGN.md使用带空格的长破折号—禁止word—word–只用于数字范围Markdown 文件一行一句话连续行会被渲染成同一段落但 diff 会更容易审查统一用…而非...可用pixi run lint-rerun file校验这些约定不传文件则检查全部。Python docstring 格式Python API 文档用MkDocs mkdocstrings不是 Sphinx因此 docstring 里严禁使用 reStructuredTextrST语法改用 Markdown交叉引用使用[ClassName][]mkdocstrings 语法而不是:class:ClassName /:func:/:meth:警告/提示使用 MkDocs admonitions!!! warning加缩进正文而不是.. warning::弃用说明使用deprecated装饰器mkdocstrings 自动渲染不要在 docstring 里再用.. deprecated::或**Deprecated:**重复代码块使用 Markdown fenced 块 而不是.. code-block::参数文档使用 numpy 风格分节Parameters、Returns加----------这是仓库现有代码已经采用的风格。Python 开发工作流Python 使用独立的、由 uv 管理的 .venv而不是 pixi 的 conda 环境pixi run py-build # 构建 rerun-sdk 到 .venv pixi run uvpy script.py # 通过 uv 运行 Python 脚本 pixi run uv run script.py # 显式 uv runuv包装脚本会清除CONDA_PREFIX确保与 pixi 环境的隔离。相关配套pixi run py-test先构建再跑 rerun_py/tests 下的 pytest、pixi run py-sync-examples安装示例专属依赖而不重建 SDK、pixi run py-sync-snippets安装片段依赖。构建系统细节见 rerun_py/README.md。文档系统与代码片段完整的文档架构见 docs/README.md。Rerun 的文档横跨多个站点主文档由 docs/content 构建以及 PythonMkDocs、CDoxygen、JSTypeDoc各自的 API 参考站。关键约定docs/content/reference/types 由pixi run codegen从re_type_definitions自动生成不要直接编辑docs/content/reference/cli.md 由pixi run man自动生成基于rerun-cli --all-features -- man输出不要直接编辑代码片段snippets位于 docs/snippets/all多数片段同时提供.py、.rs、.cpp三种语言实现配置在 docs/snippets/snippets.toml运行方式见 docs/snippets/README.mdRust/C 片段会被编译进一个 dispatcher 二进制按片段名执行compare_snippet_output.py会验证三种 SDK 用相同方式记录时产出完全一致的数据pixi run py-docs-serve本地预览 Python API 文档pixi run -e cpp cpp-docs构建 C 文档Doxygen需在cpp环境。重要注意事项速查PyO3 配置遇到 PyO3 config 错误先运行pixi run ensure-pyo3-build-cfggit-lfs测试快照等大文件需要 git-lfs用包管理器安装后执行git lfs install即时模式整个 Viewer 每帧从头渲染无状态管理回调Arrow 原生数据以 Apache Arrow 数组存储、传输、查询多语言联动修改re_type_definitions会同时影响 Rust、Python、C。开发者参考文档索引ARCHITECTURE.md详细架构文档BUILD.md完整构建说明CODE_STYLE.md代码风格指南CONTRIBUTING.md贡献指南DESIGN.mdUI 设计指南GUI、CLI、文档、日志消息docs/README.md文档系统说明rerun_py/README.mdPython SDK 构建说明综合来看AGENTS.md 是进入 Rerun 仓库开发的一站式操作手册从 pixi 任务体系、代码生成管线、测试快照工作流到 MCP 驱动的 UI 自动化、架构分层与文档规范均给出了可直接执行的命令与明确约定。对希望以 LLM/Agent 身份在仓库中高效、合规工作的开发者本文列出的命令与文件路径即是最短上手路径。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考