skilldisclose

package
v0.45.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package skilldisclose 技能披露:**确定性**挑出该给模型看的那几个技能。

生命周期: Experimental(v0.33.0 定级)——本包仍会改、删、拆,不承诺任何 兼容,升级风险自负;定级理由见 api-lifecycle.yaml,分级规则见 docs/api-compat.md。

与 tooldisclose 的分工

@@tooldisclose@ 解决的是「工具太多,一次给全量 schema 撑爆上下文」,它的检索 键是**工具调用需求**(我要做什么)。技能不一样:技能是**带资源文件的工作流**, 触发信号有三种且强度不同——① 用户/程序**点名**了它;② 描述与当前任务相关; ③ 当前要读的文件落在它声明的资源里。把三者混成一个分数就会让「相关」压过 「点名」,而那正是用户已经明确表达过的意图。

本包只做判定,不做投递

披露的**内容**(正文注入、文件读取、渐进式加载)归宿主。本包给的是: 给定目录与查询,**挑哪几个**、**为什么挑它们**、**有没有被预算裁掉**。

三条可机械判定的判据

  1. **点名优先**:命中名字的分数必须高于任何「相关度」信号,且不受描述长度影响。
  2. **确定性**:同分按名字字典序,结果与目录的遍历顺序、map 顺序无关。
  3. **裁剪显式**:预算裁掉了候选时必须标出来(@@Result.Truncated@)。 静默截断会让宿主以为「就这几个技能相关」,而实际上有更多被挤掉了。

空结果不是静默

没命中时 @@Reason@ 必须写明「为什么是空的」。空结果与「目录里只有一个技能, 正好命中」在调用方看起来一样,而前者是「模型不知道有这个能力」的形态—— 与「技能不存在」不是一回事,宿主据此要不要回退到全量披露。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func MetadataBytes added in v0.42.0

func MetadataBytes(s Skill) int

MetadataBytes 一条技能作为披露元数据实际占用的字节数:Name + Description + 全部 Tags + 全部 Resources(按 UTF-8 字节计)。

为什么不含分隔符/容器开销:这是一个**可对账的口径**——预算是宿主给的, 宿主需要能自己算一遍并与披露结果对上。计费与交付共用这一份实现,不另写一套。

Types

type Budget

type Budget struct {
	// Max 最多披露几个(<=0 表示不限制数量)。
	Max int
	// MaxBytes 元数据字节上限(<=0 表示不限制)。
	//
	// 计量口径是**实际交付的元数据**(MetadataBytes:Name + Description +
	// Tags + Resources),不是只算 name+description:宿主拿到的就是整个 Skill,
	// 计费口径与交付口径必须是同一份(issue #289)。
	MaxBytes int
}

Budget 披露预算。

type Catalog

type Catalog struct {
	// contains filtered or unexported fields
}

Catalog 已登记的技能集合。

副本口径(全覆盖)

Skill.Resources 与 Skill.Tags 是引用类型。构造期从宿主入参深拷贝一次; Disclose 交出 Scored / Skills 前再深拷贝一次(cloneSkill)。调用方拿到的 都是自己的副本——构造后改写宿主原变量、或原地改写披露结果,都改不动目录 (与 tooldisclose 的副本口径同源,issue #377)。

func New

func New(skills []Skill) (*Catalog, error)

New 建目录并做**加载期自检**。

自检项(任一不满足即报错,不静默去重/取第一个):

  • 名字非空且唯一(重名会让「点名」指到两个技能,而判定方无从知道是哪个);
  • 描述非空(没有描述就无法按相关度打分,它只能靠点名命中——那等于假装登记了);
  • 资源项非空串(空串会匹配一切,把一个技能变成万能匹配)。

func (*Catalog) Disclose

func (c *Catalog) Disclose(q Query, b Budget) (Result, error)

Disclose 按查询挑技能。

type Query

type Query struct {
	// Mention 点名(用户/程序明确提到的技能名,可空)。
	Mention string
	// Text 当前任务的自然语言描述(相关度打分用)。
	Text string
	// Resources 当前上下文里涉及的文件路径(资源匹配用)。
	Resources []string
	// Exclude 已披露过的技能(**不重复披露**:重复注入会挤占窗口且没有新信息)。
	Exclude []string
}

Query 一次披露请求。

type Result

type Result struct {
	// Skills 按分数降序(同分按名字)挑出的技能。
	Skills []Skill
	// Scored 全部候选的完整打分(含未入选者,留痕用)。
	Scored []Scored
	// Truncated 是否因预算裁掉了候选。
	Truncated bool
	// Reason 空结果或裁剪的原因(人读;空结果时必须写)。
	Reason string
}

Result 披露结果。

type Scored

type Scored struct {
	Skill Skill
	Score int
}

Scored 一个候选及其分数(留着让宿主能解释「为什么是它」)。

type Skill

type Skill struct {
	// Name 技能名(唯一,模型按它点名)。
	Name string
	// Description 一句话描述(相关度打分用)。
	Description string
	// Resources 该技能能处理的资源路径/后缀(如 "**/*.vue"、"deploy/")。
	Resources []string
	// Tags 自由标签(宿主可用它做粗筛)。
	Tags []string
}

Skill 一个技能的**披露元数据**(不含正文:正文归宿主投递)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL