gscore-plugin-development

name

gscore-plugin-development

description

当用户要求"帮我写一个 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 插件开发完整指南（核心入口）

本 SKILL 已按章节拆分为主入口 + references/ 子文档的形式组织。Agent 在需要某专题细节时， 顺着下文的相对路径按需 ViewFile / ReadFile 加载对应文件，不要一次性把所有内容塞进上下文。

文档目录索引

章节	主题	链接
一	插件基础结构（目录、命名、入口三件套、Plugins vs SV、pyproject、资源路径）	references/01-plugin-basics.md
二	SV 与触发器（SV 实例、八种触发器语义对比、装饰器通用参数、签名规范）	references/02-sv-and-triggers.md
三	消息收发（Event 属性、bot.send 各种形态、send_option、多步会话）	references/03-messaging.md
四	配置管理（CONFIG_DEFAULT、StringConfig、所有配置类型）	references/04-config-management.md
五	数据库操作（SQLModel 基类、@with_session、async_maker、注册到 Web 控制台、exec_list 自动迁移）	references/05-database.md
六	定时任务与订阅（APScheduler、gs_subscribe 全套 API）	references/06-scheduler-and-subscribe.md
七	启动 / 关闭 / Bot 上线钩子（4 类钩子的区别与适用场景）	references/07-lifecycle-hooks.md
八	帮助系统注册（register_help、get_new_help、register_status）	references/08-help-system.md
九	图片渲染范式（PIL → htmlkit → playwright 三档）	references/09-image-rendering.md
十	AI 集成：to_ai 与 ai_return（优先方案）	references/10-ai-to-ai-and-ai-return.md
十一	AI 集成：@ai_tools 装饰器（仅当函数不暴露为用户命令时使用）	references/11-ai-tools-decorator.md
十二	AI 集成：知识库（ai_entity）与别名（ai_alias）注册	references/12-ai-knowledge-and-alias.md
十三	AI 集成：create_agent（临时专用 AI Agent）	references/13-ai-create-agent.md
十四	AI 集成：能力代理画像（CapabilityAgentProfile） + 框架自带 plugin_developer_agent	references/14-ai-capability-profile.md
十五	完整插件示例（MyGameUID 端到端）	references/15-full-plugin-example.md
十六	常用工具模块速查（get_res_path / send_msg_to_master / error_reply / 限流 / 缓存 / 字体 / to_thread / cache_data / 批量播报 / 常用 import）	references/16-common-utilities.md
十七	代码规范红线（禁止 try/except 兜底、cast、type:ignore、getattr/dict.get 兜底、同步阻塞函数）	references/17-code-redlines.md
十八	to_ai 批量改造工作流（背景、Step 0~4、完整股票 / 游戏示例、质量检查清单、Q&A）	references/18-ai-trigger-migration.md
十九	为插件挂 FastAPI 后端接口（共享 app、鉴权、CRUD、命名规范、反模式）	references/19-fastapi-plugin-api.md
二十	嵌入 Provider 注册表（插件扩展 RAG 嵌入后端：懒 import、工厂模式、降级策略）	references/20-embedding-provider-registry.md
二十一	AI 集成：在插件 repo 内管理 AI Skill（ai_skill 注册目录式 SKILL.md + 脚本/资源）	references/21-ai-skill-registration.md

推荐开发流程（按需跳转）

1. 新建插件：先看 一、插件基础结构 确定目录与命名，参考 十五、完整插件示例 起步。
2. 加命令：看 二、SV 与触发器 选合适触发器，按 三、消息收发 写发送 / 多步会话；要监听进群/退群/戳一戳用 on_meta（§2.6），要撤回/禁言看 §3.5。
3. 加配置：看 四、配置管理 定义 CONFIG_DEFAULT 与 StringConfig。
4. 加数据库表：看 五、数据库操作；要可视化后台看 §5.5，要给已部署用户补字段看 §5.7。
5. 加定时推送：看 六、定时任务与订阅 的 gs_subscribe 强制规范。
6. 加启动逻辑：在 七、生命周期钩子 选合适的钩子。
7. 加帮助 / 状态：看 八、帮助系统注册。
8. 画图：参考 九、图片渲染范式 的"决策口诀"选 PIL / htmlkit / playwright。
9. 想被 AI 调用：
   • 命令同时也是用户命令 → 十、to_ai 与 ai_return （优先）
   • 纯数据 / 内部工具 → 十一、@ai_tools 装饰器
   • 知识库 / 别名 → 十二、知识库与别名注册
   • 临时 Agent 子任务 → 十三、create_agent
   • 业务专业代理 → 十四、能力代理画像
   • 随插件分发 Markdown「技能」（SKILL.md + 脚本/资源，模型 list_skills/run_skill_script 调用）→ 二十一、AI Skill 注册
   • 批量改造已有触发器支持 AI → 十八、to_ai 批量改造工作流
