xiaozhi-client 1.9.2 → 1.9.3-beta.1

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xiaozhi-client",
-  "version": "1.9.2",
+  "version": "1.9.3-beta.1",
   "description": "小智 AI 客户端 命令行工具",
   "repository": {
     "type": "git",
@@ -33,25 +33,28 @@
     "xiaozhi-client": "dist/cli.js"
   },
   "scripts": {
-    "build": "pnpm run build:web && cross-env NODE_ENV=production tsup",
+    "build": "pnpm run build:packages && pnpm run build:web && cross-env NODE_ENV=production tsup --config config/tsup.config.ts",
+    "build:packages": "pnpm --filter './packages/*' run build",
     "build:web": "cd apps/frontend && 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",
-    "format": "biome format --write .",
-    "lint": "biome lint --write .",
-    "type:check": "tsc --project tsconfig.typecheck.json",
-    "check": "biome check .",
-    "check:fix": "biome check --write --unsafe .",
+    "dev": "pnpm run build:packages && cross-env NODE_ENV=development tsup --config config/tsup.config.ts --watch",
+    "test": "vitest run --config config/vitest.config.ts",
+    "test:silent": "vitest run --silent=true --config config/vitest.config.ts",
+    "test:watch": "vitest --config config/vitest.config.ts",
+    "test:coverage": "vitest run --coverage --config config/vitest.config.ts",
+    "test:ui": "vitest --ui --config config/vitest.config.ts",
+    "format": "biome format --write --config-path=config/biome.json .",
+    "lint": "biome lint --write --config-path=config/biome.json .",
+    "type:check": "tsc --project config/tsconfig.typecheck.json",
+    "check": "biome check --config-path=config/biome.json .",
+    "check:fix": "biome check --write --unsafe --config-path=config/biome.json .",
     "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",
+    "spell:check": "cspell --config config/cspell.json .",
+    "duplicate:check": "jscpd apps/backend/",
+    "docker:update-version": "node docker/scripts/update-version.js",
     "example": "node --loader ts-node/esm",
-    "docs:dev": "cd docs && mintlify dev"
+    "docs:dev": "cd docs && mintlify dev",
+    "release": "npx release-it --config config/release-it.json",
+    "release:dry": "npx release-it --config config/release-it.json --dry-run"
   },
   "dependencies": {
     "@hono/node-server": "^1.17.1",
@@ -116,7 +119,11 @@
       "axios": ">=1.12.0",
       "@conventional-changelog/git-client": ">=2.0.0",
       "vite@>=7.1.0 <=7.1.10": ">=7.1.11",
-      "hono@>=1.1.0 <4.10.3": ">=4.10.3"
+      "hono@>=1.1.0 <4.10.3": ">=4.10.3",
+      "js-yaml@<4.1.1": ">=4.1.1",
+      "esbuild@<=0.24.2": ">=0.25.0",
+      "glob@>=10.2.0 <10.5.0": ">=10.5.0",
+      "glob@>=11.0.0 <11.1.0": ">=11.1.0"
     }
   },
   "packageManager": "pnpm@10.13.1"

package/docs/arch/{cache.md → cache.mdx}

@@ -1,3 +1,11 @@
+---
+title: MCP 缓存机制开发者指南
+description: 详细介绍了 xiaozhi-client 项目中 MCP 服务工具列表的缓存机制
+sidebar_position: 5
+---
+
+import { Mermaid } from '@theme/Mermaid';
+
 # MCP 缓存机制开发者指南
 
 ## 概述
@@ -36,24 +44,7 @@
 
 ### 缓存数据的生命周期管理
 
-```mermaid
-graph TD
-    A[服务启动] --> B{缓存文件存在?}
-    B -->|否| C[创建初始缓存]
-    B -->|是| D[加载现有缓存]
-    C --> E[连接 MCP 服务]
-    D --> F{缓存有效?}
-    F -->|是| G[使用缓存数据]
-    F -->|否| E
-    E --> H{连接成功?}
-    H -->|是| I[获取工具列表]
-    H -->|否| J[记录错误日志]
-    I --> K[写入缓存]
-    K --> L[更新元数据]
-    G --> M[服务就绪]
-    L --> M
-    J --> N[降级处理]
-```
+<Mermaid chart={`graph TD A[服务启动] --> B{缓存文件存在?} B -->|否| C[创建初始缓存] B -->|是| D[加载现有缓存] C --> E[连接 MCP 服务] D --> F{缓存有效?} F -->|是| G[使用缓存数据] F -->|否| E E --> H{连接成功?} H -->|是| I[获取工具列表] H -->|否| J[记录错误日志] I --> K[写入缓存] K --> L[更新元数据] G --> M[服务就绪] L --> M J --> N[降级处理]`} />
 
 ## 工作流程说明
 
