npm - xiaozhi-client - Versions diffs - 1.9.3 → 1.9.4-beta.1 - Mend

xiaozhi-client 1.9.3 → 1.9.4-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (138) hide show

package/docs/arch/cache.mdx DELETED Viewed

@@ -1,885 +0,0 @@
----
-title: MCP 缓存机制开发者指南
-description: 详细介绍了 xiaozhi-client 项目中 MCP 服务工具列表的缓存机制
-sidebar_position: 5
----
-import { Mermaid } from '@theme/Mermaid';
-# MCP 缓存机制开发者指南
-## 概述
-本文档面向希望参与 xiaozhi-client 项目开发的贡献者，详细介绍了 MCP (Model Context Protocol) 服务工具列表的缓存机制。该缓存机制旨在优化 MCP 服务的启动性能，减少重复的服务连接和工具列表获取操作。
-## 缓存机制核心原理
-### 设计目标
-1. **性能优化**: 减少 MCP 服务启动时的连接和工具获取时间
-2. **用户体验**: 提升服务启动速度，减少用户等待时间
-3. **系统稳定性**: 降低频繁连接对 MCP 服务的压力
-4. **数据一致性**: 确保缓存数据与实际服务状态保持同步
-### 解决的问题
-- **启动延迟**: 每次启动都需要重新连接所有 MCP 服务
-- **网络依赖**: 网络问题可能导致服务启动失败
-- **资源消耗**: 频繁的服务连接消耗系统资源
-- **用户等待**: 长时间的启动过程影响用户体验
-### 缓存写入的触发时机
-1. **MCP 服务连接成功后**: 每当 MCP 服务成功连接并获取到工具列表时
-2. **工具列表变更时**: 检测到服务提供的工具列表发生变化时
-3. **服务配置变更时**: 服务的配置参数（command、args、env 等）发生变更时
-4. **缓存文件不存在时**: 首次启动或缓存文件被删除后的重新创建
-### 缓存写入条件
-- **服务连接状态**: 只有在服务成功连接的情况下才会写入缓存
-- **工具列表有效性**: 确保获取到的工具列表不为空且格式正确
-- **配置完整性**: 服务配置必须包含必要的字段和有效值
-- **文件系统权限**: 确保对缓存文件目录有写入权限
-### 缓存数据的生命周期管理
-<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[降级处理]`} />
-## 工作流程说明
-### 完整流程图
-从 MCP 服务启动到缓存写入的完整流程：
-<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: 所有服务启动完成`} />
-### 缓存文件的创建、更新、验证过程
-#### 创建过程
-1. **初始化检查**: `MCPCacheManager.ensureCacheFile()` 检查缓存文件是否存在
-2. **创建初始结构**: 如果不存在，创建包含基本元数据的空缓存文件
-3. **设置权限**: 确保缓存文件具有适当的读写权限
-#### 更新过程
-1. **加载现有缓存**: 读取并解析现有的缓存文件
-2. **验证数据完整性**: 检查缓存文件格式和必要字段
-3. **生成配置哈希**: 为当前服务配置生成 SHA256 哈希值
-4. **创建缓存条目**: 构建包含工具列表、配置和元数据的缓存条目
-5. **原子写入**: 使用临时文件确保写入操作的原子性
-6. **更新元数据**: 增加写入计数，更新时间戳
-#### 验证过程
-1. **格式验证**: 使用 TypeScript 类型检查验证缓存文件结构
-2. **数据完整性检查**: 验证必要字段的存在和类型
-3. **版本兼容性**: 检查缓存文件版本与当前代码的兼容性
-4. **哈希验证**: 比较配置哈希以检测配置变更
-### 与 MCPServiceManager 的集成方式
-#### 集成架构
-```typescript
-// MCPServiceManager 中的集成
-export class MCPServiceManager {
-  private cacheManager: MCPCacheManager; // 缓存管理器实例
-  constructor(configs?: Record<string, MCPServiceConfig>) {
-    this.cacheManager = new MCPCacheManager();
-    // ... 其他初始化
-  }
-  // 在工具缓存刷新时写入缓存
-  private async refreshToolsCache(): Promise<void> {
-    // ... 获取工具列表逻辑
-    // 写入缓存
-    await this.cacheManager.writeCacheEntry(serviceName, tools, config);
-    // ... 其他处理逻辑
-  }
-}
-```
-#### 集成要点
-1. **单例模式**: `MCPCacheManager` 作为 `MCPServiceManager` 的私有成员
-2. **异步操作**: 缓存写入采用异步方式，不阻塞主流程
-3. **错误隔离**: 缓存操作失败不影响服务的正常启动
-4. **日志记录**: 详细记录缓存操作的成功和失败情况
-## 缓存应用场景
-### 项目中使用缓存机制的模块
-1. **MCPServiceManager**: 主要的缓存写入模块
-   - 在 `refreshToolsCache()` 方法中写入缓存
-   - 管理多个 MCP 服务的缓存数据
-2. **配置管理系统**: 间接受益于缓存机制
-   - 减少配置文件的频繁更新
-   - 提升配置加载速度
-3. **Web 界面**: 通过更快的服务启动改善用户体验
-   - 减少页面加载等待时间
-   - 提升工具列表显示速度
-### 缓存机制在不同场景下的行为差异
-#### 正常启动场景
-- **首次启动**: 创建缓存文件，连接所有服务，写入工具列表
-- **后续启动**: 加载缓存文件，验证有效性，按需更新
-#### 配置变更场景
-- **服务配置修改**: 检测配置哈希变化，重新连接服务，更新缓存
-- **新增服务**: 为新服务创建缓存条目
-- **删除服务**: 保留缓存条目但标记为无效
-#### 异常情况场景
-- **缓存文件损坏**: 重新创建缓存文件，记录警告日志
-- **服务连接失败**: 保持旧缓存数据，记录错误信息
-- **磁盘空间不足**: 跳过缓存写入，不影响服务启动
-### 缓存失效和降级策略
-#### 缓存失效条件
-1. **配置变更检测**
-   ```typescript
-   // 配置哈希比较
-   const currentHash = generateConfigHash(currentConfig);
-   const cachedHash = cacheEntry.configHash;
-   if (currentHash !== cachedHash) {
-     // 配置已变更，缓存失效
-     await invalidateCache(serverName);
-   }
-   ```
-2. **时间过期检测**
-   ```typescript
-   // 检查缓存年龄（当前实现中暂未启用时间过期）
-   const cacheAge = Date.now() - new Date(cacheEntry.lastUpdated).getTime();
-   const maxAge = 24 * 60 * 60 * 1000; // 24小时
-   if (cacheAge > maxAge) {
-     // 缓存过期
-     return false;
-   }
-   ```
-3. **数据完整性检查**
-   ```typescript
-   // 验证缓存数据结构
-   if (!cacheEntry.tools || cacheEntry.tools.length === 0) {
-     // 数据不完整
-     return false;
-   }
-   ```
-#### 降级策略
-1. **优雅降级**: 缓存操作失败时不影响主流程
-   ```typescript
-   try {
-     await this.cacheManager.writeCacheEntry(serverName, tools, config);
-   } catch (error) {
-     // 记录警告但继续执行
-     this.logger.warn(`缓存写入失败: ${error.message}`);
-   }
-   ```
-2. **错误隔离**: 单个服务的缓存问题不影响其他服务
-3. **自动恢复**: 下次启动时自动重试缓存操作
-## 数据结构详解
-### 缓存文件结构
-缓存文件遵循以下 JSON 结构：
-```json
-{
-  "version": "1.0.0",
-  "mcpServers": {
-    "服务名称": {
-      "tools": [...],
-      "lastUpdated": "YYYY-MM-DD HH:mm:ss 时间戳",
-      "serverConfig": {...},
-      "configHash": "SHA256 哈希值",
-      "version": "1.0.0"
-    }
-  },
-  "metadata": {
-    "lastGlobalUpdate": "YYYY-MM-DD HH:mm:ss 时间戳",
-    "totalWrites": 数字,
-    "createdAt": "YYYY-MM-DD HH:mm:ss 时间戳"
-  }
-}
-```
-对应的 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`)
-- **作用**: 标识缓存文件格式版本，用于兼容性检查
-- **约束**: 必须符合语义化版本格式 (`x.y.z`)
-- **示例**: `"1.0.0"`
-#### 服务器字段 (`mcpServers`)
-- **作用**: 存储各个 MCP 服务的缓存数据
-- **约束**: 键名只能包含字母、数字、下划线和连字符
-- **结构**: 每个服务包含工具列表、配置快照和元数据
-#### 工具列表 (`tools`)
-- **作用**: 缓存服务提供的工具定义
-- **约束**: 每个工具必须有唯一的名称
-- **格式**: 符合 MCP Tool 接口规范
-#### 配置哈希 (`configHash`)
-- **作用**: 快速检测服务配置是否发生变更
-- **约束**: 64 位十六进制字符串 (SHA256)
-- **生成**: 基于服务配置的 JSON 字符串计算
-#### 时间戳字段
-- **作用**: 记录缓存的创建和更新时间
-- **约束**: 必须符合 YYYY-MM-DD HH:mm:ss 格式
-- **示例**: `"2025-09-01 12:39:21"`
-### 配置哈希的生成和验证机制
-#### 哈希生成算法
-```typescript
-private generateConfigHash(config: MCPServiceConfig): string {
-  try {
-    return createHash("sha256")
-      .update(JSON.stringify(config))
-      .digest("hex");
-  } catch (error) {
-    this.logger.warn(`生成配置哈希失败: ${error.message}`);
-    return "";
-  }
-}
-```
-#### 验证机制
-1. **配置变更检测**
-   ```typescript
-   const currentHash = this.generateConfigHash(currentConfig);
-   const cachedHash = cacheEntry.configHash;
-   if (currentHash !== cachedHash) {
-     // 配置已变更，需要重新获取工具列表
-     return false;
-   }
-   ```
-2. **哈希完整性检查**
-   ```typescript
-   if (!cacheEntry.configHash || cacheEntry.configHash.length !== 64) {
-     // 哈希值无效
-     return false;
-   }
-   ```
-## 开发指南
-### 如何扩展缓存功能
-#### 添加新的缓存字段
-1. **更新接口定义**
-   ```typescript
-   // 在 MCPCacheManager.ts 中
-   export interface MCPToolsCacheEntry {
-     tools: Tool[];
-     lastUpdated: string;
-     serverConfig: MCPServiceConfig;
-     configHash: string;
-     version: string;
-     // 添加新字段
-     newField?: string;
-   }
-   ```
-2. **更新验证函数**
-   ```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"
-     );
-   }
-   ```
-3. **更新写入逻辑**
-   ```typescript
-   const cacheEntry: MCPToolsCacheEntry = {
-     // ... 现有字段
-     newField: "新字段的值",
-   };
-   ```
-#### 添加新的验证规则
-1. **扩展验证函数**
-   ```typescript
-   private validateCacheStructure(cache: any): cache is MCPToolsCache {
-     return (
-       // ... 现有验证
-       && this.validateNewField(cache.newField)
-     );
-   }
-   private validateNewField(field: any): boolean {
-     // 新字段的验证逻辑
-     return typeof field === "string" && field.length > 0;
-   }
-   ```
-### 修改缓存结构的步骤和注意事项
-#### 步骤清单
-1. **评估影响范围**
-   - 确定修改是否为破坏性变更
-   - 评估对现有缓存文件的兼容性影响
-   - 制定版本升级策略
-2. **更新数据结构**
-   ```typescript
-   // 1. 更新 TypeScript 接口
-   export interface MCPToolsCacheEntry {
-     // ... 现有字段
-     newField: string; // 新增字段
-   }
-   // 2. 更新版本号（如果是破坏性变更）
-   private readonly CACHE_VERSION = "2.0.0";
-   ```
-3. **实现向后兼容**
-   ```typescript
-   private migrateCache(cache: any): MCPToolsCache {
-     if (cache.version === "1.0.0") {
-       // 从 v1.0.0 迁移到 v2.0.0
-       cache.version = "2.0.0";
-       for (const entry of Object.values(cache.mcpServers)) {
-         entry.newField = "defaultValue";
-       }
-     }
-     return cache;
-   }
-   ```
-4. **更新测试用例**
-   ```typescript
-   it("应该支持新字段", async () => {
-     const mockConfig = {
-       /* ... */
-     };
-     const mockTools = [
-       /* ... */
-     ];
-     await cacheManager.writeCacheEntry("test", mockTools, mockConfig);
-     const cache = JSON.parse(readFileSync(testCachePath, "utf8"));
-     expect(cache.mcpServers.test.newField).toBeDefined();
-   });
-   ```
-#### 注意事项
-- **版本兼容性**: 主版本号变更表示不兼容的结构变更
-- **数据迁移**: 提供从旧版本到新版本的迁移逻辑
-- **测试覆盖**: 确保新功能有完整的测试覆盖
-- **文档更新**: 同步更新接口文档和使用说明
-### 代码贡献的最佳实践
-#### 开发流程
-1. **Fork 和 Clone**
-   ```bash
-   git clone https://github.com/your-username/xiaozhi-client.git
-   cd xiaozhi-client
-   pnpm install
-   ```
-2. **创建功能分支**
-   ```bash
-   git checkout -b feature/cache-enhancement
-   ```
-3. **开发和测试**
-   ```bash
-   # 运行缓存相关测试
-   pnpm test src/services/__tests__/MCPCacheManager.test.ts
-   # 运行完整测试套件
-   pnpm test
-   # 代码质量检查
-   pnpm check:fix
-   ```
-4. **验证功能**
-   ```bash
-   # 构建项目
-   pnpm build
-   # 在测试环境验证
-   cd tmp/hello-world
-   xiaozhi start
-   # 验证缓存文件格式
-   cat xiaozhi.cache.json | jq .
-   ```
-#### 代码规范
-- **TypeScript**: 使用严格的类型定义
-- **错误处理**: 所有缓存操作都应有适当的错误处理
-- **日志记录**: 使用统一的日志格式和级别
-- **测试覆盖**: 新功能必须有对应的单元测试
-- **文档更新**: 修改接口时同步更新文档
-## 测试和调试
-### 单元测试的运行方法
-#### 运行特定测试文件
-```bash
-# 只运行缓存管理器测试
-pnpm test src/services/__tests__/MCPCacheManager.test.ts
-# 运行所有服务相关测试
-pnpm test src/services/__tests__/
-# 运行测试并显示覆盖率
-pnpm test --coverage src/services/__tests__/MCPCacheManager.test.ts
-```
-#### 测试用例结构
-```typescript
-describe("MCPCacheManager", () => {
-  let cacheManager: MCPCacheManager;
-  let testCachePath: string;
-  beforeEach(() => {
-    // 设置测试环境
-    cacheManager = new MCPCacheManager();
-    testCachePath = "/tmp/test-cache.json";
-  });
-  afterEach(() => {
-    // 清理测试文件
-    if (existsSync(testCachePath)) {
-      unlinkSync(testCachePath);
-    }
-  });
-  describe("writeCacheEntry", () => {
-    it("应该成功写入缓存条目", async () => {
-      // 测试逻辑
-    });
-  });
-});
-```
-### 缓存功能的手动测试步骤
-#### 基础功能测试
-1. **缓存文件创建测试**
-   ```bash
-   # 删除现有缓存文件
-   rm xiaozhi.cache.json
-   # 启动服务，观察缓存文件是否创建
-   xiaozhi start
-   # 验证缓存文件存在且格式正确
-   ls -la xiaozhi.cache.json
-   cat xiaozhi.cache.json | jq .
-   ```
-2. **缓存写入测试**
-   ```bash
-   # 启动服务并观察日志
-   xiaozhi start
-   # 查找缓存相关日志
-   # 应该看到类似以下的日志：
-   # [CacheManager] 缓存写入成功: calculator, 工具数量: 1
-   # [CacheManager] 缓存写入成功: datetime, 工具数量: 4
-   ```
-3. **配置变更检测测试**
-   ```bash
-   # 修改服务配置
-   # 编辑 xiaozhi.config.json，修改某个服务的 command 或 args
-   # 重新启动服务
-   xiaozhi start
-   # 观察是否检测到配置变更并更新缓存
-   # 检查缓存文件中的 configHash 是否发生变化
-   ```
-#### 异常情况测试
-1. **缓存文件损坏测试**
-   ```bash
-   # 故意损坏缓存文件
-   echo "invalid json" > xiaozhi.cache.json
-   # 启动服务，观察是否能自动恢复
-   xiaozhi start
-   # 验证缓存文件是否被重新创建
-   cat xiaozhi.cache.json | jq .
-   ```
-2. **权限问题测试**
-   ```bash
-   # 设置缓存文件为只读
-   chmod 444 xiaozhi.cache.json
-   # 启动服务，观察错误处理
-   xiaozhi start
-   # 检查日志中是否有适当的警告信息
-   # 恢复权限
-   chmod 644 xiaozhi.cache.json
-   ```
-3. **磁盘空间不足测试**
-   ```bash
-   # 在测试环境中模拟磁盘空间不足
-   # 观察缓存写入失败时的行为
-   # 确保服务仍能正常启动
-   ```
-### 常见问题的排查和解决方案
-#### 问题 1: 缓存文件未创建
-**症状**: 启动服务后没有生成 `xiaozhi.cache.json` 文件
-**排查步骤**:
-1. 检查当前目录权限
-   ```bash
-   ls -la .
-   ```
-2. 检查环境变量设置
-   ```bash
-   echo $XIAOZHI_CONFIG_DIR
-   ```
-3. 查看详细日志
-   ```bash
-   xiaozhi start --verbose
-   ```
-**解决方案**:
-- 确保当前目录有写入权限
-- 检查 `XIAOZHI_CONFIG_DIR` 环境变量是否正确设置
-- 查看错误日志中的具体错误信息
-#### 问题 2: 缓存验证失败
-**症状**: 缓存文件格式验证失败
-**排查步骤**:
-1. 检查缓存文件格式
-   ```bash
-   cat xiaozhi.cache.json | jq .
-   ```
-2. 查看具体验证错误
-   ```bash
-   cat xiaozhi.cache.json | jq . || echo "JSON 格式错误"
-   ```
-**解决方案**:
-- 删除损坏的缓存文件，重新生成
-- 检查缓存文件中的时间戳格式
-- 确保所有必需字段都存在
-#### 问题 3: 配置变更未检测到
-**症状**: 修改服务配置后，缓存没有更新
-**排查步骤**:
-1. 检查配置哈希是否变化
-   ```bash
-   # 查看缓存文件中的 configHash
-   cat xiaozhi.cache.json | jq '.mcpServers.serviceName.configHash'
-   ```
-2. 验证配置文件修改
-   ```bash
-   cat xiaozhi.config.json | jq '.mcpServerConfig'
-   ```
-3. 查看缓存管理器日志
-   ```bash
-   # 启动时查找相关日志
-   xiaozhi start | grep -i cache
-   ```
-**解决方案**:
-- 确保配置文件修改已保存
-- 重新构建项目 `pnpm build`
-- 删除缓存文件强制重新生成
-#### 问题 4: 缓存写入性能问题
-**症状**: 缓存写入操作耗时过长
-**排查步骤**:
-1. 检查缓存文件大小
-   ```bash
-   ls -lh xiaozhi.cache.json
-   ```
-2. 监控磁盘 I/O
-   ```bash
-   # macOS
-   iostat -d 1
-   # Linux
-   iotop
-   ```
-3. 查看缓存统计信息
-   ```bash
-   cat xiaozhi.cache.json | jq '.metadata'
-   ```
-**解决方案**:
-- 检查磁盘空间和性能
-- 考虑缓存文件压缩
-- 优化缓存写入频率
-### 性能测试和监控方法
-#### 性能基准测试
-1. **启动时间对比**
-   ```bash
-   # 测试无缓存启动时间
-   rm xiaozhi.cache.json
-   time xiaozhi start
-   # 测试有缓存启动时间
-   time xiaozhi start
-   ```
-2. **缓存统计监控**
-   ```bash
-   # 查看缓存统计
-   cat xiaozhi.cache.json | jq '.metadata'
-   # 输出示例：
-   # {
-   #   "lastGlobalUpdate": "2025-09-01 12:39:21",
-   #   "totalWrites": 6,
-   #   "createdAt": "2025-09-01 12:30:15"
-   # }
-   ```
-3. **内存使用监控**
-   ```bash
-   # 启动服务并监控内存使用
-   xiaozhi start &
-   PID=$!
-   # 监控内存使用
-   while kill -0 $PID 2>/dev/null; do
-     ps -p $PID -o pid,vsz,rss,comm
-     sleep 1
-   done
-   ```
-#### 性能优化建议
-1. **缓存文件大小控制**
-   - 定期清理过期的缓存条目
-   - 压缩工具定义中的冗余信息
-   - 设置合理的缓存保留策略
-2. **I/O 操作优化**
-   - 使用异步文件操作
-   - 批量写入多个缓存条目
-   - 避免频繁的小文件写入
-3. **内存使用优化**
-   - 及时释放不需要的缓存数据
-   - 使用流式处理大型缓存文件
-   - 实现缓存数据的懒加载
-## 总结
-xiaozhi 的 MCP 缓存机制通过智能的数据缓存和配置变更检测，显著提升了服务启动性能和用户体验。本文档为开发者提供了完整的缓存机制理解、开发指南和调试方法，帮助贡献者更好地参与项目开发和维护。
-### 关键要点
-- **设计原则**: 性能优化、数据一致性、错误隔离
-- **核心功能**: 缓存写入、配置变更检测、原子操作
-- **开发规范**: TypeScript 类型安全、完整测试覆盖、详细文档
-- **调试方法**: 单元测试、手动验证、性能监控
-### 后续发展
-当前实现专注于缓存写入功能，为后续的缓存读取、命中机制和性能优化奠定了坚实基础。未来的发展方向包括：
-- 实现缓存读取和命中机制
-- 添加缓存预热和后台更新功能
-- 优化缓存存储格式和压缩算法
-- 实现分布式缓存支持
-## 验证规则
-### 格式验证
-- **时间戳**: 必须符合 YYYY-MM-DD HH:mm:ss 格式
-- **版本号**: 必须符合语义化版本格式 (`x.y.z`)
-- **配置哈希**: 必须是 64 位十六进制字符串 (SHA256)
-- **服务器名称**: 只能包含字母、数字、下划线和连字符
-### 数据完整性
-- 所有必需字段必须存在
-- 数组字段不能为 null
-- 数值字段必须在合理范围内
-- 字符串字段不能为空（除非明确允许）
-## 版本兼容性
-当前缓存文件格式版本: `1.0.0`
-### 版本升级策略
-- **主版本号**: 不兼容的结构变更
-- **次版本号**: 向后兼容的功能添加
-- **修订版本号**: 向后兼容的问题修复
-## 相关文件
-- `src/services/MCPCacheManager.ts`: 缓存管理器实现
-- `xiaozhi.cache.json`: 实际的缓存文件（运行时生成）
-## 注意事项
-1. **数据一致性**: 缓存文件应该与实际的 MCP 服务配置保持一致
-2. **性能考虑**: 大型缓存文件可能影响读写性能
-3. **安全性**: 缓存文件可能包含敏感的配置信息，注意访问权限
-4. **备份**: 建议定期备份缓存文件，避免数据丢失
-## 故障排除
-### 常见验证错误
-1. **时间格式错误**: 确保时间戳符合 YYYY-MM-DD HH:mm:ss 格式
-2. **缺少必需字段**: 检查所有必需字段是否存在
-3. **类型不匹配**: 确保字段类型与接口定义一致
-4. **格式不符**: 检查版本号、哈希值等格式是否正确
-### 修复建议
-1. 使用 `jq` 工具检查 JSON 格式和内容
-2. 参考接口定义修正格式问题
-3. 重新生成缓存文件（删除现有文件，重启服务）
-4. 检查 MCPCacheManager 的实现逻辑