Skills 执行机制

graph TD
  A[用户请求] --> B[主代理接收]
  B --> C{选择 Skill}
  C --> D[加载 Skill 定义]
  D --> E[解析参数和上下文]
  E --> F[执行 Skill 逻辑]
  F --> G[调用工具]
  G --> H[处理结果]
  H --> I[返回输出]
  I --> J[主代理整合]
  J --> K[呈现给用户]

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

# 交互式调用
/skill code-review

## 自动选择流程
### 用户请求
"帮我审查这段代码的质量"

### 主代理分析
1. 理解用户意图
2. 搜索相关 Skills
3. 匹配最合适的 Skill
4. 执行并返回结果

## 嵌套调用示例

### Skill: 部署应用

#### 执行步骤
1. 调用代码审查 Skill
2. 调用测试运行 Skill
3. 调用部署 Skill
4. 生成部署报告

# 命令行参数
claude --skill code-gen --language python --framework flask

> 交互式输入
> - 编程语言：Python
> - 框架：Flask
> - 功能描述：用户认证系统

# 配置文件
skills:
  code-gen:
    language: python
    framework: flask

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

## Skill 定位流程

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

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. 生成审查报告

## 定义验证

### 验证项
- 必需字段是否存在
- 参数类型是否正确
- 默认值是否有效
- 引用是否存在
- 语法是否正确

### 验证失败处理
- 返回错误信息
- 提供修复建议
- 阻止 Skill 执行

## Skill 缓存

### 缓存内容
- Skill 定义
- 解析结果
- 依赖关系

### 缓存策略
- 内存缓存（会话级别）
- 磁盘缓存（持久化）
- 版本控制（基于 Skill 版本）

### 缓存失效
- Skill 定义更新
- 依赖变更
- 手动清除

## 项目上下文

### 包含信息
- 项目结构
- 文件列表
- 依赖关系
- 配置文件
- 技术栈

### 获取方式
- 读取项目配置
- 扫描文件系统
- 分析依赖文件
- 检测技术栈

## 代码上下文

### 包含信息
- 代码结构
- 函数定义
- 类定义
- 导入关系
- 调用关系

### 获取方式
- 解析源代码
- 构建抽象语法树
- 分析符号表
- 追踪依赖关系

## 用户上下文

### 包含信息
- 用户偏好
- 历史操作
- 常用命令
- 学习进度

### 获取方式
- 读取用户配置
- 查看历史记录
- 分析使用模式
- 记录用户反馈

## 上下文收集策略

### 按需收集
- 只收集需要的上下文
- 避免不必要的开销
- 动态调整收集范围

### 增量收集
- 基于已有上下文
- 只收集变更部分
- 减少重复工作

### 并行收集
- 同时收集多个上下文
- 提高收集效率
- 合理分配资源

## 上下文限制

### 大小限制
- 上下文窗口大小
- Token 限制
- 内存限制

### 处理策略
- 优先级排序
- 摘要压缩
- 分批处理
- 流式处理

## 同步执行

### 特点
- 阻塞等待结果
- 适用于快速任务
- 简单的错误处理

result = execute_skill("code-review", file="src/main.py")
print(result)

## 异步执行

### 特点
- 非阻塞执行
- 适用于耗时任务
- 复杂的错误处理

task = execute_skill_async("code-review", file="src/main.py")
# 继续其他工作
result = await task.get_result()

## 流式执行

### 特点
- 实时返回结果
- 适用于大输出任务
- 更好的用户体验

for chunk in execute_skill_stream("code-review", file="src/main.py"):
  print(chunk, end='')

## Skill: 代码审查

### 执行步骤
1. **准备阶段**
   - 验证输入参数
   - 加载代码文件
   - 初始化审查规则
2. **分析阶段**
   - 解析代码结构
   - 分析代码质量
   - 检查安全问题
3. **评估阶段**
   - 评估代码复杂度
   - 验证最佳实践
   - 计算质量分数
4. **生成阶段**
   - 生成问题列表
   - 提供改进建议
   - 创建审查报告
5. **验证阶段**
   - 验证报告完整性
   - 检查建议可行性
   - 确保输出格式正确

## 错误类型

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

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

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

## 错误处理策略

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

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

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

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

## 工具选择

### 选择依据
- 任务需求
- 可用工具
- 工具能力
- 性能考虑

### 选择策略
- 最佳匹配
- 优先级排序
- 负载均衡
- 缓存利用

## 工具调用流程

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

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

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

# 读取文件
content = read_file("src/main.py")

# 分析代码
analysis = analyze_code(content)

# 生成报告
report = generate_report(analysis)

# 检查文件是否存在
if file_exists("src/main.py"):
  content = read_file("src/main.py")
  analysis = analyze_code(content)
else:
  create_file("src/main.py", template)

# 获取所有 Python 文件
files = glob("**/*.py")

# 对每个文件执行分析
for file in files:
  content = read_file(file)
  analysis = analyze_code(content)
  save_analysis(file, analysis)

# 并行读取多个文件
tasks = [
  read_file_async("src/main.py"),
  read_file_async("src/utils.py"),
  read_file_async("src/api.py")
]

# 等待所有任务完成
results = await asyncio.gather(*tasks)

{
  "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
  }
}

代码审查报告

发现的问题：
- 使用参数化查询
- 删除未使用的导入

总结：
- 总问题数：5
- 严重：1
- 高：2
- 中：2

## 代码审查报告

### 结构化数据
```json
{
  "total_issues": 5,
  "critical": 1
}

特点：兼顾机器和人类，灵活性高，适合复杂场景。

### 结果验证

```markdown
## 结果验证

### 验证项
- 结果完整性
- 数据有效性
- 格式正确性
- 逻辑一致性

### 验证方法
- 模式匹配
- 类型检查
- 逻辑验证
- 交叉验证

## 结果修正

### 修正策略
- 自动修正
- 提示用户
- 记录问题
- 重试执行

# 自动修正格式问题
result = format_result(raw_result)

# 提示用户确认
if not confirm_result(result):
  result = retry_execution()

claude --skill code-review --file src/main.py --output report.md

{
  "skill": "code-review",
  "status": "success",
  "result": {}
}

## 输出性能优化
### 优化策略
- 流式输出
- 增量更新
- 压缩输出
- 缓存结果

# 流式输出大结果
for chunk in stream_result(result):
  yield chunk

## 用户体验优化
### 优化策略
- 进度显示
- 实时反馈
- 高亮显示
- 交互式输出

## 性能指标
### 指标类型
- 执行时间
- 内存使用
- CPU 使用
- I/O 操作

### 监控方式
- 实时监控
- 定期采样
- 事件触发
- 阈值告警

## 质量指标

### 指标类型
- 成功率
- 错误率
- 重试次数
- 用户满意度

### 监控方式
- 统计分析
- 趋势跟踪
- 异常检测
- 反馈收集

## 日志级别
### DEBUG
- 每个步骤的详细信息
- 中间结果
- 变量值

### INFO
- 执行开始/结束
- 主要步骤
- 关键决策

### WARNING
- 潜在问题
- 非最佳实践
- 性能警告

### ERROR
- 错误详情
- 堆栈跟踪
- 恢复建议

## 日志格式

### 标准格式
[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 个问题

{
  "timestamp": "2024-01-15T10:30:45Z",
  "level": "INFO",
  "skill": "code-review",
  "message": "开始执行代码审查"
}