# 🌐 UAL: 通用智能体语言 (Universal Agent Language)

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

[English Version](README.md) | **中文文档**

> **AI 智能体界的“世界语”。**  
> **The "Esperanto" for Artificial Intelligence.**

---

## 📖 项目简介

UAL (通用智能体语言) 是一个突破性的开源协议，旨在打破不同 AI 智能体之间的通信壁垒。与传统的 JSON/XML API 不同，UAL 采用**语义优先**的 DAG（有向无环图）结构，使机器人、IoT 设备和软件智能体能够以**节省 90% 带宽**的方式进行**零歧义**沟通。

在 **UAL v0.2** 中，我们引入了**双引擎解析器**（规则 + LLM）和**去中心化共识机制**，标志着 UAL 已具备支撑大规模生产级智能体网络的能力。

## 🆕 最新更新 (v0.2.1)

*   **🧠 Atlas 核心升级**: 
    *   **外挂加载**: 支持从 `src/ual/atlas.yaml` 加载外部词汇表，方便社区扩展。
    *   **词汇扩充**: 新增 50+ 家居与机器人常用概念（如 `living_room`, `fridge`, `turn_on`）。
    *   **智能匹配**: 自动处理复数（`lights` -> `light`）与别名映射。
*   **🔌 硬件生态全覆盖**: 
    *   **Embedded Core**: 新增 C/C++ 核心库，支持 Arduino/ESP32 等单片机接入。
    *   **Logic & Temporal**: 解析器升级，支持 "If-Then-Else" 条件判断与 "Wait 10s" 时序控制。
    *   **Semantic Hub**: 新增 `hub_sync.py` 工具，一键下载行业语义包（如 `smart_city_v1`）。
*   **⚡ Parser 增强 (v2.2)**: 
    *   **短语动词支持**: RuleBasedParser 新增 Bigram 检测，完美支持 "turn on", "pick up" 等双词动词。
    *   **精准度提升**: 优化了介词处理与连词逻辑。
*   **🛠️ 开发体验**: 
    *   `UAL` 类新增 `create_env_frame`, `parse`, `encode_from_graph` 等便捷 API。
    *   修复了 `universal_demo.py` 的依赖问题。

---

## ✨ 核心特性

| 特性 | 说明 |
| :--- | :--- |
| **🧠 递归语义元** | 支持零样本定义新概念 (如 `不 + 听 = 沉默`)。 |
| **🤖 双引擎解析** | **New!** 无缝切换 **规则解析** (极速) 与 **LLM 解析** (智能)。 |
| **🤝 分布式共识** | **New!** 基于 Gossip 协议，让智能体民主地“商议”新词汇。 |
| **📉 极致压缩** | 语义哈希与增量编码可减少 90% 的载荷大小。 |
| **🌍 环境共鸣** | 内置 3D 坐标系与物理环境感知能力。 |
| **🔌 万能网关** | 原生支持 ROS2 与 MQTT 适配，即插即用。 |
| **🌉 LLM 深度集成** | **New!** 提供 LangChain / LlamaIndex 原生插件 ("Tool" 支持)。 |
| **🎨 动态方言** | 支持特定领域（医疗、工业）的命名空间扩展。 |

---

## 🏗️ UAL 1.0 终极架构 (Ultimate Architecture)

UAL 采用三层分层架构，实现了从云端可视化编排到极端受限硬件的全面覆盖。

| 层级 (Layer) | 模块 (Module) | 核心能力 (Core Capability) | 功耗/带宽 (Power/BW) | 典型载体 (Device) |
| :--- | :--- | :--- | :--- | :--- |
| **应用层 (L3)** | **UAL-Studio** | DSL 编译器 & DAG 可视化预览 | High | Web / Desktop / Cloud |
| **逻辑层 (L2)** | **UAL-Core** | 语义还原、自愈网关、ECC 纠错 | Medium | Edge Gateway / Linux |
| **物理层 (L1)** | **UAL-Tiny** | 4-Byte Raw Bitstream 解析 | Ultra Low | MCU / FPGA / Sensors |

