8.Skills 技能系统:Agent 的“上下文链接器”——如何像管理动态链接库一样管理 Agent 能力

一灰灰blogAgentScope Java进阶架构技能与工程化Skills技能系统AgentScopeJavaSkills技能系统约 5396 字大约 18 分钟

依赖 LLM 生成代码又贵又不稳定?把确定性逻辑预置为脚本,Agent 只需“链接”进去执行。Skills 不是简单的“知识库”,它是 Agent 世界的 动态链接器(Dynamic Linker)。

8.Skills 技能系统:Agent 的“上下文链接器”——如何像管理动态链接库一样管理 Agent 能力

前几篇文章我们把 HarnessAgent 的操作系统模型、Workspace 的大脑外化都聊透了。Agent 有了“操作系统”和“大脑”,能干不少活了。但各位小伙伴在落地时,一定遇到了一个更现实的成本问题:

LLM 生成代码(Tool Calling)非常昂贵且不稳定。 让 Agent 现场写 Python 脚本算个指标,不仅消耗大量 Token(几百到几千 tokens),还可能写出带 Bug 的代码,执行失败后重试又一轮烧钱。

反过来,如果我们把“算指标”这个确定性逻辑预置成一个 Shell/Python 脚本,Agent 只需要“链接”到它并执行,成本瞬间降为 约 50 tokens 的输出回传,且结果 100% 准确。

这就是 Skills 系统的核心命题:如何让 Agent 像程序加载动态链接库(.so / .dll)一样,在运行时按需挂载预置的“确定性能力包”,从而把高频、高成本的 LLM 生成行为,下沉为低成本、零错误的确定性执行?

AgentScope 2.0 的 Skills 机制给出了答案——它本质上是 Agent 世界的 上下文链接器(Context Linker)。

一、从“代码生成”到“能力链接”:解决上下文膨胀的“税”

1. “概率性计算”的隐性成本

在 Tool Calling 模式下,Agent 解决一个“统计 Excel 数据”的任务,链路是这样的:

用户提问 → LLM 推理(写 Python 代码)→ 消耗 ~800 tokens
       → 执行代码 → 报错(缺依赖)
       → LLM 推理(修 Bug)→ 消耗 ~400 tokens
       → 执行成功 → 返回结果
总计:~1200+ tokens + 不可靠的首次成功率

这个链路的问题在于:LLM 在干它不擅长的事——写确定性逻辑。大模型本质是概率预测器,用来生成 pandas.read_excel().sum() 这种确定性代码,简直是“用牛刀杀鸡”,还容易砍歪。

2. Skills:作为“确定性卸载器”

Skills 解决这个痛点的思路极其“计算机科学”——把“概率性生成”卸载为“确定性链接”。

它把能力封装成包含 预置脚本 的目录包,Agent 在运行时只需要做三件事:

  1. 识别场景:判断该加载哪个 Skill(消耗 ~100 tokens 决策)
  2. 执行脚本:直接运行预置的确定性代码(消耗 ~0 tokens 生成,仅 ~50 tokens 回传结果)
  3. 组装输出:用自然语言包装结果返回用户
维度现场写代码(Tool Calling)链接 Skill(确定性脚本)
推理消耗生成代码:~800-1500 tokens仅加载元数据 + 结果包装:~150 tokens
可靠性依赖模型能力,首次成功率 ~70%预置脚本 100% 准确
调试成本高(看模型生成的“黑盒”代码)低(直接查看/修改预置脚本)
上下文占用代码挤占上下文窗口脚本执行结果仅占 ~50 tokens

结论:Skills 通过“空间换确定性”——用预置脚本的存储空间,换取推理时的 Token 和准确率。

3. “单体/微服务/索引”之外的第四种能力加载模式

一般来讲,在深入原理之前,我们不妨把 Skills 放到能力加载方式的演进图谱中看:

  • 模式 A:全量加载(单体上下文) —— 所有 SOP 塞进 SystemPrompt。直白,但 20k+ tokens 起,扩展性为 0。
  • 模式 B:多 Agent 路由(微服务上下文) —— 按领域拆 Agent。局部看仍是全量,且跨领域会话体验割裂。
  • 模式 C:向量检索(索引上下文) —— RAG 动态捞文档。灵活,但流程性知识容易被检索成“断章取义”,准确率 70%~80%。
  • 模式 D:Skills 链接(动态链接上下文) —— 启动只载入“符号表”(能力目录),触发时再“重定位”具体 SOP。

