xiaozhi-client 1.7.1 → 1.7.2

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xiaozhi-client",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "小智 AI 客户端 命令行工具",
   "type": "module",
   "main": "dist/cli.js",
@@ -25,6 +25,7 @@
     "build:web": "cd web && pnpm install && pnpm run build",
     "dev": "cross-env NODE_ENV=development tsup --watch",
     "test": "vitest run",
+    "test:silent": "vitest run --silent=true",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui",
@@ -37,7 +38,8 @@
     "spell:check": "cspell \"src/**/*.ts\" \"*.md\" \"*.json\"",
     "duplicate:check": "jscpd src/",
     "docker:update-version": "node scripts/update-dockerfile-version.js",
-    "example": "node --loader ts-node/esm"
+    "example": "node --loader ts-node/esm",
+    "docs:dev": "cd docs && mintlify dev"
   },
   "keywords": [
     "xiaozhi",
@@ -61,7 +63,7 @@
     "dotenv": "^17.2.1",
     "eventsource": "^4.0.0",
     "express": "^5.1.0",
-    "hono": "^4.9.6",
+    "hono": "^4.9.7",
     "json5": "^2.2.3",
     "json5-writer": "^0.2.0",
     "jsonc-parser": "^3.3.1",
@@ -90,6 +92,7 @@
     "glob": "^11.0.3",
     "happy-dom": "^18.0.1",
     "jscpd": "^4.0.5",
+    "mintlify": "^4.2.107",
     "release-it": "^19.0.4",
     "semver": "^7.7.2",
     "supertest": "^7.1.4",
@@ -103,7 +106,9 @@
     "overrides": {
       "form-data": "^4.0.4",
       "braces": ">=3.0.3",
-      "micromatch": ">=4.0.8"
+      "micromatch": ">=4.0.8",
+      "axios": ">=1.12.0"
     }
-  }
+  },
+  "packageManager": "pnpm@10.13.1"
 }

package/docs/{Architecture.md → development/architecture.mdx}

