EmbodiChain

Project Agent Context Routing

EmbodiChain keeps agent-facing context in a structured topic registry:

• agent_context/ — agent-readable Markdown context, indexed by agent_context/MAP.yaml
• docs/source/ — human-facing Sphinx documentation
• .agents/skills/project-dev-context/ — the skill that routes project-context and codebase-navigation requests
• .claude/skills/ and .github/copilot/ — thin tool-specific adapters that point back to .agents/skills/

When a request says things like:

• reference project development docs
• reference project context
• where is X
• where do I change X
• 配置或默认值在哪里
• 入口或注册逻辑在哪里

the agent should:

1. Read agent_context/MAP.yaml first
2. Resolve the topic by id, aliases, then keywords
3. For context reads, load only the matched Markdown files under agent_context/
4. For navigation, verify matched facts against the current source_of_truth; if no topic matches, use rg --files and rg -n against the current tree
5. Report the owning entry point, resolution path, recommended change site, and focused validation surface when relevant
6. Avoid reading docs/source/ unless the user explicitly asks for the Sphinx documentation

Available topics: simulation-system, env-framework, manager-functor, ik-solvers, robot-system, sensor-system, sim-visualization, motion-planning, atomic-actions, rl-learning, configclass-pattern, randomization.

---

Package Name

IMPORTANT: The distribution and primary Python package name is embodichain (all lowercase, one word). The same wheel also bundles the official tasks under the embodichain_tasks import package.

• Repository folder: EmbodiChain (PascalCase)
• Distribution/core package: embodichain (lowercase)
• Bundled task import package: embodichain_tasks

Project Structure

EmbodiChain/
├── .agents/                      # Canonical in-repo agent skills
│   └── skills/
├── .claude/                      # Claude adapters for canonical skills
│   └── skills/
├── embodichain/                  # Main Python package
│   ├── data/                     # Assets, datasets, constants, enums
│   ├── data_pipeline/            # Datasets and online data streaming
│   ├── gen_sim/                  # Scene Engine and SimReady generation pipelines
│   ├── learning/                 # Learning systems
│   │   └── rl/                   # RL: PPO/GRPO/APG, buffers, collectors, policies
│   ├── lab/                      # Simulation lab
│   │   ├── visualization/        # Browser visualization protocol, runtime, and Viser backend
│   │   ├── gym/                  # OpenAI Gym-compatible environments
│   │   │   ├── envs/             # BaseEnv, EmbodiedEnv
│   │   │   │   ├── managers/     # Observation, event, reward, record, dataset managers
│   │   │   │   │   └── randomization/  # Physics, geometry, spatial, visual randomizers
│   │   │   │   ├── action_bank/  # Configurable action primitives
│   │   │   │   └── wrapper/      # Env wrappers (e.g. no_fail)
│   │   │   └── utils/            # Gym registration, misc helpers
│   │   ├── sim/                  # Simulation core
│   │   │   ├── atomic_actions/   # Typed planning and execution primitives
│   │   │   ├── objects/          # Robot, RigidObject, Articulation, Light, Gizmo, SoftObject
│   │   │   ├── sensors/          # Camera, StereoCamera, BaseSensor
│   │   │   ├── robots/           # Robot-specific configs and params (dexforce_w1, cobotmagic)
│   │   │   ├── planners/         # Motion planners (TOPPRA, motion generator)
│   │   │   ├── solvers/          # IK solvers (SRS, OPW, pink, pinocchio, pytorch)
│   │   │   ├── skills/           # Semantic scene and robot-skill binding contracts
│   │   │   └── workspace/        # Reachability analysis and runtime workspace queries
│   │   ├── devices/              # Real-device controllers
│   │   └── scripts/              # Environment, preview, and analysis entry points
│   ├── toolkits/                 # Standalone tools
│   │   ├── acd/                  # URDF convex-decomposition CLI
│   │   ├── graspkit/pg_grasp/    # Parallel-gripper grasp sampling
│   │   └── urdf_assembly/        # URDF builder utilities
│   └── utils/                    # Shared utilities
│       ├── configclass.py        # @configclass decorator
│       ├── logger.py             # Project logger
│       ├── math/                 # Tensor math helpers
│       └── warp/kinematics/      # GPU kinematics via Warp
├── embodichain_tasks/            # Official tasks/configs bundled in the main wheel as an import package
├── docs/                         # Sphinx documentation source + build
│   └── source/                   # .md doc pages (overview, quick_start, features, resources)
├── tests/                        # Test suite
├── .github/                      # CI workflows, issue/PR templates, Copilot adapters
├── pyproject.toml                # Distribution metadata and unified CLI entry point
├── setup.py                      # Package setup
└── VERSION                       # Package version file

---

Code Style

Formatting

• Formatter: black==26.3.1 — run before every commit.

  black .
  

• Use the /pre-commit-check skill before committing to catch all CI violations locally.

File Headers

Every source file begins with the Apache 2.0 copyright header:

