基于微内核架构(EventBus + DI + BaseTool),支持任意 OpenAI 兼容 API
核心设计:决策环(Control Loop)驱动的自学习 Agent,通过贝叶斯 Bandit 实现自适应决策优化。
| 特性 | 说明 |
|---|---|
| Agent 运行时自感知 | 实时感知运行状态(进度、停滞、循环、饱和度),动态调整决策 |
| 决策环架构 | 每轮决策 - 执行 - 反馈 - 学习的闭环控制 |
| 自学习系统 | 基于贝叶斯 Bandit 的 Action 选择,持续优化决策策略 |
| 三层记忆系统 | 人格记忆 + 会话记忆 + 长期记忆(FTS5全文检索 + 96维LSH向量混合召回) |
| 启发式决策引擎 | 规则提取特征 + Bandit 做 tie-break,兼顾可解释性与学习能力 |
| 工具使用控制 | 动态禁止/推荐工具切换,避免重复调用同一工具陷入循环 |
| 组件热插拔 | app/components/ 下文件 3 秒自动加载生效 |
| 事件驱动架构 | 基于 EventBus 的发布-订阅模式,组件松耦合 |
| Flash 模式 | 跳过记忆注入,加速简单任务 |
| 多通道接入 | 支持 QQ 等外部平台(目前只支持qqbot,telegram,持续更新中),通过 ChannelManager 统一管理消息路由、文件传输与注入 |
pip install -r requirements.txt
python main.py主要依赖:
- FastAPI + Uvicorn(Web 框架)
- PyYAML(配置解析)
- Jieba(中文分词)
- DrissionPage(用于网页搜索和操作浏览器)
- openai(OpenAI API 客户端)
- websockets(QQ Bot WebSocket 客户端)
- httpx(HTTP 客户端,用于外部平台文件上传)
编辑 config/agent/llm.yaml 文件,配置 API 密钥、服务地址和模型名称。
python main.py启动后访问 http://localhost:18000 打开聊天界面,访问 http://localhost:18000/docs 查看 API 文档。 (默认端口 18000,如被占用会自动切换,请查看启动日志获取实际端口)
Cellium Agent 的核心是 Control Loop(控制环) 驱动的决策系统,结合 贝叶斯 Bandit 实现自学习优化。
┌─────────────────────────────────────────────────────────────────────────┐
│ 自学习层 (Learning) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────────┐ │
│ │ Policy │ │ Bayesian │ │ PolicyBanditMemory │ │
│ │ Templates │───▶│ Bandit │◄───│ (Thompson Sampling 统计) │ │
│ │ (策略模板) │ │ (策略选择) │ │ │ │
│ └─────────────┘ └──────┬──────┘ └─────────────────────────────┘ │
│ │ │
└────────────────────────────┼────────────────────────────────────────────┘
│ 选择 Policy
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 决策环层 (Control Loop) │
│ │
│ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Step │────▶│ Feature │────▶│ Rule │ │
│ │ (每轮开始)│ │ Extraction │ │ Evaluation │ │
│ └──────────┘ │ (特征提取) │ │ (规则评估) │ │
│ │ └──────────────┘ └──────┬───────┘ │
│ │ │ │
│ │ ┌────────────────────────────┘ │
│ │ ▼ │
│ │ ┌──────────────┐ ┌──────────────┐ │
│ │ │ Action │◄────│ Action │ │
│ │ │ Candidates │ │ Bandit │ │
│ │ │ (候选动作) │ │ (Tie-break) │ │
│ │ └──────┬───────┘ └──────────────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌──────────────┐ │
│ │ │ Control │ │
│ │ │ Decision │ │
│ │ │ (决策输出) │ │
│ │ └──────┬───────┘ │
│ │ │ │
│ │ ┌──────┴───────┐ ┌──────────────┐ │
│ └────▶│ Execute │────▶│ End Round │ │
│ │ (执行) │ │ (每轮结束) │ │
│ └──────────────┘ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ Feedback Evaluator │ │
│ │ (反馈评估) │ │
│ │ - 分段式评估 │ │
│ │ - n-step return │ │
│ └──────────┬───────────┘ │
│ │ │
│ ┌──────────┴───────────┐ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Bandit Update │ │ Stats Persist │ │
│ │ (更新统计) │ │ (持久化) │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
-
特征提取(Feature Extraction)
- 启发式引擎提取当前状态特征
- 包括:停滞迭代数、进展趋势、重复分数、上下文饱和度等
-
规则评估(Rule Evaluation)
- 硬规则给出 action 候选集合
- 例如:检测到循环时候选 [redirect, compress]
-
Bandit Tie-break(Action 选择)
- 当候选 action 多于 1 个时,Bandit 介入
- 使用 Thompson Sampling + Heuristic Bias 选择最优 action
-
执行与反馈(Execute & Feedback)
- 执行选中的 action(continue/retry/redirect/compress/terminate)
- FeedbackEvaluator 分段式评估本轮表现
-
学习与更新(Learning & Update)
- 使用 n-step return 累积 reward
- 更新 Bandit 的 Beta 分布参数
- 定期衰减旧数据防止过拟合
PEOP 循环是决策环的扩展模块,实现自适应计划-执行循环。该模块根据任务复杂度动态调整策略:简单任务直接响应,复杂任务自动启用多步规划;执行过程中持续验证结果,发现偏差时局部重规划,通过显式状态管理实现高效、可靠的任务分解与执行:
┌─────────────────────────────────────────────────────────────┐
│ 计划执行引擎状态机 │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ OBSERVE │───▶│ PLAN │───▶│ EXECUTE │◄─────────────┐ │
│ │ 观察 │ │ 规划 │ │ 执行 │ 验证成功 │ │
│ └─────────┘ └─────────┘ └────┬────┘ 继续下一步 │ │
│ ▲ │ │ │
│ │ 验证失败│ │ │
│ │ ▼ │ │
│ │ ┌─────────┐ 重规划成功 │ │
│ │ │ REPLAN │───────────────┘ │
│ │ │ 重规划 │ │ │
│ │ └────┬────┘ │ │
│ │ │ │ │
│ └─────────────────────────────┘ 重规划次数超限 │ │
│ 或任务完成 │ │
│ ▼ │ │
│ ┌─────┐ │ │
│ │DONE │ │ │
│ │完成 │ │ │
│ └─────┘ │ │
└─────────────────────────────────────────────────────────────┘
核心机制:
| 机制 | 说明 |
|---|---|
| 批量规划 | 一次生成多步执行计划(1-5步)支持并行执行工具调用(如果无依赖关系),减少 LLM 调用次数 |
| 状态驱动 | 5阶段显式状态机(OBSERVE/PLAN/EXECUTE/REPLAN/DONE) |
| 执行内验证 | 每步执行后自动验证结果 |
| 局部重规划 | 验证失败时保留成功步骤,仅重新规划失败及后续步骤 |
工作流程:
- 观察(OBSERVE):分析用户输入,理解任务目标与上下文
- 规划(PLAN):LLM 生成结构化计划,每步包含:工具名、参数、执行目的、预期结果
- 执行(EXECUTE):按顺序执行计划步骤,每步执行后自动验证结果
- 验证成功 → 继续执行下一步
- 验证失败 → 进入 REPLAN 阶段
- 重规划(REPLAN):保留已成功的步骤,仅对失败及后续步骤重新生成计划
- 完成(DONE):所有步骤执行成功,或重规划次数超限
设计特点:
- 高效:多步计划一次生成,执行阶段零 LLM 调用
- 稳定:局部重规划避免全盘推翻,保持上下文连续性
- 可观测:5阶段状态机提供清晰的执行轨迹,便于调试与监控
- 协同:状态信息实时同步给 Control Loop,重规划触发 redirect 决策
配置参数:
max_plan_steps=5:单次规划最多 5 个步骤max_replans=3:最多允许 3 次重规划
代码定义:ACTION_TYPES = ["continue", "retry", "redirect", "compress", "terminate"]
| Action | 说明 | Heuristic Bias 条件 |
|---|---|---|
| continue | 继续当前方向 | 进展分数 > 0.5 或停滞迭代为 0 |
| retry | 保持方向但修正策略 | 轻微停滞(1 <= stuck < threshold)或进展趋势在 0~0.3 |
| redirect | 换方向/换工具 | 重复分数 > 0.5 或停滞 >= stuck_threshold |
| compress | 压缩上下文 | 上下文饱和度 > 0.6 或停滞 >= stuck_threshold // 2 |
| terminate | 终止会话 | 硬规则触发:输出循环且 exact_repetition_count >= 5 |
Policy - Bandit - Action 三层架构:
┌─────────────────────────────────────────┐
│ Policy Templates │
│ ┌─────────┬───────────┬─────────────┐ │
│ │ default │ efficient │ aggressive │ │
│ │ 平衡策略 │ 高效策略 │ 激进策略 │ │
│ │(stuck=3)│ (stuck=2) │ (stuck=5) │ │
│ └────┬────┴─────┬─────┴──────┬──────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ Bayesian Bandit │ │
│ │ Thompson Sampling 选择最优 Policy │ │
│ │ - 从 Beta 分布采样 │ │
│ │ - 选择期望收益最高的 Policy │ │
│ └─────────────┬───────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ Action Bandit │ │
│ │ 在候选 action 内做 tie-break │ │
│ │ - Heuristic 提供 bias │ │
│ │ - 动态调整阈值参数 │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────────┘
学习过程:
- Policy 选择:会话开始时,Bayesian Bandit 从多个 Policy(default/efficient/aggressive)中选择当前最优策略
- 阈值注入:选中的 Policy 参数(如 stuck_iterations=3)注入 HeuristicEngine 和 ActionBandit
- Action 学习:每轮结束后,根据 FeedbackEvaluator 的评分更新 Action 的 Beta 分布
- n-step return:累积最近 n 轮的 reward,支持延迟反馈和序列优化
- 数据衰减:每 50 个会话衰减一次旧数据(衰减因子 0.99),防止过拟合
采用分段式设计,先区分成功/失败,再优化细节:
-
成功分支:基础分 1.0,扣除效率和成本
- 迭代惩罚:迭代越少分越高
- Token 惩罚:超出阈值扣分
- 顺畅度奖励:无停滞加分
-
失败分支:基础分 0.0,根据停滞程度扣分
- 停滞迭代越多扣分越多
- 错误类型影响扣分幅度
┌─────────────────────────────────────────────────────────────┐
│ EventBus │
│ (发布-订阅,组件松耦合通信) │
├─────────────────────────────────────────────────────────────┤
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ LLM │ │ Memory │ │ Tools │ │ Heuristics│ │
│ │ Engine │ │ System │ │ │ │ Engine │ │
│ └──────────┘ └──────────┘ └──────────┘ └───────────┘ │
├─────────────────────────────────────────────────────────────┤
│ AgentLoop(主循环) │
│ ┌────────────┐ ┌────────────┐ ┌────────────────────┐ │
│ │ Control │ │ Tool │ │ Prompt │ │
│ │ Loop │ │ Executor │ │ Context Builder │ │
│ └────────────┘ └────────────┘ └────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
| 组件 | 说明 |
|---|---|
| AgentLoop | 事件驱动的核心主循环,协调 LLM、工具、记忆 |
| LLM Engine | 统一 LLM 接口,内置 40+ 模型注册表,自动检测上下文窗口、工具支持、最大输出 |
| ThreeLayerMemory | 三层记忆:人格 + 会话 + FTS5 长期检索 |
| HeuristicEngine | 启发式规则引擎,作为特征提取器为 Bandit 提供输入 |
| ControlLoop | 控制环核心,每轮决策 - 执行 - 反馈 - 学习 |
| ActionBandit | Action 选择器,Thompson Sampling + Heuristic Bias |
| LearningIntegration | 学习模块集成,Policy 选择和参数注入 |
| EventBus | 事件总线,组件间松耦合通信 |
| BaseTool | 工具基类,声明式命令注册模式 |
Agent 通过 FeatureExtractor 实时感知运行状态,动态调整决策策略:
| 状态维度 | 特征 | 说明 |
|---|---|---|
| 进度状态 | progress_score | 任务完成进度估计 (0-1) |
| stuck_iterations | 连续无进展迭代次数 | |
| is_making_progress | 是否在取得进展 | |
| 趋势状态 | progress_trend | EMA 平滑后的进展趋势 (-1 到 1) |
| convergence_rate | 收敛速度 | |
| is_plateau | 是否进入平台期 | |
| 工具状态 | unique_tools_used | 使用过的不同工具数 |
| tool_diversity_score | 工具多样性分数 | |
| repetition_score | 工具重复调用分数 | |
| pattern_detected | 检测到的循环模式 | |
| 上下文状态 | context_saturation | 上下文饱和度 (0-1) |
| context_saturation_level | 饱和等级: idle/normal/warn/redirect/stop | |
| 结果质量 | error_rate | 工具调用错误率 |
| empty_result_rate | 空结果率 | |
| result_quality_score | 结果质量综合分数 | |
| 输出状态 | exact_repetition_count | LLM 输出完全重复次数 |
| is_output_loop | 是否陷入输出循环 |
自适应调整机制:
- 进展停滞检测:stuck_iterations > threshold 时触发 redirect/retry
- 上下文压力感知:saturation > 0.7 时触发 compress,> 0.95 时触发 stop
- 工具循环检测:repetition_score > 0.5 时触发 redirect 换工具
- 输出循环检测:exact_repetition_count >= 5 时强制 terminate
- 动态 HardConstraint:根据状态实时生成控制指令(如 REDIRECT/COMPRESS/RETRY)
| 层级 | 实现 | 说明 |
|---|---|---|
| 人格记忆 | personality.md | 静态人格设定文件 |
| 会话记忆 | MemoryManager | 短期上下文,自动维护有界历史 |
| 长期记忆 | FTS5 + Repository | 向量检索 + 混合召回,支持知识提取和归档 |
轻量级向量模型(96维):
长期记忆使用无需外部依赖的轻量级混合记忆检索系统,通过特征哈希向量与全文检索融合,实现本地高效的语义近似召回:
- 维度:96 维
- 生成方式:基于 SHA1 哈希的局部敏感哈希(LSH)
- 英文:字符 3-gram
- 中文:词级 bigram + 完整拼音哈希 + 拼音 bigram
- 分词(Jieba)+ 关键词提取
- 每个 token 通过 SHA1 哈希映射到 96 维向量桶
- 位置加权(前 8 个 token 额外 +0.25 权重)
- 相似度计算:余弦相似度(cosine similarity)
- 混合召回:FTS5 全文检索 + 向量相似度融合排序
- 中文增强:拼音哈希实现中文谐音、拼音首字母匹配
- 依赖:jieba(中文分词),可选 pypinyin(拼音增强)
| 规则 | 说明 |
|---|---|
| MaxIterationRule | 迭代次数上限终止 |
| TokenBudgetRule | Token 预算耗尽终止 |
| EmptyResultChainRule | 空结果链检测 |
| NoProgressRule | 无进展检测(EMA 平滑) |
| SameToolRepetitionRule | 同工具+参数重复调用检测 |
| PatternLoopRule | 模式循环检测 |
| ParameterSimilarityRule | 参数相似度检测 |
| 功能 | 说明 |
|---|---|
| 自动发现 | 扫描 components/ 目录,自动发现继承 BaseCell 的组件类 |
| 热插拔 | ComponentWatcher 后台监控,3 秒间隔扫描,动态加载/卸载 |
| 工具包装 | ComponentToolRegistry 将 BaseCell 包装为 BaseTool,注入 AgentLoop |
| 信任白名单 | 组件需用户 /trust 确认,持久化到 trusted_components.json |
| 配置自动维护 | 发现新组件自动追加到 settings.yaml 的 enabled_components |
保留工具名(不可被组件覆盖):
shell— ShellToolmemory— MemoryToolfile— FileTool
Cellium Agent 支持运行时自扩展能力,Agent 可在运行时动态创建并注入新组件,无需重启服务,实现Agent自我改装进化。
核心原理:
ComponentWatcher 后台进程每 3 秒扫描 components/ 目录,发现新文件或文件变更后,自动触发加载流程:扫描发现 → 实例化组件类 → 审计合规性 → 写入配置文件 → 注册到工具注册表 → AgentLoop 动态读取。整个过程全自动,新工具立即可用。
组件规范:
组件必须继承 BaseCell,定义唯一的 cell_name 标识,命令方法以 _cmd_ 前缀命名并附带 docstring 描述。文件放入 components/ 目录即自动生效。
组件生成器:
系统内置 ComponentBuilder 组件,Agent 可通过 component.generate 命令快速创建符合规范的组件,自动生成完整的类结构、命令方法和帮助文档。
管理 API:
系统提供完整的组件管理接口,支持扫描发现、热重载、手动加载、卸载等操作,Agent 可通过 API 自主管理自身能力。
目录约定:
components/
├── __init__.py # 包标记
├── _example_component.py # 组件模板参考
├── component_builder.py # 组件生成器(系统内置)
├── skill_installer.py # Skill 安装器(支持从压缩包安装)
├── skill_manager.py # Skill 管理器(列表、搜索、详情、卸载)
└── my_tool.py # Agent 创建的组件(系统级)
支持在 QQBot 和本地之间传输文件:
| 命令 | 功能 | 示例 |
|---|---|---|
download |
从 QQ 下载文件 | {"url": "...", "filename": "doc.pdf"} |
send_file |
发送文件到 QQ | {"target_id": "...", "file_path": "...", "is_group": false} |
send_image |
发送图片到 QQ | {"target_id": "...", "image_path": "..."} |
list_downloads |
列出下载的文件 | {} |
文件保存路径:workspace/downloads/qq/
基于 DrissionPage 的无头浏览器组件,支持网页自动化操作:
| 命令 | 功能 | 示例 |
|---|---|---|
navigate |
访问指定 URL | {"url": "https://example.com"} |
get_screenshot |
截图(支持元素级截图) | {"full_page": false, "selector": "#content"} |
find_qrcode |
查找页面二维码 | {} |
js_action |
页面操作(click/input/scroll_to) | {"selector": "button", "action": "click"} |
find_button |
查找按钮元素 | {"value": "登录"} |
get_page_info |
获取页面信息 | {} |
scroll |
滚动页面 | {"direction": "down", "amount": 500} |
save_cookies / load_cookies |
Cookie 持久化 | {"path": "cookies.json"} |
使用场景:
- 网页内容抓取与分析
- 自动化登录流程(支持二维码识别)
- 网页截图与视觉验证
- 表单自动填写与提交
截图保存路径:workspace/web_fetch_screenshots/域名_时间戳.png
核心机制:
_cell_registry: cell_name → ICell 实例get_all_tools(): AgentLoop 运行时动态读取组件工具get_tool_definitions(): 返回 LLM 格式的工具定义
工具操作可见性:
- 所有工具调用都会生成用户友好的操作描述
- 支持
_intent参数自定义描述(最高优先级) - 示例:
{"command": "read", "path": "test.py", "_intent": "正在读取配置文件"}
完整的 Skill 包管理解决方案,支持从压缩包安装、列表展示、搜索、详情查看和卸载。
安装方式:
- 支持
.zip、.tar.gz、.tgz、.tar格式压缩包 - 压缩包内需包含
SKILL.md文件 - 自动解析
SKILL.md的 YAML Frontmatter 元信息
管理功能:
| 组件 | 功能 | 命令/接口 |
|---|---|---|
skill_installer |
安装 Skill | install_from_archive(path) |
skill_installer |
刷新索引 | refresh_index() |
skill_manager |
列出所有 Skill | list(show_details=True) |
skill_manager |
搜索 Skill | search(query) |
skill_manager |
获取详情 | get_info(name) |
skill_manager |
卸载 Skill | uninstall(name) |
- 设置页面提供 Skill 管理面板
- 支持压缩包上传安装
- 支持按名称、描述、分类过滤
- 详情弹窗展示完整元信息
目录约定:
components/
├── skill_installer.py # Skill 安装器
├── skill_manager.py # Skill 管理器
└── skills/ # Skill 安装目录
├── skill-a/ # 已安装的 Skill
│ └── SKILL.md
├── skill-b/
│ └── SKILL.md
└── _index.json # 索引文件(自动生成)
Cellium-Agent/
├── app/ # 应用核心代码
│ ├── agent/ # Agent 核心模块
│ │ ├── control/ # 控制环:ControlLoop、ActionBandit、FeedbackEvaluator
│ │ ├── events/ # 事件模型与类型定义
│ │ ├── heuristics/ # 启发式引擎:规则、特征提取、评分
│ │ │ └── rules/ # 启发式规则:终止规则、循环检测
│ │ ├── learning/ # 学习模块:BayesianBandit、Policy
│ │ ├── llm/ # LLM 引擎,支持 OpenAI 兼容 API
│ │ ├── loop/ # Agent 主循环:AgentLoop、SessionManager、ToolExecutor
│ │ ├── memory/ # 三层记忆:FTS5、Repository、ArchiveStore
│ │ ├── tools/ # 工具基类与内置工具
│ │ ├── prompt/ # Prompt 构建器
│ │ ├── shell/ # Shell 交互
│ │ ├── security/ # 安全策略
│ │ └── di_config.py # 依赖注入配置
│ ├── channels/ # 通道适配层
│ │ ├── base.py # 通道基类 IChannelAdapter,支持文件消息抽象接口
│ │ ├── channel_manager.py # 通道管理器,消息路由、文件传输与注入
│ │ ├── qq_adapter.py # QQBot 适配器(消息 + 文件传输)
│ │ ├── qq_channel_config.py # QQ 通道配置模型
│ │ ├── telegram_adapter.py # Telegram Bot 适配器(消息 + 文件传输)
│ │ └── telegram_channel_config.py # Telegram 通道配置模型
│ ├── core/ # 核心基础设施
│ │ ├── bus/ # 事件总线 EventBus
│ │ ├── di/ # 依赖注入容器
│ │ ├── interface/ # 核心接口定义
│ │ ├── security/ # 安全模块
│ │ └── util/ # 工具类:ComponentWatcher、Logger 等
│ └── server/ # FastAPI 服务层
│ └── routes/ # API 路由:chat、memory、channels、session_events
├── components/ # 组件目录(热插拔)
│ ├── _example_component.py # 组件模板参考
│ ├── component_builder.py # 组件生成器(系统内置)
│ ├── qq_files.py # QQ 文件传输组件
│ ├── telegram_files.py # Telegram 文件传输组件
│ ├── web_fetch.py # 网页获取组件
│ ├── web_search.py # 网页搜索组件
│ ├── skill_installer.py # Skill 安装器(支持 .zip/.tar.gz 压缩包安装)
│ ├── skill_manager.py # Skill 管理器(列表、搜索、详情、卸载)
│ └── skills/ # Skill 安装目录
├── config/agent/ # 配置文件
│ ├── channels.yaml # 通道配置(QQ、Telegram 等外部平台)
│ └── llm.yaml # LLM 模型配置
├── ui/ # React 前端源码
├── html/ # 前端构建输出
├── memory/ # 记忆存储目录
├── tests/ # 单元测试
└── main.py # 入口文件
Apache 2.0



