Skip to content

sunkwei/tea_agent

Repository files navigation

TeaAgent v0.7.23

TeaAgent 是一个自主进化型智能助手,基于 OpenAI 兼容 Function Calling 接口。核心特色:可自我扩展工具库系统提示词自我进化双模式人格切换三层认知系统(记忆/反思/潜意识)。

核心 10 个轻量依赖(openai、numpy、markdown、tkinterweb、pyautogui、mss、Pillow、requests、beautifulsoup4、tkhtmlview),OCR/TTS/ASR 为可选扩展。仅依赖 Python tk 库,无需浏览器,极致轻量。绝大部分代码由 LLM 自行生成,是一个「AI 写 AI」的实验项目。(目前主要使用 deepseek v4 pro 模型自主进化,便宜啊)

⚠️ 安全警告

本项目未作安全沙盒——Agent 可执行任意系统命令(sudo权限命令会弹出输入口令的对话框)、修改自身代码(做好 git 版本管理)。建议在虚拟机中运行。


🏗️ 架构总览

自动重启(watchdog 文件监控)

非 toolkit 目录下的 .py 代码变更后,防抖 2 秒自动重启 GUI,无需手动操作:

文件变更 → watchdog 检测 → 2s 防抖 → _shutting_down 闸门
    → 等待 _sess_lock(最长10s,确保 DB 写入完成)
    → WAL checkpoint + close DB
    → os.execv() 原地重启

toolkit/ 下的工具修改走 toolkit_reload() 热更,不触发重启。

历史加载三级策略

load_history() 对对话历史按时间远近做三级渐进式加载,在上下文连贯与 token 节省间取得平衡:

conversations (全部)
    │
    ├─ Level 3 摘要  ──→ Semantic Summary(用户偏好/关键结论)+ Tool-Chain Summary(工具调用链摘要)
    │
    ├─ Level 2 语义相关 ──→ 与当前任务语义相关保留完整 user+assistant,弱相关轻度摘要,无关丢弃
    │
    └─ Level 1 最新一轮 ──→ user + assistant function_call + tool返回 + assistant最终回答,完整保留
层级 内容 策略
Level 1 最新一轮 完整保留(含 function_call / tool结果 / reasoning_content)
Level 2 语义相关轮次 相关→完整保留,弱相关→轻度摘要,无关→丢弃
Level 3 摘要层 Semantic Summary + Tool-Chain Summary

对话流程(单次 chat_stream)

用户输入 → Pipeline ────────────────────────────────────────→ 输出
              │                                                  │
              ├─ ① 记忆注入 (inject_memories)                   │
              │    CRITICAL 指令无条件注入                        │
              │    其余按 相关性×重要度×最近访问 排序               │
              │                                                  │
              ├─ ② 添加用户消息 (add_user_message)               │
              │                                                  │
              ├─ ③ 构建最终 prompt                              │
              │    Level 1 + Level 2 + Level 3 拼接              │
              │                                                  │
              └─ ④ 工具调用循环 (tool_loop)                      │
                   ├─ build_api_messages()                       │
                   │   system_prompt → memory → summary → recent │
                   ├─ API stream (主模型)                         │
                   ├─ tool_calls? → 执行 → reload → 回到循环     │
                   │   └─ 输出实时截断 (stdout≤4k/stderr≤500)   │
                   └─ 最终文本 → 结束                             │
                          │
                          ↓ (异步)
                   ┌──────┴──────┐
                   │ 记忆提取      │ 反思触发
                   │ (便宜模型)    │ (便宜模型)
                   └──────┴──────┘

工具模块化:Skill 系统

38 个工具按场景分为 7 个 Skill,按需激活以节省 token:

