{"id":49226015,"url":"https://github.com/cellium-project/cellium-agent","last_synced_at":"2026-05-23T07:12:21.305Z","repository":{"id":350868787,"uuid":"1207614462","full_name":"Cellium-Project/Cellium-Agent","owner":"Cellium-Project","description":"A self-learning, adaptive agent./一个自学习、自适应的agent","archived":false,"fork":false,"pushed_at":"2026-04-24T06:33:09.000Z","size":3158,"stargazers_count":16,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T07:31:24.995Z","etag":null,"topics":["agent","ai","claw","gpt","skill"],"latest_commit_sha":null,"homepage":"https://agent.cellium.top","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cellium-Project.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-11T06:50:37.000Z","updated_at":"2026-04-24T06:29:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Cellium-Project/Cellium-Agent","commit_stats":null,"previous_names":["cellium-project/cellium-agent"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Cellium-Project/Cellium-Agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cellium-Project%2FCellium-Agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cellium-Project%2FCellium-Agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cellium-Project%2FCellium-Agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cellium-Project%2FCellium-Agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cellium-Project","download_url":"https://codeload.github.com/Cellium-Project/Cellium-Agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cellium-Project%2FCellium-Agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32326122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","claw","gpt","skill"],"created_at":"2026-04-24T07:07:04.394Z","updated_at":"2026-05-23T07:12:21.296Z","avatar_url":"https://github.com/Cellium-Project.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cellium Agent\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"logo.png\" width=\"200\" style=\"background:#1e90ff;padding:20px;border-radius:10px;\"\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://www.producthunt.com/products/cellium-agent?utm_source=badge-follow\u0026utm_medium=badge\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://api.producthunt.com/widgets/embed-image/v1/follow.svg?product_id=cellium-agent\u0026theme=light\" alt=\"Cellium-Agent - Product Hunt\" style=\"width: 250px; height: 54px;\" width=\"250\" height=\"54\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n[![Python](https://img.shields.io/badge/Python-3.12%2B-blue)](https://www.python.org/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.100%2B-green)](https://fastapi.tiangolo.com/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-orange)](LICENSE)\n[![React](https://img.shields.io/badge/React-18%2B-61DAFB?logo=react)](https://react.dev/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-3178C6?logo=typescript)](https://www.typescriptlang.org/)\n[![Platform](https://img.shields.io/badge/Platform-Windows%2FmacOS%2FLinux-blue)]()\n\n**这是一个自进化AI Agent**\n\n[English](README_EN.md) | 中文\n\n\u003c/div\u003e\n\n\u003e **传统 Agent 重复犯错、陷入死循环、不会总结经验。所以我们选择让Agent无限进化**\n\n基于微内核架构（EventBus + DI + BaseTool），支持任意 OpenAI 兼容 API\n\n\n核心设计：决策环（Control Loop）驱动的自学习 Agent，通过贝叶斯 Bandit 实现自适应决策优化。\n\n\u003e 感谢 [Strategy Gene](https://arxiv.org/abs/2604.15097) 研究团队，本项目参考并使用了其提出的紧凑经验表示方法，让 Agent 从失败中自动进化，持续优化决策策略。\n\n## 能做什么\n\nCellium Agent 是一个通用的 AI 助手，可以帮助你完成各种任务：\n\n| 功能 | 示例 |\n|------|------|\n| **文件操作** | 读取、写入、搜索文件，管理目录结构 |\n| **代码开发** | 编写代码、调试、重构、解释代码逻辑 |\n| **网页搜索** | 搜索互联网获取实时信息，总结网页内容 |\n| **数据分析** | 处理数据文件，生成报告和可视化 |\n| **自动化任务** | 创建定时任务，如\"每天早上8点查询天气\" |\n| **组件扩展** | 通过自然语言创建新组件，扩展 Agent 能力 |\n| **多平台接入** | 支持 WebUI、QQ、Telegram 等多平台对话 |\n\n**使用示例**：\n- \"帮我读取 workspace 目录下的所有文件，统计每个文件的函数数量\"\n- \"搜索最新的 AI 技术发展动态，并创建一个word组件，总结成一份报告发给我\"\n- \"创建一个定时任务，每小时检查一次服务器状态，当状态异常时自动通知我。\"\n- \"帮我写一个 Python 脚本处理 CSV 文件，自动生成数据可视化图表\"\n- \"创建一个新组件，用于监控股票价格，当价格波动超过 5% 时自动通知我\"\n\n## 特性\n\n| 特性 | 说明 |\n|------|------|\n| Agent 运行时自感知 | 实时感知运行状态（进度、停滞、循环、饱和度），动态调整决策 |\n| 决策环架构 | 每轮决策 - 执行 - 反馈 - 学习的闭环控制 |\n| 自学习系统 | 基于贝叶斯 Bandit 的 Action 选择，持续优化决策策略 |\n| 三层记忆系统 | 人格记忆 + 会话记忆 + 长期记忆（FTS5全文检索 + 96维哈希向量混合召回） |\n| 启发式决策引擎 | 规则提取特征 + Bandit 做 tie-break，兼顾可解释性与学习能力 |\n| 工具使用控制 | 动态禁止/推荐工具切换，避免重复调用同一工具陷入循环 |\n| 敏感信息控制 | 自动检测并脱敏私钥、Token、密码等敏感信息，支持写入拦截 |\n| 组件热插拔 | app/components/ 下文件 3 秒自动加载生效 |\n| 组件沙箱安全 | 三层防护：进程隔离 + 路径透明映射 + 危险方法拦截 |\n| 事件驱动架构 | 基于 EventBus 的发布-订阅模式，组件松耦合 |\n| Flash 模式 | 跳过记忆注入，加速简单任务 |\n| 多通道接入 | 支持 QQ 等外部平台（目前只支持qqbot,telegram,持续更新中），通过 ChannelManager 统一管理消息路由、文件传输与注入 |\n| 定时任务调度 | 支持间隔任务、每日任务、每周任务，通过自然语言创建任务，触发时自动调用 Agent 执行并推送结果到对应平台 |\n| 后台组件事件触发 | 组件可在后台运行并主动触发 Agent 执行任务，支持实时场景（如虚拟币价格监控、实时数据推送、Agent 自动总结分析） |\n\n## 快速开始\n\n### 一键安装启动 (带环境)\n\n\n**Windows:**\n```powershell\npowershell -Command \"Invoke-WebRequest -Uri 'https://github.com/Cellium-Project/Cellium-Agent/releases/latest/download/Cellium-Agent-Windows.zip' -OutFile 'Cellium-Agent-Windows.zip'; Expand-Archive -Path 'Cellium-Agent-Windows.zip' -DestinationPath '.' -Force; cd Cellium-Agent-Windows; .\\CelliumAgent.exe\"\n```\n\n**Linux x64:**\n```bash\ncurl -LO https://github.com/Cellium-Project/Cellium-Agent/releases/latest/download/Cellium-Agent-Linux.tar.gz \u0026\u0026 tar -xzf Cellium-Agent-Linux.tar.gz \u0026\u0026 cd Cellium-Agent-Linux \u0026\u0026 ./start-cellium.sh\n```\n\n**Linux ARM64:**\n```bash\ncurl -LO https://github.com/Cellium-Project/Cellium-Agent/releases/latest/download/Cellium-Agent-Linux-ARM64.tar.gz \u0026\u0026 tar -xzf Cellium-Agent-Linux-ARM64.tar.gz \u0026\u0026 cd Cellium-Agent-Linux-ARM64 \u0026\u0026 ./start-cellium.sh\n```\n\n**macOS:**\n```bash\ncurl -LO https://github.com/Cellium-Project/Cellium-Agent/releases/latest/download/Cellium-Agent-macOS.tar.gz \u0026\u0026 tar -xzf Cellium-Agent-macOS.tar.gz \u0026\u0026 cd Cellium-Agent-macOS \u0026\u0026 ./start-cellium.sh\n```\n\n\u003e 更多安装选项见 [INSTALL.md](INSTALL.md)\n\n### 从源码运行\n\n```bash\npip install -r requirements.txt\npython main.py\n```\n\n主要依赖：\n- FastAPI + Uvicorn（Web 框架）\n- PyYAML（配置解析）\n- Jieba（中文分词）\n- DrissionPage（用于网页搜索和操作浏览器）\n- openai（OpenAI API 客户端）\n- websockets（QQ Bot WebSocket 客户端）\n- httpx（HTTP 客户端，用于外部平台文件上传）\n\n### 配置模型\n\n编辑 `config/agent/llm.yaml` 文件，配置 API 密钥、服务地址和模型名称。\n\n### 启动服务\n\n```bash\npython main.py\n```\n\n启动后访问 http://localhost:18000 打开聊天界面，访问 http://localhost:18000/docs 查看 API 文档。\n（默认端口 18000，如被占用会自动切换，请查看启动日志获取实际端口）\n\n## 核心架构：决策环 + 自学习\n\nCellium Agent 的核心是 **Control Loop（控制环）** 驱动的决策系统，结合 **贝叶斯 Bandit** 实现自学习优化。\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│                           自学习层 (Learning)                            │\n│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────────────┐  │\n│  │   Policy    │    │  Bayesian   │    │      PolicyBanditMemory     │  │\n│  │  Templates  │───▶│   Bandit    │◄───│  (Thompson Sampling 统计)    │  │\n│  │ (策略模板)   │    │ (策略选择)   │    │                             │  │\n│  └─────────────┘    └──────┬──────┘    └─────────────────────────────┘  │\n│                            │                                            │\n└────────────────────────────┼────────────────────────────────────────────┘\n                             │ 选择 Policy\n                             ▼\n┌─────────────────────────────────────────────────────────────────────────┐\n│                          决策环层 (Control Loop)                         │\n│                                                                         │\n│   ┌──────────┐     ┌──────────────┐     ┌──────────────┐               │\n│   │  Step    │────▶│   Feature    │────▶│    Rule      │               │\n│   │ (每轮开始)│     │  Extraction  │     │  Evaluation  │               │\n│   └──────────┘     │  (特征提取)   │     │  (规则评估)   │               │\n│        │           └──────────────┘     └──────┬───────┘               │\n│        │                                        │                       │\n│        │           ┌────────────────────────────┘                       │\n│        │           ▼                                                    │\n│        │     ┌──────────────┐     ┌──────────────┐                     │\n│        │     │   Action     │◄────│   Action     │                     │\n│        │     │  Candidates  │     │   Bandit     │                     │\n│        │     │  (候选动作)   │     │ (Tie-break)  │                     │\n│        │     └──────┬───────┘     └──────────────┘                     │\n│        │            │                                                  │\n│        │            ▼                                                  │\n│        │     ┌──────────────┐                                         │\n│        │     │   Control    │                                         │\n│        │     │   Decision   │                                         │\n│        │     │   (决策输出)  │                                         │\n│        │     └──────┬───────┘                                         │\n│        │            │                                                  │\n│        │     ┌──────┴───────┐     ┌──────────────┐                    │\n│        └────▶│   Execute    │────▶│  End Round   │                    │\n│              │   (执行)      │     │  (每轮结束)   │                    │\n│              └──────────────┘     └──────┬───────┘                    │\n│                                          │                             │\n│                                          ▼                             │\n│                              ┌──────────────────────┐                  │\n│                              │  Feedback Evaluator  │                  │\n│                              │    (反馈评估)         │                  │\n│                              │   - 分段式评估        │                  │\n│                              │   - n-step return    │                  │\n│                              └──────────┬───────────┘                  │\n│                                         │                              │\n│                              ┌──────────┴───────────┐                  │\n│                              ▼                      ▼                  │\n│                    ┌─────────────────┐   ┌─────────────────┐          │\n│                    │   Bandit Update │   │   Stats Persist │          │\n│                    │   (更新统计)     │   │   (持久化)       │          │\n│                    └─────────────────┘   └─────────────────┘          │\n│                                                                         │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n\n\n### 决策环（Control Loop）工作流程\n![决策环](tests/img/1.png)\n每轮循环包含 5 个阶段：\n\n1. **特征提取（Feature Extraction）**\n   - 启发式引擎提取当前状态特征\n   - 包括：停滞迭代数、进展趋势、重复分数、上下文饱和度等\n\n2. **规则评估（Rule Evaluation）**\n   - 硬规则给出 action 候选集合\n   - 例如：检测到循环时候选 [redirect, compress]\n\n3. **Bandit Tie-break（Action 选择）**\n   - 当候选 action 多于 1 个时，Bandit 介入\n   - 使用 Thompson Sampling + Heuristic Bias 选择最优 action\n\n4. **执行与反馈（Execute \u0026 Feedback）**\n   - 执行选中的 action（continue/retry/redirect/compress/terminate）\n   - FeedbackEvaluator 分段式评估本轮表现\n\n5. **学习与更新（Learning \u0026 Update）**\n   - 使用 n-step return 累积 reward\n   - 更新 Bandit 的 Beta 分布参数\n   - 定期衰减旧数据防止过拟合\n\n### PEOP 循环（Plan-Execute-Observe-RePlan 循环）\n\nPEOP 循环是决策环的扩展模块，实现**自适应计划-执行循环**。该模块根据任务复杂度动态调整策略：简单任务直接响应，复杂任务自动启用多步规划；执行过程中持续验证结果，发现偏差时局部重规划，通过显式状态管理实现高效、可靠的任务分解与执行：\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                 计划执行引擎状态机                            │\n│                                                             │\n│  ┌─────────┐    ┌─────────┐    ┌─────────┐                 │\n│  │ OBSERVE │───▶│  PLAN   │───▶│ EXECUTE │◄─────────────┐  │\n│  │  观察   │    │  规划   │    │  执行   │   验证成功    │  │\n│  └─────────┘    └─────────┘    └────┬────┘   继续下一步  │  │\n│       ▲                             │                     │  │\n│       │                      验证失败│                     │  │\n│       │                             ▼                     │  │\n│       │                        ┌─────────┐   重规划成功   │  │\n│       │                        │ REPLAN  │───────────────┘  │\n│       │                        │ 重规划  │                  │  │\n│       │                        └────┬────┘                  │  │\n│       │                             │                     │  │\n│       └─────────────────────────────┘   重规划次数超限      │  │\n│                                         或任务完成          │  │\n│                                         ▼                  │  │\n│                                       ┌─────┐              │  │\n│                                       │DONE │              │  │\n│                                       │完成 │              │  │\n│                                       └─────┘              │  │\n└─────────────────────────────────────────────────────────────┘\n```\n\n**核心机制**：\n\n| 机制 | 说明 |\n|------|------|\n| **批量规划** | 一次生成多步执行计划（1-5步）支持并行执行工具调用（如果无依赖关系），减少 LLM 调用次数 |\n| **状态驱动** | 5阶段显式状态机（OBSERVE/PLAN/EXECUTE/REPLAN/DONE） |\n| **执行内验证** | 每步执行后自动验证结果 |\n| **局部重规划** | 验证失败时保留成功步骤，仅重新规划失败及后续步骤 |\n\n**工作流程**：\n\n1. **观察（OBSERVE）**：分析用户输入，理解任务目标与上下文\n2. **规划（PLAN）**：LLM 生成结构化计划，每步包含：工具名、参数、执行目的、预期结果\n3. **执行（EXECUTE）**：按顺序执行计划步骤，每步执行后自动验证结果\n   - 验证成功 → 继续执行下一步\n   - 验证失败 → 进入 REPLAN 阶段\n4. **重规划（REPLAN）**：保留已成功的步骤，仅对失败及后续步骤重新生成计划\n5. **完成（DONE）**：所有步骤执行成功，或重规划次数超限\n\n**设计特点**：\n- **高效**：多步计划一次生成，执行阶段零 LLM 调用\n- **稳定**：局部重规划避免全盘推翻，保持上下文连续性\n- **可观测**：5阶段状态机提供清晰的执行轨迹，便于调试与监控\n- **协同**：状态信息实时同步给 Control Loop，重规划触发 redirect 决策\n\n**配置参数**：\n- `max_plan_steps=5`：单次规划最多 5 个步骤\n- `max_replans=3`：最多允许 3 次重规划\n\n### Action 类型与策略\n\n代码定义：`ACTION_TYPES = [\"continue\", \"retry\", \"redirect\", \"compress\", \"terminate\"]`\n\n| Action | 说明 | Heuristic Bias 条件 |\n|--------|------|---------------------|\n| continue | 继续当前方向 | 进展分数 \u003e 0.5 或停滞迭代为 0 |\n| retry | 保持方向但修正策略 | 轻微停滞（1 \u003c= stuck \u003c threshold）或进展趋势在 0~0.3 |\n| redirect | 换方向/换工具 | 重复分数 \u003e 0.5 或停滞 \u003e= stuck_threshold |\n| compress | 压缩上下文 | 上下文饱和度 \u003e 0.6 或停滞 \u003e= stuck_threshold // 2 |\n| terminate | 终止会话 | 硬规则触发：输出循环且 exact_repetition_count \u003e= 5 |\n\n\n\n### 自学习机制\n![自学习机制](tests/img/2.png)\n**Policy - Bandit - Action 三层架构**：\n\n```\n┌─────────────────────────────────────────┐\n│           Policy Templates              │\n│  ┌─────────┬───────────┬─────────────┐  │\n│  │ default │ efficient │ aggressive  │  │\n│  │ 平衡策略 │  高效策略  │   激进策略   │  │\n│  │(stuck=3)│ (stuck=2) │  (stuck=5)  │  │\n│  └────┬────┴─────┬─────┴──────┬──────┘  │\n│       │          │            │         │\n│       ▼          ▼            ▼         │\n│  ┌─────────────────────────────────┐    │\n│  │      Bayesian Bandit            │    │\n│  │  Thompson Sampling 选择最优 Policy │   │\n│  │  - 从 Beta 分布采样              │    │\n│  │  - 选择期望收益最高的 Policy      │    │\n│  └─────────────┬───────────────────┘    │\n│                │                        │\n│                ▼                        │\n│  ┌─────────────────────────────────┐    │\n│  │        Action Bandit            │    │\n│  │  在候选 action 内做 tie-break    │    │\n│  │  - Heuristic 提供 bias          │    │\n│  │  - 动态调整阈值参数              │    │\n│  └─────────────────────────────────┘    │\n└─────────────────────────────────────────┘\n```\n\n**学习过程**：\n\n1. **Policy 选择**：会话开始时，Bayesian Bandit 从多个 Policy（default/efficient/aggressive）中选择当前最优策略\n2. **阈值注入**：选中的 Policy 参数（如 stuck_iterations=3）注入 HeuristicEngine 和 ActionBandit\n3. **Action 学习**：每轮结束后，根据 FeedbackEvaluator 的评分更新 Action 的 Beta 分布\n4. **n-step return**：累积最近 n 轮的 reward，支持延迟反馈和序列优化\n5. **数据衰减**：每 50 个会话衰减一次旧数据（衰减因子 0.99），防止过拟合\n\n### 反馈评估（Feedback Evaluation）\n\n采用**分段式设计**，先区分成功/失败，再优化细节：\n\n- **成功分支**：基础分 1.0，扣除效率和成本\n  - 迭代惩罚：迭代越少分越高\n  - Token 惩罚：超出阈值扣分\n  - 顺畅度奖励：无停滞加分\n\n- **失败分支**：基础分 0.0，根据停滞程度扣分\n  - 停滞迭代越多扣分越多\n  - 错误类型影响扣分幅度\n\n## 微内核架构\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                        EventBus                              │\n│              (发布-订阅，组件松耦合通信)                      │\n├─────────────────────────────────────────────────────────────┤\n│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────┐  │\n│  │  LLM     │  │  Memory  │  │  Tools   │  │ Heuristics│  │\n│  │  Engine  │  │  System  │  │          │  │  Engine   │  │\n│  └──────────┘  └──────────┘  └──────────┘  └───────────┘  │\n├─────────────────────────────────────────────────────────────┤\n│                     AgentLoop（主循环）                      │\n│  ┌────────────┐  ┌────────────┐  ┌────────────────────┐    │\n│  │   Control   │  │   Tool    │  │   Prompt           │    │\n│  │   Loop      │  │  Executor │  │   Context Builder  │    │\n│  └────────────┘  └────────────┘  └────────────────────┘    │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 核心组件\n\n| 组件 | 说明 |\n|------|------|\n| AgentLoop | 事件驱动的核心主循环，协调 LLM、工具、记忆 |\n| LLM Engine | 统一 LLM 接口，内置 40+ 模型注册表，自动检测上下文窗口、工具支持、最大输出 |\n| ThreeLayerMemory | 三层记忆：人格 + 会话 + FTS5 长期检索 |\n| HeuristicEngine | 启发式规则引擎，作为特征提取器为 Bandit 提供输入 |\n| ControlLoop | 控制环核心，每轮决策 - 执行 - 反馈 - 学习 |\n| ActionBandit | Action 选择器，Thompson Sampling + Heuristic Bias |\n| LearningIntegration | 学习模块集成，Policy 选择和参数注入 |\n| EventBus | 事件总线，组件间松耦合通信 |\n| BaseTool | 工具基类，声明式命令注册模式 |\n\n### 组件沙箱安全机制\n\nAgent 编写的组件代码在独立的沙箱环境中运行，采用三层安全防护：\n\n| 层级 | 机制 | 作用 |\n|------|------|------|\n| **进程隔离** | 组件在独立子进程运行 | 崩溃不影响主程序，通过 Queue 通信 |\n| **路径透明映射** | 文件操作路径映射到 sandbox_root | 防路径穿越，保护真实系统文件 |\n| **危险方法拦截** | 运行时拦截 os.system/subprocess 等 | 禁止执行系统命令 |\n\n组件可以正常使用 `open()`、`os.listdir()` 等文件操作，但路径会被透明映射到项目目录下的 `sandbox_root/` 文件夹中。同时 `os.system()`、`subprocess.run()` 等危险方法会被拦截。\n\n### Agent 运行时自状态感知\n\nAgent 通过 FeatureExtractor 实时感知运行状态，动态调整决策策略：\n\n| 状态维度 | 特征 | 说明 |\n|----------|------|------|\n| **进度状态** | progress_score | 任务完成进度估计 (0-1) |\n| | stuck_iterations | 连续无进展迭代次数 |\n| | is_making_progress | 是否在取得进展 |\n| **趋势状态** | progress_trend | EMA 平滑后的进展趋势 (-1 到 1) |\n| | convergence_rate | 收敛速度 |\n| | is_plateau | 是否进入平台期 |\n| **工具状态** | unique_tools_used | 使用过的不同工具数 |\n| | tool_diversity_score | 工具多样性分数 |\n| | repetition_score | 工具重复调用分数 |\n| | pattern_detected | 检测到的循环模式 |\n| **上下文状态** | context_saturation | 上下文饱和度 (0-1) |\n| | context_saturation_level | 饱和等级: idle/normal/warn/redirect/stop |\n| **结果质量** | error_rate | 工具调用错误率 |\n| | empty_result_rate | 空结果率 |\n| | result_quality_score | 结果质量综合分数 |\n| **输出状态** | exact_repetition_count | LLM 输出完全重复次数 |\n| | is_output_loop | 是否陷入输出循环 |\n\n**自适应调整机制**：\n\n1. **进展停滞检测**：stuck_iterations \u003e threshold 时触发 redirect/retry\n2. **上下文压力感知**：saturation \u003e 0.7 时触发 compress，\u003e 0.95 时触发 stop\n3. **工具循环检测**：repetition_score \u003e 0.5 时触发 redirect 换工具\n4. **输出循环检测**：exact_repetition_count \u003e= 5 时强制 terminate\n5. **动态 HardConstraint**：根据状态实时生成控制指令（如 REDIRECT/COMPRESS/RETRY）\n\n\n\n### 三层记忆\n![记忆系统](tests/img/3.png)\n| 层级 | 实现 | 说明 |\n|------|------|------|\n| 人格记忆 | personality.md | 静态人格设定文件 |\n| 会话记忆 | MemoryManager | 短期上下文，自动维护有界历史 |\n| 长期记忆 | FTS5 + Repository | 向量检索 + 混合召回，支持知识提取和归档 |\n\n**轻量级向量模型（96维）**：\n\n长期记忆使用无需外部依赖的轻量级混合记忆检索系统，通过特征哈希向量与全文检索融合，实现本地高效的语义近似召回：\n\n- **维度**：96 维\n- **生成方式**：基于 SHA1 哈希的向量编码\n  - 英文：字符 3-gram\n  - 中文：词级 bigram + 完整拼音哈希 + 拼音 bigram\n  - 分词（Jieba）+ 关键词提取\n  - 每个 token 通过 SHA1 哈希映射到 96 维向量桶\n  - 位置加权（前 8 个 token 额外 +0.25 权重）\n- **相似度计算**：余弦相似度（cosine similarity）\n- **混合召回**：FTS5 全文检索 + 向量相似度融合排序\n- **中文增强**：拼音哈希实现中文谐音、拼音首字母匹配\n- **依赖**：jieba（中文分词），可选 pypinyin（拼音增强）\n\n**结构化 Schema 与分类系统**：\n\n长期记忆采用分层分类设计，Schema 类型决定数据结构，Category 分类决定内容类型：\n\n**Schema 类型（4种）**：\n\n| Schema 类型 | 用途 | 包含的 Category |\n|-------------|------|-----------------|\n| `general` | 通用记忆、会话笔记 | `general`, `user_info`, `command`, `project` |\n| `profile` | 用户画像 | `preference` |\n| `project` | 项目相关 | `project` |\n| `issue` | 问题排查 | `troubleshooting`, `code` |\n\n**Category 分类（8种）**：\n\n| Category | 说明 | 来源 |\n|----------|------|------|\n| `general` | 日常对话、知识问答 | 通用记忆 |\n| `user_info` | 用户偏好、会话目标 | 会话笔记 (goal/goal_history) |\n| `command` | 已执行的操作命令 | 会话笔记 (completed) |\n| `project` | 项目配置、关键发现 | 通用记忆 / 会话笔记 (finding) |\n| `preference` | 用户画像信息 | 通用记忆 |\n| `troubleshooting` | 故障记录、解决方案 | 通用记忆 / 会话笔记 (error) |\n| `code` | 代码相关记录 | 通用记忆 / 会话笔记 |\n\n**会话压缩自动提取**：\n\n会话压缩时自动提取以下类型的笔记，并映射到相应 Category 存入长期记忆：\n- `goal` / `goal_history` → `user_info`\n- `completed` → `command` / `code`\n- `finding` → `project` / `code` / `command`\n- `error` → `troubleshooting`\n- `pending` → `general`\n\n**敏感信息控制**：\n\n记忆系统内置敏感信息检测与保护机制：\n\n- **自动检测**：识别私钥、AWS 密钥、GitHub Token、API Key 等敏感内容\n- **脱敏处理**：自动将敏感值替换为 `[REDACTED]`\n- **写入拦截**：高风险敏感信息（如私钥）默认禁止写入记忆\n- **分类标记**：敏感记忆会被标记，支持检索时过滤排除\n\n### 启发式决策规则\n\n| 规则 | 说明 |\n|------|------|\n| MaxIterationRule | 迭代次数上限终止 |\n| TokenBudgetRule | Token 预算耗尽终止 |\n| EmptyResultChainRule | 空结果链检测 |\n| NoProgressRule | 无进展检测（EMA 平滑） |\n| SameToolRepetitionRule | 同工具+参数重复调用检测 |\n| PatternLoopRule | 模式循环检测 |\n| ParameterSimilarityRule | 参数相似度检测 |\n\n### 组件系统\n\n| 功能 | 说明 |\n|------|------|\n| 自动发现 | 扫描 components/ 目录，自动发现继承 BaseCell 的组件类 |\n| 热插拔 | ComponentWatcher 后台监控，3 秒间隔扫描，动态加载/卸载 |\n| 工具包装 | ComponentToolRegistry 将 BaseCell 包装为 BaseTool，注入 AgentLoop |\n| 信任白名单 | 组件需用户 /trust 确认，持久化到 trusted_components.json |\n| 配置自动维护 | 发现新组件自动追加到 settings.yaml 的 enabled_components |\n\n**保留工具名**（不可被组件覆盖）：\n- `shell` — ShellTool\n- `memory` — MemoryTool\n- `file` — FileTool\n\n### 原生组件自扩展\n\nCellium Agent 支持**运行时自扩展**能力，Agent 可在运行时动态创建并注入新组件，无需重启服务，实现Agent自我改装进化。\n\n**核心原理**：\n\nComponentWatcher 后台进程每 3 秒扫描 `components/` 目录，发现新文件或文件变更后，自动触发加载流程：扫描发现 → 实例化组件类 → 审计合规性 → 写入配置文件 → 注册到工具注册表 → AgentLoop 动态读取。整个过程全自动，新工具立即可用。\n\n**组件规范**：\n\n组件必须继承 BaseCell，定义唯一的 cell_name 标识，命令方法以 `_cmd_` 前缀命名并附带 docstring 描述。文件放入 `components/` 目录即自动生效。\n\n**组件生成器**：\n\n系统内置 ComponentBuilder 组件，Agent 可通过 `component.generate` 命令快速创建符合规范的组件，自动生成完整的类结构、命令方法和帮助文档。\n\n**管理 API**：\n\n系统提供完整的组件管理接口，支持扫描发现、热重载、手动加载、卸载等操作，Agent 可通过 API 自主管理自身能力。\n\n**目录约定**：\n```\ncomponents/\n├── __init__.py              # 包标记\n├── _example_component.py    # 组件模板参考\n├── component_builder.py     # 组件生成器（系统内置）\n├── skill_installer.py       # Skill 安装器（支持从压缩包安装）\n├── skill_manager.py         # Skill 管理器（列表、搜索、详情、卸载）\n└── my_tool.py               # Agent 创建的组件（系统级）\n```\n\n### QQBot 文件传输组件 (qq_files)\n\n支持在 QQBot 和本地之间传输文件：\n\n| 命令 | 功能 | 示例 |\n|------|------|------|\n| `download` | 从 QQ 下载文件 | `{\"url\": \"...\", \"filename\": \"doc.pdf\"}` |\n| `send_file` | 发送文件到 QQ | `{\"target_id\": \"...\", \"file_path\": \"...\", \"is_group\": false}` |\n| `send_image` | 发送图片到 QQ | `{\"target_id\": \"...\", \"image_path\": \"...\"}` |\n| `list_downloads` | 列出下载的文件 | `{}` |\n\n**文件保存路径**：`workspace/downloads/qq/`\n\n### 原生览器操作组件 (web_fetch)\n![操作演示](tests/img/qq.png)\n基于 DrissionPage 的无头浏览器组件，支持网页自动化操作：\n\n| 命令 | 功能 | 示例 |\n|------|------|------|\n| `navigate` | 访问指定 URL | `{\"url\": \"https://example.com\"}` |\n| `get_screenshot` | 截图（支持元素级截图） | `{\"full_page\": false, \"selector\": \"#content\"}` |\n| `find_qrcode` | 查找页面二维码 | `{}` |\n| `js_action` | 页面操作（click/input/scroll_to） | `{\"selector\": \"button\", \"action\": \"click\"}` |\n| `find_button` | 查找按钮元素 | `{\"value\": \"登录\"}` |\n| `get_page_info` | 获取页面信息 | `{}` |\n| `scroll` | 滚动页面 | `{\"direction\": \"down\", \"amount\": 500}` |\n| `save_cookies` / `load_cookies` | Cookie 持久化 | `{\"path\": \"cookies.json\"}` |\n\n**使用场景**：\n- 网页内容抓取与分析\n- 自动化登录流程（支持二维码识别）\n- 网页截图与视觉验证\n- 表单自动填写与提交\n\n**截图保存路径**：`workspace/web_fetch_screenshots/域名_时间戳.png`\n\n**核心机制**：\n- `_cell_registry`: cell_name → ICell 实例\n- `get_all_tools()`: AgentLoop 运行时动态读取组件工具\n- `get_tool_definitions()`: 返回 LLM 格式的工具定义\n\n**工具操作可见性**：\n- 所有工具调用都会生成用户友好的操作描述\n- 支持 `_intent` 参数自定义描述（最高优先级）\n- 示例：`{\"command\": \"read\", \"path\": \"test.py\", \"_intent\": \"正在读取配置文件\"}`\n\n### Skill 管理系统 (skill_installer + skill_manager)\n\n完整的 Skill 包管理解决方案，支持从压缩包安装、列表展示、搜索、详情查看和卸载。\n\n**安装方式**：\n- 支持 `.zip`、`.tar.gz`、`.tgz`、`.tar` 格式压缩包\n- 压缩包内需包含 `SKILL.md` 文件\n- 自动解析 `SKILL.md` 的 YAML Frontmatter 元信息\n\n**管理功能**：\n\n| 组件 | 功能 | 命令/接口 |\n|------|------|-----------|\n| `skill_installer` | 安装 Skill | `install_from_archive(path)` |\n| `skill_installer` | 刷新索引 | `refresh_index()` |\n| `skill_manager` | 列出所有 Skill | `list(show_details=True)` |\n| `skill_manager` | 搜索 Skill | `search(query)` |\n| `skill_manager` | 获取详情 | `get_info(name)` |\n| `skill_manager` | 卸载 Skill | `uninstall(name)` |\n\n**前端界面**：\n![skill](tests/img/4.png)\n- 设置页面提供 Skill 管理面板\n- 支持压缩包上传安装\n- 支持按名称、描述、分类过滤\n- 详情弹窗展示完整元信息\n\n**目录约定**：\n```\ncomponents/\n├── skill_installer.py        # Skill 安装器\n├── skill_manager.py          # Skill 管理器\n└── skills/                   # Skill 安装目录\n    ├── skill-a/              # 已安装的 Skill\n    │   └── SKILL.md\n    ├── skill-b/\n    │   └── SKILL.md\n    └── _index.json           # 索引文件（自动生成）\n    \n```\n\n### 定时任务调度 (scheduler)\n\n![定时任务](tests/img/5.png)\n\n支持三种任务类型：\n\n| 类型 | 说明 | 示例 |\n|------|------|------|\n| 间隔任务 | 每隔固定时间执行一次 | 每30分钟提醒喝水 |\n| 每日任务 | 每天固定时间执行 | 每天9点发送日报 |\n| 每周任务 | 每周固定时间执行 | 每周一10点发送周报 |\n\n**使用方式**：通过自然语言创建定时任务，任务触发时 Agent 会自动执行任务内容。支持复杂任务场景：\n- \"每隔1小时检查服务器状态并汇报结果\"\n- \"每天早上8点查询今日天气\"\n- \"每周五下午5点总结本周工作进度\"\n\n任务执行结果会自动推送到创建任务的平台（WebUI/QQ/Telegram）。\n\n### 后台组件事件触发\n\n组件可以在后台运行并主动触发 Agent 执行任务，实现实时数据推送和自动分析。\n\n**实时场景示例**：\n- 虚拟币价格监控：检测到价格突破阈值时推送数据，Agent 自动分析趋势\n- 服务器状态监控：CPU/内存异常时推送告警，Agent 生成诊断报告\n- 实时新闻订阅：检测到关键词新闻时推送，Agent 自动总结要点\n- 数据库变更监听：关键数据变化时推送，Agent 执行相应处理逻辑\n\n事件触发结果会自动推送到对应的 session（WebUI/QQ/Telegram）。\n\n\n## 目录结构\n\n```\nCellium-Agent/\n├── app/                        # 应用核心代码\n│   ├── agent/                  # Agent 核心模块\n│   │   ├── control/            # 控制环：ControlLoop、ActionBandit、FeedbackEvaluator\n│   │   ├── events/             # 事件模型与类型定义\n│   │   ├── heuristics/         # 启发式引擎：规则、特征提取、评分\n│   │   │   └── rules/          # 启发式规则：终止规则、循环检测\n│   │   ├── learning/           # 学习模块：BayesianBandit、Policy\n│   │   ├── llm/                # LLM 引擎，支持 OpenAI 兼容 API\n│   │   ├── loop/               # Agent 主循环：AgentLoop、SessionManager、ToolExecutor\n│   │   ├── memory/             # 三层记忆：FTS5、Repository、ArchiveStore\n│   │   ├── tools/              # 工具基类与内置工具\n│   │   ├── prompt/             # Prompt 构建器\n│   │   ├── shell/              # Shell 交互\n│   │   ├── security/           # 安全策略\n│   │   └── di_config.py        # 依赖注入配置\n│   ├── channels/               # 通道适配层\n│   │   ├── base.py             # 通道基类 IChannelAdapter，支持文件消息抽象接口\n│   │   ├── channel_manager.py  # 通道管理器，消息路由、文件传输与注入\n│   │   ├── qq_adapter.py       # QQBot 适配器（消息 + 文件传输）\n│   │   ├── qq_channel_config.py # QQ 通道配置模型\n│   │   ├── telegram_adapter.py # Telegram Bot 适配器（消息 + 文件传输）\n│   │   └── telegram_channel_config.py # Telegram 通道配置模型\n│   ├── core/                   # 核心基础设施\n│   │   ├── bus/                # 事件总线 EventBus\n│   │   ├── di/                 # 依赖注入容器\n│   │   ├── interface/          # 核心接口定义\n│   │   ├── security/           # 安全模块\n│   │   └── util/               # 工具类：ComponentWatcher、Logger 等\n│   └── server/                 # FastAPI 服务层\n│       └── routes/             # API 路由：chat、memory、channels、session_events\n├── components/                 # 组件目录（热插拔）\n│   ├── _example_component.py   # 组件模板参考\n│   ├── component_builder.py    # 组件生成器（系统内置）\n│   ├── qq_files.py             # QQ 文件传输组件\n│   ├── telegram_files.py       # Telegram 文件传输组件\n│   ├── web_fetch.py            # 网页获取组件\n│   ├── web_search.py           # 网页搜索组件\n│   ├── skill_installer.py      # Skill 安装器（支持 .zip/.tar.gz 压缩包安装）\n│   ├── skill_manager.py        # Skill 管理器（列表、搜索、详情、卸载）\n│   └── skills/                 # Skill 安装目录\n├── config/agent/               # 配置文件\n│   ├── channels.yaml           # 通道配置（QQ、Telegram 等外部平台）\n│   └── llm.yaml                # LLM 模型配置\n├── ui/                         # React 前端源码\n├── html/                       # 前端构建输出\n├── memory/                     # 记忆存储目录\n├── tests/                      # 单元测试\n└── main.py                     # 入口文件\n```\n\n## Strategy Gene (GEP) 集成\n\nCellium Agent --- **2026-04-22** 引入 [Strategy Gene](https://arxiv.org/abs/2604.15097) 论文设计理念。\n\n### 实现方式\n\n论文提出将经验编码为紧凑的 Gene 对象（~230 tokens），替代文档型 Skill 包（~2,500 tokens）。本项目在 Control Loop 的 Hard Constraint 层实现：\n\n- **任务匹配**：用户输入关键词匹配 Gene 模板\n- **动态注入**：匹配到的 Gene 作为系统提示注入 LLM\n- **经验进化**：失败时自动提取 Avoid_Cues 并更新 Gene\n\n### 实现的功能\n\n| 论文概念 | 本项目实现 |\n|----------|-----------|\n| Gene 结构 | `[HARD CONSTRAINTS]` + `[CONTROL ACTION]` + `[AVOID]` |\n| 任务匹配 | `TaskSignalMatcher` 关键词匹配 |\n| Avoid_Cues | 从失败反馈自动提取，写入 `[AVOID]` 段 |\n| 版本管理 | `version` 字段 + `evolution_history` 记录变更 |\n| 效果评估 | `success_rate`, `avg_reward`, `consecutive_success/failure` |\n| 交叉组合 | `GeneComposer` 多任务时合并多个 Gene |\n\n## License\n\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcellium-project%2Fcellium-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcellium-project%2Fcellium-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcellium-project%2Fcellium-agent/lists"}