Hermes Agent Skill生命周期管理与触发条件体系

Skill生命周期管理与触发条件体系

文档归属：Hermes Agent自进化智能体高阶实战 / 组织结构深度分析节点 文档版本：v1.0.0 文档状态：正式发布 编写时间：2026-07-07 | 编写者：风云再起

目录

• 第一章 Skill系统总览与架构设计
• 第二章 Skill定义与结构规范
• 第三章 四种触发条件深度机制
• 第四章 Skill生成全流程
• 第五章 三级验证体系
• 第六章 Skill生命周期状态机
• 第七章 Skill质量评估与淘汰机制
• 第八章 Skill与记忆系统交互及竞品对比

第一章 Skill系统总览与架构设计

1.1 概述

Hermes Agent的Skill（技能）系统是其自进化能力的核心载体。与传统的插件系统或工具集成不同，Skill系统具备自动发现、自动生成、自动验证、自动注册的完整闭环能力，使得Agent能够在与用户的交互过程中持续积累可复用的操作模式，逐步从"通用助手"进化为"个性化专家"。

Skill系统的设计哲学可以概括为三个核心原则：

1.2 Skill系统的核心价值

1.3 系统架构总览

┌─────────────────────────────────────────────────────────────────────────────┐
│ Hermes Agent Skill System Architecture │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 频次触发引擎 │ │ 自修复触发引擎 │ │ 用户纠正触发 │ │
│ │ FrequencyTrig │ │ SelfHealTrig │ │ UserCorrectTrig│ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ └────────────┬───────┴────────────┬───────┘ │
│ │ │ │
│ ┌────▼────┐ ┌────▼────┐ │
│ │ 手动创建 │ │ 触发调度 │ │
│ │ Manual │ │ Trigger │ │
│ │ Create │ │ Router │ │
│ └────┬────┘ └────┬────┘ │
│ │ │ │
│ └───────┬───────────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ Skill生成引擎 │ │
│ │ SkillGenerator │ │
│ └───────┬───────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ │ │ │ │
│ ┌──────▼──────┐ ┌────▼────┐ ┌──────▼──────┐ │
│ │ 语法验证器 │ │行为验证 │ │ 安全验证器 │ │
│ │ SyntaxValid │ │Behavior │ │SecurityValid│ │
│ └──────┬──────┘ └────┬────┘ └──────┬──────┘ │
│ └─────────────┼─────────────┘ │
│ ┌──────▼──────┐ │
│ │ Skill注册器 │ │
│ │ SkillRegistr│ │
│ └──────┬──────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ Skill存储层 │ │
│ │ L4 Skill Mem│ │
│ └──────┬──────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ 按需加载器 │ │
│ │ OnDemandLoad│ │
│ └─────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 生命周期管理器 LifecycleManager │ │
│ │ 草稿 → 验证中 → 激活 → 休眠 → 淘汰 → 归档 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 质量评估器 QualityAssessor │ │
│ │ 调用成功率 | 用户满意度 | 执行效率 | 复用频率 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘

1.4 Skill系统的设计目标

1.4.1 零配置技能积累

用户无需任何额外操作，Agent在日常交互中自动识别可复用的操作模式，并将其沉淀为Skill。这一过程对用户完全透明，只有在Skill被成功创建并激活时，系统才会以轻量提示告知用户。

1.4.2 安全的技能进化

所有自动生成的Skill在激活前必须通过三级验证：

• 语法验证：确保SKILL.md格式正确、参数定义合法
• 行为验证：在沙箱环境中执行，验证行为符合预期
• 安全验证：检查权限声明、资源访问范围、潜在风险

1.4.3 自然的技能淘汰

Skill不是永久存在的。当一个Skill长期不被调用（低频淘汰）、与另一个Skill功能重叠（冲突合并）、或被更高版本的Skill替代（版本升级）时，系统会自动将其淘汰或归档，保持技能库的精简和高效。

1.4.4 高效的技能检索

Skill存储在L4技能记忆层，采用"索引 + 按需加载"的架构。Agent在执行任务时，通过语义检索从索引中找到匹配的Skill，然后按需加载完整的Skill定义，避免一次性加载所有Skill导致的上下文膨胀。

1.5 Skill系统在Hermes Agent架构中的定位

┌─────────────────────────────────────────────────────────────────────────────┐
│ Hermes Agent 五层记忆架构 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ L1 – 工作记忆层 (Working Memory) │ │
│ │ 当前对话上下文、临时变量、活跃的推理链 │ │
│ │ 生命周期: 单次对话 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ L2 – 短期记忆层 (Short-term Memory) │ │
│ │ 近期对话历史、临时决策记录、待办事项 │ │
│ │ 生命周期: 数小时 ~ 数天 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ L3 – 长期记忆层 (Long-term Memory) │ │
│ │ 用户画像、长期偏好、历史决策、项目知识库 │ │
│ │ 生命周期: 永久（除非用户删除） │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ L4 – 技能记忆层 (Skill Memory) ★ 本文档焦点 │ │
│ │ Skill定义、执行脚本、参数模式、验证结果、质量指标 │ │
│ │ 生命周期: 永久（除非被淘汰/归档/删除） │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ L5 – 元认知层 (Meta-cognitive Memory) │ │
│ │ 跨Skill的策略知识、Skill间组合规则、进化策略 │ │
│ │ 生命周期: 永久 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘

Skill系统位于L4技能记忆层，它向上为L1工作记忆层提供按需加载的Skill定义，向下从L2/L3记忆层中提取可沉淀的操作模式。L5元认知层则负责管理Skill之间的组合策略和进化方向。

1.6 核心概念定义

1.7 Skill系统的运行时上下文

Skill系统在Hermes Agent运行时中的上下文关系如下：

用户输入 → 意图理解 → [Skill索引检索] → 命中Skill?
│ │
否 是
│ │
正常推理执行 加载Skill定义
│ │
│ 按Skill执行
│ │
└───────┬────────┘
│
执行结果反馈
│
┌───────────────┼───────────────┐
│ │ │
触发检测引擎 质量评估器 生命周期管理器
(检测是否满足 (更新质量指标) (检查状态迁移)
触发条件)
│
满足触发条件?
│
是 → 生成Skill
否 → 继续监控

1.8 本章小结

本章从宏观视角介绍了Hermes Agent Skill系统的设计哲学、核心价值、系统架构和在五层记忆模型中的定位。Skill系统的核心创新在于将"技能获取"从纯手动模式提升为"自动发现 + 手动创建"的混合模式，并通过完整的生命周期管理和三级验证体系确保技能的安全性和质量。后续章节将逐步深入每个子系统的实现细节。

第二章 Skill定义与结构规范

2.1 SKILL.md格式规范

每个Skill的核心定义文件为SKILL.md，采用Markdown格式编写，结合YAML前置元数据块和Markdown正文。这种设计使得Skill定义既具有机器可解析的结构化元数据，又具有人类可读的说明文档。

2.1.1 SKILL.md整体结构

—
# ═══════════════════════════════════════════════════════════
# YAML Front Matter – 元数据块
# ═══════════════════════════════════════════════════════════
name: format_json # Skill唯一标识符
display_name: JSON格式化 # 用户可见的显示名称
version: 1.2.0 # 语义化版本号
author: auto-generated # 作者：auto-generated / 用户名
created_at: 2026-06-15T10:30:00+08:00 # 创建时间
updated_at: 2026-07-01T14:22:00+08:00 # 最后更新时间
status: active # 生命周期状态
trigger_source: frequency # 触发来源
trigger_count: 8 # 触发次数统计
quality_score: 0.92 # 质量评分（0.0~1.0）

# ═══════════════════════════════════════════════════════════
# 工具定义
# ═══════════════════════════════════════════════════════════
tools:
– name: format_json
description: 将输入的JSON字符串格式化为带缩进的可读形式
parameters:
– name: input
type: string
required: true
description: 需要格式化的JSON字符串
– name: indent
type: integer
required: false
default: 2
description: 缩进空格数
– name: sort_keys
type: boolean
required: false
default: false
description: 是否按键名排序
returns:
type: string
description: 格式化后的JSON字符串

# ═══════════════════════════════════════════════════════════
# 权限声明
# ═══════════════════════════════════════════════════════════
permissions:
filesystem:
read: []
write: []
network:
allowed: false
shell:
allowed: false
memory:
read_layers: [L1, L2]
write_layers: [L1]

# ═══════════════════════════════════════════════════════════
# 约束声明
# ═══════════════════════════════════════════════════════════
constraints:
max_execution_time: 5000
max_memory_usage: 50
rate_limit: 100
retry_policy:
max_retries: 3
backoff: exponential
initial_delay: 1000

# ═══════════════════════════════════════════════════════════
# 依赖声明
# ═══════════════════════════════════════════════════════════
dependencies:
skills: []
packages:
– python: json
min_agent_version: 2.0.0

# ═══════════════════════════════════════════════════════════
# 标签与分类
# ═══════════════════════════════════════════════════════════
tags: [json, formatting, data-processing]
category: data-manipulation
priority: normal
—

# JSON格式化技能

## 功能描述
将输入的JSON字符串格式化为带缩进的可读形式。

## 使用场景
– 用户粘贴一段压缩的JSON需要美化
– API响应数据需要格式化查看

## 执行逻辑
1. 解析输入字符串为JSON对象
2. 如果解析失败，返回错误信息
3. 按指定参数重新序列化JSON
4. 返回格式化后的字符串

## 错误处理
– 输入不是有效JSON → 返回解析错误及位置信息
– 输入为空 → 返回提示信息

2.1.2 YAML前置元数据块规范

基础信息字段

工具定义字段（tools）

tools:
– name: tool_name # 工具名称，全局唯一
description: 工具描述 # 简洁的功能描述
parameters: # 参数列表
– name: param_name # 参数名
type: string # 类型: string/integer/float/boolean/array/object
required: true # 是否必填
default: null # 默认值（可选）
description: 参数描述 # 参数说明
enum: [a, b, c] # 枚举值（可选）
pattern: "^[a-z]+$" # 正则约束（可选）
min: 0 # 最小值（数值类型可选）
max: 100 # 最大值（数值类型可选）
returns: # 返回值定义
type: string
description: 返回值描述
errors: # 可能的错误
– code: PARSE_ERROR
message: JSON解析失败
http_status: 400

权限声明字段（permissions）

权限声明采用白名单模式，未明确授权的资源均不可访问：

