npm package: @gnai/message-content-renderer
Description: 一个为光年 AI 智能体打造的现代化网页端对话应用，提供流畅的用户体验和强大的功能特性。
Latest version: 0.1.20

# 光年 AI 智能体对话网页端

一个为光年 AI 智能体打造的现代化网页端对话应用，提供流畅的用户体验和强大的功能特性。

## 🎯 项目概述

这是一个基于 Vue 3 + TypeScript 构建的智能体对话平台，用户可以通过网页与指定的 AI 智能体进行自然对话交互。项目采用组件化架构，具有优秀的响应式设计和流畅的动画效果。

## ✨ 核心功能

### 🤖 智能体识别与信息加载

- **动态 ID 解析**: 从域名自动提取智能体 ID（如 `gnlab.a.gnlab.com` → `gnlab`）
- **智能体信息展示**: 加载并展示智能体的头像、名称、描述、作者信息
- **动态页面配置**: 根据智能体信息自动更新网页标题和 favicon
- **加载状态管理**: 提供优雅的加载动画和错误处理

### 💬 智能对话系统

- **文本对话**: 支持纯文本消息的发送与接收
- **图文混合**: 支持文本与图片的混合消息
- **图片上传**: 最多支持 5 张图片上传，提供预览和删除功能
- **消息重试**: 失败消息支持重新发送
- **Markdown 渲染**: 支持 Markdown 格式的消息展示
- **多媒体支持**: 支持图片、视频、音频、文件等多种消息类型

### 🔐 用户认证系统

- **登录状态检测**: 自动检查用户登录状态
- **无感登录**: 未登录时在对话窗口内展示登录组件
- **Token 管理**: 完善的用户认证和状态管理
- **用户信息**: 自动获取和展示用户信息

### 🎨 现代化界面

- **Apple 风格设计**: 简洁大方的视觉设计，大量留白
- **响应式布局**: 完美适配桌面端和移动端
- **智能面板**: 可展开/收起的智能体信息面板
- **流畅动画**: 平滑的过渡效果和交互动画
- **键盘快捷键**: 提供高效的键盘操作支持

## 🏗️ 技术架构

### 技术栈

- **前端框架**: Vue 3 (Composition API)
- **状态管理**: Pinia
- **类型检查**: TypeScript
- **样式方案**: Less + CSS 变量
- **图标库**: Iconify (@iconify/vue)
- **HTTP 客户端**: Axios
- **构建工具**: Vite
- **代码格式化**: Prettier

### 项目结构

```
src/
├── components/          # 15+ 个高内聚组件
│   ├── AgentPanel.vue      # 智能体信息面板
│   ├── ChatArea.vue        # 对话区域容器
│   ├── MessageItem.vue     # 单条消息组件
│   ├── MessageList.vue     # 消息列表
│   ├── InputArea.vue       # 输入区域
│   ├── ImagePreview.vue    # 图片预览
│   ├── LoginModal.vue      # 登录弹窗
│   └── 更多组件...
├── stores/             # Pinia 状态管理
│   ├── agent.ts            # 智能体状态
│   ├── chat.ts             # 对话状态
│   └── user.ts             # 用户状态
├── utils/              # 工具函数
│   ├── agent.ts            # 智能体相关
│   ├── request.ts          # HTTP 请求
│   └── app.ts              # 通用工具
├── lib/                # 可复用库组件
│   ├── MessageContentRenderer.vue  # 消息内容渲染器
│   └── ImageViewer.vue     # 图片查看器
├── App.vue             # 主应用组件
├── Login.vue           # 登录组件
├── main.ts             # 应用入口
└── main.css            # 全局样式
```

### 设计规范

- **配色方案**: 浅色主题，蓝色强调色
- **间距系统**: 4px 基础单位的规范化间距
- **圆角规范**: 6px-20px 的柔和圆角
- **动画系统**: 150ms-300ms 的流畅过渡

## 🚀 快速开始

### 环境要求

- Node.js ^20.19.0 || >=22.12.0
- pnpm 包管理器

### 安装与启动

```bash
# 克隆项目
git clone <repository-url>
cd gnai-angent-web

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建生产版本
pnpm build

# 预览生产版本
pnpm preview
```

### 开发命令

```bash
# 类型检查
pnpm type-check

# 代码格式化
pnpm format

# 构建库组件（MessageContentRenderer）
pnpm run build:lib
```

## 📱 使用方式

### 智能体部署

应用会自动从域名解析智能体 ID：

- `demo.a.gnlab.com` → 智能体 ID: `demo`
- `gnlab.a.gnlab.com` → 智能体 ID: `gnlab`
- `localhost:5173` → 开发环境默认使用 `demo`

### 对话功能

1. **发送消息**: 输入文本后按 Enter 或点击发送按钮
2. **图片上传**: 点击图片按钮选择最多 5 张图片
3. **新对话**: 使用 `Cmd/Ctrl + K` 快捷键
4. **切换面板**: 使用 `Cmd/Ctrl + I` 快捷键

### 移动端体验

- 面板默认收起，点击边缘按钮展开
- 支持侧滑手势操作
- 适配各种移动设备尺寸

## 📦 库组件发布

本项目包含可复用的 `MessageContentRenderer` 库组件：

```bash
# 构建库组件
pnpm run build:lib

# 发布到 npm
npm login
npm publish
```

### MessageContentRenderer 特性

- 支持多种消息类型（文本、图片、文件、音频、视频）
- Markdown 渲染支持
- 响应式设计
- 类型安全的 Vue 组件

## 🔧 配置说明

### 环境变量

项目支持以下环境变量配置：

- `VITE_API_BASE`: API 基础地址
- `VITE_APP_ENV`: 应用环境标识

### 构建配置

- `vite.config.ts`: 主应用构建配置
- `vite.config.lib.ts`: 库组件构建配置
- `tsconfig.json`: TypeScript 配置

## 🎨 自定义开发

### 主题定制

通过 CSS 变量系统可以轻松定制主题：

```css
:root {
  --color-primary: #007aff;
  --color-bg: #f5f5f7;
  --color-text: #1d1d1f;
}
```

### 组件扩展

所有组件都遵循高内聚低耦合原则，易于扩展和维护：

1. 新增功能建议创建独立组件
2. 使用 TypeScript 提供类型安全
3. 遵循现有的设计规范和命名约定

## 📋 API 接口

### 智能体接口

```typescript
// 获取智能体详情
GET /api/athena/v1/chatbot/detail?pid={agentId}
```

### 对话接口

```typescript
// 发送消息
POST /api/athena/v1/chat/send
{
  agentId: string,
  message: string,
  images?: string[]
}
```

## 🧪 测试与调试

### 开发模式

- 热重载开发服务器
- TypeScript 实时检查
- ESLint 代码检查
- Prettier 代码格式化

### 浏览器支持

- Chrome / Edge (最新版本)
- Firefox (最新版本)
- Safari (最新版本)
- 移动端浏览器

## 📈 性能优化

- **代码分割**: 基于路由的代码分割
- **图片懒加载**: 大图片的懒加载处理
- **虚拟滚动**: 大量消息的性能优化（可选）
- **缓存策略**: 智能体信息本地缓存

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- Vue.js 团队
- Pinia 团队
- 所有开源库的贡献者

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 GitHub Issues
- 查看开发文档: `DEVELOPMENT.md`
- 快速指南: `QUICKSTART.md`

---

✨ **由光年 AI 提供技术支持** | 🚀 **立即体验智能对话新境界**