feat: Enhance Marketplace and Skill Management UI with improved error handling and user feedback

- Updated MarketplaceDrawer to include security notes and manual installation hints. - Refactored SkillDetailDrawer to display default icons for skills. - Simplified SkillListItem to use default icons for better readability. - Integrated gateway status checks and warnings in SkillsPage for improved user awareness. - Enhanced error handling for skill installation and fetching, providing clearer feedback to users. - Added new translations for error messages and gateway warnings to improve localization support.
2026-04-19 20:33:44 +08:00
parent 2cedc1c234
commit 38bea97197
230 changed files with 77824 additions and 163 deletions
--- a/docs/Skills-Development-Plan.md
+++ b/docs/Skills-Development-Plan.md
@@ -9,18 +9,18 @@
 ### 技术栈差异
 | 领域 | ClawX (源项目) | zn-ai (目标项目) | 适配策略 |
 |------|----------------|------------------|----------|
-| 前端框架 | React 18 + TypeScript | Vue 3 + TypeScript | React组件转换为Vue组件（Composition API） |
-| 状态管理 | Zustand | Pinia | Zustand Store转换为Pinia Store |
-| UI组件库 | Shadcn/ui (基于Radix) | Element Plus + Tailwind CSS | 使用Element Plus组件+自定义样式实现相似UI |
+| 前端框架 | React 18 + TypeScript | React 18 + TypeScript | 直接复用React组件 |
+| 状态管理 | Zustand | 本地状态（useState） | 将Zustand Store转换为组件本地状态管理 |
+| UI组件库 | Shadcn/ui (基于Radix) | Tailwind CSS | 使用Tailwind CSS自定义样式实现相似UI |
 | API通信 | 自定义hostApiFetch | 现有axios/request封装 | 适配现有API调用方式 |
-| 国际化 | react-i18next | vue-i18n | 翻译键迁移，保持相同结构 |
+| 国际化 | react-i18next | 自定义消息树 | 翻译键迁移，保持相同结构 |
 | 构建工具 | Vite | Vite | 直接兼容 |

 ### 核心挑战与解决方案
-1. **UI一致性**：通过Element Plus组件+Tailwind CSS自定义样式实现类似视觉效果
-2. **状态管理**：Pinia的模块化store结构与Zustand的函数式风格适配
-3. **组件交互**：Vue的事件系统与React的props/callback模式转换
-4. **响应式系统**：利用Vue的ref/reactive替代React的useState
+1. **UI一致性**：通过Tailwind CSS自定义样式实现类似视觉效果
+2. **状态管理**：将Zustand的全局store转换为组件本地状态（useState + useEffect）
+3. **组件交互**：直接复用React的props/callback模式
+4. **响应式系统**：使用React的useState/useRef管理状态和副作用

 ## 阶段一：基础架构与类型定义 (预计：1-2天)

@@ -42,12 +42,12 @@
 // 包括配置schema、验证逻辑等
 ```

-#### 1.2 状态管理Store
-**文件**: `src/store/skills.ts`
+#### 1.2 状态管理
+**文件**: `src/pages/Skills/index.tsx`（组件本地状态）
 ```typescript
-// Pinia Store定义，包含：
+// 使用React useState/useRef管理：
 // - 技能列表、搜索结果、加载状态等核心状态
-// - fetchSkills、searchSkills、installSkill等核心actions
+// - fetchSkills、searchSkills、installSkill等核心逻辑
 // - 错误处理逻辑
 ```

@@ -60,24 +60,18 @@
 ```

 #### 1.4 国际化资源
-**文件**: `src/i18n/locales/zh/skills.json`
-**文件**: `src/i18n/locales/en/skills.json`
-**文件**: `src/i18n/locales/ja/skills.json`
-```json
+**文件**: `src/pages/Skills/messages.ts`
+```typescript
 // 从ClawX项目迁移翻译键
 // 保持相同的键结构，确保功能一致性
