既然要做 HagiCode Skill 系统,咱们先把话说明白:这套东西解决的不是"能不能接模型"的问题,而是"接到什么程度、往里加新能力要多费劲"的问题。我见过太多团队把 AI Agent 做成了铁板一块,加一个工具函数就要改核心代码,改完还要重新走一遍发布流程,真要命。HagiCode Skill 这套设计思路,核心就是模仿插件生态——让每一个技能像 App 一样独立存在、按需安装、动态生效,主程序只负责调度和兜底。下面我把整套系统的设计思路、核心实现、扩展机制和踩坑记录一次性铺开讲清楚,希望能给正在做同类平台的你省掉几个月的弯路。
1. 整体架构设计:先拆层,再谈扩展
1.1 为什么需要一个独立的技能管理层
先想一个问题:大模型本身会"干活"吗?不会。它只能根据上下文生成文本。所谓 AI 技能,本质上是把我们封装好的函数或工具,通过模型的能力识别用户的意图,然后触发对应函数执行,再把结果反馈给模型组织成最终回答。这套机制当前行业里普遍叫 function calling 或 tool use,但落到工程落地时,大部分团队的实现方式都很粗暴:
- 在代码里硬编码一个 tools 数组;
- 每次新增技能都改代码、加分支;
- 技能之间的依赖、版本、参数校验全靠口头约定。
一开始技能少,这么干没问题。一旦技能上了两位数,维护成本直接起飞。我带的项目就遇到过:想下线一个废弃技能,结果还有十几个 prompt 模板在引用它的名字,改了三天都没改干净。所以,独立的技能管理层不是炫技,而是规模化的必然结果。它的职责很纯粹:定义技能的统一描述格式、管理技能的注册与发现、隔离技能的运行环境、监控技能的调用状态。
一句话总结:没有这个管理层,你构建的不是平台,而是一个不断膨胀的补丁堆。
1.2 分层设计:四层结构让职责边界清晰
HagiCode 这套系统的整体架构我把它分成四层,每一层之间的接口都收得很窄,保证可以独立演进:
| 层级 | 核心职责 | 关键组件 |
|---|---|---|
| 接入层 | 接收用户输入、处理会话状态 | Chat Adapter、Session Manager |
| 编排层 | 理解意图、决策调用哪个技能、管理调用链 | Agent Core、Planner、Context Builder |
| 技能层 | 技能的注册、加载、执行、生命周期管理 | Skill Registry、Loader、Executor |
| 基础设施层 | 存储、日志、监控、配置管理 | Redis、PostgreSQL、Prometheus |
这里面最容易被忽视的是接入层和编排层之间的解耦。很多团队把 prompt 拼装和技能调用逻辑写在同一个函数里,Session 上下文直接被技能实现给污染了。我的建议是:接入层只负责把用户消息转成统一的 AgentMessage 结构,编排层只负责产出决策,技能层只管执行具体函数,三者之间用标准的数据结构传递信息,谁都不准越界调用。这样后续无论是换模型、换 UI,还是加技能,都不至于牵一发动全身。
技能层本身还要再拆成三个子模块:Registry 负责维护"技能元信息中心",Loader 负责把技能代码从文件系统或远程仓库加载进运行时,Executor 负责真正执行技能并返回结构化结果。这种拆分的好处是:Registry 只跟元数据打交道,不关心具体实现;Loader 只负责把"代码"变成"可执行对象",不关心技能做什么;Executor 只管跑,不关心技能怎么被找到的。任何一个环节出了问题,排查范围都特别小。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Skill 定义规范与协议设计:一切扩展性的地基
2.1 技能描述文件:从 manifest 到参数 schema
扩展性的核心不在代码,在协议。HagiCode 里的每个技能都自带一份 manifest 文件,这个文件是技能的唯一"身份证",所有注册、发现、鉴权都围绕它展开。我采用 YAML 格式,原因很简单:相比 JSON,YAML 支持注释,写起来也更容易维护。一个标准 manifest 长这样:
yaml复制name: weather_query
description: 查询指定城市的实时天气信息,包含温度、湿度、风力等
version: 1.2.0
author: hagicode-team
tags:
- weather
- location
parameters:
type: object
properties:
city:
type: string
description: 城市名称,如"北京"、"上海"
required: true
unit:
type: string
enum: ["celsius", "fahrenheit"]
default: "celsius"
description: "温度单位,默认摄氏度"
required:
- city
entrypoint:
module: skill_weather
function: run
handler: webhook
permissions:
network: true
filesystem: false
timeout: 30
这里有几个字段值得重点说说。
parameters 这块是重头戏。它不是给人看的,是给模型看的。大模型要靠这段 JSON Schema 来理解"这个技能需要什么参数、参数各自是什么含义",所以 description 必须写得足够具体,要站在模型的视角,而不是开发者的视角。比如 city 的 description 写成"城市名称,如北京、上海"就比"城市"两个字效果好得多,模型能通过示例推断出正确格式。
entrypoint 定义了技能的执行入口。module 和 function 指向一个可导入的 Python 函数,handler 字段则标记了技能的执行方式——是本地函数调用,还是请求外部 webhook。这个设计天然支持了"本地技能"和"远程技能"两种形态,远程技能甚至不需要在本地安装任何依赖,只要你实现了 webhook 协议,就可以挂载进来。
permissions 部分我非常强调。AI 技能往往需要执行一些敏感操作,比如读文件、访问网络、写数据库。给技能显式声明权限边界,一方面可以在注册时做合法性检查,另一方面在运行时可以做细粒度的拦截。这比在技能代码里自己写"我能不能联网"靠谱得多。
最后,所有人最容易忽略的字段是 timeout。我见过太多技能没有设置超时时间,结果模型调用了一个第三方 API,对方响应卡了 5 分钟,整个 Agent 卡死,用户等得直接关掉页面。每个技能都必须显式声
