gsuid_core

当用户要求"维护/开发 gsuid_core 框架本身"、"GsCore 是怎么启动的"、 "消息从进来到 AI 回复经过了哪些步骤"、"触发器是怎么匹配的"、 "handle_event / handle_ai_chat 干了什么"、"AI Session 怎么路由 / 怎么隔离"、 "工具注册表 / 渐进式工具加载 / find_tools 是怎么回事"、 "AI 为什么召不回某个插件的工具 / 工具选错插件 / 实体路由"、 "记忆没存下来 / 偏好记忆为空 / 私聊记忆 scope 不对"、 "AI 回复里出现 \<br\> / 输出文本归一化"、 "Heartbeat 定时巡检 / 免唤醒续聊怎么实现"、"记忆系统 / 偏好记忆 / 双路检索原理"、 "RAG 知识库 SQL 真值源 / 嵌入 Provider"、"定时任务 / Kanban 长任务编排"、 "启动钩子 on_core_start(_before) / init_ai_core 顺序"、"配置系统 / 配置热重载"、 "数据库基类 / @with_session / AI 表与总开关"、"帮助系统 register_help"、 "_Bot / Bot / MockBot 区别"、"网页控制台认证加密"、 "改框架要注意什么 / 有哪些已知坑"时触发此 SKILL。 凡是改动 `gsuid_core/` 框架核心（非业务插件）的任务都应优先读取此 SKILL。 面向 **GsCore（早柚核心 / gsuid-core）框架开发者与维护者**的系统级开发指南。 与「插件开发」「适配器开发」「AI Core API（给插件用）」三个 SKILL 不同，本 SKILL 讲的是**框架自身的内部实现与设计约束**：项目启动时序与两阶段钩子、插件发现/加载/ 依赖安装、配置系统（CoreConfig / PluginConfigStore / SV 配置 / 热重载）、事件处理 入口 `handler.py` 与触发器匹配、命令 vs AI 的分流、`handle_ai_chat` 全链路、 `_Bot`/`Bot`/`MockBot` 三类 Bot、AI Session 路由与隔离、Persona 系统、工具注册表与 渐进式装配（三层工具池 + Reranker 精排 + `find_tools` 动态暴露 + `visible_when`

当用户要求"部署 GsCore / gsuid_core"、"搭建早柚核心"、"把 Core 跑起来"、"Core 启动失败 / 报错"、"Core 配置 WebConsole / 网页控制台"、"连接 NoneBot2 / AstrBot / Koishi 等 Bot"、"安装 / 更新 / 卸载插件"、"切换 Git 镜像源"、"用 Docker 部署"、"挂载模式 / Bundle 模式"、"MySQL 切换"、"配置 WS_TOKEN / TRUSTED_IPS"、"公网部署"、"配置 AI 核心 启用 OpenAI 兼容 API / Tavily / 嵌入模型"、"升级 v3 到 v4"、"core 启动报错排查" "Docker 内 git 代理配置"、"WebConsole 注册码忘记"、"Core 与 Bot 不在同一台机器上" "HTTPS 与 WebConsole 加密握手" 时触发此 SKILL。 GsCore（gsuid_core）项目面向部署者的完整指南：覆盖环境与依赖检查、四种 Python 包管理器（uv / poetry / pdm / pip）的安装与启动、Docker 两种部署模式 （mount / bundle）、配置文件体系（config.json / core_config.json / ai_config.json / openai_config.json / tavily_config.json）、WebConsole 体系（含注册码 / 加密握手 / 限流）、WebSocket 安全（WS_TOKEN / TRUSTED_IPS / 失败封禁 / IP 限流）、插件管理体系（命令安装 / 手动安装 / Git 镜像源 / 自动更新）、Bot 适配器连接清单（NoneBot2 / Hoshino / AstrBot / ZeroBot / YunZai / Koishi / XYBotV2 / napcat / gs-core-adapter）、 数据库配置（SQLite 默认 / MySQL / PostgreSQL / 自定义 URL）、AI 核心部署 关键开关与外部服务（OpenAI 兼容 API / 嵌入 / Rerank / Qdrant / Tavily / Exa / MCP）、从 GenshinUID v3 迁移、故障排查清单、目录与路径速查。