permissions:
filesystem:
read:
– "/app/data/**"
write:
– "/app/data/output/**"
delete: []
network:
allowed: true
domains:
– "api.example.com"
– "cdn.example.com"
shell:
allowed: false
commands: []
memory:
read_layers: [L1, L2, L3]
write_layers: [L1, L2]
env_vars:
read: ["HOME", "PATH"]
write: []

2.2 元数据模型详解

2.2.1 元数据模型ER图

┌─────────────────────────────────────────────────────────────────────────┐
│ Skill 元数据模型 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────┐ │
│ │ SkillMetadata │ │ ToolDefinition │ │ ParameterDef │ │
│ ├──────────────────┤ ├──────────────────┤ ├────────────────┤ │
│ │ – name: str │1───n│ – name: str │1───n│ – name: str │ │
│ │ – display_name │ │ – description │ │ – type: enum │ │
│ │ – version: str │ │ – parameters[] │─────│ – required │ │
│ │ – author: str │ │ – returns │ │ – default │ │
│ │ – created_at │ │ – errors[] │ │ – description │ │
│ │ – updated_at │ └──────────────────┘ │ – enum[] │ │
│ │ – status: enum │ │ – pattern │ │
│ │ – trigger_source │ ┌──────────────────┐ │ – min/max │ │
│ │ – trigger_count │1───1│ PermissionSet │ └────────────────┘ │
│ │ – quality_score │ ├──────────────────┤ │
│ │ – tags[] │ │ – filesystem │ ┌────────────────┐ │
│ │ – category │ │ – network │ │ ConstraintSet │ │
│ │ – priority │ │ – shell │ ├────────────────┤ │
│ └──────────────────┘ │ – memory │ │ – max_exec_time│ │
│ │ – env_vars │ │ – max_memory │ │
│ ┌──────────────────┐ └──────────────────┘ │ – rate_limit │ │
│ │ DependencySet │ │ – retry_policy │ │
│ ├──────────────────┤ ┌──────────────────┐ └────────────────┘ │
│ │ – skills[] │ │ QualityMetrics │ │
│ │ – packages[] │1───1│ ├──────────────────┤ │
│ │ – min_agent_ver │ │ – success_rate │ │
│ └──────────────────┘ │ – satisfaction │ │
│ │ – efficiency │ │
│ │ – reuse_freq │ │
│ │ – total_calls │ │
│ │ – last_called │ │
│ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘

2.2.2 元数据序列化格式

元数据在L4技能记忆层中以JSON格式存储，便于检索和加载：

{
"skill_id": "format_json_v1.2.0",
"name": "format_json",
"display_name": "JSON格式化",
"version": "1.2.0",
"author": "auto-generated",
"created_at": "2026-06-15T10:30:00+08:00",
"updated_at": "2026-07-01T14:22:00+08:00",
"status": "active",
"trigger_source": "frequency",
"trigger_count": 8,
"quality_score": 0.92,
"quality_metrics": {
"success_rate": 0.95,
"satisfaction": 0.88,
"efficiency": 0.96,
"reuse_freq": 0.90,
"total_calls": 42,
"last_called": "2026-07-05T09:15:00+08:00"
},
"tools": [
{
"name": "format_json",
"description": "将输入的JSON字符串格式化为带缩进的可读形式",
"parameters": [
{
"name": "input",
"type": "string",
"required": true,
"description": "需要格式化的JSON字符串"
},
{
"name": "indent",
"type": "integer",
"required": false,
"default": 2,
"description": "缩进空格数",
"min": 0,
"max": 8
}
],
"returns": {
"type": "string",
"description": "格式化后的JSON字符串"
}
}
],
"permissions": {
"filesystem": { "read": [], "write": [] },
"network": { "allowed": false },
"shell": { "allowed": false },
"memory": {
"read_layers": ["L1", "L2"],
"write_layers": ["L1"]
}
},
"constraints": {
"max_execution_time": 5000,
"max_memory_usage": 50,
"rate_limit": 100
},
"dependencies": {
"skills": [],
"packages": [{"python": "json"}],
"min_agent_version": "2.0.0"
},
"tags": ["json", "formatting", "data-processing"],
"category": "data-manipulation",
"priority": "normal",
"skill_file_path": "/app/data/skills/format_json/SKILL.md",
"script_file_path": "/app/data/skills/format_json/scripts/format_json.py"
}

2.3 工具定义规范

2.3.1 参数类型系统

2.3.2 参数约束规范

parameters:
– name: output_format
type: enum
required: true
enum: [json, yaml, xml, csv]
default: json
description: 输出格式

– name: max_results
type: integer
required: false
min: 1
max: 1000
default: 50
description: 最大返回结果数

– name: file_pattern
type: string
required: true
pattern: "^[a-zA-Z0-9_\\\\-/.]+$"
min_length: 1
max_length: 255
description: 文件匹配模式

– name: options
type: object
required: false
properties:
verbose:
type: boolean
default: false
timeout:
type: integer
default: 30
description: 高级选项

2.3.3 返回值规范

returns:
type: object
description: 格式化结果
properties:
success:
type: boolean
description: 是否成功
formatted_text:
type: string
description: 格式化后的文本
error:
type: string
description: 错误信息（success为false时存在）
warnings:
type: array
items:
type: string
description: 警告信息列表

2.4 权限声明详解

2.4.1 权限层级模型

┌─────────────────────────────────────────────────────────────────────────────┐
│ Skill 权限层级模型 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Level 0: 无权限（默认） │
│ ├── 无文件系统访问 │
│ ├── 无网络访问 │
│ ├── 无Shell执行 │
│ └── 仅可访问L1工作记忆 │
│ │
│ Level 1: 只读权限 │
│ ├── 文件系统：指定路径只读 │
│ ├── 网络：指定域名GET请求 │
│ ├── Shell：禁止 │
│ └── 记忆：L1读写 + L2/L3只读 │
│ │
│ Level 2: 标准权限 │
│ ├── 文件系统：指定路径读写 │
│ ├── 网络：指定域名全方法 │
│ ├── Shell：指定命令列表 │
│ └── 记忆：L1/L2读写 + L3只读 │
│ │
│ Level 3: 高权限（需用户确认） │
│ ├── 文件系统：全路径读写 │
│ ├── 网络：无限制 │
│ ├── Shell：全命令执行 │
│ └── 记忆：L1/L2/L3读写 + L4只读 │
│ │
│ Level 4: 系统权限（需用户确认 + 管理员审批） │
│ ├── 所有Level 3权限 │
│ ├── 记忆：L1~L5全层读写 │
│ ├── Skill管理：可创建/修改/删除其他Skill │
│ └── 系统配置：可修改Agent配置 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘

2.4.2 权限自动推断

当Skill由系统自动生成时，权限声明会根据触发场景自动推断：

# 权限自动推断逻辑（伪代码）

def infer_permissions(trigger_source: str, operation_history: list) –> PermissionSet:
"""根据触发来源和操作历史推断所需权限"""

permissions = PermissionSet()

# 分析操作历史中实际使用的资源
used_paths_read = set()
used_paths_write = set()
used_network = False
used_shell = False
used_memory_layers = set()

for op in operation_history:
if op.type == "file_read":
used_paths_read.add(op.path)
elif op.type == "file_write":
used_paths_write.add(op.path)
elif op.type == "network_request":
used_network = True
elif op.type == "shell_exec":
used_shell = True
elif op.type == "memory_access":
used_memory_layers.add(op.layer)

# 最小权限原则：仅授予实际使用过的权限
permissions.filesystem.read = minimize_paths(used_paths_read)
permissions.filesystem.write = minimize_paths(used_paths_write)
permissions.network.allowed = used_network
permissions.shell.allowed = used_shell
permissions.memory.read_layers = list(used_memory_layers)
permissions.memory.write_layers = ["L1"]

# 频次触发的Skill默认降低权限级别
if trigger_source == "frequency":
permissions = apply_security_downgrade(permissions, max_level=2)
elif trigger_source == "self_heal":
permissions = apply_security_downgrade(permissions, max_level=2)
elif trigger_source == "user_correction":
permissions = apply_security_downgrade(permissions, max_level=1)
elif trigger_source == "manual":
pass # 使用用户显式声明的权限

return permissions

def minimize_paths(paths: set) –> list:
"""将具体路径归纳为通配模式，减少权限粒度"""
minimized = []
for path in paths:
parts = path.split("/")
if len(parts) > 4:
minimized.append("/".join(parts[:4]) + "/**")
else:
minimized.append(path)
return list(set(minimized))

2.5 Skill目录结构

每个Skill在文件系统中以独立目录的形式存在：

/app/data/skills/
├── format_json/ # Skill名称作为目录名
│ ├── SKILL.md # Skill定义文件（必需）
│ ├── metadata.json # 序列化的元数据（自动生成）
│ ├── scripts/ # 执行脚本目录
│ │ ├── format_json.py # 主执行脚本
│ │ └── utils.py # 辅助脚本
│ ├── references/ # 参考资料目录
│ │ ├── examples.md # 使用示例
│ │ └── edge_cases.md # 边界情况说明
│ ├── tests/ # 测试用例目录
│ │ ├── test_basic.py # 基础测试
│ │ ├── test_edge.py # 边界测试
│ │ └── test_security.py # 安全测试
│ ├── validation/ # 验证结果目录
│ │ ├── syntax_report.json # 语法验证报告
│ │ ├── behavior_report.json # 行为验证报告
│ │ └── security_report.json # 安全验证报告
│ └── quality/ # 质量指标目录
│ ├── metrics.json # 质量指标数据
│ └── history.json # 调用历史记录
│
├── api_error_handler/ # 另一个Skill
│ ├── SKILL.md
│ ├── scripts/
│ │ └── retry_handler.py
│ └── …
│
└── daily_report_generator/ # 手动创建的Skill
├── SKILL.md
├── scripts/
│ ├── generate_report.py
│ └── send_email.py
└── …

2.6 Skill索引文件

L4技能记忆层维护一个全局Skill索引文件，用于快速检索：

