Tea Agent v0.16.6

⚠️ AI 写 AI 的实验项目，自行承担责任。

🌐 English Version

会自我进化的 AI 编程助手 — 不只是完成编码任务，还能修改自己的代码、创造新工具、优化自己的提示词，越用越强。

🎯 一句话看懂 Tea Agent


🧠 自进化	AI 写 AI —— 能改自己的代码、造新工具、优化提示词，任务越多越强
🧰 工具驱动	60+ 内置工具（文件/代码/搜索/截图/浏览器/包管理/Git），运行时热插拔
🛡️ 工具自净化	按真实使用统计收缩工具暴露面（长期闲置自动屏蔽），三条不变式保底 + 逃生阀
♻️ 服务韧性	无感重启（在途回合快照续跑、消息不丢）+ 生成中插话（steering）
🖥️ 多形态	Web V2 / REST API / ACP / Telegram / 微信界面，一套引擎
🧠 真记忆	类人长期记忆：分层优先级、语义检索、自然衰减、去重合并，跨会话不忘
🤖 多 Agent	6 阶段全栈协作：角色化 Agent + 事件流 + 消息总线 + 并行执行 + DAG 编排
📡 远程协同	`toolkit_remote_agent` 连接边缘设备（RK3588/BM1688），主机 ↔ 设备协同

✨ 核心特点

1. 🧠 自进化引擎（AI 写 AI）— 本项目灵魂

Agent 在运行中改造自己，全程五层安全防护：

toolkit_save          → 运行时创建/更新工具，即时生效，自动版本管理
toolkit_self_evolve   → 五层安全修改源码：Git 快照 → .bak → 语法检查 → 编译 → LSP → 测试
toolkit_prompt_evolve → 基于反思 + 记忆，自我优化系统提示词
toolkit_experience_solidify → 成功→技能，失败→教训，自动结晶复用

⚠️ 上下文感知：自进化能力只在 tea_agent 自身项目内激活；在外部项目中自动禁用，专注完成你的任务，不做有害改动。

2. 🧰 工具驱动 — 60+ 内置工具

类别	代表工具
📁 文件 / 代码	`toolkit_file`, `toolkit_edit`, `toolkit_diff`, `toolkit_code_review`, `toolkit_format_code`
🔍 搜索 / 智能	`toolkit_search`, `toolkit_lsp`, `toolkit_explr`, `toolkit_query_chat_history`
🖥️ 屏幕 / 视觉	`toolkit_screenshot`, `toolkit_input`, `toolkit_js_fetch`, `toolkit_browser_tab`, `toolkit_vision_analyze`
🧠 记忆 / 知识	`toolkit_memory`, `toolkit_kb`, `toolkit_proactive`
🤖 多 Agent	`toolkit_parallel_subtasks`, `toolkit_subagent`, `toolkit_subagent_msg`, `toolkit_remote_agent`
📋 规划 / 调度	`toolkit_plan`, `toolkit_todo`, `toolkit_scheduler`, `toolkit_task_resume`
🔧 系统 / 工程	`toolkit_exec`(含 git), `toolkit_pkg`, `toolkit_build`, `toolkit_config`, `toolkit_server_restart`, `toolkit_approve`

工具引擎（tlk.py）支持动态加载/卸载/重载 — 对话中创建一个新工具，下一轮就能用。当前 56 个工具模块 / 60 个注册工具，其中 58 个对模型可见（2 个内部工具不暴露）。

工具暴露自缩减（v0.16.6+）

把全部工具塞进每次请求既烧 token 也稀释注意力。tool_shield.py 按真实使用数据收缩暴露面：

