# 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功能分析报告制定*