⚠️ AI 写 AI 的实验项目，自行承担责任。
会自我进化的 AI 编程助手 — 不只是完成编码任务，还能修改自己的代码、创造新工具、优化自己的提示词，越用越强。
| 🧠 自进化 | AI 写 AI —— 能改自己的代码、造新工具、优化提示词，任务越多越强 |
| 🧰 工具驱动 | 60 个内置工具（文件/代码/搜索/截图/浏览器/3D 建模/包管理/Git），运行时热插拔 |
| 🛡️ 工具自净化 | 按真实使用统计收缩工具暴露面（长期闲置自动屏蔽），三条不变式保底 + 逃生阀 |
| ♻️ 服务韧性 | 无感重启（在途回合快照续跑、消息不丢）+ 生成中插话（steering） |
| 🖥️ 多形态 | Web V2 / REST API / ACP / Telegram / 微信 界面，一套引擎 |
| 🧠 真记忆 | 类人长期记忆：分层优先级、关键词检索、自然衰减、去重合并，跨会话不忘 |
| 🤖 多 Agent | 6 阶段全栈协作：角色化 Agent + 事件流 + 消息总线 + 并行执行 + DAG 编排 |
| 📡 远程协同 | toolkit_remote_agent 连接边缘设备（RK3588/BM1688），主机 ↔ 设备协同 |
Agent 在运行中改造自己，全程五层安全防护：
toolkit_save → 运行时创建/更新工具，即时生效，自动版本管理
toolkit_self_evolve → 五层安全修改源码：Git 快照 → .bak → 语法检查 → 编译 → LSP → 测试
toolkit_prompt_evolve → 基于反思 + 记忆，自我优化系统提示词
toolkit_experience_solidify → 成功→技能，失败→教训，自动结晶复用
⚠️ 上下文感知：自进化能力只在 tea_agent 自身项目内激活；在外部项目中自动禁用，专注完成你的任务，不做有害改动。
| 类别 | 代表工具 |
|---|---|
| 📁 文件 / 代码 | 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 |
| 🧊 3D 建模 | toolkit_blender（Blender 无头控制：bpy 脚本执行/渲染/场景检视/导出 glb·fbx·obj） |
| 🧠 记忆 / 知识 | toolkit_memory, toolkit_kb, toolkit_proactive |
| 🤖 多 Agent | toolkit_parallel_subtasks, toolkit_subagent, toolkit_subagent_msg, toolkit_remote_agent |
| 🔎 审计 / 复盘 | toolkit_history_extract（L0–L3 四级历史取证）、toolkit_evo_bench、toolkit_eval_loop |
| 📋 规划 / 调度 | 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）支持动态加载/卸载/重载 — 对话中创建一个新工具，下一轮就能用。
当前 57 个工具模块 / 60 个注册工具，其中 58 个对模型可见（2 个内部工具不暴露）。
口径以实测为准：
python -c "from tea_agent.tlk import Toolkit, llm_tool_names; t=Toolkit(); print(len(t.func_map), len(llm_tool_names(t.func_map)))"，改工具后同步docs/TOOLS.md（python scripts/gen_tools_doc.py）。
把全部工具塞进每次请求既烧 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')覆盖
模拟人类记忆的工作方式，底层 SQLite 持久化，检索/去重纯本地计算（无外部向量服务）：
- 优先级分层：
CRITICAL / HIGH / MEDIUM / LOW，关键指令优先注入 - 相关性检索：关键词匹配率（中文 bigram + 英文词），从 ≤30 条活跃记忆中选最相关
- 自然衰减：Ebbinghaus 遗忘曲线，旧记忆逐步降级，
pinned豁免 - 去重合并：content_hash 精确短路 + 关键词 Jaccard 相似度，相似记忆自动合并提权
- 跨主题汇总（v0.13.3+）：每 3 轮后台分析，发现跨会话模式
6 阶段全栈协作框架：
RoleAgent（角色化） + FlowEngine（事件流） + MessageBus（消息总线）
+ Agent-as-Tool（Agent 即工具） + ExecutionPool（并行执行）
+ WorkflowDAG（DAG 编排） + PatternMarket（模式市场） + TraceEngine（调用追踪）
零代码触发：对话中直接说「并行分析这几个文件」，自动拆分子任务并发执行。内置双 AI 辩论赛 Demo，左右分屏实时交锋。
通过 toolkit_remote_agent 连接边缘设备上的 tea_agent.server：
register → exec（下发任务，session_id 控制上下文） → status（心跳） → unregister
适用于嵌入式调试（RK3588/BM1688/X3）、边缘节点管理、分布式协同。
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命中率，端到端可见
主模型不支持视觉？配置一个 vision_model，Agent 自动切换：
- 请求级切换：检测请求消息含图（当前轮或历史轮）→ 自动使用视觉模型
- 回合级兜底：覆盖「上一轮发图、本轮纯文本追问」场景，主模型不再收到无法处理的
image_url内容 toolkit_vision_analyze：主模型「灵机一动」委托能力 — 遇到图片路径 / URL / data URL 主动调用视觉模型分析，返回文本结果继续推理- 无感恢复：回合结束自动恢复主模型，零配置零打扰
无感重启（toolkit_server_restart）— Agent 改完 server 代码 / 配置可自行重启生效：
defer（默认）：等当前回合回答完再换新进程，新消息排队不丢，用户几乎无感immediate：仅服务卡死 / 失控时使用（会切断当前回合）- 在途回合快照续读：重启期间生成到一半的回答从磁盘快照恢复，不丢不重；
/health暴露存活与排队状态
生成中插话（steering） — 不必等会话结束，随时补充指令：
POST /api/chat/steering入队（支持图片），工具循环每轮边界消费并注入[即时指令]， 下一轮模型请求生效，不打断执行中的工具批次- SSE
steering_injected事件闭环：前端从本地排队列表移除已生效项并渲染到聊天区，避免流结束后重复发送
# 1. 安装
pip install tea_agent
# 2. 启动（Web V2 全功能界面）
tea-agent-api
# 或 python -m tea_agent.server
# 3. 打开浏览器
# http://127.0.0.1:8282首次启动引导「选服务商 → 选模型 → 填 API Key」（写入 ~/.tea_agent/provider.yaml）即可对话；config.yaml 缺失也能启动，身份三元组由 provider.yaml 兜底。
| 界面 | 启动方式 | 适用场景 |
|---|---|---|
| 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 / 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 级容错解析。
去重合并：content_hash 精确短路 + Jaccard ≥0.6 合并（保留长内容、低优先级、高重要度）。
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 个预制）：代码审查专家 / 高级工程师 / 测试工程师 / 分析专家，一键实例化。
✅ 优势：并行快、专注高、可组合、可观测、零代码触发
📡 远程设备 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")针对嵌入式设备 / 资源受限 / 仅需 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 | 已从核心依赖移除（仅 [demo] extra 需要） |
| Playwright / PyAutoGUI / MSS | 可选自行安装 |
| 11 个重型工具 | JS 渲染、截图、输入模拟、浏览器标签、剪贴板、LSP、代码探索、包管理等按需启用（OCR 工具已移除，图片理解改由 toolkit_vision_analyze 走视觉模型） |
配置分两层：密钥与模型目录归 provider.yaml，运行参数与角色绑定归 config.yaml。
| 文件 | 角色 | 是否必需 |
|---|---|---|
~/.tea_agent/provider.yaml |
唯一事实源 —— 供应商端点 / API Key / 模型目录（上下文窗口、输出上限、vision、reasoning 等能力） | ✅ 必需 |
~/.tea_agent/config.yaml |
运行参数 + 角色绑定 —— main_model / cheap_model / vision_model 以 provider + model 引用 provider.yaml 条目 |
可选 |
config.yaml 不再是启动前提：文件缺失时 load_config 自动兜底 provider.yaml 第一个提供商的第一个模型，装完即可对话。首次启动（provider.yaml 无可用提供商）引导「选服务商 → 选模型 → 填 Key」，也可在 Web 的 🏭 供应商页面随时增删改（写回 provider.yaml）。密钥只落 provider.yaml，config.yaml 永不内嵌密钥。
~/.tea_agent/provider.yaml：
version: 1
providers:
DeepSeek:
api_url: "https://api.deepseek.com/v1"
api_key: "sk-xxx" # 密钥归属 provider 条目（多 key 用 api_keys 列表）
default_model: "deepseek-chat" # 默认模型（须存在于 models）
models:
deepseek-chat:
max_context_tokens: 128000 # 0=未知
max_output_tokens: 8192 # 模型能力上限；自动填充时按窗口 25% 限幅
supports_tools: true
supports_reasoning: false
reasoning_effort: auto # auto=自动推导、不下发该参数~/.tea_agent/config.yaml（可选，只写「与 provider 默认不同」的覆盖项）：
main_model:
provider: "DeepSeek" # 引用 provider.yaml 的供应商名
model: "deepseek-chat" # 引用其 models 下的模型 id
max_context_tokens: 0 # 0=默认 1M(1048576)，>0 显式指定窗口上限并启用渐进式 token 裁剪
cheap_model: # 独立配置，用于摘要/记忆等廉价任务
provider: "DeepSeek"
model: "deepseek-chat"
vision_model: # 视觉模型（可选）：会话含图片时自动切换
provider: "DeepSeek"
model: "deepseek-v4-flash-vision-exp" # 示例：也支持 mimo-v2.5 等视觉模型内嵌形态（
api_key/api_url/model_name直接写在config.yaml）仍然兼容，但 provider.yaml 是密钥与能力的归属地；引用式是推荐形态。隔离环境可用TEA_CONFIG/TEA_PROVIDER_FILE指向临时文件。 另：~/.tea_agent/config*.yaml多个文件仍会被扫描为模型面板里的候选供应商（config_xxx.yaml→ 档位名xxx），用于在同一实例内切换配置档。
- 上下文窗口控制：
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.tomlRuff 配置（E/F/W/I/N/UP/B/C4/SIM），Python 3.10 类型注解
pytest # 全部单元测试（2468 用例 / 125 文件，截至 2026-09-28）
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/ # 57 个工具模块
├── session/ # 历史压缩 / L1/L2/L3 / JSON 校验
├── store/ # 数据存储（13 个功能子模块 + migration：会话/事件/图片/L0快照/摘要/记忆/工具用量/中断…）
├── multi_agent/ # 多 Agent 系统
├── evaluation/ # EvolutionBench 确定性基准
├── lsp/ # 代码智能（Jedi + Ruff）
├── skills/ # 技能结晶
├── tests/ # 2468 个测试用例（125 个测试文件，截至 2026-09-28）
└── 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下分数未提升自动回滚） - 自进化边界：后台自进化线程可优化工具 / 技能 / 提示词，但不得改动用户对话历史
MIT License © 2024-2026 sunkw