早柚核心Docs

外观

别名注册 ​

字数统计:1.5k 字
阅读时长:5 分钟

💡 提醒

让 AI 听懂"黑话"！本章教你如何让 AI 理解玩家的各种叫法——从"雷神"到"将军"，从"公子"到"鸭鸭"。

适合场景：

  • 🎭 游戏角色有多个昵称（如"雷电将军"也叫"雷神"、"影"）
  • 🗣️ 玩家社区有特定的简称或梗（如"椰羊"指甘雨）
  • 📝 命令有多个等价说法（如"查询"和"查"）
  • 🌐 需要支持中英文混合称呼

生动比喻：别名系统就像是给 AI 配备了一本"俚语词典"。没有它，AI 只会死板地匹配标准名称；有了它，AI 就能理解玩家说的"雷军"其实是指"雷电将军"！

本文档介绍如何使用 ai_alias 为实体名称注册别名，提升 AI 对用户输入的理解能力。

概述 ​

ai_alias 函数允许插件开发者为实体名称注册一个或多个别名。当用户使用别名时，AI 能够识别并映射到标准名称，提高交互的自然性和准确性。

入口函数 ​

python
from gsuid_core.ai_core.register import ai_alias

函数签名 ​

python
def ai_alias(name: str, alias: Union[str, List[str]]) -> None

参数说明 ​

参数类型必填说明
namestr是标准名称
aliasstr | List[str]是别名（单个或列表）

基础示例 ​

单个别名 ​

python
from gsuid_core.ai_core.register import ai_alias

# 为 "雷电将军" 注册别名 "雷神"
ai_alias("雷电将军", "雷神")

多个别名 ​

python
from gsuid_core.ai_core.register import ai_alias

# 为 "雷电将军" 注册多个别名
ai_alias("雷电将军", ["雷神", "将军", "影", "巴尔泽布"])

应用场景 ​

场景一：游戏角色别名 ​

python
from gsuid_core.ai_core.register import ai_alias

def register_character_aliases():
    # 原神角色
    ai_alias("雷电将军", ["雷神", "将军", "影", "巴尔泽布", "雷军"])
    ai_alias("钟离", ["岩神", "帝君", "摩拉克斯", "老爷子"])
    ai_alias("温迪", ["风神", "巴巴托斯", "卖唱的"])
    ai_alias("纳西妲", ["草神", "小吉祥草王", "小草神", "纳西达"])
    ai_alias("芙宁娜", ["水神", "芙芙", "芙卡洛斯"])
    
    # 崩坏：星穹铁道角色
    ai_alias("黄泉", ["芽衣", "雷电芽衣"])
    ai_alias("砂金", ["卡卡瓦夏"])
    ai_alias("知更鸟", ["罗宾", "robin"])

场景二：游戏道具别名 ​

python
from gsuid_core.ai_core.register import ai_alias

def register_item_aliases():
    # 原神材料
    ai_alias("原石", ["石头", "抽卡石", "创世结晶"])
    ai_alias("摩拉", ["金币", "钱", "mora"])
    ai_alias("纠缠之缘", ["粉球", "粉球球", "限定抽"])
    ai_alias("相遇之缘", ["蓝球", "蓝球球", "常驻抽"])

场景三：功能命令别名 ​

python
from gsuid_core.ai_core.register import ai_alias

def register_command_aliases():
    # 功能别名
    ai_alias("角色信息", ["角色面板", "角色数据", "人物信息"])
    ai_alias("抽卡记录", ["抽卡历史", "gacha记录", "祈愿记录"])
    ai_alias("深渊战绩", ["螺旋战绩", "深境螺旋", "abyss记录"])

场景四：插件名称别名 ​

python
from gsuid_core.ai_core.register import ai_alias

# 在插件初始化时注册
def on_init():
    # 为插件名称注册别名
    ai_alias("GenshinUID", ["原神UID", "原神插件", "genshin"])
    ai_alias("StarRailUID", ["星铁UID", "崩铁插件", "starrail"])

完整示例 ​

python
# my_plugin/aliases.py

