Documentation
¶
Overview ¶
Package skill 定义 Agent 技能（skill）调用框架的基础设施。
技能是比工具（tool）更高一层的可复用能力单元：一个技能既包含"元信息" （Definition：名称 / 描述 / 入参 schema，用于暴露给模型做 function calling）， 也包含"指令正文"（Instructions：注入到上下文中的 markdown 说明），以及 可选的"执行体"（Invoke：真正运行技能逻辑，产出结果）。
与 tool 包一样，本包只回答三个问题：
- 有哪些技能（Definition / Instructions 描述给模型）；
- 如何组织它们（Registry 按名注册 / 解析）；
- 如何调用它们（Invoker 解析技能 → 校验参数 → 套用中间件 → 执行）。
上层 internal/agent 通过 SkillRunner 把技能执行桥接到 Runtime（事件流 + 权限门禁）， 因此本包不依赖 agent，避免循环引用。
Index ¶
- Variables
- func BooleanProperty(description string) map[string]any
- func IntegerProperty(description string) map[string]any
- func NumberProperty(description string) map[string]any
- func Schema(description string, properties map[string]any, required ...string) map[string]any
- func StringProperty(description string) map[string]any
- type Call
- type Definition
- type Func
- type Invoker
- type InvokerOption
- type Loader
- type Manifest
- type Middleware
- type Next
- type Registry
- type Result
- type Skill
- type Static
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotFound 表示技能未注册。 ErrNotFound = errors.New("skill: skill not found") // ErrInvalidArguments 表示技能参数非法（无法解析为输入结构或不是合法 JSON）。 ErrInvalidArguments = errors.New("skill: invalid arguments") )
技能相关错误。
Functions ¶
func BooleanProperty ¶
BooleanProperty 构造一个 boolean 类型属性。
func IntegerProperty ¶
IntegerProperty 构造一个 integer 类型属性。
func NumberProperty ¶
NumberProperty 构造一个 number 类型属性。
func StringProperty ¶
StringProperty 构造一个 string 类型属性。
Types ¶
type Call ¶
type Call struct {
ID string `json:"id,omitempty"` // 调用唯一 ID（模型生成）
Name string `json:"name"` // 技能名
Arguments json.RawMessage `json:"arguments,omitempty"` // 参数（JSON）
}
Call 是一次待执行的技能调用。
type Definition ¶
type Definition struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
InputSchema map[string]any `json:"input_schema,omitempty"`
}
Definition 描述一个技能，用于暴露给模型（function calling 的技能定义）。
与工具不同，技能的 InputSchema 可为 nil：纯指令型技能无需参数， 模型只需在上下文里看到 Instructions 并按需"启用"它。
type Func ¶
type Func[In, Out any] struct { // contains filtered or unexported fields }
Func 把普通函数适配为 Skill：In 为入参结构，Out 为返回结构。
Instructions 可用于附带指令正文；对纯函数型技能可留空。
func NewFunc ¶
func NewFunc[In, Out any](manifest Manifest, fn func(context.Context, In) (Out, error)) *Func[In, Out]
NewFunc 基于一个强类型函数构建技能。
- manifest：技能的元信息（名称 / 描述 / 入参 schema / 指令正文）；
- fn：实际执行逻辑。
func (*Func[In, Out]) Definition ¶
func (f *Func[In, Out]) Definition() Definition
Definition 实现 Skill。
func (*Func[In, Out]) Instructions ¶
Instructions 实现 Skill。
type Invoker ¶
type Invoker struct {
// contains filtered or unexported fields
}
Invoker 执行技能调用：解析技能 → 校验参数 → 套用中间件 → 执行。
语义约定：所有失败（技能不存在 / 参数非法 / 超时 / panic / 技能返回错误）都 收敛为 Result.IsError=true，而不会向上抛出中断整个流程——模型据此纠正行为。
func NewInvoker ¶
func NewInvoker(registry *Registry, opts ...InvokerOption) *Invoker
NewInvoker 创建执行器；默认在最内层附带 Recover 中间件（panic 不逃逸）。
type InvokerOption ¶
type InvokerOption func(*Invoker)
InvokerOption 配置 Invoker。
func WithMiddlewares ¶
func WithMiddlewares(ms ...Middleware) InvokerOption
WithMiddlewares 追加中间件（先加入的越靠内层）。
type Loader ¶
type Loader struct{}
Loader 从文件系统加载技能（SKILL.md）。
布局约定：
- 一个技能目录 = 一个技能；目录内 SKILL.md 描述该技能；
- 也支持直接加载单个 SKILL.md 文件。
SKILL.md 采用 frontmatter + 正文：
--- name: my-skill description: 技能描述 version: 1.0.0 --- # 指令正文 ...
frontmatter 只解析 name / description / version 三个字段，其余内容作为 指令正文（Instructions）原样保留。
type Manifest ¶
type Manifest struct {
Definition
Version string `json:"version,omitempty"`
Instructions string `json:"instructions,omitempty"` // markdown 指令正文，注入到上下文
}
Manifest 是一个技能的完整元信息（Definition + 指令正文 + 版本）。
func ParseManifest ¶
ParseManifest 解析 SKILL.md 内容（frontmatter + 正文）为 Manifest。
type Middleware ¶
Middleware 包裹技能执行：在真正调用技能前后做校验 / 超时 / 恢复 / 日志等。
中间件在 Invoker 中按注册顺序包裹（先注册的越靠内层）。约定：中间件应调用 next 继续执行，并在需要时改造 ctx / call / 返回值。
func Logging ¶
func Logging(logf func(format string, args ...any)) Middleware
Logging 在技能执行前后记录日志；logf 为 nil 时使用标准库 log。
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry 注册并解析技能。
技能按名称唯一；List 返回全部技能的 Definition，供 Provider 暴露给模型 （即 function calling 里的 skills 参数）。
func NewRegistryWith ¶
NewRegistryWith 创建注册表并注册给定技能。
func (*Registry) Instructions ¶
Instructions 返回全部技能的指令正文（按名称升序），用于把技能说明批量注入到 系统提示词 / 上下文，让模型在没有 function calling 的 Provider 上也能感知技能。
type Result ¶
type Result struct {
Content string `json:"content"` // 回传给模型的文本
Data any `json:"data,omitempty"` // 结构化结果（供上层业务使用）
IsError bool `json:"is_error"` // 是否为失败结果
Err error `json:"-"` // 底层错误（仅供日志 / 观测，不回传模型）
}
Result 是一次技能调用的结果。
无论成功还是失败，Content 都会回传给模型（因此始终是可读文本）； IsError 标识这次调用是否失败，模型可据此纠正后续行为。
type Skill ¶
type Skill interface {
// Definition 返回技能的元信息（名称 / 描述 / 入参 schema）。
Definition() Definition
// Instructions 返回注入到模型上下文的 markdown 指令正文；可为空。
Instructions() string
// Invoke 执行技能；args 是模型生成的参数（JSON，空时视为 {}）。
Invoke(ctx context.Context, args json.RawMessage) (Result, error)
}
Skill 是可被 Agent 启用并调用的一个技能。
实现约定：
- Invoke 返回的 error 会被上层包装为"技能执行失败"的结果（Result.IsError=true）， 而不会中断整个调用流程——模型可以看到错误信息并尝试纠正。
- 返回的 any 会被序列化为结果内容（Result.Content）回传给模型。
- 纯指令型技能可以只提供 Instructions，Invoke 直接返回指令正文即可。
Source Files
Directories