@next-open-ai/openbot 0.1.1 → 0.1.3

package/README.md

@@ -12,7 +12,7 @@
 
 | 能力 | 说明 |
 |------|------|
-| **技能架构** | 基于 Cursor Agent Skills 规范，支持多路径加载、本地安装与动态扩展 |
+| **技能架构** | 基于 Agent Skills 规范，支持多路径加载、本地安装与动态扩展 |
 | **编码智能体** | 集成 [pi-coding-agent](https://www.npmjs.com/package/@mariozechner/pi-coding-agent)，支持多轮工具调用与代码执行 |
 | **浏览器自动化** | 内置 [agent-browser](https://www.npmjs.com/package/agent-browser)，可导航、填表、截图与数据抓取 |
 | **长期记忆** | 向量存储（Vectra）+ 本地嵌入，支持经验总结与会话压缩（compaction） |
@@ -27,7 +27,7 @@
 │                              客户端 / 接入层                                  │
 ├─────────────────┬─────────────────────────────┬─────────────────────────────┤
 │   CLI (openbot) │   WebSocket Gateway (JSON-RPC)  │   OpenBot Desktop (Electron)  │
-│   Commander     │   ws, 端口 3000               │   Vue 3 + Pinia + Vite       │
+│   Commander     │   ws, 端口 38080              │   Vue 3 + Pinia + Vite       │
 └────────┬────────┴──────────────┬──────────────┴──────────────┬──────────────┘
          │                        │                             │
          │                        │  HTTP + Socket.io            │
@@ -54,10 +54,21 @@
 ```
 
 - **CLI**：直接调用 Agent 核心，单次提示或批量脚本。
-- **Gateway**：对外提供 WebSocket（JSON-RPC），供 Web/移动端连接；内部负责起端口、拉 Nest 后端、路由请求。
-- **Desktop**：Electron 包一层 Vue 前端 + 本地 Nest 后端，通过 Gateway 或直连后端与 Agent 通信；技能、会话、任务、工作区等由 Nest 模块管理。
+- **WebSocket Gateway**（`src/gateway/`）：对外提供 WebSocket（JSON-RPC），供 Web/移动端连接；负责起端口、拉 Nest 后端子进程、代理 `/server-api` 请求。**与「Desktop 后端」是不同进程。**
+- **Desktop 后端**（`src/server/`）：NestJS HTTP API，即 **server-api**；会话、智能体配置、技能、任务、工作区、鉴权等由本模块提供。桌面前端与 Gateway 通过 HTTP 调用此服务。
+- **Desktop**：Electron 包一层 Vue 前端 + 上述后端；通过 Gateway 或直连 Desktop 后端与 Agent 通信。
 - **Agent 核心**：统一由 `AgentManager` 管理会话、技能注入与工具注册；记忆与 compaction 作为扩展参与 system prompt 与经验写入。
 
+### 目录与模块对应
+
+| 目录 | 说明 |
+|------|------|
+| `src/server/` | **Desktop 后端**（NestJS），HTTP API，前缀 `server-api`。不要与「Gateway 进程」混淆。 |
+| `src/gateway/` | **WebSocket 网关**，独立进程，提供 WS JSON-RPC 并代理到 Desktop 后端。 |
+| `src/agent/` | Agent 核心（CLI 与 Gateway 共用）。 |
+| `src/config/` | 桌面配置读取（~/.openbot/desktop），CLI 与 Gateway 共用。 |
+| `examples/workspace/` | 示例工作区数据（仅示例/测试用）。真实工作区根目录为 `~/.openbot/workspace/`。 |
+
 ---
 
 ## 各端技术栈
@@ -77,7 +88,7 @@
 | 类别 | 技术 |
 |------|------|
 | 协议 | JSON-RPC over WebSocket（`ws`） |
-| 端口 | 默认 3000，可 `-p` 指定 |
+| 端口 | 默认 38080，可 `-p` 指定 |
 | 职责 | 连接管理、消息路由、静态资源、拉 Nest 子进程 |
 | 方法 | `connect`、`agent.chat`、`agent.cancel`、`subscribe_session`、`unsubscribe_session` 等 |
 
@@ -133,7 +144,7 @@
 ### 环境要求
 
 - **Node.js** ≥ 20
-- 可选：`OPENAI_API_KEY` 或 `DEEPSEEK_API_KEY` 等（按所用 provider 配置）
+- 可选：`OPENAI_API_KEY` （按所用 provider 配置）
 
 ### 安装与构建
 
@@ -154,17 +165,51 @@ openbot -s ./skills "用 find-skills 搜一下 PDF 相关技能"
 # 仅打印 system/user prompt，不调 LLM
 openbot --dry-run --prompt "查北京天气"
 
-# 指定模型与 provider
+# 指定模型与 provider（覆盖桌面缺省）
 openbot --model deepseek-chat --provider deepseek "写一段 TypeScript 示例"
 ```
 
+### CLI 配置模型选项
+
+CLI 与桌面端共用**桌面配置**（`~/.openbot/desktop/config.json`）。未在命令行显式指定 `--provider` / `--model` 时，将使用该配置中的**缺省智能体**对应的 provider 与 model；若该智能体未单独配置模型，则使用全局缺省模型。
+
+| 操作 | 命令 | 说明 |
+|------|------|------|
+| 保存 API Key | `openbot login <provider> <apiKey>` | 将某 Provider 的 API Key 写入桌面配置，供 CLI 与桌面端共用 |
+| 设置缺省模型 | `openbot config set-model <provider> <modelId>` | 在桌面配置中设置全局缺省 provider 与 model（如 `deepseek` / `deepseek-chat`） |
+| 查看配置 | `openbot config list` | 列出桌面配置中的 providers 与缺省模型 |
+| 同步到 Agent 目录 | `openbot config sync` | 将桌面配置同步到 `~/.openbot/agent/models.json`，供 pi-agent 使用 |
+
+**常用 Provider 示例**：`deepseek`、`dashscope`、`openai`、`openai-custom`（自定义 OpenAI 兼容端点）、`nvidia`、`kimi`。模型 ID 需与各 Provider 支持的一致（如 DeepSeek 的 `deepseek-chat`、OpenAI 的 `gpt-4o`）；使用 `openai-custom` 时可填写自部署模型的 ID。
+
+**命令行覆盖**：单次执行时可用 `--provider`、`--model`、`--api-key` 覆盖配置或环境变量中的值。
+
+**环境变量**：未在桌面配置中保存 API Key 时，会回退到环境变量，例如 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY`、`DASHSCOPE_API_KEY` 等（详见 `openbot --help` 末尾的 Environment 说明）。
+
+**首次使用建议**：
+
+```bash
+# 1. 保存 API Key（任选其一或多种）
+openbot login deepseek YOUR_DEEPSEEK_API_KEY
+# openbot login openai YOUR_OPENAI_API_KEY
+
+# 2. 设置缺省模型
+openbot config set-model deepseek deepseek-chat
+
+# 3. 可选：同步到 agent 目录（桌面端保存配置后也会自动同步）
+openbot config sync
+
+# 4. 直接对话
+openbot "总结一下当前有哪些技能"
+```
+
 ### 启动 WebSocket 网关
 
 ```bash
-openbot gateway --port 3000
+openbot gateway --port 38080
 ```
 
-客户端通过 `ws://localhost:3000` 连接，使用 JSON-RPC 调用 `connect`、`agent.chat` 等。
+客户端通过 `ws://localhost:38080` 连接，使用 JSON-RPC 调用 `connect`、`agent.chat` 等。
 
 ### 启动桌面端
 
@@ -195,7 +240,7 @@ npm run desktop:install
 ## 开发
 
 ```bash
-# 单元/集成测试
+# 单元/集成测试（含 config/desktop-config、gateway/utils、server agents e2e）
 npm test
 
 # 仅 e2e
@@ -205,6 +250,8 @@ npm run test:e2e
 npm run test:memory
 ```
 
+测试分布：`test/config/` 桌面配置、`test/gateway/` 网关工具方法、`test/server/` Nest 后端 e2e。
+
 ---
 
 ## 许可证

package/desktop/README.md

@@ -0,0 +1,210 @@
+# OpenBot Desktop Application
+
+A professional desktop application for managing and executing AI agents with real-time chat, session management, and skills browsing.
+
+## 🚀 Features
+
+- **Real-time Agent Chat**: Stream responses from AI agents with live tool execution visualization
+- **Session Management**: Create, manage, and switch between multiple agent sessions
+- **Skills Browser**: Browse and explore available agent skills with detailed documentation
+- **Professional UI**: Modern glassmorphism design with dark/light theme support
+- **WebSocket Integration**: Real-time communication with OpenBot gateway service
+- **Configuration Management**: Flexible agent and workspace configuration
+
+## 📋 Prerequisites
+
+- Node.js >= 20.0.0
+- npm or yarn
+- OpenBot gateway service running
+
+## 🛠️ Installation
+
+### 1. Install Dependencies
+
+From the openbot root directory:
+
+```bash
+# Install desktop app dependencies
+npm run desktop:install
+
+# Or install manually
+cd desktop
+npm install
+cd server && npm install
+cd ../renderer && npm install
+```
+
+### 2. Build OpenBot Core
+
+```bash
+# From openbot root
+npm install
+npm run build
+```
+
+## 🎯 Usage
+
+### Development Mode
+
+Start all services in development mode:
+
+```bash
+# Terminal 1: Start OpenBot Gateway
+npm run build
+node dist/gateway/server.js
+
+# Terminal 2: Start Desktop App (from openbot root)
+npm run desktop:dev
+
+# Or from desktop directory
+cd desktop
+npm run dev
+```
+
+This will start:
+- NestJS backend on `http://localhost:38081`
+- Vue.js frontend on `http://localhost:5173`
+- Electron desktop window
+
+### Production Build
+
+```bash
+cd desktop
+npm run build
+```
+
+## 🏗️ Architecture
+
+### Backend (NestJS)
+
+- **Agents Module**: Session management and gateway integration
+- **Skills Module**: Skills browsing and documentation
+- **Config Module**: Application configuration management
+- **WebSocket Gateway**: Real-time event streaming
+
+### Frontend (Vue.js)
+
+- **Dashboard**: Overview and quick actions
+- **Agent Chat**: Real-time chat interface with streaming
+- **Sessions**: Session management and history
+- **Skills**: Skills browser with modal details
+- **Configuration**: Agent and workspace settings
+- **Settings**: Application preferences
+
+### Communication Flow
+
+```
+Desktop UI (Vue.js)
+    ↓ HTTP/WebSocket
+NestJS Backend
+    ↓ WebSocket
+OpenBot Gateway
+    ↓
+Agent Manager
+```
+
+## 📁 Directory Structure
+
+```
+desktop/
+├── main.js                 # Electron main process
+├── preload.js             # Electron preload script
+├── package.json           # Root dependencies
+├── server/                # NestJS backend
+│   ├── src/
+│   │   ├── agents/       # Agent management
+│   │   ├── skills/       # Skills browsing
+│   │   ├── config/       # Configuration
+│   │   └── main.ts       # Entry point
+│   └── package.json
+└── renderer/             # Vue.js frontend
+    ├── src/
+    │   ├── views/        # Page components
+    │   ├── components/   # Reusable components
+    │   ├── store/        # Pinia state management
+    │   ├── router/       # Vue Router
+    │   ├── api/          # API client
+    │   └── assets/       # Styles and assets
+    └── package.json
+```
+
+## 🎨 Design System
+
+The application uses a professional design system with:
+
+- **Glassmorphism effects**: Modern translucent UI elements
+- **Gradient accents**: Vibrant color gradients for primary actions
+- **Smooth animations**: Fade, slide, and pulse animations
+- **Dark/Light themes**: Automatic theme switching
+- **Typography**: Inter for UI, Roboto Mono for code
+- **Responsive layouts**: Adapts to different window sizes
+
+## 🔧 Configuration
+
+Configuration is stored in `~/.openbot/desktop/config.json`:
+
+```json
+{
+  "gatewayUrl": "ws://localhost:38080",
+  "defaultProvider": "deepseek",
+  "defaultModel": "deepseek-chat",
+  "defaultAgentId": "default",
+  "theme": "dark"
+}
+```
+
+（`defaultAgentId` 表示缺省智能体 id。）
+
+## 🐛 Troubleshooting
+
+### Gateway Connection Issues
+
+If the desktop app can't connect to the gateway:
+
+1. Ensure the gateway is running: `node dist/gateway/server.js`
+2. Check the gateway URL in Configuration
+3. Verify no firewall is blocking port 38080
+
+### Build Errors
+
+```bash
+# Clean and rebuild
+cd desktop
+rm -rf node_modules server/node_modules renderer/node_modules
+npm install
+```
+
+### WebSocket Not Connecting
+
+Check that:
+- NestJS backend is running on port 38081
+- Frontend is connecting to the correct backend URL
+- CORS is properly configured
+
+## 📝 Development Tips
+
+### Hot Reload
+
+All three services support hot reload:
+- Electron: Restart on main process changes
+- NestJS: Auto-restart on file changes
+- Vue.js: Hot module replacement
+
+### Debugging
+
+- **Frontend**: Open DevTools in Electron window (Cmd/Ctrl+Shift+I)
+- **Backend**: Check NestJS console output
+- **Gateway**: Check gateway server logs
+
+## 🚢 Building for Production
+
+```bash
+cd desktop
+npm run build
+```
+
+This creates platform-specific installers in `desktop/dist/`.
+
+## 📄 License
+
+MIT