# CollabMind

**Repository Path**: AGIROS_Team/collabmind

## Basic Information

- **Project Name**: CollabMind
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-09-29
- **Last Updated**: 2026-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CollabMind: 一个基于多模态大模型的协作式具身智能框架

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

**CollabMind** 是一个先进的开源框架，旨在通过多模态大型语言模型（MLLMs）理解、推理和识别复杂的人类协作任务，特别是在物理装配场景中。它通过分析视频帧、结合任务规划和外部知识，实现对人类行为的深层语义理解。

## 核心特性

* **🤖 模块化与可扩展架构**: 项目被精心设计为一系列高内聚、低耦合的模块，包括任务规划器、API环境、AI功能模块和数据加载器，易于扩展和维护。
* **🌐 统一的多供应商API (`ApiEnv`)**: 提供一个标准化的接口，用于与不同的多模态LLM供应商（如 QDD, ModelScope）进行交互，支持文本、图像、PDF和视频帧等多种输入。
* **🧠 先进的任务规划器 (`Planner`)**: 内置多种任务规划策略，包括：
  * **`ObjectPlanner`**: 基于对象/资源可用性的有向无环图（DAG）规划器。
  * **`LogicPlanner`**: 使用形式化逻辑表达式定义复杂任务依赖的规划器。
  * **`LinearPlanner`**: 用于任务间无依赖场景的线性规划器。
* **🎥 强大的视频与姿态分析 (`ProcessVideo`)**: 提供一套完整的工具库，用于从视频中提取关键帧（基于运动流或均匀采样）、分析手部运动、平滑关键点数据等。
* **🧩 灵活的数据加载器 (`LoadDataset`)**: 可轻松解析和加载不同格式的动作识别数据集（如本项目使用的 "Self" 和 "HAViD" 数据集）。
* **📜 清晰的演示示例 (`demo`)**: 提供配置简单、易于运行的演示脚本，帮助新用户快速上手和理解框架的核心用法。

## 项目架构

CollabMind 的核心工作流程围绕一个中央**识别代理（RecognitionAgent）** 展开，该代理协调各个模块以完成任务识别：

```mermaid
graph TD
    A[视频/任务目标] --> B(ProcessVideo);
    B --> C{关键帧序列};
    C --> D[RecognitionAgent];
    D --> P[输出: 识别的动作序列];
```

## 安装指南

1. **克隆仓库**

    ```bash
    git clone https://gitee.com/AGIROS_Team/collabmind.git
    cd CollabMind
    ```

2. **创建虚拟环境并安装依赖**

    建议使用 Python 3.8 或更高版本。

    ```bash
    python -m venv venv
    source venv/bin/activate  # on Windows use `venv\Scripts\activate`
    pip install -r requirements.txt
    ```

## 快速上手

我们提供了一个端到端的动作识别演示，让您快速体验 CollabMind 的威力。

1. **准备演示资源 (`demo_assets`)**
    在项目根目录创建一个 `demo_assets` 文件夹，并按以下结构组织您的样本数据。这是一个运行演示所必需的步骤。

    ```text
    demo_assets/
    ├── prompts/
    │   └── action_recognition_system.txt  # 存放系统提示
    ├── sample_task_self2/
    │   ├── images                         # 存放视频
    │   │   ├── frame_0.jpg
    │   │   └── frame_5.jpg
    │   ├── odag.txt                       # 任务依赖描述
    │   └── requirements.json              # 任务所需零件清单
    └── sample_data/
        └── intro_self2.png                # 零件介绍图
    ```

2. **配置API密钥**

    我们建议通过命令行参数传入您的API密钥。您也可以通过设置环境变量来配置。

3. **运行动作识别演示**

    从项目根目录运行以下命令：

    ```bash
    python demo/demo_action_recognition.py --api-key "sk-YOUR_API_KEY_HERE" --model-name gpt-5-mini --task-data-dir ./demo_assets/sample_task_self2/v3 --prompt-path ./demo_assets/prompts/action_recognition_system.txt --sm-prompt-path ./demo_assets/prompts/gen_semantic_map_system.txt --intro-image-path ./demo_assets/sample_data/intro_self2.png --output-dir output/action_recognition
    ```

    演示将开始运行，处理 `sample_task_self2` 中的关键帧，并将详细的日志和结果保存在 `output/demo_run` 目录中。

## 模块详解

* **`ApiEnv`**: 封装了与底层LLM API的通信逻辑，是所有AI模块与模型交互的桥梁。
* **`LoadDataset`**: 负责解析特定格式的数据集文件，将其转换为程序可以使用的标准动作序列和依赖关系。
* **`Planner`**: 状态管理的核心。它不执行任务，而是根据规则（依赖、资源等）跟踪每个任务的状态（如 `PENDING`, `EXECUTABLE`, `FINISHED`），并告知上层哪些任务是当前可执行的。
* **`Modules`**: 包含独立的、可重用的AI功能单元。例如，`SemanticMapGenerator` 专门负责从图像中生成场景的结构化描述。
* **`RecognitionAction`**: 框架的大脑。`RecognitionAgent` 在这里被定义，它负责协调 `Planner`、`Modules` 和 `ApiEnv`，执行完整的“感知-思考-行动”循环。
* **`ProcessVideo`**: 一个包含视频处理算法的工具库，提供关键帧提取、运动分析等原子能力。
* **`demo`**: 包含如何使用本框架完成特定任务的端到端示例脚本。

## 许可证

本项目采用 [MIT 许可证](LICENSE)。