Help us shape the future of Go! Take the 2026 Go Developer Survey

tools

package
v1.38.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 26, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package tools 把 corebridge 能力包装为 eino 工具。 所有列表类工具每页硬上限 20 条,控制 token 用量;凭据字段永不进入工具输出。 依赖方向:tools → corebridge;会话能力经 SessionScope 接口注入,tools 不感知 agent 包。

Index

Constants

View Source 
const (
	// ModeDefault 危险工具走确认链路。
	ModeDefault = "default"
	// ModeReadOnly 一切写/危险工具一律拒绝。
	ModeReadOnly = "readonly"
	// ModeAudit 允许执行但标记审计(行为同 default)。
	ModeAudit = "audit"
)

权限模式常量。

View Source 
const ToolSetPermissionMode = "set_permission_mode"

ToolSetPermissionMode 切换工具权限模式的工具名。

Variables

This section is empty.

Functions

func DangerToolNames added in v1.25.0 

func DangerToolNames() []string

DangerToolNames 全部危险工具名(排序)。

**派生结果**:事实源是注册处(repo.go 的 addDanger 标注)。 供拿不到 Registry 实例的地方使用(如 system prompt 模板)。

func IsDangerTool added in v1.25.0 

func IsDangerTool(name string) bool

IsDangerTool 该工具是否需要用户确认(危险工具)。

**派生结果**:事实源是注册处(repo.go 的 addDanger 标注)。

func WithClientConfirmedScope added in v1.25.0 

func WithClientConfirmedScope(ctx context.Context) context.Context

WithClientConfirmedScope 给 ctx 装上「客户端已确认」的 scope。

用途:MCP 端点（以及任何「确认由调用方负责」的外部链路）。

func WithScope 

func WithScope(ctx context.Context, sc SessionScope) context.Context

WithScope 把会话能力注入 ctx(Runner 在每轮对话开始时调用)。

Types

type Action added in v1.17.0 

type Action string

Action 工具动作分级(借鉴 zcode permission capability groups)。 

const (
	ActionReadOnly Action = "readonly" // 只读,直接执行
	ActionConfirm  Action = "confirm"  // 危险,需用户确认
	ActionDenied   Action = "denied"   // 拒绝执行
)

type ClientConfirmedScope added in v1.25.0 

type ClientConfirmedScope struct{}

ClientConfirmedScope 是给**外部 MCP 客户端**用的 scope。

## 为什么 MCP 不走「登记待确认 → 用户确认 → 执行」

「登记待确认」这套机制是为**本进程内的 agent** 设计的:模型在同一个 会话里发起工具调用，服务端登记一个待确认项，前端把令牌带回来， 模型用令牌再调一次才执行。

MCP 是**无状态**的:客户端（Claude Code / Cursor）在把工具调用发过来之前， **它自己就已经向用户展示并征求过同意**了 —— 确认发生在客户端那一侧。 服务端这边再登记一个「待确认」，登记与执行根本不在同一个会话里， 令牌无处可去 —— 结果就是危险工具**在 MCP 上根本不可用** （会话上下文缺失，直接拒绝）。

## 它不绕过什么

  • **角色闸门照旧**：`dangerGuard` 的角色检查在 scope 检查**之前** （fail-closed）—— 只读角色在 MCP 上同样执行不了写工具。
  • **强制推送的 admin 闸门照旧**：那是 core 层的批准者校验，MCP 也一样。
  • **审计链照旧**：每次执行照样入链、可校验。

## 口径对齐

MCP 路径与 HTTP 路径一致（都是「客户端负责确认，服务端负责角色」）； CLI 与内置 AI 助手是本进程 agent，服务端必须自己加确认闸 —— 那条差异有理由。

func (ClientConfirmedScope) ConsumeConsumed added in v1.25.0 

func (ClientConfirmedScope) ConsumeConsumed(string, string) bool

ConsumeConsumed 恒为 true：视为客户端已确认，直接放行。

func (ClientConfirmedScope) LastConfirm added in v1.25.0 

func (ClientConfirmedScope) LastConfirm() (string, string, string)

LastConfirm 无状态可读。

func (ClientConfirmedScope) MarkConsumed added in v1.25.0 

func (ClientConfirmedScope) MarkConsumed(string, string)

MarkConsumed 无状态可标记。

func (ClientConfirmedScope) PermissionMode added in v1.25.0 

func (ClientConfirmedScope) PermissionMode() string

PermissionMode 没有会话状态,恒为空(⇒ 用进程级默认档)。

func (ClientConfirmedScope) SetLastConfirm added in v1.25.0 

func (ClientConfirmedScope) SetLastConfirm(string, string, string)

SetLastConfirm 无状态可记录。

func (ClientConfirmedScope) SetPending added in v1.25.0 

func (ClientConfirmedScope) SetPending(string, string) (string, error)

SetPending 不登记任何待确认项：MCP 的确认在客户端侧完成了。

func (ClientConfirmedScope) SetPermissionMode added in v1.25.0 

