tools

AGGO 工具系统

tools/ 提供可直接注册到 Eino Agent 的工具集合。顶层 github.com/CoolBanHub/aggo/tools 包是便捷入口；生产代码也可以直接导入 子包获得更细的配置能力。

工具包

使用示例

import (
    cronPkg "github.com/CoolBanHub/aggo/cron"
    aggotools "github.com/CoolBanHub/aggo/tools"
    "github.com/CoolBanHub/aggo/tools/database"
    "github.com/CoolBanHub/aggo/tools/shell"
    "github.com/cloudwego/eino/components/tool"
)

knowledgeTools := aggotools.GetKnowledgeTools(indexer, retriever, retrieverOptions)
reasoningTools := aggotools.GetKnowledgeReasoningTools(retriever, retrieverOptionsList)

// database_execute 默认只允许只读查询。
dbTools := aggotools.GetDatabaseTools(gormDB)

// 写 SQL 需要由工具创建方显式开启。
writeDBTools := aggotools.GetDatabaseTools(gormDB, database.WithAllowWrite(true))

// shell_execute 默认拒绝 rm、sudo 等高危命令，并将 workingDir 限制在进程启动目录内。
shellTools := aggotools.GetShellTools(
    shell.WithAllowedCommands("ls", "pwd", "cat"),
)

service := cronPkg.NewCronService(cronPkg.NewFileStore("cron_jobs.json"), nil)
cronTools := aggotools.GetCronTools(service)

allTools := append([]tool.BaseTool{}, knowledgeTools...)
allTools = append(allTools, reasoningTools...)
allTools = append(allTools, dbTools...)
allTools = append(allTools, shellTools...)
allTools = append(allTools, cronTools...)

安全边界

• database_execute 默认只允许 SELECT、SHOW、DESCRIBE、EXPLAIN、PRAGMA、WITH 等只读语句。需要写操作时使用 database.WithAllowWrite(true)。
• shell_execute 默认工作目录根为当前进程启动目录。需要修改根目录时使用 shell.WithWorkingDirRoot(...)；确需关闭限制时使用 shell.WithUnrestrictedWorkingDir()。
• shell_execute 默认拒绝高危命令，并可用 shell.WithAllowedCommands(...) 将可执行命令收敛到白名单。
• 对会产生大量结果的工具，应配置行数、输出长度或检索数量上限，避免把过多数据送入模型上下文。

开发约定

• 新工具应放在对应领域子包内，再按需通过 tools/tools.go 暴露便捷入口。
• 工具参数结构体应提供清晰的 jsonschema 描述，便于模型正确调用。
• 有外部副作用的工具必须有默认安全策略，并提供显式选项放宽限制。
• 新增工具时至少补一组参数校验或安全策略测试。