pit-client/README.md

# PitChat（智队）

> PIT 用户交互层应用 - Personal Intelligent Team Client

**英文名**：PitChat
**中文名**：智队

## 项目概述

PitChat（智队）是 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 | 作者: 小白 🐶*