Architecture
在对话生命周期的每个关键时刻，注入智能
Sidecar 是 Lumina 的侧载 Agent 框架。多个独立 Agent 挂载在对话流程的不同阶段，
在不干扰主对话的前提下，完成记忆注入、技能匹配、标题生成等后台任务。
Core Idea
每个 Sidecar Agent 实现统一的 SidecarAgent 接口，声明名称、启用状态和要挂载的钩子。SidecarManager 负责注册、调度和生命周期管理。
传统做法
Sidecar 模式
How It Works
主对话流程是一条直线，Sidecar Agent 在关键节点侧向介入
Interface
name: string
唯一标识，用于注册和去重追踪
enabled: boolean
运行时开关，可响应设置变更和用户权限动态切换
beforeUserMessage? · afterAssistantMessage?
消息级钩子 — 注入上下文 / 后处理分析
onIdle? · onSessionStart?
会话级钩子 — 空闲提取 / 初始化环境
独立
Agent 之间互不感知，各自运行
容错
任何 Agent 异常不阻塞主对话
去重
injectionIds 跨消息防止重复注入
Lifecycle
关键路径钩子串行执行保证顺序，非关键路径钩子并行执行提升性能
用户消息发送前触发。收集所有启用 Agent 的注入内容（如相关记忆、匹配的技能文档），拼接到用户消息前方，增强 LLM 的上下文。
助手消息完成后触发。所有 Agent 通过 Promise.allSettled 并行执行，适合后处理任务如自动标题生成。单个 Agent 失败不影响其他。
用户停止发送消息 3 分钟后触发。每个会话维护独立的空闲定时器，新消息自动重置。适合记忆提取、对话总结等耗时后台任务。
会话创建或恢复时触发。通过 Promise.allSettled 并行执行，用于初始化 Agent 所需的环境和状态。
Built-in
跨会话持久记忆
挂载的钩子
beforeUserMessage
分析用户消息，从记忆库中检索相关 domain，注入匹配的用户/Agent 记忆
onIdle
空闲时从最近对话中提取新记忆，支持去重合并和 token 预算控制
关键设计
语义级技能匹配
挂载的钩子
beforeUserMessage
用轻量 LLM 分析用户意图，从内置技能库中匹配 0-2 个相关技能，将技能文档注入上下文
关键设计
智能会话标题
挂载的钩子
afterAssistantMessage
第 2 轮对话完成后，用 LLM 基于完整对话上下文生成更准确的标题
关键设计
Data Flow
注入内容从 Agent 产出到最终拼入 prompt，经过去重、持久化、重建三个阶段
Manager 收集各 Agent 的 MessageInjection，通过 injectionIds 跨消息去重
注入内容随消息保存为「快照」——即使记忆库后续变更，历史注入保持不变
从快照重建注入内容，保持 token 序列一致，命中 prompt cache
为什么是快照不变性？
同一历史消息无论何时重建，产出的 token 序列完全一致。 这让 LLM provider 可以命中 prompt cache，显著降低延迟和成本。 这是 Sidecar 架构最核心的设计约束。
Orchestration
全局单例，负责 Agent 注册/注销、钩子调度和空闲定时器管理
按名称注册，重复注册自动替换旧实例并打印警告日志
每个会话独立定时器，新消息重置计时，3 分钟空闲后触发
dispose() 清除所有定时器和注册的 Agent，防止内存泄漏
Extensibility
任何新的后台智能——情绪分析、对话评分、自动标签—— 都只需要实现 SidecarAgent 接口并注册到 Manager，无需修改主对话流程的任何代码。
返回首页