Skills 技能架构文档

历史路径说明

文中部分代码路径来自历史阶段，保留它们是为了说明演进关系。

真正继续实现时，请以当前 desktop/ 工作区中的技能实现为准。

这篇文档暂时保留作架构整理参考，还没有进入首批正式导航。

概述

Skills（技能）系统是 Agent 的能力扩展模块，允许为 Agent 绑定特定的技能配置，以增强 Agent 在特定场景下的能力。技能可以是工作流、工具集或自定义脚本。

功能特性

1. 技能管理

功能	说明
技能列表	获取所有可用技能
技能详情	获取指定技能的详细信息
技能校验	验证技能配置的有效性

2. Agent 技能绑定

功能	说明
绑定技能	为 Agent 绑定技能
解绑技能	移除 Agent 的技能绑定
绑定模式	支持多种绑定模式

3. 绑定模式

模式	说明
summary_only	仅在摘要中使用
on_demand	按需调用
always	始终启用
full	完全模式
summary	摘要模式

技术架构

目录结构

archive/desktop-legacy/src-tauri/src/
├── runtime/
│   └── skills.rs              # Skills 运行时核心
├── commands/
│   └── skills.rs             # Tauri 命令接口
archive/desktop-legacy/src/
├── services/
│   └── skillApi.ts           # 前端 API 服务
└── pages/
    └── Agent/
        └── SkillsPage.tsx    # 技能管理页面

核心模块

RuntimeState (Rust)

负责技能管理：

// 主要方法
list_skills(search?)           // 获取技能列表
get_skill(name_or_path)       // 获取技能详情
validate_skill(name_or_path)  // 校验技能有效性
bind_agent_skill()            // 绑定技能到 Agent
unbind_agent_skill()           // 解绑 Agent 技能

SkillApiService (TypeScript)

前端技能 API 服务封装：

// 主要方法
listSkills(search?)           // 获取技能列表
getSkill(nameOrPath)          // 获取技能详情
validateSkill(nameOrPath)     // 校验技能
bindAgentSkill(payload)       // 绑定技能
unbindAgentSkill(payload)     // 解绑技能

API 接口

Tauri Commands

命令	参数	返回值
skill_list	search?	{ success: boolean, skills: SkillItem[] }
skill_get	skill_name_or_path	Skill
skill_validate	skill_name_or_path	{ valid: boolean, errors?: string[] }
skill_bind_agent	agent_id, skill_name, binding_mode?	{ success: boolean }
skill_unbind_agent	agent_id, skill_name	{ success: boolean }
skill_list_behavior_traces	agent_id?, limit?	{ success: boolean, traces: BehaviorTrace[] }
skill_list_gap_analyses	agent_id?, run_id?, limit?	{ success: boolean, gaps: SkillGapAnalysis[] }
skill_list_recommendations	agent_id?, run_id?, limit?	{ success: boolean, recommendations: SkillRecommendation[] }
skill_get_recommendation	recommendation_id	{ success: boolean, recommendation, gap }
skill_list_versions	skill_name?, recommendation_id?, limit?	{ success: boolean, versions: SkillVersion[] }
skill_generate_recommendation_draft	recommendation_id	{ success: boolean, status, draft_skill_path }
skill_validate_recommendation	recommendation_id	{ success: boolean, status, validation }
skill_prepare_recommendation_shadow	recommendation_id	{ success: boolean, status, shadow_contract }
skill_apply_recommendation_shadow	recommendation_id	{ success: boolean, status }
skill_prepare_recommendation_canary	recommendation_id	{ success: boolean, status, canary_contract }
skill_apply_recommendation_canary	recommendation_id	{ success: boolean, status }
skill_promote_recommendation_to_live	recommendation_id, binding_mode?	{ success: boolean, status, version, binding }
skill_rollback_recommendation	recommendation_id, reason?	{ success: boolean, status }
skill_retire_recommendation	recommendation_id, reason?	{ success: boolean, status }

数据结构

interface SkillItem {
  name: string;          // 技能名称
  description: string;   // 技能描述
  path: string;          // 技能路径
  source: string;        // 技能来源
}

interface SkillBindPayload {
  agentId: string;       // Agent ID
  skillName: string;     // 技能名称
  bindingMode?: string;  // 绑定模式
}

interface BehaviorTrace {
  id: string;            // 行为轨迹 ID
  run_id: string;        // 来源 run
  agent_id: string;      // 归属 Agent
  task_kind: string;     // 任务类型摘要
  repeat_count: number;  // 相同模式累计次数
  tool_sequence: Array<{ tool_id: string; status: string; retry_count: number }>;
}

interface SkillGapAnalysis {
  id: string;
  run_id: string;
  gap_type: 'knowledge_gap' | 'workflow_gap' | 'skill_gap' | 'policy_gap';
  severity: 'low' | 'medium' | 'high';
  summary: string;
}

interface SkillRecommendation {
  id: string;
  gap_id: string;
  recommendation_kind: 'skill' | 'workflow';
  title: string;
  target_skill_name: string;
  status:
    | 'recommended'
    | 'draft_pending'
    | 'draft_generated'
    | 'validated'
    | 'shadow_ready'
    | 'shadow_active'
    | 'canary_ready'
    | 'canary_applied'
    | 'live'
    | 'rolled_back'
    | 'retired';
  confidence: number;
}

interface SkillVersion {
  id: string;
  recommendation_id: string;
  skill_name: string;
  version_number: number;
  lifecycle_stage: 'live' | 'rolled_back' | 'retired' | 'draft';
  bound_agent_id: string;
  binding_mode: string;
}

前端页面

技能管理页面

路径：/pages/Agent/SkillsPage.tsx

功能：

• 浏览可用技能列表
• 搜索过滤技能
• 查看技能详情
• 验证技能有效性

Agent 表单集成

在 Agent 创建/编辑页面中：

• 选择要绑定的技能
• 设置绑定模式
• 管理已绑定的技能

使用示例

获取技能列表

// 获取所有技能
const skills = await skillApi.listSkills();

// 搜索特定技能
const searchResults = await skillApi.listSkills('workflow');

校验技能

const result = await skillApi.validateSkill('my-skill');
if (!result.valid) {
  console.error('技能验证失败:', result.errors);
}

绑定技能到 Agent

await skillApi.bindAgentSkill({
  agentId: 'agent-123',
  skillName: 'data-processing',
  bindingMode: 'on_demand'
});

解绑技能

await skillApi.unbindAgentSkill({
  agentId: 'agent-123',
  skillName: 'data-processing'
});

错误处理

错误码	说明	处理建议
agent_id cannot be empty	Agent ID 为空	提供有效的 Agent ID
skill_name cannot be empty	技能名称为空	提供有效的技能名称
skill not found	技能不存在	检查技能名称或路径
binding failed	绑定失败	检查 Agent 状态和权限

相关文件

• archive/desktop-legacy/src-tauri/src/runtime/skills.rs - Skills 运行时核心
• archive/desktop-legacy/src-tauri/src/commands/skills.rs - Tauri 命令
• archive/desktop-legacy/src/services/skillApi.ts - 前端 API
• archive/desktop-legacy/src/pages/Agent/SkillsPage.tsx - 前端页面