tool

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"`
}

Definition 描述一个工具，用于暴露给模型（function calling 的 tool 定义）。

InputSchema 是参数的 JSON Schema（object 类型），模型据此生成调用参数。 这里只承载模型可见的元信息；授权动作由工具在执行期自行调用 RequestPermission（见 permission.go）声明，不再作为定义元数据透传给 Provider。

type Executor ¶

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

Executor 执行工具调用：解析工具 → 校验参数 → 套用中间件 → 执行。

语义约定：所有失败（工具不存在 / 参数非法 / 超时 / panic / 工具返回错误）都 收敛为 Result.IsError=true，而不会向上抛出中断整个流程——模型据此纠正行为。

func NewExecutor(registry *Registry, opts ...ExecutorOption) *Executor

func (e *Executor) Execute(ctx context.Context, call Call) Result

type ExecutorOption ¶

type ExecutorOption func(*Executor)

ExecutorOption 配置 Executor。

func WithMiddlewares(ms ...Middleware) ExecutorOption

type Func ¶

type Func[In, Out any] struct {
	// contains filtered or unexported fields
}

Func 把普通函数适配为 Tool：In 为入参结构，Out 为返回结构。

Execute 内部完成 json.Unmarshal(In) → fn(ctx, in) → 返回 Out。

func NewFunc[In, Out any](name, description string, inputSchema map[string]any, fn func(context.Context, In) (Out, error)) *Func[In, Out]

func (f *Func[In, Out]) Definition() Definition

func (f *Func[In, Out]) Execute(ctx context.Context, args json.RawMessage) (any, error)

func (f *Func[In, Out]) WithPermission(action, pathFrom, description string) *Func[In, Out]

func (f *Func[In, Out]) WithPermissionPreview(action, pathFrom, description string, preview func(context.Context, In) PermissionPreview) *Func[In, Out]

type Middleware ¶

type Middleware func(next Next) Next

Middleware 包裹工具执行：在真正调用工具前后做校验 / 超时 / 恢复 / 日志等。

中间件在 Executor 中按注册顺序包裹（先注册的越靠内层）。约定：中间件应调用 next 继续执行，并在需要时改造 ctx / call / 返回值。

func Logging(logf func(format string, args ...any)) Middleware

func Recover() Middleware

func Timeout(d time.Duration) Middleware

type Next ¶

type Next func(ctx context.Context, call Call) (any, error)

Next 是中间件链中的下一个处理器。

type PermissionPreview ¶ added in v0.2.0

type PermissionPreview struct {
	FilePath string `json:"file_path,omitempty"`
	Diff     string `json:"diff,omitempty"`
}

PermissionPreview 是授权请求中「批准前预览」的附加信息。

FilePath / Diff 的 JSON 键与 coder edit / write 的授权参数保持一致，上层 （agent.operationFromToolPermission）会把它们提取到 Operation.Metadata 的 file_path / diff，前端据此在用户批准前渲染 unified diff。

type PermissionRequest ¶ added in v0.2.0

type PermissionRequest struct {
	SessionID   string `json:"session_id"`
	ToolName    string `json:"tool_name"`
	Description string `json:"description"`
	Action      string `json:"action"`
	Params      any    `json:"params,omitempty"`
	Path        string `json:"path,omitempty"`
}

PermissionRequest 描述一次工具操作授权请求。

字段与 opencode internal/permission.CreatePermissionRequest 对齐，使从 opencode/internal/llm/tools 迁移过来的工具保持一致的权限语义：

• SessionID：发起调用的会话标识（缺省时由 RequestPermission 从 ctx 补齐）；
• ToolName / Action：工具名与授权动作（execute / write / read / fetch / delete ...）；
• Description：展示给用户的摘要（如 "Execute command: ls -la"）；
• Params：工具入参，供上层抽取命令 / diff 等细节；
• Path：授权作用路径（文件操作取目录，命令执行取工作目录）。

type PermissionRequester ¶ added in v0.2.0

type PermissionRequester interface {
	RequestPermission(ctx context.Context, req PermissionRequest) bool
}

PermissionRequester 由上层注入，把工具操作授权请求桥接到 Runtime。

返回 true 表示允许，false 表示拒绝。tool 包不依赖 agent 包，因此这里只声明 最小端口，具体映射（PermissionRequest → Operation → Runtime.RequestPermission） 由上层实现（见 agent.WithToolPermission）。

func PermissionRequesterFrom(ctx context.Context) PermissionRequester

type Registry ¶

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

Registry 注册并解析工具。

工具按名称唯一；List 返回全部工具的 Definition，供 Provider 暴露给模型 （即 function calling 里的 tools 参数）。

func NewRegistry() *Registry

func NewRegistryWith(tools ...Tool) *Registry

func (r *Registry) Definition(name string) (Definition, bool)

func (r *Registry) Get(name string) (Tool, bool)

func (r *Registry) Has(name string) bool

func (r *Registry) List() []Definition

func (r *Registry) Names() []string

func (r *Registry) Register(t Tool)

func (r *Registry) Tools() []Tool

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 标识这次调用是否失败，模型可据此纠正后续行为。

func Failure(err error) Result

func Success(data any) Result

type Tool ¶

type Tool interface {
	// Definition 返回工具的元信息（名称 / 描述 / 参数 schema）。
	Definition() Definition
	// Execute 执行工具；args 是模型生成的参数（JSON，空时视为 {}）。
	Execute(ctx context.Context, args json.RawMessage) (any, error)
}

Tool 是可被 Agent 调用的一个工具。

实现约定：

• Execute 返回的 error 会被上层包装为"工具执行失败"的结果（Result.IsError=true）， 而不会中断整个调用流程——模型可以看到错误信息并尝试纠正。
• 返回的 any 会被序列化为结果内容（Result.Content）回传给模型。