内置工具一览

字数统计:1.7k 字

阅读时长:7 分钟

💡 提醒

本文档介绍 GsCore AI Core 提供的内置工具函数，这些工具可以直接在 AI 工具函数中使用。

适合场景：

🔍 需要让 AI 检索知识库内容
💬 想让 AI 主动发送消息给用户
💝 需要查询或更新用户好感度
🧠 想让 AI 记住用户相关信息

本文档介绍 GsCore AI Core 提供的内置工具函数，这些工具可以直接在 AI 工具函数中使用。

概述

GsCore AI Core 提供了一系列内置工具函数，方便插件开发者快速实现常见功能，无需重复开发。

工具导入

python

from gsuid_core.ai_core.buildin_tools import (
    search_knowledge,      # 知识库检索
    web_search,            # Web搜索
    send_message_by_ai,    # 发送消息
    query_user_favorability,   # 查询好感度
    query_user_memory,     # 查询用户记忆
    set_user_favorability,     # 设置好感度
    update_user_favorability,  # 更新好感度
)

知识库检索

search_knowledge

检索知识库内容。

python

async def search_knowledge(
    ctx: RunContext[ToolContext],
    query: str,                      # 自然语言查询
    category: Optional[str] = None,  # 知识类别筛选
    plugin: Optional[str] = None,    # 插件来源筛选
    limit: int = 10,                 # 最大返回数量
    score_threshold: float = 0.45,   # 相似度阈值
) -> str

参数说明

参数	类型	必填	默认值	说明
`ctx`	`RunContext[ToolContext]`	是	-	工具上下文
`query`	`str`	是	-	自然语言查询语句
`category`	`str`	否	`None`	知识类别筛选
`plugin`	`str`	否	`None`	插件来源筛选
`limit`	`int`	否	`10`	最大返回数量
`score_threshold`	`float`	否	`0.45`	相似度阈值，低于此值的结果会被过滤

返回值

返回检索到的知识内容字符串，多条结果会合并返回。

示例

python

from gsuid_core.ai_core.buildin_tools import search_knowledge
from pydantic_ai import RunContext
from gsuid_core.ai_core.models import ToolContext

@ai_tools()
async def query_game_info(
    ctx: RunContext[ToolContext],
    character_name: str,
) -> str:
    """
    查询游戏角色信息

    Args:
        character_name: 角色名称
    """
    result = await search_knowledge(
        ctx,
        query=f"{character_name}的角色信息和技能",
        plugin="Genshin",  # 限定在原神插件知识库中检索
        limit=5,
    )
    return result

Web 搜索

web_search

执行 Web 搜索。

python

async def web_search(
    ctx: RunContext[ToolContext],
    query: str,              # 搜索关键词
    num_results: int = 5,    # 返回结果数量
) -> str

参数说明

参数	类型	必填	默认值	说明
`ctx`	`RunContext[ToolContext]`	是	-	工具上下文
`query`	`str`	是	-	搜索关键词
`num_results`	`int`	否	`5`	返回结果数量

返回值

返回搜索结果的摘要信息。

示例

python

from gsuid_core.ai_core.buildin_tools import web_search
from pydantic_ai import RunContext
from gsuid_core.ai_core.models import ToolContext

@ai_tools()
async def search_latest_news(
    ctx: RunContext[ToolContext],
    topic: str,
) -> str:
    """
    搜索最新资讯

    Args:
        topic: 搜索主题
    """
    result = await web_search(
        ctx,
        query=f"{topic} 最新资讯",
        num_results=3,
    )
    return result

消息发送

send_message_by_ai

AI 主动发送消息。

python

async def send_message_by_ai(
    ctx: RunContext[ToolContext],
    message_type: Literal["text", "image"],  # 消息类型
    text: Optional[str] = None,              # 文本内容
    image_id: Optional[str] = None,          # 图片资源ID
    user_id: Optional[str] = None,          # 目标用户ID
) -> str

参数说明

