aa6a9cbd84
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
refactor: 统一Hands系统常量到单个源文件 refactor: 更新Hands中文名称和描述 fix: 修复技能市场在连接状态变化时重新加载 fix: 修复身份变更提案的错误处理逻辑 docs: 更新多个功能文档的验证状态和实现位置 docs: 更新Hands系统文档 test: 添加测试文件验证工作区路径
371 lines
9.0 KiB
Markdown
371 lines
9.0 KiB
Markdown
# Skills 系统概述 (Skill System)
|
||
|
||
> **分类**: Skills 生态
|
||
> **优先级**: P1 - 重要
|
||
> **成熟度**: L4 - 生产
|
||
> **最后更新**: 2026-03-24
|
||
|
||
> ✅ **实现更新**: Skills 动态扫描已实现。Kernel 集成了 `SkillRegistry`，支持通过 Tauri 命令 `skill_list` 和 `skill_refresh` 动态发现所有 **69 个**技能。**新增 `execute_skill` 工具**，允许 Agent 在对话中直接调用技能。
|
||
|
||
---
|
||
|
||
## 一、功能概述
|
||
|
||
### 1.1 基本信息
|
||
|
||
Skills 系统是 ZCLAW 的核心扩展机制，通过 SKILL.md 文件定义 Agent 的专业技能，支持自动发现和推荐。
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 分类 | Skills 生态 |
|
||
| 优先级 | P1 |
|
||
| 成熟度 | L4 |
|
||
| 依赖 | SkillRegistry (Rust), SkillDiscoveryEngine (TypeScript) |
|
||
| SKILL.md 文件 | **69** |
|
||
| **动态发现技能** | **69 (100%)** |
|
||
| **execute_skill 工具** | **✅ 已实现** |
|
||
|
||
### 1.2 动态扫描实现
|
||
|
||
**架构变更 (2026-03-24)**:
|
||
- Kernel 结构体添加 `skills: Arc<SkillRegistry>` 字段
|
||
- KernelConfig 添加 `skills_dir: Option<PathBuf>` 配置
|
||
- 新增 Tauri 命令 `skill_list` 和 `skill_refresh`
|
||
- 前端 `SkillDiscoveryEngine` 从后端动态加载技能
|
||
|
||
**数据流**:
|
||
```
|
||
kernel_init()
|
||
→ SkillRegistry::new()
|
||
→ SkillRegistry::add_skill_dir("skills/")
|
||
→ discover_skills() 扫描 SKILL.md
|
||
→ 前端调用 skill_list 获取技能
|
||
```
|
||
|
||
### 1.3 相关文件
|
||
|
||
| 文件 | 路径 | 用途 |
|
||
|------|------|------|
|
||
| 技能目录 | `skills/` | 69 个 SKILL.md |
|
||
| Rust 注册中心 | `crates/zclaw-skills/src/registry.rs` | 技能注册和发现 |
|
||
| Rust 加载器 | `crates/zclaw-skills/src/loader.rs` | SKILL.md 解析 |
|
||
| Kernel 集成 | `crates/zclaw-kernel/src/kernel.rs` | Kernel 集成 SkillRegistry |
|
||
| Tauri 命令 | `desktop/src-tauri/src/kernel_commands.rs` | skill_list, skill_refresh |
|
||
| 前端发现引擎 | `desktop/src/lib/skill-discovery.ts` | 从后端加载技能 |
|
||
| 模板 | `skills/.templates/skill-template.md` | 技能模板 |
|
||
| 协调规则 | `skills/.coordination/` | 协作规则 |
|
||
|
||
---
|
||
|
||
## 二、设计初衷
|
||
|
||
### 2.1 问题背景
|
||
|
||
**用户痛点**:
|
||
1. 单一 Agent 能力有限
|
||
2. 不同任务需要不同专业技能
|
||
3. 技能定义缺乏标准
|
||
|
||
**系统缺失能力**:
|
||
- 缺乏标准化的技能定义
|
||
- 缺乏技能发现机制
|
||
- 缺乏多技能协作
|
||
|
||
**为什么需要**:
|
||
标准化的技能系统让 Agent 可以动态获得专业能力，支持多 Agent 协作。
|
||
|
||
### 2.2 设计目标
|
||
|
||
1. **标准化**: SKILL.md 统一格式
|
||
2. **可发现**: 自动发现和推荐技能
|
||
3. **可组合**: 多技能协作
|
||
4. **可扩展**: 易于添加新技能
|
||
|
||
### 2.3 SKILL.md 格式
|
||
|
||
```yaml
|
||
---
|
||
name: skill-name
|
||
description: "简短描述"
|
||
triggers:
|
||
- "触发词1"
|
||
- "触发词2"
|
||
tools:
|
||
- bash
|
||
- read
|
||
- write
|
||
---
|
||
|
||
## Identity & Memory
|
||
[角色定义、性格、专业技能]
|
||
|
||
## Core Mission
|
||
[负责与不负责的边界]
|
||
|
||
## Core Capabilities
|
||
[具体能力描述]
|
||
|
||
## Workflow Process
|
||
[标准化工作流程]
|
||
|
||
## Deliverable Format
|
||
[交付物格式]
|
||
|
||
## Collaboration Triggers
|
||
[何时调用其他 Agent]
|
||
|
||
## Critical Rules
|
||
[关键约束]
|
||
|
||
## Success Metrics
|
||
[成功指标]
|
||
```
|
||
|
||
### 2.4 设计约束
|
||
|
||
- **格式约束**: 必须遵循 SKILL.md 模板
|
||
- **性能约束**: 发现不能阻塞主流程
|
||
- **可读约束**: 人类可读，机器可解析
|
||
|
||
---
|
||
|
||
## 三、技术设计
|
||
|
||
### 3.1 技能分类
|
||
|
||
| 分类 | 技能数 | 代表技能 |
|
||
|------|--------|---------|
|
||
| 开发工程 | 15+ | ai-engineer, senior-developer, backend-architect |
|
||
| 协调管理 | 8+ | agents-orchestrator, project-shepherd |
|
||
| 测试质量 | 6+ | code-reviewer, reality-checker, evidence-collector |
|
||
| 设计体验 | 8+ | ux-architect, brand-guardian, ui-designer |
|
||
| 数据分析 | 5+ | analytics-reporter, performance-benchmarker |
|
||
| 社媒营销 | 12+ | twitter-engager, xiaohongshu-specialist |
|
||
| 中文平台 | 5+ | chinese-writing, feishu-docs, wechat-oa |
|
||
| XR/空间 | 4+ | visionos-spatial-engineer, xr-immersive-dev |
|
||
|
||
### 3.2 发现引擎
|
||
|
||
```typescript
|
||
interface SkillDiscovery {
|
||
// 搜索技能
|
||
search(query: string, options?: SearchOptions): Promise<Skill[]>;
|
||
|
||
// 推荐技能
|
||
recommend(context: TaskContext): Promise<Skill[]>;
|
||
|
||
// 解析技能文件
|
||
parse(content: string): Skill;
|
||
|
||
// 列出所有技能
|
||
listAll(): Promise<Skill[]>;
|
||
}
|
||
|
||
interface Skill {
|
||
name: string;
|
||
description: string;
|
||
triggers: string[];
|
||
tools: string[];
|
||
capabilities: string[];
|
||
collaborationTriggers: string[];
|
||
filePath: string;
|
||
}
|
||
```
|
||
|
||
### 3.3 发现流程
|
||
|
||
```
|
||
任务上下文
|
||
│
|
||
▼
|
||
关键词提取
|
||
│
|
||
├──► 从任务描述提取
|
||
└──► 从历史行为提取
|
||
│
|
||
▼
|
||
技能匹配
|
||
│
|
||
├──► 触发词匹配
|
||
├──► 能力匹配
|
||
└──► 语义相似度
|
||
│
|
||
▼
|
||
排序推荐
|
||
│
|
||
├──► 相关性排序
|
||
├──► 历史成功率
|
||
└──► 用户偏好
|
||
│
|
||
▼
|
||
返回 Top-N
|
||
```
|
||
|
||
### 3.4 协作触发
|
||
|
||
```typescript
|
||
// 技能可以定义何时调用其他技能
|
||
const collaborationTriggers = [
|
||
{
|
||
condition: "任务涉及 UI 设计",
|
||
action: "调用 ux-architect"
|
||
},
|
||
{
|
||
condition: "代码需要审查",
|
||
action: "调用 code-reviewer"
|
||
},
|
||
{
|
||
condition: "部署到生产",
|
||
action: "调用 security-engineer"
|
||
}
|
||
];
|
||
```
|
||
|
||
---
|
||
|
||
## 四、预期作用
|
||
|
||
### 4.1 用户价值
|
||
|
||
| 价值类型 | 描述 |
|
||
|---------|------|
|
||
| 能力扩展 | 获得专业能力 |
|
||
| 效率提升 | 自动匹配技能 |
|
||
| 质量保证 | 专业技能保证质量 |
|
||
|
||
### 4.2 系统价值
|
||
|
||
| 价值类型 | 描述 |
|
||
|---------|------|
|
||
| 架构收益 | 可扩展的能力系统 |
|
||
| 可维护性 | 标准化易于管理 |
|
||
| 可扩展性 | 易于添加新技能 |
|
||
|
||
### 4.3 成功指标
|
||
|
||
| 指标 | 基线 | 目标 | 当前 |
|
||
|------|------|------|------|
|
||
| 技能数量 | 0 | 50+ | 69 |
|
||
| 发现准确率 | 0% | 80% | 75% |
|
||
| 技能使用率 | 0% | 60% | 50% |
|
||
|
||
---
|
||
|
||
## 五、实际效果
|
||
|
||
### 5.1 已实现功能
|
||
|
||
- [x] 73 个 SKILL.md 技能定义
|
||
- [x] 标准化模板
|
||
- [x] 发现引擎 (静态注册 12 个核心技能)
|
||
- [x] 触发词匹配
|
||
- [x] 协作规则
|
||
- [x] Playbooks 集成
|
||
- [x] SkillMarket UI 组件
|
||
|
||
### 5.2 技能分类统计
|
||
|
||
| 分类 | 数量 | 代表技能 |
|
||
|------|------|---------|
|
||
| 开发工程 | 15 | frontend-developer, backend-architect, ai-engineer |
|
||
| 测试/QA | 5 | code-review, api-tester, accessibility-auditor |
|
||
| 设计/UX | 5 | ui-designer, ux-architect, visual-storyteller |
|
||
| 安全 | 2 | security-engineer, legal-compliance-checker |
|
||
| 数据分析 | 5 | data-analysis, analytics-reporter, evidence-collector |
|
||
| 运维/DevOps | 4 | devops-automator, infrastructure-maintainer |
|
||
| 管理/PM | 8 | senior-pm, project-shepherd, agents-orchestrator |
|
||
| 营销/社媒 | 12 | twitter-engager, xiaohongshu-specialist, zhihu-strategist |
|
||
| 内容/写作 | 4 | chinese-writing, translation, content-creator |
|
||
| 研究 | 3 | trend-researcher, feedback-synthesizer |
|
||
| 商务/销售 | 3 | sales-data-extraction-agent, report-distribution-agent |
|
||
| 教育 | 2 | classroom-generator, agentic-identity-trust |
|
||
| 核心工具 | 4 | git, file-operations, web-search, shell-command |
|
||
|
||
### 5.3 实现说明
|
||
|
||
**✅ 已实现动态扫描 (2026-03-24)**:
|
||
- Kernel 集成 `SkillRegistry`，启动时自动扫描 `skills/` 目录
|
||
- 前端通过 Tauri 命令 `skill_list` 获取所有技能
|
||
- 支持 `skill_refresh` 命令重新扫描指定目录
|
||
- 73 个技能全部可被发现
|
||
|
||
**数据结构映射**:
|
||
```typescript
|
||
// 前端 SkillInfo (保留兼容)
|
||
interface SkillInfo {
|
||
id: string;
|
||
name: string;
|
||
description: string;
|
||
triggers: string[]; // 从 tags 映射
|
||
capabilities: string[];
|
||
toolDeps: string[]; // 后端暂无
|
||
installed: boolean; // 从 enabled 映射
|
||
category?: string; // 从 tags[0] 映射
|
||
version?: string;
|
||
mode?: string;
|
||
}
|
||
|
||
// 后端 SkillManifest (Rust)
|
||
struct SkillManifest {
|
||
id: SkillId,
|
||
name: String,
|
||
description: String,
|
||
version: String,
|
||
mode: SkillMode,
|
||
capabilities: Vec<String>,
|
||
tags: Vec<String>,
|
||
enabled: bool,
|
||
}
|
||
```
|
||
|
||
### 5.4 测试覆盖
|
||
|
||
- **单元测试**: 43 项 (swarm-skills.test.ts)
|
||
- **集成测试**: 完整流程测试
|
||
- **覆盖率**: ~90%
|
||
|
||
### 5.3 已知问题
|
||
|
||
| 问题 | 严重程度 | 状态 | 计划解决 |
|
||
|------|---------|------|---------|
|
||
| 语义匹配精度待提高 | 中 | 待优化 | Q2 |
|
||
| 技能质量参差不齐 | 低 | 持续改进 | - |
|
||
|
||
### 5.4 用户反馈
|
||
|
||
技能覆盖全面，但发现准确性需要提高。
|
||
|
||
---
|
||
|
||
## 六、演化路线
|
||
|
||
### 6.1 短期计划（1-2 周）
|
||
- [ ] 优化发现算法
|
||
- [ ] 添加技能评分
|
||
|
||
### 6.2 中期计划（1-2 月）
|
||
- [ ] 技能市场 UI
|
||
- [ ] 用户自定义技能
|
||
|
||
### 6.3 长期愿景
|
||
- [ ] 技能共享社区
|
||
- [ ] 技能认证体系
|
||
|
||
---
|
||
|
||
## 七、头脑风暴笔记
|
||
|
||
### 7.1 待讨论问题
|
||
1. 是否需要技能版本控制？
|
||
2. 如何处理技能冲突？
|
||
|
||
### 7.2 创意想法
|
||
- 技能组合：多个技能组合成新技能
|
||
- 技能学习：从用户行为学习新技能
|
||
- 技能热力图：可视化技能使用频率
|
||
|
||
### 7.3 风险与挑战
|
||
- **技术风险**: 技能匹配精度
|
||
- **质量风险**: 技能定义质量
|
||
- **缓解措施**: 评分系统，社区审核
|