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` 类型作为标准：

```typescript
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` 类型做适配：

```typescript
// 适配映射
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 系统概述](../features/04-skills-ecosystem/00-skill-system.md)
- [状态管理文档](../features/00-architecture/02-state-management.md)
- [通信层文档](../features/00-architecture/01-communication-layer.md)

### 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` - 完整模板示例