相比于前三种模式在“全量”与“碎片”之间反复横跳,模式 D 像操作系统的动态链接器——编译时只记录符号引用,运行时才解析地址、加载代码段。它精准地卡在了“低 Token 占用”和“流程完整性”的平衡点上,且支持确定性代码的预置执行,这是前三者都做不到的。

二、底层机制:动态链接器的四步加载流程

接下来我们拆开这个链接器,看看它内部到底怎么走。如果把 Skills 比作动态链接器,那它的加载流程就是 “符号表 → 重定位 → 加载 → 执行” 的四步走。

第 1 步:编译时(启动)—— 只生成“符号表”

Agent 启动时,HarnessAgent 扫描所有 SkillRepository(技能仓库),对于找到的每个 Skill,只提取 name 和 description,组装成 System Prompt 中的一份“导出符号表”:

<!-- 相当于 .symtab 符号表 -->
<available_skills>
  <skill name="data-reporter" description="用户需要统计Excel数据、生成报表时触发"/>
  <skill name="code-reviewer" description="用户提交代码请求评审时触发"/>
</available_skills>

重点关注:此时的上下文占用,每个 Skill 仅 ~100 tokens。你注册 100 个 Skill,也就占 10k tokens——远低于一个 RAG 文档块的大小。

第 2 步:运行时(触发)—— 动态“重定位”

用户发来消息:“帮我统计一下这个 Excel 的销售额总和。”

ReActAgent 的推理层看到 data-reporter 的 description 匹配了,便调用系统内置的 load_skill_through_path 工具,相当于动态链接器去 .dynstr 表里找字符串,执行“重定位”:

load_skill_through_path(skillId="data-reporter", path="SKILL.md")

此时,SKILL.md 的完整正文(SOP,约 2k tokens)才被加载进上下文。Agent 第一次看到了“怎么执行”的完整流程。

第 3 步:执行时 —— 按需加载资源文件(代码段/数据段)

在 SOP 的指引下,Agent 可能需要读取规范文档或执行脚本:

// 加载参考文档(相当于加载 .rodata 只读数据段)
load_skill_through_path(skillId="data-reporter", path="references/standard.md")

// 加载/执行脚本(相当于执行代码段)
load_skill_through_path(skillId="data-reporter", path="scripts/analyze.py")

请注意,这里有个关键区别:脚本执行逻辑不在 LLM 上下文里跑,而是在宿主环境(或 Docker 沙箱)中由解释器执行,只把 stdout/stderr 回传给 LLM(约 50 tokens)。

第 4 步:卸载(可选)—— 释放上下文

当本轮推理结束,或 Agent 切换到其他话题时,加载的 Skill 正文和文档资源 可以自动从上下文中释放(取决于 Memory Compaction 策略),只保留核心符号表。这就实现了“用完后释放内存”的链接器效果——Agent 的上下文窗口始终保持轻量化。

正是这四步机制,让 Skills 成为 Agent 的 确定性计算协处理器(Coprocessor):把高能耗的概率计算(LLM 写代码)卸载给低能耗的确定性执行(预置脚本)。

三、SKILL.mdopen in new window:链接器的“导入表”与“重定位脚本”

机制搞清楚了,接下来看文件协议就轻松多了。SKILL.md 本质上是链接器的 “重定位描述文件”。

1. 目录结构:一个完整的“共享库”包

code-reviewer/                   # 库名
├── SKILL.md                     # 链接描述文件(必须)
├── references/                  # 只读数据段(文档/规范)
│   └── style-guide.md
└── scripts/                     # 代码段(可执行模块)
    └── run-checks.sh

2. SKILL.mdopen in new window 的“导出符号”与“重定位指令”

SKILL.md 由 YAML 头信息(导出符号) 和 Markdown 正文(重定位/SOP) 组成:

---
name: code-reviewer                          # 导出符号名
description: 用户需要对 Java/Python 代码做评审、检查规范、发现潜在 Bug 时触发   # 导出符号描述
---

# 重定位指令(SOP)

## 触发条件(入口点)
当用户提交代码片段并请求“评审 / review / 找问题”时触发。

## 执行步骤(重定位过程)
1. 加载 `references/style-guide.md`(加载只读数据段)
2. 执行 `scripts/run-checks.sh`(运行代码段)
3. 整理问题清单输出