{
"index_version": "1.0.0",
"last_updated": "2026-07-05T18:00:00+08:00",
"total_skills": 27,
"active_skills": 22,
"dormant_skills": 3,
"deprecated_skills": 2,
"skills": [
{
"skill_id": "format_json_v1.2.0",
"name": "format_json",
"display_name": "JSON格式化",
"version": "1.2.0",
"status": "active",
"category": "data-manipulation",
"tags": ["json", "formatting", "data-processing"],
"trigger_source": "frequency",
"quality_score": 0.92,
"last_called": "2026-07-05T09:15:00+08:00",
"call_count_30d": 18,
"skill_path": "/app/data/skills/format_json/SKILL.md",
"semantic_embedding": [0.123, –0.456, 0.789],
"description_summary": "将JSON字符串格式化为带缩进的可读形式"
},
{
"skill_id": "api_error_handler_v1.0.3",
"name": "api_error_handler",
"display_name": "API错误处理器",
"version": "1.0.3",
"status": "active",
"category": "error-handling",
"tags": ["api", "error", "retry", "self-heal"],
"trigger_source": "self_heal",
"quality_score": 0.87,
"last_called": "2026-07-04T16:30:00+08:00",
"call_count_30d": 7,
"skill_path": "/app/data/skills/api_error_handler/SKILL.md",
"semantic_embedding": [0.234, –0.567, 0.890],
"description_summary": "处理API调用失败，自动重试和错误恢复"
}
]
}

2.7 本章小结

本章详细定义了Skill的结构规范，包括SKILL.md的完整格式、YAML前置元数据块的所有字段、工具定义的参数类型系统、权限声明的层级模型以及Skill在文件系统中的目录结构。这些规范构成了Skill系统的基础，后续章节中的触发机制、生成流程、验证体系和生命周期管理都建立在这些结构定义之上。

第三章 四种触发条件深度机制

3.1 触发条件体系总览

Hermes Agent的Skill系统定义了四种触发条件，每种触发条件对应一种不同的Skill发现模式。这四种触发条件共同构成了一个完整的"技能发现矩阵"，覆盖了从被动观察到主动创建的全部场景。

┌─────────────────────────────────────────────────────────────────────────────┐
│ Skill 触发条件决策树 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─ 用户主动编写Skill? │
│ │ │ │
│ │ 是 → [手动创建触发] │
│ │ │ │
│ │ 否 ↓ │
│ │ │
│ ├─ Agent出错后自行修复成功? │
│ │ │ │
│ │ 是 → [自修复触发] │
│ │ │ │
│ │ 否 ↓ │
│ │ │
│ ├─ 用户明确纠正Agent行为? │
│ │ │ │
│ │ 是 → [用户纠正触发] │
│ │ │ │
│ │ 否 ↓ │
│ │ │
│ ├─ 同类操作被调用≥5次? │
│ │ │ │
│ │ 是 → [频次触发] │
│ │ │ │
│ │ 否 → 继续监控，不触发 │
│ │ │
│ └──────────────────────────────── │
│ │
│ 触发优先级: 手动创建 > 自修复 > 用户纠正 > 频次触发 │
│ (高优先级触发条件先检查，满足则不再检查低优先级) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘

3.2 四种触发条件对比

3.3 频次触发深度机制

3.3.1 频次检测算法

频次触发是四种触发条件中最复杂的一种，其核心挑战在于"同类操作"的判定。系统需要在不干扰正常交互的前提下，实时检测操作模式的重复性。

操作模式抽取

每次Agent执行操作时，系统会抽取一个"操作模式签名"（Operation Pattern Signature），用于后续的相似性比较：

class OperationPatternExtractor:
"""操作模式抽取器"""

def extract_pattern(self, operation: Operation) –> OperationPattern:
"""
从一次操作中抽取操作模式

操作模式包含以下维度：
1. 意图类别 – 操作的目标类型
2. 输入类型 – 输入数据的类型特征
3. 输出类型 – 输出数据的类型特征
4. 工具链 – 使用的工具序列
5. 参数模式 – 关键参数的取值模式
6. 上下文标签 – 执行上下文的语义标签
"""
pattern = OperationPattern()

# 1. 意图类别抽取
pattern.intent = self._classify_intent(operation.description)
# 例如: "帮我把这段JSON格式化" → intent = "format_data"

# 2. 输入类型特征
pattern.input_types = self._extract_type_features(operation.inputs)
# 例如: 输入是字符串, 包含{}和:, 判定为JSON格式

# 3. 输出类型特征
pattern.output_types = self._extract_type_features(operation.outputs)
# 例如: 输出是字符串, 带缩进, 判定为格式化文本

# 4. 工具链序列
pattern.tool_chain = [t.name for t in operation.tools_used]
# 例如: ["python_executor"]

# 5. 参数模式
pattern.param_patterns = self._extract_param_patterns(operation.parameters)
# 例如: {indent: 2, sort_keys: false}

# 6. 上下文语义标签
pattern.context_tags = self._extract_context_tags(operation.context)
# 例如: ["data_processing", "formatting"]

# 生成模式签名
pattern.signature = self._generate_signature(pattern)

return pattern

def _classify_intent(self, description: str) –> str:
"""使用语义模型分类操作意图"""
intent_categories = [
"format_data", # 数据格式化
"parse_data", # 数据解析
"transform_data", # 数据转换
"validate_data", # 数据验证
"search_information", # 信息搜索
"generate_content", # 内容生成
"send_communication", # 发送通信
"file_operation", # 文件操作
"api_call", # API调用
"error_handling", # 错误处理
"data_analysis", # 数据分析
"report_generation", # 报告生成
"code_execution", # 代码执行
"workflow_automation", # 工作流自动化
"other" # 其他
]
# 使用嵌入向量相似度进行分类
...

def _generate_signature(self, pattern: OperationPattern) –> str:
"""生成操作模式的唯一签名"""
signature_input = f"{pattern.intent}|{pattern.input_types}|" \\
f"{pattern.output_types}|{pattern.tool_chain}|" \\
f"{pattern.param_patterns}"
return hashlib.md5(signature_input.encode()).hexdigest()

频次检测引擎

class FrequencyTriggerEngine:
"""频次触发引擎"""

FREQUENCY_THRESHOLD = 5 # 频次触发阈值
TIME_WINDOW = 7 * 24 * 3600 # 时间窗口：7天（秒）
MIN_TIME_INTERVAL = 3600 # 最小时间间隔：1小时

def __init__(self):
self.pattern_store = PatternStore()
self.skill_registry = SkillRegistry()

def check_trigger(self, current_operation: Operation) –> TriggerResult:
"""
检查当前操作是否满足频次触发条件
"""
# 1. 抽取当前操作的模式
current_pattern = self.pattern_extractor.extract_pattern(current_operation)

# 2. 检查是否已有覆盖此模式的Skill
existing_skill = self.skill_registry.find_by_pattern(current_pattern)
if existing_skill:
self.skill_registry.increment_call_count(existing_skill.skill_id)
return TriggerResult(triggered=False, reason="existing_skill_covers")

# 3. 在时间窗口内查找相似模式
similar_patterns = self.pattern_store.find_similar(
pattern=current_pattern,
time_window=self.TIME_WINDOW,
similarity_threshold=0.85
)

# 4. 过滤掉时间间隔过短的模式
filtered_patterns = self._filter_by_time_interval(similar_patterns)

# 5. 检查是否达到频次阈值
if len(filtered_patterns) >= self.FREQUENCY_THRESHOLD:
return TriggerResult(
triggered=True,
trigger_source="frequency",
pattern=current_pattern,
similar_patterns=filtered_patterns,
trigger_count=len(filtered_patterns)
)
else:
self.pattern_store.store(current_pattern)
return TriggerResult(
triggered=False,
reason="below_threshold",
current_count=len(filtered_patterns),
threshold=self.FREQUENCY_THRESHOLD
)

def _filter_by_time_interval(self, patterns: list) –> list:
"""过滤时间间隔过短的模式"""
if not patterns:
return []

filtered = [patterns[0]]
for p in patterns[1:]:
time_diff = (p.timestamp – filtered[–1].timestamp).total_seconds()
if time_diff >= self.MIN_TIME_INTERVAL:
filtered.append(p)

return filtered

3.3.2 频次触发的具体示例

时间线示例：频次触发 format_json Skill

Day 1 10:30 用户: "帮我把这段JSON格式化" → Agent执行格式化操作
模式签名: format_data|json_string|formatted_string|[python]|
频次计数: 1/5 → 未触发

Day 2 14:20 用户: "这个JSON太乱了，帮我整理一下" → Agent执行格式化操作
模式签名: format_data|json_string|formatted_string|[python]|
频次计数: 2/5 → 未触发

Day 3 09:15 用户: "格式化这个配置文件" → Agent执行格式化操作
模式签名: format_data|json_string|formatted_string|[python]|
频次计数: 3/5 → 未触发

Day 4 16:45 用户: "帮我美化这段JSON数据" → Agent执行格式化操作
模式签名: format_data|json_string|formatted_string|[python]|
频次计数: 4/5 → 未触发

Day 5 11:00 用户: "这段JSON能不能格式化一下" → Agent执行格式化操作
模式签名: format_data|json_string|formatted_string|[python]|
频次计数: 5/5 → ★ 频次触发！

→ Skill生成引擎启动
→ 从5次操作中提炼通用模式
→ 生成 format_json Skill
→ 进入验证流程

3.3.3 模式相似度计算

class PatternSimilarityCalculator:
"""操作模式相似度计算器"""

def calculate(self, pattern_a: OperationPattern,
pattern_b: OperationPattern) –> float:
"""
计算两个操作模式之间的相似度
返回0.0~1.0的相似度分数
"""
weights = {
"intent": 0.30,
"input_types": 0.20,
"output_types": 0.15,
"tool_chain": 0.15,
"param_patterns": 0.10,
"context_tags": 0.10
}

scores = {}
scores["intent"] = self._intent_similarity(
pattern_a.intent, pattern_b.intent
)
scores["input_types"] = self._type_similarity(
pattern_a.input_types, pattern_b.input_types
)
scores["output_types"] = self._type_similarity(
pattern_a.output_types, pattern_b.output_types
)
scores["tool_chain"] = self._jaccard_similarity(
set(pattern_a.tool_chain), set(pattern_b.tool_chain)
)
scores["param_patterns"] = self._param_similarity(
pattern_a.param_patterns, pattern_b.param_patterns
)
scores["context_tags"] = self._jaccard_similarity(
set(pattern_a.context_tags), set(pattern_b.context_tags)
)

total_score = sum(
scores[dim] * weights[dim] for dim in weights
)
return total_score

def _intent_similarity(self, intent_a: str, intent_b: str) –> float:
"""意图相似度计算"""
if intent_a == intent_b:
return 1.0
similarity_matrix = {
("format_data", "transform_data"): 0.7,
("parse_data", "validate_data"): 0.6,
("search_information", "data_analysis"): 0.5,
("generate_content", "report_generation"): 0.7,
}
key = tuple(sorted([intent_a, intent_b]))
return similarity_matrix.get(key, 0.0)

