AutoDev Codebase MCP Server

# --force 选项实现经验总结 ## 概述 本文档记录了在 autodev-codebase 项目中实现 `--force` 选项的完整过程，包括遇到的问题、调试过程和最终解决方案。这个经验对于理解复杂异步系统中的竞态条件问题具有重要参考价值。 ## 需求背景 用户需要一个 `--force` 选项来强制忽略缓存，重新索引所有文件。这在以下场景中非常有用： - 配置变更后重新索引 - 缓存损坏修复 - 调试和测试 - 版本升级后重建索引 ## 实现过程 ### 1. 基础实现 首先实现了基本的 CLI 参数解析和功能集成： #### CLI 参数解析 (`src/cli/args-parser.ts`) ```typescript export interface CliOptions { // ... 其他选项 force: boolean; // 新增强制重新索引标志 } // 解析逻辑 } else if (arg === '--force') { options.force = true; ``` #### TUI Runner 集成 (`src/cli/tui-runner.ts`) 在三个运行模式中都添加了 force 处理逻辑： - TUI 模式：`createTUIApp()` - MCP Server 模式：`startMCPServerMode()` - Stdio Adapter 模式：`startStdioAdapterMode()` ```typescript // Handle force option if (options.force) { console.log('🔄 Force mode enabled, clearing all index data...'); if (manager.isFeatureEnabled && manager.isInitialized) { await manager.clearIndexData(); console.log('✅ All index data cleared successfully'); } } ``` ### 2. 遇到的问题：交错成功/失败 实现后发现一个奇怪的现象：**连续运行时会出现交错的成功/失败模式**： - 第一次运行：成功 - 第二次运行：失败（Collection doesn't exist 错误） - 第三次运行：成功 - 第四次运行：失败 - ...如此循环 #### 错误表现 ``` Failed to upsert points: ApiError: Not Found Collection `ws-d7947ff78f9f219d` doesn't exist! ``` ### 3. 问题分析过程 #### 第一步：竞态条件假设 最初怀疑是 `clearIndexData()` 和 `startIndexing()` 之间的竞态条件： 1. `clearIndexData()` 删除集合 2. 正在运行的批处理操作仍试图向已删除的集合插入数据 3. 导致"集合不存在"错误 #### 尝试的修复方案 1. **向量存储级别保护**：在 `upsertPoints()` 中添加集合存在性检查 2. **批处理器智能错误处理**：检测"集合不存在"错误并停止重试 3. **时序控制**：在清理后添加延迟 这些修复能减少错误，但没有解决交错问题的根本原因。 #### 第二步：单例状态假设 怀疑是 `CodeIndexManager` 单例模式导致状态持久化： - 第一次运行创建新实例，成功 - 第二次运行复用旧实例，保持着脏状态，失败 尝试添加进程退出时的单例清理，但仍然没有解决问题。 #### 第三步：真正的根本原因 通过仔细观察用户的反馈，发现了关键信息： > "只有在数据库有 ws-d7947ff78f9f219d 集合的时候会报错，也就交错执行中集合会一次有一次无" 这揭示了真正的问题：**集合的存在状态在每次运行后都会改变**。 ### 4. 根本原因分析 问题出现在 `clearIndexData()` 的实现中： ```typescript // 有问题的实现 public async clearIndexData(): Promise<void> { // ... await this.vectorStore.deleteCollection() // 立即重新初始化，重新创建集合 await this.vectorStore.initialize() // ... } ``` #### 竞态条件的具体表现： 1. **集合存在时的运行**： - `clearIndexData()` 删除集合 - 立即调用 `initialize()` 重新创建 - 但删除操作可能还没完全传播到 Qdrant - `initialize()` 检查时发现集合"仍然存在" - 尝试创建集合时发生冲突 → **失败** 2. **集合不存在时的运行**： - `clearIndexData()` 尝试删除不存在的集合（通常成功） - `initialize()` 检查发现集合不存在 - 成功创建新集合 → **成功** 3. **交错模式的形成**： - 成功的运行会留下集合 - 失败的运行不会留下集合 - 因此下次运行的条件总是相反，形成交错 ### 5. 最终解决方案 经过实验验证，最终采用的解决方案是：**在 `clearIndexData()` 中立即重新创建集合，但增加足够的等待时间确保删除操作完全传播**。 #### 修改后的实现 ```typescript public async clearIndexData(): Promise<void> { this._isProcessing = true try { this.stopWatcher() try { if (this.configManager.isFeatureConfigured) { await this.vectorStore.deleteCollection() // Add a small delay to ensure deletion is fully completed in Qdrant await new Promise(resolve => setTimeout(resolve, 500)) this.info("[CodeIndexOrchestrator] Collection deletion completed, waiting for propagation...") // Immediately reinitialize the vector store to recreate the collection // This prevents any timing window where the collection doesn't exist this.info("[CodeIndexOrchestrator] Reinitializing vector store after deletion...") await this.vectorStore.initialize() this.info("[CodeIndexOrchestrator] Vector store reinitialized successfully") } else { this.warn("[CodeIndexOrchestrator] Service not configured, skipping vector collection clear.") } } catch (error: any) { this.error("[CodeIndexOrchestrator] Failed to clear vector collection:", error) this.stateManager.setSystemState("Error", `Failed to clear vector collection: ${error.message}`) } await this.cacheManager.clearCacheFile() if (this.stateManager.state !== "Error") { this.stateManager.setSystemState("Standby", "Index data cleared successfully.") } } finally { this._isProcessing = false } } ``` #### 关键改进点 1. **增加传播等待时间**：在删除集合后等待 500ms，确保 Qdrant 完全处理删除操作 2. **立即重新初始化**：删除完成后立即重新创建集合，避免"集合不存在"的时间窗口 3. **详细日志记录**：提供清晰的操作进度反馈 4. **错误隔离**：将集合操作包装在单独的 try-catch 中 #### 工作流程 1. `clearIndexData()` 删除集合并等待传播 2. 立即重新初始化向量存储，创建新的空集合 3. 清理缓存文件 4. `startIndexing()` 检测到集合已存在且为空，开始正常索引流程 #### 为什么这个方案有效 - **消除时间窗口**：通过立即重新创建，避免了正在进行的批处理操作遇到"集合不存在"的情况 - **数据清空**：新创建的集合是空的，达到了 force 清理的目的 - **状态一致性**：确保系统始终处于可预期的状态（集合总是存在） ## 关键经验教训 ### 1. 异步系统中的时序问题 - **问题**：在异步操作密集的系统中，操作的完成时间难以预测 - **教训**：避免在异步删除操作后立即执行创建操作 - **最佳实践**：让系统的不同阶段负责不同的职责，避免在一个操作中同时进行删除和创建 ### 2. 分布式系统的状态传播 - **问题**：Qdrant 等外部服务的状态变更需要时间传播 - **教训**：即使本地操作返回成功，远程状态可能还没有更新 - **最佳实践**：设计操作序列时考虑状态传播延迟 ### 3. 调试复杂竞态条件的方法 - **观察模式**：交错的成功/失败模式通常指向状态依赖问题 - **状态跟踪**：跟踪关键资源（如数据库集合）的存在状态 - **隔离变量**：逐一排除可能的原因（单例、缓存、时序等） ### 4. 架构设计原则 - **单一职责**：每个方法应该有明确的单一职责 - **幂等性**：重复执行相同操作应该产生相同结果 - **状态一致性**：避免创建可能导致不一致状态的操作序列