12 KiB
12 KiB
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 | 直接兼容 |
核心挑战与解决方案
- UI一致性：通过Element Plus组件+Tailwind CSS自定义样式实现类似视觉效果
- 状态管理：Pinia的模块化store结构与Zustand的函数式风格适配
- 组件交互：Vue的事件系统与React的props/callback模式转换
- 响应式系统：利用Vue的ref/reactive替代React的useState
阶段一：基础架构与类型定义 (预计：1-2天)
目标
建立技能功能的基础架构，包括类型定义、状态管理骨架和核心API接口。
具体任务
1.1 类型定义创建
文件: src/lib/skills-types.ts
// 复用ClawX的Skill和MarketplaceSkill类型定义
// 根据zn-ai的命名规范进行适当调整
文件: src/lib/skill-config.ts
// 技能配置相关的类型和工具函数
// 包括配置schema、验证逻辑等
1.2 状态管理Store
文件: src/store/skills.ts
// Pinia Store定义，包含：
// - 技能列表、搜索结果、加载状态等核心状态
// - fetchSkills、searchSkills、installSkill等核心actions
// - 错误处理逻辑
1.3 API客户端适配
文件: src/lib/skills-api.ts
// 封装技能相关的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
// 从ClawX项目迁移翻译键
// 保持相同的键结构，确保功能一致性
更新: src/i18n/constants.ts
// 添加'skills'到NAMESPACES数组
交付成果
- 完整的TypeScript类型定义
- Pinia Store骨架（可编译通过）
- API客户端接口定义
- 多语言资源文件
- 无TypeScript编译错误
阶段二：核心UI组件开发 (预计：2-3天)
目标
开发技能功能的主要UI组件，包括技能列表、详情面板和市场搜索界面。
具体任务
2.1 主页面组件
文件: src/pages/skills/index.vue
<template>
<!-- 主容器，包含： -->
<!-- 1. 头部区域：标题、副标题、打开文件夹按钮 -->
<!-- 2. 网关状态警告（如适用） -->
<!-- 3. 导航与筛选：搜索框、来源筛选选项卡 -->
<!-- 4. 批量操作工具栏 -->
<!-- 5. 技能列表区域 -->
</template>
<script setup>
// 使用Composition API实现：
// - 搜索和筛选逻辑
// - 批量操作处理
// - 与Pinia Store的交互
</script>
2.2 技能列表项组件
文件: src/pages/skills/components/SkillListItem.vue
<!-- 单个技能卡片的展示组件 -->
<!-- 包含：图标、名称、描述、状态开关、来源标签等 -->
2.3 技能详情弹窗组件
文件: src/pages/skills/components/SkillDetailDialog.vue
<!-- 右侧滑出式详情面板 -->
<!-- 包含：技能基本信息、API密钥配置、环境变量管理、路径操作等 -->
2.4 市场搜索弹窗组件
文件: src/pages/skills/components/MarketplaceDialog.vue
<!-- 技能市场搜索和安装界面 -->
<!-- 包含：搜索框、搜索结果列表、安装/卸载按钮 -->
2.5 环境变量管理组件
文件: src/pages/skills/components/EnvVarManager.vue
<!-- 动态环境变量表单 -->
<!-- 支持添加、编辑、删除环境变量键值对 -->
UI/UX设计要点
- 视觉风格：使用Element Plus的Dialog、Drawer、Card等组件，配合Tailwind CSS实现类似ClawX的视觉效果
- 交互设计：
- 点击技能卡片打开详情
- 状态开关的即时反馈
- 搜索输入的防抖处理（300ms）
- 批量操作的成功/失败提示
- 响应式设计：确保桌面端良好的显示效果
交付成果
- 完整的技能管理页面（可交互但数据为模拟）
- 详情弹窗组件（包含配置表单）
- 市场搜索界面
- 基本的样式和交互效果
阶段三：功能集成与数据绑定 (预计：2-3天)
目标
将UI组件与状态管理和后端API进行集成，实现完整的数据流和业务逻辑。
具体任务
3.1 Store功能实现
完善: src/store/skills.ts
// 实现所有核心actions：
// - fetchSkills(): 集成真实API调用
// - searchSkills(): 连接市场搜索API
// - installSkill()/uninstallSkill(): 安装/卸载逻辑
// - enableSkill()/disableSkill(): 启用/禁用技能
// - 错误处理：超时、频率限制等
3.2 API集成
完善: src/lib/skills-api.ts
// 实现所有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有类似的网关架构，需要集成网关状态检测功能。如无，可简化或省略相关逻辑。
风险评估与缓解策略
技术风险
-
网关架构差异：zn-ai可能没有ClawX的网关架构
- 缓解：简化网关相关逻辑，或实现兼容层
-
ClawHub服务依赖：技能市场服务可能不可用
- 缓解：实现降级方案，支持本地技能安装
-
文件系统兼容性：跨平台路径处理问题
- 缓解：使用Node.js的path模块进行规范化处理
实施风险
-
开发工作量超出预期
- 缓解：优先实现核心功能，增强功能后续迭代
-
UI一致性难以保证
- 缓解：使用设计系统规范，确保与zn-ai现有UI风格协调
兼容性风险
- 技能包格式兼容性
- 缓解：实现格式转换层，或要求技能包符合zn-ai标准
成功标准
功能完整性
- 技能列表展示和筛选
- 技能启用/禁用功能
- 技能详情查看和配置
- 技能市场搜索和安装
- 批量操作支持
- 文件系统集成
- 完整的错误处理
技术质量
- 无TypeScript编译错误
- 通过ESLint检查
- 代码覆盖率达标（如有时）
- 性能指标满足要求
用户体验
- 界面响应迅速
- 操作反馈明确
- 错误提示友好
- 多语言支持完整
后续迭代建议
短期优化（1-2周内）
- 技能分类和标签系统
- 技能依赖关系管理
- 技能版本更新检查
- 技能使用统计
中期增强（1-2月内）
- 技能开发工具包
- 技能市场用户评价系统
- 技能自动更新机制
- 技能组合和模板
长期愿景（3-6月内）
- 技能可视化编排
- AI辅助技能创建
- 技能商店和分发平台
- 社区技能分享生态
附录
参考资源
- ClawX Skills源代码：
/Users/duanshuwen/Documents/workspace/electron/ClawX/src/pages/Skills/ - ClawX技能Store：
/Users/duanshuwen/Documents/workspace/electron/ClawX/src/stores/skills.ts - ClawX技能类型：
/Users/duanshuwen/Documents/workspace/electron/ClawX/src/types/skill.ts - ClawX技能API：
/Users/duanshuwen/Documents/workspace/electron/ClawX/electron/api/routes/skills.ts
关键决策点
- UI框架选择：坚持使用Element Plus，通过自定义样式达到视觉一致性
- 状态管理：使用Pinia，保持与zn-ai其他模块的一致性
- API设计：尽可能保持与ClawX的API兼容，便于后续维护
- 国际化策略：完全复用ClawX的翻译键结构，确保功能对齐
计划制定时间：2026-04-10 基于Skills功能分析报告制定