@@ -61,30 +52,7 @@ graph TD
 
 从 MCP 服务启动到缓存写入的完整流程：
 
-```mermaid
-sequenceDiagram
-    participant U as 用户
-    participant SM as MCPServiceManager
-    participant CM as MCPCacheManager
-    participant MS as MCPService
-    participant CF as 缓存文件
-
-    U->>SM: xiaozhi start
-    SM->>CM: 初始化缓存管理器
-    CM->>CF: 检查缓存文件存在性
-
-    loop 每个 MCP 服务
-        SM->>MS: 启动服务
-        MS->>MS: 连接 MCP 服务
-        MS->>MS: 获取工具列表
-        MS->>SM: 返回工具列表
-        SM->>CM: writeCacheEntry()
-        CM->>CF: 原子写入缓存数据
-        CM->>SM: 写入完成确认
-    end
-
-    SM->>U: 所有服务启动完成
-```
+<Mermaid chart={`sequenceDiagram participant U as 用户 participant SM as MCPServiceManager participant CM as MCPCacheManager participant MS as MCPService participant CF as 缓存文件 U->>SM: xiaozhi start SM->>CM: 初始化缓存管理器 CM->>CF: 检查缓存文件存在性 loop 每个 MCP 服务 SM->>MS: 启动服务 MS->>MS: 连接 MCP 服务 MS->>MS: 获取工具列表 MS->>SM: 返回工具列表 SM->>CM: writeCacheEntry() CM->>CF: 原子写入缓存数据 CM->>SM: 写入完成确认 end SM->>U: 所有服务启动完成`} />
 
 ### 缓存文件的创建、更新、验证过程
 
@@ -105,7 +73,7 @@ sequenceDiagram
 
 #### 验证过程
 
-1. **格式验证**: 使用 JSON Schema 验证缓存文件结构
+1. **格式验证**: 使用 TypeScript 类型检查验证缓存文件结构
 2. **数据完整性检查**: 验证必要字段的存在和类型
 3. **版本兼容性**: 检查缓存文件版本与当前代码的兼容性
 4. **哈希验证**: 比较配置哈希以检测配置变更