-```
-
-**更新**: `src/i18n/constants.ts`
-```typescript
-// 添加'skills'到NAMESPACES数组
+// 包含 en/zh/ja 三种语言的消息树
 ```

 ### 交付成果
 - 完整的TypeScript类型定义
- Pinia Store骨架（可编译通过）
+- 组件本地状态管理（可编译通过）
 - API客户端接口定义
- 多语言资源文件
+- 多语言消息树（en/zh/ja）
 - 无TypeScript编译错误

 ## 阶段二：核心UI组件开发 (预计：2-3天)
@@ -88,55 +82,50 @@
 ### 具体任务

 #### 2.1 主页面组件
-**文件**: `src/pages/skills/index.vue`
-```vue
-<template>
-  <!-- 主容器，包含： -->
-  <!-- 1. 头部区域：标题、副标题、打开文件夹按钮 -->
-  <!-- 2. 网关状态警告（如适用） -->
-  <!-- 3. 导航与筛选：搜索框、来源筛选选项卡 -->
-  <!-- 4. 批量操作工具栏 -->
-  <!-- 5. 技能列表区域 -->
-</template>
-
-<script setup>
-// 使用Composition API实现：
+**文件**: `src/pages/Skills/index.tsx`
+```tsx
+// 主容器，包含：
+// 1. 头部区域：标题、副标题、打开文件夹按钮
+// 2. 网关状态警告（如适用）
+// 3. 导航与筛选：搜索框、来源筛选选项卡
+// 4. 批量操作工具栏
+// 5. 技能列表区域
+// 使用React Hooks实现：
 // - 搜索和筛选逻辑
 // - 批量操作处理
-// - 与Pinia Store的交互
-</script>
+// - 组件本地状态管理
 ```

 #### 2.2 技能列表项组件
-**文件**: `src/pages/skills/components/SkillListItem.vue`
-```vue
-<!-- 单个技能卡片的展示组件 -->
-<!-- 包含：图标、名称、描述、状态开关、来源标签等 -->
+**文件**: `src/pages/Skills/components/SkillListItem.tsx`
+```tsx
+// 单个技能卡片的展示组件
+// 包含：图标、名称、描述、状态开关、来源标签等
 ```

 #### 2.3 技能详情弹窗组件
-**文件**: `src/pages/skills/components/SkillDetailDialog.vue`
-```vue
-<!-- 右侧滑出式详情面板 -->
-<!-- 包含：技能基本信息、API密钥配置、环境变量管理、路径操作等 -->
+**文件**: `src/pages/Skills/components/SkillDetailDrawer.tsx`
+```tsx
+// 右侧滑出式详情面板
+// 包含：技能基本信息、API密钥配置、环境变量管理、路径操作等
 ```

 #### 2.4 市场搜索弹窗组件
-**文件**: `src/pages/skills/components/MarketplaceDialog.vue`
-```vue
-<!-- 技能市场搜索和安装界面 -->
-<!-- 包含：搜索框、搜索结果列表、安装/卸载按钮 -->
+**文件**: `src/pages/Skills/components/MarketplaceDrawer.tsx`
+```tsx
+// 技能市场搜索和安装界面
+// 包含：搜索框、搜索结果列表、安装/卸载按钮
 ```

 #### 2.5 环境变量管理组件
-**文件**: `src/pages/skills/components/EnvVarManager.vue`
-```vue
-<!-- 动态环境变量表单 -->
-<!-- 支持添加、编辑、删除环境变量键值对 -->
+**文件**: `src/pages/Skills/components/EnvVarManager.tsx`
+```tsx
+// 动态环境变量表单
+// 支持添加、编辑、删除环境变量键值对
 ```

 ### UI/UX设计要点
-1. **视觉风格**：使用Element Plus的Dialog、Drawer、Card等组件，配合Tailwind CSS实现类似ClawX的视觉效果
+1. **视觉风格**：使用Tailwind CSS自定义样式实现类似ClawX的视觉效果
 2. **交互设计**：
   - 点击技能卡片打开详情
   - 状态开关的即时反馈