统计：项目库 tool_usage 表，一行一工具（uses / first_used / last_used / pin）。记录点是 Toolkit.call_tool，且在缓存判定之前 —— 命中缓存同样是一次真实调用，漏记会把常用工具长期误判成"没用过"而屏蔽
屏蔽：构建工具列表时剔除长期未使用者。与 tool_profiles 的窗口档位是两层独立收缩 （档位按上下文窗口裁、屏蔽按真实使用裁）；屏蔽集合排序稳定，不抖动 DeepSeek 前缀缓存
三条不变式（屏蔽会让 Agent 失去能力，故"何时绝不屏蔽"比"何时屏蔽"更要紧）： ① 无数据不屏蔽 —— 空表只代表"尚未观测"，否则新装机首启即屏蔽全部工具、Agent 瘫痪； ② 观测期未满不屏蔽零使用工具 —— 判"长期不用"必须先有"长期"，"刚装上"不等于"长期不用"； ③ 自愈通路永不屏蔽 —— config/save/reload/exec/file/edit/diff/approve/tool_usage/rollback/list_versions 共 11 个，屏蔽它们等于拆掉解除屏蔽的梯子
逃生阀：TEA_TOOL_SHIELD=0 关闭；TEA_TOOL_SHIELD_IDLE_DAYS=N 调闲置阈值；单工具用 toolkit_tool_usage(action='pin'|'unpin'|'auto'|'reset') 覆盖

3. 🧠 类人长期记忆系统

模拟人类记忆的工作方式，底层 SQLite + 语义向量：

优先级分层：CRITICAL / HIGH / MEDIUM / LOW，关键指令优先注入
语义检索：embedding 余弦相似度，从 ≤30 条活跃记忆中选最相关
自然衰减：Ebbinghaus 遗忘曲线，旧记忆逐步降级，pinned 豁免
去重合并：Jaccard + embedding 双通道，相似记忆自动合并提权
跨主题汇总（v0.13.3+）：每 3 轮后台分析，发现跨会话模式

4. 🤖 多 Agent 系统（v0.11+）

6 阶段全栈协作框架：

RoleAgent（角色化） + FlowEngine（事件流） + MessageBus（消息总线）
+ Agent-as-Tool（Agent 即工具） + ExecutionPool（并行执行）
+ WorkflowDAG（DAG 编排） + PatternMarket（模式市场） + TraceEngine（调用追踪）

零代码触发：对话中直接说「并行分析这几个文件」，自动拆分子任务并发执行。内置双 AI 辩论赛 Demo，左右分屏实时交锋。

5. 📡 远程设备 Agent（v0.13.10+）

通过 toolkit_remote_agent 连接边缘设备上的 tea_agent.server：

register → exec（下发任务，session_id 控制上下文） → status（心跳） → unregister

适用于嵌入式调试（RK3588/BM1688/X3）、边缘节点管理、分布式协同。

6. 🏎️ Token 经济 — 四级历史压缩 + 前缀缓存稳定化

L0 系统层 → L3 语义摘要 → L2 历史对 → L1 当前对话 四级组装上下文，在有限 token 窗口内最大化信息密度，长对话不爆上下文。

v0.15.0 缓存前缀稳定化（对齐 DeepSeek Harness「派生只依赖事件流」哲学）— 深度优化 LLM 前缀缓存命中率：

入库定型：消息一旦入库即决定最终形态（截断/占位符/清空），绝不逐轮重算
L2 入库定型：相关性过滤只在「新消息边界」重算一次，工具循环内多轮请求复用同一版本，消除 L2 条目翻转
裁剪决策固化：reasoning 清空 / 紧急截断等形态决策回写 context.messages，预算波动不再导致「完整版↔截断版」翻转
动态内容尾部注入：时间/token 预算/技能/记忆全部放消息尾部，不进 system prompt，保护最长最贵的前缀段
可观测：cache_report.py 输出 prompt_cache_hit_tokens 命中率，端到端可见

7. 👁️ 视觉模型自动切换（v0.13.16+）

主模型不支持视觉？配置一个 vision_model，Agent 自动切换：

