yunxiafei
cd89b0c94e
- 项目概述与技术栈
- 系统架构设计
- 项目结构（Monorepo）
- 核心功能设计
- API 客户端与 WebSocket 事件
- 开发指南
- 界面设计
- 开发计划
版本: v1.0
作者: 小白 🐶
375 lines
12 KiB
Markdown
375 lines
12 KiB
Markdown
# PIT 用户交互层应用
|
||
|
||
> Personal Intelligent Team Client - 用户交互层应用
|
||
|
||
## 项目概述
|
||
|
||
PIT Client 是 PIT（Personal Intelligent Team）系统的用户交互层应用，提供桌面、Web 和移动端多种访问方式，让用户能够与智能体团队进行交互。
|
||
|
||
### 核心目标
|
||
|
||
- 提供统一的用户界面
|
||
- 支持 WebSocket 实时通信
|
||
- 多平台支持（桌面/Web/移动端）
|
||
- 会话管理与历史记录
|
||
- Agent 选择与切换
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
### 桌面应用 (Electron)
|
||
|
||
| 技术 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| Electron | 28+ | 跨平台桌面应用框架 |
|
||
| React | 18+ | UI 组件库 |
|
||
| TypeScript | 5+ | 类型安全 |
|
||
| Tailwind CSS | 3+ | 样式框架 |
|
||
| Socket.IO Client | 4+ | WebSocket 客户端 |
|
||
|
||
### Web 应用 (React)
|
||
|
||
| 技术 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| React | 18+ | UI 框架 |
|
||
| Vite | 5+ | 构建工具 |
|
||
| TypeScript | 5+ | 类型安全 |
|
||
| Tailwind CSS | 3+ | 样式框架 |
|
||
| Socket.IO Client | 4+ | WebSocket 客户端 |
|
||
|
||
### 移动应用 (React Native)
|
||
|
||
| 技术 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| React Native | 0.73+ | 跨平台移动应用框架 |
|
||
| TypeScript | 5+ | 类型安全 |
|
||
| Socket.IO Client | 4+ | WebSocket 客户端 |
|
||
|
||
---
|
||
|
||
## 系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 用户交互层 (Clients) │
|
||
│ │
|
||
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
|
||
│ │ Windows 桌面 │ │ Android App │ │ Web UI │ │
|
||
│ │ Electron │ │ React Native │ │ React + Vite │ │
|
||
│ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │
|
||
│ │ │ │ │
|
||
│ ┌───────┴──────────────────┴──────────────────┴───────┐ │
|
||
│ │ 共享核心模块 │ │
|
||
│ │ - WebSocket 连接管理 │ │
|
||
│ │ - 会话状态管理 │ │
|
||
│ │ - 消息渲染组件 │ │
|
||
│ │ - 用户认证 │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
│ WebSocket / HTTP
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ PIT 网关路由应用 (Gateway Router) │
|
||
│ http://1.14.58.157:9000 │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
pit-client/
|
||
├── packages/
|
||
│ ├── core/ # 共享核心模块
|
||
│ │ ├── src/
|
||
│ │ │ ├── api/ # API 客户端
|
||
│ │ │ │ ├── auth.ts # 认证 API
|
||
│ │ │ │ ├── sessions.ts # 会话 API
|
||
│ │ │ │ └── agents.ts # Agent API
|
||
│ │ │ ├── socket/ # WebSocket 管理
|
||
│ │ │ │ ├── client.ts # Socket.IO 客户端
|
||
│ │ │ │ └── events.ts # 事件定义
|
||
│ │ │ ├── store/ # 状态管理
|
||
│ │ │ │ ├── session.ts # 会话状态
|
||
│ │ │ │ ├── user.ts # 用户状态
|
||
│ │ │ │ └── agent.ts # Agent 状态
|
||
│ │ │ ├── types/ # 类型定义
|
||
│ │ │ └── utils/ # 工具函数
|
||
│ │ └── package.json
|
||
│ │
|
||
│ ├── desktop/ # Electron 桌面应用
|
||
│ │ ├── src/
|
||
│ │ │ ├── main/ # 主进程
|
||
│ │ │ │ └── index.ts
|
||
│ │ │ ├── renderer/ # 渲染进程
|
||
│ │ │ │ ├── App.tsx
|
||
│ │ │ │ ├── pages/
|
||
│ │ │ │ └── components/
|
||
│ │ │ └── preload/ # 预加载脚本
|
||
│ │ ├── electron-builder.json
|
||
│ │ └── package.json
|
||
│ │
|
||
│ ├── web/ # Web 应用
|
||
│ │ ├── src/
|
||
│ │ │ ├── App.tsx
|
||
│ │ │ ├── pages/
|
||
│ │ │ │ ├── Login.tsx
|
||
│ │ │ │ ├── Chat.tsx
|
||
│ │ │ │ └── Settings.tsx
|
||
│ │ │ ├── components/
|
||
│ │ │ │ ├── MessageList.tsx
|
||
│ │ │ │ ├── MessageInput.tsx
|
||
│ │ │ │ ├── AgentSelector.tsx
|
||
│ │ │ │ └── SessionList.tsx
|
||
│ │ │ └── main.tsx
|
||
│ │ ├── vite.config.ts
|
||
│ │ └── package.json
|
||
│ │
|
||
│ └── mobile/ # React Native 移动应用
|
||
│ ├── src/
|
||
│ │ ├── App.tsx
|
||
│ │ ├── screens/
|
||
│ │ └── components/
|
||
│ └── package.json
|
||
│
|
||
├── package.json # Monorepo 根配置
|
||
├── pnpm-workspace.yaml # pnpm 工作空间
|
||
├── tsconfig.json # TypeScript 配置
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 核心功能
|
||
|
||
### 1. 用户认证
|
||
|
||
- 登录/注册
|
||
- JWT Token 管理
|
||
- 自动刷新 Token
|
||
- 登出
|
||
|
||
### 2. 会话管理
|
||
|
||
- 创建新会话
|
||
- 查看会话列表
|
||
- 切换会话
|
||
- 关闭会话
|
||
- 会话历史记录
|
||
|
||
### 3. 消息交互
|
||
|
||
- 发送文本消息
|
||
- 接收实时消息
|
||
- 流式消息显示
|
||
- 消息历史加载
|
||
- 附件发送（图片、文件）
|
||
|
||
### 4. Agent 管理
|
||
|
||
- 查看 Agent 列表
|
||
- 选择指定 Agent
|
||
- 查看 Agent 状态
|
||
- Agent 信息展示
|
||
|
||
---
|
||
|
||
## API 客户端
|
||
|
||
### 认证 API
|
||
|
||
```typescript
|
||
// 登录
|
||
POST /api/auth/login
|
||
Body: { username, password }
|
||
Response: { token, user }
|
||
|
||
// 注册
|
||
POST /api/auth/register
|
||
Body: { username, password, email }
|
||
Response: { token, user }
|
||
|
||
// 获取当前用户
|
||
GET /api/auth/me
|
||
Header: Authorization: Bearer <token>
|
||
Response: { user }
|
||
```
|
||
|
||
### 会话 API
|
||
|
||
```typescript
|
||
// 获取会话列表
|
||
GET /api/sessions
|
||
Response: { sessions[] }
|
||
|
||
// 创建会话
|
||
POST /api/sessions
|
||
Body: { agent_id?, title? }
|
||
Response: { session }
|
||
|
||
// 获取会话详情
|
||
GET /api/sessions/:id
|
||
Response: { session, messages[] }
|
||
```
|
||
|
||
---
|
||
|
||
## WebSocket 事件
|
||
|
||
### 客户端发送
|
||
|
||
```typescript
|
||
// 创建会话
|
||
socket.emit('session.create', { agent_id?, title? })
|
||
|
||
// 加入会话
|
||
socket.emit('session.join', { session_id })
|
||
|
||
// 发送消息
|
||
socket.emit('message.send', { session_id, content })
|
||
```
|
||
|
||
### 服务端推送
|
||
|
||
```typescript
|
||
// 连接成功
|
||
socket.on('connected', { user_id })
|
||
|
||
// 会话创建成功
|
||
socket.on('session.created', { session })
|
||
|
||
// 收到消息
|
||
socket.on('message', { session_id, message })
|
||
|
||
// 错误通知
|
||
socket.on('error', { code, message })
|
||
```
|
||
|
||
---
|
||
|
||
## 开发指南
|
||
|
||
### 环境要求
|
||
|
||
- Node.js 18+
|
||
- pnpm 8+
|
||
- Electron (桌面应用)
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
# 安装所有依赖
|
||
pnpm install
|
||
|
||
# 只安装 core
|
||
pnpm install --filter @pit/core
|
||
|
||
# 只安装 web
|
||
pnpm install --filter @pit/web
|
||
```
|
||
|
||
### 开发模式
|
||
|
||
```bash
|
||
# 启动 Web 应用
|
||
pnpm --filter @pit/web dev
|
||
|
||
# 启动桌面应用
|
||
pnpm --filter @pit/desktop dev
|
||
|
||
# 启动移动应用
|
||
pnpm --filter @pit/mobile start
|
||
```
|
||
|
||
### 构建发布
|
||
|
||
```bash
|
||
# 构建 Web 应用
|
||
pnpm --filter @pit/web build
|
||
|
||
# 构建桌面应用
|
||
pnpm --filter @pit/desktop build
|
||
|
||
# 构建移动应用
|
||
pnpm --filter @pit/mobile build
|
||
```
|
||
|
||
---
|
||
|
||
## 界面设计
|
||
|
||
### 主界面布局
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ PIT Client ─ □ × [用户头像] │
|
||
├──────────────┬──────────────────────────────────────────────────┤
|
||
│ │ │
|
||
│ 会话列表 │ 消息区域 │
|
||
│ │ │
|
||
│ ┌────────┐ │ ┌────────────────────────────────────────────┐ │
|
||
│ │ 会话1 │ │ │ Agent: 小白 │ │
|
||
│ │ 会话2 │ │ │ ───────────────────────────────────────── │ │
|
||
│ │ 会话3 │ │ │ │ │
|
||
│ └────────┘ │ │ [用户] 你好 │ │
|
||
│ │ │ │ │
|
||
│ [+ 新会话] │ │ [Agent] 你好！有什么可以帮你的？ │ │
|
||
│ │ │ │ │
|
||
│ │ └────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ │ ┌────────────────────────────────────────────┐ │
|
||
│ │ │ [附件] [输入消息...] [发送] │ │
|
||
│ │ └────────────────────────────────────────────┘ │
|
||
└──────────────┴──────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 开发计划
|
||
|
||
### Phase 1: 核心模块 (2-3 天)
|
||
|
||
- [ ] 项目结构搭建
|
||
- [ ] 共享核心模块
|
||
- [ ] API 客户端
|
||
- [ ] WebSocket 连接管理
|
||
|
||
### Phase 2: Web 应用 (3-4 天)
|
||
|
||
- [ ] 登录/注册页面
|
||
- [ ] 聊天界面
|
||
- [ ] 会话管理
|
||
- [ ] Agent 选择
|
||
|
||
### Phase 3: 桌面应用 (2-3 天)
|
||
|
||
- [ ] Electron 集成
|
||
- [ ] 原生功能
|
||
- [ ] 打包发布
|
||
|
||
### Phase 4: 移动应用 (3-4 天)
|
||
|
||
- [ ] React Native 界面
|
||
- [ ] 移动端适配
|
||
- [ ] 推送通知
|
||
|
||
---
|
||
|
||
## 相关项目
|
||
|
||
- [PIT Router](http://localhost:3000/yunxiafei/pit-router) - 网关路由应用
|
||
- [PIT Channel](http://localhost:3000/yunxiafei/PIT_Channel) - OpenClaw Channel 插件
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
---
|
||
|
||
*创建时间: 2026-03-14 | 作者: 小白 🐶*
|