From 74c7bac1d55a7f4326c2ac920e89c7f5dfc75515 Mon Sep 17 00:00:00 2001 From: Kentaro Wu Date: Tue, 31 Mar 2026 14:07:51 +0800 Subject: [PATCH 1/3] docs: add Chinese (zh-CN) translations for README, AGENTS, and CLA MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add README.zh-CN.md, AGENTS.zh-CN.md, CLA.zh-CN.md - Add language switcher (English | 中文) to existing English docs Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 2 + AGENTS.zh-CN.md | 384 ++++++++++++++++++++++++++++++++++++++++++++++++ CLA.md | 2 + CLA.zh-CN.md | 26 ++++ README.md | 2 + README.zh-CN.md | 331 +++++++++++++++++++++++++++++++++++++++++ 6 files changed, 747 insertions(+) create mode 100644 AGENTS.zh-CN.md create mode 100644 CLA.zh-CN.md create mode 100644 README.zh-CN.md diff --git a/AGENTS.md b/AGENTS.md index 34c33d9a02..4641d5467d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,7 @@ # Dimensional AGENTS.md +**English** | [中文](AGENTS.zh-CN.md) + ## What is DimOS The agentic operating system for generalist robotics. `Modules` communicate via typed streams over LCM, ROS2, DDS, or other transports. `Blueprints` compose modules into runnable robot stacks. `Skills` give agents the ability to execute physical on-hardware function like `grab()`, `follow_object()`, or `jump()` diff --git a/AGENTS.zh-CN.md b/AGENTS.zh-CN.md new file mode 100644 index 0000000000..e7234a46ad --- /dev/null +++ b/AGENTS.zh-CN.md @@ -0,0 +1,384 @@ +# Dimensional AGENTS.md + +[English](AGENTS.md) | **中文** + +## 什么是 DimOS + +面向通用机器人的智能体操作系统。`Module`（模块）通过 LCM、ROS2、DDS 或其他传输协议上的类型化数据流进行通信。`Blueprint`（蓝图）将模块组合为可运行的机器人栈。`Skill`（技能）赋予智能体执行硬件物理功能的能力，例如 `grab()`、`follow_object()` 或 `jump()`。 + +--- + +## 快速开始 + +```bash +# 安装 +uv sync --all-extras --no-extra dds + +# 列出所有可运行的蓝图 +dimos list + +# --- Go2 四足机器人 --- +dimos --replay run unitree-go2 # 感知 + 建图，回放数据 +dimos --replay run unitree-go2 --daemon # 同上，后台运行 +dimos --replay run unitree-go2-agentic # + LLM 智能体 (GPT-4o) + 技能 + MCP 服务器 +dimos run unitree-go2-agentic --robot-ip 192.168.123.161 # 真实 Go2 硬件 + +# --- G1 人形机器人 --- +dimos --simulation run unitree-g1-agentic-sim # MuJoCo 仿真中的 G1 + 智能体 + 技能 +dimos run unitree-g1-agentic --robot-ip 192.168.123.161 # 真实 G1 硬件 + +# --- 检查与控制 --- +dimos status +dimos log # 最近 50 行，可读格式 +dimos log -f # 实时跟踪日志 +dimos agent-send "say hello" +dimos stop # 优雅关闭：SIGTERM → SIGKILL +dimos restart # 停止 + 使用相同参数重新运行 +``` + +### 蓝图快速参考 + +| 蓝图 | 机器人 | 硬件 | 智能体 | MCP 服务器 | 备注 | +|-----------|-------|----------|-------|------------|-------| +| `unitree-go2-agentic` | Go2 | 真实硬件 | 通过 McpClient | ✓ | McpServer 运行中 | +| `unitree-g1-agentic-sim` | G1 | 仿真 | GPT-4o（G1 提示词） | — | 完整智能体仿真，无需真实机器人 | +| `xarm-perception-agent` | xArm | 真实硬件 | GPT-4o | — | 操控 + 感知 + 智能体 | +| `xarm7-trajectory-sim` | xArm7 | 仿真 | — | — | 轨迹规划仿真 | +| `teleop-quest-xarm7` | xArm7 | 真实硬件 | — | — | Quest VR 遥操作 | +| `dual-xarm6-planner` | xArm6×2 | 真实硬件 | — | — | 双臂运动规划器 | + +运行 `dimos list` 查看完整列表。 + +--- + +## 可用工具（MCP） + +**MCP 仅在蓝图包含 `McpServer` 时有效。** 所有已发布的智能体蓝图都使用 `McpServer` + `McpClient`。例如：`unitree-go2-agentic`。 + +```bash +# 先启动支持 MCP 的蓝图： +dimos --replay run unitree-go2-agentic --daemon + +# 然后使用 MCP 工具： +dimos mcp list-tools # 以 JSON 格式列出所有可用技能 +dimos mcp call move --arg x=0.5 --arg duration=2.0 # 通过 key=value 参数调用 +dimos mcp call move --json-args '{"x": 0.5, "duration": 2.0}' # 通过 JSON 调用 +dimos mcp status # PID、模块列表、技能列表 +dimos mcp modules # 模块 → 技能映射 + +# 向正在运行的智能体发送消息（无 McpServer 也可使用）： +dimos agent-send "walk forward 2 meters then wave" +``` + +MCP 服务器运行在 `http://localhost:9990/mcp`（`GlobalConfig.mcp_port`）。 + +### 在蓝图中添加 McpServer + +同时使用 `McpServer.blueprint()` 和 `McpClient.blueprint()`。 + +```python +from dimos.agents.mcp.mcp_client import McpClient +from dimos.agents.mcp.mcp_server import McpServer + +unitree_go2_agentic = autoconnect( + unitree_go2_spatial, # 机器人栈 + McpServer.blueprint(), # HTTP MCP 服务器 -- 在端口 9990 暴露所有 @skill 方法 + McpClient.blueprint(), # LLM 智能体 -- 从 McpServer 获取工具 + _common_agentic, # 技能容器 +) +``` + +参考：`dimos/robot/unitree/go2/blueprints/agentic/unitree_go2_agentic.py` + +--- + +## 仓库结构 + +``` +dimos/ +├── core/ # 模块系统、蓝图、工作进程、传输 +│ ├── module.py # Module 基类、In/Out 数据流、@rpc、@skill +│ ├── blueprints.py # 蓝图组合（autoconnect） +│ ├── global_config.py # GlobalConfig（环境变量、CLI 标志、.env） +│ └── run_registry.py # 每次运行的跟踪 + 日志路径 +├── robot/ +│ ├── cli/dimos.py # CLI 入口点（typer） +│ ├── all_blueprints.py # 自动生成的蓝图注册表（请勿手动编辑） +│ ├── unitree/ # Unitree 机器人实现（Go2、G1、B1） +│ │ ├── unitree_skill_container.py # Go2 @skill 方法 +│ │ ├── go2/ # Go2 蓝图与连接 +│ │ └── g1/ # G1 蓝图、连接、仿真、技能 +│ └── drone/ # 无人机实现（MAVLink + DJI） +│ ├── connection_module.py # MAVLink 连接 +│ ├── camera_module.py # DJI 视频流 +│ ├── drone_tracking_module.py # 视觉目标跟踪 +│ └── drone_visual_servoing_controller.py # 视觉伺服 +├── agents/ +│ ├── agent.py # Agent 模块（基于 LangGraph） +│ ├── system_prompt.py # 默认 Go2 系统提示词 +│ ├── annotation.py # @skill 装饰器 +│ ├── mcp/ # McpServer、McpClient、McpAdapter +│ └── skills/ # NavigationSkillContainer、SpeakSkill 等 +├── navigation/ # 路径规划、前沿探索 +├── perception/ # 目标检测、跟踪、记忆 +├── visualization/rerun/ # Rerun 桥接 +├── msgs/ # 消息类型（geometry_msgs、sensor_msgs、nav_msgs） +└── utils/ # 日志、数据加载、CLI 工具 +docs/ +├── usage/modules.md # ← 模块系统深入解析 +├── usage/blueprints.md # 蓝图组合指南 +├── usage/configuration.md # GlobalConfig + Configurable 模式 +├── development/testing.md # 快速/慢速测试、pytest 使用 +├── development/dimos_run.md # CLI 使用、添加蓝图 +└── agents/ # 智能体系统文档 +``` + +--- + +## 架构 + +### 模块 + +自治子系统。通过 `In[T]`/`Out[T]` 类型化数据流通信。在 forkserver 工作进程中运行。 + +```python +from dimos.core.module import Module +from dimos.core.stream import In, Out +from dimos.core.core import rpc +from dimos.msgs.sensor_msgs import Image + +class MyModule(Module): + color_image: In[Image] + processed: Out[Image] + + @rpc + def start(self) -> None: + super().start() + self.color_image.subscribe(self._process) + + def _process(self, img: Image) -> None: + self.processed.publish(do_something(img)) +``` + +### 蓝图 + +使用 `autoconnect()` 组合模块。数据流通过 `(名称, 类型)` 匹配自动连接。 + +```python +from dimos.core.blueprints import autoconnect + +my_blueprint = autoconnect(module_a(), module_b(), module_c()) +``` + +直接从 Python 运行蓝图： + +```python +# build() 将所有模块部署到 forkserver 工作进程并连接数据流 +# loop() 阻塞主线程，直到停止（Ctrl-C 或 SIGTERM） +autoconnect(module_a(), module_b(), module_c()).build().loop() +``` + +将蓝图暴露为模块级变量，以便 `dimos run` 发现。通过运行 `pytest dimos/robot/test_all_blueprints_generation.py` 添加到注册表。 + +### GlobalConfig + +单例配置。值按优先级层叠：默认值 → `.env` → 环境变量 → 蓝图 → CLI 标志。环境变量前缀为 `DIMOS_`。关键字段：`robot_ip`、`simulation`、`replay`、`viewer`、`n_workers`、`mcp_port`。 + +### 传输 + +- **LCMTransport**：默认。组播 UDP。 +- **SHMTransport/pSHMTransport**：共享内存 -- 用于图像和点云。 +- **pLCMTransport**：序列化 LCM -- 用于复杂的 Python 对象。 +- **ROSTransport**：ROS 话题桥接 -- 与 ROS 节点互操作（`dimos/core/transport.py`）。 +- **DDSTransport**：DDS 发布/订阅 -- 在 `DDS_AVAILABLE` 时可用；使用 `uv sync --extra dds` 安装（`dimos/protocol/pubsub/impl/ddspubsub.py`）。 + +--- + +## CLI 参考 + +### 全局标志 + +每个 `GlobalConfig` 字段都是 CLI 标志：`--robot-ip`、`--simulation/--no-simulation`、`--replay/--no-replay`、`--viewer {rerun|rerun-web|foxglove|none}`、`--mcp-port`、`--n-workers` 等。标志会覆盖 `.env` 和环境变量。 + +### 核心命令 + +| 命令 | 描述 | +|---------|-------------| +| `dimos run [--daemon]` | 启动蓝图 | +| `dimos status` | 显示运行实例（运行 ID、PID、蓝图、运行时间、日志路径） | +| `dimos stop [--force]` | SIGTERM → 5 秒后 SIGKILL；`--force` = 立即 SIGKILL | +| `dimos restart [--force]` | 停止 + 使用原始参数重新执行 | +| `dimos list` | 列出所有非演示蓝图 | +| `dimos show-config` | 打印已解析的 GlobalConfig 值 | +| `dimos log [-f] [-n N] [--json] [-r ]` | 查看每次运行的日志 | +| `dimos mcp list-tools / call / status / modules` | MCP 工具（需要蓝图中包含 McpServer） | +| `dimos agent-send ""` | 通过 LCM 向运行中的智能体发送文本 | +| `dimos lcmspy / agentspy / humancli / top` | 调试/诊断工具 | +| `dimos topic echo / send ` | LCM 话题发布/订阅 | +| `dimos rerun-bridge` | 独立启动 Rerun 可视化 | + +日志文件：`~/.local/state/dimos/logs//main.jsonl` +运行注册表：`~/.local/state/dimos/runs/.json` + +--- + +## 智能体系统 + +### `@skill` 装饰器 + +`dimos/agents/annotation.py`。设置 `__rpc__ = True` 和 `__skill__ = True`。 + +- `@rpc` 单独使用：可通过 RPC 调用，但不暴露给 LLM +- `@skill`：隐含 `@rpc` 并将方法作为工具暴露给 LLM。**不要同时使用两者。** + +#### Schema 生成规则 + +| 规则 | 违反后果 | +|------|------------------------------| +| **文档字符串（docstring）必须提供** | 启动时抛出 `ValueError` -- 模块注册失败，所有技能消失 | +| **每个参数都必须有类型注解** | 缺少注解 → schema 中无 `"type"` -- LLM 没有类型信息 | +| **返回 `str`** | 返回 `None` → 智能体收到"已启动，稍后更新" | +| **完整文档字符串逐字写入 `description`** | 保持 `Args:` 块简洁 -- 它会出现在每次工具调用的提示词中 | + +支持的参数类型：`str`、`int`、`float`、`bool`、`list[str]`、`list[float]`。避免使用复杂嵌套类型。 + +#### 最小正确技能示例 + +```python +from dimos.agents.annotation import skill +from dimos.core.core import rpc +from dimos.core.module import Module + +class MySkillContainer(Module): + @rpc + def start(self) -> None: + super().start() + + @rpc + def stop(self) -> None: + super().stop() + + @skill + def move(self, x: float, duration: float = 2.0) -> str: + """Move the robot forward or backward. + + Args: + x: Forward velocity in m/s. Positive = forward, negative = backward. + duration: How long to move in seconds. + """ + return f"Moving at {x} m/s for {duration}s" + +my_skill_container = MySkillContainer.blueprint + +### 系统提示词 + +| 机器人 | 文件 | 变量 | +|-------|------|----------| +| Go2（默认） | `dimos/agents/system_prompt.py` | `SYSTEM_PROMPT` | +| G1 人形机器人 | `dimos/robot/unitree/g1/system_prompt.py` | `G1_SYSTEM_PROMPT` | + +传入机器人特定提示词：`McpClient.blueprint(system_prompt=G1_SYSTEM_PROMPT)`。默认提示词针对 Go2；在 G1 上使用会导致技能幻觉。 + +### RPC 连接 + +要调用另一个模块的方法，声明一个 `Spec` Protocol 并用它注解属性。蓝图在构建时注入匹配的模块 -- 完全类型化、无字符串、在构建时（而非运行时）失败。 + +```python +# my_module_spec.py +from typing import Protocol +from dimos.spec.utils import Spec + +class NavigatorSpec(Spec, Protocol): + def set_goal(self, goal: PoseStamped) -> bool: ... + def cancel_goal(self) -> bool: ... + +# my_skill_container.py +class MySkillContainer(Module): + _navigator: NavigatorSpec # 蓝图在构建时注入 + + @skill + def go_to(self, x: float, y: float) -> str: + """Navigate to a position.""" + self._navigator.set_goal(make_pose(x, y)) + return "Navigating" +``` + +如果多个模块匹配该 spec，使用 `.remappings()` 解决。源码：`dimos/spec/utils.py`、`dimos/core/blueprints.py`。 + +### 添加新技能 + +1. 选择合适的容器（机器人专用的或 `dimos/agents/skills/`）。 +2. `@skill` + 必须提供文档字符串 + 所有参数的类型注解。 +3. 如果需要其他模块的 RPC，使用 Spec 模式。 +4. 返回描述性的 `str`。 +5. 更新系统提示词 -- 添加到 `# AVAILABLE SKILLS` 部分。 +6. 暴露为 `my_container = MySkillContainer.blueprint` 并包含在智能体蓝图中。 + +--- + +## 测试 + +```bash +# 快速测试（默认） +uv run pytest + +# 包含慢速测试（CI） +./bin/pytest-slow + +# 单个文件 +uv run pytest dimos/core/test_blueprints.py -v + +# Mypy +uv run mypy dimos/ +``` + +`uv run pytest` 排除 `slow`、`tool` 和 `mujoco` 标记。CI（`./bin/pytest-slow`）包含 slow，排除 tool 和 mujoco。参见 `docs/development/testing.md`。 + +--- + +## Pre-commit 与代码风格 + +Pre-commit 在 `git commit` 时运行。包括 ruff 格式化/检查、许可证头、LFS 检查。 + +**提交前务必激活虚拟环境：** `source .venv/bin/activate` + +代码风格规则： +- 导入语句放在文件顶部。除非存在循环依赖，否则不使用内联导入。 +- HTTP 请求使用 `requests`（而非 `urllib`）。JSON 值使用 `Any`（而非 `object`）。 +- 手动测试脚本以 `demo_` 为前缀，以排除在 pytest 收集之外。 +- 不要硬编码端口/URL -- 使用 `GlobalConfig` 常量。 +- 需要类型注解。Mypy 严格模式。 + +--- + +## `all_blueprints.py` 为自动生成 + +`dimos/robot/all_blueprints.py` 由 `test_all_blueprints_generation.py` 生成。添加或重命名蓝图后： + +```bash +pytest dimos/robot/test_all_blueprints_generation.py +``` + +CI 会断言文件是最新的 -- 如果过时，CI 将失败。 + +--- + +## Git 工作流 + +- 分支前缀：`feat/`、`fix/`、`refactor/`、`docs/`、`test/`、`chore/`、`perf/` +- **PR 目标为 `dev`** -- 不要直接推送到 `main` 或 `dev` +- **不要强制推送**，除非在有冲突的 rebase 之后 +- **减少推送次数** -- 每次推送都会触发 CI（自托管运行器上约 1 小时）。在本地批量提交，一次推送。 + +--- + +## 延伸阅读 + +- 模块系统：`docs/usage/modules.md` +- 蓝图：`docs/usage/blueprints.md` +- 可视化：`docs/usage/visualization.md` +- 配置：`docs/usage/configuration.md` +- 测试：`docs/development/testing.md` +- CLI / dimos run：`docs/development/dimos_run.md` +- LFS 数据：`docs/development/large_file_management.md` +- 智能体系统：`docs/agents/` diff --git a/CLA.md b/CLA.md index 507849309c..399220dd15 100644 --- a/CLA.md +++ b/CLA.md @@ -1,3 +1,5 @@ +**English** | [中文](CLA.zh-CN.md) + ## Dimensional OS Individual Contributor License Agreement In order to clarify the intellectual property license granted with Contributions from any person or entity, **Dimensional Inc.** ("**Dimensional**") must have a Contributor License Agreement ("CLA") on file that has been signed by each Contributor, indicating agreement to the license terms below. This license is for your protection as a Contributor as well as the protection of Dimensional; it does not change your rights to use your own Contributions for any other purpose. diff --git a/CLA.zh-CN.md b/CLA.zh-CN.md new file mode 100644 index 0000000000..152cbf21c9 --- /dev/null +++ b/CLA.zh-CN.md @@ -0,0 +1,26 @@ +[English](CLA.md) | **中文** + +## Dimensional OS 个人贡献者许可协议 + +为明确任何个人或实体所提交贡献的知识产权许可授权，**Dimensional Inc.**（以下简称 "**Dimensional**"）须持有经每位贡献者签署的贡献者许可协议（"CLA"），以表明其同意以下许可条款。本许可既保护作为贡献者的您，也保护 Dimensional；它不会改变您将自己的贡献用于其他任何目的的权利。 + +您接受并同意以下条款和条件，适用于您当前和未来向 Dimensional 提交的贡献。除本协议中向 Dimensional 及 Dimensional 分发软件的接收方授予的许可外，您保留对您的贡献的所有权利、所有权和利益。 + +1. 定义。 + "您"（或"您的"）是指与 Dimensional 签订本协议的版权所有者或经版权所有者授权的法律实体。对于法律实体，进行贡献的实体以及控制该实体、被该实体控制或与该实体处于共同控制之下的所有其他实体，均被视为单一贡献者。就本定义而言，"控制"是指 (i) 直接或间接地通过合同或其他方式引导或管理该实体的权力，或 (ii) 拥有百分之五十 (50%) 或以上的已发行股份，或 (iii) 对该实体的受益所有权。 + + "贡献"是指您有意向 Dimensional 提交的任何原创作品，包括对现有作品的任何修改或补充，用于纳入 Dimensional 拥有或管理的任何产品（以下简称"作品"）或为其编写文档。就本定义而言，"提交"是指发送给 Dimensional 或其代表的任何形式的电子、口头或书面通信，包括但不限于在由 Dimensional 管理或代表 Dimensional 管理的电子邮件列表、源代码管理系统和问题追踪系统上的通信，以讨论和改进作品为目的，但不包括被您明确标注或以书面形式指定为"非贡献"的通信。 + +2. 版权许可授权。根据本协议的条款和条件，您特此向 Dimensional 及 Dimensional 分发软件的接收方授予永久的、全球性的、非排他性的、免费的、免版税的、不可撤销的版权许可，以复制、准备衍生作品、公开展示、公开表演、再许可和分发您的贡献及其衍生作品。 + +3. 专利许可授权。根据本协议的条款和条件，您特此向 Dimensional 及 Dimensional 分发软件的接收方授予永久的、全球性的、非排他性的、免费的、免版税的、不可撤销的（本条另有规定的除外）专利许可，以制造、委托制造、使用、许诺销售、销售、进口和以其他方式转让作品，该许可仅适用于您可许可的、因您的贡献本身或您的贡献与所提交作品的组合而必然被侵犯的专利权利要求。如果任何实体对您或任何其他实体提起专利诉讼（包括诉讼中的交叉请求或反诉），指控您的贡献或您所贡献的作品构成直接或间接的专利侵权，则根据本协议授予该实体的与该贡献或作品相关的任何专利许可自该诉讼提起之日起终止。 + +4. 您声明您在法律上有权授予上述许可。如果您的雇主对您创建的知识产权（包括您的贡献）拥有权利，您声明您已获得代表该雇主进行贡献的许可，或您的雇主已放弃对您向 Dimensional 贡献的此类权利，或您的雇主已与 Dimensional 签署了单独的企业 CLA。 + +5. 您声明您的每项贡献均为您的原创作品（代表他人提交的情况请参见第 7 条）。您声明您提交的贡献包含您个人知晓的、与您贡献的任何部分相关的任何第三方许可或其他限制（包括但不限于相关专利和商标）的完整详情。 + +6. 除非您愿意，否则不要求您为您的贡献提供支持。您可以免费提供支持、收费提供支持或完全不提供支持。除非适用法律要求或经书面同意，否则您的贡献按"现状"提供，不附带任何明示或暗示的保证或条件，包括但不限于关于所有权、不侵权、适销性或特定用途适用性的任何保证或条件。 + +7. 如果您希望提交非您原创的作品，您可以在任何贡献之外单独向 Dimensional 提交，注明其来源的完整详情以及您个人知晓的任何许可或其他限制（包括但不限于相关专利、商标和许可协议），并明确标注该作品为"代表第三方提交：[在此注明名称]"。 + +8. 您同意在您获知任何可能使上述声明在任何方面不准确的事实或情况时通知 Dimensional。 diff --git a/README.md b/README.md index 62f9f464f0..c09a2c6112 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,8 @@ +**English** | [中文](README.zh-CN.md) + [Hardware](#hardware) • [Installation](#installation) • [Agent CLI & MCP](#agent-cli-and-mcp) • diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000000..cc6d3b3fa5 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,331 @@ +
+ +banner_bordered_trimmed + +

