Skip to content

An open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作

7.9 KB
Raw Blame
// SiYuan - https://github.com/siyuan-note/siyuan
// Copyright (c) 2020-present, b3log.org
// SPDX-License-Identifier: AGPL-3.0-or-later

package tools

import (
	"context"
	"encoding/json"
	"net/url"
	"strings"

	"github.com/siyuan-note/siyuan/kernel/model"
)

// BuildCapabilityID 构造由来源、执行侧和提供方局部名称组成的稳定能力 ID。
func BuildCapabilityID(source, side string, segments ...string) string {
	parts := []string{url.PathEscape(source), url.PathEscape(side)}
	for _, segment := range segments {
		parts = append(parts, url.PathEscape(segment))
	}
	return strings.Join(parts, "/")
}

const (
	EffectScopeLocal    = "local"
	EffectScopeExternal = "external"
	EffectScopeMixed    = "mixed"
	EffectScopeUnknown  = "unknown"
)

type Tool struct {
	Name         string      `json:"name"`
	Title        string      `json:"title,omitempty"`
	Description  string      `json:"description"`
	InputSchema  ToolSchema  `json:"inputSchema"`
	OutputSchema *ToolSchema `json:"outputSchema,omitempty"`
	// CapabilityID 是能力使用与对外暴露策略共用的稳定标识,不随模型函数名或显示标题变化。
	CapabilityID string `json:"capabilityId,omitempty"`
	// Source 标记工具来源:"native"(SiYuan 内置)、"plugin"(插件注册)、"mcp"(外部 MCP 服务)。
	// 用于 token 分类统计按来源拆分。空值按 "native" 处理(兼容旧调用方)。
	Source string `json:"source,omitempty"`
	// OwnerID 和 OwnerName 标识提供能力的插件或 MCP 服务,内置能力留空。
	OwnerID   string `json:"ownerId,omitempty"`
	OwnerName string `json:"ownerName,omitempty"`
	// Runtime 描述执行位置:kernel、plugin-worker 或 mcp。
	Runtime string `json:"runtime,omitempty"`
	// AgentOnly 标记能力仅供应用内 Agent 使用,不得投影到外部 MCP 服务。
	AgentOnly bool `json:"agentOnly,omitempty"`
	// Available 在列出和执行能力时检查其配置是否可用,空值表示始终可用。
	Available func() bool `json:"-"`
	// ReadOnlyHint 仅在外部工具明确声明只读时为 true;未声明时按可能写入处理并要求确认。
	ReadOnlyHint bool `json:"readOnlyHint,omitempty"`
	// EffectScope 描述写操作影响范围,用于判断本地数据仓库快照是否具有回滚价值。
	EffectScope string `json:"effectScope,omitempty"`
	// ActionEffects 按 action 描述本地读写、数据外发与外部计费,供智能体精确执行确认和快照策略。
	ActionEffects map[string]ToolEffects `json:"-"`
	// ResolveEffects 在列出和确认能力时读取当前配置,未声明时沿用静态效果与既有确认规则。
	ResolveEffects func(string) (ToolEffects, bool) `json:"-"`

	Handler          func(args map[string]any) (CallToolResult, error)                      `json:"-"`
	ContextHandler   func(ctx context.Context, args map[string]any) (CallToolResult, error) `json:"-"`
	BoxLeaseResolver func(args map[string]any) []string                                     `json:"-"`
}

type ToolEffects struct {
	LocalRead    bool `json:"localRead,omitempty"`
	LocalWrite   bool `json:"localWrite,omitempty"`
	DataEgress   bool `json:"dataEgress,omitempty"`
	ExternalCost bool `json:"externalCost,omitempty"`
}

func (t *Tool) IsAvailable() bool {
	return t != nil && (t.Available == nil || t.Available())
}

func (t *Tool) EffectsFor(action string) (ToolEffects, bool) {
	if t == nil {
		return ToolEffects{}, false
	}
	if t.ResolveEffects != nil {
		if effects, declared := t.ResolveEffects(action); declared {
			return effects, true
		}
	}
	if t.ActionEffects == nil {
		return ToolEffects{}, false
	}
	effects, ok := t.ActionEffects[action]
	if !ok && action != "" {
		effects, ok = t.ActionEffects[""]
	}
	return effects, ok
}

