feat(tool): 增强工具实例管理和更新功能 #56
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
**主要变更：**
1. **后端能力增强**
- 新增 validate_tool_path 命令：验证用户指定的工具路径有效性
- 新增 add_manual_tool_instance 命令：支持保存用户手动指定的工具路径
- 新增 detect_tool_without_save 命令：支持检测预览（不保存到数据库）
- 修改 refresh_tool_status 行为：从数据库读取而非重新检测（性能优化）
2. **v3 引导流程重构**
- ToolDetectionStep：从自动检测改为引导用户进入工具管理页面
- 使用标准化的 onboarding-navigate 事件处理页面跳转和限制
- 支持自动触发添加实例对话框（autoAction 机制）
3. **工具管理 UI 增强**
- AddInstanceDialog：支持本地环境的两种添加方式
- 自动扫描：检测系统已安装的工具
- 手动指定：浏览文件选择器指定工具路径
- 集成 @tauri-apps/plugin-dialog 用于原生文件选择器
- 实时验证路径有效性和显示检测结果
4. **导航和限制机制**
- App.tsx：支持 restrictedPage 限制用户在引导过程中的导航
- 监听 onboarding-navigate 和 clear-onboarding-restriction 事件
- 延迟触发自动动作（500ms）确保页面渲染完成
5. **类型和依赖更新**
- 新增 OnboardingNavigationPayload 类型定义
- 添加 @tauri-apps/plugin-dialog 依赖
- 更新 Tauri schemas 以支持新命令
**改进点：**
- 用户体验：从被动的自动检测改为主动的引导式配置
- 灵活性：支持自动扫描和手动指定两种方式
- 性能：检测和保存分离，避免不必要的重复检测
- 可维护性：标准化事件处理和页面导航逻辑
**影响范围：**
- 前端：引导流程、工具管理页面、事件系统
- 后端：工具检测命令、数据库操作逻辑
- 依赖：新增原生对话框插件
**主要变更：**
1. **新增基于实例的更新检测**
- check_update_for_instance 命令：使用实例配置的路径检测版本号
- refresh_all_tool_versions 命令：批量刷新数据库中所有工具版本号
- parse_version_string 辅助函数：统一处理多种版本号格式
- 支持括号格式：2.0.61 (Claude Code) → 2.0.61
- 支持空格格式：codex-cli 0.65.0 → 0.65.0
- 支持 v 前缀：v1.2.3 → 1.2.3
2. **移除废弃命令**
- 删除 has_tools_in_database 命令（不再需要）
- 删除 detect_and_save_tools 命令（已被实例管理替代）
- 从 main.rs 中移除相应的命令注册
3. **前端调用优化**
- Dashboard：使用 refreshAllToolVersions 替代 refreshToolStatus
- ToolManagement：使用 checkUpdateForInstance 替代 checkUpdate
- 检测更新后自动同步 groupedTools 状态（避免 Tab 跳转）
4. **ToolRegistry 改进**
- aggregate_tool_status：按 base_id 聚合时选择最高版本号
- 版本解析统一使用 parse_version_string 函数
**改进点：**
- 准确性：使用实例配置的路径检测，避免检测到错误的工具
- 一致性：版本号解析统一处理，支持多种格式
- 性能：检测时自动更新数据库，避免重复刷新
- 用户体验：检测更新后状态实时同步，无需重新加载页面
**影响范围：**
- 后端：工具命令层、ToolRegistry
- 前端：Dashboard、ToolManagement 的更新检测逻辑
- 数据库：版本号在检测时自动同步更新
## 动机 手动添加的工具实例缺少安装方法和安装器路径信息，导致无法使用 APP 内快捷更新功能。需要在添加时收集这些信息以支持完整的工具生命周期管理。 ## 主要改动 ### 数据模型扩展 - `ToolInstance` 新增 `installer_path` 字段存储安装器路径（如 npm/brew 路径） - `InstallMethod` 新增 `Other` 变体，用于不支持 APP 内更新的场景 - 数据库读写、JSON 序列化逻辑同步更新 ### 安装器自动检测 - `ToolRegistry::detect_local_tool` 增加安装器路径检测 - 支持 npm（优先 which/where）和 brew（macOS）的自动定位 - 检测结果存储到 `ToolInstance.installer_path` ### 手动添加流程优化 - `add_manual_tool_instance` 命令新增 `install_method` 和 `installer_path` 参数 - 验证逻辑：非 `Other` 类型必须提供安装器路径 - 安装器路径存在性和可执行性验证 ### UI 改进 - `AddInstanceDialog` 新增安装器类型选择（4 选项：npm/brew/official/other） - 新增安装器路径输入和文件浏览功能（非 other 类型时显示） - `Other` 类型显示黄色警告提示不支持 APP 内更新 - 表单布局优化，清晰展示工具路径与安装器路径的区别 ### Detector 更新 - `ClaudeCodeDetector`、`CodeXDetector`、`GeminiCLIDetector` 增加 `Other` 类型拦截 - 统一错误提示："不支持 APP 内安装,请手动安装" ## 测试情况 - ✅ 已验证手动添加流程（npm 类型） - ✅ 安装器路径验证逻辑正常 - ✅ Other 类型警告显示正确 -⚠️ 尚未覆盖数据库迁移场景（旧数据 `installer_path` 默认 None） ## 影响范围 - **数据层**：`ToolInstance` 结构变更，旧数据兼容（字段可选） - **检测层**：所有 Detector 需处理 `Other` 类型 - **前端**：工具管理页面添加实例流程更新 ## 风险评估 - 低风险：字段为可选，不影响现有数据 - 需关注：数据库读取时 `installer_path` 为 `None` 的处理
## 动机
手动添加工具实例的表单信息量较大（工具选择、环境类型、添加方式、路径配置、安装器配置等），单步展示容易造成视觉负担和操作混乱。需要拆分为多步向导以提升用户体验。
## 主要改动
### 流程拆分
- **第一步**：基础选择（工具、环境类型、添加方式）
- 本地环境：选择自动检测或手动指定
- WSL 环境：选择发行版
- SSH 环境：暂时灰显（下期支持）
- **第二步**：详细配置（路径输入、安装器配置、扫描验证）
- 仅在第一步选择完成后显示
- 根据添加方式（auto/manual）动态展示不同内容
### 状态管理
- 新增 `step` 状态（1=基础选择，2=详细配置）
- `handleNext` 验证第一步必填项（WSL 需选择发行版）
- `handleBack` 返回第一步并清空扫描结果
- `handleClose` 重置所有状态包括 step
### UI 优化
- 对话框底部按钮根据步骤动态切换：
- 第一步：[取消] [下一步]
- 第二步：[上一步] [添加]
- 移除重复的 WSL 发行版选择代码块（原有 step 1 和独立渲染逻辑冗余）
- 保持原有验证逻辑和禁用状态判断
### 代码结构
- 使用条件渲染 `{step === 1 && ...}` 和 `{step === 2 && ...}` 清晰划分视图
- 保留所有原有功能（自动检测、路径验证、安装器配置）
- 无逻辑变更，纯 UI 流程重构
## 测试情况
- ✅ 已验证两步流程正常切换
- ✅ 第一步验证（WSL 发行版必选）工作正常
- ✅ 返回第一步后状态重置正确
- ✅ 最终提交逻辑不受影响
## 影响范围
- **用户体验**：添加流程更清晰，降低认知负担
- **代码结构**：条件渲染优化，减少重复代码
## 风险评估
- 极低风险：纯 UI 重构，所有业务逻辑保持不变
- 已保留所有验证和错误处理
## 主要改动 **后端新增扫描服务：** - 新增 `installer_scanner.rs` 模块，提供智能安装器路径扫描能力 - 实现两级扫描策略：工具同级目录 + 上级目录 - 支持多种安装器类型（npm/pnpm/yarn/brew）自动识别 - 新增 `scan_all_tool_candidates` 命令，在 PATH 中批量扫描工具实例 - 新增 `scan_installer_for_tool_path` 命令，为指定工具路径扫描安装器 **前端交互优化：** - 自动扫描模式支持多实例展示和选择 - 手动模式集成安装器候选列表（优先级排序：同级 npm > 上级 npm > 同级 brew > 上级 brew） - 安装器路径自动填充，支持下拉选择或手动输入 - 单个候选自动选择，多个候选展示卡片式选择器 - 优化用户体验：减少手动配置步骤，提高准确性 **数据结构：** - `ToolCandidate`: 工具候选（路径 + 版本 + 安装器 + 安装方法） - `InstallerCandidate`: 安装器候选（路径 + 类型 + 扫描级别） ## 测试情况 - [x] 后端命令功能验证（单元测试框架已准备） - [x] 前端多候选/单候选流程测试 - [x] 安装器扫描准确性验证 - [x] 跨平台路径处理（Windows/macOS/Linux） ## 影响范围 - 工具管理模块（添加实例对话框） - 命令层（tool_commands.rs） - 类型系统（前后端类型同步）
## 主要改动 **后端新增命令：** - 新增 `update_tool_instance` 命令，使用数据库中的 `installer_path` 和 `install_method` 执行更新 - 支持 npm/brew 安装方式的自动更新（120秒超时保护） - 更新成功后自动刷新数据库中的版本号 - 标记旧 `update_tool` 命令为废弃（保留向后兼容） **更新逻辑优化：** - 从数据库读取实例配置，无需重新检测安装方法 - 支持同一工具的多个实例独立更新 - 更精准的错误提示（区分配置缺失、方法不支持等场景） **前端集成：** - 添加 `updateToolInstance` TypeScript 函数 - `useToolManagement` Hook 切换到新命令 - 标记旧 `updateTool` 函数为废弃 ## 技术细节 **命令参数：** - `instance_id`: 工具实例ID（如 "claude-code-local-1"） - `force`: 可选强制更新标志 **错误处理：** - 未配置安装器：提示用户重新添加实例 - 官方安装方式：提示手动重新安装 - "其他"类型：提示不支持快捷更新 - 执行超时：120秒保护机制 ## 影响范围 - 工具管理模块（更新功能） - 命令层（新增命令） - 前端 Hook（调用切换） ## 向后兼容 旧 `update_tool` 命令保留，前端已切换到新命令，未来版本可移除旧命令。
## 主要改动 **UI 流程重构：** - 将安装器类型选择移至路径验证成功之后（避免用户盲目选择） - 验证路径后智能判断： - 扫描到安装器 → 显示下拉选择器 + "自定义"按钮 - 未扫描到 → 显示安装器类型选择 + 路径输入 - 点击"自定义"按钮可切换到手动配置模式 **状态管理优化：** - 对话框打开时完整重置所有状态（避免脏数据） - 路径输入框 onChange 时清除扫描结果和安装器候选 - 添加 `showCustomInstaller` 状态控制手动配置模式 **用户体验提升：** - 路径验证和安装器扫描合并为单次操作 - 按钮文案优化："验证中..." → "验证路径" - 自动检测时优先展示扫描结果，减少手动配置步骤 - 自定义模式保留完整的类型选择和路径输入功能 ## 视觉改进 - 验证成功后分阶段展示：路径验证 → 安装器配置 - 安装器候选列表显示级别信息（同级/上级） - 类型选择卡片保持响应式布局（4列网格） ## 影响范围 仅影响前端组件 `AddInstanceDialog`，无后端变更，向后兼容。
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
动机
工具管理系统当前存在以下问题：
本 PR 通过引入智能扫描和实例级更新机制来解决这些问题。
主要改动点
1. 新增安装器智能扫描功能 (a6c4cb8)
后端模块：
installer_scanner.rs模块，实现两级目录扫描策略scan_all_tool_candidates命令：批量扫描 PATH 中的工具实例scan_installer_for_tool_path命令：为指定工具路径扫描安装器前端集成：
数据结构：
ToolCandidate: 工具候选（路径 + 版本 + 安装器 + 安装方法）InstallerCandidate: 安装器候选（路径 + 类型 + 扫描级别）2. 新增实例级工具更新命令 (bb4326b)
核心功能：
update_tool_instance命令，直接使用数据库中的installer_path和install_methodupdate_tool命令为废弃（保留向后兼容）优势：
前端调用：
useToolManagementHook 切换到新命令3. 优化添加对话框 UI 流程 (db9002a)
流程改进：
showCustomInstaller状态控制手动配置模式状态管理：
用户体验：
测试情况
后端测试
installer_scanner.rs::tests）前端测试
集成测试
风险评估
低风险
需要注意
cmd /C命令执行需要正确处理路径空格（已通过双引号处理）回滚方案
git revert独立回滚各个提交受影响模块
commands/tool_commands.rs、utils/installer_scanner.rs、main.rstauri-commands.ts、AddInstanceDialog.tsx、useToolManagement.ts截图/演示
（本地验证通过，如需截图可补充）
检查清单
npm run check且全部通过cargo test --locked）