feat: 新增技能编排引擎和工作流构建器组件

refactor: 统一Hands系统常量到单个源文件 refactor: 更新Hands中文名称和描述 fix: 修复技能市场在连接状态变化时重新加载 fix: 修复身份变更提案的错误处理逻辑 docs: 更新多个功能文档的验证状态和实现位置 docs: 更新Hands系统文档 test: 添加测试文件验证工作区路径
2026-03-25 08:27:25 +08:00
parent 9c781f5f2a
commit aa6a9cbd84
110 changed files with 12384 additions and 1337 deletions
--- a/docs/features/04-skills-ecosystem/00-skill-system.md
+++ b/docs/features/04-skills-ecosystem/00-skill-system.md
@@ -3,7 +3,9 @@
 > **分类**: Skills 生态
 > **优先级**: P1 - 重要
 > **成熟度**: L4 - 生产
-> **最后更新**: 2026-03-16
+> **最后更新**: 2026-03-24
+
+> ✅ **实现更新**: Skills 动态扫描已实现。Kernel 集成了 `SkillRegistry`，支持通过 Tauri 命令 `skill_list` 和 `skill_refresh` 动态发现所有 **69 个**技能。**新增 `execute_skill` 工具**，允许 Agent 在对话中直接调用技能。

 ---

@@ -18,14 +20,38 @@ Skills 系统是 ZCLAW 的核心扩展机制，通过 SKILL.md 文件定义 Agen
 | 分类 | Skills 生态 |
 | 优先级 | P1 |
 | 成熟度 | L4 |
-| 依赖 | SkillDiscovery, AgentSwarm |
+| 依赖 | SkillRegistry (Rust), SkillDiscoveryEngine (TypeScript) |
+| SKILL.md 文件 | **69** |
+| **动态发现技能** | **69 (100%)** |
+| **execute_skill 工具** | **✅ 已实现** |

-### 1.2 相关文件
+### 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/` | 74 个 SKILL.md |
-| 发现引擎 | `desktop/src/lib/skill-discovery.ts` | 技能发现 |
+| 技能目录 | `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/` | 协作规则 |