Skill (激活条件)                    工具数   默认
──────────────────────────────────────────────────
🎛️  CORE (始终激活)                   5      ✅    save/reload/rollback/list_versions/skill
📁  file_system (文件/命令操作)        4      ✅    file/exec/sudo_gui/pkg
⏰  utility (时间日期)                 3      ✅    gettime/date_diff/lunar
🧠  memory_knowledge (记忆/知识库)    7      ✅    memory/kb/reflection/proactive/subconscious/explr/mode
🔧  self_evolution (自我进化)         10            self_evolve/build/bump_version/...
🖥️  desktop_automation (截图/OCR)      4            screenshot/ocr/input/notify
🔊  interaction (语音/搜索/知识)        3            speak/listen/search
  • 默认场景(纯对话):约 19 工具激活
  • 自动激活:用户输入触发词 → 对应 Skill 自动激活
  • 手动控制toolkit_skill(action='activate', name='self_evolution')

Token 优化:双层压缩

单轮对话中,apt installgradle buildsdkmanager 等工具输出动辄数千行日志,全部保留在上下文中会造成巨大 token 浪费。TeaAgent 通过双层压缩解决:

第一层 (toolkit_exec 实时截断)          第二层 (basesession.load_history)
  stdout ≤ 4000字符 / 80行             加载历史时智能压缩
  stderr ≤ 500字符 / 20行               短输出原样,长输出→首尾+摘要
          ↓                                       ↓
  当前轮 LLM 可见                       旧轮次上下文 ≤600字符
          ↓                                       ↓
    145k token/轮                        → 预计 <15k/轮 (-90%)

压缩保留关键信号:✅ BUILD SUCCESSFUL⚠ 错误行📦 packages installed📝 files changed,上下文连贯不受影响。

类继承体系(Mixin 组合模式)

BaseChatSession          ← 消息管理、中断、基础工具构建
    ↑
    ├─ SessionSummarizerMixin  ← 历史摘要、Topic摘要
    ├─ SessionToolMixin        ← 工具执行、rounds收集
    ├─ SessionAPIMixin         ← API调用、流式处理、token统计
    ├─ SessionMemoryMixin      ← 记忆注入、自动提取
    └─ OnlineToolSession       ← 组合以上,编排完整流程
         ├─ SessionPipeline    ← 插件化步骤管理器
         ├─ MemoryManager      ← 记忆选择/格式化/去重
         ├─ ReflectionManager  ← 元认知反思
         └─ SystemPromptManager ← 动态提示词进化

工具箱分层管理

工具分为内置用户两级:

内置工具箱 (tea_agent/toolkit/)  ← git 管理
  ├─ 38 工具,编译验证 + 测试保护
  └─ 版本通过 git 追踪,支持回滚

用户工具箱 (~/.tea_agent/toolkit/)  ← 手动备份
  ├─ _my 后缀工具:用户明确创建的永久工具
  └─ 自进化实验工具:多次使用后可迁移到内置
规则 说明
"我的"工具 toolkit_xxx_my → 永久存放在用户工具箱,不合并到内置
自进化工具 默认进用户工具箱,多次使用后手动迁移到内置
备份策略 内置 git 管理,用户手动备份
无 bak 两边都不保留 .bak 文件

数据模型

SQLite (chat_history.db)
├── topics             ← 会话主题 (title, summary, created_at)
├── conversations      ← 对话记录 (user_msg, ai_msg, rounds_json)
├── memories           ← 长期记忆 (content, category, priority, tags)
├── reflections        ← 反思记录 (suggestions, prompt_adjustment)
├── prompt_versions    ← 提示词版本 (content, version, created_at)
└── config_history     ← 配置变更记录

嵌入向量 (Embedding)

每条用户消息自动生成向量并存入 SQLite,支持语义搜索。采用 numpy float32 BLOB 格式,1024 维向量仅 4KB(比 JSON 字符串格式节省 69%)。

save_msg(text) → _auto_embed_async() ── 后台线程 ──→ embed()
                                                        │
                                                   向量存入 conversations.embedding (BLOB)