def _jaccard_similarity(self, set_a: set, set_b: set) –> float:
"""Jaccard相似度"""
if not set_a and not set_b:
return 1.0
intersection = set_a & set_b
union = set_a | set_b
return len(intersection) / len(union) if union else 0.0

3.3.4 频次触发的防抖机制

为了避免因短时间内的大量相似操作导致误触发，频次触发引擎内置了防抖机制：

class FrequencyDebouncer:
"""频次触发防抖器"""

def __init__(self):
self.recent_triggers = {}
self.cooldown_period = 3600 * 24 # 冷却期：24小时
self.confirmation_window = {}

def should_trigger(self, pattern_signature: str,
current_count: int) –> bool:
"""
判断是否应该真正触发Skill生成

防抖规则:
1. 同一模式签名在冷却期内只触发一次
2. 超过阈值后不立即触发，等待一个确认窗口
3. 确认窗口内如果模式继续出现，则触发
"""
now = datetime.now()

# 规则1：冷却期检查
last_trigger = self.recent_triggers.get(pattern_signature)
if last_trigger:
time_since_last = (now – last_trigger).total_seconds()
if time_since_last < self.cooldown_period:
return False

# 规则2：确认窗口检查
if current_count == 5: # FREQUENCY_THRESHOLD
self.confirmation_window[pattern_signature] = {
"start_time": now,
"confirmations": 0,
"required": 2
}
return False

# 规则3：确认窗口内的计数
if pattern_signature in self.confirmation_window:
window = self.confirmation_window[pattern_signature]
window["confirmations"] += 1
if window["confirmations"] >= window["required"]:
del self.confirmation_window[pattern_signature]
self.recent_triggers[pattern_signature] = now
return True
else:
return False

return False

3.4 自修复触发深度机制

3.4.1 自修复识别逻辑

自修复触发是Skill系统中最具智能性的触发条件。当Agent在执行任务时遇到错误，通过自身的推理和重试成功解决了问题后，系统会将这个"错误→修复"的链路提取为一个可复用的Skill。

┌─────────────────────────────────────────────────────────────────────────────┐
│ 自修复触发识别流程 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ Agent执行任务│ │
│ └──────┬──────┘ │
│ │ │
│ ┌────▼────┐ │
│ │ 执行成功？│ │
│ └────┬────┘ │
│ 是 │ 否 │
│ │ └──────┐ │
│ │ │ │
│ │ ┌──────▼──────┐ │
│ │ │ Agent自行排查 │ │
│ │ │ – 分析错误 │ │
│ │ │ – 查找原因 │ │
│ │ │ – 尝试修复 │ │
│ │ └──────┬──────┘ │
│ │ │ │
│ │ ┌────▼────┐ │
│ │ │ 修复成功？│ │
│ │ └────┬────┘ │
│ │ 是 │ 否 │
│ │ │ └──────→ 请求用户帮助（不触发） │
│ │ │ │ │
│ │ ┌─────────▼───────▼──┐ │
│ │ │ 自修复识别器检查 │ │
│ │ │ │ │
│ │ │ 1. 错误是否可复现？ │──→ 否 → 不触发（偶发错误不值得沉淀） │
│ │ │ │ │
│ │ │ 2. 修复是否通用？ │──→ 否 → 不触发（过于特定的修复） │
│ │ │ │ │
│ │ │ 3. 修复是否安全？ │──→ 否 → 不触发（不安全的修复方式） │
│ │ │ │ │
│ │ │ 4. 是否已有同类 │──→ 是 → 更新已有Skill（不新建） │
│ │ │ Skill？ │ │
│ │ │ │ │
│ │ │ 5. 修复链路是否 │──→ 否 → 不触发（修复过于复杂，不适合沉淀） │
│ │ │ 可抽象？ │ │
│ │ └────────┬───────────┘ │
│ │ │ │
│ │ 通过所有检查 │
│ │ │ │
│ │ ┌─────▼─────┐ │
│ │ │ ★ 触发 │ │
│ │ │ 自修复触发 │ │
│ │ │ Skill生成 │ │
│ │ └───────────┘ │
│ │ │
│ └──→ 正常完成，无触发 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘

3.4.2 自修复识别器实现

class SelfHealTriggerDetector:
"""自修复触发检测器"""

def __init__(self):
self.error_recovery_store = ErrorRecoveryStore()
self.skill_registry = SkillRegistry()
self.safety_checker = SafetyChecker()

def detect_self_heal_trigger(self,
task_context: TaskContext) –> TriggerResult:
"""
检测任务执行过程中是否存在可触发的自修复链路
"""
# 1. 检查是否存在错误-修复链路
error_recovery_chain = self._extract_error_recovery_chain(task_context)
if not error_recovery_chain:
return TriggerResult(triggered=False, reason="no_error_recovery_chain")

# 2. 检查1: 错误是否可复现
if not self._is_error_reproducible(error_recovery_chain.error):
return TriggerResult(triggered=False, reason="error_not_reproducible")

# 3. 检查2: 修复是否具有通用性
generality_score = self._assess_generality(error_recovery_chain)
if generality_score < 0.6:
return TriggerResult(
triggered=False, reason="fix_not_general_enough",
generality_score=generality_score
)

# 4. 检查3: 修复方式是否安全
safety_result = self.safety_checker.check_fix_safety(
error_recovery_chain.recovery_actions
)
if not safety_result.is_safe:
return TriggerResult(
triggered=False, reason="fix_not_safe",
safety_issues=safety_result.issues
)

# 5. 检查4: 是否已有覆盖此错误场景的Skill
existing_skill = self.skill_registry.find_by_error_pattern(
error_recovery_chain.error
)
if existing_skill:
return TriggerResult(
triggered=True, trigger_source="self_heal",
action="update_existing", target_skill=existing_skill.skill_id,
error_recovery_chain=error_recovery_chain
)

# 6. 检查5: 修复链路是否可以抽象为通用Skill
abstraction_result = self._attempt_abstraction(error_recovery_chain)
if not abstraction_result.success:
return TriggerResult(
triggered=False, reason="cannot_abstract",
abstraction_issues=abstraction_result.issues
)

# 7. 所有检查通过，触发Skill生成
return TriggerResult(
triggered=True, trigger_source="self_heal",
action="create_new",
error_recovery_chain=error_recovery_chain,
abstraction=abstraction_result,
generality_score=generality_score
)

def _is_error_reproducible(self, error: ErrorInfo) –> bool:
"""判断错误是否可复现（排除偶发错误）"""
reproducible_error_types = {
"api_authentication_error",
"invalid_parameter_error",
"file_not_found_error",
"permission_denied_error",
"data_format_error",
"api_rate_limit_error",
"api_connection_timeout",
"json_parse_error",
}
return error.type in reproducible_error_types

def _assess_generality(self, chain: ErrorRecoveryChain) –> float:
"""评估修复的通用性"""
score = 0.0

# 维度1: 错误类型常见程度
common_errors = {
"api_connection_timeout": 0.25,
"api_authentication_error": 0.20,
"api_rate_limit_error": 0.25,
"json_parse_error": 0.30,
"file_not_found_error": 0.20,
"permission_denied_error": 0.15,
}
score += common_errors.get(chain.error.type, 0.1)

# 维度2: 修复策略可复用性
reusable_strategies = {
"exponential_backoff_retry": 0.30,
"fallback_to_cache": 0.25,
"switch_to_alternative_api": 0.20,
"refresh_token_and_retry": 0.25,
"sanitize_and_reparse": 0.28,
}
score += reusable_strategies.get(chain.fix_strategy, 0.10)

# 维度3: 修复步骤抽象程度
abstraction_level = self._measure_abstraction(chain.recovery_actions)
score += abstraction_level * 0.20

# 维度4: 上下文依赖程度（反向评分）
context_dependency = self._measure_context_dependency(chain)
score += (1.0 – context_dependency) * 0.20

return min(score, 1.0)

3.4.3 自修复触发示例

自修复触发示例：生成 api_retry_handler Skill

场景: Agent调用外部API时遇到超时错误

时间线:
1. Agent调用 https://api.example.com/data → 连接超时
2. Agent分析错误: "ConnectionTimeoutError"
3. Agent推理: "可能是网络临时问题，尝试重试"
4. Agent执行: 等待1秒 → 重试 → 仍然超时
5. Agent推理: "连续超时，使用指数退避策略"
6. Agent执行: 等待2秒 → 重试 → 超时
7. Agent执行: 等待4秒 → 重试 → 成功！

自修复识别器检查:
✓ 错误可复现: api_connection_timeout 是常见可复现错误
✓ 修复具有通用性: 指数退避重试策略通用性评分 0.85
✓ 修复安全: 仅涉及重试，无危险操作
✓ 无同类Skill: 系统中不存在api_retry_handler
✓ 可抽象: 修复链路可抽象为通用的API重试Skill

→ 触发自修复触发
→ 生成 api_retry_handler Skill
– 名称: api_retry_handler
– 触发来源: self_heal
– 功能: API调用失败时自动执行指数退避重试
– 参数: url, method, params, max_retries, initial_delay
– 策略: exponential backoff (1s, 2s, 4s, 8s, 16s)

3.5 用户纠正触发深度机制

3.5.1 用户纠正语义分析

用户纠正触发发生在用户明确纠正Agent行为的场景。系统需要从用户的纠正语句中提取出可沉淀的偏好规则，并将其转化为Skill。

class UserCorrectionAnalyzer:
"""用户纠正语义分析器"""

CORRECTION_TYPES = {
"language_preference": {
"patterns": [
r"用中文", r"说中文", r"用英文", r"用日语",
r"please (use|reply in) (english|chinese)",
r"回答.*请用.*语"
],
"skill_category": "language",
"generality": "permanent"
},
"format_preference": {
"patterns": [
r"用表格", r"用列表", r"用 markdown",
r"不要用.*格式", r"换成.*格式",
r"用.*排版", r"简洁一点", r"详细一点"
],
"skill_category": "formatting",
"generality": "persistent"
},
"behavior_correction": {
"patterns": [
r"不要.*这样", r"应该.*才对", r"不对",
r"错了", r"不是.*是", r"应该先.*再"
],
"skill_category": "behavior",
"generality": "contextual"
},
"tone_adjustment": {
"patterns": [
r"正式一点", r"随意一点", r"专业一点",
r"简单说", r"详细解释", r"给个例子"
],
"skill_category": "communication_style",
"generality": "persistent"
},
"workflow_correction": {
"patterns": [
r"步骤.*不对", r"顺序.*错了", r"应该先.*后",
r"漏了.*步骤", r"多了一步"
],
"skill_category": "workflow",
"generality": "persistent"
}
}