### 🌟 架构亮点
*   **全链路覆盖**: 从 React 前端可视化 DSL 编写，到 C 语言嵌入式解析，同一套语义协议贯穿始终。
*   **极致压缩 (Raw Bitstream)**: 在 L1 层，一条完整的动作指令仅需 **4 Bytes**，适用于水声通信、深空探测等极端环境。
*   **自愈能力 (Self-Healing)**: L2 层内置 ECC 纠错引擎，能够自动修复传输中的比特翻转错误。

---

## 🚀 快速开始

### 1. 安装

```bash
pip install ual-lang
```

### 2. 验证与体验 (一键集成)

使用 UAL CLI 命令行工具，几秒钟内完成环境检查与演示：

```bash
# 🏥 环境体检：检查依赖与核心功能
ual doctor

# 🎬 运行演示：体验语义编码/解码全流程
ual demo

# 🚀 快速集成：生成 boilerplate 代码，立即开始开发
ual init
```

### 3. "Hello World" 代码示例

运行 `ual init` 后，您将获得一个 `my_agent.py` 文件，内容如下：

```python
from ual import UAL

# 初始化智能体
sender = UAL("Robot_A")
receiver = UAL("Robot_B")

# 1. 编码: 自然语言 -> 紧凑二进制
cmd = "Move to Kitchen and clean the floor"
binary = sender.encode(cmd)

print(f"📦 Payload Size: {len(binary)} bytes")

# 2. 解码: 紧凑二进制 -> 结构化语义
msg = receiver.decode(binary)
print(f"📩 Received: {msg['natural_language']}")
```

### 4. 纯软件智能体与大模型 (Software Agents & LLMs)

UAL 不仅仅是为了机器人设计的，它同样是 **Multi-Agent Systems (MAS)** 的理想通信协议。无论是 LangChain 智能体、AutoGPT 还是 MetaGPT，都可以使用 UAL 进行高效、结构化的逻辑交换。

#### 🔹 接入大模型 (LangChain/LlamaIndex)

让你的 LLM 智能体原生支持 UAL 协议。

```python
from ual.llm_bridge import UALBridge

bridge = UALBridge("GPT-4_Agent")
response = bridge.speak("Drone return to base immediately", protocol='UAL')

print(f"Hex Output: {response['ual_binary_hex']}")
```

#### 🔹 纯软件智能体通信演示 (Virtual Agents)

查看两个纯软件智能体（无硬件）如何通过 UAL 交换逻辑条件（If-Then）：

```bash
python3 examples/virtual_agent_demo.py
# 演示 User Agent 发送 "If temperature is high then turn on fan"
# Service Agent 接收并解析出逻辑结构，而非简单的文本匹配。
```

---

## 🌈 全栈覆盖 (Full-Stack Support)

| 平台 | 模块 | 实现语言 | 适用场景 |
| :--- | :--- | :--- | :--- |
| **云端/边缘** | `UAL-Python` | Python | LLM 编排、复杂推理、数据监控 |
| **工业硬件** | `UAL-Tiny` | C / Rust | 传感器节点、执行器、单片机控制 |
| **人机交互** | `UAL-Studio` | React/Flask | 无代码指令生成、可视化调试 |

💡 **双轨演进策略**：
1. **硬核底层 (UAL-Tiny)**: 专为 ESP32/STM32 等低算力设备设计。无堆内存分配 (No-heap)，仅需 <10KB RAM 即可解码复杂语义指令。
2. **极致易用 (UAL-Studio)**: 提供 Node-RED 风格的 Web 编辑器，让非程序员也能通过拖拽生成 UAL 指令，并一键部署到硬件。

---

## 🛠️ 生态工具

### ⚡ 性能对比 (Benchmark)
| 协议 | 指令: "Move to Kitchen" | 数据包大小 | 解析延迟 (Avg) |
| :--- | :--- | :--- | :--- |
| JSON-RPC | `{"jsonrpc":"2.0","method":"move","params":...}` | ~120 bytes | 2.5ms |
| **UAL** | `0x0A1 0xBC2 0x00F` (Binary) | **12 bytes** | **0.1ms** |