# ----------------------------------------------------------------------------
# Copyright (c) 2021-2026 DexForce Technology Co., Ltd.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ----------------------------------------------------------------------------

Type Annotations

• Use full type hints on all public APIs.
• Use from __future__ import annotations at the top of every file.
• Use TYPE_CHECKING guards for circular-import-safe imports.
• Prefer A | B over Union[A, B].

Configuration Pattern (@configclass)

All configuration objects use the @configclass decorator (similar to Isaac Lab's pattern):

from embodichain.utils import configclass
from dataclasses import MISSING

@configclass
class MyManagerCfg:
    param_a: float = 1.0
    param_b: str = MISSING  # required — must be set by caller

Functor / Manager Pattern

Managers (observation, event, reward, randomization) use a Functor/FunctorCfg pattern with two styles:

• Function-style: a plain function with signature (env, env_ids, ...) -> None.
• Class-style: a class inheriting Functor, with __init__(cfg, env) and __call__(env, env_ids, ...).

Registered in a manager config via FunctorCfg(func=..., params={...}).

Use the /add-functor skill to scaffold new functors with the correct signature and module placement.

Docstrings

Use Google-style docstrings with Sphinx directives:

def my_function(env, env_ids, scale: float = 1.0) -> None:
    """Short one-line summary.

    Longer description if needed.

    .. attention::
        Note a non-obvious behavior here.

    .. tip::
        Helpful usage hint.

    Args:
        env: The environment instance.
        env_ids: Target environment IDs.
        scale: Scaling factor applied to the result.

    Returns:
        Description if not None.

    Raises:
        ValueError: If the entity type is unsupported.
    """

Module Exports

Define __all__ in every public module to declare the exported API:

__all__ = ["MyClass", "my_function"]

Documentation

• Docs are built with Sphinx using Markdown source files (docs/source/).
• Check public API coverage without modifying files:

  python docs/scripts/check_api_docs.py
  

• Use the /update-api-docs skill to generate or update documentation for missing public exports; the checker itself never writes documentation.
• Build locally:

  pip install -r docs/requirements.txt
  cd docs && make html
  # Preview at docs/build/html/index.html
  

• If you encounter locale errors: export LC_ALL=C.UTF-8; export LANG=C.UTF-8

---

Contributing Guide

Bug Reports

Use the Bug Report issue template (.github/ISSUE_TEMPLATE/bug.md). Title format: [Bug Report] Short description.

Include:

• Clear description of the bug
• Minimal reproduction steps and stack trace
• System info: commit hash, OS, GPU model, CUDA version, GPU driver version
• Confirm you checked for duplicate issues

Feature Requests / Proposals

Use the Proposal issue template (.github/ISSUE_TEMPLATE/proposal.md). Title format: [Proposal] Short description.

Include:

• Description of the feature and its core capabilities
• Motivation and problem it solves
• Any related existing issues

Pull Requests

1. Fork the repository and create a focused branch.
2. Keep PRs small — one logical change per PR.
3. Format the code with black==26.3.1 before submitting.
4. Update documentation for any public API changes.
5. Add tests that prove your fix or feature works.
6. Use the /pr skill to create PRs following the project's template and label conventions.

Adding a New Robot

Refer to docs/source/guides/add_robot.rst for a detailed guide. The basic structure requires:

• A config class (inheriting from RobotCfg)
• URDF configuration for the robot
• Control parts definition
• IK solver configuration
• Drive properties for joint physics

For complex robots with multiple variants (like dexforce_w1), use a package structure with types.py, params.py, utils.py, and cfg.py.

Also add robot documentation in docs/source/resources/robot/ (see existing examples: cobotmagic.md, dexforce_w1.md) and update docs/source/resources/robot/index.rst to include the new robot.

Adding a New Task Environment

Use the /add-task-env skill to scaffold a new task with the correct file structure, @register_env decorator, base class, and test stub.

Adding Functors

Use the /add-functor skill to scaffold observation, reward, event, action, dataset, or randomization functors with the correct signature, style, and module placement.

Writing Tests

Use the /add-test skill to scaffold tests with the correct file placement, style (pytest vs class), mock patterns, and project conventions.

---

Skills Quick Reference

Canonical skill instructions live under .agents/skills/<skill>/SKILL.md. Tool-specific adapter files should stay thin and point back to the canonical skill.

Skill	Command	Purpose
Add Atomic Action	/add-atomic-action	Scaffold a new simulation atomic action
Add Task Env	/add-task-env	Scaffold a new EmbodiedEnv task
Add Functor	/add-functor	Scaffold observation/reward/event/action/dataset/randomization functors
Add Test	/add-test	Scaffold tests following project conventions
Update API Docs	/update-api-docs	Document public exports reported by the read-only API checker
Pre-Commit Check	/pre-commit-check	Run all local CI checks before committing
Create PR	/pr	Create a PR following the project template
Benchmark	/benchmark	Write benchmark scripts for EmbodiChain modules