## 依赖的资源(外部依赖项)
- references/style-guide.md
- scripts/run-checks.sh

这里头部的 name + description 就相当于 .dynsym 动态符号表,供 Agent 在编译时(启动)查阅;正文则相当于 .text 段的加载指令,告诉 Agent 如何把外部资源(文档/脚本)链接到当前推理任务中。

四、SkillRepository:技能世界的 LD_LIBRARY_PATH

在 Linux 系统中,动态链接器通过 LD_LIBRARY_PATH 或 /etc/ld.so.conf 指定库搜索路径,同名库按路径顺序覆盖。AgentScope 2.0 的 SkillRepository 机制完全遵循了这一设计。

1. 从 1.x 的 SkillsKit 到 2.0 的 SkillRepository

在 1.x 时代,SkillsKit 是硬编码在代码里的“技能包”。你要么继承它,要么手动装配——这相当于把共享库写死在可执行文件里,既不灵活,也不可覆盖。

2.0 的 SkillRepository 把技能来源抽象为“仓库”接口,你可以随时追加新的仓库路径,且后注册的仓库拥有更高的符号解析优先级(类似于 LD_LIBRARY_PATH 中的顺序)。

2. 四大“库搜索路径”实现

(a) 本地工作区——自动注入的默认路径

只要配置了 HarnessAgent.builder().workspace(path),workspace/skills/<id>/SKILL.md 就会被自动扫描并纳入符号表。这是零代码的“默认系统库路径”。

(b) Git 远程仓库——共享库中央仓库

使用姿势如下:

// 指向团队 Git 仓库,自动轻量级克隆
.skillRepository(new GitSkillRepository("https://github.com/team/skills-repo.git"))

(c) Nacos/Config Center——动态配置的库路径

适合平台动态下发的场景,相当于企业级的分布式“符号表服务器”。

(d) MySQL / Classpath——结构化存储与内嵌库

MysqlSkillRepository 支持 writeable(true),Agent 甚至可以把自学习的成果回写进数据库,实现“社区共建”。

3. 同名覆盖与优先级:严格的“搜索路径”规则

当多个仓库存在同名 Skill 时,覆盖优先级从低到高如下:

优先级搜索路径说明
1(最低)全局用户目录 ~/.agentscope/skills相当于系统级 /usr/lib
2远程仓库(Git/Nacos/MySQL)后注册的优先
3工作区公共 workspace/skills相当于项目级 /lib
4(最高)用户私有 {userId}/skills相当于用户级 ~/lib,仅当前用户可见

本质解读:这完全就是动态链接器的 搜索路径覆盖规则。高优先级的同名 Skill 会“遮蔽”低优先级的实现,允许用户或项目在不修改中央仓库的情况下,覆盖特定能力的实现。

五、确定性能力卸载:Tool 的绑定与脚本执行

1. Tool 的动态可见性(符号表的导出控制)

作为一个有追求、有理想新四好码农,这种“工具按需暴露”的骚操作,怎么能忍!Skills 里有个很妙的设计——Tool 的可见性跟随 Skill 的加载状态。

在 Skill 未激活时,它绑定的 Tool 不出现在 Agent 的工具列表中(相当于未导出的局部符号)。Skill 被加载后,绑定的 Tool 才动态注册到模型可用的工具集里(相当于导出全局符号)。

skillBox.registration()
        .skill(reportSkill)
        .tool(new ExcelExportTool())  // 未激活时不可见
        .apply();

这相当于控制了 符号的导出时机——不把不用的 API 暴露给 LLM,既节省了描述工具 Schema 的 Token,又防止了模型在无关场景下错误调用工具。

2. 脚本执行:绕开 LLM 的“确定性协处理器”

当 Skill 执行 scripts/ 目录下的脚本时,AgentScope 会把脚本内容导出到工作目录,由 Shell/Python 解释器直接执行,执行过程完全不经过 LLM:

// 配置脚本执行环境(相当于配置协处理器)
ShellCommandTool shell = new ShellCommandTool(
        workDir,
        Set.of("python3", "node"),  // 允许的解释器白名单
        command -> approvalCallback  // 审批钩子
);

skillBox.codeExecution()
        .workDir("/sandbox/work")
        .includeFolders("scripts/")
        .withShell(shell)
        .enable();

