397 lines
12 KiB
Markdown
397 lines
12 KiB
Markdown
# 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功能分析报告制定* |