请求级切换：检测请求消息含图（当前轮或历史轮）→ 自动使用视觉模型
回合级兜底：覆盖「上一轮发图、本轮纯文本追问」场景，主模型不再收到无法处理的 image_url 内容
toolkit_vision_analyze：主模型「灵机一动」委托能力 — 遇到图片路径 / URL / data URL 主动调用视觉模型分析，返回文本结果继续推理
无感恢复：回合结束自动恢复主模型，零配置零打扰

8. ♻️ 服务韧性 — 无感重启 + 生成中插话（v0.16.x）

无感重启（toolkit_server_restart）— Agent 改完 server 代码 / 配置可自行重启生效：

defer（默认）：等当前回合回答完再换新进程，新消息排队不丢，用户几乎无感
immediate：仅服务卡死 / 失控时使用（会切断当前回合）
在途回合快照续读：重启期间生成到一半的回答从磁盘快照恢复，不丢不重；/health 暴露存活与排队状态

生成中插话（steering） — 不必等会话结束，随时补充指令：

POST /api/chat/steering 入队（支持图片），工具循环每轮边界消费并注入 [即时指令]，下一轮模型请求生效，不打断执行中的工具批次
SSE steering_injected 事件闭环：前端从本地排队列表移除已生效项并渲染到聊天区，避免流结束后重复发送

🚀 30 秒快速开始

# 1. 安装
pip install tea_agent

# 2. 启动（Web V2 全功能界面）
tea-agent-api
# 或 python -m tea_agent.server

# 3. 打开浏览器
# http://127.0.0.1:8282

首次启动自动弹出配置窗口，填入 LLM API Key 即可对话。

💻 界面形态

界面	启动方式	适用场景
Web V2（推荐）	`tea-agent-api`	单页应用 SPA，全功能浏览器体验：聊天 + 记忆 + 调度 + 历史
REST API	`python -m tea_agent.server --port 8081`	OpenAI 兼容接口，第三方集成
ACP 协议	`tea-agent-acp`	VS Code / IDE 集成（JSON-RPC 2.0）
Telegram	`tea-agent-telegram`	手机远程对话
微信	`tea-agent-wechat`	微信个人号接入（iLink Bot，扫码登录）
Mini 版	`tea-agent-mini`	嵌入式 / Docker / 低配 VPS

🗺️ 深度能力地图

想深入了解某一项？展开对应章节。

🧠 长期记忆系统 — 工作原理

存储结构：每条记忆含 content / priority(0-3) / importance(1-5) / category / tags / embedding / expires_at / pinned。

选择算法（每次对话注入 ≤30 条）：

score = 关键词相关性 × 重要度 × 时效因子 × 优先级因子

分层保底：CRITICAL 优先（上限 10）→ HIGH ≥3 → MEDIUM ≥2 → LOW ≥1 → 剩余按分竞争。

年龄衰减（Ebbinghaus）：CRITICAL>30天→HIGH，HIGH>60天→MEDIUM，MEDIUM>90天→LOW。

提取分类：instruction→CRITICAL、preference/reminder→HIGH、fact→MEDIUM、general→LOW，LLM 自动提取 + 4 级容错解析。

去重合并：Jaccard ≥0.6 合并（保留长内容、低优先级、高重要度）；embedding 余弦 ≥0.92 批量去重。

CRITICAL FIFO：上限 30 条，超出软删除最旧，防指令记忆膨胀。

📜 四级历史压缩 — Token 效率

L0 系统层   系统提示词 + 任务恢复 + 记忆注入
L3 语义摘要 L2 溢出时 LLM 生成关键结论（50→20 裁剪）
L2 历史对   SQLite 环形缓冲（50 条），Jaccard 相关性筛选注入
L1 当前对话 128KB 截断 + 旧工具输出占位 + 5 级渐进裁剪

# L0 组装顺序
result.append({"role": "system", "content": system_prompt})
if has_pending_tasks:
    result.append({"role": "user", "content": resume_info})
if memories:
    result.append({"role": "user", "content": memories})

L3 注入格式（[System Memory] 区）包含长期背景/偏好/关键结论 + 历史工具链回顾两块。

🔄 自进化引擎 — 安全机制