10. 挂自己的 HTTP 后端接口：看 十九、FastAPI 插件 API——复用 gsuid_core.webconsole.app_app.app，3 行加一个接口。
11. 扩展 RAG 嵌入后端：看 二十、嵌入 Provider 注册表——用 register_embedding_provider 注册 sentence_transformers / llama.cpp embedding 等自定义 Provider，懒 import + 工厂模式，自动出现在 WebConsole 下拉选项。
12. 遇到 API 缓存 / 限流 / 字体 / 错误码 / 推主人 / 批量播报 等问题：直接看 十六、常用工具模块速查。
13. 写完代码：用 十七、代码规范红线 自查（try/except、cast、type:ignore、getattr 兜底、同步阻塞函数全部禁止）。

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

• 嵌套加载：外层 __init__.py + 外层 __nest__.py（空文件） + 内层 __init__.py 声明 Plugins(...) + 内层 __full__.py（空文件）。详见 一、插件基础结构 §1.2。
• Plugins vs SV：插件级 vs 服务模块级；SV 自动从调用栈推断归属。详见 §1.3。
• 触发器选择：on_command（推荐默认）vs on_prefix（强制带参）vs on_fullmatch（精确匹配）vs on_keyword（污染消息流，慎用）vs on_regex（复杂结构）vs on_file / on_message（特殊）。详见 §2.2。
• 监听平台事件用 on_meta：标准元事件仅三种——user_join_group / user_exit_group / poke，data 字段跨平台统一（适配器侧已归一），可放心监听；其他事件不做适配。触发器内用 ev.get_meta(key) 读字段；与命令路径双向隔离。详见 §2.6。
• 撤回 / 禁言：bot.send(..., wait_recall=True) 返回出站 id 列表（Optional[List[str]]），配 bot.unsend(...) 撤回；bot.ban(user_id, group_id, duration) 禁言（duration=0 解禁）。三者 HTTP 模式不支持。详见 §3.5。
• to_ai vs @ai_tools 二选一：同一函数不可同时用。命令也允许用户直接触发 → to_ai；纯 AI 内部工具 → @ai_tools。详见 §10 顶部警告 与 §11 顶部警告。
• 主动推送必须用 gs_subscribe：不要 for bot in gss.active_bot.items(): await bot.target_send(...) 硬塞群号。详见 §6.2。
• 数据库 Schema 变更用 exec_list：放在 on_core_start_before 阶段执行。详见 §5.7。
• 唯一允许 try/except 的地方：_ai_return_xxx() 辅助函数。详见 §17.3。
• 图片渲染优先级：PIL（首选）→ htmlkit（推荐）→ playwright（兜底）。详见 §9.1。
• 能力代理 prompt 必须拼 _DELIVERY_BOUNDARY：否则画像会绕过主人格直接发消息。详见 §14.4。
• to_ai 改造三层：触发器层 to_ai="..." + 数据/渲染层 ai_return() + 业务画像 CapabilityAgentProfile；详见 §18.1 与 §18.3 Step 0.4。
• ai_return 注入点 = 数据已拿到 / 图片未生成：必须在数据层函数里，不能只在触发器层。详见 §18.3 Step 3。
• 插件 FastAPI = 共享 app + Depends(require_auth)：从 gsuid_core.webconsole.app_app import app 即可挂自己的 /api/<插件名>/... 路由；详见 §19.2 与 §19.3。
• 嵌入 Provider 注册 = 懒 import + 工厂模式：插件 __init__.py 顶层调用 register_embedding_provider 注册 EmbeddingProviderEntry，重依赖只能在 factory 内部 import；注册时序保证早于消费；配置指向的 Provider 不可用时框架自动降级回 local 并记录 error，不会导致 AI 核心整体不可用。详见 §20。
• AI Skill 随插件走 = ai_skill(目录)：插件 __init__.py 顶层一行 ai_skill(Path(__file__).parent / "skills") 即把 repo 内 skills/<name>/SKILL.md（+ 脚本/资源）注册为运行时技能，无需挪进 data/ai_core/skills/；webconsole 内标记 source="plugin" 且只读。注意「运行时 Skill」≠「docs/skills 开发文档 skill」。详见 §21。

关联文档（本 SKILL 文件夹内）

• 触发器 → AI 迁移工作流：§18、to_ai 批量改造
• 插件挂后端 API：§19、FastAPI 插件 API
• 嵌入 Provider 注册：§20、嵌入 Provider 注册表

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

• AI Agent 总架构：docs/AI_AGENT_ARCHITECTURE.md
• AI 触发流程 / 框架开发：docs/skills/gscore-development/SKILL.md
• LLM.md（Bot 内部连接管理红线）：仓库根目录 docs/LLM.md
• AI Core API（给插件用）：docs/ai_core_api_for_plugins.md
• WebConsole 后端 API 设计：gsuid_core/webconsole/docs/README.md