@@ -157,15 +146,16 @@

 ### 具体任务

-#### 3.1 Store功能实现
-**完善**: `src/store/skills.ts`
+#### 3.1 核心逻辑实现
+**完善**: `src/pages/Skills/index.tsx`
 ```typescript
-// 实现所有核心actions：
-// - fetchSkills(): 集成真实API调用
-// - searchSkills(): 连接市场搜索API
-// - installSkill()/uninstallSkill(): 安装/卸载逻辑
-// - enableSkill()/disableSkill(): 启用/禁用技能
+// 实现所有核心逻辑：
+// - loadSkills(): 集成真实API调用
+// - handleSearch(): 连接市场搜索API
+// - handleInstall()/handleUninstall(): 安装/卸载逻辑
+// - handleToggle(): 启用/禁用技能
 // - 错误处理：超时、频率限制等
+// - 批量操作：串行容错模式
 ```

 #### 3.2 API集成
@@ -182,9 +172,9 @@
 ```

 #### 3.3 组件数据绑定
-**更新各Vue组件**：
- 将UI组件连接到Pinia Store
- 实现响应式数据更新
+**更新各React组件**：
+- 将UI组件连接到组件本地状态
+- 使用props和callback传递数据
 - 添加加载状态和错误处理
 - 实现表单验证和提交逻辑

@@ -273,25 +263,17 @@ src/
 │   ├── skills-types.ts          # 技能相关类型定义
 │   ├── skills-api.ts            # 技能API客户端
 │   └── skill-config.ts          # 技能配置工具
-├── store/
-│   └── skills.ts                # Pinia技能Store
 ├── pages/
-│   └── skills/
-│       ├── index.vue            # 技能主页面
+│   └── Skills/
+│       ├── index.tsx            # 技能主页面
+│       ├── messages.ts          # 多语言消息树（en/zh/ja）
+│       ├── copy.ts              # 文案hook
 │       └── components/
-│           ├── SkillListItem.vue        # 技能列表项
-│           ├── SkillDetailDialog.vue    # 技能详情弹窗
-│           ├── MarketplaceDialog.vue    # 市场搜索弹窗
-│           ├── EnvVarManager.vue        # 环境变量管理
-│           └── SkillCard.vue            # 技能卡片（可选）
-└── i18n/
-    └── locales/
-        ├── zh/
-        │   └── skills.json      # 中文翻译
-        ├── en/
-        │   └── skills.json      # 英文翻译
-        └── ja/
-            └── skills.json      # 日文翻译
+│           ├── SkillListItem.tsx        # 技能列表项
+│           ├── SkillDetailDrawer.tsx    # 技能详情抽屉
+│           ├── MarketplaceDrawer.tsx    # 市场搜索抽屉
+│           ├── EnvVarManager.tsx        # 环境变量管理
+│           └── icons.tsx                # 图标组件
 ```

 ## 后端集成考虑
@@ -387,10 +369,10 @@ POST   /api/clawhub/open-path       # 打开技能目录
 4. ClawX技能API：`/Users/duanshuwen/Documents/workspace/electron/ClawX/electron/api/routes/skills.ts`

 ### 关键决策点
-1. **UI框架选择**：坚持使用Element Plus，通过自定义样式达到视觉一致性
-2. **状态管理**：使用Pinia，保持与zn-ai其他模块的一致性
+1. **UI框架选择**：使用Tailwind CSS，通过自定义样式达到视觉一致性
+2. **状态管理**：使用React组件本地状态（useState/useRef），保持与zn-ai其他React模块的一致性
 3. **API设计**：尽可能保持与ClawX的API兼容，便于后续维护
-4. **国际化策略**：完全复用ClawX的翻译键结构，确保功能对齐
+4. **国际化策略**：完全复用ClawX的翻译键结构，使用自定义消息树实现，确保功能对齐

 ---
 *计划制定时间：2026-04-10*