人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载本篇技术指南介绍 AIRI 仓库中的satori-bot集成模块它以 Satori 协议 为统一消息层借助 Koishi 的server-satori插件与 OpenAI 兼容 LLM 接口让 AIRI 的赛博灵魂同时接入 QQ、Telegram、Discord、Lark 等多个消息平台。读完本文你将掌握该模块的完整部署流程、环境变量语义、事件驱动 自主循环的底层运行机制以及其状态持久化与并发控制设计能够独立完成配置、启动与二次排障。模块定位过渡性的独立 Mini-Core 与未来演进satori-bot 位于 integrations/satori-bot是一个独立standalone、事件驱动的 AI 机器人实现。它的核心定位需要先讲清楚当前实现模块内部自带一套Mini-Coresrc/core/包含事件循环、调度器与规划器逻辑用于模拟未来 AIRI Core 的行为。仓库 README 与文档均明确声明这只是过渡性实现适合实验与维护不应视为稳定的 AIRI Core 集成。保留组件src/core/dispatcher.ts动作分发器与基于 PGlite 的数据库层src/lib/db.ts是会被保留的部分未来将作为工具型模块暴露给 AIRI Core用于动作执行与状态持久化。未来迁移一旦主框架稳定src/core/中的循环/规划逻辑将被移除本模块将重构为严格的AdapterSatori 协议处理 Capability Provider动作提供把认知循环交给主 AIRI 进程。这一边界决定了你可以放心用它做多平台接入实验但不要把它当作 AIRI 的最终认知架构。从目录结构看模块的代码路径划分非常清晰详见 integrations/satori-bot/README.mdLoop 与逻辑临时integrations/satori-bot/src/core/Adapter保留integrations/satori-bot/src/adapter/satori/Capabilities保留integrations/satori-bot/src/capabilities/文档integrations/satori-bot/docs/含HANDLER.md、PERSISTENCE.md、PROMPTS.md、EVENT.md四份内部说明快速开始三步跑通多平台接入前置准备部署前需要满足三个条件依赖安装在仓库根目录执行pnpm i安装全部依赖项目使用 pnpm workspace需 Node.js ≥ 18 与 pnpm ≥ 8。Koishi 实例运行一个启用了server-satori插件的 Koishi 实例它负责把 QQ、Telegram、Discord、Lark 等平台的适配器桥接为统一的 Satori 协议端点。模型服务准备一个 OpenAI 兼容 API 的 LLM 服务如 Ollama、vLLM、DeepSeek 等README 中列举为典型选项。配置环境变量复制示例配置为本地配置文件cp integrations/satori-bot/.env integrations/satori-bot/.env.local然后编辑integrations/satori-bot/.env.local填写 Satori 连接信息与 LLM 信息。完整的变量语义如下表以 .env 示例 与 config.ts 实现 为准变量必填默认值说明SATORI_WS_URL否ws://localhost:5140/satori/v1/eventsKoishiserver-satori的 WebSocket 事件推送地址SATORI_API_BASE_URL否http://localhost:5140/satori/v1Satori REST API 基地址若未设置客户端会从 WS 地址推导将ws://换成http://、去掉/v1/eventsSATORI_TOKEN否空Koishi 端鉴权 token若 Koishi 关闭了鉴权可留空LLM_API_KEY是—OpenAI 兼容 API 的密钥LLM_API_BASE_URL是—OpenAI 兼容 API 的基地址LLM_MODEL是—模型名如gpt-4LLM_OLLAMA_DISABLE_THINK否false是否禁用模型思考true/1视为开启用于 Ollama 等带思考链的模型DB_PATH否../../data/pglite-dbPGlite 本地数据库目录相对src/lib解析注意示例.env中还有LLM_RESPONSE_LANGUAGE字段但从 src/config.ts 的运行时解析看该变量并未被消费可视为预留占位实际回复语言由人物设定与提示词约束决定。配置校验机制模块使用valibot对配置做运行时校验src/config.ts。LLM_API_KEY、LLM_API_BASE_URL、LLM_MODEL是必填项缺失时会在启动时打印每个失败字段并调用process.exit(1)直接退出SATORI_WS_URL、SATORI_API_BASE_URL有默认值兜底SATORI_TOKEN与LLM_OLLAMA_DISABLE_THINK为可选项。布尔值通过parseBoolean解析true或1视为真。启动机器人# 开发模式热重载 pnpm -F proj-airi/satori-bot dev # 生产模式 pnpm -F proj-airi/satori-bot start对应的 npm scripts 定义在 integrations/satori-bot/package.json两条命令都会通过tsx加载.env与.env.local后者存在则覆盖前者并运行src/index.ts。启动入口src/index.ts的执行顺序是initDb()初始化 PGlite 数据库并自动执行 Drizzle 迁移创建SatoriClient持有 WS URL、token 与 API 基地址createBotContext从数据库恢复事件队列与未读事件构建机器人运行上下文注册ready与message-created事件处理器建立 WebSocket 连接globalRegistry.loadStandardActions注册全部动作startPeriodicLoop启动周期性巡检循环。深入一Satori 协议适配层satori-bot 的适配层在 integrations/satori-bot/src/adapter/satori/由client.tsWebSocket 客户端、api.tsREST API 客户端、schema.tsvalibot 运行时校验与types.ts协议类型定义组成。WebSocket 连接与鉴权SatoriClient.connect()client.ts建立连接后立即发送IDENTIFY信号完成鉴权。协议操作码定义在 types.ts操作码常量方向含义0EVENT收接收事件1PING发心跳2PONG收心跳回复3IDENTIFY发鉴权4READY收鉴权成功携带logins列表5META收元信息更新IDENTIFY会带上token与断线前的序列号sn用于重连后的消息续传client.ts。心跳与断线重连连接建立后客户端每10 秒发送一次PING心跳client.ts收到READY后为每个login即每个平台上的机器人账号初始化一个独立的 REST API 客户端键为platform:self_id。断线时进入 5 秒后自动重连的退避流程client.ts保证机器人掉线后能自动恢复。REST API 客户端SatoriAPIapi.ts封装了message.create、message.get、message.delete、message.update四个端点请求头携带Satori-Platform、Satori-User-ID与可选的Authorization: Bearer token每个请求设置 10 秒超时。发消息的核心调用链为Action 处理器 →SatoriClient.sendMessage(platform, selfId, channelId, content)→ 查找对应平台的SatoriAPI→ POST/message.create。深入二事件驱动 自主循环的消息处理架构这是本模块最核心的运行时设计。官方文档 HANDLER.md 将其概括为事件驱动 自主循环的混合模型整个消息生命周期分为五阶段。阶段 1事件入口与去重Ingress入口在setupMessageEventHandlerqueue.tsSatoriClient收到原始 JSON 信号解析为SatoriEvent经 valibot 校验监听message-created事件以channelId-messageId为键存入processedIds集合做去重将事件包装为{ event, status: ready }推入内存eventQueue同时通过pushToEventQueue写入数据库触发onMessageArrival消费队列。阶段 2消费与未读池锚定Consumption AnchoringonMessageArrivalscheduler.ts逐条消费事件通过ensureChatContextcontext.ts按channelId加载或创建该频道的内存会话上下文——频道 ID 是全部上下文的主键过滤机器人自身消息若发送者 ID 等于selfId直接从队列移除并丢弃不计入未读事件推入botContext.unreadEvents[channelId]即未读池并持久化随后从数据库队列中删除立即调用loopIterationForChannel唤醒该频道的自主循环。值得注意的是调度采用了通道级锁chatCtx.isProcessing标志确保同一频道不会被并发处理而不同频道可以并行推进避免全局锁死锁这一改进记录在 todolist.md 的已完成事项中。阶段 3LLM 推理ReasoningLLM 被提示的目标不是回复这段文本而是基于当前状态决策下一个动作详见下节LLM 规划器。阶段 4动作分发与执行Dispatch ExecutionLLM 输出 JSON 动作后由 dispatcher.ts 做 valibot 二次校验再从globalRegistry查表分发详见Action 能力系统。阶段 5循环延续Loop ContinuationdispatchAction返回带shouldContinue标志的ActionResult。若为true例如读完消息后通常应继续回复调度器等待LOOP_CONTINUE_DELAY_MS默认 2.5 秒后递归执行下一步。循环控制常量集中定义在 constants.ts常量值含义LOOP_CONTINUE_DELAY_MS2500循环步之间的等待毫秒数PERIODIC_LOOP_INTERVAL_MS60000周期性巡检间隔处理仅剩未读、无新消息的频道SLEEP_DURATION_MS30000sleep动作的默认休眠时长MAX_LOOP_ITERATIONS5单次循环硬上限防止 LLM 幻觉或 API 滥用导致死循环MAX_ACTIONS_IN_CONTEXT50注入上下文的最大动作历史条数ACTIONS_KEEP_ON_TRIM20超出上限后保留的动作条数MAX_UNREAD_EVENTS100单频道未读事件上限MAX_RECENT_INTERACTED_CHANNELS5记录最近互动频道的数量上限周期性循环startPeriodicLoop每 60 秒巡检一次但只处理存在未读消息的频道从而避免无谓的 LLM 调用scheduler.ts。深入三LLM 规划器与 Prompt 架构规划器位于 integrations/satori-bot/src/core/planner/核心函数imagineAnActionllm-client.ts在每次循环 tick 动态构造提示词。内部文档 PROMPTS.md 将其归纳为三层架构静态层系统定义由personality-v1.velin.md人格设定与system-action-gen-v1.velin.md工具定义与行为规则两个 Velin 模板组成经src/core/planner/prompts/index.ts加载。历史层短期记忆从数据库动态拉取最近 10 条消息映射为assistant/user轮次注入。动态状态层感官注入在用户消息末尾追加实时状态块包含正在到达的Incoming events流仅第一轮注入History actions上一次动作及其结果如Action: send_message, Result: Success服务器当前时间各频道未读事件统计You have total X unread events最终指令基于上下文选择动作仅输出 JSON不含任何解释与标记。关键设计模块不使用OpenAI 原生 Function Calling / Tools API而是纯提示词工程强制模型输出 JSON再交给best-effort-json-parser解析、valibot 校验ActionSchema定义在 types.ts。若 LLM 输出被代码块包裹会先剥去 json 标记。LLM_OLLAMA_DISABLE_THINKtrue时会给请求附加think: false字段响应中的think.../think思考链也会被剥离。人格设定示例默认人格 personality-v1.velin.md 将机器人塑造为一位性格鲜明的高中女生傲娇、护短、口语化、短促有力的回复风格并对不同人物关系给出差异化的语气规则。这体现了 AIRI赛博灵魂容器的产品理念——机器人不只是客服而是有性格的个体。如需自定义直接修改该模板文件即可。深入四Action 能力系统能力层在 integrations/satori-bot/src/capabilities/ActionRegistryregistry.ts在启动时批量注册全部动作。目前共有6 种动作其 valibot 校验 Schema 与执行器如下动作Schematypes.ts执行器行为read_unread_messages需channelIdread-messages.ts将频道未读事件格式化为[用户名]: 内容文本块返回给 LLM并按 ID 精准删除已读事件保留处理期间新到达的消息send_message需channelId、contentsend-message.ts先做并发安全检查若生成期间又有新未读到达则中止发送并提示 LLM 先读取新消息再经SatoriClient发消息并持久化continue无参数system.ts结束当前循环等待用户输入shouldContinuefalsebreak无参数同上清空动作历史并中断循环sleep可选duration同上休眠指定毫秒数默认 30 秒后继续list_channels无参数同上从数据库列出已知频道ID、名称、平台动作分发在 dispatcher.ts先safeParse校验负载查不到处理器则返回Action not implemented的系统错误执行成功后将{ action, result }追加到chatCtx.actions作为下一轮 LLM 的History actions输入。上下文裁剪的巧思trimActionsutils.ts在动作历史超过上限时向后保留最近keep条但如果保留段开头恰好是continue会回溯包含触发它的前一条动作避免截断破坏send_messagecontinue这类成对逻辑链导致失忆。深入五状态持久化PGlite Drizzle模块已从早期 lowdbJSON迁移到PGliteWASM 版 PostgreSQL Drizzle ORM内部文档 PERSISTENCE.md 记录了完整的架构决策。启动时initDbdb.ts自动执行drizzle/目录下的迁移。数据库共四张表schema.ts 与 0000_cooing_captain_flint.sql表用途关键字段channels已发现频道的元数据idPK、name、platform、self_idmessages消息日志用于重建对话历史id、channel_id、user_id、user_name、content、timestamp并建有channel_timestamp_idx复合索引event_queue待处理 Satori 事件队列eventJSON、status、created_atunread_events各频道未读事件eventJSON、channel_id、created_at内存优先 磁盘持久化策略活跃会话上下文存于内存Mapstring, ChatContext按需惰性创建ensureChatContext事件队列与未读事件采用增量 SQL 更新按 ID 添加/删除而非早期全量重写崩溃恢复eventQueue与unreadEvents完全持久化机器人重启后createBotContext会从数据库恢复队列继续处理对话历史由messages表重建保证跨重启的连续性。安全注意事项原文档对此有专门强调这也是本模块最重要的运维红线Satori token、消息平台凭据、模型 API Key 是敏感信息。请只保存在本地integrations/satori-bot/.env.local文件中。不要提交到版本控制、不要出现在截图里、不要分享给任何人。.env.local已被 git 忽略项目约定.env为模板、.env.local为本地私有配置配置错误时日志也会给出明确的排查提示LLM API Key 错误会输出❌ LLM API Key Error: Please check your .env.local...并附带当前LLM_API_BASE_URL与LLM_MODEL见 llm-client.ts。相关文档索引若需进一步深入仓库内还有以下一手资料可供查阅消息生命周期完整流程HANDLER.md内存与持久化架构PERSISTENCE.mdPrompt 三层架构与数据流图PROMPTS.mdSatoriEvent各字段说明含 OneBot 原始数据字段EVENT.md已解决与待办问题清单todolist.md赞分享人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载相关推荐CAMEL 多平台 AI 机器人指南用 ChatAgent 驱动 Telegram、Discord 与 Slack BotCAMEL 多平台 AI 机器人指南用 ChatAgent 驱动 Telegram、Discord 与 Slack Bot 本文围绕 CAMEL 开源框架中的人工智能大模型AI AgentAgent 框架多智能体RAG工具调用AIRI Telegram Bot 部署指南用 PostgreSQL 向量库与模型服务将 AIRI 接入 TelegramAIRI Telegram Bot 部署指南用 PostgreSQL 向量库与模型服务将 AIRI 接入 Telegram 本文基于 integrations人工智能AI 应用大模型AI Agent交互助手语音数字人后端前端桌面应用移动开发GUI 自动化MCP 服务终极指南如何快速部署go-cqhttp跨平台QQ机器人终极指南如何快速部署go cqhttp跨平台QQ机器人 go cqhttp是一款基于Go语言实现的轻量级、原生跨平台QQ机器人框架完美兼容OneBot v1即时通讯后端上一篇Zenodo数据下载终极指南zenodo_get工具完全解析下一篇Symfony 8.0 版本变更全解读从 CHANGELOG 看新特性、破坏性变更与安全修复创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考