@@ -235,9 +203,9 @@ export class MCPServiceManager {
 
 ## 数据结构详解
 
-### JSON Schema 完整结构
+### 缓存文件结构
 
-缓存文件遵循以下 JSON Schema 结构：
+缓存文件遵循以下 JSON 结构：
 
 ```json
 {
@@ -259,6 +227,32 @@ export class MCPServiceManager {
 }
 ```
 
+对应的 TypeScript 接口定义如下：
+
+```typescript
+interface MCPToolsCache {
+  version: string;
+  mcpServers: {
+    [serverName: string]: MCPToolsCacheEntry;
+  };
+  metadata: CacheMetadata;
+}
+
+interface MCPToolsCacheEntry {
+  tools: Tool[];
+  lastUpdated: string;
+  serverConfig: MCPServiceConfig;
+  configHash: string;
+  version: string;
+}
+
+interface CacheMetadata {
+  lastGlobalUpdate: string;
+  totalWrites: number;
+  createdAt: string;
+}
+```
+
 ### 各字段的作用和约束条件
 
 #### 版本字段 (`version`)
@@ -351,16 +345,21 @@ private generateConfigHash(config: MCPServiceConfig): string {
    }
    ```
 
-2. **更新 JSON Schema**
+2. **更新验证函数**
 
-   ```json
-   {
-     "properties": {
-       "newField": {
-         "type": "string",
-         "description": "新字段的描述"
-       }
-     }
+   ```typescript
+   private validateCacheStructure(cache: any): cache is MCPToolsCache {
+     return (
+       cache &&
+       typeof cache === "object" &&
+       typeof cache.version === "string" &&
+       typeof cache.mcpServers === "object" &&
+       cache.metadata &&
+       typeof cache.metadata === "object" &&
+       typeof cache.metadata.lastGlobalUpdate === "string" &&
+       typeof cache.metadata.totalWrites === "number" &&
+       typeof cache.metadata.createdAt === "string"
+     );
    }
    ```
 
@@ -390,17 +389,6 @@ private generateConfigHash(config: MCPServiceConfig): string {
    }
    ```
 
-2. **更新 Schema 验证规则**
-   ```json
-   {
-     "newField": {
-       "type": "string",
-       "minLength": 1,
-       "pattern": "^[a-zA-Z0-9_-]+$"
-     }
-   }
-   ```
-
 ### 修改缓存结构的步骤和注意事项
 
 #### 步骤清单
@@ -424,22 +412,7 @@ private generateConfigHash(config: MCPServiceConfig): string {
    private readonly CACHE_VERSION = "2.0.0";
    ```
 
-3. **更新 JSON Schema**
-
-   ```json
-   {
-     "version": "2.0.0",
-     "properties": {
-       "newField": {
-         "type": "string",
-         "description": "新字段描述"
-       }
-     },
-     "required": ["existingFields", "newField"]
-   }
-   ```
-
-4. **实现向后兼容**
+3. **实现向后兼容**
 
    ```typescript
    private migrateCache(cache: any): MCPToolsCache {
@@ -454,7 +427,7 @@ private generateConfigHash(config: MCPServiceConfig): string {
    }
    ```
 
-5. **更新测试用例**
+4. **更新测试用例**
 
    ```typescript
    it("应该支持新字段", async () => {
@@ -477,7 +450,7 @@ private generateConfigHash(config: MCPServiceConfig): string {
 - **版本兼容性**: 主版本号变更表示不兼容的结构变更
 - **数据迁移**: 提供从旧版本到新版本的迁移逻辑
 - **测试覆盖**: 确保新功能有完整的测试覆盖
-- **文档更新**: 同步更新 Schema 文档和使用说明
+- **文档更新**: 同步更新接口文档和使用说明
 
 ### 代码贡献的最佳实践
 
@@ -705,16 +678,11 @@ describe("MCPCacheManager", () => {
    cat xiaozhi.cache.json | jq . || echo "JSON 格式错误"
    ```
 
-3. 检查 Schema 文件是否存在
-   ```bash
-   ls -la xiaozhi.cache.schema.json
-   ```
-
 **解决方案**:
 
 - 删除损坏的缓存文件，重新生成
-- 更新 Schema 文件到最新版本
 - 检查缓存文件中的时间戳格式
+- 确保所有必需字段都存在
 
 #### 问题 3: 配置变更未检测到
 
@@ -880,7 +848,7 @@ xiaozhi 的 MCP 缓存机制通过智能的数据缓存和配置变更检测，
 
 ## 版本兼容性
 
-当前 Schema 版本: `1.0.0`
+当前缓存文件格式版本: `1.0.0`
 
 ### 版本升级策略
 
@@ -890,9 +858,8 @@ xiaozhi 的 MCP 缓存机制通过智能的数据缓存和配置变更检测，
 
 ## 相关文件
 
-- `xiaozhi.cache.schema.json`: JSON Schema 定义文件
 - `src/services/MCPCacheManager.ts`: 缓存管理器实现
-- `xiaozhi.cache.json`: 实际的缓存文件
+- `xiaozhi.cache.json`: 实际的缓存文件（运行时生成）
 
 ## 注意事项
 
@@ -907,12 +874,12 @@ xiaozhi 的 MCP 缓存机制通过智能的数据缓存和配置变更检测，
 
 1. **时间格式错误**: 确保时间戳符合 YYYY-MM-DD HH:mm:ss 格式
 2. **缺少必需字段**: 检查所有必需字段是否存在
-3. **类型不匹配**: 确保字段类型与 Schema 定义一致
+3. **类型不匹配**: 确保字段类型与接口定义一致
 4. **格式不符**: 检查版本号、哈希值等格式是否正确
 
 ### 修复建议
 
 1. 使用 `jq` 工具检查 JSON 格式和内容
-2. 参考示例文件修正格式问题
+2. 参考接口定义修正格式问题
 3. 重新生成缓存文件（删除现有文件，重启服务）
-4. 检查 MCPCacheManager 的实现逻辑
+4. 检查 MCPCacheManager 的实现逻辑