修改自身代码时五层防护，任一层失败自动回滚：

Layer 0  Git 快照（仅工作区干净时；落点 refs/tea/snapshots，不污染分支历史）
Layer 1  时间戳 .bak（永不覆盖历史）
Layer 1.5  语法严格检查（换行/缩进/括号/冒号）
Layer 2  py_compile 编译验证 → 失败回滚
Layer 2.5  LSP 智能检查（影响分析 + lint 对比 + 签名对比）
Layer 3  pytest 测试验证 → 失败按快照恢复目标文件（不再 git reset --hard 波及整个工作区）

能力	工具	安全
创建新工具	`toolkit_save` + `toolkit_reload`	版本回滚
修改源码	`toolkit_self_evolve`	五层安全
优化提示词	`toolkit_prompt_evolve`	版本回滚
进化评分	`toolkit_evo_bench` / `toolkit_eval_loop`	keep-or-rollback 决策
固化经验	`toolkit_experience_solidify`	分类标签
代码智能	`toolkit_lsp`	只读

进化闸门（EvolutionBench）：toolkit_self_evolve 原有的门槛只有「编译过 + 测试过」，回答不了「这版是否真的更好」。现在改动落地后会自动跑确定性基准（纯代码 check，无 LLM）并写入进化曲线，与上一数据点比较给出 keep / rollback 建议；evolution.gate=enforce 时分数未提升自动按 .bak 回滚（off 零开销 / advisory 默认只建议）。

🤖 多 Agent — 核心组件

四种协作方式：

方式	说明
FlowEngine	事件驱动流：`@flow_start` / `@flow_listen` / `@flow_route`，Mermaid 可视化
Agent-as-Tool	把子 Agent 包装成 `toolkit_xxx`，对话中直接调用
MessageBus	发布/订阅 + 点对点，Agent 间自由通信
ExecutionPool	线程池并行执行，批量 + 超时 + 状态查询

WorkflowDAG 节点：TASK / CONDITION / LOOP / PARALLEL / WAIT / END 六种类型，静态编排复杂流程。

内置模式市场（4 个预制）：代码审查专家 / 高级工程师 / 测试工程师 / 分析专家，一键实例化。

✅ 优势：并行快、专注高、可组合、可观测、零代码触发 ⚠️ 限制：Token 成本高（子任务×每任务）、协调开销、上下文隔离、并发改文件需串行化

📡 远程设备 Agent — 使用示例

# ① 注册设备
toolkit_remote_agent(action="register", device_id="bm1688-1",
    host="172.16.1.49", port=8282, working_path="/app/zkfs/")

# ② 下发任务（不传 session_id → 自动新建远程主题）
r = toolkit_remote_agent(action="exec", device_id="terminal-49",
    goal="分析 /record/dbs/log/ 今日日志")

# ③ 同一 session_id → 追加上下文继续对话
r2 = toolkit_remote_agent(action="exec", device_id="terminal-49",
    goal="继续排查网络问题", session_id=r["session_id"])

# ④ 任务完成 → 断开
toolkit_remote_agent(action="unregister", device_id="terminal-49")

📦 Mini 版（tea_agent_mini）

针对嵌入式设备 / 资源受限 / 仅需 Web 场景的瘦身版 —— 只依赖 7 个核心包（~5 MB vs Full 版 ~80 MB），保留 Agent 核心、Web V2、REST API、记忆、多 Agent 全部能力。

pip install tea_agent_mini        # 独立包
python build_mini.py              # 或从源码构建
python build_nuitka.py            # 或编译为单文件可执行文件（无需 Python 环境）

剔除内容	说明
ACP / Telegram	协议与渠道层
NumPy 向量	替换为纯 Python `math+struct`
Playwright / PyAutoGUI / MSS	可选自行安装
11 个重型工具	JS 渲染、截图、输入模拟、浏览器标签、剪贴板、LSP、代码探索、包管理等按需启用（OCR 工具已移除，图片理解改由 `toolkit_vision_analyze` 走视觉模型）