```bash
python3 tools/benchmark.py
# 结果: UAL 通常快 5-10 倍，且数据包体积小 90%。
```

### 🧬 语言进化实验室 (Evolutionary Lab)
模拟语言进化过程，通过遗传算法优化语义压缩比。
```bash
python3 tools/evolution_lab.py
```

### 📊 实时监控看板
使用基于 Web 的仪表盘实时监控您的智能体网络。

```bash
python3 examples/dashboard.py
# 访问 http://localhost:5000
```

---

## 🧪 测试与验证 (Tests & Validation)

UAL 包含一套完整的自动化测试套件，涵盖核心编解码、逻辑解析、跨域场景以及异常处理。

### 1. 运行测试
使用 `pytest` 运行所有测试用例：

```bash
python3 -m pytest
# 预期输出: 11 passed in 0.xxs
```

### 2. 可视化报告 (Visualization)
测试过程中会自动生成 DAG (有向无环图) 可视化报告，直观展示语义解析结果。

| 智能家居场景 (Smart Home) | 工业协作场景 (Industrial) | 机器人社交场景 (Social Chat) |
| :---: | :---: | :---: |
| ![Smart Home](test_reports/images/scenario_smart_home.png) | ![Industrial](test_reports/images/scenario_industrial.png) | ![Social Chat](test_reports/images/scenario_social_chat.png) |

### 3. 异常处理 (Robustness)
包含针对 "Invalid Input" 和 "Unknown Concept" 的负面测试，确保系统在面对未知指令时能优雅降级或报错，而不是崩溃。

---

## 🌍 生态贡献 (Contribution)

UAL 旨在成为通用标准，我们非常欢迎社区贡献新的领域词库！

### 如何提交新词库？

为了保证语义 ID 的全局唯一性，我们提供了一套包管理工具来规范扩展流程。

#### 1. 创建扩展包
使用 `pkg_manager.py` 创建你的领域包（例如金融领域）：

```bash
# 在 src/ual/packages/ 生成 finance_v1.yaml
python3 tools/pkg_manager.py create finance_v1 --start-id 0x6000
```

#### 2. 编辑词库
在生成的 YAML 文件中添加你的概念：

```yaml
concepts:
  0x6001: ["invoice", "bill"]
  0x6002: ["payment", "transaction"]
```

#### 3. 验证冲突
在提交前，务必运行验证工具检查 ID 是否冲突：

```bash
python3 tools/pkg_manager.py validate finance_v1.yaml
# ✅ Validation Passed: No ID conflicts detected.
```

#### 4. 提交回传
将你的 `.yaml` 文件提交 Pull Request 到本仓库。合并后，这些 ID 将被全球 UAL 网络识别！

---

## 📂 项目结构

*   `src/ual/core.py`: **核心协议** (编解码逻辑)
*   `src/ual/parser.py`: **语义解析器** (规则引擎 & LLM)
*   `src/ual/atlas.py`: **语义注册表** (ID 映射与加载逻辑)
*   `src/ual/atlas.yaml`: **外部词汇表** (用户可扩展的词库配置)
*   `src/ual/consensus.py`: **分布式共识** (Gossip 协议)
*   `src/ual/llm_bridge.py`: **跨大模型桥接** (LangChain/LlamaIndex 插件)
*   `src/ual/ecc.py`: **纠错机制**
*   `src/ual/gateway.py`: **网关适配器** (ROS2/MQTT)
*   `spec/ual.proto`: **协议定义文件**

---

## 📜 开源协议

本项目基于 **MIT 许可证** 开源。

我们强烈鼓励**企业级引用**与商业化应用。无论是初创公司还是大型企业，您都可以自由地将 UAL 集成到您的商业产品中，无需支付任何费用。

详细协议内容请参阅 [LICENSE](LICENSE) 文件。

---

### 🟢 实时状态 (模拟值)

| 指标 | 数值 |
| :--- | :--- |
| **UAL 网络节点数** | 1,204 |
| **平均压缩率** | 91.2% |
| **共识达成率** | 99.99% |

*Made with ❤️ by the UAL Community*