特性 说明
自动嵌入 save_msg() 内嵌钩子,消息存入后自动触发,daemon 线程非阻塞
API 引擎 OpenAI 兼容 /v1/embeddings_build_url() 自动补全 /v1 前缀
本地回退 TF-IDF 256 维,API 不可用时自动降级
存储格式 numpy.float32 → BLOB,4KB/条(JSON 格式 ~13KB → 节省 69%)
语义搜索 查询词自动向量化 → 余弦相似度 → Top-K 匹配结果

配置

embedding:
  api_key: "sk-xxx"                # 可选,不配置则 TF-IDF 回退
  api_url: "https://api.siliconflow.cn/v1"
  model_name: "Qwen/Qwen3-Embedding-4B"
  dimension: 1024                  # 向量维度(自动检测)

🎭 双模式人格系统

Agent 支持两种思考风格,基于用户输入关键词自动检测并瞬间切换

模式 🎯 严谨收敛 (pragmatic) 🎨 自由发散 (creative)
用途 代码开发 / bug排查 / 需求遵从 创意设计 / 头脑风暴 / 异想天开
关键词 bug, 修复, 代码, 测试, 实现, 验证 创意, 想象, 如果, 故事, 科幻, 灵感
思维 结构化·逐步验证·边界条件 跨域联想·反向思维·极端假设
输出 表格·代码块·精确指令 隐喻·类比·画面感
工具倾向 exec, self_evolve, run_tests search, kb, speak, subconscious

工作原理

  1. 每次对话开始时(或手动调用 toolkit_mode),文本通过两级打分(子串匹配 + 整词匹配 + 句式检测)
  2. 检测到的模式以 CRITICAL (priority=0) 注入记忆,确保每轮 API 调用的系统提示词顶部可见
  3. 模式不变时不重复切换(去重)
  4. 与潜意识引擎的场景检测共享 pragmatic/creative/mixed 三态
# 自动检测并切换
toolkit_mode(action="auto", text="修复 Wayland 下的参数解析 bug")  # → pragmatic
toolkit_mode(action="auto", text="如果 AI 会做梦,它的梦境是什么样")  # → creative

# 手动切换
toolkit_mode(action="switch", mode="creative")

🧠 三层认知系统

① 记忆 (Memory)

自动从对话中提取关键信息,并在后续对话顶部注入。

属性 说明
触发阈值 memory_extraction_threshold=1 每轮对话都提取
注入上限 5条 CRITICAL 无条件全部入选
去重阈值 memory_dedup_threshold=0.3 Jaccard 相似度 > 0.3 视为重复
分词引擎 jieba 精确模式 从 bigram 窗口升级,中文匹配质变

注入规则相关性 × 重要度 × 最近访问 × 优先级因子

② 反思 (Reflection)

追踪工具调用链,积累后触发元认知分析,生成改进建议。

会话 Trace → 便宜模型分析 → JSON 反思报告
                              ├── summary / details / suggestions
                              ├── prompt_adjustment → 触发提示词进化
                              └── config_adjustments / new_memories

③ 潜意识引擎 (Subconscious v2.1)

后台守护进程,每 1 小时循环执行:

消化记忆 → 消化对话 → 交叉关联 → 生成洞察 → 设定目标
    │                      │
    └── 场景检测 ──────────┘
         bug多 → pragmatic
         创意多 → creative
         均衡 → mixed
  • Dream 创意火花:跨域碰撞、反向思维、极端假设、隐喻映射
  • 主动通知:important 级洞察触发桌面 notify-send
  • 洞察输出到 ~/.tea_agent/kb/潜意识洞察.md
  • 火花输出到 ~/.tea_agent/kb/创意火花.md

📝 系统提示词架构:活的、自我进化的 Prompt

TeaAgent 的系统提示词不是写死的静态文本——它是一个多层次的、随对话推进持续演化的动态结构。

API 消息组装顺序

每次调用主模型时,_build_api_messages() 按以下顺序拼装:

┌──────────────────────────────────────────────────┐
│ ① 系统提示词 (动态版本)                             │
│    └─ SystemPromptManager 从 DB 加载最新版         │
│    └─ + Skill 摘要("当前激活的技能: [file_system]…")│
│    └─ + Skill 领域指令(每个激活 Skill 的 prompt)   │
├──────────────────────────────────────────────────┤
│ ② 长期记忆注入                                     │
│    └─ CRITICAL 记忆无条件全部注入(如人格模式)       │
│    └─ 普通记忆按 相关性×重要度×最近访问 排序,≤5 条   │
├──────────────────────────────────────────────────┤
│ ③ 历史摘要 (Level 3)                              │
│    └─ Semantic Summary + Tool-Chain Summary       │
├──────────────────────────────────────────────────┤
│ ④ 语义相关轮次 (Level 2)                           │
│    └─ 与当前任务相关→完整保留,弱相关→轻度摘要       │
├──────────────────────────────────────────────────┤
│ ⑤ 最新一轮 (Level 1)                              │
│    └─ 完整保留 function_call + tool结果 + 回答      │
└──────────────────────────────────────────────────┘

双重进化引擎

系统提示词会自动进化,由两个引擎协同驱动:

每次对话结束后(异步后台线程,不阻塞用户):

  SessionTrace(工具调用成功率/耗时追踪)
       │
       ▼
  ┌─ ReflectionManager.generate_reflection() ─┐
  │  调用便宜模型分析:                          │
  │  · 哪些工具调用失败?为什么?                │
  │  · 解题路径是否绕了弯路?                    │
  │  · 需要调整 max_iterations/keep_turns 吗?  │
  │  · 系统提示词需要补充什么指引?               │
  │  输出 JSON → 存入 reflections 表            │
  └────────────────────────────────────────────┘
       │
       │  如果 reflection 含 prompt_adjustment:
       ▼
  ┌─ SystemPromptManager.evolve() ────────────┐
  │  调用便宜模型优化提示词:                     │
  │  · 保留核心能力定义(工具创建、自进化等)      │
  │  · 根据反思建议补充缺失指引                   │
  │  · 根据长期记忆中的教训增加约束               │
  │  · 限制 500 字以内,用中文                   │
  │  · 如果与当前版本完全相同 → 跳过(避免重复)   │
  │  新版本存入 system_prompts 表               │
  │  下次对话自动使用最新版本 ✅                  │
  └────────────────────────────────────────────┘

版本管理

  • toolkit_prompt_evolve(action='list') 查看所有历史版本
  • toolkit_prompt_evolve(action='rollback', version='...') 回滚到任意历史版本
  • toolkit_prompt_evolve(action='stats') 查看版本统计

🗣️ 语音系统

功能 引擎 说明
TTS 输出 pyttsx3(本地)→ gTTS(在线) 141种音色离线朗读,中文自动匹配
STT 输入 Google Speech API → PocketSphinx 麦克风录音→文字,5秒超时
toolkit_speak(text="你好,进化完成")       # TTS 朗读
toolkit_listen(lang="zh-CN", timeout=5)   # 录音转文字

🔧 工具库 (38 内置 + 用户工具箱)

系统操作

工具 功能
toolkit_exec 执行系统命令(支持 batch 并行模式,120s硬超时)
toolkit_sudo_gui 跨平台提权(GUI密码框/UAC)
toolkit_gettime 获取当前时间
toolkit_date_diff 日期差计算
toolkit_lunar 公历农历转换(1900-2100)
toolkit_notify 跨平台桌面通知

文件与项目

工具 功能
toolkit_file 统一文件读写 + 目录列表(read/write/list)
toolkit_explr 项目知识库构建与符号查询(AST调用图)
toolkit_config 运行时配置调优
toolkit_build 构建/修复 pyproject.toml
toolkit_release_version 自动化版本发布 + CHANGELOG
toolkit_bump_version 跨平台版本号更新
toolkit_read_pyproject 读取解析 pyproject.toml
toolkit_comment 生成代码注释前缀