参数	类型	必填	默认值	说明
`ctx`	`RunContext[ToolContext]`	是	-	工具上下文
`message_type`	`Literal["text", "image"]`	是	-	消息类型
`text`	`str`	否	`None`	文本内容（text类型必填）
`image_id`	`str`	否	`None`	图片资源ID（image类型必填）
`user_id`	`str`	否	`None`	目标用户ID，不填则发送到当前会话

返回值

返回发送结果描述。

示例

python

from gsuid_core.ai_core.buildin_tools import send_message_by_ai
from pydantic_ai import RunContext
from gsuid_core.ai_core.models import ToolContext

@ai_tools()
async def notify_user(
    ctx: RunContext[ToolContext],
    message: str,
    target_user: Optional[str] = None,
) -> str:
    """
    通知用户

    Args:
        message: 通知内容
        target_user: 目标用户ID，不填则通知当前用户
    """
    result = await send_message_by_ai(
        ctx,
        message_type="text",
        text=message,
        user_id=target_user,
    )
    return result

好感度管理

query_user_favorability

查询用户好感度。

python

async def query_user_favorability(
    ctx: RunContext[ToolContext],
    user_id: Optional[str] = None,
) -> str

参数说明

参数	类型	必填	默认值	说明
`ctx`	`RunContext[ToolContext]`	是	-	工具上下文
`user_id`	`str`	否	`None`	用户ID，不填则查询当前用户

返回值

返回用户好感度信息字符串。

示例

python

from gsuid_core.ai_core.buildin_tools import query_user_favorability
from pydantic_ai import RunContext
from gsuid_core.ai_core.models import ToolContext

@ai_tools()
async def check_favorability(
    ctx: RunContext[ToolContext],
    target_user: Optional[str] = None,
) -> str:
    """
    查询用户好感度

    Args:
        target_user: 目标用户ID，不填则查询当前用户
    """
    result = await query_user_favorability(ctx, target_user)
    return result

set_user_favorability

设置用户好感度（绝对值）。

python

async def set_user_favorability(
    ctx: RunContext[ToolContext],
    value: int,                        # 好感度绝对值
    user_id: Optional[str] = None,
) -> str

参数说明

参数	类型	必填	默认值	说明
`ctx`	`RunContext[ToolContext]`	是	-	工具上下文
`value`	`int`	是	-	好感度绝对值
`user_id`	`str`	否	`None`	用户ID，不填则设置当前用户

示例

python

from gsuid_core.ai_core.buildin_tools import set_user_favorability
from pydantic_ai import RunContext
from gsuid_core.ai_core.models import ToolContext

@ai_tools()
async def reset_favorability(
    ctx: RunContext[ToolContext],
    value: int = 50,
) -> str:
    """
    重置用户好感度

    Args:
        value: 重置后的好感度值，默认50
    """
    result = await set_user_favorability(ctx, value)
    return f"好感度已重置为 {value}"

update_user_favorability

更新用户好感度（相对值）。

python

async def update_user_favorability(
    ctx: RunContext[ToolContext],
    delta: int,                        # 好感度变化量
    user_id: Optional[str] = None,
) -> str

参数说明

参数	类型	必填	默认值	说明
`ctx`	`RunContext[ToolContext]`	是	-	工具上下文
`delta`	`int`	是	-	好感度变化量，可为负数
`user_id`	`str`	否	`None`	用户ID，不填则更新当前用户

示例

python

from gsuid_core.ai_core.buildin_tools import update_user_favorability
from pydantic_ai import RunContext
from gsuid_core.ai_core.models import ToolContext

@ai_tools()
async def increase_favorability(
    ctx: RunContext[ToolContext],
    amount: int = 5,
) -> str:
    """
    增加用户好感度

    Args:
        amount: 增加的好感度值，默认5
    """
    result = await update_user_favorability(ctx, amount)
    return f"好感度增加了 {amount} 点"

用户记忆

query_user_memory

查询用户记忆条数。

python

async def query_user_memory(
    ctx: RunContext[ToolContext],
    user_id: Optional[str] = None,
) -> str

参数说明

参数	类型	必填	默认值	说明
`ctx`	`RunContext[ToolContext]`	是	-	工具上下文
`user_id`	`str`	否	`None`	用户ID，不填则查询当前用户

