# DigitalHuman-Workflow

**Repository Path**: ccq/digital-human-workflow

## Basic Information

- **Project Name**: DigitalHuman-Workflow
- **Description**: 基于 Live2D 数字人的多 Workflow 对话系统，用户通过语音/文字/点击与数字人交互，后端由 AgentScope 编排多个 AI Agent 协作完成任务。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-06
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DigitalHuman-Workflow

> 多 Workflow 数字人系统 — Live2D + AgentScope + MiniMax

[![Python](https://img.shields.io/badge/python-3.11-blue)](https://www.python.org/)
[![AgentScope](https://img.shields.io/badge/agentscope-1.0.21-green)](https://github.com/agentscope-ai/agentscope)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

通过语音/文字/点击与 Live2D 数字人交互，后端 Workflow 引擎编排多个 AI Agent 协作完成任务。支持天气查询（3 节点严格校验，自动切换 Archive/Forecast API）、通用问答（联网搜索）、闲聊直答三种工作流。

---

## 目录

- [特性](#特性)
- [架构](#架构)
- [快速开始](#快速开始)
- [配置](#配置)
- [开发](#开发)
- [测试](#测试)
- [部署](#部署)
- [API](#api)
- [文档索引](#文档索引)

---

## 特性

| 特性 | 说明 |
|------|------|
| 🎤 **多通道输入** | 语音 / 文字 / 点击身体三种交互方式 |
| 🧠 **智能路由** | 自动识别用户意图 → 分发到对应 Workflow |
| 🔄 **多节点 Workflow** | 天气查询 3 Worker（预查询→查询→校验+格式化）；通用 QA 2 Worker（搜索→回答） |
| 🌤️ **智能 API 切换** | 今天/明天 → Forecast API；昨天/历史 → Archive API；自动选择 |
| ✅ **结果校验+重试** | LLM 驱动的数据质量验证，不通过自动重试 |
| 😊 **Live2D 表情** | 5 种情绪状态，随 Workflow 阶段自动切换 |
| 🛡️ **断路器** | MiniMax API 异常时自动熔断，保护配额 |
| 🐳 **Docker 支持** | 多阶段构建，一键 `docker compose up` |
| 🔌 **可扩展** | 新 Workflow = 新建一个 Orchestrator + 注册一行 YAML |

---

## 架构

```
用户 → 语音/文字/点击
         │
Open-LLM-VTuber (Live2D + ASR + TTS) :12393
         │ OpenAI Compatible API
AgentScope Runtime :8090
    │
    ├─ Master Agent (ReAct, Tool Calling)
    │     ├─ run_weather → WeatherOrchestrator (3 Workers)
    │     ├─ run_general_qa → GeneralQAOrchestrator (2 Workers)
    │     └─ run_direct → DirectReplyOrchestrator
    │
    ├─ Router: 意图分类 (Structured Output)
    ├─ ExpressionManager: 阶段 → [emotion_key]
    │
    ▼
MiniMax API (LLM) + Open-Meteo (天气) + DuckDuckGo (搜索)
```

详细架构见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)

---

## 快速开始

### 环境要求

- Python 3.11+
- [uv](https://docs.astral.sh/uv/) 包管理器
- MiniMax API Key ([获取地址](https://platform.minimaxi.com))
- Open-LLM-VTuber（数字人前端，可选）

### 安装

```bash
git clone git@gitee.com:ccq/digital-human-workflow.git
cd digital-human-workflow

# 创建配置
cp .env.example .env
# 编辑 .env，填入你的 MINIMAX_API_KEY

# 安装依赖
uv sync
```

### 验证

```bash
# 单元测试（无需 API Key）
uv run pytest tests/ -v

# 启动服务
uv run python -m src.main
# → 监听 http://localhost:8090
```

### 第一个请求

```bash
curl -X POST http://localhost:8090/process \
  -H "Content-Type: application/json" \
  -d '{"input":[{"role":"user","content":[{"type":"text","text":"今天成都天气怎么样？"}]}]}'
```

### 使用 Docker

```bash
# 构建并启动
docker compose up -d

# 查看日志
docker compose logs -f

# 测试
curl -X POST http://localhost:8090/process \
  -H "Content-Type: application/json" \
  -d '{"input":[{"role":"user","content":[{"type":"text","text":"你好"}]}]}'

# 停止
docker compose down
```

---

## 配置

### 环境变量 (.env)

| 变量 | 必需 | 默认值 | 说明 |
|------|------|--------|------|
| `MINIMAX_API_KEY` | ✅ | — | MiniMax API 密钥 |
| `MINIMAX_MODEL` | ❌ | `MiniMax-M2.7` | 模型名（M2.7/M3） |
| `MINIMAX_BASE_URL` | ❌ | `https://api.minimaxi.com/v1` | API 基地址 |
| `AGENTSCOPE_PORT` | ❌ | `8090` | 服务端口 |
| `LOG_LEVEL` | ❌ | `INFO` | 日志级别 |

详见 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)

### Workflow 注册

编辑 `src/config/workflows.yaml` 即可注册新 Workflow，无需改代码。
详见 [CONTRIBUTING.md](CONTRIBUTING.md)

---

## 开发

### 项目结构

```
src/
├── main.py               # 入口
├── agent_app.py          # AgentScope App + Master Agent
├── router.py             # Router Agent
├── expression_manager.py # Live2D 表情管理
├── orchestors/           # Workflow 编排器
├── agents/               # Worker Agent
├── tools/                # 工具函数
├── schemas/              # Pydantic 数据模型
├── utils/                # 断路器/重试
└── config/               # 配置 YAML + settings
```

### 代码质量

```bash
# Lint
uvx ruff check src/ tests/

# Format
uvx ruff format src/ tests/
```

---

## 测试

### 测试等级

| 等级 | 命令 | 数量 | 耗时 | 需要 API |
|------|------|------|------|---------|
| 单元 | `uv run pytest tests/ -k "not integration and not e2e"` | 34 | <0.8s | ❌ |
| 集成 | `uv run pytest tests/ -m integration` | 6 | ~120s | ✅ |
| E2E | `uv run python tests/test_e2e.py` | 4 | ~60s | ✅ |

详见 [docs/TESTING.md](docs/TESTING.md)

---

## 部署

### 本地部署

```bash
./scripts/start.sh
```

### 对接 OLV（数字人前端）

在 OLV 的 `conf.yaml` 中：

```yaml
llm_provider: 'openai_compatible_llm'
openai_compatible_llm:
  base_url: 'http://localhost:8090/compatible-mode/v1'
  model: 'MiniMax-M2.7'
  llm_api_key: 'not-needed'
```

### 嵌入网页（右下角 Widget）

一行代码即可在任何网页右下角嵌入 Live2D 数字人：

```html
<script src="http://localhost:12393/widget/embed-snippet.js"></script>
```

支持三种模式：纯展示 / 文字聊天 / 语音对话。详见 `widget/embed-snippet.html`。

### 注意事项

- 先启动本项目（`:8090`），再启动 OLV（`:12393`）
- 生产环境建议加 systemd 守护
- AgentScope 进程崩溃时 `start.sh` 自动重启

---

## API

### 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/process` | 对话处理（SSE 流式） |
| `POST` | `/compatible-mode/v1/chat/completions` | OpenAI 兼容接口 |
| `GET` | `/compatible-mode/v1/models` | 模型列表 |

### 请求格式

```json
{
  "input": [{
    "role": "user",
    "content": [{"type": "text", "text": "今天成都天气怎么样？"}]
  }]
}
```

### 响应格式（SSE）

```
data: {"status":"created","id":"..."}
data: {"status":"in_progress","id":"..."}
data: {"object":"content","type":"text","text":"[surprise] 正在分析…","delta":true}
data: {"object":"content","type":"text","text":"[smirk] 正在查询…","delta":true}
data: {"object":"content","type":"text","text":"[joy] 成都 2026-06-07 天气：小雨…","delta":true}
data: {"status":"completed","id":"..."}
```

详见 [docs/API.md](docs/API.md)

---

## 文档索引

| 文档 | 用途 |
|------|------|
| [README.md](README.md) | 项目概述、快速开始 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 新人教程——如何添加新 Workflow |
| [CHANGELOG.md](CHANGELOG.md) | 版本变更记录 |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 技术架构设计 |
| [docs/API.md](docs/API.md) | API 接口文档 |
| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | 配置项参考 |
| [docs/TESTING.md](docs/TESTING.md) | 测试体系与验证指南 |
| [docs/VERIFICATION.md](docs/VERIFICATION.md) | 端到端验证清单 |
| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | 常见问题排查 |
| [docs/SECURITY.md](docs/SECURITY.md) | 安全策略 |

---

## License

MIT © 2026