Documentation
¶
Overview ¶
Package tooldisclose 渐进式工具披露 + 执行门禁。
生命周期: Stable(v0.33.0 定级)——只允许 additive 变更(新增导出符号 / 新增方法且给零值默认实现 / 新增错误值);改签名、改语义、改默认值、 删导出符号都算 breaking,判定规则与变更流程见 docs/api-compat.md, 逐包理由见 api-lifecycle.yaml。
为什么需要这个包 ¶
工具少的时候「把全部定义塞进上下文」最省事;工具一多,它就是**头号上下文占用源**—— tool_definitions 是每轮都要重发的固定成本。挂几十个工具,光声明就能把窗口吃满, 真正要推理的内容反而放不下。
但「按需给 schema」有个前提:模型得先知道**有哪些工具**,才会想到去要。故两段式披露:
- 首轮只给「名字 + 描述」的**退化占位**,成本极低但可枚举;
- 模型用关键词**检索**换完整 schema,没检索过的继续是占位。
为什么执行门禁必须与检索同包 ¶
渐进披露制造了一个此前不存在的失败模式:**模型凭占位猜出一个调用就发过来**。 此时只有两种可能,处置方式相反:
- 工具在目录里、只是 schema 没取回 → 可恢复:先取回 schema 再构造参数调用;
- 工具压根不在目录里 → 不可恢复,再重试多少次也不会出现。
把两者混成一句「工具不可用」,后果很具体:上层的自动退避重试会把**策略否定**变成 无穷重试。故本包把两种结局做成两个哨兵并各自标注重试性,调用方按 errors.Is 分支。
确定性纪律 ¶
目录构造、检索排序、已加载集合并全部无随机、无时钟、无 map 序依赖:同一输入必得同一 输出,编排才可复现、回归才可比对。
内存边界 ¶
目录是本包唯一随工具数量线性增长的内存,故「单个工具最多占多少」必须是可核对的事实:
- 描述在构造时截到 MaxDescriptionLen(按 rune);
- 参数描述在构造时截到 MaxParamDescriptionLen(按 rune);
- schema 的内容字节(Type + 参数名/类型/描述 + Required)总量超 MaxSchemaBytes 时, 按确定顺序丢弃参数项并同步过滤 Required,置 Schema.Truncated=true。
故单条目录记录的持有量上界 = len(Name) + MaxDescriptionLen + MaxSchemaBytes (按内容字节计,不含 map/slice 容器开销)。**工具名不截断**——它是调用身份, 截断会让「在目录内」与宿主实际能调的名字不一致;其长度归宿主自查(调用身份不应是 无界自由文本,但本包不能替宿主改名)。
检索用的小写形态另存一份,但它只在描述**真含大写**时才单独占内存(strings.ToLower 在无字符改变时原样返回入参),故上界还要加上「每条至多一份 MaxDescriptionLen 的小写描述」。
占位披露面的描述(原文 + 取回指令)也受 MaxDescriptionLen 约束:追加指令不得让 模型实际收到的描述超过声明的单条上限(见 placeholder.go)。
反过来,**跨轮复用的缓存不归本包管**:本包没有隐式的请求作用域(参考实现靠 Python 的 contextvar 天然拿到 thread 级缓存,Go 没有等价物),凭空造一个就是替宿主决定生命周期。 宿主若要跨轮持有目录,请自己按会话键持有、会话结束时释放。
边界 ¶
本包只管「披露面」与「能不能调」:不执行工具、不认识任何具体工具、不解释参数语义。 参数校验、返回值语义、权限判定全归宿主。纯 stdlib,零外部依赖。
Index ¶
- Constants
- Variables
- func Guidance(err error) string
- func MergeLoaded(sets ...[]string) []string
- func PlaceholderDescription(description string) string
- func Retryable(err error) bool
- func SignatureOf(t Tool) (string, error)
- func Stage(cat *Catalog) invoke.Stage
- type Catalog
- func (c *Catalog) Expose(name string) (Exposure, bool)
- func (c *Catalog) ExposeAll() []Exposure
- func (c *Catalog) Has(name string) bool
- func (c *Catalog) IsLoaded(name string) bool
- func (c *Catalog) Len() int
- func (c *Catalog) Load(name string) (Tool, bool)
- func (c *Catalog) Loaded() []string
- func (c *Catalog) Lookup(name string) (Tool, bool)
- func (c *Catalog) Names() []string
- func (c *Catalog) Search(query string) []Match
- func (c *Catalog) SearchWithMeta(query string) SearchResult
- type Exposure
- type Gate
- type GateError
- type Match
- type Param
- type Schema
- type SearchResult
- type Tool
Constants ¶
const ( // MaxParamDescriptionLen 单个参数描述的字符上限(按 rune 计)。 // // 参数描述与工具描述一样是宿主自由文本;不设界时「单个工具占多少」没有上界 // (50 个参数 × 5000 字 ≈ 750 KB 全量留在目录里,issue #290)。截断只削文档, // 不改参数名/类型与 Required 语义。 MaxParamDescriptionLen = 320 // MaxSchemaBytes 单个工具 schema 的内容字节上限(Type + 参数名/类型/描述 + Required)。 // // 超过时按确定顺序丢弃参数项(先丢最大的、同大小按名字升序)并同步过滤 Required, // 置 Schema.Truncated=true。上界按**内容字节**计,不含 map/slice 容器开销。 MaxSchemaBytes = 64 << 10 )
const ( // DefaultSearchLimit 检索默认上限。取 3 的理由:一次检索的价值是**把候选缩到模型读得完 // 的一小屏**,三条已足够表达「你要的是这类工具里的哪几个」;再多只是把首轮省下的 // 声明费原样花回去。模型检索不准时可以再查一次——窄面 + 可重复,远好过一次糊一大片。 DefaultSearchLimit = 3 // MaxSearchLimit 检索上限的钳位天花板。防的是宿主误传一个天文数字,把「按需披露」 // 退化成「一次性全量披露」——那等于本包没装。天花板压到 5:单次检索能吐出的东西 // 必须**永远少于一个工具全集**,否则「省上下文」只是把省的动作挪到了检索里。 MaxSearchLimit = 5 // MaxDescriptionLen 目录内单条描述的字符上限(按 rune 计),超出在构造时截断。 // // 为什么截断而不是写进文档靠自觉:描述是宿主给的自由文本,长度不受本包控制,而目录是 // 本包**唯一**按工具数量线性增长的内存。不设界,工具一多描述就能吃满整个进程; // 落成常量后「单个工具最多占多少」才是可核对的事实而不是一条约定。 // 取 320 与参考实现对齐:同一份注册表在两侧应得到同一长度的目录,否则「谁更长」 // 变成实现细节,而目录内容是要逐轮发给模型的。 MaxDescriptionLen = 320 )
const DegenerateType = "none"
DegenerateType 退化 schema 的顶层类型标记。
为什么不是空串:空串是「忘了填」的默认值,拿它当占位标记,任何一处遗漏构造都会 静默变成占位而没人发现。取一个**真实工具不会声明的类型名**,占位与真身因此不可能混淆。
const PlaceholderNotice = "(schema 未加载:先用检索工具按关键词取回本工具的完整 schema,再调用。)"
PlaceholderNotice 未加载工具描述里追加的取回指令。
为什么指令必须落在**描述**里而不是指望空 schema 自己表达:模型读的是描述里的祈使句。 一个「空 schema」不会被它理解成「禁止调用」,只会被理解成「这工具不需要参数」—— 于是它开始照着描述瞎编参数,门禁也就没机会把这次调用挡回来。 指令写死在这里而不做成可变文案:它是本包的核心机制提示,允许宿主改写等于 允许宿主无声地关掉「先取回再调用」这道闸。
const StageName = "tool_disclosure"
StageName 本环在链上的名字。固定值:留痕要能回答「是哪一环拒的」。
Variables ¶
var ( // ErrNotLoaded 工具在目录内,但 schema 尚未交付给模型。 // 可恢复:先取回 schema、再按 schema 构造参数调用即可成功;**原样重试不会成功**。 // 门禁不再把「被拒的尝试」当成加载事件——那样会绕开渐进披露本身。 ErrNotLoaded = errors.New("工具 schema 尚未取回") // ErrNotInCatalog 工具不在目录内,从未可用。 // 不可恢复:不存在的东西不会因为重试而出现,任何退避策略都应就此停手。 ErrNotInCatalog = errors.New("工具不在目录内") )
门禁哨兵。两者重试性**相反**,混淆的后果是把一次策略否定变成无穷重试。
var ErrSchemaNotDerivable = errors.New("工具 schema 派不出合法的位置调用形态")
ErrSchemaNotDerivable 该工具的 schema 派不出合法的调用形态。errors.Is 判定。
Functions ¶
func Guidance ¶
Guidance 取出任意错误的门禁指引。非门禁错误返回空串(调用方据此判断要不要回退到自己的文案)。
认不出就返回空而不是编一句:本包只对自己的两类结局有把握, 替别人的错误编措辞会把无关的失败也套上门禁口径。
func MergeLoaded ¶
MergeLoaded 合并多份已加载集:并集、去重、升序。
为什么排序是**语义要求**而不是格式偏好:编排可能从多个环节并发汇流各自的已加载集。 若保留各自的追加顺序,同一份事实在不同并发时序下会呈现成不同的序列—— 留痕、回放、比对全都不再可复现。并集 + 排序把并发时序从结果里彻底抹掉: 无论谁先谁后,合并结果逐字节相同。
空名成员被丢弃:空名进不了任何目录(见 NewCatalogWithLimit),留着只会让 「已加载了什么」这个集合凭空多一项。
func PlaceholderDescription ¶
PlaceholderDescription 给工具描述追加取回指令(原文保留在前,宿主可自行决定是否换文案, 但必须保留「先取回 schema 再调用」这句语义)。
原文按「MaxDescriptionLen − 指令长度」截断:追加指令后模型实际收到的描述仍不得超过 声明的单条上限。旧实现把指令无条件追加在已截到 MaxDescriptionLen 的描述后面, 实际交付 363 rune > 320(issue #290)。
func Retryable ¶
Retryable 该错误是否值得重试。
认不出的错误一律 false(fail-closed)。理由同上:门禁两类结局的差别只在「是否可恢复」上, 猜错的代价不是少重试一次,而是不停重复一个永远不会成功的调用——把策略否定伪装成抖动。
func SignatureOf ¶
SignatureOf 从工具 schema 派生位置调用形态,形如 `get_logs(host, count?)`。
返回的字符串直接可作为 ptc.Binding.Signature 使用;两者由本函数保证同一口径, 不需要调用方再对一次。
函数名是**净化后**的名字,不是目录里的原名 ¶
程序里真正挂上去的是净化后的名字:ptc 把绑定挂在 `host.<净化名>` 上, 而净化规则(`toolname.Normalize`)会改掉名字的形状——`get-logs` 挂上去 叫 `host.get_logs`。所以形态串里的函数名也必须是净化后的那个。
旧实现照抄目录里的原名,于是对任何名字带非法字符的工具(`get-logs`、 `restart-service` 这类带横线的名字极常见)派出的形态**在 ptc 侧必被拒**: ptc 校验「形态里的函数名 == 净化后的绑定名」,而这里是原名。
而本函数的文档却写着「直接可用、不需要调用方再对一次」——**文档与代码 自相矛盾**,症状是「工具明明在目录里,程序就是调不通」,排查时极容易 先怀疑模型。同一份文档的上一版甚至把这条矛盾**用测试钉住了**(钉的是 「会被拒」),于是两边的错一起被固化成了「预期行为」。
现在两侧共用同一条规则(`toolname` 包),派生态与消费端**不可能**再漂移。
func Stage ¶
Stage 把工具披露门接成 invoke 链上的一环。
cat 为 nil 时按「不在目录内」处理——即 fail-closed:不装配目录就是没有工具, 门禁不因缺配置而乐观放行(与 Gate.Check 在空目录下的语义一致)。
为什么 Reason 回的是指引而不是 err.Error() ¶
链上的 Verdict.Reason 是宿主把这环结论交给上层的唯一出口,绝大多数宿主会 把它原样送进模型可见的失败消息。而两类结局要求模型做的动作恰好相反: 未加载要**重试**、不在目录要**换工具**。回一句「工具不在目录内」的话, 模型只知道自己被拒了,接下来做什么全靠猜——而在第二类上继续重试, 就是把一次策略否定拖成一段空转。
指引文本本身含工具名,审计要的「哪次调用被拒」不会因此丢失, 故同一字段同时满足留痕与模型两头的需要,不需要再开一个字段。
Types ¶
type Catalog ¶
type Catalog struct {
// contains filtered or unexported fields
}
Catalog 工具目录 + 已加载集。
不变式:**目录成员在构造后不再变化**(没有删除/新增入口),只有已加载集可变。 门禁正是靠这条不变式把「在目录内」判成一个稳定事实:并发加载不会让同一个名字 在两次调用里一会儿在、一会儿不在。
**副本口径(全覆盖)**:Schema.Properties(map)与 Schema.Required(slice)是 引用类型。构造期从宿主入参深拷贝一次;Lookup / Load / Expose / ExposeAll / Search 交出前再深拷贝一次。调用方拿到的都是自己的副本——原地改写返回值或构造后 改写宿主原变量都改不动目录(Names 的副本承诺同此口径)。
func NewCatalogWithLimit ¶
NewCatalogWithLimit 构造目录并指定检索上限(钳位到 [1, MaxSearchLimit];<=0 取默认值)。
重名规则:首次出现处胜出(first wins) ¶
目录入参是宿主给的注册表,重名意味着两个来源各声明了一个同名工具。选 first wins 而不是 last wins,理由有三:
- **与本仓既有去重同款**(checkpoint.BuildPlan 的编排图净化同样是保留首次出现处), 同一种理由在仓内只有一种答案,避免两处各自漂移。
- last wins 会让「追加一条覆盖」成为事实上的默认用法,而覆盖发生在**调用方拼注册表** 时——那是个拼装细节,却悄悄改变了模型能调到什么;first wins 则把「重名」保持在 「装配问题」这一层,不外溢成运行期行为。
- 两种规则都能确定,但 first wins 保留了首次声明的位置与内容,故障排查时 「这条工具哪来的」指向唯一来源。
重名**静默去重**:目录是可复现的装配结果,不是诊断面。宿主若需要发现冲突, 在调用本包前自己按名去重即可——那属于装配期的校验,不属于运行期门禁。
func (*Catalog) Expose ¶
Expose 按名取披露面:已加载给完整 schema,未加载给占位。 不在目录内返回 (零值, false)——不存在的东西没有占位面,占位只对「已存在但未取回」有意义。
返回的 Schema 是深拷贝(占位面的退化 schema 本就不含引用了,仍走同一出口)。
func (*Catalog) ExposeAll ¶
ExposeAll 全目录披露面,按名升序。
每轮装配工具面走这一个出口,避免调用方自己拼「哪些给全、哪些给占位」而出现分叉。 每条的 Schema 都是深拷贝(同 Expose 口径)。
func (*Catalog) Load ¶
Load 取回完整 schema 并标记为已加载,幂等(重复取回不改变任何状态)。
这是「披露」的唯一写入口:谁把工具变成完整面,在这里留痕,而不是各调用点各记一份。 返回深拷贝(同 Lookup 口径)。
func (*Catalog) Lookup ¶
Lookup 取完整定义;不在目录内返回 (零值, false)。
返回深拷贝:调用方可以原地改写 Schema.Properties/Required,改不动目录。
func (*Catalog) Names ¶
Names 目录内全部工具名,升序。
返回的是副本:调用方拿到的切片可以随便改,改不动目录(与旧实现一致——旧实现 每次调用都新建切片,这里保留那条契约,只是不再重新排序)。
func (*Catalog) Search ¶
Search 按关键词检索目录,返回按 (分值降序, 名字升序) 排好并已截断的命中。
无命中返回空,不兜底给「随便几个」 ¶
这是本包最重要的一条语义。渐进披露的成本模型建立在「模型问什么、我们给什么」上; 无命中时兜底塞几个候选,等于把一次检索失败变成一次静默的上下文膨胀,而且模型会以为 检索有效,下一轮继续照着错的候选走。宁可让它看见「没查到」——它会换个词再来一次。
检索只排序、**不激活**:激活是宿主(或门禁)的显式决定。若检索顺手把命中项全部标成已加载, 一次宽泛的查询就能把刚省下来的上下文又吐回去,本包也就退化成了「带搜索框的全量披露」。
需要知道「有没有被截断」时用 SearchWithMeta;本方法保留既有签名(Stable 包只允许 additive 变更),两者共用同一份检索实现。
func (*Catalog) SearchWithMeta ¶ added in v0.42.0
func (c *Catalog) SearchWithMeta(query string) SearchResult
SearchWithMeta 与 Search 同一次检索,额外返回截断统计(Total / Omitted / Truncated)。
Truncated 的语义与 skilldisclose.Result.Truncated 对齐:**预算/上限裁掉了候选** 就必须标出来,静默截断会让调用方以为「就这几个」。
type Exposure ¶
type Exposure struct {
Name string
Description string
Schema Schema
// Loaded 该面是否为完整面(占位面恒为 false)。
Loaded bool
}
Exposure 一次披露投给模型的工具面。
func Placeholder ¶
Placeholder 构造未加载工具的占位披露面:退化 schema + 带取回指令的描述。
单独立为函数(而不是只藏在目录内部):宿主拼自定义工具面、或测试替身要复刻这套语义时, 都能取到同一份实现,不至于各写一版慢慢分叉。
type Gate ¶
type Gate struct {
// contains filtered or unexported fields
}
Gate 工具执行门禁。
func (*Gate) Check ¶
Check 判定一次调用是否放行。三种结局,处置互不代偿:
- 已加载(schema 已交付)→ nil,可执行;
- 在目录内但未加载 → 返回可恢复的 *GateError。**不产生任何副作用**: 放行判据只认 schema 交付事件(Catalog.Load),不认被拒的调用尝试;
- 不在目录内 → 返回不可重试的 *GateError,调用方应就地终止,不得退避重试。
为什么被拒的尝试不再顺手激活:那会让「猜参数 ⇒ 被拒 ⇒ 原样重试 ⇒ 放行」 成为最短路径,模型从未取回 schema,渐进披露省上下文的前提被自身恢复路径绕开 (issue #286)。恢复路径是「先取回 schema,再构造参数调用」,不是重试。
空工具名按「不在目录内」处置:门禁不做乐观放行。
type GateError ¶
type GateError struct {
// Name 被拒的工具名。
Name string
// Activated 门禁是否已把该工具激活为已加载。
//
// 保留字段是为兼容既有审计面,但门禁现在**恒不产生该副作用**(恒为 false):
// 「已加载」只能由 schema 交付事件(Catalog.Load)改写。把拒绝尝试当成加载事件
// 会让「猜参数 ⇒ 被拒 ⇒ 原样重试 ⇒ 放行」成为一条最短路径(issue #286)。
Activated bool
// contains filtered or unexported fields
}
GateError 门禁拒绝的结构化形态。
用共享类型 + 哨兵而不是两个独立类型:调用方多半只想问「能不能重试」, 而审计/留痕另需工具名与「门禁是否动了手」。拆成两个类型会逼每个分支各抄一遍这几个字段。 两者靠 Unwrap 指向的哨兵区分,errors.Is 分支,调用方不必认这个结构体。
Retryable() 方法同时是对外的**自报接口**:通用退避层(toolfail)问的就是「能不能重试」, 不该被迫认识本包、也不该靠 errors.Is 认哨兵。让本类型直接答,比让每个调用方各抄一遍 「哪种结局可重试」可靠——那正是两边各判一套、慢慢漂移的起点。
func (*GateError) Error ¶
Error 文本。nil 接收者给缺省串而不是解引用 e.kind:typed-nil 的 *GateError 会被无防御地塞进日志链路(%v / err.Error()),panic 会杀掉整个编排进程。
func (*GateError) Guidance ¶
Guidance 该次拒绝面向模型的指引:既说清发生了什么,也说清下一步该做什么。
为什么门禁必须能对模型说话 ¶
本包的机器侧契约一直很完整:哨兵二分、Retryable 自报、Activated 字段, 都在为**程序**决策服务。但模型不是程序——它看到一句「工具 schema 尚未取回」 之后无从判断该取回 schema 还是该换工具,只能自己猜。而两类结局要求的行为相反: 未加载时**先取回 schema 再调用**,不在目录时**必须停手**。 指引缺位时,模型在第二类上继续重试,就会把一次策略否定拖成一段空转。
未加载一路的指引**不得**包含「原样重试/以相同参数重新调用」:门禁不会因重试 而放行(issue #286),那样写等于教模型跳过 schema 取回。
为什么不是可选能力 ¶
判据建了没人读等于没建。与其让每个宿主各写一份文案(拼法散落必然漂移, 而模型对措辞的敏感度远高于人),不如由本包给出唯一措辞——这是 toolfail.Guidance 同一套纪律的第二次落地。
type Schema ¶
type Schema struct {
// Type JSON Schema 顶层类型;退化占位恒为 DegenerateType。
Type string
// Properties 参数定义;退化占位恒为 nil。
Properties map[string]Param
// Required 必填参数名;退化占位恒为 nil。
Required []string
// Truncated 构造期是否裁剪过 schema(参数描述截断或参数项超 MaxSchemaBytes 被丢弃)。
// 宿主可据此决定是否回源取完整定义;未裁剪恒为 false。
Truncated bool
}
Schema 工具输入 schema 的最小载体。
为什么自定一个结构而不是收 map[string]any:占位的「退化」必须**可机械判定**, 否则宿主无法保证「未加载的工具不泄露真 schema」。宿主把自己的 schema 投影进来即可, 本包不要求与宿主的 JSON Schema 库同型。
func Degenerate ¶
func Degenerate() Schema
Degenerate 空 schema:声明不了任何参数,故任何调用都必然参数非法。
这一点是**故意**的:占位若碰巧还能被调用,模型就会把占位当契约继续瞎编参数, 门禁也就没机会把它挡回来。
type SearchResult ¶ added in v0.42.0
type SearchResult struct {
// Matches 与 Search 返回值相同:按 (分值降序, 名字升序) 排好并已截断的命中。
Matches []Match
// Total 截断前的命中总数(不是目录总数)。
Total int
// Omitted 被截断掉的命中数:Total - len(Matches)。
Omitted int
// Truncated Omitted > 0,即「有候选因上限未披露」。
Truncated bool
}
SearchResult 带截断信息的检索结果。
为什么要有它:Search 的返回值只有命中项,调用方拿不到「还有更多候选」的信号。 模型看到三条就会认定「就这三个工具相关」,宿主也无法据此决定要不要再检索一次。 字段名与 skilldisclose.Result 对齐:Truncated 同义(裁剪发生了),Omitted 给出 「还有多少条未披露」。