Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ImagePart ¶ added in v1.3.5
type ImagePart struct {
MimeType string `json:"mimeType"` // image/png | image/jpeg | image/webp | image/gif
Data string `json:"data"`
}
ImagePart 是一张内嵌图片（MIME 类型 + 纯 base64 数据，无 data: 前缀）。
type LoopState ¶
type LoopState struct {
Input string
Messages []Message
// InputImages 是本次输入携带的多模态图片（WithInputImages 注入，
// 引擎组装 input user 消息时带上）。已入 Messages，不参与序列化。
InputImages []ImagePart `json:"-"`
Tools *ToolRegistry
Iteration int
MaxIterations int
// PendingToolCalls 是本轮模型响应中待执行的调用，由引擎填充。
PendingToolCalls []ToolCall
LastResponse *ModelResponse
Usage Usage
// ForkID 非空表示这是 fork 子循环（core.Fork）的状态：引擎发出的事件
// 带上它，hook（如 localsession）按它分流归属；主循环为空串。
ForkID string
// SeedLen 是 fork 子循环携带的上下文快照长度（Messages 前 SeedLen 条
// 为 seed）。持久化层据此剥离 seed 只存分身增量；主循环为 0。
SeedLen int
// Metadata 供 hook 之间共享任意数据。
// 并发契约：除 OnToolStart / OnToolEnd（跨调用并发）外，引擎串行执行
// hook 回调；这两个回调内写 Metadata 须自行加锁。
Metadata map[string]any
// Emitter 由引擎注入：hook 通过它发送自定义事件到 OnEvent 回调。
// OnToolStart / OnToolEnd 跨调用并发，其中发事件须遵守 OnEvent 的
// 并发契约（快速返回、并发安全）。
Emitter event.OnEvent
// Stop 置 true 后，当前节点收尾完毕即终止 loop。
Stop bool
StopReason StopReason
// LastError 记录导致 StopError 的错误本体（endnote 等收尾 hook
// 展示用）。error 不可序列化，不参与落盘。
LastError error `json:"-"`
StartedAt time.Time
EndedAt time.Time
}
LoopState 是贯穿整个 loop 的统一结构体，hook 可读写任意字段。
context.Context 按 Go 惯例作为独立参数传递，不放入 State。
func (*LoopState) AppendMessage ¶
AppendMessage 追加一条消息到历史。
type Message ¶
type Message struct {
Role Role `json:"role"`
Content string `json:"content"`
ToolCalls []ToolCall `json:"tool_calls,omitempty"`
ToolCallID string `json:"tool_call_id,omitempty"` // RoleTool 消息关联的调用 ID
Err string `json:"err,omitempty"` // 工具执行失败时的错误文本
// 推理模型的思考过程（reasoning_content），仅展示与持久化回放——
// 协议要求请求不回传，Provider 构造请求时丢弃。
Reasoning string `json:"reasoning,omitempty"`
// 多模态图片输入（仅 user 消息携带）。base64 内嵌消息：落盘/恢复、
// fork 复制、trim 折叠段随消息自然流转；Provider 按各自协议转
// content parts（chat/completions image_url / responses input_image /
// anthropic image block），非 user 消息忽略。
Images []ImagePart `json:"images,omitempty"`
}
Message 是消息历史的原子单元，可序列化、可直接作为下一轮历史。
type ModelChunk ¶
type ModelChunk struct {
ContentDelta string
ReasoningDelta string
ToolCalls []ToolCallDelta
}
ModelChunk 是流式输出的增量：正文与思考过程分开通出，工具调用增量按片透出。
type ModelRequest ¶
ModelRequest 是引擎调用 Provider 时的完整输入。
type ModelResponse ¶
type ModelResponse struct {
Content string
ToolCalls []ToolCall
Usage Usage
// 推理模型的思考过程，入史到 Message.Reasoning（不回传 Provider）。
Reasoning string
}
ModelResponse 是模型单次响应：纯文本，或附带 tool calls 触发下一轮循环。
type StopReason ¶
type StopReason string
StopReason 是 loop 终止原因。
const ( StopCompleted StopReason = "completed" StopMaxIteration StopReason = "max_iterations" StopAborted StopReason = "aborted" StopError StopReason = "error" StopCancelled StopReason = "cancelled" )
type Tool ¶
type Tool interface {
Name() string
Description() string
ArgsSchema() json.RawMessage
Invoke(ctx context.Context, args json.RawMessage) (string, error)
}
Tool 是工具节点接口：schema 供模型发现，Invoke 执行（可并发，碰不到 state）。
func NewTool ¶ added in v1.3.0
NewTool 从函数构造工具：A 是参数结构体，schema 由其 struct tag 反射生成—— json:"name,omitempty" 定字段名（omitempty → 非 required，默认全 required）、 desc:"…" → description、enum:"a|b|c" → string enum。支持 string / bool / number（int*、uint*、float*）/ slice / map[string]T / json.RawMessage / 嵌套 struct；不支持的类型构造期 panic（组装者错误，fail fast，优于运行期产出 畸形 schema）。properties 与 required 均按字段声明序输出——schema 是 A 的 确定函数，跨进程稳定，KV cache 前缀才可能命中（不得改用 json.Marshal(map)， 其按 key 排序会打散声明序）。
required 只约束字段是否必须出现在 JSON 里，不做非零校验：允许空串的字段 （如 edit_file 的 new_text 删除语义）照常 required，值级业务校验留在 fn 内。
type ToolCall ¶
type ToolCall struct {
ID string
Name string
Args json.RawMessage
}
ToolCall 是模型发起的一次工具调用请求。
type ToolCallDelta ¶ added in v1.3.0
type ToolCallDelta struct {
Index int `json:"index"`
ID string `json:"id,omitempty"`
NameDelta string `json:"nameDelta,omitempty"`
ArgsDelta string `json:"argsDelta,omitempty"`
}
ToolCallDelta 是流式工具调用的增量分片：Index 定位同轮第几个调用 （协议侧的累积序号），各字段是本片新增量——ID 一次性给出， 名字与参数按序拼接。消费方按 Index 分桶累积。
type ToolRegistry ¶
type ToolRegistry struct {
// contains filtered or unexported fields
}
ToolRegistry 持有已注册工具。List 按工具名排序返回——排序是工具集的
确定函数，与注册顺序、组装路径无关（resume、重新 New、hook 注册时机变化 都不会打散），tools 序列化顺序因此跨请求稳定，前缀缓存（KV cache）才可能 命中。同名注册直接覆盖（同名 = 同一工具的新版本，幂等重注册与热加载语义）。
func NewToolRegistry ¶
func NewToolRegistry(tools ...Tool) *ToolRegistry
NewToolRegistry 创建注册表并注册初始工具。
func (*ToolRegistry) Lookup ¶
func (r *ToolRegistry) Lookup(name string) (Tool, error)
Lookup 按名解析工具；找不到返回 error——模型幻觉调用会走到这里，
错误作为工具结果回传模型自纠，不终止 loop。
func (*ToolRegistry) Register ¶
func (r *ToolRegistry) Register(t Tool)
Register 注册工具：经 warp 壳包装后按名存入，同名覆盖。
func (*ToolRegistry) SetWarp ¶
func (r *ToolRegistry) SetWarp(warp func(Tool) Tool)
SetWarp 设置注册拦截：之后所有 Register 的工具都会被包装（含 hook 运行时
注入的工具，如 mcp router）。已注册的不受影响。
type ToolResult ¶
ToolResult 是一次工具调用的执行结果（toolEnd hook 可改写后入史）。
Source Files