首页 / 第5部分：技能 Skills / 第15章：Skills的工作原理

15.2 渐进式披露机制详解

渐进式披露的核心概念

渐进式披露（Progressive Disclosure）是 Skills 架构的核心设计原则，它通过分层加载信息来优化 AI 模型的上下文使用效率。

三层披露架构详解

第一层：元数据层（Metadata Layer）

内容组成

元数据层仅包含最基本的标识信息：

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files, forms, or document extraction.
---

技术细节

  • 大小限制：name ≤ 64字符，description ≤ 1024字符
  • 加载时机：AI 代理启动时
  • 存储位置：系统提示词中
  • 更新频率：代理重启时

设计目的

  1. 快速筛选：基于描述判断 Skill 相关性
  2. 上下文节约：最小化初始上下文占用
  3. 性能优化：减少启动时间

第二层：指令层（Instructions Layer）

内容组成

指令层包含完整的 SKILL.md 文件：

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
---

# PDF Processing

## When to use this skill

Use this skill when working with PDF documents, including:
- Text extraction from PDF files
- Form filling and data extraction
- Document merging and splitting
- Table and structure recognition

## How to extract text

1. Use pdfplumber library for text extraction
2. Handle different PDF layouts and encodings
3. Extract text with position information
4. Clean and format extracted text

## Form filling instructions

...

技术细节

  • 大小建议：< 5000 tokens
  • 加载时机：任务匹配时
  • 格式要求：标准 Markdown
  • 内容要求：包含使用条件和详细步骤

设计目的

  1. 完整指导：提供执行任务的详细说明
  2. 灵活表达：支持自然语言描述
  3. 标准化格式：便于解析和处理

第三层：资源层（Resources Layer）

内容组成

资源层包含所有支持文件：

pdf-processing/
├── SKILL.md              # 指令文件
├── scripts/
│   ├── extract_text.py   # 文本提取脚本
│   └── fill_form.py      # 表单填写脚本
├── references/
│   ├── api_guide.md      # API 使用指南
│   └── examples.md       # 使用示例
└── assets/
    ├── templates/        # 模板文件
    └── sample_data/      # 示例数据

技术细节

  • 加载时机：指令中明确引用时
  • 文件类型：脚本、文档、模板、数据等
  • 访问方式：相对路径引用
  • 大小限制：无固定限制，按需加载

设计目的

  1. 功能扩展：提供实际可执行的代码
  2. 知识补充：支持详细的参考资料
  3. 资源复用：模板和示例数据的复用

披露机制的工作流程

1. 初始发现

启动时 → 扫描 Skills 目录 → 解析元数据 → 建立索引

2. 相关性评估

用户请求 → 匹配描述 → 计算相关度 → 选择候选 Skills

3. 指令加载

选择 Skill → 读取 SKILL.md → 解析内容 → 注入上下文

4. 资源按需加载

执行指令 → 遇到引用 → 读取资源文件 → 执行操作

5. 结果整合

收集输出 → 整理结果 → 呈现给用户

上下文管理策略

智能缓存机制

元数据缓存

  • 在代理会话期间保持元数据
  • 支持动态更新
  • 处理新增和删除的 Skills

指令缓存

  • 缓存最近使用的 SKILL.md
  • LRU（最近最少使用）策略
  • 基于内容哈希的版本控制

资源缓存

  • 缓存常用资源文件
  • 基于访问频率的预加载
  • 自动清理过期缓存

上下文窗口优化

内容压缩

  • 使用结构化格式（YAML + Markdown）
  • 避免冗余描述
  • 引用而非内联大块内容

选择性加载

  • 只加载相关的 Skills
  • 支持多 Skill 并行加载
  • 动态调整加载优先级

增量更新

  • 支持部分内容更新
  • 最小化重新加载
  • 保持上下文连续性

披露机制的性能优势

量化分析

披露层级 平均大小 加载频率 上下文占用
元数据层 ~100 tokens 每次启动 < 1%
指令层 ~2000 tokens 任务相关 ~10-20%
资源层 按需加载 引用时 ~5-15%

实际效益

  1. 启动性能：初始加载时间减少 80%
  2. 任务响应：相关任务响应时间减少 60%
  3. 扩展能力：支持的 Skills 数量增加 10x
  4. 资源效率：上下文使用效率提高 3x

披露机制的局限性与解决方案

潜在问题

1. 过度分层导致的复杂性

问题：多层加载可能增加理解难度 解决方案：清晰的文档结构和导航

2. 缓存一致性问题

问题：文件更新后缓存可能过时 解决方案：基于文件修改时间的缓存验证

3. 资源依赖管理

问题：复杂依赖关系难以管理 解决方案：声明式依赖管理和验证

最佳实践

内容组织

  • 保持元数据简洁准确
  • 指令层次清晰易懂
  • 资源文件结构合理

性能优化

  • 合理控制文件大小
  • 使用高效的缓存策略
  • 监控和调整加载策略

维护管理

  • 定期验证缓存一致性
  • 监控性能指标
  • 根据使用情况调整结构

总结

渐进式披露机制通过精心设计的多层架构，实现了 Skills 在功能丰富性和性能效率之间的完美平衡。这种机制不仅优化了 AI 模型的上下文使用，还为 Skills 的扩展和维护提供了坚实的技术基础。