为什么这是“降维打击”?

  • 传统 Agent 执行计算任务:LLM 生成代码(概率性,高 Token)→ 执行 → 可能出错 → 再生成。
  • Skills 执行计算任务:直接运行预置脚本(确定性,0 Token 生成)→ 返回结果(~50 Token)。

这相当于给 Agent 接上了一个“数学协处理器”——既然 CPU(LLM)算浮点又慢又费电,我们就外挂一个 FPU(确定性脚本执行器)。作为一个紧跟时代潮流的小伙,这种外挂协处理器的玩法,我是真觉得香 😊

六、实战:构建一个“无情盘问”链接器

理论吹得天花乱坠,不如实操来得直接。接下来进入正题,我们动手撸一个 “grilling” Skill,它不提供文档,也不执行数据分析,而是提供一套 “盘问 SOP” 。

这个 Skill 的场景是:当用户表达某个冲动计划时,Agent 像产品经理一样进行“无情盘问”,挖掘需求漏洞。它完美体现了“能力链接”的价值——把“如何盘问”的策略固化成了预置指令,而不是每次让 LLM 即兴发挥(后者很容易变成无原则的附和)。

1. Skill 定义

在 workspace/skills/grilling/SKILL.md 放置以下内容:

---
name: grilling
description: 用户表达某个计划、决定或想法,并希望被检验、盘问、质疑或压力测试时触发
---

# 无情盘问协议

## 触发条件
用户说出“我想...”“我打算...”“我决定...”等句式。

## 盘问准则
1. **只提问题,不给建议,不提供解决方案**
2. 关注三个维度:**Why**(为什么做)、**How**(怎么做)、**Risks**(风险在哪)
3. 连续追问,直到用户承认“我还没想清楚”

## 禁止行为
- ❌ 不要鼓励用户
- ❌ 不要提供替代方案
- ❌ 不要说“挺好的”

2. 接入代码(零配置注册)

使用姿势如下(零配置,把技能丢进 workspace/skills/ 即可,连一行注册代码都不用写):

因为 Skill 放在 workspace/skills/ 下,Agent 会自动扫描并加载它的元数据(name + description):

// 构建 Agent,指向包含 grilling 的工作区
HarnessAgent agent = HarnessAgent.builder()
    .name("assistant")
    .sysPrompt("""
            你是一个有用的 AI 助手,名叫一灰灰。

            工作区中已经为你预置了技能(Skill),其中包含一个名为 grilling 的"无情盘问"技能。
            当用户表达某个计划、决定或想法,并希望被检验、盘问、拷问、质疑、挑战或压力测试时,
            你必须先通过 load_skill_through_path 工具加载 grilling 技能的完整内容,
            然后严格按照该技能定义的准则进行无情追问,不要自行发挥、不要给建议、只提问。
            """)
    .model(
            OpenAIChatModel.builder()
                    .apiKey(EnvUtil.getSiliconApiKey())
                    .baseUrl("https://api.siliconflow.cn")
                    .endpointPath("/v1/chat/completions")
                    .modelName("Qwen/Qwen3-8B")
                    .stream(true)
                    .formatter(new OpenAIChatFormatter())
                    .build()
    )
    .workspace(Paths.get(".agentscope/workspace"))
    .build();
// 维持会话上下文
RuntimeContext ctx = RuntimeContext.builder()
        .sessionId("grilling-session")
        .userId("yihuihui")
        .build();

3. 流式事件监听:见证“动态链接”的瞬间

通过 streamEvents 监听,我们能看到 Agent 在后台精确地执行了“链接器”的四步流程:

agent.streamEvents(new UserMessage(input), ctx)
        .doOnNext(event -> {
            switch (event.getType()) {
                case TOOL_CALL_START -> {
                    // 🔧 [调用工具] load_skill_through_path
                    // 这就是"重定位"发生的证据!
                    System.out.println("🔧 链接技能: " + 
                        ((ToolCallStartEvent) event).getToolCallName());
                }
                case THINKING_BLOCK_DELTA -> {
                    // 灰色显示思维链
                    System.out.print("\u001B[90m" + delta + "\u001B[0m");
                }
                case TEXT_BLOCK_DELTA -> {
                    // 盘问正文
                    System.out.print(delta);
                }
            }
        }).blockLast();

交互效果示例:

image.png
image.png
image.png
image.png

这个过程 Agent 没有自己编造“如何盘问”,而是严格遵循了我们预置在 SKILL.md 中的“盘问准则”, 一股脑提了一堆的灵魂拷问,堪称人间清醒了。

