15.1 Skills 执行机制

Skills 执行机制概述

Skills 的执行机制是理解其工作原理的核心。本节将深入探讨 Skills 如何被调用、解析和执行，以及整个执行流程中的关键环节。

执行流程概览

Skills 的执行流程可以分为以下几个主要阶段：

graph

A[用户请求] --> B[主代理接收]

    B --> C{选择 Skill}
    C --> D[加载 Skill 定义]

D --> E[解析参数和上下文]

    E --> F[执行 Skill 逻辑]

F --> G[调用工具] G --> H[处理结果] H --> I[返回输出] I --> J[主代理整合] J --> K[呈现给用户]

1. Skill 调用

调用方式

1.1 直接调用

用户直接指定要使用的 Skill：

    # 命令行调用
    claude --skill code-review --file src/main.py
 
    # 交互式调用
    /skill code-review

主代理根据任务自动选择合适的 Skill：

    ## 自动选择流程
    ### 用户请求
    "帮我审查这段代码的质量"
 
    ### 主代理分析
    1. 理解用户意图
    2. 搜索相关 Skills
    3. 匹配最合适的 Skill
    4. 执行并返回结果

一个 Skill 调用另一个 Skill：

    markdown
 
    ## 嵌套调用示例
 
    ### Skill: 部署应用
 
    #### 执行步骤
    1. 调用代码审查 Skill
    2. 调用测试运行 Skill
    3. 调用部署 Skill
    4. 生成部署报告

参数传递

    ## 参数传递方式
 
    ### 命令行参数
 
    ```bash
 
    claude --skill code-gen --language python --framework flask

交互式输入

    > 请提供以下信息：
    > - 编程语言：Python
    > - 框架：Flask
    > - 功能描述：用户认证系统

配置文件

skills:
  code-gen:
    language: python
    framework: flask

上下文推断

    ## 从上下文推断
    - 从文件扩展名推断语言
    - 从项目配置推断框架
    - 从代码风格推断风格偏好
    - 从历史记录推断用户偏好

2. Skill 加载

加载过程

2.1 定位 Skill

    ## Skill 定位流程
 
    ### 搜索顺序
    1. 项目本地 Skills
    2. 用户自定义 Skills
    3. 系统内置 Skills
    4. 插件提供的 Skills

2.2 读取定义

    ## Skill 定义结构
 
    ### 元数据
 
    ```yaml
 
    name: code-review
    version: 1.2.0
    description: 自动审查代码质量
    author: Claude Code Team

输入规范

inputs:
  file:
    type: string
    required: true
    description: 要审查的文件路径
  strict:
    type: boolean
    required: false
    default: false
    description: 是否严格模式

执行逻辑

    ## 执行步骤
    1. 读取代码文件
    2. 分析代码结构
    3. 检查代码质量
    4. 生成审查报告

2.3 验证定义

    ## 定义验证
 
    ### 验证项
    - 必需字段是否存在
    - 参数类型是否正确
    - 默认值是否有效
    - 引用是否存在
    - 语法是否正确
 
    ### 验证失败处理
    - 返回错误信息
    - 提供修复建议
    - 阻止 Skill 执行

