zclaw_openfang/docs/plans/skill-market-mvp.md

Skill Market MVP 实现计划

创建日期: 2026-03-20 状态: 研究完成，待实现 优先级: P1 - 中期计划 (M2)

---

一、背景研究

1.1 现有代码分析

经过代码审查，发现以下关键组件已存在但需要集成和完善：

已存在组件

组件	路径	状态	问题
SkillMarket.tsx	desktop/src/components/SkillMarket.tsx	已实现	使用本地 SkillDiscoveryEngine，未接入后端
skillMarketStore.ts	desktop/src/store/skillMarketStore.ts	已实现	使用硬编码技能列表，未接入 configStore
skill-discovery.ts	desktop/src/lib/skill-discovery.ts	已实现	使用 localStorage + 静态技能注册表
skill-market.ts (类型)	desktop/src/types/skill-market.ts	已实现	Skill/SkillReview/SkillMarketState 类型
configStore.ts	desktop/src/store/configStore.ts	已实现	包含 skillsCatalog 和技能 CRUD 方法
gateway-api.ts	desktop/src/lib/gateway-api.ts	已实现	包含 listSkills/getSkill/createSkill 等方法

技能定义文件

• skills/ 目录包含 74 个 SKILL.md 文件
• 格式: YAML frontmatter + Markdown 正文
• 包含: name, description, triggers, tools, capabilities 等

1.2 当前架构问题

1. 双轨系统: SkillMarket.tsx 使用 SkillDiscoveryEngine，但 configStore.ts 已有完整的技能管理逻辑
2. 硬编码技能: skillMarketStore.ts 的 scanSkillsDirectory() 返回硬编码列表，未读取实际 SKILL.md
3. 后端未连接: 组件未通过 GatewayClient 与后端 /api/skills 通信
4. 安装状态不同步: skillMarketStore 和 configStore 各自维护 installed 状态

1.3 数据流现状

当前（问题）:
SkillMarket.tsx → SkillDiscoveryEngine → localStorage
                              ↓
                    BUILT_IN_SKILLS (硬编码 12 个)

configStore.ts → GatewayClient → /api/skills (后端)
        ↓
  skillsCatalog (从后端获取)

---

二、MVP 功能范围

2.1 核心功能

功能	优先级	描述
技能浏览	P0	展示所有可用技能，支持分类筛选
技能搜索	P0	按名称、触发词、能力搜索
技能详情	P0	展示技能详细信息（能力、触发词、工具依赖）
安装/卸载	P0	切换技能启用状态，持久化到后端
分类过滤	P1	按类别筛选技能

2.2 MVP 不包含

• 技能评分和评论（已有代码但 MVP 不启用）
• 技能推荐引擎（suggestSkills 功能）
• 技能市场在线同步
• 技能版本管理
• 自定义技能创建

2.3 技能卡片信息

每张技能卡片需要展示：

┌─────────────────────────────────────┐
│ [图标] 技能名称          [已安装?]  │
│ 简短描述（1-2 行）                  │
│ ┌─────────┐ ┌──────────┐            │
│ │ 分类标签 │ │ 能力标签 │ ...        │
│ └─────────┘ └──────────┘            │
│                                     │
│ 展开后:                              │
│ 触发词: [词1] [词2] [词3]           │
│ 能力: [能力1] [能力2] [能力3]       │
│ 工具依赖: [read] [write] [bash]     │
│                                     │
│              [安装] 或 [卸载]        │
└─────────────────────────────────────┘

---

三、技术架构

3.1 目标数据流

目标架构:
SkillMarket.tsx → useConfigStore → GatewayClient → /api/skills
       ↓
  skillsCatalog (统一来源)
       ↓
  安装状态 → GatewayClient.updateSkill() → 后端

3.2 组件依赖关系

App.tsx
  └── SkillMarket.tsx (重构)
        ├── useConfigStore (替代 SkillDiscoveryEngine)
        ├── SkillCard (保留，增强)
        ├── CategoryBadge (保留)
        └── SuggestionCard (MVP 隐藏)

3.3 类型统一

使用 configStore.ts 中的 SkillInfo 类型作为标准：

interface SkillInfo {
  id: string;
  name: string;
  path: string;
  source: 'builtin' | 'extra';
  description?: string;
  triggers?: Array<{ type: string; pattern?: string }>;
  actions?: Array<{ type: string; params?: Record<string, unknown> }>;
  enabled?: boolean;
}

需要与 skill-market.ts 中的 Skill 类型做适配：

// 适配映射
function adaptSkillInfo(info: SkillInfo): Skill {
  return {
    id: info.id,
    name: info.name,
    description: info.description || '',
    triggers: info.triggers?.map(t => t.pattern || t.type) || [],
    capabilities: info.actions?.map(a => a.type) || [],
    category: extractCategory(info.path),
    installed: info.enabled || false,
  };
}

---

四、实现步骤

Phase 1: Store 统一 (1-2 天)

目标: 让 SkillMarket 使用 configStore 而非 SkillDiscoveryEngine

任务清单

• 1.1 分析 configStore.skillsCatalog 返回的数据结构
• 1.2 创建类型适配器 adaptSkillInfo()
• 1.3 修改 SkillMarket.tsx 使用 useConfigStore
• 1.4 移除对 SkillDiscoveryEngine 的直接依赖
• 1.5 测试技能列表加载

