Airi 项目实战指南：从环境搭建到功能落地

一、核心功能解析：AI 虚拟角色的技术实现

1.1 什么是 AI 驱动的虚拟角色系统？

Airi 项目是一个基于 LLM（大语言模型）的 Live2D/VRM 虚拟角色平台，核心功能是将 AI 角色"实体化"到现实世界中。想象一下，这就像给聊天机器人穿上了数字躯体，不仅能对话还能通过动作和表情传递情感。项目通过模块化设计实现了角色交互、环境感知和多平台部署三大核心能力。

1.2 为什么传统虚拟角色缺乏"灵魂"？

传统虚拟角色往往是预设动画的简单播放，而 Airi 采用实时渲染+AI 决策的双引擎架构。通过 apps/stage-tamagotchi/ 中的渲染系统和 services/ 目录下的 AI 服务，实现了角色行为的动态生成。这种架构解决了传统虚拟角色"重复动作"和"反应机械"的痛点。

避坑指南：首次接触项目时，建议先了解 packages/core-character/ 中的角色核心模块，这是理解整个项目架构的关键。

二、环境准备：从依赖到部署的完整流程

2.1 开发环境配置为什么需要特殊处理？

Airi 项目采用多语言混合开发（TypeScript/Rust）和微服务架构，传统的单一环境配置方式难以满足需求。项目使用 pnpm 工作区（类似多工位协同办公）和 Nix 环境隔离（如同不同部门的独立办公区）来解决依赖冲突问题。

2.2 如何验证环境配置的正确性？

执行以下命令检查环境完整性：

# 克隆项目仓库
git clone https://gitcode.com/GitHub_Trending/ai/airi
cd airi

# 安装依赖
pnpm install

# 运行环境检查脚本
pnpm run check-env

避坑指南：依赖安装失败时，先检查 Node.js 版本是否符合 package.json 中指定的要求（建议 v18.18+），并确保 Rust 工具链已正确安装。

三、实战操作：从零开始运行你的第一个虚拟角色

3.1 开发模式启动为什么需要特殊命令？

Airi 采用热重载开发模式，需要同时启动前端界面、后端服务和 AI 处理模块。通过 turbo 任务管理器（类似项目调度中心）实现多服务协同启动：

# 启动开发环境
pnpm dev

该命令会同时启动 apps/stage-web/（Web 界面）、apps/server/（后端服务）和 services/ 下的 AI 服务，所有模块会在代码变更时自动更新。

3.2 如何验证角色功能是否正常工作？

1. 访问 http://localhost:3000 打开 Web 界面
2. 在角色交互框输入"你好"并发送
3. 观察角色是否有语音回应和表情变化
4. 检查控制台输出是否有错误信息

避坑指南：如果角色没有响应，首先检查 apps/server/src/api/ 目录下的接口日志，确认 AI 服务是否正常连接。

四、深度解析：项目架构与配置优化

4.1 模块化架构如何提升开发效率？

Airi 采用"插件化微内核"设计，核心功能通过 packages/ 目录下的独立包管理：

• packages/stage-ui/：UI 组件库
• packages/audio/：音频处理模块
• packages/plugin-sdk/：插件开发工具包

这种设计允许开发者只关注特定模块，例如在 plugins/airi-plugin-bilibili-laplace/ 中开发 bilibili 平台集成插件，而无需了解整个项目代码。

4.2 配置文件如何适应多环境需求？

项目使用多层次配置系统：

1. 基础配置：tsconfig.json 和 uno.config.ts
2. 环境变量：.env.development 和 .env.production
3. 服务配置：apps/server/src/config/ 目录下的模块配置

例如，修改 apps/server/src/config/model.ts 中的模型参数，可以调整 AI 角色的响应风格，无需修改核心代码。

避坑指南：修改配置后建议运行 pnpm run validate-config 命令，确保配置格式正确。

通过这种结构化的开发方式，Airi 项目实现了 AI 虚拟角色的快速开发和灵活部署。无论是开发自定义角色插件，还是优化现有功能，理解这种模块化架构都是提升效率的关键。