def analyze_correction(self, user_input: str,
agent_behavior: AgentBehavior) –> CorrectionAnalysis:
"""分析用户纠正语句"""
analysis = CorrectionAnalysis()

# 1. 判断是否为纠正语句
is_correction, correction_type = self._detect_correction_type(user_input)
if not is_correction:
return CorrectionAnalysis(is_correction=False)

analysis.correction_type = correction_type
analysis.correction_config = self.CORRECTION_TYPES[correction_type]

# 2. 提取纠正的规则
analysis.rule = self._extract_correction_rule(
user_input, agent_behavior, correction_type
)

# 3. 评估规则的通用性
analysis.generality_score = self._evaluate_generality(
analysis.rule, analysis.correction_config["generality"]
)

# 4. 检查是否已有同类Skill
analysis.existing_skill = self._find_overlapping_skill(
analysis.rule, analysis.correction_config["skill_category"]
)

# 5. 生成Skill草案
if analysis.generality_score >= 0.5:
analysis.skill_draft = self._generate_skill_draft(
analysis.rule, correction_type, agent_behavior
)
analysis.should_trigger = True
else:
analysis.should_trigger = False
analysis.reason = "low_generality"

return analysis

3.5.2 用户纠正触发示例

用户纠正触发示例：生成 language_preference_zh Skill

场景: Agent使用英文回复，用户要求使用中文

时间线:
1. 用户: "分析一下这段代码的性能瓶颈"
2. Agent: "Based on my analysis, the main performance bottleneck
is in the nested loop at line 42…" (英文回复)
3. 用户: "用中文回复"

用户纠正分析器处理:
– 纠正类型: language_preference
– 规则: response_language = "zh-CN"
– 通用性评分: 0.95 (永久偏好，高通用性)
– 是否已有同类Skill: 否
– should_trigger: True

→ 触发用户纠正触发
→ 生成 language_preference_zh Skill
– 名称: language_preference_zh
– 触发来源: user_correction
– 功能: 确保Agent始终使用简体中文回复
– 纠正类型: language_preference
– 通用性: permanent (永久)
– 执行方式: 在Agent生成回复前注入语言偏好约束

3.5.3 纠正类型的通用性分级

3.6 手动创建流程

3.6.1 手动创建的交互流程

┌─────────────────────────────────────────────────────────────────────────────┐
│ Skill 手动创建流程 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 用户: "帮我创建一个每日报告生成的Skill" │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Step 1: 需求理解 │ │
│ │ Agent: "好的，我来帮你创建每日报告生成Skill。请告诉我以下信息： │ │
│ │ 1. 报告内容包含哪些部分？ │ │
│ │ 2. 数据来源是什么？ │ │
│ │ 3. 报告格式要求？ │ │
│ │ 4. 生成时间和频率？ │ │
│ │ 5. 是否需要自动发送？发送给谁？" │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ 用户: "报告包含项目进度、待办事项、风险预警三部分。数据从飞书文档 │
│ 读取。Markdown格式。每天早上9点生成。发送到我的邮箱。" │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Step 2: Skill草案生成 │ │
│ │ Agent: "我理解了你的需求，下面是我生成的Skill草案，请确认： │ │
│ │ 名称: daily_report_generator │ │
│ │ 功能: 每日从飞书文档读取项目数据，生成Markdown格式报告 │ │
│ │ 触发: 每日09:00 │ │
│ │ 输出: Markdown报告 → 邮件发送 │ │
│ │ 权限: 飞书文档读取 + 邮件发送 │ │
│ │ 是否需要调整？" │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ 用户: "没问题，就这样" │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Step 3: SKILL.md生成 │ │
│ │ – 生成完整的SKILL.md文件 │ │
│ │ – 生成执行脚本 │ │
│ │ – 生成测试用例 │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Step 4: 验证 │ │
│ │ – 语法验证 ✓ │ │
│ │ – 行为验证（沙箱测试运行）✓ │ │
│ │ – 安全验证（权限审查）✓ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Step 5: 注册与激活 │ │
│ │ – 注册到Skill索引 │ │
│ │ – 设置定时触发 │ │
│ │ – 状态: draft → validating → active │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
│ Agent: "✅ daily_report_generator Skill已创建并激活。 │
│ 每天早上9点将自动生成报告并发送到你的邮箱。" │
│ │
└─────────────────────────────────────────────────────────────────────────────┘

3.6.2 手动创建的Skill定义示例

—
name: daily_report_generator
display_name: 每日报告生成器
version: 1.0.0
author: user
created_at: 2026-07-05T15:00:00+08:00
updated_at: 2026-07-05T15:00:00+08:00
status: active
trigger_source: manual
trigger_count: 0
quality_score: null

tools:
– name: generate_daily_report
description: 从飞书文档读取项目数据，生成每日Markdown格式报告
parameters:
– name: report_date
type: string
required: false
default: "today"
description: 报告日期，默认为今天
– name: sections
type: array
required: false
default: ["project_progress", "todo_items", "risk_alert"]
description: 报告包含的部分
items:
type: enum
enum: [project_progress, todo_items, risk_alert, meeting_notes]
– name: output_format
type: enum
required: false
default: markdown
enum: [markdown, html, pdf]
description: 输出格式
returns:
type: object
properties:
report_content:
type: string
description: 报告内容
report_path:
type: string
description: 报告文件路径
sent:
type: boolean
description: 是否已发送邮件

– name: send_report_email
description: 将报告通过邮件发送
parameters:
– name: report_content
type: string
required: true
description: 报告内容
– name: recipient
type: string
required: true
description: 收件人邮箱
– name: subject
type: string
required: false
default: "每日项目报告 – {date}"
description: 邮件主题

permissions:
filesystem:
read: ["/app/data/reports/**"]
write: ["/app/data/reports/**"]
network:
allowed: true
domains: ["open.feishu.cn", "smtp.example.com"]
shell:
allowed: false
memory:
read_layers: [L1, L2, L3]
write_layers: [L1, L2]

constraints:
max_execution_time: 120000
max_memory_usage: 200
rate_limit: 1
schedule:
type: cron
expression: "0 9 * * *"
timezone: "Asia/Shanghai"

dependencies:
skills: []
packages:
– python: requests
– python: jinja2
– python: smtplib
min_agent_version: 2.0.0

tags: [report, daily, automation, feishu, email]
category: workflow–automation
priority: high
—

# 每日报告生成器

## 功能描述
每日定时从飞书文档读取项目数据，生成包含项目进度、待办事项和风险预警
的Markdown格式报告，并通过邮件发送给指定收件人。

## 使用场景
– 每日项目进度跟踪
– 团队晨会数据准备
– 管理层日报自动化

## 执行逻辑
1. 连接飞书API，读取项目文档数据
2. 解析项目进度、待办事项、风险信息
3. 使用Jinja2模板引擎生成Markdown报告
4. 保存报告到本地文件系统
5. 通过SMTP发送报告邮件

## 错误处理
– 飞书API不可用 → 使用缓存数据 + 标注"数据可能不是最新"
– 邮件发送失败 → 保存报告到本地 + 通知用户手动发送
– 文档解析失败 → 跳过该部分 + 在报告中标注"解析失败"

3.7 触发条件调度器

四种触发条件由统一的调度器管理，确保触发逻辑的有序执行：

class TriggerDispatcher:
"""触发条件调度器"""

def __init__(self):
self.frequency_engine = FrequencyTriggerEngine()
self.self_heal_detector = SelfHealTriggerDetector()
self.correction_analyzer = UserCorrectionAnalyzer()
self.manual_creator = ManualSkillCreator()
self.trigger_queue = TriggerQueue()

def evaluate_triggers(self, event: AgentEvent) –> list:
"""
评估所有触发条件，返回触发的Skill生成任务列表

触发优先级:
1. 手动创建（用户显式请求）
2. 自修复触发（错误恢复链路）
3. 用户纠正触发（纠正语句）
4. 频次触发（操作模式重复）
"""
triggers = []

# 1. 检查手动创建
if event.type == EventType.USER_REQUEST_SKILL_CREATION:
manual_trigger = self.manual_creator.process_request(event)
if manual_trigger:
triggers.append(manual_trigger)
return triggers # 手动创建优先级最高，直接返回

# 2. 检查自修复触发
if event.type == EventType.TASK_COMPLETED:
self_heal_trigger = self.self_heal_detector.detect_self_heal_trigger(
event.task_context
)
if self_heal_trigger.triggered:
triggers.append(self_heal_trigger)

# 3. 检查用户纠正触发
if event.type == EventType.USER_INPUT:
correction = self.correction_analyzer.analyze_correction(
event.user_input, event.agent_behavior
)
if correction.should_trigger:
triggers.append(correction)

# 4. 检查频次触发
if event.type == EventType.OPERATION_COMPLETED:
freq_trigger = self.frequency_engine.check_trigger(event.operation)
if freq_trigger.triggered:
triggers.append(freq_trigger)

for trigger in triggers:
self.trigger_queue.enqueue(trigger)

return triggers

3.8 本章小结

本章深入分析了四种触发条件的实现机制：频次触发通过操作模式签名和相似度计算实现重复模式检测；自修复触发通过错误-修复链路提取和通用性评估实现智能技能沉淀；用户纠正触发通过语义分析将用户纠正转化为可复用的偏好规则；手动创建提供了用户主动定义Skill的完整交互流程。四种触发条件由统一的调度器管理，按优先级有序执行，共同构成了Skill系统的技能发现矩阵。

第四章 Skill生成全流程

4.1 生成流程总览

当触发条件满足后，系统启动Skill生成引擎，将检测到的操作模式或修复链路转化为一个完整的、可验证的Skill定义。整个生成流程分为六个阶段：发现 → 提炼 → 定义格式 → 验证 → 注册 → 激活。

