zn-ai/docs/Skills-Development-Plan.md

zn-ai 技能功能开发计划

项目概述

本计划旨在将 ClawX 项目的 Skills（技能）功能完整迁移到 zn-ai 项目中，并保持功能一致性、代码完整性和用户体验对齐。基于对 ClawX Skills 功能的深入分析，制定本四阶段开发计划。

技术栈映射与适配策略

技术栈差异

领域	ClawX (源项目)	zn-ai (目标项目)	适配策略
前端框架	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	自定义消息树	翻译键迁移，保持相同结构
构建工具	Vite	Vite	直接兼容

核心挑战与解决方案

1. UI一致性：通过Tailwind CSS自定义样式实现类似视觉效果
2. 状态管理：将Zustand的全局store转换为组件本地状态（useState + useEffect）
3. 组件交互：直接复用React的props/callback模式
4. 响应式系统：使用React的useState/useRef管理状态和副作用

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

目标

建立技能功能的基础架构，包括类型定义、状态管理骨架和核心API接口。

具体任务

1.1 类型定义创建

文件: src/lib/skills-types.ts

// 复用ClawX的Skill和MarketplaceSkill类型定义
// 根据zn-ai的命名规范进行适当调整

文件: src/lib/skill-config.ts

// 技能配置相关的类型和工具函数
// 包括配置schema、验证逻辑等

1.2 状态管理

文件: src/pages/Skills/index.tsx（组件本地状态）

// 使用React useState/useRef管理：
// - 技能列表、搜索结果、加载状态等核心状态
// - fetchSkills、searchSkills、installSkill等核心逻辑
// - 错误处理逻辑

1.3 API客户端适配

文件: src/lib/skills-api.ts

// 封装技能相关的API调用
// 与现有的host-api.ts或axios封装集成
// 包含：获取技能列表、搜索市场、安装/卸载等接口

1.4 国际化资源

文件: src/pages/Skills/messages.ts

// 从ClawX项目迁移翻译键
// 保持相同的键结构，确保功能一致性
// 包含 en/zh/ja 三种语言的消息树

交付成果

• 完整的TypeScript类型定义
• 组件本地状态管理（可编译通过）
• API客户端接口定义
• 多语言消息树（en/zh/ja）
• 无TypeScript编译错误

阶段二：核心UI组件开发 (预计：2-3天)

目标

开发技能功能的主要UI组件，包括技能列表、详情面板和市场搜索界面。

具体任务

2.1 主页面组件

文件: src/pages/Skills/index.tsx

// 主容器，包含：
// 1. 头部区域：标题、副标题、打开文件夹按钮
// 2. 网关状态警告（如适用）
// 3. 导航与筛选：搜索框、来源筛选选项卡
// 4. 批量操作工具栏
// 5. 技能列表区域
// 使用React Hooks实现：
// - 搜索和筛选逻辑
// - 批量操作处理
// - 组件本地状态管理

2.2 技能列表项组件

文件: src/pages/Skills/components/SkillListItem.tsx

// 单个技能卡片的展示组件
// 包含：图标、名称、描述、状态开关、来源标签等

2.3 技能详情弹窗组件

文件: src/pages/Skills/components/SkillDetailDrawer.tsx

// 右侧滑出式详情面板
// 包含：技能基本信息、API密钥配置、环境变量管理、路径操作等

2.4 市场搜索弹窗组件

文件: src/pages/Skills/components/MarketplaceDrawer.tsx

// 技能市场搜索和安装界面
// 包含：搜索框、搜索结果列表、安装/卸载按钮

2.5 环境变量管理组件

文件: src/pages/Skills/components/EnvVarManager.tsx

// 动态环境变量表单
// 支持添加、编辑、删除环境变量键值对

UI/UX设计要点

1. 视觉风格：使用Tailwind CSS自定义样式实现类似ClawX的视觉效果
2. 交互设计：
   • 点击技能卡片打开详情
   • 状态开关的即时反馈
   • 搜索输入的防抖处理（300ms）
   • 批量操作的成功/失败提示
3. 响应式设计：确保桌面端良好的显示效果

交付成果

• 完整的技能管理页面（可交互但数据为模拟）
• 详情弹窗组件（包含配置表单）
• 市场搜索界面
• 基本的样式和交互效果

阶段三：功能集成与数据绑定 (预计：2-3天)

目标

将UI组件与状态管理和后端API进行集成，实现完整的数据流和业务逻辑。

具体任务

3.1 核心逻辑实现

完善: src/pages/Skills/index.tsx

// 实现所有核心逻辑：
// - loadSkills(): 集成真实API调用
// - handleSearch(): 连接市场搜索API
// - handleInstall()/handleUninstall(): 安装/卸载逻辑
// - handleToggle(): 启用/禁用技能
// - 错误处理：超时、频率限制等
// - 批量操作：串行容错模式

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 组件数据绑定

更新各React组件：

• 将UI组件连接到组件本地状态
• 使用props和callback传递数据
• 添加加载状态和错误处理
• 实现表单验证和提交逻辑

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          # 技能配置工具
├── pages/
│   └── Skills/
│       ├── index.tsx            # 技能主页面
│       ├── messages.ts          # 多语言消息树（en/zh/ja）
│       ├── copy.ts              # 文案hook
│       └── components/
│           ├── SkillListItem.tsx        # 技能列表项
│           ├── SkillDetailDrawer.tsx    # 技能详情抽屉
│           ├── MarketplaceDrawer.tsx    # 市场搜索抽屉
│           ├── EnvVarManager.tsx        # 环境变量管理
│           └── icons.tsx                # 图标组件

后端集成考虑

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

---

计划制定时间：2026-04-10 基于Skills功能分析报告制定