gscore-plugin-development

name

gscore-plugin-development

description

当用户要求"帮我写一个 GsCore 插件"、"给这个插件加功能"、"改造触发器支持 AI"、 "怎么用 to_ai"、"注册 ai_tools"、"写一个游戏查询插件"、"插件帮助怎么注册"、 "能力代理/代理画像"、"怎么为触发器添加AI功能"、"几个触发器的差别在哪"、"数据库和配置项怎么添加" "如何把数据库表挂到网页控制台"、"PIL/pytakumi/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 → pytakumi → 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、资源路径、meta plugin、ruff / .vscode）	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 / @with_read_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 → pytakumi → playwright；AI 资料图走 render_chart_spec）	references/09-image-rendering.md
十	AI 集成：to_ai 与 ai_return（优先方案）	references/10-ai-to-ai-and-ai-return.md
十一	AI 集成：@ai_tools（含 covers/aliases；仅纯 AI 内部工具）	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 集成：能力代理（AgentNode）Cookbook + render_agent / 业务节点（如 stock_report）+ 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 兜底、Any、同步阻塞函数）	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. 加数据库表：看 五、数据库操作；纯 SELECT 用 @with_read_session，写入仍用 @with_session；要可视化后台看 §5.5，要给已部署用户补字段看 §5.7。
5. 加定时推送：看 六、定时任务与订阅 的 gs_subscribe 强制规范。
6. 加启动逻辑：在 七、生命周期钩子 选合适的钩子。
7. 加帮助 / 状态：看 八、帮助系统注册。
8. 画图：参考 九、图片渲染范式 的"决策口诀"选 PIL / pytakumi / playwright。
9. 想被 AI 调用：
   • 命令同时也是用户命令 → 十、 与

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

• 嵌套加载：外层 __init__.py + 外层 __nest__.py（空文件） + 内层 __init__.py 声明 Plugins(...) + 内层 __full__.py（空文件）。详见 一、插件基础结构 §1.2。
• 基础设施插件（meta plugin）：[tool.gsuid] kind = "meta" + 内层 api/。别人硬依赖 from gscore_mail.api import send；软依赖先 import_api("gscore_mail") 再同样 import。不要 try/except，不要改 Core 去声明对方的类型。详见 §1.6。
• 每个插件自带 Ruff / .vscode：插件常被单独打开，读不到 Core 根配置。根目录放 ruff.toml + .vscode/extensions.json + .vscode/settings.json（extraPaths 指到 Core 仓库根）。详见 §1.7。
• 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。

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

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

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

• AI Agent 总架构：docs/AI_AGENT_ARCHITECTURE.md
• AI 触发流程 / 框架开发：.agents/skills/gscore-development/SKILL.md
• AGENTS.md（代码红线）：仓库根目录 AGENTS.md
• AI Core API（给插件用）：gscore-ai-core-api；MCP Server 钩子见 §11.1.7
• WebConsole 后端 API 设计：gsuid_core/webconsole/docs/README.md