缓存机制

    ## Skill 缓存
 
    ### 缓存内容
    - Skill 定义
    - 解析结果
    - 依赖关系
 
    ### 缓存策略
    - 内存缓存（会话级别）
    - 磁盘缓存（持久化）
    - 版本控制（基于 Skill 版本）
 
    ### 缓存失效
    - Skill 定义更新
    - 依赖变更
    - 手动清除
 
    ## 3. 上下文解析
 
    ### 上下文类型
 
    #### 3.1 项目上下文
 
    ## 3. 上下文管理
 
    ### 3.1 项目上下文
 
    ```markdown
 
    ## 项目上下文
 
    ### 包含信息
    - 项目结构
    - 文件列表
    - 依赖关系
    - 配置文件
    - 技术栈
 
    ### 获取方式
    - 读取项目配置
    - 扫描文件系统
    - 分析依赖文件
    - 检测技术栈

3.2 代码上下文

    ## 代码上下文
 
    ### 包含信息
    - 代码结构
    - 函数定义
    - 类定义
    - 导入关系
    - 调用关系
 
    ### 获取方式
    - 解析源代码
    - 构建抽象语法树
    - 分析符号表
    - 追踪依赖关系

3.3 用户上下文

    ## 用户上下文
 
    ### 包含信息
    - 用户偏好
    - 历史操作
    - 常用命令
    - 学习进度
 
    ### 获取方式
    - 读取用户配置
    - 查看历史记录
    - 分析使用模式
    - 记录用户反馈

上下文收集

    ## 上下文收集策略
 
    ### 按需收集
    - 只收集需要的上下文
    - 避免不必要的开销
    - 动态调整收集范围
 
    ### 增量收集
    - 基于已有上下文
    - 只收集变更部分
    - 减少重复工作
 
    ### 并行收集
    - 同时收集多个上下文
    - 提高收集效率
    - 合理分配资源

上下文限制

    ## 上下文限制
 
    ### 大小限制
    - 上下文窗口大小
    - Token 限制
    - 内存限制
 
    ### 处理策略
    - 优先级排序
    - 摘要压缩
    - 分批处理
    - 流式处理

4. Skill 执行

执行模式

4.1 同步执行

    ## 同步执行
 
    ### 特点
    - 阻塞等待结果
    - 适用于快速任务
    - 简单的错误处理
 
    ### 示例
 
    ```python
 
    result = execute_skill("code-review", file="src/main.py")
    print(result)
 
````bash
 
    #### 4.2 异步执行
 
    ```markdown
 
    ## 异步执行
 
    ### 特点
    - 非阻塞执行
    - 适用于耗时任务
    - 复杂的错误处理
 
    ### 示例
 
    ```python
 
    task = execute_skill_async("code-review", file="src/main.py")
 
    # 继续其他工作
 
    result = await task.get_result()
 
```bash
 
    #### 4.3 流式执行
 
    ```markdown
 
    ## 流式执行
 
    ### 特点
    - 实时返回结果
    - 适用于大输出任务
    - 更好的用户体验
 
    ### 示例
 
    ```python
 
    for chunk in execute_skill_stream("code-review", file="src/main.py"):
        print(chunk, end='')
 
```bash
 
    ### 执行步骤
 
    #### 4.4 步骤分解
 
    ```markdown
 
    ## Skill: 代码审查
 
    ### 执行步骤
    1. **准备阶段**
       - 验证输入参数
       - 加载代码文件
       - 初始化审查规则
 
    2. **分析阶段**
       - 解析代码结构
       - 分析代码质量
       - 检查安全问题
 
    3. **评估阶段**
       - 评估代码复杂度
       - 验证最佳实践
       - 计算质量分数
 
    4. **生成阶段**
       - 生成问题列表
       - 提供改进建议
       - 创建审查报告
 
    5. **验证阶段**
       - 验证报告完整性
       - 检查建议可行性
       - 确保输出格式正确
````

### 错误处理

#### 4.5 错误类型

``````yaml
    ## 错误类型

    ### 输入错误
    - 参数缺失
    > - 参数类型错误
    > - 参数值无效

    ### 执行错误
    > - 文件不存在
    > - 权限不足
    > - 资源不足

    ### 逻辑错误
    > - 无法解析代码
    > - 分析失败
    > - 生成失败

    #### 4.6 错误处理策略

    ~~~markdown
```markdown

    ## 错误处理策略

    ### 立即失败
    - 遇到错误立即停止
    - 返回错误信息
    - 不继续执行

    ### 跳过继续
    - 记录错误
    - 跳过当前步骤
    - 继续执行

    ### 重试机制
    - 自动重试
    - 指数退避
    - 最大重试次数

    ### 降级处理
    - 使用备用方案
    - 简化执行逻辑
    - 返回部分结果

    ## 5. 工具调用

    ### 工具调用机制

    #### 5.1 工具选择

    ```markdown

    ## 工具选择

    ### 选择依据

    > - 任务需求
    > - 可用工具
    > - 工具能力
    > - 性能考虑

    ### 选择策略

    > - 最佳匹配
    > - 优先级排序
    > - 负载均衡
    > - 缓存利用

    #### 5.2 工具调用

    ~~~markdown
```markdown

    ## 工具调用流程

    ### 调用准备

    1. 准备工具参数
    2. 验证参数有效性
    3. 设置调用选项

    ### 执行调用

    1. 发送调用请求
    2. 等待工具响应
    3. 处理响应数据

    ### 结果处理

    1. 解析响应数据
    2. 验证结果有效性
    3. 传递给下一步

    ### 工具调用模式

    #### 5.3 顺序调用

    ```markdown

    ## 顺序调用

    ### 示例
    ~~~python

    ```python

    # 读取文件

    content = read_file("src/main.py")

    # 分析代码

    analysis = analyze_code(content)

    # 生成报告

    report = generate_report(analysis)

    ### 特点

    > - 简单直观
    > - 易于理解
    > - 适合线性流程

    #### 5.4 条件调用

    ~~~
    ``markdown

    `````markdown

    ## 条件调用

    ### 示例
    ~~~python

    ```python

    # 检查文件是否存在

    if file_exists("src/main.py"):

        # 如果存在，读取并分析

        content = read_file("src/main.py")
        analysis = analyze_code(content)
    else:

        # 如果不存在，创建新文件

        create_file("src/main.py", template)

    ### 特点

    > - 灵活性高
    > - 适应性强
    > - 处理分支逻辑

    #### 5.5 循环调用

    ~~~
    ``markdown

    `````markdown

    ## 循环调用

    ### 示例
    ~~~python

    ```python

    # 获取所有 Python 文件

    files = glob("**/*.py")

    # 对每个文件执行分析