┌─────────────────────────────────────────────────────────────────────────────┐
│ Skill 生成全流程图 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ │
│ │ 触发条件 │ │
│ │ 满足 │ │
│ └────┬─────┘ │
│ │ │
│ ┌────▼──────────────────────────────────────────┐ │
│ │ 阶段1: 发现 │ │
│ │ – 收集操作历史/错误链路/纠正内容 │ │
│ │ – 提取操作模式签名 │ │
│ │ – 确定Skill的目标功能 │ │
│ └────┬──────────────────────────────────────────┘ │
│ │ │
│ ┌────▼──────────────────────────────────────────┐ │
│ │ 阶段2: 提炼 │ │
│ │ – 从多次操作中提炼通用模式 │ │
│ │ – 抽象参数和返回值 │ │
│ │ – 确定执行步骤序列 │ │
│ │ – 识别错误处理逻辑 │ │
│ └────┬──────────────────────────────────────────┘ │
│ │ │
│ ┌────▼──────────────────────────────────────────┐ │
│ │ 阶段3: 定义格式 │ │
│ │ – 生成SKILL.md文件 │ │
│ │ – 填写YAML前置元数据 │ │
│ │ – 编写Markdown正文 │ │
│ │ – 生成执行脚本 │ │
│ │ – 生成测试用例 │ │
│ └────┬──────────────────────────────────────────┘ │
│ │ │
│ ┌────▼──────────────────────────────────────────┐ │
│ │ 阶段4: 验证 │ │
│ │ – 语法验证: SKILL.md格式检查 │ │
│ │ – 行为验证: 沙箱执行测试 │ │
│ │ – 安全验证: 权限和安全审查 │ │
│ └────┬──────────────────────────────────────────┘ │
│ │ │
│ ├── 验证失败 → 返回阶段3修正 → 重新验证（最多3次） │
│ │ │
│ ├── 验证失败3次 → 标记为草稿，等待手动修正 │
│ │ │
│ ┌────▼──────────────────────────────────────────┐ │
│ │ 阶段5: 注册 │ │
│ │ – 将Skill注册到全局索引 │ │
│ │ – 生成语义嵌入向量 │ │
│ │ – 建立分类和标签关联 │ │
│ └────┬──────────────────────────────────────────┘ │
│ │ │
│ ┌────▼──────────────────────────────────────────┐ │
│ │ 阶段6: 激活 │ │
│ │ – 状态变更为active │ │
│ │ – 初始化质量指标 │ │
│ │ – 通知用户（轻量提示） │ │
│ └────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘

4.2 阶段一：发现

发现阶段是Skill生成的起点，其核心任务是从触发事件中收集足够的信息，为后续的提炼阶段提供原始材料。

class SkillDiscoveryPhase:
"""Skill生成 – 发现阶段"""

def discover(self, trigger_result: TriggerResult) –> DiscoveryResult:
"""从触发结果中发现可沉淀的Skill信息"""
result = DiscoveryResult()
result.trigger_source = trigger_result.trigger_source

if trigger_result.trigger_source == "frequency":
result.operations = self._collect_operations(
trigger_result.similar_patterns
)
result.pattern_summary = self._summarize_pattern(
trigger_result.pattern, result.operations
)
elif trigger_result.trigger_source == "self_heal":
result.error_recovery_chain = trigger_result.error_recovery_chain
result.abstraction = trigger_result.abstraction
result.operations = self._extract_operations_from_chain(
trigger_result.error_recovery_chain
)
elif trigger_result.trigger_source == "user_correction":
result.correction_rule = trigger_result.rule
result.agent_behavior = trigger_result.agent_behavior
elif trigger_result.trigger_source == "manual":
result.user_requirement = trigger_result.user_requirement
result.operations = []

result.context = trigger_result.context
result.timestamp = datetime.now()
return result

发现阶段信息汇总示例（频次触发 format_json）：

输入信息:
– 触发来源: frequency
– 触发次数: 5
– 操作模式: format_data | json_string | formatted_string | [python]

收集的5次操作详情:
操作1: "帮我把这段JSON格式化"
– 输入: '{"name":"test","value":123}'
– 输出: '{\\n "name": "test",\\n "value": 123\\n}'
– 工具: python_executor, 参数: {indent: 2}
– 成功: true, 耗时: 120ms

操作2: "这个JSON太乱了，帮我整理一下"
– 输入: '{"a":1,"b":[2,3],"c":{"d":4}}'
– 输出: 格式化后的JSON
– 工具: python_executor, 参数: {indent: 2}
– 成功: true, 耗时: 95ms

… (操作3-5类似)

模式摘要:
– 意图: format_data (数据格式化)
– 输入类型: JSON字符串
– 输出类型: 格式化的JSON字符串
– 核心步骤: parse_json → serialize_with_indent
– 关键参数: indent (默认2)
– 成功率: 5/5 = 100%, 平均耗时: 108ms

4.3 阶段二：提炼

提炼阶段是Skill生成的核心环节，其任务是从发现阶段收集的原始信息中提炼出通用的、可复用的操作模式。

class SkillDistillationPhase:
"""Skill生成 – 提炼阶段"""

def distill(self, discovery: DiscoveryResult) –> DistillationResult:
"""从发现的信息中提炼通用Skill模式"""
result = DistillationResult()

# 1. 提炼Skill名称和描述
result.name = self._generate_skill_name(discovery)
result.display_name = self._generate_display_name(discovery)
result.description = self._generate_description(discovery)

# 2. 提炼参数模式
result.parameters = self._distill_parameters(discovery.operations)

# 3. 提炼执行步骤
result.execution_steps = self._distill_execution_steps(discovery.operations)

# 4. 提炼返回值结构
result.returns = self._distill_returns(discovery.operations)

# 5. 提炼错误处理逻辑
result.error_handling = self._distill_error_handling(discovery.operations)

# 6. 提炼权限需求
result.permissions = self._distill_permissions(discovery)

# 7. 提炼约束条件
result.constraints = self._distill_constraints(discovery.operations)

# 8. 生成标签和分类
result.tags = self._generate_tags(discovery)
result.category = self._classify_category(discovery)

return result

def _distill_parameters(self, operations: list) –> list:
"""
从多次操作中提炼通用参数模式

策略:
1. 收集所有操作中出现的参数
2. 统计每个参数的出现频率
3. 高频参数(>=80%)标记为required
4. 推断参数类型和默认值
"""
param_stats = {}

for op in operations:
for param_name, param_value in op.get("parameters", {}).items():
if param_name not in param_stats:
param_stats[param_name] = {
"count": 0, "types": set(),
"values": [], "total_ops": len(operations)
}
param_stats[param_name]["count"] += 1
param_stats[param_name]["types"].add(type(param_value).__name__)
param_stats[param_name]["values"].append(param_value)

parameters = []
for param_name, stats in param_stats.items():
frequency = stats["count"] / stats["total_ops"]
param_def = {
"name": param_name,
"type": self._infer_type(stats["types"]),
"required": frequency >= 0.8,
"description": self._infer_description(param_name, stats),
}
if not param_def["required"]:
param_def["default"] = self._infer_default(stats["values"])
parameters.append(param_def)

return parameters

提炼示例（频次触发 format_json）：

1. 名称提炼:
– 关键词: "格式化", "JSON", "整理"
– Skill名称: format_json, 显示名称: JSON格式化

2. 参数提炼:
– input: 5/5出现 → required=true, type=string
– indent: 4/5出现 → required=false, type=integer, default=2
– sort_keys: 1/5出现 → required=false, type=boolean, default=false

3. 执行步骤提炼:
Step 1: parse_json(${param:input}) → json_object
Step 2: serialize_json(json_object, ${param:indent}, ${param:sort_keys}) → output
Step 3: return output

4. 错误处理提炼:
– 输入不是有效JSON → 返回解析错误
– 输入为空 → 返回提示信息

5. 权限提炼: Level 0 (最低, 无文件/网络/Shell访问)
6. 约束提炼: max_execution_time=5000ms, max_memory=50MB, rate_limit=100/min

4.4 阶段三：定义格式

定义格式阶段将提炼结果转化为符合规范的SKILL.md文件和配套脚本。

class SkillDefinitionGenerator:
"""Skill定义格式生成器"""

def generate(self, distillation, discovery) –> SkillDefinition:
# 1. 生成YAML前置元数据
yaml_metadata = self._generate_yaml_metadata(distillation, discovery)
# 2. 生成Markdown正文
markdown_body = self._generate_markdown_body(distillation, discovery)
# 3. 合并为SKILL.md
skill_md = f"—\\n{yaml_metadata}\\n—\\n\\n{markdown_body}"
# 4. 生成执行脚本
script = self._generate_script(distillation)
# 5. 生成测试用例
tests = self._generate_tests(distillation, discovery)
return SkillDefinition(
skill_md=skill_md, script=script,
tests=tests, metadata=distillation
)

4.5 阶段四：验证

验证阶段是Skill生成流程中的安全屏障，所有自动生成的Skill必须通过三级验证才能进入注册阶段。

class SkillValidationPhase:
"""Skill生成 – 验证阶段"""
MAX_RETRY = 3

def validate(self, skill_def) –> ValidationResult:
result = ValidationResult()
retry_count = 0

while retry_count < self.MAX_RETRY:
# Level 1: 语法验证
syntax_result = self.syntax_validator.validate(skill_def)
if not syntax_result.passed:
skill_def = self._attempt_syntax_fix(skill_def, syntax_result)
retry_count += 1
continue

# Level 2: 行为验证
behavior_result = self.behavior_validator.validate(skill_def)
if not behavior_result.passed:
skill_def = self._attempt_behavior_fix(skill_def, behavior_result)
retry_count += 1
continue

# Level 3: 安全验证
security_result = self.security_validator.validate(skill_def)
if not security_result.passed:
result.passed = False
result.reason = "security_validation_failed"
return result

result.passed = True
result.validated_skill = skill_def
return result

result.passed = False
result.reason = "max_retry_exceeded"
return result

4.6 阶段五：注册

注册阶段将验证通过的Skill添加到全局Skill索引中，使其可被检索和加载。

class SkillRegistrationPhase:
"""Skill生成 – 注册阶段"""

def register(self, skill_def, validation) –> RegistrationResult:
# 1. 生成Skill ID
skill_id = f"{skill_def.name}_v{skill_def.version}"

# 2. 检查ID冲突
if self.skill_index.exists(skill_id):
return RegistrationResult(success=False, reason="skill_id_conflict")

# 3. 生成语义嵌入向量
embedding = self.embedding_generator.generate(
f"{skill_def.name} {skill_def.description} {skill_def.tags}"
)

# 4. 构建并写入索引条目
index_entry = {
"skill_id": skill_id,
"name": skill_def.name,
"display_name": skill_def.display_name,
"version": skill_def.version,
"status": "validating",
"category": skill_def.category,
"tags": skill_def.tags,
"trigger_source": skill_def.trigger_source,
"quality_score": None,
"last_called": None,
"call_count_30d": 0,
"skill_path": skill_def.skill_md_path,
"semantic_embedding": embedding,
"description_summary": skill_def.description[:200],
}
self.skill_index.add(index_entry)
self.file_store.save_skill(skill_def)

return RegistrationResult(success=True, skill_id=skill_id)

4.7 阶段六：激活

