xiaozhi-client 1.9.3 → 1.9.4-beta.1

package/docs/mcp-tool-calling.md

@@ -1,363 +0,0 @@
-# xiaozhi mcp call 命令使用说明
-
-## 概述
-
-`xiaozhi mcp call` 命令用于调用已配置的 MCP (Model Context Protocol) 服务中的工具，以及自定义的 customMCP 工具。该命令通过 HTTP API 与后台服务通信，实现对各种 MCP 工具和 customMCP 工具的统一调用接口。
-
-### 支持的工具类型
-
-1. **标准 MCP 工具**：通过 MCP 协议连接的外部服务工具
-2. **customMCP 工具**：在配置文件中直接定义的自定义工具，支持多种处理器类型：
-   - **proxy**：代理调用第三方平台（如 Coze、Dify、n8n）
-   - **http**：直接 HTTP API 调用
-   - **function**：JavaScript 函数执行
-   - **script**：脚本执行（Node.js、Python 等）
-   - **chain**：链式工具调用
-
-## 前置条件
-
-在使用 `xiaozhi mcp call` 命令之前，请确保：
-
-1. **服务已启动**：xiaozhi 后台服务必须正在运行
-   ```bash
-   # 启动后台服务
-   xiaozhi start -d
-
-   # 检查服务状态
-   xiaozhi status
-   ```
-
-2. **MCP 服务已配置**：在配置文件中正确配置了 MCP 服务
-3. **工具已启用**：目标工具未被禁用
-
-## 命令语法
-
-### 标准 MCP 工具调用
-
-```bash
-xiaozhi mcp call <服务名称> <工具名称> [选项]
-```
-
-### customMCP 工具调用
-
-```bash
-xiaozhi mcp call customMCP <工具名称> [选项]
-```
-
-### 参数说明
-
-#### 必需参数
-
-- `<服务名称>`：
-  - 对于标准 MCP 工具：MCP 服务的名称，在配置文件中定义
-  - 对于 customMCP 工具：固定使用 `customMCP`
-- `<工具名称>`：要调用的工具名称
-
-#### 可选参数
-
-- `--args <JSON>`：工具参数，JSON 格式字符串（默认值：`{}`）
-  - customMCP 工具支持基于 JSON Schema 的参数验证
-
-### 选项格式
-
-```bash
---args '{"参数名1": "参数值1", "参数名2": "参数值2"}'
-```
-
-## 使用示例
-
-### 标准 MCP 工具示例
-
-#### 1. 调用计算器工具
-
-```bash
-# 执行简单的数学计算
-xiaozhi mcp call calculator calculator --args '{"javascript_expression": "1+2"}'
-```
-
-**输出示例：**
-```
-✔ calculator/calculator: {"content":[{"type":"text","text":"{\"success\":true,\"result\":3}"}]}
-```
-
-#### 2. 调用日期时间工具
-
-```bash
-# 获取当前日期
-xiaozhi mcp call datetime get_current_date
-
-# 添加时间
-xiaozhi mcp call datetime add_time --args '{"date": "2024-01-01", "days": 7}'
-```
-
-### customMCP 工具示例
-
-#### 3. 调用 Coze 工作流工具
-
-```bash
-# 调用 Coze 工作流进行文本分析
-xiaozhi mcp call customMCP coze_workflow_analyzer --args '{"input": "这是一段需要分析的文本内容"}'
-```
-
-**输出示例：**
-```
-✔ customMCP/coze_workflow_analyzer: {"content":[{"type":"text","text":"分析结果：这是一段中性情感的文本..."}]}
-```
-
-#### 4. 调用 HTTP API 工具
-
-```bash
-# 获取天气信息
-xiaozhi mcp call customMCP weather_api --args '{"city": "北京", "units": "metric"}'
-```
-
-#### 5. 调用函数处理器工具
-
-```bash
-# 文本处理
-xiaozhi mcp call customMCP text_processor --args '{"text": "Hello World", "operation": "uppercase"}'
-```
-
-**输出示例：**
-```
-✔ customMCP/text_processor: {"content":[{"type":"text","text":"HELLO WORLD"}]}
-```
-
-### 复杂参数示例
-
-#### 3. 多参数工具调用
-
-```bash
-# 调用包含多个参数的工具
-xiaozhi mcp call myservice mytool --args '{
-  "param1": "value1",
-  "param2": 123,
-  "param3": true,
-  "param4": ["item1", "item2"]
-}'
-```
-
-#### 4. 嵌套对象参数
-
-```bash
-# 传递嵌套对象作为参数
-xiaozhi mcp call dataservice process --args '{
-  "config": {
-    "format": "json",
-    "options": {
-      "pretty": true,
-      "indent": 2
-    }
-  },
-  "data": ["a", "b", "c"]
-}'
-```
-
-## 常见错误和解决方法
-
-### 1. 服务未启动错误
-
-**错误信息：**
-```
-错误: xiaozhi 服务未启动。请先运行 'xiaozhi start' 或 'xiaozhi start -d' 启动服务。
-```
-
-**解决方法：**
-```bash
-# 启动后台服务
-xiaozhi start -d
-
-# 验证服务状态
-xiaozhi status
-```
-
-### 2. 服务不存在错误
-
-**错误信息：**
-```
-错误: 服务 'nonexistent' 不存在。可用服务: calculator, datetime
-```
-
-**解决方法：**
-- 检查服务名称拼写是否正确
-- 使用 `xiaozhi config show` 查看已配置的服务
-- 确认服务已在配置文件中正确定义
-
-### 3. 工具不存在错误
-
-**错误信息：**
-```
-错误: 工具 'unknown_tool' 在服务 'calculator' 中不存在。可用工具: calculator
-```
-
-**解决方法：**
-- 检查工具名称拼写是否正确
-- 查看服务文档了解可用工具列表
-- 使用正确的工具名称重新调用
-
-### 4. 工具已被禁用错误
-
-**错误信息：**
-```
-错误: 工具 'calculator' 已被禁用。请使用 'xiaozhi mcp tool calculator calculator enable' 启用该工具。
-```
-
-**解决方法：**
-```bash
-# 启用指定工具
-xiaozhi mcp tool calculator calculator enable
-
-# 重新调用工具
-xiaozhi mcp call calculator calculator --args '{"javascript_expression": "1+2"}'
-```
-
-### 5. 参数格式错误
-
-**错误信息：**
-```
-错误: 参数格式错误: Unexpected token...
-```
-
-**解决方法：**
-- 确保 JSON 格式正确
-- 使用单引号包围 JSON 字符串
-- 检查 JSON 中的引号、括号、逗号等语法
-
-**正确格式：**
-```bash
-xiaozhi mcp call service tool --args '{"param": "value"}'
-```
-
-**错误格式：**
-```bash
-xiaozhi mcp call service tool --args {"param": "value"}  # 缺少引号
-xiaozhi mcp call service tool --args '{"param": value}'  # 值缺少引号
-```
-
-### 6. customMCP 工具不存在错误
-
-**错误信息：**
-```
-错误: customMCP 工具 'unknown_tool' 不存在。可用的 customMCP 工具: coze_workflow, text_processor。请使用 'xiaozhi mcp list' 查看所有可用工具。
-```
-
-**解决方法：**
-- 检查工具名称拼写是否正确
-- 使用 `xiaozhi mcp list --tools` 查看所有可用的 customMCP 工具
-- 确认工具已在 `xiaozhi.config.json` 的 `customMCP.tools` 中正确定义
-
-### 7. customMCP 参数验证失败
-
-**错误信息：**
-```
-错误: 参数验证失败: 缺少必需参数: input
-```
-
-**解决方法：**
-- 检查工具的 `inputSchema` 定义，了解必需参数
-- 确保提供所有必需参数
-- 验证参数类型是否正确
-
-**示例：**
-```bash
-# 错误：缺少必需参数
-xiaozhi mcp call customMCP text_processor --args '{}'
-
-# 正确：提供所有必需参数
-xiaozhi mcp call customMCP text_processor --args '{"text": "Hello", "operation": "uppercase"}'
-```
-
-### 8. customMCP 配置错误
-
-**错误信息：**
-```
-错误: customMCP 工具 'my_tool' 配置验证失败。请检查配置文件中的工具定义。
-```
-
-**解决方法：**
-- 检查 `xiaozhi.config.json` 中的 customMCP 配置语法
-- 确认 handler 类型和配置参数正确
-- 验证环境变量是否已设置（如 API 密钥）
-- 参考 [customMCP 配置示例文档](./custom-mcp-handlers-examples.md)
-
-## 相关命令
-
-### 服务管理命令
-
-- `xiaozhi start [-d]`：启动 xiaozhi 服务
-- `xiaozhi stop`：停止 xiaozhi 服务
-- `xiaozhi status`：查看服务状态
-- `xiaozhi restart [-d]`：重启服务
-
-### MCP 相关命令
-
-- `xiaozhi mcp list`：列出所有可用的 MCP 服务和 customMCP 工具
-- `xiaozhi mcp list --tools`：显示详细的工具列表，包括 customMCP 工具
-- `xiaozhi mcp tool <服务名> <工具名> <enable|disable>`：启用或禁用标准 MCP 工具
-- `xiaozhi config show`：查看当前配置，包括 customMCP 配置
-
-## 技术架构说明
-
-`xiaozhi mcp call` 命令采用以下架构：
-
-1. **CLI 命令**：解析用户输入的命令和参数
-2. **HTTP API 调用**：通过 HTTP 请求调用后台服务的 `/api/tools/call` 端点
-3. **后台服务处理**：后台服务管理所有 MCP 连接并执行工具调用
-4. **结果返回**：将工具执行结果格式化后返回给用户
-
-这种架构确保了：
-- CLI 和后台服务的清晰分离
-- 统一的工具调用接口
-- 可靠的错误处理和状态管理
-
-## 最佳实践
-
-### 通用最佳实践
-
-1. **参数验证**：调用前确认参数格式和内容正确
-2. **错误处理**：根据错误信息进行相应的故障排除
-3. **服务监控**：定期检查服务状态确保正常运行
-4. **配置管理**：保持 MCP 服务配置的准确性和时效性
-
-### customMCP 工具最佳实践
-
-1. **配置验证**：
-   - 使用 `xiaozhi mcp list` 验证 customMCP 工具是否正确加载
-   - 定期检查配置文件语法和结构
-   - 确保环境变量正确设置
-
-2. **参数设计**：
-   - 为 customMCP 工具定义清晰的 `inputSchema`
-   - 使用适当的参数类型和验证规则
-   - 提供有意义的参数描述
-
-3. **错误处理**：
-   - 实现适当的超时和重试机制
-   - 为不同的 handler 类型配置合适的错误处理策略
-   - 监控外部 API 调用的成功率
-
-4. **性能优化**：
-   - 合理设置超时时间，避免长时间等待
-   - 对于频繁调用的工具，考虑缓存机制
-   - 监控工具调用的响应时间
-
-5. **安全考虑**：
-   - 使用环境变量存储敏感信息（API 密钥等）
-   - 定期轮换 API 密钥和访问令牌
-   - 限制工具的访问权限和操作范围
-
-## 故障排除检查清单
-
-遇到问题时，请按以下顺序检查：
-
-- [ ] xiaozhi 服务是否正在运行（`xiaozhi status`）
-- [ ] 服务名称和工具名称是否正确
-- [ ] 参数 JSON 格式是否有效
-- [ ] 工具是否已启用
-- [ ] 网络连接是否正常
-- [ ] 配置文件是否正确
-
-如果问题仍然存在，请查看日志文件获取更详细的错误信息：
-```bash
-xiaozhi attach  # 查看实时日志
-```