```bash
    for file in files:
        content = read_file(file)
        analysis = analyze_code(content)
        save_analysis(file, analysis)

特点

  • 批量处理
  • 高效执行
  • 适合重复任务

5.6 并行调用

``markdown

`````markdown

## 并行调用

### 示例
~~~python

```python

# 并行读取多个文件

tasks = [
    read_file_async("src/main.py"),
    read_file_async("src/utils.py"),
    read_file_async("src/api.py")
]

# 等待所有任务完成

results = await asyncio.gather(*tasks)

### 特点

> - 高性能
> - 节省时间
> - 适合独立任务

## 6. 结果处理

### 结果类型

#### 6.1 结构化结果

``markdown

 
## 结构化结果
 
### 示例
~~~json
 
```json
 
{
  "issues": [
    {
      "type": "security",
      "severity": "high",
      "message": "SQL injection vulnerability",
      "location": "src/main.py:42",
      "suggestion": "Use parameterized queries"
    }
  ],
  "summary": {
    "total_issues": 5,
    "critical": 1,
    "high": 2,
    "medium": 2
  }
}
 
### 特点
 
> - 易于解析
> - 结构清晰
> - 适合程序处理
 
#### 6.2 文本结果
 
~~~
``markdown
 
`````markdown
 
## 文本结果
 
### 示例
 
代码审查报告
 
发现的问题：
 
 - 使用参数化查询
 
 - 删除未使用的导入
 
总结：
> - 总问题数：5
> - 严重：1
> - 高：2
> - 中：2
 
~~~
### 特点
> - 易于阅读
> - 人类友好
> - 适合展示
#### 6.3 混合结果
~~~`markdown
`markdown
 
## 混合结果
 
### 示例
~~~markdown
 
```markdown
 
## 代码审查报告
 
### 结构化数据
 
~~~json
 
```json
 
{
  "total_issues": 5,
  "critical": 1
}
 
### 详细说明
发现 1 个严重问题和 4 个其他问题...
 
### 建议
建议优先修复严重问题...
 
### 特点
- 兼顾机器和人类
- 灵活性高
- 适合复杂场景
~~~
### 结果验证
 
#### 6.4 验证检查
 
~~~
 
`````markdown
## 结果验证
 
### 验证项
- 结果完整性
- 数据有效性
- 格式正确性
- 逻辑一致性
 
### 验证方法
- 模式匹配
- 类型检查
- 逻辑验证
- 交叉验证
 
#### 6.5 结果修正
 
~~~`markdown
 
````markdown
 
## 结果修正
 
### 修正策略
 
> - 自动修正
> - 提示用户
> - 记录问题
> - 重试执行
 
### 修正示例
 
~~~python
 
```python
 