🔧 配置

配置文件 ~/.tea_agent/config.yaml：

main_model:
  api_key: "sk-xxx"
  api_url: "https://api.openai.com/v1"
  model_name: "gpt-4o"
  max_context_tokens: 0    # 0=默认 1M(1048576)，>0 显式指定窗口上限并启用渐进式 token 裁剪
cheap_model:               # 独立配置，用于摘要/记忆等廉价任务
  max_context_tokens: 0
embedding:
  provider: openai
  model: text-embedding-3-small
vision_model:             # 视觉模型（可选）：会话含图片时自动切换
  api_key: "sk-xxx"
  api_url: "https://api.openai.com/v1"
  model_name: "gpt-4o-mini"    # 示例：也支持 mimo-v2.5 等视觉模型

上下文窗口控制：max_context_tokens 作为"上下文已用"百分比的分母（窗口上限），超预算时按 5 级渐进裁剪（删旧历史 → 工具输出占位 → 清 thinking → 截长文 → 删旧轮）。未显式配置时默认 1M（1048576），不做模型名推断，避免模型名不匹配导致窗口上限误判。输入预算与 max_tokens 联动求解（窗口 − 输出请求 − 2% 安全余量），从源头防止"输入+输出 > 窗口"的 400 溢出；API 真返回 400 时自动修正窗口、激进压缩历史、钳制 max_tokens 后重试。
上下文填充治理（2026-09）：修复"多轮对话迅速打满窗口"。provider.yaml 的 max_output_tokens 自动填充时按窗口 25% 限幅（不再把 384K 输出预留算进预算，1M 窗口的输入预算从 446K 回到 580K）；L1 的 reasoning_content 以 rc_keep_steps（默认 8）分块，只保留最近一块全文、更早的块置空（字段保留，满足 DeepSeek V4 回传要求），单轮 200 步的思考链不再全量重放；L2 单条 thinking 限幅 l2_thinking_max_chars（默认 6000 字符）且总字符数达到 l2_max_chars（默认 120000）即触发 L3 摘要；L2 与 L1 重叠的轮次自动去重；源码文件回放上限 64KB（此前不截断）；keep_turns 默认回落 5 并让 max_history 真正生效（限制 L1 保留的最近用户轮数）。
视觉模型自动切换：配置 vision_model 后，会话输入含图片时自动使用视觉模型（回合结束恢复主模型）；另提供 toolkit_vision_analyze 工具供主模型委托图片分析
自我进化闸门：evolution.gate = off | advisory | enforce（环境变量 TEA_EVOLVE_GATE，阈值 TEA_EVOLVE_GATE_THRESHOLD 默认 0.0 即"必须严格提升才算 keep"）；enforce 下修改自身代码后自动跑 EvolutionBench，分数未提升即按 .bak 回滚 —— 把"测试通过"升级为"确实更好"
工具暴露自缩减：TEA_TOOL_SHIELD=0 关闭长期未使用工具自动屏蔽；TEA_TOOL_SHIELD_IDLE_DAYS=N 调整闲置阈值（默认 30 天，观测期未满不屏蔽）
运行时调优：Agent 可用 toolkit_config 自主调整参数
Ruff 规范：内置 pyproject.toml Ruff 配置（E/F/W/I/N/UP/B/C4/SIM），Python 3.10 类型注解

🧪 测试

pytest                    # 全部单元测试（1800+ 用例）
python tests/test_server_api.py --port 8282   # Server API 黑盒测试（8 套件 30+ 测试点）

测试覆盖：会话、工具、存储、多 Agent、LSP、ACP 协议、Server 路由、记忆系统。

🏗️ 项目结构

