feat: 新增技能相关功能

2026-04-10 23:03:56 +08:00
parent 90a3ff6f77
commit 825fe36967
17 changed files with 2295 additions and 27 deletions
--- a/Skills-Development-Plan.md
+++ b/Skills-Development-Plan.md
@@ -0,0 +1,397 @@
+# zn-ai 技能功能开发计划
+
+## 项目概述
+
+本计划旨在将 ClawX 项目的 Skills（技能）功能完整迁移到 zn-ai 项目中，并保持功能一致性、代码完整性和用户体验对齐。基于对 ClawX Skills 功能的深入分析，制定本四阶段开发计划。
+
+## 技术栈映射与适配策略
+
+### 技术栈差异
+| 领域 | 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 |
+| API通信 | 自定义hostApiFetch | 现有axios/request封装 | 适配现有API调用方式 |
+| 国际化 | react-i18next | vue-i18n | 翻译键迁移，保持相同结构 |
+| 构建工具 | Vite | Vite | 直接兼容 |
+
+### 核心挑战与解决方案
+1. **UI一致性**：通过Element Plus组件+Tailwind CSS自定义样式实现类似视觉效果
+2. **状态管理**：Pinia的模块化store结构与Zustand的函数式风格适配
+3. **组件交互**：Vue的事件系统与React的props/callback模式转换
+4. **响应式系统**：利用Vue的ref/reactive替代React的useState
+
+## 阶段一：基础架构与类型定义 (预计：1-2天)
+
+### 目标
+建立技能功能的基础架构，包括类型定义、状态管理骨架和核心API接口。
+
+### 具体任务
+
+#### 1.1 类型定义创建
+**文件**: `src/lib/skills-types.ts`
+```typescript
+// 复用ClawX的Skill和MarketplaceSkill类型定义
+// 根据zn-ai的命名规范进行适当调整
+```
+
+**文件**: `src/lib/skill-config.ts`
+```typescript
+// 技能配置相关的类型和工具函数
+// 包括配置schema、验证逻辑等
+```
+
+#### 1.2 状态管理Store
+**文件**: `src/store/skills.ts`
+```typescript
+// Pinia Store定义，包含：
+// - 技能列表、搜索结果、加载状态等核心状态
+// - fetchSkills、searchSkills、installSkill等核心actions
+// - 错误处理逻辑
+```
+
+#### 1.3 API客户端适配
+**文件**: `src/lib/skills-api.ts`
+```typescript
+// 封装技能相关的API调用
+// 与现有的host-api.ts或axios封装集成
+// 包含：获取技能列表、搜索市场、安装/卸载等接口
+```
+
+#### 1.4 国际化资源
+**文件**: `src/i18n/locales/zh/skills.json`
+**文件**: `src/i18n/locales/en/skills.json`
+**文件**: `src/i18n/locales/ja/skills.json`
+```json
+// 从ClawX项目迁移翻译键
+// 保持相同的键结构，确保功能一致性
+```
+
+**更新**: `src/i18n/constants.ts`
+```typescript
+// 添加'skills'到NAMESPACES数组
+```
+
+### 交付成果
+- 完整的TypeScript类型定义
+- Pinia Store骨架（可编译通过）
+- API客户端接口定义
+- 多语言资源文件
+- 无TypeScript编译错误
+
+## 阶段二：核心UI组件开发 (预计：2-3天)
+
+### 目标
+开发技能功能的主要UI组件，包括技能列表、详情面板和市场搜索界面。
+
+### 具体任务
+
+#### 2.1 主页面组件
+**文件**: `src/pages/skills/index.vue`
+```vue
+<template>
+  <!-- 主容器，包含： -->
+  <!-- 1. 头部区域：标题、副标题、打开文件夹按钮 -->
+  <!-- 2. 网关状态警告（如适用） -->
+  <!-- 3. 导航与筛选：搜索框、来源筛选选项卡 -->
+  <!-- 4. 批量操作工具栏 -->
+  <!-- 5. 技能列表区域 -->
+</template>
+
+<script setup>
+// 使用Composition API实现：
+// - 搜索和筛选逻辑
+// - 批量操作处理
+// - 与Pinia Store的交互
+</script>
+```
+
+#### 2.2 技能列表项组件
+**文件**: `src/pages/skills/components/SkillListItem.vue`
+```vue
+<!-- 单个技能卡片的展示组件 -->
+<!-- 包含：图标、名称、描述、状态开关、来源标签等 -->
+```
+
+#### 2.3 技能详情弹窗组件
+**文件**: `src/pages/skills/components/SkillDetailDialog.vue`
+```vue
+<!-- 右侧滑出式详情面板 -->
+<!-- 包含：技能基本信息、API密钥配置、环境变量管理、路径操作等 -->
+```
+
+#### 2.4 市场搜索弹窗组件
+**文件**: `src/pages/skills/components/MarketplaceDialog.vue`
+```vue
+<!-- 技能市场搜索和安装界面 -->
+<!-- 包含：搜索框、搜索结果列表、安装/卸载按钮 -->
+```
+
+#### 2.5 环境变量管理组件
+**文件**: `src/pages/skills/components/EnvVarManager.vue`
+```vue
+<!-- 动态环境变量表单 -->
+<!-- 支持添加、编辑、删除环境变量键值对 -->
+```
+
+### UI/UX设计要点
+1. **视觉风格**：使用Element Plus的Dialog、Drawer、Card等组件，配合Tailwind CSS实现类似ClawX的视觉效果
+2. **交互设计**：
+   - 点击技能卡片打开详情
+   - 状态开关的即时反馈
+   - 搜索输入的防抖处理（300ms）
+   - 批量操作的成功/失败提示
+3. **响应式设计**：确保桌面端良好的显示效果
+
+### 交付成果
+- 完整的技能管理页面（可交互但数据为模拟）
+- 详情弹窗组件（包含配置表单）
+- 市场搜索界面
+- 基本的样式和交互效果
+
+## 阶段三：功能集成与数据绑定 (预计：2-3天)
+
+### 目标
+将UI组件与状态管理和后端API进行集成，实现完整的数据流和业务逻辑。
+
+### 具体任务
+
+#### 3.1 Store功能实现
+**完善**: `src/store/skills.ts`
+```typescript
+// 实现所有核心actions：
+// - fetchSkills(): 集成真实API调用
+// - searchSkills(): 连接市场搜索API
+// - installSkill()/uninstallSkill(): 安装/卸载逻辑
+// - enableSkill()/disableSkill(): 启用/禁用技能
+// - 错误处理：超时、频率限制等
+```
+
+#### 3.2 API集成
+**完善**: `src/lib/skills-api.ts`
+```typescript
+// 实现所有API调用：
+// - GET /api/skills/configs
+// - PUT /api/skills/config
+// - POST /api/clawhub/search
+// - POST /api/clawhub/install
+// - POST /api/clawhub/uninstall
+// - GET /api/clawhub/list
+// - 等所有必要的接口
+```
+
+#### 3.3 组件数据绑定
+**更新各Vue组件**：
+- 将UI组件连接到Pinia Store
+- 实现响应式数据更新
+- 添加加载状态和错误处理
+- 实现表单验证和提交逻辑
+
+#### 3.4 文件系统集成
+**功能实现**：
+- 打开技能文件夹功能
+- 复制技能路径到剪贴板
+- 打开技能手册/编辑器
+- 跨平台文件路径处理
+
+#### 3.5 错误处理与用户反馈
+**实现**：
+- Toast通知系统集成
+- 错误消息的友好显示
+- 网络错误的重试机制
+- 操作成功/失败的明确反馈
+
+### 交付成果
+- 完整的数据流：UI ↔ Store ↔ API
+- 真实的技能管理功能（安装、卸载、配置）
+- 完整的错误处理和用户反馈
+- 文件系统操作功能
+
+## 阶段四：测试、优化与完善 (预计：1-2天)
+
+### 目标
+进行功能测试、性能优化、国际化完善和代码质量提升。
+
+### 具体任务
+
+#### 4.1 功能测试
+**测试范围**：
+- 技能列表加载和显示
+- 搜索和筛选功能
+- 启用/禁用技能
+- 安装/卸载技能
+- 配置保存和加载
+- 文件系统操作
+- 错误场景处理
+
+**测试方法**：
+- 手动功能测试
+- 关键路径的单元测试
+- 模拟API响应的集成测试
+
+#### 4.2 性能优化
+**优化点**：
+- 技能列表的虚拟滚动（如列表过长）
+- 图片/图标的懒加载
+- API响应的缓存策略
+- 搜索防抖的优化调整
+
+#### 4.3 国际化完善
+**完善内容**：
+- 验证所有翻译键的正确使用
+- 动态内容（如技能来源）的本地化
+- 错误消息的多语言支持
+- 日期、数字等格式的本地化
+
+#### 4.4 代码质量
+**改进项**：
+- TypeScript类型定义的完善
+- 代码注释和文档
+- 组件和函数的单一职责原则
+- 错误处理的统一模式
+
+#### 4.5 UI/UX优化
+**优化内容**：
+- 响应式设计的进一步完善
+- 动画和过渡效果的优化
+- 无障碍访问支持
+- 深色/浅色主题的适配
+
+### 交付成果
+- 经过充分测试的稳定功能
+- 良好的性能表现
+- 完整的国际化支持
+- 高质量的代码实现
+- 优秀的用户体验
+
+## 文件结构规划
+
+```
+src/
+├── lib/
+│   ├── skills-types.ts          # 技能相关类型定义
+│   ├── skills-api.ts            # 技能API客户端
+│   └── skill-config.ts          # 技能配置工具
+├── store/
+│   └── skills.ts                # Pinia技能Store
+├── pages/
+│   └── skills/
+│       ├── index.vue            # 技能主页面
+│       └── components/
+│           ├── SkillListItem.vue        # 技能列表项
+│           ├── SkillDetailDialog.vue    # 技能详情弹窗
+│           ├── MarketplaceDialog.vue    # 市场搜索弹窗
+│           ├── EnvVarManager.vue        # 环境变量管理
+│           └── SkillCard.vue            # 技能卡片（可选）
+└── i18n/
+    └── locales/
+        ├── zh/
+        │   └── skills.json      # 中文翻译
+        ├── en/
+        │   └── skills.json      # 英文翻译
+        └── ja/
+            └── skills.json      # 日文翻译
+```
+
+## 后端集成考虑
+
+### API接口对齐
+zn-ai项目需要实现以下后端API接口以支持完整功能：
+```
+GET    /api/skills/configs          # 获取所有技能配置
+PUT    /api/skills/config           # 更新技能配置
+POST   /api/clawhub/search          # 搜索技能市场
+POST   /api/clawhub/install         # 安装技能
+POST   /api/clawhub/uninstall       # 卸载技能
+GET    /api/clawhub/list            # 列出已安装技能
+POST   /api/clawhub/open-readme     # 打开技能手册
+POST   /api/clawhub/open-path       # 打开技能目录
+```
+
+### 网关状态检测
+如果zn-ai有类似的网关架构，需要集成网关状态检测功能。如无，可简化或省略相关逻辑。
+
+## 风险评估与缓解策略
+
+### 技术风险
+1. **网关架构差异**：zn-ai可能没有ClawX的网关架构
+   - **缓解**：简化网关相关逻辑，或实现兼容层
+
+2. **ClawHub服务依赖**：技能市场服务可能不可用
+   - **缓解**：实现降级方案，支持本地技能安装
+
+3. **文件系统兼容性**：跨平台路径处理问题
+   - **缓解**：使用Node.js的path模块进行规范化处理
+
+### 实施风险
+1. **开发工作量超出预期**
+   - **缓解**：优先实现核心功能，增强功能后续迭代
+
+2. **UI一致性难以保证**
+   - **缓解**：使用设计系统规范，确保与zn-ai现有UI风格协调
+
+### 兼容性风险
+1. **技能包格式兼容性**
+   - **缓解**：实现格式转换层，或要求技能包符合zn-ai标准
+
+## 成功标准
+
+### 功能完整性
+- [ ] 技能列表展示和筛选
+- [ ] 技能启用/禁用功能
+- [ ] 技能详情查看和配置
+- [ ] 技能市场搜索和安装
+- [ ] 批量操作支持
+- [ ] 文件系统集成
+- [ ] 完整的错误处理
+
+### 技术质量
+- [ ] 无TypeScript编译错误
+- [ ] 通过ESLint检查
+- [ ] 代码覆盖率达标（如有时）
+- [ ] 性能指标满足要求
+
+### 用户体验
+- [ ] 界面响应迅速
+- [ ] 操作反馈明确
+- [ ] 错误提示友好
+- [ ] 多语言支持完整
+
+## 后续迭代建议
+
+### 短期优化（1-2周内）
+1. 技能分类和标签系统
+2. 技能依赖关系管理
+3. 技能版本更新检查
+4. 技能使用统计
+
+### 中期增强（1-2月内）
+1. 技能开发工具包
+2. 技能市场用户评价系统
+3. 技能自动更新机制
+4. 技能组合和模板
+
+### 长期愿景（3-6月内）
+1. 技能可视化编排
+2. AI辅助技能创建
+3. 技能商店和分发平台
+4. 社区技能分享生态
+
+## 附录
+
+### 参考资源
+1. ClawX Skills源代码：`/Users/duanshuwen/Documents/workspace/electron/ClawX/src/pages/Skills/`
+2. ClawX技能Store：`/Users/duanshuwen/Documents/workspace/electron/ClawX/src/stores/skills.ts`
+3. ClawX技能类型：`/Users/duanshuwen/Documents/workspace/electron/ClawX/src/types/skill.ts`
+4. ClawX技能API：`/Users/duanshuwen/Documents/workspace/electron/ClawX/electron/api/routes/skills.ts`
+
+### 关键决策点
+1. **UI框架选择**：坚持使用Element Plus，通过自定义样式达到视觉一致性
+2. **状态管理**：使用Pinia，保持与zn-ai其他模块的一致性
+3. **API设计**：尽可能保持与ClawX的API兼容，便于后续维护
+4. **国际化策略**：完全复用ClawX的翻译键结构，确保功能对齐
+
+---
+*计划制定时间：2026-04-10*
+*基于Skills功能分析报告制定*