func (ClientConfirmedScope) SetPermissionMode(string) bool

SetPermissionMode 存不住:MCP 是无状态的,没有「会话」可挂。

返回 false 是**如实**而不是拒绝:调用方会告诉用户 「权限模式是会话级设置,MCP 端点上切不了」。

type MemEntry added in v1.17.0 

type MemEntry struct {
	ID      string   `json:"id"`
	Kind    string   `json:"kind"`
	Content string   `json:"content"`
	Tags    []string `json:"tags,omitempty"`
}

MemEntry 记忆条目视图。

type MemStore added in v1.17.0 

type MemStore interface {
	Remember(kind, content string, tags []string) (id string, err error)
	Recall(query string, limit int) []MemEntry
	Forget(id string) bool
}

MemStore 记忆库接口(tools 不直接依赖 agent/memory 包,保持依赖方向)。

type Policy added in v1.17.0 

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

Policy 工具权限策略(可运行时切换,如只读模式)。

判定主体交给 oagentkit guardx/permgate:它把「要不要人确认」表达成 规则引擎(Mode + Capability + Ruleset),裁决结果带 RuleID/Reason, 且预留了按工具入参内容匹配、按会话授权等扩展位—— 权限策略从此是数据而不是一段 switch,后续加配置化规则不必再重写判定层。

func NewPolicy added in v1.17.0 

func NewPolicy() *Policy

NewPolicy 默认策略:危险工具 confirm,其余 readonly。

func (*Policy) Classify added in v1.17.0 

func (p *Policy) Classify(ctx context.Context, tool string, danger bool) Action

Classify 判定工具动作。

danger:该工具是否需要用户确认 —— **由调用方(Registry)传入**。 Policy 不再自己查任何全局集合:「哪些工具危险」的事实源在注册处 (repo.go 的 addDanger 标注),由 Registry 用 r.IsDanger() 取出来传进来。

映射关系(与迁移前的本地 switch 逐档等价):

  • 危险工具 → Capability{AlwaysAsk} → permgate 裁决 Ask → ActionConfirm
  • 其余工具 → Capability{ReadOnly} → permgate 裁决 Allow → ActionReadOnly
  • 只读模式 → permgate ModeReadOnly → 非只读工具 Deny → ActionDenied

只留一处本地判定:显式 override 最高优先——permgate 的规则集排在只读档之下, 表达不了「把某个工具显式改成只读/放行」。

「只读模式下危险工具一律拒」这一条**已由上游原生支持** (oagentkit/guardx v0.14.0 起:checkAlwaysAsk 在会话授权之后、ask 之前插了 只读拦截段,checkStandard 把只读拦截插在 project ask 之前),本地不再兜底。 上游口径:会话授权在只读档仍放行(是用户已给出的决定,不是「问」)—— 本仓从不调用 AllowForSession,故无行为差异。

func (*Policy) Mode added in v1.17.0 

func (p *Policy) Mode() string

Mode 当前模式(进程级默认档)。

func (*Policy) ModeFor added in v1.25.0 

func (p *Policy) ModeFor(ctx context.Context) string

ModeFor 取本次调用生效的权限模式。

**会话优先**:会话里显式切过的档只影响这个会话 —— 之前档位是**进程级单例**,一个会话切成 readonly, 会连带把**其他所有会话**的写操作都拒掉(跨会话 DoS)。 会话没设过就用进程级默认档。

func (*Policy) Override added in v1.17.0 

func (p *Policy) Override(tool string, act Action)

Override 单独覆盖某工具动作。

func (*Policy) SetMode added in v1.17.0 

func (p *Policy) SetMode(mode string)

SetMode 切换模式:

  • default: 危险工具走确认链路
  • readonly: 一切写/危险工具一律拒绝
  • audit: 允许执行但标记审计(行为同 default)

type Registry 

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

Registry 工具注册表:构建 eino 工具集,并支持按名调用(确认执行路径复用)。

func NewRegistry 

func NewRegistry(svc SyncService) *Registry

func (*Registry) ByName 

func (r *Registry) ByName(name string) tool.InvokableTool

func (*Registry) DangerToolNames added in v1.25.0 

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

DangerToolNames 全部危险工具名(排序)。

func (*Registry) IsDanger added in v1.25.0 

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

IsDanger 该工具是否被标注为危险(需用户确认 / 只读角色不可执行)。

func (*Registry) Names 

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

Names 返回全部工具名。

func (*Registry) Policy added in v1.17.0 

func (r *Registry) Policy() *Policy

Policy 返回策略(可为 nil)。

func (*Registry) SetMemoryStore added in v1.17.0 

func (r *Registry) SetMemoryStore(m MemStore)

SetMemoryStore 注入记忆库(可选,未注入时工具返回说明)。

func (*Registry) SetPolicy added in v1.17.0 

func (r *Registry) SetPolicy(p *Policy)

SetPolicy 注入策略到注册表。

type SessionScope 

