Deep Agents 技能系统升级实操：Skill-Bound Tools、Pinned Skills 与线程内热更新

# 升级到带本次改造的版本
pip install -U deepagents
python -c "import deepagents; print(deepagents.__version__)"
# 工具绑定需 0.7.22+；热更新 0.7.16+ 即可

# 准备一个技能库目录
# ./skills/
# ├── call-transcripts/
# │   └── SKILL.md
# ├── meeting-prep/
# │   └── SKILL.md
# └── competitive-intel-card/
#     └── SKILL.md

每个技能就是「目录 + SKILL.md」：YAML frontmatter 写名称与描述，正文写智能体要遵循的操作指令。建一个常规的 deep agent，把技能库挂上，先确认基线行为：启动后系统提示词里只有三个技能的名字与描述，不读正文、不载工具。这就是后面所有改造的对照组。

# skills/call-transcripts/SKILL.md
---
name: call-transcripts
description: 搜索销售通话记录并阅读转写文本，用于复盘与竞品情报整理
metadata:
  include_tools:
    - search_calls
    - get_transcript
---

# 通话转写使用规范

1. 用 search_calls 按客户名与日期范围检索
2. 用 get_transcript 拉取全文，引用时保留时间戳
3. 复盘输出按「异议—回应—结果」三段组织

关键接线变化：这两个工具不放进 Agent 的常规工具列表，而是传给 SkillsMiddleware，由它按技能激活节奏披露。官方博客的表述是把这些工具交给 SkillsMiddleware(tools=[...]) 而不是 Agent 本身；技能还可以用标签（labels）声明工具组，由解析函数映射到具体工具——比如「某台 MCP Server 上的全部工具」或「按用户权限过滤后的子集」，适合一个技能对应一批工具的场景。

# 验证对话一：不提技能，直接让智能体检索通话
# 预期：调用 search_calls 失败 —— 工具不在上下文，报未知工具

# 验证对话二：让智能体「按 call-transcripts 技能复盘上周通话」
# 预期：智能体读 SKILL.md，随后 search_calls 与 get_transcript
#       以一条新系统消息的形式加入对话，调用成功

这个顺序约束是本次改造的核心价值：智能体在能调用工具之前必然已经读过怎么用。另一个容易被忽略的收益在提示缓存上——过去往对话中途加工具，意味着修改请求的工具列表，整段前缀缓存作废，长对话重新计费；在 Anthropic 与 OpenAI 的较新模型上，绑定工具以新系统消息的形式追加在缓存前缀之后，前缀不动、缓存保住。其他模型走旧的追加行为，缓存会失效。

# 用户输入 /meeting-prep 时，应用层识别命令后置顶技能：
result = agent.invoke(
    {"messages": [{"role": "user",
                   "content": "/meeting-prep 准备明天与华东客户的会议"}]},
    pinned_skills=["meeting-prep"],   # 指令在模型调用前就进上下文
)
# 置顶技能绑定的工具也会随之到位

置顶解决的是确定性问题：用户敲了 /meeting-prep，意图毫无歧义，没必要再让模型自己「发现并决定读哪个技能」——应用层直接把技能指令插进下一轮模型调用之前，省掉一轮 read_file 往返，行为从「模型自己挑」变成「应用保证加载」。注意分界：框架本身不解析斜杠命令，检测 /xxx 是你应用层的活，框架只负责置顶动作。

# Python：强制本次调用重扫技能源
result = agent.invoke(
    {"messages": messages},
    skills_metadata=None,
)

# JavaScript 对应写法
# agent.invoke({ messages }, { skillsMetadata: null })

deepagents 会把发现阶段拿到的技能元数据存在 Agent 状态里，后续轮次复用——这本是省掉重复扫描的优化，副作用是长跑线程对增删改无感。置空 skills_metadata 后，下一轮运行会重扫配置的技能源并替换存量目录：同事刚提交的技能、刚改的描述、刚下线的旧版，全部即时生效，不用重开会话。适用场景是值班型长会话、跨天的多轮项目助理这类「会话活得比技能库变更周期长」的场合。

# 团队技能库的三条治理建议
# 1) 技能入库走评审：SKILL.md 是指令，写错会稳定复现错误行为
# 2) 标签解析函数里做权限过滤：
#    用户权限不同，同一个 label 解析出的工具子集不同
# 3) 用正式环境做回归：技能或绑定关系变更后，
#    跑一遍标准任务清单，确认激活与工具调用行为没漂移

官方在博客里给这套机制的场景画得很清楚：技能库涨到几十上百个、跨团队共享、企业当资产管理时，绑定、置顶、热更新才真正发力；个人开发者三五个技能，感知不明显。同时要警惕一个误区——「工具延迟出现」不等于「工具受控」：权限校验、版本管理、测试与可观测性一样不能少，加载时机只是把暴露面收窄了。