package/docs/python-dependencies.md

@@ -1,216 +0,0 @@
-# Python 依赖管理指南
-
-xiaozhi-client Docker 容器支持动态 Python 依赖管理，让你可以轻松添加和管理 Python 包，特别适用于 MCP (Model Context Protocol) 服务器开发。
-
-## 🚀 快速开始
-
-### 1. 创建自定义依赖文件
-
-在你的挂载目录（通常是 `~/xiaozhi-client/`）中创建 `requirements.txt` 文件：
-
-```bash
-# 在主机上创建文件
-echo "mcp-proxy>=0.8.2" > ~/xiaozhi-client/requirements.txt
-```
-
-### 2. 重启容器
-
-```bash
-docker restart xiaozhi-client
-```
-
-容器启动时会自动检测并安装新的依赖包。
-
-## 📋 工作原理
-
-### 依赖安装优先级
-
-1. **用户自定义** (`~/xiaozhi-client/requirements.txt`) - 最高优先级
-2. **默认模板** (`docker/templates/requirements.txt`) - 仅在用户未自定义时使用
-
-### 安装流程
-
-容器启动时会按以下顺序执行：
-
-1. 检查 `/workspaces/requirements.txt`（用户自定义文件）
-2. 如果存在且包含有效内容，安装用户依赖
-3. 如果不存在，检查是否需要安装默认依赖
-4. 所有依赖都安装在 Python 虚拟环境中（`/opt/venv`）
-
-## 📝 使用示例
-
-### 示例 1：添加 MCP 相关包
-
-```bash
-# ~/xiaozhi-client/requirements.txt
-mcp-proxy>=0.8.2
-mcp-server-git>=0.1.0
-```
-
-### 示例 2：添加数据科学包
-
-```bash
-# ~/xiaozhi-client/requirements.txt
-numpy>=1.24.0
-pandas>=2.0.0
-matplotlib>=3.7.0
-```
-
-### 示例 3：添加 Web 开发包
-
-```bash
-# ~/xiaozhi-client/requirements.txt
-fastapi>=0.104.0
-uvicorn>=0.24.0
-sqlalchemy>=2.0.0
-```
-
-### 示例 4：完整的 MCP 服务器依赖
-
-```bash
-# ~/xiaozhi-client/requirements.txt
-# MCP 核心
-mcp>=1.13.0
-fastmcp>=2.11.0
-
-# 网络通信
-httpx>=0.27.0
-websockets>=12.0
-
-# 数据处理
-pydantic>=2.11.0
-python-dotenv>=1.0.0
-
-# 自定义包
-mcp-proxy>=0.8.2
-openai>=1.0.0
-```
-
-## 🔧 高级用法
-
-### 版本固定
-
-```bash
-# 固定特定版本
-mcp==1.13.0
-fastmcp==2.11.0
-
-# 版本范围
-httpx>=0.27.0,<1.0.0
-pydantic>=2.11.0,<3.0.0
-```
-
-### 从 Git 安装
-
-```bash
-# 从 GitHub 安装开发版本
-git+https://github.com/user/repo.git
-git+https://github.com/user/repo.git@branch_name
-```
-
-### 可选依赖
-
-```bash
-# 安装包的可选依赖
-fastapi[all]>=0.104.0
-httpx[http2]>=0.27.0
-```
-
-## 🐛 故障排除
-
-### 查看安装日志
-
-容器启动时会显示详细的安装日志：
-
-```bash
-docker logs xiaozhi-client
-```
-
-### 常见问题
-
-#### 1. 依赖安装失败
-
-**症状**：容器启动时显示警告信息
-**解决**：
-- 检查包名拼写是否正确
-- 确认版本号是否存在
-- 查看完整错误日志
-
-#### 2. 包版本冲突
-
-**症状**：安装过程中出现依赖冲突
-**解决**：
-- 使用兼容的版本范围
-- 移除冲突的包
-- 使用虚拟环境隔离
-
-#### 3. 网络连接问题
-
-**症状**：下载包时超时
-**解决**：
-- 容器已配置清华大学 PyPI 镜像源
-- 检查网络连接
-- 重试安装
-
-### 手动安装包
-
-如果需要在运行中的容器内手动安装包：
-
-```bash
-# 进入容器
-docker exec -it xiaozhi-client bash
-
-# 激活虚拟环境并安装
-source /opt/venv/bin/activate
-pip install package_name
-```
-
-## 📚 默认预装包
-
-容器默认包含以下 MCP 开发常用包：
-
-- `mcp` - 官方 MCP Python SDK
-- `fastmcp` - 高级 MCP 框架
-- `httpx` - 现代 HTTP 客户端
-- `websockets` - WebSocket 支持
-- `pydantic` - 数据验证
-- `python-dotenv` - 环境变量管理
-- `aiofiles` - 异步文件操作
-
-完整列表请查看 `docker/templates/requirements.txt`。
-
-## 🔄 更新依赖
-
-### 更新单个包
-
-```bash
-# 修改 requirements.txt 中的版本号
-mcp>=1.14.0  # 从 1.13.0 更新到 1.14.0
-
-# 重启容器
-docker restart xiaozhi-client
-```
-
-### 批量更新
-
-```bash
-# 在容器内手动更新
-docker exec -it xiaozhi-client bash
-source /opt/venv/bin/activate
-pip install --upgrade -r requirements.txt
-```
-
-## 💡 最佳实践
-
-1. **版本管理**：使用版本范围而不是固定版本，确保兼容性
-2. **依赖分组**：在 requirements.txt 中使用注释分组相关依赖
-3. **测试验证**：添加新依赖后测试 MCP 服务器功能
-4. **备份配置**：定期备份 requirements.txt 文件
-5. **最小化原则**：只安装必需的包，避免臃肿
-
-## 🔗 相关链接
-
-- [MCP 官方文档](https://modelcontextprotocol.io/)
-- [FastMCP 文档](https://gofastmcp.com/)
-- [Python 包索引 (PyPI)](https://pypi.org/)
-- [pip 用户指南](https://pip.pypa.io/en/stable/user_guide/)

package/docs/reference/command.mdx

@@ -1,15 +0,0 @@
----
-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

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

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

@@ -1,76 +0,0 @@
----
-title: 接入到 MCP 客户端
-sidebarTitle: 接入到 MCP 客户端
----
-
-<Note>
-xiaozhi-client 不仅可以连接小智服务端接入点，还可以作为普通 MCP 服务被其他客户端集成。
-</Note>
-
-## 准备工作
-
-首先，你需要先启动服务
-
-```bash
-xiaozhi start
-```
-
-<Note>服务启动后，你可以使用以下配置添加到你的MCP客户端中</Note>
-
-```json mcpServer
-{
-  "mcpServers": {
-    "xiaozhi-client": {
-      "type": "streamableHttp",
-      "url": "http://localhost:9999/mcp"
-    }
-  }
-}
-```
-
-## 接入到 Cherry Studio 中
-
-<Steps>
-  <Step title="配置 MCP 服务">
-    <Frame caption="第一步：打开 cherry-studio 中的 添加 MCP 服务弹窗">
-      <img src="/images/add-to-cherry-studio/step-1.png" alt="第一步：打开 cherry-studio 中的 添加 MCP 服务弹窗" />
-    </Frame>
-    <br />
-    <Frame caption="第二步：添加 MCP 并点击 确定 按钮">
-  <img src="/images/add-to-cherry-studio/step-2.png" alt="第二步：添加 MCP 并点击 确定 按钮" />
-</Frame>
-<br />
-    <Frame caption="添加成功后 xiaozhi-client 会出现在 MCP 列表中">
-  <img src="/images/add-to-cherry-studio/step-3.png" alt="添加成功后 xiaozhi-client 会出现在 MCP 列表中" />
-</Frame>
-</Step>
-
-  <Step title="测试效果">
-    <Frame caption="第一步：在 cherry-studio 的聊天界面添加 xiaozhi-client MCP">
-      <img src="/images/add-to-cherry-studio/step-4.png" alt="第一步：在 cherry-studio 的聊天界面添加 xiaozhi-client MCP" />
-    </Frame>
-    <br />
-    <Frame caption="第二步：在聊天界面输入问题，并点击 发送 按钮">
-      <img src="/images/add-to-cherry-studio/step-5.png" alt="第二步：在聊天界面输入问题，并点击 发送 按钮" />
-    </Frame>
-  </Step>
-</Steps>
-
-## 接入到 Cursor 中
-<Steps>
-  <Step title="配置 MCP 服务">
-    <Frame caption="第一步：打开 cursor 的 MCP 配置界面">
-      <img src="/images/add-to-cursor/step-1.png" alt="第一步：打开 cursor 的 MCP 配置界面" />
-    </Frame>
-    <br />
-    <Frame caption="第二步：添加 xiaozhi-client MCP">
-      <img src="/images/add-to-cursor/step-2.png" alt="第二步：添加 xiaozhi-client MCP" />
-    </Frame>
-  </Step>
-
-  <Step title="测试效果">
-    <Frame caption="在 cursor 的聊天界面输入问题，并点击 发送 按钮">
-      <img src="/images/add-to-cursor/step-3.png" alt="在 cursor 的聊天界面输入问题，并点击 发送 按钮" />
-    </Frame>
-  </Step>
-</Steps>