# 自动修正格式问题
result = format_result(raw_result)
 
# 提示用户确认
 
```bash
if not confirm_result(result):
    result = retry_execution()
```
 
### 输出格式
 
#### 7.1 控制台输出
 
## 控制台输出
 
### 特点
 
- 实时显示
- 交互友好
- 适合开发调试
 
### 示例

正在执行代码审查... ✓ 分析代码结构 ✓ 检查安全问题 ✓ 评估代码质量

审查完成！发现 5 个问题。

    #### 7.2 文件输出
 
    ## 文件输出
    ### 特点
    - 持久化存储
    - 可追溯
    - 适合报告归档
    ### 示例
    ~~~`bash
    `bash
 
    claude --skill code-review --file src/main.py --output report.md
 
    ```> >
 
    ~~~
    #### 7.3 API 输出
 
    ## API 输出
    ### 特点
    - 结构化数据
    - 易于集成
    - 适合自动化
    ### 示例
    ~~~`json
    `json
 
    {
    "skill": "code-review",
    "status": "success",
    "result": {...}
    }
 
    ```> > ~~~
 
    ### 输出优化
 
    #### 7.4 性能优化
 
    ## 输出性能优化
 
    ### 优化策略
 
    - 流式输出
    - 增量更新
    - 压缩输出
    - 缓存结果
 
    ### 示例
 
    ~~~`python
    `python
 
    # 流式输出大结果
 
    for chunk in stream_result(result):
    yield chunk
 
    ```> >
 
    ~~~
    #### 7.5 用户体验优化
 
    ## 用户体验优化
    ### 优化策略
    - 进度显示
    - 实时反馈
    - 高亮显示
    - 交互式输出
    ### 示例
    ~~~
    ``> > 正在执行代码审查... [████████░░] 80%
    ✓ 分析代码结构
    ✓ 检查安全问题
    → 评估代码质量...
 
    ~~~## 8. 执行监控
 
    ### 监控指标
 
    #### 8.1 性能指标
 
    ## 性能指标
    ### 指标类型
    - 执行时间
    - 内存使用
    - CPU 使用
    - I/O 操作
    ### 监控方式
    - 实时监控
    - 定期采样
    - 事件触发
    - 阈值告警

8.2 质量指标

 
## 质量指标
 
### 指标类型
 
- 成功率
- 错误率
- 重试次数
- 用户满意度
 
### 监控方式
 
- 统计分析
- 趋势跟踪
- 异常检测
- 反馈收集
 
```### 日志记录
 
#### 8.3 日志级别
 
## 日志级别
### DEBUG
详细的调试信息
- 每个步骤的详细信息
- 中间结果
- 变量值
### INFO
一般信息
- 执行开始/结束
- 主要步骤
- 关键决策
### WARNING
警告信息
- 潜在问题
- 非最佳实践
- 性能警告
### ERROR
错误信息
- 错误详情
- 堆栈跟踪
- 恢复建议
 
#### 8.4 日志格式
 
~~~markdown
 
```markdown
 
## 日志格式
 
### 标准格式
 
```> [2024-01-15 10:30:45] [INFO] [skill:code-review] 开始执行代码审查
 
[2024-01-15 10:30:46] [DEBUG] [skill:code-review] 读取文件: src/main.py
[2024-01-15 10:30:47] [INFO] [skill:code-review] 分析完成，发现 5 个问题
 
### 结构化格式
 
~~~`json
`json
 
{
"timestamp": "2024-01-15T10:30:45Z",
"level": "INFO",
"skill": "code-review",
"message": "开始执行代码审查"
}
 
```> >

总结

Skills 的执行机制是一个复杂而精密的系统，涉及多个环节和组件。理解这些机制有助于：

  1. 优化性能 ：识别和优化性能瓶颈
  2. 提高可靠性 ：增强错误处理和恢复能力
  3. 改善体验 ：提供更好的用户交互体验
  4. 扩展功能 ：基于执行机制开发新功能

在下一节中，我们将探讨 Skills 的上下文管理机制，了解如何高效地管理和利用上下文信息。