xiaozhi-client 1.6.0-rc.0 → 1.6.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://badge.fury.io/js/xiaozhi-client.svg)](https://badge.fury.io/js/xiaozhi-client)
 [![codecov](https://codecov.io/gh/shenjingnan/xiaozhi-client/branch/main/graph/badge.svg)](https://codecov.io/gh/shenjingnan/xiaozhi-client)
 [![CI](https://github.com/shenjingnan/xiaozhi-client/workflows/Release/badge.svg)](https://github.com/shenjingnan/xiaozhi-client/actions)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
 <img src="https://raw.githubusercontent.com/shenjingnan/xiaozhi-client/main/docs/images/qq-group-qrcode.jpg" alt="QQ群" width="300"/>
 
@@ -11,6 +11,51 @@
 
 ![效果图](https://raw.githubusercontent.com/shenjingnan/xiaozhi-client/main/docs/images/preview.png)
 
+## 目录
+
+1. [Xiaozhi Client](#xiaozhi-client)
+   1. [目录](#目录)
+   2. [功能特色](#功能特色)
+   3. [快速上手](#快速上手)
+      1. [全局安装 xiaozhi-client 命令行工具](#全局安装-xiaozhi-client-命令行工具)
+      2. [通过 npx 直接运行](#通过-npx-直接运行)
+      3. [使用 Docker 运行](#使用-docker-运行)
+         1. [前置要求](#前置要求)
+         2. [快速启动](#快速启动)
+         3. [获取小智接入点地址](#获取小智接入点地址)
+         4. [配置服务](#配置服务)
+            1. [方式一：通过 Web UI 配置（推荐）](#方式一通过-web-ui-配置推荐)
+            2. [方式二：直接编辑配置文件](#方式二直接编辑配置文件)
+         5. [常用操作](#常用操作)
+         6. [故障排除](#故障排除)
+   4. [可用命令](#可用命令)
+   5. [多接入点配置](#多接入点配置)
+      1. [配置方式](#配置方式)
+         1. [方式一：单接入点配置（字符串）](#方式一单接入点配置字符串)
+         2. [方式二：多接入点配置（字符串数组）](#方式二多接入点配置字符串数组)
+      2. [使用命令管理接入点](#使用命令管理接入点)
+      3. [示例配置](#示例配置)
+      4. [注意事项](#注意事项)
+   6. [ModelScope MCP 服务集成](#modelscope-mcp-服务集成)
+      1. [配置方式](#配置方式-1)
+      2. [使用前准备](#使用前准备)
+      3. [注意事项](#注意事项-1)
+   7. [自建服务端 JSON-RPC 消息格式规范](#自建服务端-json-rpc-消息格式规范)
+      1. [消息类型](#消息类型)
+         1. [1. 请求（Request）- 需要响应](#1-请求request--需要响应)
+         2. [2. 通知（Notification）- 不需要响应](#2-通知notification--不需要响应)
+         3. [3. 成功响应（Response）](#3-成功响应response)
+         4. [4. 错误响应（Error）](#4-错误响应error)
+      2. [重要注意事项](#重要注意事项)
+      3. [通信时序图](#通信时序图)
+      4. [常见错误](#常见错误)
+   8. [Web UI 配置界面](#web-ui-配置界面)
+      1. [功能特性](#功能特性)
+      2. [启动 Web UI](#启动-web-ui)
+   9. [作为 MCP Server 集成到其他客户端](#作为-mcp-server-集成到其他客户端)
+      1. [方式一：使用 stdio 模式（推荐）](#方式一使用-stdio-模式推荐)
+      2. [方式二：使用 HTTP Server 模式](#方式二使用-http-server-模式)
+
 ## 功能特色
 
 - 支持 小智(xiaozhi.me) 官方服务器接入点
@@ -83,15 +128,48 @@ npx -y xiaozhi-client start
 这个脚本会自动完成以下操作：
 
 - 创建工作目录 `~/xiaozhi-client`
-- 拉取最新的 Docker 镜像
+- 拉取指定版本的 Docker 镜像
 - 停止并删除已存在的容器（如果有）
 - 启动新的容器并配置端口映射
 
+**基本使用：**
+
+> 下载并运行启动脚本（默认使用最新版本）
+
 ```bash
-# 下载并运行启动脚本
 curl -fsSL https://raw.githubusercontent.com/shenjingnan/xiaozhi-client/main/docker-start.sh | bash
 ```
 
+> 无法访问 `Github` 可以使用 `Gitee` 替代
+
+```bash
+curl -fsSL https://gitee.com/shenjingnan/xiaozhi-client/raw/main/docker-start.sh | bash
+```
+
+**指定版本运行：**
+
+启动脚本现在支持灵活的版本指定方式：
+
+```bash
+# 下载脚本
+curl -fsSL https://raw.githubusercontent.com/shenjingnan/xiaozhi-client/main/docker-start.sh -o docker-start.sh
+
+# 下载脚本（Gitee）
+curl -fsSL https://gitee.com/shenjingnan/xiaozhi-client/raw/main/docker-start.sh | bash
+
+# 为脚本设置可执行权限
+chmod +x docker-start.sh
+
+# 使用默认版本 (latest)
+./docker-start.sh
+
+# 通过位置参数指定版本
+./docker-start.sh v1.6.0
+
+# 查看帮助信息
+./docker-start.sh --help
+```
+
 **方式二：使用 Docker Compose**
 
 首先获取 docker-compose.yml 文件：
@@ -100,6 +178,9 @@ curl -fsSL https://raw.githubusercontent.com/shenjingnan/xiaozhi-client/main/doc
 # 下载 docker-compose.yml 文件
 curl -O https://raw.githubusercontent.com/shenjingnan/xiaozhi-client/main/docker-compose.yml
 
+# 下载 docker-compose.yml 文件（Gitee）
+curl -O https://gitee.com/shenjingnan/xiaozhi-client/raw/main/docker-compose.yml
+
 # 使用 Docker Compose 启动
 docker-compose up -d
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xiaozhi-client",
-  "version": "1.6.0-rc.0",
+  "version": "1.6.0",
   "description": "小智 AI 客户端 命令行工具",
   "type": "module",
   "main": "dist/cli.js",
@@ -20,6 +20,28 @@
     "xiaozhi": "./dist/cli.js",
     "xiaozhi-client": "./dist/cli.js"
   },
+  "scripts": {
+    "build": "pnpm run build:web && tsup",
+    "build:web": "cd web && pnpm install && pnpm run build",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:ui": "vitest --ui",
+    "format": "biome format --write .",
+    "lint": "biome lint --write .",
+    "type:check": "tsc --noEmit",
+    "check": "biome check .",
+    "check:fix": "biome check --write --unsafe .",
+    "check:all": "pnpm check && pnpm type:check && pnpm spell:check && pnpm duplicate:check",
+    "spell:check": "cspell \"src/**/*.ts\" \"*.md\" \"*.json\"",
+    "duplicate:check": "jscpd src/",
+    "docker:update-version": "node scripts/update-dockerfile-version.js",
+    "release": "semantic-release",
+    "release:beta": "semantic-release",
+    "release:dry": "semantic-release --dry-run",
+    "release:dry:beta": "semantic-release --dry-run"
+  },
   "keywords": [
     "xiaozhi",
     "mcp",
@@ -79,26 +101,11 @@
     "typescript": "^5.8.3",
     "vitest": "^3.2.3"
   },
-  "scripts": {
-    "build": "pnpm run build:web && tsup",
-    "build:web": "cd web && pnpm install && pnpm run build",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:ui": "vitest --ui",
-    "format": "biome format --write .",
-    "lint": "biome lint --write .",
-    "type:check": "tsc --noEmit",
-    "check": "biome check .",
-    "check:fix": "biome check --write --unsafe .",
-    "check:all": "pnpm check && pnpm type:check && pnpm spell:check && pnpm duplicate:check",
-    "spell:check": "cspell \"src/**/*.ts\" \"*.md\" \"*.json\"",
-    "duplicate:check": "jscpd src/",
-    "docker:update-version": "node scripts/update-dockerfile-version.js",
-    "release": "semantic-release",
-    "release:beta": "semantic-release",
-    "release:dry": "semantic-release --dry-run",
-    "release:dry:beta": "semantic-release --dry-run"
+  "pnpm": {
+    "overrides": {
+      "form-data": "^4.0.4",
+      "braces": ">=3.0.3",
+      "micromatch": ">=4.0.8"
+    }
   }
-}
+}

package/web/README.md

@@ -0,0 +1,169 @@
+# 小智客户端 Web UI
+
+这是小智客户端的 Web 配置界面，提供了一个现代化、直观的界面来管理 MCP 服务配置。
+
+## 功能特性
+
+- 🎨 **现代化设计**：基于 shadcn/ui 组件库，提供优雅的用户界面
+- 🔧 **可视化配置**：无需手动编辑 JSON 文件，通过界面即可完成所有配置
+- 🚀 **实时状态监控**：实时显示与小智服务器的连接状态
+- 📦 **MCP 服务管理**：支持添加、编辑、删除 MCP 服务，支持本地和 SSE 类型
+- ⚙️ **灵活的配置选项**：可调整心跳间隔、超时时间等连接参数
+- 🎯 **优秀的用户体验**：Toast 通知、确认对话框、平滑动画等
+
+## 技术栈
+
+- **框架**: React 18 + TypeScript
+- **构建工具**: Vite
+- **样式**: Tailwind CSS
+- **UI 组件**: shadcn/ui
+- **状态管理**: React Hooks
+- **通知系统**: Sonner
+- **图标**: Lucide React
+- **代码质量**: Biome (代码格式化和 linting)
+- **测试**: Vitest + React Testing Library
+
+## 开发指南
+
+### 安装依赖
+
+```bash
+pnpm install
+```
+
+### 开发命令
+
+```bash
+# 启动开发服务器
+pnpm dev
+
+# 构建生产版本
+pnpm build
+
+# 预览生产构建
+pnpm preview
+
+# 运行测试
+pnpm test
+
+# 运行测试（watch 模式）
+pnpm test:watch
+
+# 生成测试覆盖率报告
+pnpm test:coverage
+
+# 代码格式化
+pnpm format
+
+# 代码检查
+pnpm lint
+
+# 类型检查
+pnpm type:check
+
+# 运行所有检查并修复
+pnpm check:write
+```
+
+### 项目结构
+
+```
+web/
+├── src/
+│   ├── components/
+│   │   ├── ui/          # shadcn/ui 组件
+│   │   ├── ConfigEditor.tsx    # 配置编辑器
+│   │   ├── MCPServerList.tsx   # MCP 服务列表
+│   │   └── StatusCard.tsx      # 状态卡片
+│   ├── hooks/           # 自定义 React Hooks
+│   │   └── useWebSocket.ts     # WebSocket 连接管理
+│   ├── pages/           # 页面组件
+│   │   └── Dashboard.tsx       # 主控制台页面
+│   ├── types/           # TypeScript 类型定义
+│   ├── utils/           # 工具函数
+│   ├── App.tsx          # 应用主组件
+│   ├── main.tsx         # 应用入口
+│   └── index.css        # 全局样式
+├── public/              # 静态资源
+├── tests/               # 测试文件
+└── package.json         # 项目配置
+```
+
+### UI 组件说明
+
+#### StatusCard
+显示与小智服务器的连接状态，包括：
+- 连接状态指示器（连接中/已连接/已断开）
+- 最后活动时间
+- 重连按钮
+
+#### ConfigEditor
+配置编辑器，用于：
+- 编辑 MCP 接入点 URL
+- 调整连接参数（心跳间隔、超时时间等）
+- 管理 ModelScope API Key
+
+#### MCPServerList
+MCP 服务管理界面，支持：
+- 查看所有已配置的 MCP 服务
+- 添加新服务（支持 JSON 批量导入）
+- 编辑现有服务配置
+- 删除服务（带确认对话框）
+
+### 样式定制
+
+项目使用 Tailwind CSS 和 CSS 变量进行样式管理。主题颜色定义在 `src/index.css` 中：
+
+```css
+:root {
+  --background: 0 0% 100%;
+  --foreground: 222.2 84% 4.9%;
+  --primary: 222.2 47.4% 11.2%;
+  --destructive: 0 84.2% 60.2%;
+  /* ... 其他颜色变量 */
+}
+```
+
+### 添加新的 UI 组件
+
+如果需要添加新的 shadcn/ui 组件：
+
+```bash
+# 查看可用组件
+npx shadcn@latest add
+
+# 添加特定组件（例如 dialog）
+npx shadcn@latest add dialog
+```
+
+### 测试
+
+项目使用 Vitest 进行单元测试：
+
+```bash
+# 运行所有测试
+pnpm test
+
+# 运行特定测试文件
+pnpm test ConfigEditor
+
+# 生成覆盖率报告
+pnpm test:coverage
+```
+
+### 贡献指南
+
+1. Fork 项目
+2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
+3. 提交更改 (`git commit -m 'feat: 添加某个很棒的功能'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 创建 Pull Request
+
+提交前请确保：
+- 所有测试通过 (`pnpm test`)
+- 代码通过格式检查 (`pnpm check:write`)
+- 类型检查通过 (`pnpm type:check`)
+
+## 许可证
+
+MIT License