@@ -219,7 +245,7 @@ const collaborationTriggers = [

 | 指标 | 基线 | 目标 | 当前 |
 |------|------|------|------|
-| 技能数量 | 0 | 50+ | 74 |
+| 技能数量 | 0 | 50+ | 69 |
 | 发现准确率 | 0% | 80% | 75% |
 | 技能使用率 | 0% | 60% | 50% |

@@ -229,14 +255,70 @@ const collaborationTriggers = [

 ### 5.1 已实现功能

- [x] 74 个技能定义
+- [x] 73 个 SKILL.md 技能定义
 - [x] 标准化模板
- [x] 发现引擎
+- [x] 发现引擎 (静态注册 12 个核心技能)
 - [x] 触发词匹配
 - [x] 协作规则
 - [x] Playbooks 集成
+- [x] SkillMarket UI 组件

-### 5.2 测试覆盖
+### 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)
 - **集成测试**: 完整流程测试
--- a/docs/features/04-skills-ecosystem/01-intelligent-routing.md
+++ b/docs/features/04-skills-ecosystem/01-intelligent-routing.md
@@ -0,0 +1,417 @@
+# 智能技能路由系统
+
+> **设计目标**: 让 ZCLAW 能智能地理解用户意图，自动选择和调用合适的技能，而不是依赖硬编码的触发词。
+
+---
+
+## 一、问题分析
+
+### 1.1 当前方案的问题
+
+```
+用户: "查询腾讯财报"
+       ↓
+硬编码触发词匹配: "财报" ∈ triggers?
+       ↓
+❌ 如果 triggers 中没有 "财报"，技能不会被调用
+```
+
+**问题**:
+1. **无法覆盖所有表达方式** - 用户可能说 "财务数据"、"盈利情况"、"营收报告"...
+2. **维护成本高** - 每个技能都需要维护触发词列表
+3. **无语义理解** - 无法理解 "帮我分析一下这家公司的赚钱能力" 也是财务分析
+
+### 1.2 设计目标
+
+```
+用户: "帮我分析一下腾讯最近赚了多少钱"
+       ↓
+语义理解: 意图 = 财务分析, 实体 = 腾讯, 指标 = 盈利
+       ↓
+智能路由: 最佳匹配技能 = finance-tracker
+       ↓
+✅ 自动调用 execute_skill("finance-tracker", {company: "腾讯", metrics: ["profit"]})
+```
+
+---
+
+## 二、智能路由架构
+
+### 2.1 三层架构
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     LLM Orchestrator                             │
+│  - 理解用户意图                                                   │
+│  - 决定是否需要调用技能                                           │
+│  - 选择最佳技能                                                   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   Semantic Skill Router                          │
+│  - 技能描述向量化                                                 │
+│  - 查询-技能语义匹配                                              │
+│  - Top-K 候选检索                                                │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                     Skill Registry                               │
+│  - 77 个技能的元数据                                              │
+│  - 描述、能力、示例                                               │
+│  - 向量索引                                                       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 路由流程
+
+```
+用户消息
+    │
+    ▼
+┌─────────────────────┐
+│ 1. 意图分类         │ ──→ 是否需要技能?
+│    (LLM 判断)       │     ├─ 否 → 直接对话
+└─────────────────────┘     └─ 是 ↓
+                                  │
+                                  ▼
+                    ┌─────────────────────┐
+                    │ 2. 语义检索         │ ──→ Top-3 候选技能
+                    │    (Embedding)      │     (基于描述相似度)
+                    └─────────────────────┘
+                                  │
+                                  ▼
+                    ┌─────────────────────┐
+                    │ 3. 精细选择         │ ──→ 最佳技能 + 参数
+                    │    (LLM 决策)       │     (考虑上下文、依赖)
+                    └─────────────────────┘
+                                  │
+                                  ▼
+                    ┌─────────────────────┐
+                    │ 4. 技能执行         │ ──→ 执行结果
+                    │    (execute_skill)  │
+                    └─────────────────────┘
+                                  │
+                                  ▼
+                              最终响应
+```
+
+---
+
+## 三、核心组件设计
+
+### 3.1 丰富的技能描述
+
+**问题**: 当前技能描述过于简单
+
+```yaml
+# 当前 (不够丰富)
+name: finance-tracker
+description: "财务追踪专家"
+triggers: ["财报", "财务分析"]
+```
+
+**改进**: 添加语义丰富的描述
+
+```yaml
+# 改进后
+name: finance-tracker
+description: |
+  财务追踪专家 - 专注于企业财务数据分析、财报解读、盈利能力评估。
+
+  核心能力:
+  - 财务报表分析 (资产负债表、利润表、现金流量表)
+  - 盈利能力指标 (毛利率、净利率、ROE、ROA)
+  - 营收增长分析 (同比、环比、复合增长率)
+  - 财务健康评估 (流动性、偿债能力、运营效率)
+
+  适用场景:
+  - 用户询问某公司的盈利、营收、利润
+  - 需要分析财务数据、财报数据
+  - 投资分析、估值计算
+  - 财务风险评估
+
+  不适用场景:
+  - 实时股价查询 → 使用 market-data
+  - 行业分析 → use industry-analyst
+  - 新闻资讯 → use news-collector
+
+examples:
+  - "腾讯去年赚了多少钱"
+  - "分析一下苹果的财务状况"
+  - "帮我看看这份财报"
+  - "这家公司的盈利能力如何"
+  - "对比一下阿里和京东的营收"
+
+capabilities:
+  - financial_analysis
+  - report_generation
+  - data_visualization
+```
+
+### 3.2 语义路由器实现
+
+```rust
+// crates/zclaw-kernel/src/skill_router.rs
+
+use std::sync::Arc;
+use serde::{Deserialize, Serialize};
+
+/// 技能路由结果
+#[derive(Debug, Clone)]
+pub struct RoutingResult {
+    pub skill_id: String,
+    pub confidence: f32,
+    pub parameters: serde_json::Value,
+    pub reasoning: String,
+}
+
+/// 语义技能路由器
+pub struct SemanticSkillRouter {
+    skills: Arc<SkillRegistry>,
+    embedder: Box<dyn Embedder>,
+    skill_embeddings: Vec<(String, Vec<f32>)>,
+}
+
+impl SemanticSkillRouter {
+    /// 检索 Top-K 候选技能
+    pub async fn retrieve_candidates(&self, query: &str, top_k: usize) -> Vec<(SkillManifest, f32)> {
+        // 1. 将查询向量化
+        let query_embedding = self.embedder.embed(query).await;
+
+        // 2. 计算与所有技能的相似度
+        let mut scores: Vec<_> = self.skill_embeddings
+            .iter()
+            .map(|(skill_id, embedding)| {
+                let similarity = cosine_similarity(&query_embedding, embedding);
+                (skill_id.clone(), similarity)
+            })
+            .collect();
+
+        // 3. 排序并返回 Top-K
+        scores.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap());
+        scores.truncate(top_k);
+
+        // 4. 返回技能元数据
+        scores.into_iter()
+            .filter_map(|(id, score)| {
+                self.skills.get(&id).map(|s| (s, score))
+            })
+            .collect()
+    }
+
+    /// 智能路由 - 结合语义检索和 LLM 决策
+    pub async fn route(&self, query: &str, context: &ConversationContext) -> Option<RoutingResult> {
+        // Step 1: 语义检索 Top-3 候选
+        let candidates = self.retrieve_candidates(query, 3).await;
+
+        if candidates.is_empty() {
+            return None;
+        }
+
+        // Step 2: 如果最高分超过阈值，直接返回
+        if candidates[0].1 > 0.85 {
+            let (skill, _) = &candidates[0];
+            return Some(RoutingResult {
+                skill_id: skill.id.to_string(),
+                confidence: candidates[0].1,
+                parameters: extract_parameters(query, &skill.id),
+                reasoning: format!("High semantic match ({}%)", (candidates[0].1 * 100.0) as i32),
+            });
+        }
+
+        // Step 3: 否则让 LLM 精细选择
+        self.llm_select_skill(query, candidates, context).await
+    }
+
+    /// LLM 精细选择
+    async fn llm_select_skill(
+        &self,
+        query: &str,
+        candidates: Vec<(SkillManifest, f32)>,
+        context: &ConversationContext,
+    ) -> Option<RoutingResult> {
+        let prompt = self.build_selection_prompt(query, &candidates, context);
+
+        // 调用 LLM 进行选择
+        let response = self.llm.complete(&prompt).await?;
+
+        // 解析 LLM 响应
+        parse_llm_routing_response(&response, candidates)
+    }
+
+    fn build_selection_prompt(
+        &self,
+        query: &str,
+        candidates: &[(SkillManifest, f32)],
+        context: &ConversationContext,
+    ) -> String {
+        format!(
+            r#"You are a skill router. Analyze the user query and select the best skill to handle it.
+
+## User Query
+{}
+
+## Conversation Context
+{}
+
+## Candidate Skills
+{}
+
+## Instructions
+1. Analyze the user's intent and required capabilities
+2. Select the MOST appropriate skill from the candidates
+3. Extract any parameters mentioned in the query
+4. If no skill is appropriate, respond with "none"
+
+## Response Format (JSON)
+{{
+  "selected_skill": "skill_id or null",
+  "confidence": 0.0-1.0,
+  "parameters": {{}},
+  "reasoning": "Brief explanation"
+}}
+"#,
+            query,
+            context.summary(),
+            candidates.iter()
+                .map(|(s, score)| format!("- {} ({}%): {}", s.id, (score * 100.0) as i32, s.description))
+                .collect::<Vec<_>>()
+                .join("\n")
+        )
+    }
+}
+
+fn cosine_similarity(a: &[f32], b: &[f32]) -> f32 {
+    let dot: f32 = a.iter().zip(b.iter()).map(|(x, y)| x * y).sum();
+    let norm_a: f32 = a.iter().map(|x| x * x).sum::<f32>().sqrt();
+    let norm_b: f32 = b.iter().map(|x| x * x).sum::<f32>().sqrt();
+    dot / (norm_a * norm_b + 1e-10)
+}
+```
+
+### 3.3 系统提示词增强
+
+```rust
+// 在 kernel.rs 中
+
+/// 构建智能技能提示
+fn build_skill_aware_system_prompt(&self, base_prompt: Option<&String>) -> String {
+    let mut prompt = base_prompt
+        .map(|p| p.clone())
+        .unwrap_or_else(|| "You are ZCLAW, an intelligent AI assistant.".to_string());
+
+    prompt.push_str("\n\n## Your Capabilities\n\n");
+    prompt.push_str("You have access to specialized skills. Use the `execute_skill` tool when:\n");
+    prompt.push_str("- The user's request matches a skill's domain\n");
+    prompt.push_str("- You need specialized expertise for a task\n");
+    prompt.push_str("- The task would benefit from a structured workflow\n\n");
+
+    prompt.push_str("**Important**: You should autonomously decide when to use skills based on your understanding of the user's intent. ");
+    prompt.push_str("Do not wait for explicit skill names - recognize the need and act.\n\n");
+
+    prompt.push_str("## Available Skills\n\n");
+
+    // 注入技能摘要 (不是完整列表，减少 token)
+    let skills = futures::executor::block_on(self.skills.list());
+    for skill in skills.iter().take(20) {  // 只展示前 20 个最相关的
+        prompt.push_str(&format!(
+            "- **{}**: {}\n",
+            skill.id.as_str(),
+            &skill.description[..skill.description.char_indices().take(100).last().map(|(i, _)| i).unwrap_or(skill.description.len())]
+        ));
+    }
+
+    if skills.len() > 20 {
+        prompt.push_str(&format!("\n... and {} more skills available.\n", skills.len() - 20));
+    }
+
+    prompt
+}
+```
+
+---
+
+## 四、实现计划
+
+### Phase 1: 基础架构 (当前)
+
+- [x] 在系统提示词中注入技能列表
+- [x] 添加 `triggers` 字段到 SkillManifest
+- [x] 更新 SKILL.md 解析器
+
+### Phase 2: 语义路由
+
+1. **集成 Embedding 模型**
+   - 使用本地模型 (如 `all-MiniLM-L6-v2`)
+   - 或调用 LLM API 获取 embedding
+
+2. **构建技能向量索引**
+   - 启动时预计算所有技能描述的 embedding
+   - 支持增量更新
+
+3. **实现 Hybrid Router**
+   - 语义检索 Top-K 候选
+   - LLM 精细选择
+
+### Phase 3: 智能编排
+
+1. **多技能协调**
+   - 识别需要多个技能的任务
+   - 自动编排执行顺序
+
+2. **上下文感知**
+   - 根据对话历史调整技能选择
+   - 记住用户偏好
+
+3. **自主学习**
+   - 记录用户反馈
+   - 优化路由策略
+
+---
+
+## 五、技术选型
+
+### 5.1 Embedding 模型
+
+| 选项 | 优点 | 缺点 |
+|------|------|------|
+| **本地 `all-MiniLM-L6-v2`** | 快速、离线、免费 | 需要额外依赖 |
+| **LLM API Embedding** | 高质量 | 需要网络、有成本 |
+| **OpenAI text-embedding-3-small** | 高质量、多语言 | 需要付费 |
+
+**推荐**: 使用 LLM Provider 的 embedding API (如果支持)，否则使用本地模型。
+
+### 5.2 向量存储
+
+| 选项 | 适用场景 |
+|------|---------|
+| **内存 HashMap** | 技能数量 < 100 |
+| **SQLite + vec** | 持久化、简单 |
+| **Qdrant/Chroma** | 大规模、需要过滤 |
+
+**推荐**: 对于 77 个技能，内存 HashMap 足够。
+
+---
+
+## 六、参考资料
+
+- [LLM Skills vs Tools: The Missing Layer in Agent Design](https://www.abstractalgorithms.dev/llm-skills-vs-tools-in-agent-design)
+- [Tool Selection for LLM Agents: Routing Strategies](https://mbrenndoerfer.com/writing/tool-selection-llm-agents-routing-strategies)
+- [Semantic Tool Selection](https://vllm-semantic-router.com/zh-Hans/blog/semantic-tool-selection)
+
+---
+
+## 七、总结
+
+**核心原则**:
+1. **让 LLM 自主决策** - 不要硬编码触发词
+2. **语义理解优于关键词匹配** - 理解用户意图
+3. **Hybrid 是最佳实践** - embedding 过滤 + LLM 决策
+4. **丰富的描述是关键** - 技能描述要有示例、边界、能力
+
+**下一步**:
+1. 实现语义路由器原型
+2. 增强技能描述
+3. 测试和优化