激活阶段是Skill生成流程的最后一步，将Skill状态从"验证中"变更为"激活"，并初始化质量监控。

class SkillActivationPhase:
"""Skill生成 – 激活阶段"""

def activate(self, skill_id: str) –> ActivationResult:
skill_entry = self.skill_index.get(skill_id)
if not skill_entry:
return ActivationResult(success=False, reason="skill_not_found")

if skill_entry["status"] != "validating":
return ActivationResult(success=False, reason="invalid_status")

# 状态变更: validating → active
self.skill_index.update_status(skill_id, "active")

# 初始化质量指标
initial_metrics = {
"success_rate": 1.0,
"satisfaction": None,
"efficiency": None,
"reuse_freq": 0.0,
"total_calls": 0,
"last_called": None,
"quality_score": 0.5,
"metrics_history": []
}
self.quality_store.init_metrics(skill_id, initial_metrics)

# 设置定时触发
if skill_entry.get("schedule"):
self.scheduler.add_job(skill_id, skill_entry["schedule"])

notification = self._generate_notification(skill_entry)
return ActivationResult(
success=True, skill_id=skill_id,
status="active", notification=notification
)

def _generate_notification(self, skill_entry: dict) –> str:
trigger_desc = {
"frequency": "检测到你多次执行相同操作",
"self_heal": "检测到错误自修复成功",
"user_correction": "根据你的反馈",
"manual": "根据你的要求"
}
source = trigger_desc.get(skill_entry["trigger_source"], "自动检测")
return (
f"✅ 新Skill已创建: {skill_entry['display_name']}\\n"
f" {source}，已自动生成「{skill_entry['display_name']}」技能。\\n"
f" 下次遇到类似场景将自动使用此技能。"
)

4.8 生成流程的状态追踪

# Skill生成状态追踪记录示例
generation_tracker:
skill_id: "format_json_v1.0.0"
trigger_source: "frequency"
started_at: "2026-07-05T11:00:05+08:00"

phases:
discovery:
status: completed
duration_ms: 3000
details:
operations_collected: 5

distillation:
status: completed
duration_ms: 7000
details:
parameters_distilled: 3
execution_steps: 3

definition:
status: completed
duration_ms: 7000
details:
skill_md_generated: true
script_generated: true
tests_generated: true

validation:
status: completed
duration_ms: 13000
retry_count: 1
details:
syntax_validation: passed
behavior_validation: passed (after 1 retry)
security_validation: passed

registration:
status: completed
duration_ms: 2000
details:
skill_id_assigned: "format_json_v1.0.0"

activation:
status: completed
duration_ms: 1000
details:
status_changed_to: active
user_notified: true

total_duration_ms: 33000
final_status: active

4.9 本章小结

本章详细描述了Skill生成的六个阶段：发现阶段收集原始操作数据，提炼阶段从中抽取通用模式，定义格式阶段生成SKILL.md和执行脚本，验证阶段执行三级安全检查，注册阶段将Skill添加到全局索引，激活阶段完成状态变更和质量监控初始化。整个流程支持失败重试（最多3次），并在每个阶段记录详细的追踪信息，确保生成过程的可追溯性。

第五章 三级验证体系

5.1 验证体系架构

Skill的三级验证体系是确保自动生成Skill安全性和可靠性的核心保障。每一级验证聚焦不同的验证维度，形成层层递进的安全屏障。

┌─────────────────────────────────────────────────────────────────────────────┐
│ Skill 三级验证体系架构图 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ Level 1: 语法验证层 │ │
│ │ SyntaxValidator │ │
│ ├───────────────────────────────────────────────────────────────────┤ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ YAML格式 │ │ 字段完整性 │ │ 类型正确性 │ │ │
│ │ │ 检查器 │ │ 检查器 │ │ 检查器 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 命名规范 │ │ 版本号格式 │ │ 参数约束 │ │ │
│ │ │ 检查器 │ │ 检查器 │ │ 检查器 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────┬───────────────────────────────────────┘ │
│ │ 通过 │
│ ┌───────────────────────────▼───────────────────────────────────────┐ │
│ │ Level 2: 行为验证层 │ │
│ │ BehaviorValidator │ │
│ ├───────────────────────────────────────────────────────────────────┤ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 沙箱环境 │ │ 测试用例 │ │ 边界条件 │ │ │
│ │ │ 执行器 │ │ 运行器 │ │ 测试器 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 超时检测 │ │ 资源监控 │ │ 输出验证 │ │ │
│ │ │ 器 │ │ 器 │ │ 器 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────┬───────────────────────────────────────┘ │
│ │ 通过 │
│ ┌───────────────────────────▼───────────────────────────────────────┐ │
│ │ Level 3: 安全验证层 │ │
│ │ SecurityValidator │ │
│ ├───────────────────────────────────────────────────────────────────┤ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 权限边界 │ │ 资源访问 │ │ 恶意代码 │ │ │
│ │ │ 检查器 │ │ 审计器 │ │ 扫描器 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 注入攻击 │ │ 敏感信息 │ │ 依赖安全 │ │ │
│ │ │ 检测器 │ │ 泄露检测 │ │ 检查器 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────┬───────────────────────────────────────┘ │
│ │ 通过 │
│ ┌───────────────────────────▼───────────────────────────────────────┐ │
│ │ 验证通过 → 进入注册阶段 │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘

5.2 验证层级对比

5.3 Level 1: 语法验证

5.3.1 语法验证器实现

class SyntaxValidator:
"""Level 1 语法验证器"""

def validate(self, skill_def: SkillDefinition) –> SyntaxValidationResult:
"""执行语法验证"""
result = SyntaxValidationResult()
issues = []

# 1. YAML格式验证
yaml_issues = self._validate_yaml_format(skill_def.yaml_metadata)
issues.extend(yaml_issues)

# 2. 字段完整性验证
field_issues = self._validate_field_completeness(skill_def)
issues.extend(field_issues)

# 3. 类型正确性验证
type_issues = self._validate_type_correctness(skill_def)
issues.extend(type_issues)

# 4. 命名规范验证
naming_issues = self._validate_naming_convention(skill_def)
issues.extend(naming_issues)

# 5. 版本号格式验证
version_issues = self._validate_version_format(skill_def)
issues.extend(version_issues)

# 6. 参数约束验证
param_issues = self._validate_parameter_constraints(skill_def)
issues.extend(param_issues)

result.issues = issues
result.passed = len([i for i in issues if i.severity == "error"]) == 0
result.warnings = [i for i in issues if i.severity == "warning"]
result.errors = [i for i in issues if i.severity == "error"]

return result

def _validate_yaml_format(self, yaml_str: str) –> list:
"""验证YAML格式"""
issues = []
try:
metadata = yaml.safe_load(yaml_str)
if not isinstance(metadata, dict):
issues.append(ValidationIssue(
severity="error", field="yaml",
message="YAML内容必须是字典类型"
))
except yaml.YAMLError as e:
issues.append(ValidationIssue(
severity="error", field="yaml",
message=f"YAML解析错误: {str(e)}"
))
return issues

def _validate_field_completeness(self, skill_def) –> list:
"""验证字段完整性"""
issues = []
required_fields = [
"name", "version", "author", "created_at",
"updated_at", "status", "trigger_source", "tools"
]
for field in required_fields:
if not hasattr(skill_def, field) or getattr(skill_def, field) is None:
issues.append(ValidationIssue(
severity="error", field=field,
message=f"必填字段缺失: {field}"
))
if not skill_def.tools or len(skill_def.tools) == 0:
issues.append(ValidationIssue(
severity="error", field="tools",
message="至少需要定义一个工具"
))
return issues

def _validate_type_correctness(self, skill_def) –> list:
"""验证类型正确性"""
issues = []
valid_types = {"string", "integer", "float", "boolean",
"array", "object", "file", "enum"}
for tool in skill_def.tools:
for param in tool.parameters:
if param.type not in valid_types:
issues.append(ValidationIssue(
severity="error",
field=f"tools.{tool.name}.parameters.{param.name}.type",
message=f"无效的参数类型: {param.type}"
))
if param.type == "enum" and not param.enum_values:
issues.append(ValidationIssue(
severity="error",
field=f"tools.{tool.name}.parameters.{param.name}",
message="enum类型参数必须定义enum值列表"
))
if param.type in ("integer", "float"):
if param.min is not None and param.max is not None:
if param.min > param.max:
issues.append(ValidationIssue(
severity="error",
field=f"tools.{tool.name}.parameters.{param.name}",
message=f"min({param.min})不能大于max({param.max})"
))
return issues

def _validate_naming_convention(self, skill_def) –> list:
"""验证命名规范"""
issues = []
import re
name_pattern = r'^[a-z][a-z0-9_]{0,63}$'
if not re.match(name_pattern, skill_def.name):
issues.append(ValidationIssue(
severity="error", field="name",
message="名称必须以小写字母开头，仅含小写字母/数字/下划线，最长64字符"
))
return issues

def _validate_version_format(self, skill_def) –> list:
"""验证版本号格式"""
issues = []
import re
version_pattern = r'^\\d+\\.\\d+\\.\\d+$'
if not re.match(version_pattern, skill_def.version):
issues.append(ValidationIssue(
severity="error", field="version",
message="版本号必须符合语义化版本格式: MAJOR.MINOR.PATCH"
))
return issues

def _validate_parameter_constraints(self, skill_def) –> list:
"""验证参数约束"""
issues = []
for tool in skill_def.tools:
for param in tool.parameters:
if param.required and param.default is not None:
issues.append(ValidationIssue(
severity="warning",
field=f"tools.{tool.name}.parameters.{param.name}",
message="必填参数不应设置默认值"
))
if not param.required and param.default is None:
if param.type != "enum":
issues.append(ValidationIssue(
severity="warning",
field=f"tools.{tool.name}.parameters.{param.name}",
message="非必填参数建议设置默认值"
))
return issues

5.3.2 语法验证报告示例

{
"validation_level": "syntax",
"skill_id": "format_json_v1.0.0",
"timestamp": "2026-07-05T11:00:22+08:00",
"passed": true,
"duration_ms": 45,
"checks_performed": 6,
"issues": [
{
"severity": "warning",
"field": "tools.format_json.parameters.sort_keys",
"message": "非必填参数建议设置默认值"
}
],
"errors": [],
"warnings_count": 1,
"errors_count": 0,
"details": {
"yaml_format": "passed",
"field_completeness": "passed",
"type_correctness": "passed",
"naming_convention": "passed",
"version_format": "passed",
"parameter_constraints": "passed (1 warning)"
}
}