type ToolSchema struct {
	Type       string                `json:"type,omitempty"`
	Properties map[string]Property   `json:"properties,omitempty"`
	Required   []string              `json:"required,omitempty"`
	OneOf      []ToolSchema          `json:"oneOf,omitempty"`
	AnyOf      []ToolSchema          `json:"anyOf,omitempty"`
	AllOf      []ToolSchema          `json:"allOf,omitempty"`
	Ref        string                `json:"$ref,omitempty"`
	Defs       map[string]ToolSchema `json:"$defs,omitempty"`
	Raw        map[string]any        `json:"-"`
}

func (s ToolSchema) MarshalJSON() ([]byte, error) {
	if s.Raw != nil {
		return json.Marshal(s.Raw)
	}
	type plain ToolSchema
	return json.Marshal(plain(s))
}

func (s *ToolSchema) UnmarshalJSON(data []byte) error {
	raw := map[string]any{}
	if err := json.Unmarshal(data, &raw); err != nil {
		return err
	}

	type plain ToolSchema
	var decoded plain
	if err := json.Unmarshal(data, &decoded); err == nil {
		*s = ToolSchema(decoded)
	} else {
		*s = ToolSchema{}
		if schemaType, ok := raw["type"].(string); ok {
			s.Type = schemaType
		}
	}
	s.Raw = raw
	return nil
}

type Property struct {
	Type        string              `json:"type,omitempty"`
	Description string              `json:"description,omitempty"`
	Enum        []string            `json:"enum,omitempty"`
	Items       *Property           `json:"items,omitempty"`
	Properties  map[string]Property `json:"properties,omitempty"`
	Required    []string            `json:"required,omitempty"`
	OneOf       []Property          `json:"oneOf,omitempty"`
	AnyOf       []Property          `json:"anyOf,omitempty"`
	AllOf       []Property          `json:"allOf,omitempty"`
	Ref         string              `json:"$ref,omitempty"`
}

type CallToolResult struct {
	Content              []ContentItem     `json:"content"`
	StructuredContent    any               `json:"structuredContent,omitempty"`
	StructuredContentSet bool              `json:"-"`
	ModelAttachments     []ModelAttachment `json:"-"`
	IsError              bool              `json:"isError,omitempty"`
	ExecutionUnknown     bool              `json:"-"`
}

// ModelAttachment 描述工具希望在下一轮模型请求中附加的多模态输入。
// Data 只在当前运行期内存中传递,持久化时仅保存可重新解析资源的元数据。
type ModelAttachment struct {
	PDFImage   *model.PDFImageSelection `json:"pdfImage,omitempty"`
	Type       string                   `json:"type"`
	Data       []byte                   `json:"-"`
	MIMEType   string                   `json:"mimeType,omitempty"`
	Path       string                   `json:"path,omitempty"`
	DocumentID string                   `json:"documentId,omitempty"`
	Detail     string                   `json:"detail,omitempty"`
	Width      int                      `json:"width,omitempty"`
	Height     int                      `json:"height,omitempty"`
}

func (r CallToolResult) HasStructuredContent() bool {
	return r.StructuredContentSet || r.StructuredContent != nil
}

func (r CallToolResult) MarshalJSON() ([]byte, error) {
	type plain CallToolResult
	if r.StructuredContentSet && r.StructuredContent == nil {
		return json.Marshal(struct {
			plain
			StructuredContent json.RawMessage `json:"structuredContent"`
		}{
			plain:             plain(r),
			StructuredContent: json.RawMessage("null"),
		})
	}
	return json.Marshal(plain(r))
}

func (r *CallToolResult) UnmarshalJSON(data []byte) error {
	type plain CallToolResult
	var decoded plain
	if err := json.Unmarshal(data, &decoded); err != nil {
		return err
	}
	*r = CallToolResult(decoded)

	var fields map[string]json.RawMessage
	if err := json.Unmarshal(data, &fields); err != nil {
		return err
	}
	_, r.StructuredContentSet = fields["structuredContent"]
	return nil
}

type ContentItem struct {
	Type string `json:"type"`
	Text string `json:"text"`
	raw  json.RawMessage
}

func (item ContentItem) MarshalJSON() ([]byte, error) {
	if len(item.raw) > 0 {
		return item.raw, nil
	}
	type plain ContentItem
	return json.Marshal(plain(item))
}

func (item *ContentItem) UnmarshalJSON(data []byte) error {
	type plain ContentItem
	var decoded plain
	if err := json.Unmarshal(data, &decoded); err != nil {
		return err
	}
	*item = ContentItem(decoded)
	item.raw = append(item.raw[:0], data...)
	return nil
}