gscore-ai-core-api

name

gscore-ai-core-api

description

当用户要求"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 怎么调"、 "register_mcp_token_verifier / event_enricher / export_filter 怎么用"、 "MCP Server 怎么鉴权 / 过滤导出工具 / 补 Event 会话字段"、 "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 记忆系统（双路检索 / observe / 摄入 worker）、Scheduled Task 定时任务 数据模型、工具注册表查询 API（get_registered_tools / get_all_tools / ToolBase）、 全部类型定义（ToolContext / KnowledgeBase / KnowledgePoint / ManualKnowledgeBase / ImageEntity / ToolBase / CheckFunc）、MCP 工具集成（Client/Config/ToolID 格式/ call_mcp_tool、MCP Server 插件钩子 token/enricher/export filter）、Image Understand 图片理解、Web Search 统一搜索、Meme 表情包 模块、嵌入 Provider 注册表、3 个完整示例 + 6 条常见问题。 与 `gscore-plugin-development` 的区别：该 SKILL 讲「怎么写一个插件并接 AI」， 本 SKILL 讲「AI Core 给插件暴露了哪些 API 可调用、各个 API 的完整签名/参数/ 返回值是什么」。前者是工作流指南，后者是参考手册。

GsCore AI Core 插件开发者 API 速查手册（核心入口）

本 SKILL 是 docs/ai_core_api_for_plugins.md 的拆分版本。 原文件是 2700+ 行的单文档，按章节拆分为「主入口 + references/ 子文档」的形式。 Agent 在需要某专题细节时，顺着下文的相对路径按需 ReadFile 加载对应文件，不要 一次性把所有内容塞进上下文。

文档目录索引

章节	主题	链接
一	模块导入速查（工具注册 / 触发器桥接 / Agent / MCP / 嵌入 / Persona / Memory / 内置工具 / RAG 完整 import 块）	references/01-import-cheatsheet.md
二	@ai_tools 装饰器（签名、covers/aliases 检索面、四种模式、check_func、返回值）	references/02-ai-tools-decorator.md
三	工具分类系统（_TOOL_REGISTRY 内部结构、保底池概念、Agent 调用架构、插件分类建议）	references/03-tool-categories.md
四	触发器 → AI 工具桥接（to_ai / ai_return / MockBot / send_message_by_ai / 资源ID RM 机制 / 权限检查）	references/04-trigger-bridge.md
五	create_agent 与 Agent 架构（create_agent 签名、GsCoreAIAgent.run() 全参数、get_main_agent_tools、handle_ai_chat）	references/05-create-agent.md
六	知识库与别名注册（ai_entity / add_manual_knowledge 手动知识管理 / ai_alias 含 C2 scope / ai_image 图片实体）	references/06-knowledge-and-alias.md
七	内置工具大全（含 search_cognition 路径卡 / attach_article / render_chart_spec / web 时效 + Kanban + 能力代理 + self_model）	references/07-builtin-tools.md
八	Persona 角色系统 + Memory 记忆系统（Persona 类、build_persona_prompt、memory_config / / ）

推荐查阅流程（按需跳转）

1. 第一次接 AI Core，先看导入速查：一、模块导入速查 把所有 from gsuid_core.ai_core.xxx import ... 的入口列全，按需复制。
2. 要写 AI 工具：先看 二、@ai_tools 装饰器 搞清签名 + 函数模式；选 category 之前必读 三、工具分类系统（self/buildin/common/media/default 保底池加载机制）。
3. 要把现有触发器改造成 AI 工具：看 四、触发器桥接，特别注意 MockBot 的拦截规则与 send_message_by_ai 资源ID 机制。
4. 要写临时 Agent / 子任务：看 五、create_agent。
5. 要注册知识 / 别名 / 图片：看 六、知识库与别名。
6. 要查所有内置工具的签名：看 七、内置工具大全。
7. 要碰 Persona / Memory / 定时任务：分别看 八、Persona + Memory 与 九、Scheduled Task。
8. 要查类型 / 反射工具注册表：看 十、注册表 + 类型。
9. 要接 MCP / 图片理解 / 网络搜索 / 网页抓取 / 表情包：看 十一（§11.1.7 MCP Server 插件钩子、§11.3 搜索多源、§11.3b 抓取）。
10. 要扩展 RAG 嵌入后端：看 十二、嵌入 Provider。
11. 要参考端到端示例或 FAQ：看 十三、完整示例 + FAQ。

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

• AI Core 入口模块统一前缀：gsuid_core.ai_core.*，包括 register / trigger_bridge / gs_agent / output_gate / buildin_tools / rag / mcp / persona / memory / agent_node / approval / handle_ai 等。详见 §1、§7。
• 多项出图：create_subagent(agent_profile="render_agent")；render_* 在 media，不在主人格 buildin 保底。业务长报告用插件能力代理 + 出图工具（见 gscore-plugin-development §14）。
• Agent 发话合规：插件一般不直接调 pre_send_gate；改 send_message_by_ai 或新增「模型台词出站」路径时须过 tool_gate_feedback / 主循环闸。见 gscore-development §7.12。
• @ai_tools 是入口装饰器：必须 async；三种上下文模式；Bot/Event 自动注入不暴露给 LLM。 检索面 = name + docstring + covers + aliases（须领域前缀）。详见 §2。
• category 决定加载方式：self / buildin 是框架保底工具池（无条件全部加载进主Agent，不受向量搜索影响）；common / media / mcp / 自定义分类是向量检索按需加载；default 是子Agent 工具（需通过 create_subagent 调用）。详见 §3.2。
• 保底池由 category 决定，无硬编码名单：get_main_agent_tools() 把 + 两个分类下的全部工具无条件加载；插件若希望某工具成为主 Agent 保底工具，注册时用 即可。详见 。

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

• 插件开发工作流指南：.agents/skills/gscore-plugin-development/SKILL.md
• 适配器开发指南：.agents/skills/gscore-adapter-development/SKILL.md
• AI Agent 总架构：docs/AI_AGENT_ARCHITECTURE.md
• AI 触发流程 / 框架开发：.agents/skills/gscore-development/SKILL.md
• AI Session Logging：docs/AI_SESSION_LOGGING.md
• 记忆系统详细：docs/MEMORY_SYSTEM.md
• 召回与元事件：docs/RECALL_AND_META_EVENTS.md
• AGENTS.md（代码红线）：仓库根目录 AGENTS.md
• 原单文件版（被本 SKILL 取代）：docs/ai_core_api_for_plugins.md