物理空间的智能体操作系统

+ +[![Discord](https://img.shields.io/discord/1341146487186391173?style=flat-square&logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/dimos) +[![Stars](https://img.shields.io/github/stars/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/stargazers) +[![Forks](https://img.shields.io/github/forks/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/fork) +[![Contributors](https://img.shields.io/github/contributors/dimensionalOS/dimos?style=flat-square)](https://github.com/dimensionalOS/dimos/graphs/contributors) +![Nix](https://img.shields.io/badge/Nix-flakes-5277C3?style=flat-square&logo=NixOS&logoColor=white) +![NixOS](https://img.shields.io/badge/NixOS-supported-5277C3?style=flat-square&logo=NixOS&logoColor=white) +![CUDA](https://img.shields.io/badge/CUDA-supported-76B900?style=flat-square&logo=nvidia&logoColor=white) +[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/) + +dimensionalOS%2Fdimos | Trendshift + + + +[English](README.md) | **中文** + +[硬件](#硬件) • +[安装](#安装) • +[Agent CLI 与 MCP](#agent-cli-与-mcp) • +[蓝图](#蓝图) • +[开发](#开发) + +⚠️ **预发布测试版** ⚠️ + + + +
+ +# 简介 + +Dimensional 是面向通用机器人的现代操作系统。我们正在建立下一代 SDK 标准，并与主流机器人制造商深度集成。 + +只需简单安装，无需 ROS，即可完全使用 Python 构建运行在任何人形机器人、四足机器人或无人机上的物理应用。 + +Dimensional 天生支持智能体 -- 使用自然语言为您的机器人"氛围编程"（vibecode），构建（本地和托管的）多智能体系统，与您的硬件无缝协作。智能体作为原生模块运行 -- 可订阅任何嵌入式数据流，从感知（激光雷达、相机）和空间记忆到控制回路和电机驱动程序。 + + + + + + + + + + + + + + + + + +
+ 导航 + + 感知 +
+

导航与建图

+ SLAM、动态避障、路径规划和自主探索 -- 同时支持 DimOS 原生和 ROS
观看视频 + 		+

感知

+ 检测器、3D 投影、视觉语言模型（VLM）、音频处理 +
+ 智能体 + + 空间记忆 +
+

智能体控制、MCP

+ "嘿，机器人，去找厨房"
观看视频 + 		+

空间记忆

+ 时空 RAG、动态记忆、目标定位与持久性
观看视频 +
+ + +# 硬件 + + + + + + + + + + + + + + + + + +
+

四足机器人

+ + 		+

人形机器人

+ + 		+

机械臂

+ + 		+

无人机

+ + 		+

其他

+ +
+ 🟩 Unitree Go2 pro/air
+ 🟥 Unitree B1
+ 		+ 🟨 Unitree G1
+ 		+ 🟨 Xarm
+ 🟨 AgileX Piper
+ 		+ 🟧 MAVLink
+ 🟧 DJI Mavic
+ 		+ 🟥 力/扭矩传感器
+
+
+
+🟩 稳定 🟨 测试版 🟧 预览版 🟥 实验性 + +
+ +> [!IMPORTANT] +> 🤖 将您喜欢的 Agent（OpenClaw、Claude Code 等）指向 [AGENTS.md](AGENTS.md) 和我们的 [CLI 与 MCP](#agent-cli-与-mcp) 接口，即可开始构建强大的 Dimensional 应用。 + +# 安装 + +## 交互式安装 + +```sh +curl -fsSL https://raw.githubusercontent.com/dimensionalOS/dimos/main/scripts/install.sh | bash +``` + +> 有关非交互式和高级选项，请参阅 [`scripts/install.sh --help`](scripts/install.sh)。 + +## 手动系统安装 + +如需设置系统依赖项，请参阅以下指南之一： + +- 🟩 [Ubuntu 22.04 / 24.04](docs/installation/ubuntu.md) +- 🟩 [NixOS / 通用 Linux](docs/installation/nix.md) +- 🟧 [macOS](docs/installation/osx.md) + +> 完整的系统要求、测试配置和依赖层级：[docs/requirements.md](docs/requirements.md) + +## Python 安装 + +### 快速开始 + +```bash +uv venv --python "3.12" +source .venv/bin/activate +uv pip install 'dimos[base,unitree]' + +# 回放已录制的四足机器人会话（无需硬件） +# 注意：首次运行时会显示黑色的 rerun 窗口，同时从 LFS 下载约 75 MB 数据 +dimos --replay run unitree-go2 +``` + +```bash +# 安装仿真支持 +uv pip install 'dimos[base,unitree,sim]' + +# 在 MuJoCo 仿真中运行四足机器人 +dimos --simulation run unitree-go2 + +# 在仿真中运行人形机器人 +dimos --simulation run unitree-g1-sim +``` + +```bash +# 控制真实机器人（通过 WebRTC 连接 Unitree 四足机器人） +export ROBOT_IP= +dimos run unitree-go2 +``` + +# 精选运行文件 + +| 运行命令 | 功能说明 | +|-------------|-------------| +| `dimos --replay run unitree-go2` | 四足机器人导航回放 -- SLAM、代价地图、A* 路径规划 | +| `dimos --replay --replay-dir unitree_go2_office_walk2 run unitree-go2-temporal-memory` | 四足机器人时序记忆回放 | +| `dimos --simulation run unitree-go2-agentic` | 四足机器人智能体 + 仿真中的 MCP 服务器 | +| `dimos --simulation run unitree-g1` | MuJoCo 仿真中的人形机器人 | +| `dimos --replay run drone-basic` | 无人机视频 + 遥测回放 | +| `dimos --replay run drone-agentic` | 无人机 + LLM 智能体与飞行技能（回放） | +| `dimos run demo-camera` | 摄像头演示 -- 无需硬件 | +| `dimos run keyboard-teleop-xarm7` | 使用模拟 xArm7 进行键盘遥操作（需要 `dimos[manipulation]` 扩展） | +| `dimos --simulation run unitree-go2-agentic-ollama` | 使用本地 LLM 的四足机器人智能体（需要 [Ollama](https://ollama.com) + `ollama serve`） | + +> 完整蓝图文档：[docs/usage/blueprints.md](docs/usage/blueprints.md) + +# Agent CLI 与 MCP + +`dimos` CLI 管理完整的生命周期 -- 运行蓝图、检查状态、与智能体交互以及通过 MCP 调用技能。 + +```bash +dimos run unitree-go2-agentic --daemon # 后台启动 +dimos status # 检查运行状态 +dimos log -f # 实时跟踪日志 +dimos agent-send "explore the room" # 向智能体发送命令 +dimos mcp list-tools # 列出可用的 MCP 技能 +dimos mcp call relative_move --arg forward=0.5 # 直接调用技能 +dimos stop # 关闭 +``` + +> 完整 CLI 参考：[docs/usage/cli.md](docs/usage/cli.md) + + +# 使用方法 + +## 将 DimOS 作为库使用 + +以下是一个简单的机器人连接模块示例，它向机器人发送连续的 `cmd_vel` 数据流，并将 `color_image` 接收到一个简单的 `Listener` 模块中。DimOS 模块是机器人上的子系统，使用标准化消息与其他模块通信。 + +```py +import threading, time, numpy as np +from dimos.core.blueprints import autoconnect +from dimos.core.core import rpc +from dimos.core.module import Module +from dimos.core.stream import In, Out +from dimos.msgs.geometry_msgs import Twist +from dimos.msgs.sensor_msgs import Image, ImageFormat + +class RobotConnection(Module): + cmd_vel: In[Twist] + color_image: Out[Image] + + @rpc + def start(self): + threading.Thread(target=self._image_loop, daemon=True).start() + + def _image_loop(self): + while True: + img = Image.from_numpy( + np.zeros((120, 160, 3), np.uint8), + format=ImageFormat.RGB, + frame_id="camera_optical", + ) + self.color_image.publish(img) + time.sleep(0.2) + +class Listener(Module): + color_image: In[Image] + + @rpc + def start(self): + self.color_image.subscribe(lambda img: print(f"image {img.width}x{img.height}")) + +if __name__ == "__main__": + autoconnect( + RobotConnection.blueprint(), + Listener.blueprint(), + ).build().loop() +``` + +## 蓝图 + +蓝图是关于如何构建和连接模块的指令。我们使用 `autoconnect(...)` 组合蓝图，它通过 `(名称, 类型)` 自动连接数据流并返回一个 `Blueprint`。 + +蓝图可以被组合、重映射，并且在 `autoconnect()` 因变量名或 `In[]` 和 `Out[]` 消息类型冲突而失败时，可以覆盖传输方式。 + +以下蓝图示例将机器人的图像流连接到基于 MCP 的 LLM 智能体，用于推理和动作执行。 +```py +from dimos.core.blueprints import autoconnect +from dimos.core.transport import LCMTransport +from dimos.msgs.sensor_msgs import Image +from dimos.robot.unitree.go2.connection import go2_connection +from dimos.agents.mcp.mcp_client import McpClient +from dimos.agents.mcp.mcp_server import McpServer + +blueprint = autoconnect( + go2_connection(), + McpServer.blueprint(), + McpClient.blueprint(), +).transports({("color_image", Image): LCMTransport("/color_image", Image)}) + +# 运行蓝图 +if __name__ == "__main__": + blueprint.build().loop() +``` + +## 库 API + +- [模块](docs/usage/modules.md) +- [LCM](docs/usage/lcm.md) +- [蓝图](docs/usage/blueprints.md) +- [传输](docs/usage/transports/index.md) -- LCM、SHM、DDS、ROS 2 +- [数据流](docs/usage/data_streams/README.md) +- [配置](docs/usage/configuration.md) +- [可视化](docs/usage/visualization.md) + +## 演示 + +DimOS 演示 + +# 开发 + +## 在 DimOS 上开发 + +```sh +export GIT_LFS_SKIP_SMUDGE=1 +git clone -b dev https://github.com/dimensionalOS/dimos.git +cd dimos + +uv sync --all-extras --no-extra dds + +# 运行快速测试套件 +uv run pytest dimos +``` + + +## 多语言支持 + +Python 是我们的胶水语言和原型开发语言，但我们通过 LCM 互操作支持多种语言。 + +查看我们的语言互操作示例： +- [C++](examples/language-interop/cpp/) +- [Lua](examples/language-interop/lua/) +- [TypeScript](examples/language-interop/ts/) From 57783f58cd9e44e9b823f9510b8d0b0a6137690b Mon Sep 17 00:00:00 2001 From: Kentaro Wu Date: Tue, 31 Mar 2026 14:38:57 +0800 Subject: [PATCH 2/3] docs: move language switcher below pre-release beta for visibility Co-Authored-By: Claude Opus 4.6 --- README.md | 4 ++-- README.zh-CN.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index c09a2c6112..420bc4f358 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,6 @@ -**English** | [中文](README.zh-CN.md) - [Hardware](#hardware) • [Installation](#installation) • [Agent CLI & MCP](#agent-cli-and-mcp) • @@ -27,6 +25,8 @@ ⚠️ **Pre-Release Beta** ⚠️ +**English** | [中文](README.zh-CN.md) + diff --git a/README.zh-CN.md b/README.zh-CN.md index cc6d3b3fa5..7a529f221e 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -17,8 +17,6 @@ -[English](README.md) | **中文** - [硬件](#硬件) • [安装](#安装) • [Agent CLI 与 MCP](#agent-cli-与-mcp) • @@ -27,6 +25,8 @@ ⚠️ **预发布测试版** ⚠️ +[English](README.md) | **中文** + From c93d96dc84d07a5d64e9a338f57e23de4e091041 Mon Sep 17 00:00:00 2001 From: Jetson Wu <64779050+jetsonearth@users.noreply.github.com> Date: Tue, 31 Mar 2026 14:57:01 +0800 Subject: [PATCH 3/3] Update AGENTS.zh-CN.md Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- AGENTS.zh-CN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.zh-CN.md b/AGENTS.zh-CN.md index e7234a46ad..ad27643a01 100644 --- a/AGENTS.zh-CN.md +++ b/AGENTS.zh-CN.md @@ -277,7 +277,7 @@ my_skill_container = MySkillContainer.blueprint | Go2（默认） | `dimos/agents/system_prompt.py` | `SYSTEM_PROMPT` | | G1 人形机器人 | `dimos/robot/unitree/g1/system_prompt.py` | `G1_SYSTEM_PROMPT` | -传入机器人特定提示词：`McpClient.blueprint(system_prompt=G1_SYSTEM_PROMPT)`。默认提示词针对 Go2；在 G1 上使用会导致技能幻觉。 +传入机器人特定提示词：`agent(system_prompt=G1_SYSTEM_PROMPT)`。默认提示词针对 Go2；在 G1 上使用会导致技能幻觉。 ### RPC 连接