返回值

返回用户记忆条数信息。

示例

python

from gsuid_core.ai_core.buildin_tools import query_user_memory
from pydantic_ai import RunContext
from gsuid_core.ai_core.models import ToolContext

@ai_tools()
async def check_memory(
    ctx: RunContext[ToolContext],
) -> str:
    """
    查询当前用户的记忆条数
    """
    result = await query_user_memory(ctx)
    return result

组合使用示例

示例：智能客服助手

python

from gsuid_core.ai_core.buildin_tools import (
    search_knowledge,
    send_message_by_ai,
    query_user_favorability,
)
from gsuid_core.ai_core.register import ai_tools
from pydantic_ai import RunContext
from gsuid_core.ai_core.models import ToolContext

@ai_tools()
async def smart_assistant(
    ctx: RunContext[ToolContext],
    user_question: str,
) -> str:
    """
    智能客服助手

    Args:
        user_question: 用户问题
    """
    # 1. 查询用户好感度
    favor_info = await query_user_favorability(ctx)
    
    # 2. 检索知识库
    knowledge = await search_knowledge(
        ctx,
        query=user_question,
        limit=3,
    )
    
    # 3. 根据好感度和知识库内容生成回复
    # ... AI 处理逻辑 ...
    
    response = f"根据您的提问，我找到了以下信息：\n{knowledge}"
    
    # 4. 发送消息
    await send_message_by_ai(
        ctx,
        message_type="text",
        text=response,
    )
    
    return "已回复用户"

示例：好感度奖励系统

python

from gsuid_core.ai_core.buildin_tools import (
    query_user_favorability,
    update_user_favorability,
    send_message_by_ai,
)
from gsuid_core.ai_core.register import ai_tools
from pydantic_ai import RunContext
from gsuid_core.ai_core.models import ToolContext

@ai_tools()
async def daily_check_in(
    ctx: RunContext[ToolContext],
) -> str:
    """
    每日签到，增加好感度
    """
    # 查询当前好感度
    current = await query_user_favorability(ctx)
    
    # 增加好感度
    result = await update_user_favorability(ctx, 10)
    
    # 发送通知
    await send_message_by_ai(
        ctx,
        message_type="text",
        text=f"签到成功！好感度 +10\n当前好感度：{result}",
    )
    
    return "签到完成"

注意事项

上下文传递：所有内置工具都需要 ctx 参数，确保正确传递
错误处理：建议添加 try-except 处理可能的异常
性能考虑：避免在单个工具中调用过多内置工具
用户隐私：使用涉及用户数据的工具时注意隐私保护

下一步

工具注册 - 学习如何注册自定义工具
完整示例 - 查看更多开发示例

内置工具一览 ​

概述 ​

工具导入 ​

知识库检索 ​

search_knowledge ​

参数说明 ​

返回值 ​

示例 ​

Web 搜索 ​

web_search ​

参数说明 ​

返回值 ​

示例 ​

消息发送 ​

send_message_by_ai ​

参数说明 ​

返回值 ​

示例 ​

好感度管理 ​

query_user_favorability ​

参数说明 ​

返回值 ​

示例 ​

set_user_favorability ​

参数说明 ​

示例 ​

update_user_favorability ​

参数说明 ​

示例 ​

用户记忆 ​

query_user_memory ​

参数说明 ​

返回值 ​

示例 ​

组合使用示例 ​

示例：智能客服助手 ​

示例：好感度奖励系统 ​

注意事项 ​

下一步 ​

内置工具一览

概述

工具导入

知识库检索

search_knowledge

参数说明

返回值

示例

Web 搜索

web_search

参数说明

返回值

示例

消息发送

send_message_by_ai

参数说明

返回值

示例

好感度管理

query_user_favorability

参数说明

返回值

示例

set_user_favorability

参数说明

示例

update_user_favorability

参数说明

示例

用户记忆

query_user_memory

参数说明

返回值

示例

组合使用示例

示例：智能客服助手

示例：好感度奖励系统

注意事项

下一步