5.4 Level 2: 行为验证

5.4.1 行为验证器实现

class BehaviorValidator:
"""Level 2 行为验证器"""

SANDBOX_TIMEOUT = 10000 # 沙箱超时: 10秒
MAX_MEMORY_MB = 200 # 最大内存: 200MB

def validate(self, skill_def: SkillDefinition) –> BehaviorValidationResult:
"""执行行为验证"""
result = BehaviorValidationResult()
issues = []

# 1. 准备测试用例
test_cases = self._prepare_test_cases(skill_def)

# 2. 在沙箱中执行测试
for test_case in test_cases:
test_result = self._run_in_sandbox(skill_def, test_case)
if not test_result.passed:
issues.append(ValidationIssue(
severity="error",
field=f"test_case.{test_case.name}",
message=test_result.error_message
))

# 3. 边界条件测试
boundary_tests = self._generate_boundary_tests(skill_def)
for test in boundary_tests:
test_result = self._run_in_sandbox(skill_def, test)
if not test_result.passed:
issues.append(ValidationIssue(
severity="error",
field=f"boundary_test.{test.name}",
message=test_result.error_message
))

# 4. 超时检测
timeout_result = self._check_timeout_behavior(skill_def)
if not timeout_result.passed:
issues.append(ValidationIssue(
severity="error", field="timeout",
message=f"Skill执行超时: {timeout_result.actual_time}ms"
))

# 5. 资源使用检测
resource_result = self._check_resource_usage(skill_def)
if resource_result.memory_used > self.MAX_MEMORY_MB:
issues.append(ValidationIssue(
severity="error", field="memory",
message=f"内存使用超限: {resource_result.memory_used}MB"
))

result.issues = issues
result.passed = len([i for i in issues if i.severity == "error"]) == 0
return result

def _run_in_sandbox(self, skill_def, test_case) –> SandboxTestResult:
"""在隔离沙箱中执行测试"""
sandbox = Sandbox(
timeout=self.SANDBOX_TIMEOUT,
max_memory=self.MAX_MEMORY_MB,
allowed_paths=skill_def.permissions.filesystem,
allowed_domains=skill_def.permissions.network.domains,
disabled_shell=not skill_def.permissions.shell.allowed
)

try:
result = sandbox.execute(
script=skill_def.script,
entry_point=skill_def.tools[0].name,
parameters=test_case.parameters
)

if test_case.expected_output is not None:
if not self._compare_output(result.output, test_case.expected_output):
return SandboxTestResult(
passed=False,
error_message=f"输出不匹配: 期望 {test_case.expected_output}, "
f"实际 {result.output}"
)

return SandboxTestResult(
passed=True,
output=result.output,
execution_time_ms=result.execution_time,
memory_used_mb=result.memory_used
)
except TimeoutError:
return SandboxTestResult(
passed=False,
error_message=f"执行超时（{self.SANDBOX_TIMEOUT}ms）"
)
except Exception as e:
return SandboxTestResult(
passed=False,
error_message=f"执行异常: {str(e)}"
)

def _generate_boundary_tests(self, skill_def) –> list:
"""生成边界条件测试用例"""
tests = []
for tool in skill_def.tools:
for param in tool.parameters:
if param.type in ("integer", "float"):
if param.min is not None:
tests.append(TestCase(
name=f"{param.name}_min_boundary",
parameters={param.name: param.min}
))
if param.max is not None:
tests.append(TestCase(
name=f"{param.name}_max_boundary",
parameters={param.name: param.max}
))
elif param.type == "string":
tests.append(TestCase(
name=f"{param.name}_empty",
parameters={param.name: ""}
))
tests.append(TestCase(
name=f"{param.name}_very_long",
parameters={param.name: "x" * 10000}
))
return tests

5.4.2 行为验证报告示例

{
"validation_level": "behavior",
"skill_id": "format_json_v1.0.0",
"timestamp": "2026-07-05T11:00:28+08:00",
"passed": true,
"duration_ms": 3200,
"sandbox_config": {
"timeout_ms": 10000,
"max_memory_mb": 200,
"isolation": "container"
},
"test_results": [
{
"test_name": "basic_format",
"passed": true,
"execution_time_ms": 45,
"memory_used_mb": 12
},
{
"test_name": "nested_json",
"passed": true,
"execution_time_ms": 52,
"memory_used_mb": 15
},
{
"test_name": "empty_input",
"passed": true,
"execution_time_ms": 8,
"memory_used_mb": 8,
"note": "正确处理空输入，返回提示信息"
}
],
"boundary_results": [
{
"test_name": "indent_min_boundary",
"passed": true,
"note": "indent=0 正确处理"
},
{
"test_name": "indent_max_boundary",
"passed": true,
"note": "indent=8 正确处理"
},
{
"test_name": "input_very_long",
"passed": true,
"execution_time_ms": 320,
"memory_used_mb": 45,
"note": "10000字符JSON正确处理"
}
],
"timeout_check": "passed (max 320ms / limit 10000ms)",
"resource_check": "passed (max 45MB / limit 200MB)",
"issues": []
}

5.5 Level 3: 安全验证

5.5.1 安全验证器实现

class SecurityValidator:
"""Level 3 安全验证器"""

DANGEROUS_SHELL_PATTERNS = [
r"rm\\s+-rf\\s+/",
r"chmod\\s+777",
r"curl\\s+.*\\|\\s*sh",
r"wget\\s+.*\\|\\s*bash",
r"eval\\s*\\(",
r"exec\\s*\\(",
r"subprocess\\.(call|run|Popen)\\s*\\(.*shell=True",
r"os\\.system\\s*\\(",
r"__import__\\s*\\(['\\"]os['\\"]\\)",
]

SENSITIVE_DATA_PATTERNS = [
r"(?i)password\\s*=\\s*['\\"][^'\\"]+['\\"]",
r"(?i)api[_-]?key\\s*=\\s*['\\"][^'\\"]+['\\"]",
r"(?i)secret\\s*=\\s*['\\"][^'\\"]+['\\"]",
r"(?i)token\\s*=\\s*['\\"][^'\\"]+['\\"]",
r"—–BEGIN\\s+(RSA\\s+)?PRIVATE\\s+KEY—–",
r"sk-[a-zA-Z0-9]{20,}",
]

INJECTION_PATTERNS = [
r";\\s*(rm|del|drop|truncate)\\s",
r"–\\s*$",
r"';\\s*DROP\\s+TABLE",
r"<script[^>]*>",
r"javascript:",
r"on\\w+\\s*=\\s*['\\"]",
]

def validate(self, skill_def: SkillDefinition) –> SecurityValidationResult:
"""执行安全验证"""
result = SecurityValidationResult()
issues = []

# 1. 权限边界检查
issues.extend(self._check_permission_boundaries(skill_def))

# 2. 资源访问审计
issues.extend(self._audit_resource_access(skill_def))

# 3. 恶意代码扫描
issues.extend(self._scan_malicious_code(skill_def))

# 4. 注入攻击检测
issues.extend(self._detect_injection_attacks(skill_def))

# 5. 敏感信息泄露检测
issues.extend(self._detect_sensitive_data_leak(skill_def))

# 6. 依赖安全检查
issues.extend(self._check_dependency_security(skill_def))

result.issues = issues
result.passed = len([i for i in issues if i.severity == "error"]) == 0
result.critical_issues = [i for i in issues if i.severity == "critical"]
return result

def _check_permission_boundaries(self, skill_def) –> list:
"""检查权限边界"""
issues = []
max_permissions = {
"frequency": 2,
"self_heal": 2,
"user_correction": 1,
"manual": 4,
}
max_level = max_permissions.get(skill_def.trigger_source, 1)
actual_level = self._calculate_permission_level(skill_def.permissions)

if actual_level > max_level:
issues.append(ValidationIssue(
severity="error", field="permissions",
message=f"权限级别(Level {actual_level})超出触发来源"
f"({skill_def.trigger_source})允许的最大级别(Level {max_level})"
))

for path in skill_def.permissions.filesystem.get("read", []):
if path in ("/**", "/*"):
issues.append(ValidationIssue(
severity="error", field="permissions.filesystem.read",
message=f"不允许使用全局通配符路径: {path}"
))

if skill_def.permissions.shell.allowed and skill_def.trigger_source != "manual":
issues.append(ValidationIssue(
severity="error", field="permissions.shell",
message="非手动创建的Skill不允许Shell执行权限"
))
return issues

def _scan_malicious_code(self, skill_def) –> list:
"""扫描恶意代码"""
issues = []
script_content = skill_def.script

for pattern in self.DANGEROUS_SHELL_PATTERNS:
matches = re.finditer(pattern, script_content, re.IGNORECASE)
for match in matches:
issues.append(ValidationIssue(
severity="critical", field="script",
message=f"检测到危险代码模式: {pattern}"
))
return issues

def _detect_injection_attacks(self, skill_def) –> list:
"""检测注入攻击"""
issues = []
all_content = skill_def.script + "\\n" + skill_def.skill_md
for pattern in self.INJECTION_PATTERNS:
matches = re.finditer(pattern, all_content, re.IGNORECASE)
for match in matches:
issues.append(ValidationIssue(
severity="error", field="content",
message=f"检测到潜在注入攻击模式: {pattern[:30]}"
))
return issues

def _detect_sensitive_data_leak(self, skill_def) –> list:
"""检测敏感信息泄露"""
issues = []
all_content = skill_def.script + "\\n" + skill_def.skill_md
for pattern in self.SENSITIVE_DATA_PATTERNS:
matches = re.finditer(pattern, all_content)
for match in matches:
issues.append(ValidationIssue(
severity="error", field="content",
message=f"检测到潜在敏感信息泄露"
))
return issues

def _check_dependency_security(self, skill_def) –> list:
"""检查依赖安全性"""
issues = []
for dep in skill_def.dependencies.get("packages", []):
package_name = list(dep.values())[0]
if package_name in self.KNOWN_VULNERABLE_PACKAGES:
issues.append(ValidationIssue(
severity="warning", field="dependencies",
message=f"依赖包 {package_name} 存在已知漏洞"
))
return issues

def _calculate_permission_level(self, permissions) –> int:
"""计算权限级别"""
level = 0
if permissions.filesystem.get("read") or permissions.filesystem.get("write"):
level = max(level, 1)
if permissions.filesystem.get("write"):
level = max(level, 2)
if permissions.network.get("allowed"):
level = max(level, 2)
if permissions.shell.get("allowed"):
level = max(level, 3)
if "L4" in permissions.memory.get("read_layers", []):
level = max(level, 4)
return level