tea_agent/
├── agent.py           # Agent 统一入口
├── onlinesession.py   # 在线会话（工具循环 + 流式）
├── litesession.py     # 轻量会话
├── tlk.py             # 工具加载/注册/执行引擎（60 工具）
├── memory.py          # 长期记忆系统
├── config.py          # 配置管理
├── providers.py       # 26 家 LLM 供应商引导目录（模型属性来自 provider.yaml）
├── tool_shield.py     # 长期未使用工具自动屏蔽（三条不变式 + 逃生阀）
├── evolution_gate.py  # 进化闸门：EvolutionBench 评分 → keep-or-rollback
├── skill_loader.py    # Skill 按需加载（必要性/充分性双维评估）
├── context_fragments.py # 上下文片段按需组装（时间/预算/模式/记忆）
├── server/            # REST API + Web V2（Starlette + SSE）
├── protocol/          # ACP 协议
├── channel/           # Telegram / 微信适配器
├── toolkit/           # 56 个工具模块
├── session/           # 历史压缩 / L1/L2/L3 / JSON 校验
├── store/             # 数据存储（13 个功能子模块 + migration：会话/记忆/向量/工具用量/中断…）
├── multi_agent/       # 多 Agent 系统
├── evaluation/        # EvolutionBench 确定性基准
├── lsp/               # 代码智能（Jedi + Ruff）
├── skills/            # 技能结晶
├── tests/             # 1800+ 测试用例（95 个测试文件）
└── demo/              # 演示应用（辩论赛 / 钢琴 / DAG）

🔐 安全边界

提权一律拒绝：sudo / su / pkexec / runas 等硬拒绝（toolkit_exec 与 toolkit_scheduler 两条执行路径都拦截）—— 需要管理员权限的操作必须由用户手动执行
审批闸门：TEA_APPROVAL_MODE=enforce 时高风险工具（toolkit_exec / toolkit_self_evolve 等）须经 toolkit_approve 授权，授权按项目持久生效
路径围栏：文件工具默认限制在项目内，禁止 ../ 逃逸；跨目录操作需显式绝对路径或 TEA_FILE_ALLOW_OUTSIDE=1
SQL 安全：数据库操作一律参数化查询，项目自带「禁止 f-string 拼接 SQL」的自检测试把守
快照隔离：自进化 git 快照提交到独立 ref（refs/tea/snapshots，可用 TEA_SNAPSHOT_REF 覆盖），不再污染分支历史；TEA_GIT_SNAPSHOT_MODE=off|side|branch
进化闸门：TEA_EVOLVE_GATE=off|advisory|enforce 决定 EvolutionBench 评分是否阻断自我修改（enforce 下分数未提升自动回滚）
自进化边界：后台自进化线程可优化工具 / 技能 / 提示词，但不得改动用户对话历史

📄 许可证

Metadata

Release files for tea-agent 0.16.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tea-agent 0.16.8
File	Size	Uploaded
tea_agent-0.16.8.tar.gz	1.3 MB	Sep 20, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for tea-agent 0.16.8
File	Interpreter	ABI	Platform	Reset
tea_agent-0.16.8-py3-none-any.whl 1.5 MB Sep 20, 2026	Python 3	none	any	Details

Total release size: 2.8 MB

Release files / tea_agent-0.16.8.tar.gz

Download URL	tea_agent-0.16.8.tar.gz
Size	1.3 MB
Tags	Source
SHA-256 checksum How to use checksums	`0265d4dba22a39e0792c907e3b7e03093be00f8c0b3c31a2bfec443086c90adc`
BLAKE2b-256 checksum How to use checksums	`abbb20646cf338c42410fd06b33291c5be9e57ef431eb96627eac9737493f32f`
Upload date	Sep 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.9`

Release files / tea_agent-0.16.8-py3-none-any.whl

Download URL	tea_agent-0.16.8-py3-none-any.whl
Size	1.5 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`b27fcdb38b7b73d76b42a90c9147c7922e60b85db7f6cb1b59397a230a5eff99`
BLAKE2b-256 checksum How to use checksums	`468ae322a6398e9ed436a11f394856f43b6ffccdd1872e77608c8b1f4851b24e`
Upload date	Sep 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.9`