Satori Bot 待办事项深度解读从架构治理到多平台 AI Agent 的工程实践【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi导读Satori Bot 是 AIRI 仓库中一个基于 Satori 协议、通过 Koishi 桥接连接多聊天平台QQ、Telegram、Discord、Lark的独立事件驱动 AI Agent。integrations/satori-bot/todolist.md记录了该项目从 P0 稳定性攻坚到 P2 类型安全收尾的完整工程治理轨迹。本文以该待办清单为骨架逐项还原其背后的架构设计、源码实现与演进逻辑帮助读者理解如何用待办即架构决策的方式管理一个自主循环 AI Agent 的稳定性、逻辑链完整性与代码质量。1. 待办清单的整体结构优先级即架构观integrations/satori-bot/todolist.md将工作项按三档优先级组织优先级主题核心关切 P1架构完善与逻辑优化性能与体验Action 截断、上下文记忆 P2增强功能与类型安全可观测性Trace 日志与类型收紧消除as any✅ 已完成P0/P1/P2 归档稳定性、逻辑链、类型、持久化竞态、死锁、非阻塞调度、API 滥用防护等这种优先级即架构观的组织方式本身极具参考价值P0 聚焦核心稳定性与并发架构P1 聚焦逻辑链完整性与用户体验P2 聚焦长期可维护性。它反映了一个真实项目的治理逻辑——先保证不出事再保证体验好最后保证能长期演进。待办清单中记录的三条核心工程决策已完成清单中明确记录了以下关键工程决策本文后续章节会逐一展开并发模型onMessageArrival与周期性任务改为并发执行锁粒度下放到 Channel 级别逻辑链保护trimActions自动回溯 MAX_LOOP_ITERATIONS 5硬性上限持久化重构从 lowdb 全量重写升级为 Drizzle ORM 增量更新模式。2. P0 稳定性攻坚竞态修复、锁粒度与并发调度2.1 基于 ID 的精准删除修复短时记忆清理竞态清单归档的第一项是修复短时记忆清理的竞态条件实现基于 ID 的精准删除防止异步消息丢失。在 scheduler.ts 中可以看到该设计的落点每条进入队列的事件在pushToEventQueue时由nanoid()生成唯一 ID见 db.ts 中的pushToEventQueue消费完成后通过removeFromEventQueue(currMsg.id)按 ID 删除而不是对整个队列做数组重写。这种按 ID 精准增删的模式避免了异步场景下基于索引操作导致的错位删除与消息丢失。当currMsg.id缺失时代码才回退到saveEventQueue全量保存scheduler.ts 中onMessageArrival内的分支处理保证极端情况也有兜底。2.2 锁粒度下放到 Channel消除全局死锁清单记录的第二项是消除全局锁死锁将锁粒度下放到 Channel 级别并引入try...finally强制释放机制。在 types.ts 中ChatContext携带isProcessing: boolean标志这就是 Channel 级锁的载体onMessageArrival在触发某 Channel 的处理前设置chatCtx.isProcessing true处理流程包裹在自调用异步函数中finally块内将isProcessing复位见 scheduler.ts 中onMessageArrival尾部周期性循环loopIterationPeriodicForExistingChannels在启动新任务前检查if (chatCtx.isProcessing) continue从而避免同一 Channel 的重入处理。try...finally的作用在于即使handleLoopStep抛出异常锁也会被强制释放不会因一次失败而让整个 Channel 永久卡死。2.3 非阻塞调度事件消费与周期性任务并发执行onMessageArrival采用isQueueConsumerRunning模块级标志实现单消费者串行消费但处理过程本身被设计为非阻塞每条事件消费后先将其加入unreadEvents并落库然后立即eventQueue.shift()消费下一条Channel 的具体推理循环loopIterationForChannel→handleLoopStep通过(async () {...})()自调用异步函数在后台并发执行不阻塞队列的继续消费。周期性任务loopPeriodic则通过递归setTimeout每PERIODIC_LOOP_INTERVAL_MS默认 60 秒见 constants.ts扫描所有有未读事件的 Channel。其关键优化是只处理unreadEvents[channelId]非空的 Channel避免无意义的 LLM 调用。整个调用链为loopPeriodic → loopIterationPeriodicForExistingChannels → ensureChatContext → handleLoopStep3. P1 逻辑链保护智能 Action 截断与循环上限3.1 问题背景为什么不能直接截断 Action 历史在handleLoopStep中每次迭代后dispatchAction会把{ action, result }追加到chatCtx.actions。长期运行后该数组会无限增长必须截断以控制 LLM 上下文大小。但朴素截断存在一个致命问题若保留段的首个 Action 恰好是continue那么 LLM 看到的动作序列就缺失了触发该continue的前置动作如先read_unread_messages再continue继续推理的逻辑链导致模型失忆、推理链断裂。3.2trimActions的回溯实现清单中智能 Action 截断实现trimActions自动回溯对应的实现在 utils.tsexport function trimActions(actions, max, keep) { if (actions.length max) return actions let startIndex actions.length - keep // 回溯避免以 continue 开头而丢失其前置上下文 while (startIndex 0) { const currentAction actions[startIndex].action if (currentAction.action continue) { startIndex-- } else { break } } return actions.slice(startIndex) }核心逻辑是先按keep数量保留最近动作然后向前回溯只要保留段起点仍是continue就继续前移包含其触发者直到起点为普通动作。这样保证了逻辑链的完整性。调用位置在 scheduler.ts 的handleLoopStep中chatCtx.actions trimActions(chatCtx.actions, MAX_ACTIONS_IN_CONTEXT, ACTIONS_KEEP_ON_TRIM)两个常量constants.ts含义如下常量默认值作用MAX_ACTIONS_IN_CONTEXT50上下文中的 Action 数量上限超过才触发截断ACTIONS_KEEP_ON_TRIM20触发截断时保留的最近 Action 数量MAX_UNREAD_EVENTS100单 Channel 未读事件上限超出则从尾部裁剪MAX_RECENT_INTERACTED_CHANNELS5最近活跃 Channel 的追踪数量上限LOOP_CONTINUE_DELAY_MS2500continue迭代之间的间隔毫秒PERIODIC_LOOP_INTERVAL_MS60000周期性扫描间隔毫秒SLEEP_DURATION_MS30000sleep动作的默认时长毫秒MAX_LOOP_ITERATIONS5单次循环的最大迭代次数3.3MAX_LOOP_ITERATIONS 5防幻觉硬上限handleLoopStep的 while 循环在每次迭代前检查if (iterationCount MAX_LOOP_ITERATIONS) { // 记录日志并 break防止无限循环 }这是清单中阻断 API 滥用的实现即使 LLM 不断输出continue循环也会在 5 次迭代后被强制终止避免由幻觉或 API 故障导致的无限推理与费用失控。4. P2 增强可观测性与类型安全4.1 待办中的 Trace 日志增强清单中仍处于开放状态的 P2 项包括监控增强为所有 Action 执行增加更详细的 Trace 日志类型收紧持续检查并消除残留的as any类型断言。其中为 Action 执行增加 Trace 日志的增强方向在 dispatcher.ts 的现有日志基础上延伸log.withField(action, validatedAction.action).debug(Executing action)以及异常路径log.withError(error as Error).error(Action execution failed)每次执行的 Action 名称、成功/失败状态都会记录在日志中。dispatchAction的错误处理非常讲究任何解析失败、Handler 缺失或执行异常都会返回success: false但shouldContinue: true的ActionResult把错误以文本形式注入 Action 历史回传给 LLM让模型看到自己的错误并有机会自我纠正而不是直接中断循环。从源码结构看未来若落实 Trace 增强可在chatCtx.actions.push处记录耗时、入参摘要与结果类型与 utils.ts 中已有的formatDebugContext输出队列长度、未读统计、最近 3 条 Action 摘要配合形成完整观测链路。4.2 已完成消除 Any 类型滥用清单归档的消除 Any 类型滥用修复了 LLM 解析、数据库 Schema 等多处的类型退化在代码中有多处印证LLM 输出解析dispatchAction使用 valibot 的v.safeParse(ActionSchema, actionPayload)对 LLM 输出做运行时 Schema 校验ActionSchema是 6 种动作 Schema 的 union见 types.ts并导出Action v.InferOutputtypeof ActionSchema类型数据库 Schemadb.insert(messages).values({...})全部走 Drizzle ORM 的类型化 API见 db.tsSatori API 类型对齐修复SatoriMessageCreateResponse与运行时 Schema 的不一致对应归档项修复 Satori API 类型不匹配。4.3 已完成移除全局暴力退出归档项移除全局暴力退出在process.on(unhandledRejection)中移除process.exit(1)的工程意义在于全局退出会杀死整个进程导致内存中的队列状态与进行中的推理全部丢失。移除后未处理的 Promise 拒绝只记录日志交由持久化层与重启恢复机制兜底见下文第 6 节的状态一致性讨论。5. 持久化重写从 lowdb 全量重写到 Drizzle 增量更新5.1 归档的核心工作清单归档项重写队列持久化 I/O实现 Drizzle ORM 的增量更新模式是 P2 中最有分量的改动。根据 PERSISTENCE.md 的记录存储层完成了从lowdbJSON 全量重写到PGlite Drizzle ORM的迁移PGlitePostgreSQL 的 WASM/Node 实现数据目录由DB_PATH配置默认data/pglite-db见 config.tsDrizzle ORM类型安全的 SQL 构建器migration 在启动时自动执行initDb调用migrate(db, ...)见 db.ts。5.2 四张核心表见 schema.ts表职责索引channels已发现 Channel 的元数据ID、名称、平台、self_id主键messages持久化消息日志channel_idtimestamp索引event_queue待处理的 Satori 事件持久队列主键unread_events各 Channel 的未读事件持久存储主键5.3 增量更新模式取代全量重写对比旧的全量重写每次变更把整个队列序列化回 JSON 文件新的增量模式采用精准 SQL 操作入队pushToEventQueue按事件插入一行nanoid()生成 ID出队removeFromEventQueue(id)按 ID 删除单行未读追踪pushToUnreadEvents增量写入clearUnreadEventsForChannel按 Channel 清理消息记录recordMessage按消息插入getRecentMessages(channelId, 10)按时间倒序取最近 10 条用于 LLM 上下文重建。这套设计的直接收益是I/O 从 O(队列长度) 的全量写入降为 O(1) 的单行操作同时在崩溃恢复时事件队列与未读事件都能从磁盘原样续跑。6. 状态一致性内存记忆与磁盘持久化的缺口管理PERSISTENCE.md 明确指出当前Memory-First策略下仍存在的两个缺口这是理解该架构局限性的关键AbortController句柄在重启后会丢失进程重启后进行中的 LLM 请求无法再被中断活跃会话的ChatContext仅驻留内存重启后需依赖messages表重建历史未读事件则从unread_events表恢复。已弥合的缺口包括事件队列event_queue与未读事件unread_events完全持久化崩溃后可以从断点续跑对话历史可从messages表按channel_id重建保证重启后 LLM 上下文的连续性。这种关键状态落盘、会话上下文驻留内存 按需重建的策略是单体 Agent 在响应性能与状态持久性之间的务实折中。7. 从待办清单看整体消息流架构将待办清单与 HANDLER.md 对照可以还原出完整的事件 → 队列 → 调度 → LLM → 分发链路Phase 1 入站: SatoriClient (WS) → 事件解析 → processedIds 去重 → eventQueue 入队并落库 Phase 2 消费: onMessageArrival → ensureChatContext → 过滤 bot 自身消息 → 写入 unreadEvents → 触发 channel 循环 Phase 3 推理: handleLoopStep → imagineAnAction (Persona 未读状态 Action 历史 → LLM JSON Action) Phase 4 分发: dispatchAction → ActionSchema 校验 → globalRegistry 查找 Handler → 执行 Phase 5 续环: ActionResult.shouldContinue → 等待 2.5s → 递归下一轮上限 5 次两个核心 Action 的分发逻辑见 read-messages.ts 与 send-message.tsread_unread_messages批量取出指定 Channel 的未读事件格式化为文本块作为 Action Result随后清空该 Channel 的未读池——下一轮循环 LLM 会从 History Actions 中看到这段文本并决定如何回复send_message执行前再次检查unreadEvents若推理期间有新消息到达可能中止发送以优先读取成功后把回复同时持久化到 DB 与内存messages。整个消息流中channel.id是所有上下文ChatContext、unreadEvents、数据库记录的统一主键。8. 实践启示如何用待办即架构管理 Agent 项目satori-bot/todolist.md虽是内部管理文档却提供了一个高价值的工程模板用优先级标签锚定架构阶段P0 并发与稳定性 → P1 逻辑链与体验 → P2 可观测性与类型安全符合先稳定、再体验、后治理的演进节奏把核心决策写进归档清单竞态修复方案、锁粒度选择、截断策略、循环上限、持久化模式每一条都指向明确的源码位置成为后来者的决策索引开放项保持可执行的颗粒度如将较旧的 actions 压缩为 Summary 存入 LLM Context而非直接丢弃这是对trimActions丢弃策略的明确演进方向用摘要压缩替代硬截断进一步降低信息损失类型安全作为长期债务管理将消除as any作为持续跟踪项配合 valibot Schema 与 Drizzle 类型化 API把运行时错误前移到编译期。对于任何正在构建自主循环ReAct 式Agent 的团队这份待办清单与其背后的源码实现都是一份可复用的工程范式。关键文件索引关注点文件路径待办清单与演进轨迹todolist.md消息流架构全解HANDLER.md持久化与状态一致性PERSISTENCE.mdSatori 事件字段定义EVENT.md循环调度与截断调用点scheduler.ts常量与上限定义constants.tstrimActions回溯实现utils.tsAction Schema 与上下文类型types.tsAction 校验与分发dispatcher.tsPGlite Drizzle 增量 I/Odb.ts说明根据该模块 README.md 的声明src/core/循环与规划逻辑是 AIRI 主线框架稳定前的临时替代实现Dispatcher 与数据库层将被保留未来以工具模块形式暴露给 AIRI Core 使用。本文所描述的消息流与持久化细节均以当前仓库中的独立运行版本为准。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Satori Bot 待办事项深度解读：从架构治理到多平台 AI Agent 的工程实践
Satori Bot 待办事项深度解读从架构治理到多平台 AI Agent 的工程实践【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi导读Satori Bot 是 AIRI 仓库中一个基于 Satori 协议、通过 Koishi 桥接连接多聊天平台QQ、Telegram、Discord、Lark的独立事件驱动 AI Agent。integrations/satori-bot/todolist.md记录了该项目从 P0 稳定性攻坚到 P2 类型安全收尾的完整工程治理轨迹。本文以该待办清单为骨架逐项还原其背后的架构设计、源码实现与演进逻辑帮助读者理解如何用待办即架构决策的方式管理一个自主循环 AI Agent 的稳定性、逻辑链完整性与代码质量。1. 待办清单的整体结构优先级即架构观integrations/satori-bot/todolist.md将工作项按三档优先级组织优先级主题核心关切 P1架构完善与逻辑优化性能与体验Action 截断、上下文记忆 P2增强功能与类型安全可观测性Trace 日志与类型收紧消除as any✅ 已完成P0/P1/P2 归档稳定性、逻辑链、类型、持久化竞态、死锁、非阻塞调度、API 滥用防护等这种优先级即架构观的组织方式本身极具参考价值P0 聚焦核心稳定性与并发架构P1 聚焦逻辑链完整性与用户体验P2 聚焦长期可维护性。它反映了一个真实项目的治理逻辑——先保证不出事再保证体验好最后保证能长期演进。待办清单中记录的三条核心工程决策已完成清单中明确记录了以下关键工程决策本文后续章节会逐一展开并发模型onMessageArrival与周期性任务改为并发执行锁粒度下放到 Channel 级别逻辑链保护trimActions自动回溯 MAX_LOOP_ITERATIONS 5硬性上限持久化重构从 lowdb 全量重写升级为 Drizzle ORM 增量更新模式。2. P0 稳定性攻坚竞态修复、锁粒度与并发调度2.1 基于 ID 的精准删除修复短时记忆清理竞态清单归档的第一项是修复短时记忆清理的竞态条件实现基于 ID 的精准删除防止异步消息丢失。在 scheduler.ts 中可以看到该设计的落点每条进入队列的事件在pushToEventQueue时由nanoid()生成唯一 ID见 db.ts 中的pushToEventQueue消费完成后通过removeFromEventQueue(currMsg.id)按 ID 删除而不是对整个队列做数组重写。这种按 ID 精准增删的模式避免了异步场景下基于索引操作导致的错位删除与消息丢失。当currMsg.id缺失时代码才回退到saveEventQueue全量保存scheduler.ts 中onMessageArrival内的分支处理保证极端情况也有兜底。2.2 锁粒度下放到 Channel消除全局死锁清单记录的第二项是消除全局锁死锁将锁粒度下放到 Channel 级别并引入try...finally强制释放机制。在 types.ts 中ChatContext携带isProcessing: boolean标志这就是 Channel 级锁的载体onMessageArrival在触发某 Channel 的处理前设置chatCtx.isProcessing true处理流程包裹在自调用异步函数中finally块内将isProcessing复位见 scheduler.ts 中onMessageArrival尾部周期性循环loopIterationPeriodicForExistingChannels在启动新任务前检查if (chatCtx.isProcessing) continue从而避免同一 Channel 的重入处理。try...finally的作用在于即使handleLoopStep抛出异常锁也会被强制释放不会因一次失败而让整个 Channel 永久卡死。2.3 非阻塞调度事件消费与周期性任务并发执行onMessageArrival采用isQueueConsumerRunning模块级标志实现单消费者串行消费但处理过程本身被设计为非阻塞每条事件消费后先将其加入unreadEvents并落库然后立即eventQueue.shift()消费下一条Channel 的具体推理循环loopIterationForChannel→handleLoopStep通过(async () {...})()自调用异步函数在后台并发执行不阻塞队列的继续消费。周期性任务loopPeriodic则通过递归setTimeout每PERIODIC_LOOP_INTERVAL_MS默认 60 秒见 constants.ts扫描所有有未读事件的 Channel。其关键优化是只处理unreadEvents[channelId]非空的 Channel避免无意义的 LLM 调用。整个调用链为loopPeriodic → loopIterationPeriodicForExistingChannels → ensureChatContext → handleLoopStep3. P1 逻辑链保护智能 Action 截断与循环上限3.1 问题背景为什么不能直接截断 Action 历史在handleLoopStep中每次迭代后dispatchAction会把{ action, result }追加到chatCtx.actions。长期运行后该数组会无限增长必须截断以控制 LLM 上下文大小。但朴素截断存在一个致命问题若保留段的首个 Action 恰好是continue那么 LLM 看到的动作序列就缺失了触发该continue的前置动作如先read_unread_messages再continue继续推理的逻辑链导致模型失忆、推理链断裂。3.2trimActions的回溯实现清单中智能 Action 截断实现trimActions自动回溯对应的实现在 utils.tsexport function trimActions(actions, max, keep) { if (actions.length max) return actions let startIndex actions.length - keep // 回溯避免以 continue 开头而丢失其前置上下文 while (startIndex 0) { const currentAction actions[startIndex].action if (currentAction.action continue) { startIndex-- } else { break } } return actions.slice(startIndex) }核心逻辑是先按keep数量保留最近动作然后向前回溯只要保留段起点仍是continue就继续前移包含其触发者直到起点为普通动作。这样保证了逻辑链的完整性。调用位置在 scheduler.ts 的handleLoopStep中chatCtx.actions trimActions(chatCtx.actions, MAX_ACTIONS_IN_CONTEXT, ACTIONS_KEEP_ON_TRIM)两个常量constants.ts含义如下常量默认值作用MAX_ACTIONS_IN_CONTEXT50上下文中的 Action 数量上限超过才触发截断ACTIONS_KEEP_ON_TRIM20触发截断时保留的最近 Action 数量MAX_UNREAD_EVENTS100单 Channel 未读事件上限超出则从尾部裁剪MAX_RECENT_INTERACTED_CHANNELS5最近活跃 Channel 的追踪数量上限LOOP_CONTINUE_DELAY_MS2500continue迭代之间的间隔毫秒PERIODIC_LOOP_INTERVAL_MS60000周期性扫描间隔毫秒SLEEP_DURATION_MS30000sleep动作的默认时长毫秒MAX_LOOP_ITERATIONS5单次循环的最大迭代次数3.3MAX_LOOP_ITERATIONS 5防幻觉硬上限handleLoopStep的 while 循环在每次迭代前检查if (iterationCount MAX_LOOP_ITERATIONS) { // 记录日志并 break防止无限循环 }这是清单中阻断 API 滥用的实现即使 LLM 不断输出continue循环也会在 5 次迭代后被强制终止避免由幻觉或 API 故障导致的无限推理与费用失控。4. P2 增强可观测性与类型安全4.1 待办中的 Trace 日志增强清单中仍处于开放状态的 P2 项包括监控增强为所有 Action 执行增加更详细的 Trace 日志类型收紧持续检查并消除残留的as any类型断言。其中为 Action 执行增加 Trace 日志的增强方向在 dispatcher.ts 的现有日志基础上延伸log.withField(action, validatedAction.action).debug(Executing action)以及异常路径log.withError(error as Error).error(Action execution failed)每次执行的 Action 名称、成功/失败状态都会记录在日志中。dispatchAction的错误处理非常讲究任何解析失败、Handler 缺失或执行异常都会返回success: false但shouldContinue: true的ActionResult把错误以文本形式注入 Action 历史回传给 LLM让模型看到自己的错误并有机会自我纠正而不是直接中断循环。从源码结构看未来若落实 Trace 增强可在chatCtx.actions.push处记录耗时、入参摘要与结果类型与 utils.ts 中已有的formatDebugContext输出队列长度、未读统计、最近 3 条 Action 摘要配合形成完整观测链路。4.2 已完成消除 Any 类型滥用清单归档的消除 Any 类型滥用修复了 LLM 解析、数据库 Schema 等多处的类型退化在代码中有多处印证LLM 输出解析dispatchAction使用 valibot 的v.safeParse(ActionSchema, actionPayload)对 LLM 输出做运行时 Schema 校验ActionSchema是 6 种动作 Schema 的 union见 types.ts并导出Action v.InferOutputtypeof ActionSchema类型数据库 Schemadb.insert(messages).values({...})全部走 Drizzle ORM 的类型化 API见 db.tsSatori API 类型对齐修复SatoriMessageCreateResponse与运行时 Schema 的不一致对应归档项修复 Satori API 类型不匹配。4.3 已完成移除全局暴力退出归档项移除全局暴力退出在process.on(unhandledRejection)中移除process.exit(1)的工程意义在于全局退出会杀死整个进程导致内存中的队列状态与进行中的推理全部丢失。移除后未处理的 Promise 拒绝只记录日志交由持久化层与重启恢复机制兜底见下文第 6 节的状态一致性讨论。5. 持久化重写从 lowdb 全量重写到 Drizzle 增量更新5.1 归档的核心工作清单归档项重写队列持久化 I/O实现 Drizzle ORM 的增量更新模式是 P2 中最有分量的改动。根据 PERSISTENCE.md 的记录存储层完成了从lowdbJSON 全量重写到PGlite Drizzle ORM的迁移PGlitePostgreSQL 的 WASM/Node 实现数据目录由DB_PATH配置默认data/pglite-db见 config.tsDrizzle ORM类型安全的 SQL 构建器migration 在启动时自动执行initDb调用migrate(db, ...)见 db.ts。5.2 四张核心表见 schema.ts表职责索引channels已发现 Channel 的元数据ID、名称、平台、self_id主键messages持久化消息日志channel_idtimestamp索引event_queue待处理的 Satori 事件持久队列主键unread_events各 Channel 的未读事件持久存储主键5.3 增量更新模式取代全量重写对比旧的全量重写每次变更把整个队列序列化回 JSON 文件新的增量模式采用精准 SQL 操作入队pushToEventQueue按事件插入一行nanoid()生成 ID出队removeFromEventQueue(id)按 ID 删除单行未读追踪pushToUnreadEvents增量写入clearUnreadEventsForChannel按 Channel 清理消息记录recordMessage按消息插入getRecentMessages(channelId, 10)按时间倒序取最近 10 条用于 LLM 上下文重建。这套设计的直接收益是I/O 从 O(队列长度) 的全量写入降为 O(1) 的单行操作同时在崩溃恢复时事件队列与未读事件都能从磁盘原样续跑。6. 状态一致性内存记忆与磁盘持久化的缺口管理PERSISTENCE.md 明确指出当前Memory-First策略下仍存在的两个缺口这是理解该架构局限性的关键AbortController句柄在重启后会丢失进程重启后进行中的 LLM 请求无法再被中断活跃会话的ChatContext仅驻留内存重启后需依赖messages表重建历史未读事件则从unread_events表恢复。已弥合的缺口包括事件队列event_queue与未读事件unread_events完全持久化崩溃后可以从断点续跑对话历史可从messages表按channel_id重建保证重启后 LLM 上下文的连续性。这种关键状态落盘、会话上下文驻留内存 按需重建的策略是单体 Agent 在响应性能与状态持久性之间的务实折中。7. 从待办清单看整体消息流架构将待办清单与 HANDLER.md 对照可以还原出完整的事件 → 队列 → 调度 → LLM → 分发链路Phase 1 入站: SatoriClient (WS) → 事件解析 → processedIds 去重 → eventQueue 入队并落库 Phase 2 消费: onMessageArrival → ensureChatContext → 过滤 bot 自身消息 → 写入 unreadEvents → 触发 channel 循环 Phase 3 推理: handleLoopStep → imagineAnAction (Persona 未读状态 Action 历史 → LLM JSON Action) Phase 4 分发: dispatchAction → ActionSchema 校验 → globalRegistry 查找 Handler → 执行 Phase 5 续环: ActionResult.shouldContinue → 等待 2.5s → 递归下一轮上限 5 次两个核心 Action 的分发逻辑见 read-messages.ts 与 send-message.tsread_unread_messages批量取出指定 Channel 的未读事件格式化为文本块作为 Action Result随后清空该 Channel 的未读池——下一轮循环 LLM 会从 History Actions 中看到这段文本并决定如何回复send_message执行前再次检查unreadEvents若推理期间有新消息到达可能中止发送以优先读取成功后把回复同时持久化到 DB 与内存messages。整个消息流中channel.id是所有上下文ChatContext、unreadEvents、数据库记录的统一主键。8. 实践启示如何用待办即架构管理 Agent 项目satori-bot/todolist.md虽是内部管理文档却提供了一个高价值的工程模板用优先级标签锚定架构阶段P0 并发与稳定性 → P1 逻辑链与体验 → P2 可观测性与类型安全符合先稳定、再体验、后治理的演进节奏把核心决策写进归档清单竞态修复方案、锁粒度选择、截断策略、循环上限、持久化模式每一条都指向明确的源码位置成为后来者的决策索引开放项保持可执行的颗粒度如将较旧的 actions 压缩为 Summary 存入 LLM Context而非直接丢弃这是对trimActions丢弃策略的明确演进方向用摘要压缩替代硬截断进一步降低信息损失类型安全作为长期债务管理将消除as any作为持续跟踪项配合 valibot Schema 与 Drizzle 类型化 API把运行时错误前移到编译期。对于任何正在构建自主循环ReAct 式Agent 的团队这份待办清单与其背后的源码实现都是一份可复用的工程范式。关键文件索引关注点文件路径待办清单与演进轨迹todolist.md消息流架构全解HANDLER.md持久化与状态一致性PERSISTENCE.mdSatori 事件字段定义EVENT.md循环调度与截断调用点scheduler.ts常量与上限定义constants.tstrimActions回溯实现utils.tsAction Schema 与上下文类型types.tsAction 校验与分发dispatcher.tsPGlite Drizzle 增量 I/Odb.ts说明根据该模块 README.md 的声明src/core/循环与规划逻辑是 AIRI 主线框架稳定前的临时替代实现Dispatcher 与数据库层将被保留未来以工具模块形式暴露给 AIRI Core 使用。本文所描述的消息流与持久化细节均以当前仓库中的独立运行版本为准。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考