from gsuid_core.ai_core.register import ai_alias

def register_all_aliases():
    """注册所有别名"""
    
    # 角色别名
    _register_character_aliases()
    
    # 道具别名
    _register_item_aliases()
    
    # 命令别名
    _register_command_aliases()

def _register_character_aliases():
    """注册角色别名"""
    characters = {
        "丝柯克": ["skk", "斯柯克", "SKK", "师傅"],
        "达达利亚": ["公子", "鸭鸭", "阿贾克斯", "鲸鱼"],
        "胡桃": ["堂主", "胡堂主", "桃子"],
        "甘雨": ["椰羊", "王小美", "秘书"],
        "神里绫华": ["绫华", "白鹭公主", "龟龟"],
        "宵宫": ["烟花", "夏祭的女王"],
    }
    
    for name, aliases in characters.items():
        ai_alias(name, aliases)

def _register_item_aliases():
    """注册道具别名"""
    items = {
        "圣遗物": ["遗物", "装备", "artifact"],
        "武器": ["兵器", "weapon"],
        "天赋材料": ["技能材料", "天赋书"],
        "突破材料": ["升级材料", "突破素材"],
    }
    
    for name, aliases in items.items():
        ai_alias(name, aliases)

def _register_command_aliases():
    """注册命令别名"""
    commands = {
        "查询体力": ["查体力", "体力查询", "树脂查询"],
        "查询委托": ["查委托", "每日委托", "日常查询"],
        "查询宝箱": ["查宝箱", "探索度", "宝箱统计"],
    }
    
    for name, aliases in commands.items():
        ai_alias(name, aliases)

# 在插件初始化时调用
# register_all_aliases()

最佳实践 ​

1. 别名策略 ​

python
# 好的别名应该覆盖用户的常见叫法
ai_alias("雷电将军", [
    "雷神",           # 常见简称
    "将军",           # 昵称
    "影",             # 真名
    "巴尔泽布",       # 魔神名
    "雷军",           # 网络梗
])

2. 分组管理 ​

python
# 按类别分组管理别名
def register_aliases():
    _register_mondstadt_characters()  # 蒙德角色
    _register_liyue_characters()      # 璃月角色
    _register_inazuma_characters()    # 稻妻角色
    _register_sumeru_characters()     # 须弥角色
    _register_fontaine_characters()   # 枫丹角色

3. 动态别名 ​

python
# 根据数据动态生成别名
def register_dynamic_aliases(characters: list[dict]):
    for char in characters:
        name = char["name"]
        aliases = char.get("aliases", [])
        if aliases:
            ai_alias(name, aliases)

注意事项 ​

  1. 唯一性：标准名称应该是唯一的，避免重复注册
  2. 覆盖范围：别名应该覆盖用户的常见叫法，包括：
    • 简称（如 "雷神"）
    • 昵称（如 "将军"）
    • 真名（如 "影"）
    • 音译（如 "Raiden"）
    • 网络梗（如 "雷军"）
  3. 避免冲突：不同实体的别名不应该冲突
  4. 及时更新：随着游戏版本更新，及时添加新别名

与知识库结合使用 ​

别名通常与知识库配合使用，提升 AI 的理解能力：

python
from gsuid_core.ai_core.register import ai_alias, ai_entity
from gsuid_core.ai_core.models import KnowledgePoint

# 注册别名
ai_alias("雷电将军", ["雷神", "将军", "影"])

# 注册知识库
ai_entity(KnowledgePoint(
    id="character_raiden",
    plugin="Genshin",
    title="雷电将军 - 角色介绍",
    content="""
    # 雷电将军
    
    ## 角色信息
    - 元素: 雷
    - 武器: 长枪
    - 命之座: 万世之座
    
    ## 技能介绍
    ...
    """,
    tags=["原神", "雷电将军", "雷神", "角色"],
))

这样，当用户说 "雷神怎么培养" 时，AI 能够：

  1. 通过别名识别 "雷神" = "雷电将军"
  2. 通过知识库检索到雷电将军的培养攻略

下一步 ​