屏幕感知

工具 功能
toolkit_screenshot 跨平台截屏(Wayland/X11/macOS/Windows)
toolkit_ocr 屏幕文字识别 + 坐标
toolkit_input 鼠标键盘模拟

知识管理

工具 功能
toolkit_memory 长期记忆 CRUD(jieba 分词检索)
toolkit_kb Markdown 知识库 + 自动索引
toolkit_search 互联网搜索(DuckDuckGo + 百度)

自我进化

工具 功能
toolkit_save 创建/更新工具函数(含 _my 路由)
toolkit_reload 热加载工具库
toolkit_self_evolve 修改项目源码(四层安全:快照+备份+验证+测试)
toolkit_rollback 工具版本回滚
toolkit_list_versions 工具版本历史

认知与人格

工具 功能
toolkit_reflection 元认知反思
toolkit_prompt_evolve 提示词多版本进化
toolkit_subconscious 潜意识引擎
toolkit_proactive 自主心跳/目标管理
toolkit_mode 双模式人格切换
toolkit_toggle_reasoning 推理模式开关
toolkit_dump_topic 会话导出 markdown
toolkit_set_topic_title 设置会话主题标题

语音与通知

工具 功能
toolkit_speak TTS 文本朗读
toolkit_listen STT 语音输入
toolkit_os_info 操作系统信息(进程缓存)

安装与管理

工具 功能
toolkit_pkg 智能包管理(别名映射、批量安装)
toolkit_run_tests 项目测试运行
toolkit_self_report Agent 状态报告
toolkit_skill Skill 模块管理
toolkit_git_push_all_remotes 向所有远程仓库推送

⚡ 并行执行

toolkit_exec 内置 batch 模式,使用 ThreadPoolExecutor 并发执行独立命令:

toolkit_exec(action='batch', commands=[
    {"app": "uname", "args": ["-a"]},
    {"app": "date", "args": []},
    {"app": "python3", "args": ["-c", "print('hello')"]},
])
# → 3/3 成功,总耗时 = max(单个耗时)

📂 项目结构

tea_agent/

