gscore-development

name

gscore-development

description

当用户要求"维护/开发 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` 条件 隐藏）、Heartbeat 定时巡检与免唤醒续聊、定时任务与 Kanban 长任务/能力代理、记忆系统 （双路检索 / Scope 隔离 / 摄入 / 分层图 / 偏好记忆 / RF-Mem / 生命周期 / 多模态）、 RAG 知识库（SQL 真值源 + 对账 + 过滤下推）与嵌入 Provider、统计系统、网页控制台 API 与认证加密、数据库基类与 AI 表 / 总开关、帮助系统，以及一份**已知坑与开发注意事项** 清单（D-1~D-22 历史缺陷 + 续聊/偏好/多进程/事件循环等踩坑点）。

GsCore 框架开发与维护指南（核心入口）

本 SKILL 面向框架本身的开发者 / 维护者，描述 gsuid_core/ 的系统结构、触发器与 事件流转、AI 子系统、数据库 / 配置 / 帮助系统，以及后续开发必须注意的约束与坑点。 目标：让不熟悉本项目的人也能安全地改框架，不踩历史上踩过的坑。

内容按章节拆分为「主入口 + references/ 子文档」。需要某专题细节时，顺着下表的相对 路径按需 Read 对应文件，不要一次性把所有内容塞进上下文。源码永远是唯一事实源， 本 SKILL 是导航与设计意图说明；改动核心后请同步更新对应章节。

谁该读这个 SKILL（与其他 SKILL 的分工）

你的任务	该读的 SKILL
改框架核心（handler / ai_core / 启动 / 配置 / 数据库基类 / webconsole）	本 SKILL
写一个业务插件（命令 / 数据库表 / 配置 / 帮助 / 接 AI）	gscore-plugin-development
查 AI Core 给插件暴露了哪些 API（签名 / 类型）	gscore-ai-core-api
写一个平台适配器（OneBot / 协议对接）	gscore-adapter-development
部署 / 运维 Core（安装 / 启动 / 配置文件 / Docker）	gscore-deploy

文档目录索引

章节	主题	链接
一	架构与模块全景（ai_core/ 目录结构、核心组件关系、消息→AI 的总链路）	references/01-architecture-and-modules.md
二	启动时序与生命周期钩子（core.py::main、两阶段 hook、init_ai_core 顺序、关闭钩子、AI 总开关、Web 服务启动）	references/02-startup-lifecycle.md
三	插件加载与配置系统（发现/分类/meta plugin 两阶段 import/依赖合并安装/cached_import、CoreConfig/PluginConfigStore/SV 配置、配置热重载矩阵）	references/03-plugin-loading-and-config.md
四	事件处理与触发器流转（handle_event 13 步、触发器匹配、命令 vs AI 分流、AI 触发条件、长度/并发防护）	references/04-event-trigger-flow.md
五	Bot 三类（_Bot 底层 / Bot 高层 / MockBot AI 代理、连接管理与 5 分钟重连复用、发送队列串行化）	references/05-bot-classes.md
六	AI Session 路由与 Persona（ai_router、前缀缓存红线 / 保头裁中段、Persona 热重载）	references/06-ai-session-and-persona.md
七	工具注册表与 Agent 装配（@ai_tools/covers/aliases、L0 实体路由、find_tools 分流、节点语义路由、输出闸、render_chart_spec series+图例、in_flight_short）	references/07-tool-registry-and-agent.md
八

推荐阅读顺序（按需跳转）

1. 第一次接触框架：先看 一、架构与模块全景 建立心智模型，再看 二、启动时序 搞清"东西是按什么顺序起来的"。
2. 改消息处理 / 触发逻辑：看 四、事件与触发器流转；碰 Bot 发送 / 连接看 五、Bot 三类。
3. 改 AI 链路：先 六、Session 与 Persona → 七、工具注册与 Agent 装配 → 按需 八、主动发言/编排 / 九、记忆 / 十、RAG。
4. 加配置 / 加启动逻辑 / 加数据库表 / 加帮助：看 三、插件加载与配置 与 十一、统计/控制台/数据库/帮助。
5. 动手前必读：十二、已知坑与注意事项——这一章是"别人替你踩过的坑"，改框架前过一遍能省大量返工。

关键概念速记（先看这一段再决定读哪一章）

• 单进程事件循环：Core 是 FastAPI + WebSocket + APScheduler 的单进程服务。大量状态（续聊窗口、工具轨迹、认证密钥、Bot 实例、Session 注册表、记忆队列）是进程内存，多进程水平扩展会状态不共享。详见 §12。
• Windows 事件循环：core.py 不设置事件循环策略，Windows 上跑的是 Python 默认的 ProactorEventLoop，asyncio.create_subprocess_exec 可用。Proactor 关 socket 的 InvalidStateError 改由 core.py 顶层 except 兜底，不再切 Selector。代码里遗留的「Windows 走同步 subprocess.run」分支是历史产物，冗余但无害。写新代码直接用 asyncio 子进程；要兜底用 except NotImplementedError 而不是判平台。（2026-08-14 更正了此前「切到 SelectorEventLoop 故不支持子进程」的过期描述。）详见 §12.3。
• 两阶段启动钩子：on_core_start_before（WS 启动前阻塞执行，做 DB 迁移/建表/Schema 升级）vs on_core_start（WS 启动后后台异步，不阻塞连接）。AI 子系统统一收敛到 ai_core/startup.py::init_ai_core 一个钩子，按 _INIT_STEPS 顺序串行。详见 §02。
• AI 总开关贯穿全链路：ai_config.get_config("enable").data 在 handle_ai 内函数级动态读取（切换无需重启）；每个 _init_* 与定时任务执行前都检查总开关；关闭时 create_core_tables 跳过建 AI 表。改 AI 模块时务必保留这个检查。详见 §02、§12。
• 命令优先于 AI：handle_event 先匹配 SL.lst 触发器，有命令匹配走触发器、无匹配才落入 AI。权限不足（user_pm > sv.pm）的命令会"不匹配"从而落到 AI（AI 调同名 to_ai 工具时会再做一次权限检查）。详见 §04。
• Session ID 群聊不含 user_id：群聊 …:group:{group_id}、私聊 。群内所有用户共享同一 Session 与记忆，避免"群里每个人各聊各的"。 群聊时把 置空保证同群共享 deque。详见 。

关联文档（同仓库其他位置）

• 代码红线与类型规范：仓库根目录 AGENTS.md（改任何代码前必读）
• 一条消息完整生命周期（Agent loop 时序）：docs/AI_AGENT_LIFECYCLE_SEQUENCE.md
• Takumi / HTML 出图约束：docs/TAKUMI_HTML_GUIDE.md
• 插件开发工作流：.agents/skills/gscore-plugin-development/SKILL.md
• AI Core API（给插件用）：.agents/skills/gscore-ai-core-api/SKILL.md
• 适配器开发：.agents/skills/gscore-adapter-development/SKILL.md
• 部署运维：.agents/skills/gscore-deploy/SKILL.md
• WebConsole 后端文档：gsuid_core/webconsole/docs/