type SessionScope interface {
	SetPending(toolName, argsJSON string) (token string, err error)
	// ConsumeConsumed 一次性读取并清除放行标记:确认后仅放行一次执行。
	ConsumeConsumed(toolName, argsJSON string) bool
	MarkConsumed(toolName, argsJSON string)
	SetLastConfirm(toolName, token, argsJSON string)
	LastConfirm() (toolName, token, argsJSON string)

	// SetPermissionMode 记录本会话的工具权限模式。
	//
	// 返回 false 表示这条链路**存不住**(如无状态的 MCP 端点)——
	// 调用方据此如实告诉用户「这里切不了」,而不是假装切成功了。
	SetPermissionMode(mode string) bool
	// PermissionMode 取本会话显式设过的权限模式;空串表示没设过
	// (此时用进程级默认档)。
	PermissionMode() string
}

SessionScope 危险工具所需的会话能力(agent.Session 实现之;测试用 fake)。 定义在 tools 侧保持依赖方向 tools ← agent 单向。

func ScopeFrom 

func ScopeFrom(ctx context.Context) SessionScope

ScopeFrom 取会话能力;非 agent 链路为 nil。

type SyncService 

type SyncService interface {
	ListReposWithFilter(ctx context.Context, offset, limit int, filter *corebridge.RepoFilter) ([]*corebridge.Repo, int64, error)
	CountRepos() (int64, error)
	GetRepo(ctx context.Context, key string) (*corebridge.Repo, error)
	ListBranches(ctx context.Context, repoKey string) ([]string, error)
	TestConnection(ctx context.Context, repoKey string) (*coremodel.TestConnectionResult, error)

	ListTasks(ctx context.Context, repoKey string, offset, limit int) ([]*corebridge.SyncTask, int64, error)
	GetTask(ctx context.Context, key string) (*corebridge.SyncTask, error)
	ListHistory(ctx context.Context, taskKey string, offset, limit int) ([]*corebridge.SyncRun, int64, error)

	ListPlatforms(ctx context.Context) ([]*corebridge.Platform, error)
	TestPlatformConnection(ctx context.Context, key string) (*provider.TestConnectionResult, error)

	ListRules(ctx context.Context, repoKey string) ([]*corebridge.WebhookRule, error)

	CountTasksByStatus() (map[string]int64, error)
	HealthCheck() map[string]string
	RunTaskWithTrigger(ctx context.Context, taskKey, trigger string, webhookEventID *uint) error

	// 历史同步(histsync):**通道优先** —— 配置在通道里,执行按 channel id 进行。
	// 与镜像中心的身份镜像模式并存,语义不同。
	ListHistoryChannels(ctx context.Context, offset, limit int) ([]*corebridge.HistoryChannelDTO, int64, error)
	HistoryPlan(ctx context.Context, channelID uint) (*corebridge.HistoryPlanDTO, error)
	HistoryResolve(ctx context.Context, channelID uint) (*corebridge.HistoryPlanDTO, error)
	ListHistoryRuns(ctx context.Context, channelID uint, offset, limit int) ([]*corebridge.HistoryRunDTO, int64, error)
	VerifyHistoryChannelChain(ctx context.Context, channelID uint) (*corebridge.HistoryChainResult, error)
	ListHistoryOverrides(ctx context.Context, channelID uint) ([]*corebridge.HistoryOverrideDTO, error)
	SetHistoryOverride(ctx context.Context, channelID uint, in corebridge.HistoryOverrideInput) (*corebridge.HistoryOverrideDTO, error)
	HistoryPreview(ctx context.Context, channelID uint) (*corebridge.PreviewReport, error)
	HistorySync(ctx context.Context, opts corebridge.HistorySyncOptions) (*corebridge.HistorySyncReport, error)
	RotateHistoryTargetCredential(ctx context.Context, id uint, in corebridge.HistoryCredentialInput) (*corebridge.HistoryTargetDTO, error)

	// P0-P5:灾备 / RPO / 漂移 / 审计链
	RPOReport(maxSeconds int64) (*corebridge.RPOReport, error)
	VerifyBackupManifest() (*corebridge.ManifestVerifyResult, error)
	DetectDrift(ctx context.Context, taskKeys []string) (*corebridge.DriftReport, error)
	VerifyAuditChain() (*corebridge.AuditChainResult, error)
	RunDRDrill(ctx context.Context, name string) (*corebridge.DrillReport, error)
	BatchDRDrill(ctx context.Context, names []string, max int) ([]*corebridge.DrillReport, map[string]any, error)
	BackupDir() string
}

SyncService 工具所需的 Service 能力子集(*corebridge.Service 天然满足)。 定义窄接口便于单测 mock,也避免 tools 依赖 corebridge 具体构造。

Source Files

View all Source files

Directories

Path Synopsis
Package toolstest 提供跨包共用的测试基建:SyncService mock 与脚本化假模型。
 Package toolstest 提供跨包共用的测试基建:SyncService mock 与脚本化假模型。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.