From cd89b0c94eab16d0b06286b4974ce3db334fb545 Mon Sep 17 00:00:00 2001 From: yunxiafei <307327147@qq.com> Date: Sat, 14 Mar 2026 19:44:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20PIT=20=E7=94=A8?= =?UTF-8?q?=E6=88=B7=E4=BA=A4=E4=BA=92=E5=B1=82=E5=BA=94=E7=94=A8=E6=8A=80?= =?UTF-8?q?=E6=9C=AF=E6=96=B9=E6=A1=88=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 项目概述与技术栈 - 系统架构设计 - 项目结构（Monorepo） - 核心功能设计 - API 客户端与 WebSocket 事件 - 开发指南 - 界面设计 - 开发计划 版本: v1.0 作者: 小白 🐶 --- README.md | 375 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 373 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9870fde..bad5e9d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,374 @@ -# pit-client +# PIT 用户交互层应用 -PIT 用户交互层应用 - Personal Intelligent Team Client (桌面/Web/移动端) \ No newline at end of file +> 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 +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 | 作者: 小白 🐶*