当用户要求"AI Core 给插件提供了哪些 API"、"@ai_tools 装饰器怎么用"、 "category='self'/'buildin'/'common'/'media'/'default' 有什么区别"、 "怎么把已有触发器改造成 AI 工具 to_ai / MockBot / ai_return 怎么用"、 "create_agent 怎么创建临时 Agent"、"ai_entity / ai_alias / ai_image 怎么注册"、 "Persona / Memory / Scheduled Task / MCP / 嵌入 Provider 怎么调"、 "ToolContext / ToolBase / KnowledgePoint / ImageEntity 是什么类型"、 "buildin 都有哪些内置工具"、"get_registered_tools / get_all_tools 怎么查"、 "send_meme / collect_meme / understand_image / web_search 怎么用"时触发此 SKILL。 对所有「插件作者要对接 AI Core 提供的 API」的任务都应优先读取此 SKILL。 GsCore（早柚核心 / gsuid-core）`gsuid_core/ai_core/` 模块的完整 API 速查手册。 涵盖：模块导入速查（完整 import 块）、@ai_tools 装饰器签名与四种函数模式、 工具分类系统（self/buildin/common/media/default/mcp 五类 + 保底池架构图）、 触发器→AI 工具桥接（to_ai / MockBot / ai_return / send_message_by_ai 资源ID 机制）、 create_agent 临时 Agent 与 GsCoreAIAgent.run() 全部参数、知识库注册（ai_entity / add_manual_knowledge 手动知识管理）、别名注册（含 C2 scope 变更）、 图片实体注册（ai_image）、内置工具大全（self/buildin/common/media/default 几十个 工具签名 + Kanban 任务编排 + Capability Agent 能力代理）、Persona 角色系统、 Memory 记忆

当用户要求"帮我写一个 GsCore 插件"、"给这个插件加功能"、"改造触发器支持 AI"、 "怎么用 to_ai"、"注册 ai_tools"、"写一个游戏查询插件"、"插件帮助怎么注册"、 "能力代理/代理画像"、"怎么为触发器添加AI功能"、"几个触发器的差别在哪"、"数据库和配置项怎么添加" "如何把数据库表挂到网页控制台"、"PIL/htmlkit/playwright 哪个用哪个"、 "插件怎么挂自己的 HTTP 接口"、"插件怎么注册 FastAPI 路由"、 "怎么扩展 RAG 嵌入后端"、"注册自定义 Embedding Provider"时触发此 SKILL。 对所有 GsCore Bot 插件开发任务都应优先读取此 SKILL。 为 GsCore 机器人框架编写插件的完整指南。涵盖项目级目录规范（参照 ZZZeroUID / SayuStock）、 Plugins/SV 双层架构、各类触发器的语义差异（on_command vs on_prefix vs on_fullmatch vs on_keyword vs on_regex vs on_message vs on_file）、on_meta 监听平台元事件（进群 / 退群 / 戳一戳 三种标准事件）、消息收发与撤回（wait_recall / unsend）/ 禁言（ban）、数据库操作并注册到网页控制台 （site.register_admin / GsAdminModel）、订阅系统（gs_subscribe）、定时任务、配置管理、 帮助系统（register_help + get_new_help）、推荐的渲染范式（优先 PIL → htmlkit → playwright 兜底）、AI 工具集成（@ai_tools、to_ai、ai_return、create_agent）、 知识库 / 别名注册、启动钩子、to_ai 批量改造工作流、为插件挂 FastAPI 后端接口、 嵌入 Provider 注册表（插件扩展 RAG 嵌入后端）。

当用户要求"帮我写一个 GsCore 适配器"、"把 XXX 平台接入早柚核心 / gsuid-core"、 "怎么连接 core 的 WebSocket"、"MessageReceive / MessageSend 怎么填"、 "上报消息怎么写"、"core 发回来的消息怎么解析"、"base64:// 和 link:// 有什么区别"、 "按钮 / Markdown 怎么适配到我的平台"、"node 合并转发怎么处理"、"双 ID 平台 group_id 怎么拼"、 "QQ 官方 msg_id / msg_seq 时序问题"、"为什么我的命令前缀被吞了 / 没被识别"、 "适配器 token 鉴权 / 断线重连怎么写"、"log_ 日志包是什么"、 "进退群 / 戳一戳元事件怎么上报"、"wait_recall 回执 / unsend 撤回 / ban 禁言怎么在适配器实现"时触发此 SKILL。 凡是"把某个聊天平台接入 GsCore"或"调试 core 与适配器之间通信"的任务都应优先读取此 SKILL。 为 GsCore（早柚核心 / gsuid-core）机器人框架编写**平台适配器**的完整指南。适配器是运行在 Bot 平台一侧、通过 WebSocket 与 core 通信的连接器（区别于运行在 core 内部的"插件"）。 涵盖：早柚协议总览与二进制帧、三类数据结构（Message / MessageReceive / MessageSend / Button）、 bot_id 的三层语义（路由 ID / 平台 ID / bot_self_id）、连接生命周期（token 鉴权 / 心跳 / 断线重连 / 收发双协程骨架）、上报消息（平台→core，每种 content 类型如何构造、user_pm 映射、is_tome 机制、 命令前缀处理）、发送消息（core→平台，recv 循环按 bot_id 路由、每种 type 的落地处理）、 base64:// 与 link:// 双形态图片处理、按钮与 Markdown 跨平台映射、node 合并转发、双 ID 平台 （villa / heybox）、QQ 官方时序、回调按钮上报、log_ 日志包、元事件上报（user_join_group / user_exit_group / poke 三种标准事件）、echo 撤回回执、撤回 / 禁言控制包、