Lesson 03 — Skills 与上下文工程：能力的渐进式加载

prompt engineering（2023）          context engineering（2026）
─────────────────────────          ─────────────────────────────
"怎么写好一句话 prompt"             "上下文窗口里该放什么"
关注：措辞、格式、few-shot           关注：信息选择、时机、淘汰
假设：所有信息都在 prompt 里          假设：信息分散在各处，按需调回
静态：一次写好不动                   动态：运行时动态组装上下文

              上下文工程母题
        "窗口里该放什么、何时放、怎么淘汰"
                   │
     ┌─────────┬───┴───┬─────────┐
     ▼         ▼       ▼         ▼
   记忆       RAG    Skills     MCP
  (L01-02)  (rag课)  (本课)   (ops课)
     │         │       │         │
  经验的     知识的   能力的    工具的
  按需调回   按需调回 按需调回  远程调用
     │         │       │         │
  recall()  retrieve  load()   call_tool
  注入prompt 注入prompt 注入prompt 执行返回

┌─ 第一层：描述（始终在上下文）──────────────────┐
│  system prompt 里有：                          │
│  可用技能：                                     │
│    - research-brief-format: 研究简报格式规范    │  ← 几十 token
│    - comparison-table: 对比表生成流程           │
│  （10 个 skill 的描述 = 200 token，很便宜）     │
└────────────────────────────────────────────────┘
          │ Agent 判断"我需要 comparison-table"
          ▼
┌─ 第二层：全文（用到才加载）────────────────────┐
│  load_skill("comparison-table") 返回：         │
│  # 对比表生成流程                               │
│  触发条件：当出现"对比""vs"时...                │  ← 几千 token
│  格式：| 维度 | A | B | ...                    │
│  流程：1.识别对象 2.提取维度 3.填充...          │
│  （只有用到的 skill 进上下文，不用的不占窗口）   │
└────────────────────────────────────────────────┘

全塞 system prompt                   渐进式披露
─────────────────                    ────────────
10 个 skill × 1000 token = 10000     描述：10 × 20 = 200 token
窗口占用：高（不管用不用都占）         + 用到的 1-2 个 × 1000 = 2000
噪音：Agent 被不相关 skill 干扰       总计：2200 token（省 78%）
                                     噪音：只有相关的进上下文

class SkillLoader:
    def list_skills() -> list[SkillMeta]           # 扫描，返回元信息
    def format_skill_descriptions() -> str          # 一行描述拼成 prompt 片段
    def load_skill(name) -> str                     # 加载某个 skill 全文
    def match_skills(query) -> list[str]            # 匹配 query 需要哪些 skill
    def load_matched_skills(query) -> str           # 一步到位：匹配+加载

---
name: research-brief-format
description: 研究简报格式规范——规定报告的结构、标题层级和增量标注方式
---

# 技能：研究简报格式规范
## 格式要求
...（完整规范，用到时才加载）

skill_loader = get_skill_loader()  # enable_skills=false 时返回 None
if skill_loader is not None:
    skill_text = skill_loader.load_matched_skills(summary + feedback)
    if skill_text:
        prompt += f"📋 参考技能规范（请遵循其格式要求）：\n{skill_text}"

不开 skills：writer prompt = 摘要 + 基础指令 ≈ 500 token
开 skills 但无匹配：prompt 不变（skill_text 为空）
开 skills 且匹配 1 个：prompt + skill 全文 ≈ 500 + 800 = 1300 token
全塞 system prompt（10 个 skill）：500 + 8000 = 8500 token

→ 渐进式只在用到时加 800 token，全塞永远多 8000 token。

cd portfolio-projects/research-assistant

# 1. 全量测试（25 原有 + 18 记忆 + 13 skills = 56 全绿）
.venv/Scripts/python.exe -m pytest tests/ -q
# 预期：56 passed

# 2. 演示 skills 渐进式加载
cd ../../frontier-lessons/03_skills
PYTHONIOENCODING=utf-8 ../../.venv/Scripts/python.exe code.py
# 预期：扫描 2 个 skill → 只看描述（200 token）→ 匹配后加载全文（800 token）

# 3. 真实开启 skills 跑研究
# 在 .env 设 ENABLE_SKILLS=true
# 跑一个涉及对比的主题，看 writer 输出是否遵循 skill 格式