这就是 “确定性卸载” 的直观体现——把策略固化到文件,让 Agent 去加载和执行,而不是让它猜。

七、最佳实践与避坑指南(基于链接器视角)

1. Description 即“导出符号名”,必须精准

Agent 启动时只看 description 做匹配,这相当于动态链接器通过符号名找库。如果符号名模糊,链接就会失败。

  • 坏符号:数据分析(太宽泛,无法精准匹配)
  • 好符号:用户需要计算 Excel 文件的销售额、毛利、同比环比等统计指标时触发(场景化,命中率高)

2. 路径即“相对偏移”,禁用绝对地址

在 SKILL.md 和代码中引用资源,强制使用相对路径。这相当于链接器中的 PIC(位置无关代码)——只有相对偏移,才能在容器、远端存储、本地磁盘等不同基址下正确寻址。

  • ✅ 正确:scripts/run.sh、references/style.md
  • ❌ 错误:/home/user/project/scripts/run.sh(进入沙箱直接寻址失败)

3. 分层治理即“库搜索路径规划”

  • 通用基础能力(如 Excel 解析)→ 放入 Git 仓库或 Nacos,作为“系统库”。
  • 项目特有规则(如本项目 RPC 校验)→ 放入 workspace/skills/,随代码发版,作为“项目库”。
  • 个人临时覆盖(如针对特定客户的特殊逻辑)→ 放入 {userId}/skills/,作为“用户库”,优先级最高。

4. 自学习闭环:从“草稿符号”到“正式导出”

如果开启 Agent 的 enableSkillManageTool(true),Agent 可以自行起草 SKILL.md。但千万不要让它直接写入系统库。

正确的上线策略是:

  1. Agent 生成草稿 → 写入 {userId}/skills/(用户私有)。
  2. 人工介入 Review(Code Review)→ 确认逻辑准确、无安全漏洞。
  3. 人工将确认后的 Skill 从用户目录 提升(Promote) 到 Git/Nacos 中央仓库或工作区公共目录。

这相当于 “共享库的提交通道”,必须经过人工审核,防止模型生成的“脏符号”污染全局命名空间。

八、小结

  • Skills 的本质:Agent 世界的 动态链接器。通过“编译时符号表 + 运行时重定位 + 确定性协处理器”的设计,把高频的 LLM 代码生成(概率性、高成本)卸载为预置脚本执行(确定性、低成本)。
  • 核心机制:启动只加载 元数据(~100 tokens/Skill),触发时加载 SOP(~2k tokens),执行脚本 不占上下文(仅回传 ~50 tokens)。
  • 存储抽象:SkillRepository 对标 LD_LIBRARY_PATH,支持 Git / Nacos / MySQL / Classpath / 本地工作区五种来源,同名技能按搜索路径优先级覆盖。
  • Tool 可见性:未激活 Skill 绑定的 Tool 对 LLM 不可见,动态控制 API 暴露范围,避免 Schema 占用 Token。
  • 最佳实践:description 要精准(好符号)、路径要相对(PIC)、通用入库(系统库)、项目进工作区(项目库)、个人放私库(用户库),自学习产出必须经人工审核才能提升为正式技能。

如果说 Workspace 是给 Agent 装上了“文件系统大脑”,那 Skills 就是给这个大脑接上了“确定性计算协处理器”。它让我们从“让 LLM 写每一行代码”的幻觉中醒来,回归到软件工程的本质——把确定性逻辑固化下来,让概率模型只做它最擅长的事:意图识别与自然语言交互。

九、其他

0. 项目

1. 下篇预告

第一阶段:新手村 —— 核心概念与快速起步

第二阶段:进阶架构 —— 掌握 2.0 的核心亮点 HarnessAgent,理解"文件即配置"的工程化理念。


尽信书则不如,以上内容,纯属一家之言,因个人能力有限,难免有疏漏和错误之处,如发现 bug 或者有更好的建议,欢迎批评指正,不吝感激。

看到这里的小伙伴,不妨点个赞,顺手关注下微信公众号「一灰灰Blog」。下一篇文章,我们将深入 多 Agent 编排与技能隔离——当一个“项目经理”Agent 调度多个“执行”Agent 时,各自工作区里的 Skills 如何划清边界?谁该看到谁的“符号表”?这个坑,咱们下一篇接着撕 😏

微信公众号: 一灰灰Blog

Loading...