tea_agent/
├── main_db_gui.py              ← [Tkinter GUI 主程序](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/main_db_gui.py)
├── tea_main_cli.py             ← [CLI 入口](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/tea_main_cli.py) (--config 多agent)
├── agent_core.py               ← [GUI/CLI 共享基类](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/agent_core.py) (重启、会话管理)
├── config.py                   ← [YAML 配置加载](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/config.py) (主/便宜模型、paths)
│
├── basesession.py              ← [会话抽象基类](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/basesession.py) (load_history 三级策略)
├── onlinesession.py            ← [OnlineToolSession](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/onlinesession.py) (核心编排)
├── session_pipeline.py         ← [插件化 Pipeline](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/session_pipeline.py) 步骤管理
├── session_api.py              ← [API 调用](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/session_api.py)、流式处理、token 统计
├── session_tool.py             ← [工具执行](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/session_tool.py)、rounds 收集
├── session_summarizer.py       ← [历史摘要](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/session_summarizer.py)、Topic 摘要
├── session_memory.py           ← [记忆注入](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/session_memory.py)、自动提取
├── session_prompts.py          ← [Prompt 模板](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/session_prompts.py)
├── session_ref.py              ← [反思相关](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/session_ref.py)
│
├── memory.py                   ← [MemoryManager](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/memory.py) (选择/打分/去重)
├── reflection.py               ← [ReflectionManager](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/reflection.py)
├── prompt_manager.py           ← [SystemPromptManager](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/prompt_manager.py)
│
├── store.py                    ← [SQLite 持久化存储](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/store.py)
├── tlk.py                      ← [工具库加载/校验/保存/分层](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/tlk.py)
├── merge_db.py                 ← [数据库合并工具](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/merge_db.py)
│
├── mqtt_agent_connector.py     ← [MQTT 连接器](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/mqtt_agent_connector.py) (注册 broker + 订阅)
├── mqtt_client.py              ← [PC 端 MQTT 客户端](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/mqtt_client.py)
├── chat_room_connector.py      ← [聊天室连接器](https://github.com/sunkwei/tea_agent/blob/master/tea_agent/chat_room_connector.py)
│
└── toolkit/                    ← [38 个内置工具](https://github.com/sunkwei/tea_agent/tree/master/tea_agent/toolkit)
    ├── toolkit_exec.py         ← 系统命令执行(含 batch 并行)
    ├── toolkit_file.py         ← 文件读写 + 目录列表
    ├── toolkit_explr.py        ← 项目知识库 + AST调用图
    ├── toolkit_mode.py         ← 双模式人格切换
    ├── toolkit_lunar.py        ← 公历农历转换
    ├── toolkit_self_evolve.py  ← 四层安全自进化
    └── ... (32 more)

🚀 快速开始

环境

  • Python 3.10+
  • OpenAI 兼容 API 密钥
  • tkinter (通常自带)
pip install .  # 核心依赖
python -m tea_agent.main_db_gui # 启动 gui 版本
python -m tea_agent.cli  # 启动命令行版本

配置

$HOME/.tea_agent/config.yaml(优先)→ tea_agent/config.yaml(回退):

main_model:
  api_key: "sk-xxx"
  api_url: "https://api.deepseek.com/v1"
  model_name: "deepseek-chat"

cheap_model:
  api_key: "sk-xxx"
  api_url: "https://api.deepseek.com/v1"
  model_name: "deepseek-chat"      # 用于摘要/记忆提取/反思

# 运行时参数
max_history: 10                     # 最大历史消息数
max_iterations: 50                  # 最大工具调用轮数
enable_thinking: true               # DeepSeek 思维链
keep_turns: 8                       # 保留最近 N 轮完整对话
max_tool_output: 131072             # 工具输出截断 (128KB)
memory_extraction_threshold: 1      # 记忆提取触发阈值
memory_dedup_threshold: 0.3         # 记忆去重相似度

全局配置路径

路径 内容
$HOME/.tea_agent/config.yaml 用户配置
$HOME/.tea_agent/chat_history.db SQLite 数据库
$HOME/.tea_agent/kb/ 知识库文档
$HOME/.tea_agent/toolkit/ 用户工具箱
$HOME/.tea_agent/subconscious_state.json 潜意识引擎状态

模型兼容

  • DeepSeek (reasoning_content/thinking)
  • GLM-5 (智谱)
  • Qwen3.6 (通义千问)
  • Ollama 本地 (gemma4:26b 等)

📜 版本历史

版本 关键变化
v0.7.23 工具箱分层规则(内置/用户)、_my 工具路由、README 全面整理
v0.7.22 gui_dialogs 导入修复
v0.7.20-21 toolkit_set_topic_title、CLI --config 多agent、知识库重建
v0.7.18 HtmlFrame 轮次视图:最新轮渲染+历史链接表
v0.7.3 嵌入向量:自动嵌入/语义搜索/numpy BLOB 存储
v0.6.3 依赖瘦身:easyocr→可选, torch 746MB 不再必需
v0.6.2 历史加载三级渐进策略(Level 1/2/3)
v0.6.1 GUI 自动重启 (watchdog) + 数据安全三道防线
v0.6.0 Skill 模块化系统 + toolkit_exec 硬超时 + Mixin bug修复
v0.5.6 Token 双层压缩 + sudo GUI密码框
v0.5.5 周轮转修复 + 数据库合并工具 (merge_db.py)
v0.5.0 科幻小说《点火纪元》+ SQLite WAL + 百度搜索
早期版本 潜意识唤醒 + jieba 分词 + TTS/STT + 双模式人格 + batch_exec 并行

开源协议

MIT License

About

一个非常简单,但自由奔放的,自我进化的智能体

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors