Documentation
¶
Overview ¶
Package capability 定义框架的最小统一抽象:一切节点皆能力。
工具、ChatModel、Memory、RAG、Skill、完整的 Agent,都实现同一个 Capability 接口。每个能力有两种挂载形态:
- AsTool:挂到模型的工具面,由"大脑"(LLM)决定何时调用 —— 动态编排;
- AsLambda:挂到 eino Graph 的固定节点,由流程决定何时执行 —— 静态编排。
能力以 Ref(cap://kind/ns/name@version)标识,携带 Risk 分级供运行时做审批拦截与准入控制。
Index ¶
- Constants
- Variables
- func AsTools(ctx context.Context, caps []Capability) ([]tool.BaseTool, error)
- func Invoke(ctx context.Context, c Capability, argsJSON string) (string, error)
- func ParamsSchema(params map[string]ParamDecl) (*schema.ParamsOneOf, error)
- func ParseSingle(argsJSON, field string) string
- func SingleParam(name, desc string) *schema.ParamsOneOf
- type Capability
- type DeliverMode
- type Duration
- type InvokeFunc
- type Meta
- type ParamDecl
- type Ref
- type Risk
Constants ¶
const TagInteractive = "interactive"
TagInteractive 标记"阻塞等待用户输入"的交互类能力(ask_user 等): 工具超时闸门对其豁免——等人回复的时间不是执行时间。
const TagProcedureCard = "procedure-card"
TagProcedureCard 标记过程卡能力(mode: inline 的 skill):结果是执行 指引而非数据——消化会毁掉指令结构(豁免 digest),一次性计划也编排 不了"照着指引临场干"(rewoo 计划面剔除)。
const TagRawResult = "result:raw"
TagRawResult 标记能力的结果不参与消化(结果本身就是给模型的原文, 如 read_result 的分页输出)。声明于 core:消化闸门(loop)与引擎的 计划面筛选(engine)都要认它,而 engine 不得依赖 loop。
Variables ¶
var NoParams = &schema.ParamsOneOf{}
NoParams 显式声明"该工具确实无入参":工具形态的 ToolInfo.ParamsOneOf 置为 nil——eino FAQ 明确无参工具必须传 nil,空 schema 会被部分厂商 拒绝(400)。仅作身份标记,不要调用其方法。
Functions ¶
func ParamsSchema ¶
func ParamsSchema(params map[string]ParamDecl) (*schema.ParamsOneOf, error)
ParamsSchema 把 ParamDecl 映射为工具入参 schema;无参数时退化为单个 string 入参 {"input": ...}(与 capability.New 的默认一致)。 type 词汇装配期锁死:int/str/bool 等拼法此前静默转 string,模型按错 类型传参、后端拒收,错误面在运行期且难归因。
func ParseSingle ¶
ParseSingle 从参数 JSON 里取出单个字符串字段;解析失败时把整个 入参当作该字段的值(容忍图节点直接传裸字符串)。
func SingleParam ¶
func SingleParam(name, desc string) *schema.ParamsOneOf
SingleParam 生成单参数的入参 schema,减少样板代码。
Types ¶
type Capability ¶
type Capability interface {
Meta() Meta
// AsTool 返回能力的工具形态,供模型自主调用。
AsTool(ctx context.Context) (tool.BaseTool, error)
// AsLambda 返回能力的图节点形态(string 入参 JSON -> string 出参),
// 供 compose.Graph 静态编排。
AsLambda(ctx context.Context) (*compose.Lambda, error)
}
Capability 是所有节点的统一抽象。
func FromTool ¶
FromTool 把一个已有的 eino 工具(如 MCP 拉取的工具)包装成能力。 ref 的 Name 为空时取工具自报的名字。构造时调用一次 Info 获取元信息。
func NewModel ¶
func NewModel(ref Ref, description string, m model.ToolCallingChatModel) Capability
NewModel 把 ChatModel 纳入能力体系:AsTool 时是可被上级大脑调用的 "问答子模型"(如廉价小模型做摘要),AsLambda 时是图里的模型节点。
func Rename ¶
func Rename(c Capability, toolName string) Capability
Rename 返回一个模型可见短名不同的能力副本,目录在撞名升级时使用。 Ref 与其余元信息不变。
type DeliverMode ¶
type DeliverMode string
DeliverMode 是能力产出的交付语义:证据(缺省)由大脑消费合成; 交付物由 Ring 0 捕获原文、经出站事实位直达用户——大脑保留策展权 (引用哪些、写导读),失去转述权(原文不经它的嘴)。 设计:docs/deliverable-channel-plan.md。
const ( DeliverNone DeliverMode = "" // 证据(默认) DeliverAttach DeliverMode = "attach" // 存底;终答引用 #dN 即随行 DeliverAlways DeliverMode = "always" // 存底;不待引用恒随行 DeliverDirect DeliverMode = "direct" // 独占轮次时原文即终答;否则退化 attach )
func ParseDeliver ¶
func ParseDeliver(s string) (DeliverMode, error)
ParseDeliver 解析交付语义,未知值报错(配置词汇 fail fast)。
type Duration ¶
Duration 是配置里的时长字段,YAML 里写 "30s"/"5m" 这类字符串, 或裸数字(按秒解释)。零值表示未配置(取默认),负值表示显式关闭。 放在 capability(基座)是因为它是各层共享的配置词汇——engine 的编排 步骤、loop 的可靠性、config 的 TTL 都用它;loop.Duration 是本类型的别名。
type InvokeFunc ¶
InvokeFunc 是能力的统一执行契约:入参为 JSON 字符串,出参为字符串。
type Meta ¶
type Meta struct {
Ref Ref
Description string
// Params 是工具形态的入参 schema;为 nil 时默认单个 string 入参 {"input": ...}。
Params *schema.ParamsOneOf
Risk Risk
// Deliver 是产出的交付语义(证据/attach/always/direct),
// Ring 0 的 DeliverResults 按此捕获。
Deliver DeliverMode
Tags []string
}
Meta 是能力的自描述清单。Description 会作为工具描述暴露给模型, 是大脑调用决策的直接依据,写得越清楚决策越准。
type ParamDecl ¶
type ParamDecl struct {
Type string `yaml:"type" json:"type"`
Desc string `yaml:"desc" json:"desc"`
Required bool `yaml:"required" json:"required"`
}
ParamDecl 描述一个可调用单元(skill / component / 编排步骤)的入参。 它是「可调用单元的参数接口」,循环族与编排族共用,故归基座 capability。
type Ref ¶
type Ref struct {
Kind string // tool | skill | component | agent | prompt | store | retriever
Domain string // 归属域:源名 / builtin / 存储用途 / prompt 源
Name string
Version string
}
Ref 是能力的结构化标识,文本形式(4 段):
cap://<kind>/<domain>/<name>@<version> cap://tool/fs/read_file@1.0 cap://skill/research/competitor_report@1 cap://store/session/sess
kind 是对象类别;domain 是该 kind 下 name 的归属域(见 domain 不变式: callable→源/ns,store/retriever→slot-kind,prompt→prompt 源);version 可以是语义版本或通道名(production/staging),空表示任意。
不变式:kind 段永远精确,通配只出现在 name 段(见 Match)。Key 不含 version(见 Key)。
func ParseRef ¶
ParseRef 解析完整标识或带 * 通配的模式。 形式:cap://kind/domain/name[@version];各段可为 * (模式), name 段允许前缀通配(如 todo_*)。
Source Files