@@ -1,4 +1,7 @@
-# 项目架构
+---
+title: 项目架构
+sidebarTitle: 项目架构
+---
 
 ```mermaid
 graph TB

package/docs/docs.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "Xiaozhi Client",
+  "description": "用于聚合MCP Server的命令行工具",
+  "colors": {
+    "primary": "#3B82F6",
+    "light": "#F8FAFC",
+    "dark": "#0F172A"
+  },
+  "navigation": {
+    "pages": [
+      "getting-started/intro",
+      "getting-started/quickstart",
+      "usage/docker",
+      "reference/command"
+    ]
+  },
+  "navbar": {
+    "links": [
+      {
+        "icon": "qq",
+        "label": "QQ群",
+        "href": "https://qun.qq.com/universal-share/share?ac=1&authKey=c08PvS2zvAF1NN%2F%2BuaOi0ze1AElTIsvFBLwbWUMFc2ixjaZYxqZTUQHzipwd8Kka&busi_data=eyJncm91cENvZGUiOiIxMDU0ODg4NDczIiwidG9rZW4iOiJuSmJUN2cyUEVkNEQ5WXovM3RQbFVNcDluMGVibUNZTUQvL1RuQnFJRjBkZmRZQnRBRTdwU0szL3V2Y0dLc1ZmIiwidWluIjoiMzkxMTcyMDYwMCJ9&data=9cH6_zEC-sN3xYlwzKEWiYF71RLY9CId5taN-gy6XZo7axSlSWDpd1Ojui5hYMQKIgEJYSPw59XYgF5vH2wLog&svctype=4&tempid=h5_group_info"
+      },
+      {
+        "icon": "github",
+        "label": "GitHub",
+        "href": "https://github.com/shenjingnan/xiaozhi-client"
+      }
+    ]
+  },
+  "footer": {
+    "socials": {
+      "github": "https://github.com/shenjingnan/xiaozhi-client"
+    }
+  },
+  "integrations": {
+    "telemetry": {
+      "enabled": true
+    }
+  },
+  "contextual": {
+    "options": ["copy", "view"]
+  },
+  "errors": {
+    "404": {
+      "redirect": true
+    }
+  }
+}

package/docs/getting-started/install.mdx

@@ -0,0 +1,191 @@
+# CLI installation
+
+> Install the CLI to preview and develop your docs locally
+
+<img className="block dark:hidden my-0 pointer-events-none" src="https://mintcdn.com/mintlify/Y6rP0BmbzgwHuEoU/images/installation/local-development-light.png?fit=max&auto=format&n=Y6rP0BmbzgwHuEoU&q=85&s=ffd8bc88d87fc00fe1919a33a292fa01" width="1184" height="320" data-path="images/installation/local-development-light.png" srcset="https://mintcdn.com/mintlify/Y6rP0BmbzgwHuEoU/images/installation/local-development-light.png?w=280&fit=max&auto=format&n=Y6rP0BmbzgwHuEoU&q=85&s=511ef7cd18fd4fb900f2701d062ca11b 280w, https://mintcdn.com/mintlify/Y6rP0BmbzgwHuEoU/images/installation/local-development-light.png?w=560&fit=max&auto=format&n=Y6rP0BmbzgwHuEoU&q=85&s=3d88dd1c1b9502ecf779bae2a125bfa0 560w, https://mintcdn.com/mintlify/Y6rP0BmbzgwHuEoU/images/installation/local-development-light.png?w=840&fit=max&auto=format&n=Y6rP0BmbzgwHuEoU&q=85&s=b5c7231e4a48c366bc9fadc00ad67fc2 840w, https://mintcdn.com/mintlify/Y6rP0BmbzgwHuEoU/images/installation/local-development-light.png?w=1100&fit=max&auto=format&n=Y6rP0BmbzgwHuEoU&q=85&s=43e8d5fa61bcd586ccece993dc0c3f4d 1100w, https://mintcdn.com/mintlify/Y6rP0BmbzgwHuEoU/images/installation/local-development-light.png?w=1650&fit=max&auto=format&n=Y6rP0BmbzgwHuEoU&q=85&s=c06a3f73ae2ed6cc36cfc6a15a539baf 1650w, https://mintcdn.com/mintlify/Y6rP0BmbzgwHuEoU/images/installation/local-development-light.png?w=2500&fit=max&auto=format&n=Y6rP0BmbzgwHuEoU&q=85&s=6a946dbec95af5df7dc3f71daf25fed5 2500w" data-optimize="true" data-opv="2" />
+
+<img className="hidden dark:block my-0 pointer-events-none" src="https://mintcdn.com/mintlify/Y6rP0BmbzgwHuEoU/images/installation/local-development-dark.png?fit=max&auto=format&n=Y6rP0BmbzgwHuEoU&q=85&s=ef0bb527eb258f8d720180d106ea6625" width="1184" height="320" data-path="images/installation/local-development-dark.png" srcset="https://mintcdn.com/mintlify/Y6rP0BmbzgwHuEoU/images/installation/local-development-dark.png?w=280&fit=max&auto=format&n=Y6rP0BmbzgwHuEoU&q=85&s=b6ab6647def97748df5303d2add7877c 280w, https://mintcdn.com/mintlify/Y6rP0BmbzgwHuEoU/images/installation/local-development-dark.png?w=560&fit=max&auto=format&n=Y6rP0BmbzgwHuEoU&q=85&s=83a49f961c12baf9aa9755d972160915 560w, https://mintcdn.com/mintlify/Y6rP0BmbzgwHuEoU/images/installation/local-development-dark.png?w=840&fit=max&auto=format&n=Y6rP0BmbzgwHuEoU&q=85&s=9f44e898560aaa47af54ff0f6079ca6e 840w, https://mintcdn.com/mintlify/Y6rP0BmbzgwHuEoU/images/installation/local-development-dark.png?w=1100&fit=max&auto=format&n=Y6rP0BmbzgwHuEoU&q=85&s=1bc3413b87f72bb848de2a518cf16c3a 1100w, https://mintcdn.com/mintlify/Y6rP0BmbzgwHuEoU/images/installation/local-development-dark.png?w=1650&fit=max&auto=format&n=Y6rP0BmbzgwHuEoU&q=85&s=9b79a51b960489e0d41ffd61b9d7120d 1650w, https://mintcdn.com/mintlify/Y6rP0BmbzgwHuEoU/images/installation/local-development-dark.png?w=2500&fit=max&auto=format&n=Y6rP0BmbzgwHuEoU&q=85&s=db35248ff88939a314d4ecc547ffd463 2500w" data-optimize="true" data-opv="2" />
+
+## Installing the CLI
+
+<Info>
+  **Prerequisite**: Please install [Node.js](https://nodejs.org/en) before proceeding.
+</Info>
+
+<Steps>
+  <Step title="Install the CLI.">
+    Run the following command to install the [CLI](https://www.npmjs.com/package/mint):
+
+    <CodeGroup>
+      ```bash npm
+      npm i -g mint
+      ```
+
+      ```bash pnpm
+      pnpm add -g mint
+      ```
+    </CodeGroup>
+  </Step>
+
+  <Step title="Preview locally.">
+    Navigate to your docs directory (where your `docs.json` file is located) and execute the following command:
+
+    ```bash
+    mint dev
+    ```
+
+    A local preview of your documentation will be available at `http://localhost:3000`.
+  </Step>
+</Steps>
+
+Alternatively, if you do not want to install the CLI globally, you can run a one-time script:
+
+```bash
+npx mint dev
+```
+
+## Updates
+
+If your local preview is out of sync with what you see on the web in the production version, update your local CLI:
+
+```bash
+mint update
+```
+
+If this `mint update` command is not available on your local version, re-install the CLI with the latest version:
+
+<CodeGroup>
+  ```bash npm
+  npm i -g mint@latest
+  ```
+
+  ```bash pnpm
+  pnpm add -g mint@latest
+  ```
+</CodeGroup>
+
+## Custom ports
+
+By default, the CLI uses port 3000. You can customize the port using the `--port` flag. To run the CLI on port 3333, for instance, use this command:
+
+```bash
+mint dev --port 3333
+```
+
+If you attempt to run on a port that is already in use, it will use the next available port:
+
+```mdx
+Port 3000 is already in use. Trying 3001 instead.
+```
+
+## Previewing as a specific group
+
+If you use partial authentication to restrict access to your documentation, you can preview as a specific authentication group by using the `--group [groupname]` flag.
+
+For example, if you have a group named `admin`, you can preview as a member of that group with the command:
+
+```bash
+mint dev --group admin
+```
+
+## Additional commands
+
+While `mint dev` is the most commonly used command, there are other commands you can use to manage your documentation.
+
+### Finding broken links
+
+The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command:
+
+```bash
+mint broken-links
+```
+
+### Checking OpenAPI spec
+
+You can use the CLI to check your OpenAPI file for errors using the following command:
+
+```bash
+mint openapi-check <openapiFilenameOrUrl>
+```
+
+You can pass in a filename (e.g. `./openapi.yaml`) or a URL (e.g. `https://petstore3.swagger.io/api/v3/openapi.json`).
+
+### Renaming files
+
+You can rename and update all references to files using the following command:
+
+```bash
+mint rename <oldFilename> <newFilename>
+```
+
+### Migrating MDX endpoint pages
+
+You can migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification using the following command:
+
+```bash
+mint migrate-mdx
+```
+
+This command converts individual MDX endpoint pages to autogenerated pages defined in your `docs.json`, moves MDX content to the `x-mint` extension in your OpenAPI specification, and updates your navigation. See [Migrating from MDX](/api-playground/migrating-from-mdx) for detailed information.
+
+## Formatting
+
+While developing locally, we recommend using extensions in your IDE to recognize and format `MDX` files.
+
+If you use Cursor, Windsurf, or VS Code, we recommend the [MDX VS Code extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
+
+If you use JetBrains, we recommend the [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) for syntax highlighting, and setting up [Prettier](https://prettier.io/docs/webstorm) for code formatting.
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Error: Could not load the &#x22;sharp&#x22; module using the darwin-arm64 runtime">
+    This may be due to an outdated version of node. Try the following:
+
+    1. Remove the currently-installed version of the mint CLI: `npm uninstall -g mint`
+    2. Upgrade to Node.js.
+    3. Reinstall the mint CLI: `npm install -g mint`
+  </Accordion>
+
+  <Accordion title="Issue: Encountering an unknown error">
+    **Solution**: Go to the root of your device and delete the `~/.mintlify` folder. Afterwards, run `mint dev` again.
+  </Accordion>
+
+  <Accordion title="Error: permission denied">
+    This is due to not having the required permissions to globally install node packages.
+
+    **Solution**: Try running `sudo npm i -g mint`. You will be prompted for your password, which is the one you use to unlock your computer.
+  </Accordion>
+
+  <Accordion title="The local preview doesn't look the same as my docs do on the web">
+    This is likely due to an outdated version of the CLI.
+
+    **Solution:** Run `mint update` to get the latest changes.
+  </Accordion>
+
+  <Accordion title="mintlify vs. mint package">
+    If you have any problems with the CLI package, you should first run `npm ls -g`. This command shows what packages are globally installed on your machine.
+
+    If you don't use npm or don't see it in the -g list, try `which mint` to locate the installation.
+
+    If you have a package named `mint` and a package named `mintlify` installed, you should uninstall `mintlify`.
+
+    1. Uninstall the old package:
+
+    ```bash
+      npm uninstall -g mintlify
+    ```
+
+    2. Clear your npm cache:
+
+    ```bash
+      npm cache clean --force
+    ```
+
+    3. Reinstall the new package:
+
+    ```bash
+    npm i -g mint
+    ```
+  </Accordion>
+</AccordionGroup>

package/docs/getting-started/intro.mdx

@@ -0,0 +1,11 @@
+---
+title: 介绍
+sidebarTitle: 介绍
+---
+
+Xiaozhi Client 是一个开源的MCP聚合工具。
+使用 Xiaozhi Client 你可以将多个 MCP 服务的工具聚合在一起提供给小智接入点。
+
+<Frame>
+  <img src="/images/preview.png" />
+</Frame>

package/docs/getting-started/quickstart.mdx

@@ -0,0 +1,108 @@
+---
+title: 快速上手
+sidebarTitle: 快速上手
+---
+
+快速入门指南将会向你展示最快速的安装、配置、启动方式。
+
+完成本指南后，你将拥有一个可以自由集成不同 MCP 的服务，允许你可有控制提供给小智的 MCP 工具。
+
+<Info>
+  **前期准备**:
+  在开始之前，你至少需要有一个小智硬件设备，并已添加至小智官方服务端。
+</Info>
+
+## 环境准备
+
+请先安装好 node 与 pnpm。
+
+<Info>如果你已经准备好 node & pnpm 可以跳过此步骤</Info>
+
+<Steps>
+  <Step title="安装Node">
+    请前往 [Node官方安装地址](https://nodejs.org/en/download) 进行安装，并验证安装是否成功。
+
+    以下为 node:22(LTS) + pnpm 的安装方式
+    <CodeGroup>
+      ```bash macos / linux
+      # 下载并安装 nvm:
+      curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+
+      # 重启shell
+      \. "$HOME/.nvm/nvm.sh"
+
+      # 下载并安装 Node.js:
+      nvm install 22
+
+      # 验证 Node.js 版本:
+      node -v # 应该打印出 "v22.19.0".
+
+      # 下载并安装 pnpm:
+      corepack enable pnpm
+
+      # 验证 pnpm 版本:
+      pnpm -v
+      ```
+
+      ```bash windows
+      # 下载并安装 Chocolatey:
+      powershell -c "irm https://community.chocolatey.org/install.ps1|iex"
+
+      # 下载并安装 Node.js:
+      choco install nodejs --version="22.19.0"
+
+      # 验证 Node.js 版本:
+      node -v # 应该打印出 "v22.19.0".
+
+      # 下载并安装 pnpm:
+      corepack enable pnpm
+
+      # 验证 pnpm 版本:
+      pnpm -v
+      ```
+    </CodeGroup>
+
+  </Step>
+
+  <Step title="安装 xiaozhi-client 命令行工具">
+    <CodeGroup>
+    ```bash pnpm
+    pnpm install -g xiaozhi-client
+    ```
+
+    ```bash npm
+    npm install -g xiaozhi-client
+    ```
+    </CodeGroup>
+  </Step>
+
+  <Step title="创建应用">
+    ```bash
+    # 创建应用
+    xiaozhi create my-app
+
+    # 进入应用目录
+    cd my-app
+
+    # 安装依赖
+    pnpm install
+    ```
+  </Step>
+
+  <Step title="设置小智接入点">
+    小智AI配置MCP接入点的 [使用说明](https://ccnphfhqs21z.feishu.cn/wiki/HiPEwZ37XiitnwktX13cEM5KnSb)
+    ```bash
+    xiaozhi config set mcpEndpoint "<从小智服务端获取到的接入点地址>"
+    ```
+  </Step>
+
+  <Step title="启动服务">
+    ```bash
+    xiaozhi start
+    ```
+  </Step>
+
+  <Step title="验证是否成功">
+    最后，请前往小智服务端，检查对应的接入点，刷新后是否能获取到工具列表
+  </Step>
+</Steps>

package/docs/reference/command.mdx

@@ -0,0 +1,15 @@
+---
+title: 常用命令
+sidebarTitle: 常用命令
+---
+
+| 命令                                          | 说明                        |
+| --------------------------------------------- | --------------------------- |
+| xiaozhi help                                  | 帮助信息                    |
+| xiaozhi create                                | 创建应用                    |
+| xiaozhi start                                 | 启动服务                    |
+| xiaozhi stop                                  | 停止服务                    |
+| xiaozhi status                                | 查看服务状态                |
+| xiaozhi config mcpEndpoint \<小智接入点地址\> | 设置小智接入点              |
+| xiaozhi mcp list                              | 列出所有 MCP 服务           |
+| xiaozhi mcp list --tools                      | 列出所有正在使用的 MCP 工具 |

package/docs/usage/add-mcp-server.mdx

@@ -0,0 +1,6 @@
+---
+title: 添加 MCP 服务
+sidebarTitle: 添加 MCP 服务
+---
+
+添加 MCP 服务

package/docs/usage/as-a-mcp-server.mdx

@@ -0,0 +1,6 @@
+---
+title: 作为普通 MCP 服务
+sidebarTitle: 作为普通 MCP 服务
+---
+
+作为普通 MCP 服务

package/docs/usage/docker.mdx

@@ -0,0 +1,99 @@
+---
+title: 使用 Docker 部署
+sidebarTitle: 使用 Docker 部署
+---
+
+<Info>
+  **前期准备**:
+  在开始之前，你至少需要有一个小智硬件设备，并已添加至小智官方服务端。并且已准备好
+  Docker 环境
+</Info>
+
+## 安装方式
+
+### 方式一：使用启动脚本（推荐）
+
+<Info>
+  如果你的网络环境无法访问 github ，可以使用 gitee 进行安装
+</Info>
+<CodeGroup>
+  ```bash github
+  # 下载脚本
+  curl -fsSL https://raw.githubusercontent.com/shenjingnan/xiaozhi-client/main/docker-start.sh | bash
+  ```
+
+```bash gitee
+curl -fsSL https://gitee.com/shenjingnan/xiaozhi-client/raw/main/docker-start.sh | bash
+```
+
+</CodeGroup>
+
+### 方式二：使用 Docker Compose
+
+<Steps>
+  <Step title="获取 docker-compose.yml">
+    <CodeGroup>
+      ```bash github
+      curl -O https://raw.githubusercontent.com/shenjingnan/xiaozhi-client/main/docker-compose.yml
+      ```
+
+      ```bash gitee
+      curl -O https://gitee.com/shenjingnan/xiaozhi-client/raw/main/docker-compose.yml
+      ```
+    </CodeGroup>
+
+  </Step>
+
+  <Step title="启动服务">
+    <CodeGroup>
+    ```bash
+    docker-compose up -d
+    ```
+    </CodeGroup>
+  </Step>
+</Steps>
+
+### 方式三：手动启动
+
+<Steps>
+  <Step title="创建挂载点目录">
+    <CodeGroup>
+      ```bash macos / linux
+      mkdir -p ~/xiaozhi-client
+      ```
+    </CodeGroup>
+  </Step>
+
+  <Step title="拉取镜像并启动服务">
+    <CodeGroup>
+    ```bash
+    docker run -d \
+    --name xiaozhi-client \
+    -p 9999:9999 \
+    -v ~/xiaozhi-client:/workspaces \
+    --restart unless-stopped \
+    shenjingnan/xiaozhi-client
+    ```
+    </CodeGroup>
+  </Step>
+</Steps>
+
+## 管理接入点
+
+<Info>
+  在启动容器服务之后，我们需要配置小智接入点，才可以正常使用
+</Info>
+
+<Steps>
+  <Step title="打开管理界面">
+    如果你的容器和你的本机在一起，可以直接使用浏览器打开网址：http://localhost:9999
+    如果你是在单独的设备部署容器，请确保你的电脑和单独的容器设备在同一个局域网，然后打开对应IP地址：http://{容器IP}:9999
+  </Step>
+
+  <Step title="配置小智接入点">
+    TODO
+  </Step>
+  <Step title="重启服务">
+    TODO
+  </Step>
+</Steps>

package/docs/usage/modelscope.mdx

@@ -0,0 +1,6 @@
+---
+title: 使用 魔搭社区 MCP
+sidebarTitle: 使用 魔搭社区 MCP
+---
+
+使用 魔搭社区 MCP

package/docs/usage/web-control.mdx

@@ -0,0 +1,6 @@
+---
+title: 使用网页管理
+sidebarTitle: 使用网页管理
+---
+
+使用网页管理

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xiaozhi-client",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "小智 AI 客户端 命令行工具",
   "type": "module",
   "main": "dist/cli.js",
@@ -25,6 +25,7 @@
     "build:web": "cd web && pnpm install && pnpm run build",
     "dev": "cross-env NODE_ENV=development tsup --watch",
     "test": "vitest run",
+    "test:silent": "vitest run --silent=true",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui",
@@ -37,7 +38,8 @@
     "spell:check": "cspell \"src/**/*.ts\" \"*.md\" \"*.json\"",
     "duplicate:check": "jscpd src/",
     "docker:update-version": "node scripts/update-dockerfile-version.js",
-    "example": "node --loader ts-node/esm"
+    "example": "node --loader ts-node/esm",
+    "docs:dev": "cd docs && mintlify dev"
   },
   "keywords": [
     "xiaozhi",
@@ -61,7 +63,7 @@
     "dotenv": "^17.2.1",
     "eventsource": "^4.0.0",
     "express": "^5.1.0",
-    "hono": "^4.9.6",
+    "hono": "^4.9.7",
     "json5": "^2.2.3",
     "json5-writer": "^0.2.0",
     "jsonc-parser": "^3.3.1",
@@ -90,6 +92,7 @@
     "glob": "^11.0.3",
     "happy-dom": "^18.0.1",
     "jscpd": "^4.0.5",
+    "mintlify": "^4.2.107",
     "release-it": "^19.0.4",
     "semver": "^7.7.2",
     "supertest": "^7.1.4",
@@ -103,7 +106,9 @@
     "overrides": {
       "form-data": "^4.0.4",
       "braces": ">=3.0.3",
-      "micromatch": ">=4.0.8"
+      "micromatch": ">=4.0.8",
+      "axios": ">=1.12.0"
     }
-  }
+  },
+  "packageManager": "pnpm@10.13.1"
 }