文件变更

文件	操作
desktop/src/components/SkillMarket.tsx	修改
desktop/src/lib/skill-adapter.ts	新建

Phase 2: 后端集成 (2-3 天)

目标: 实现真正的安装/卸载功能

任务清单

• 2.1 验证 /api/skills 端点可用性
• 2.2 实现 installSkill() 调用 updateSkill(id, { enabled: true })
• 2.3 实现 uninstallSkill() 调用 updateSkill(id, { enabled: false })
• 2.4 添加加载状态和错误处理
• 2.5 添加乐观更新和回滚机制

文件变更

文件	操作
desktop/src/store/configStore.ts	修改（增强 updateSkill）
desktop/src/components/SkillMarket.tsx	修改（安装/卸载逻辑）

Phase 3: 搜索和分类 (1-2 天)

目标: 完善搜索和分类过滤功能

任务清单

• 3.1 实现前端搜索过滤（基于 skillsCatalog）
• 3.2 从技能列表提取所有分类
• 3.3 实现分类过滤 UI
• 3.4 优化搜索性能（防抖、缓存）

文件变更

文件	操作
desktop/src/components/SkillMarket.tsx	修改
desktop/src/hooks/useSkillSearch.ts	新建（可选）

Phase 4: UI 完善 (1-2 天)

目标: 提升用户体验

任务清单

• 4.1 优化技能卡片展开动画
• 4.2 添加安装/卸载确认提示
• 4.3 添加空状态展示
• 4.4 添加加载骨架屏
• 4.5 优化响应式布局

文件变更

文件	操作
desktop/src/components/SkillMarket.tsx	修改
desktop/src/components/SkillCardSkeleton.tsx	新建

Phase 5: 测试和文档 (1 天)

目标: 确保质量和可维护性

任务清单

• 5.1 添加单元测试
• 5.2 添加集成测试
• 5.3 更新功能文档
• 5.4 更新用户手册

文件变更

文件	操作
tests/desktop/skill-market.test.ts	新建
docs/features/04-skills-ecosystem/02-skill-discovery.md	更新

---

五、文件变更清单

新建文件

文件路径	用途
desktop/src/lib/skill-adapter.ts	SkillInfo <-> Skill 类型适配
desktop/src/hooks/useSkillSearch.ts	技能搜索 hook（可选）
desktop/src/components/SkillCardSkeleton.tsx	加载骨架屏
tests/desktop/skill-market.test.ts	测试文件

修改文件

文件路径	变更内容
desktop/src/components/SkillMarket.tsx	使用 configStore，优化 UI
desktop/src/store/configStore.ts	增强 updateSkill，添加乐观更新
docs/features/04-skills-ecosystem/02-skill-discovery.md	更新文档
docs/features/README.md	更新集成状态

可删除文件

文件路径	原因
desktop/src/store/skillMarketStore.ts	合并到 configStore 后废弃
desktop/src/types/skill-market.ts	使用 configStore 类型替代

---

六、风险和缓解

6.1 技术风险

风险	可能性	影响	缓解措施
后端 /api/skills 未返回完整数据	中	高	添加 fallback 到本地技能列表
类型不兼容	低	中	创建适配器层
性能问题（74个技能渲染）	低	低	虚拟滚动（后期优化）

6.2 用户体验风险

风险	可能性	影响	缓解措施
安装状态不同步	中	高	使用单一数据源（configStore）
搜索不准确	中	中	优化搜索算法，支持触发词匹配
操作无反馈	低	中	添加 Toast 提示

---

七、验收标准

7.1 功能验收

• 能加载并显示所有 74 个技能
• 搜索功能正常工作
• 分类过滤功能正常工作
• 安装/卸载操作能持久化
• 刷新页面后状态保持

7.2 性能验收

• 首次加载 < 1s
• 搜索响应 < 200ms
• 列表滚动流畅（60fps）

7.3 质量验收

• 无 TypeScript 错误
• 无 ESLint 警告
• 测试覆盖率 > 80%

---

八、时间估算

阶段	估算时间	依赖
Phase 1: Store 统一	1-2 天	无
Phase 2: 后端集成	2-3 天	Phase 1
Phase 3: 搜索和分类	1-2 天	Phase 2
Phase 4: UI 完善	1-2 天	Phase 3
Phase 5: 测试和文档	1 天	Phase 4
总计	6-10 天	-

---

九、后续迭代方向

9.1 短期优化

• 技能推荐引擎（基于对话上下文）
• 技能使用统计
• 技能收藏功能

9.2 中期扩展

• 技能创建向导
• 技能导入/导出
• 技能市场在线同步

9.3 长期愿景

• 技能共享社区
• 技能认证体系
• 技能版本管理

---

十、参考资料

10.1 相关文档

• Skills 系统概述
• 状态管理文档
• 通信层文档

10.2 相关代码

• desktop/src/lib/skill-discovery.ts - 技能发现引擎
• desktop/src/store/configStore.ts - 配置状态管理
• desktop/src/lib/gateway-api.ts - API 方法实现
• skills/.templates/skill-template.md - 技能模板

10.3 技能文件示例

• skills/code-review/SKILL.md - 简单格式示例
• skills/data-analysis/SKILL.md - 带表格示例
• skills/devops-automator/SKILL.md - 完整模板示例