convez.ai
MCP ServerAutomaçãoIntermediário
llm011

Ethan Agent

llm011/ethan-agent

Agent IA pessoal multinúcleo com memória persistente e 58 ferramentas integradas

Ver no GitHub
BomPluginScore · de 0 a 100

Agent de IA pessoal leve e de alto desempenho com núcleo assíncrono rápido, ferramentas plugáveis e integração aberta com ecossistemas externos (Claude Code, Codex, MCP). Oferece REPL interativo, servidor web, múltiplos núcleos de execução e sistema de memória persistente com recall inteligente.

Instalação

$npx convez-ai llm011/ethan-agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
8
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 3 dias
Versão
v1.0.0b23
Issues abertas
0
Contribuidores
9

Casos de uso

  • Automatizar tarefas pessoais e fluxos de trabalho com IA
  • Integrar com múltiplos agentes e CLIs externas (Claude, Codex, DSH)
  • Manter memória persistente de preferências e contexto pessoal
  • Executar análise de código, busca e operações com arquivos

Veredito

Solução robusta para quem busca um agent IA pessoal extensível com memória de longo prazo e interoperabilidade com outros agentes. Arquitetura multinúcleo bem pensada, mas requer familiaridade com CLIs e MCP para aproveitar toda a potência.

README

A tradução para o português deste README ainda está na fila.

Ethan Agent v2

个人 AI Agent —— 多内核驱动、可插拔工具、跨端(Web / Desktop / Android)

Version License Python


🚀 快速开始

# 安装
pip install ethan-agent

# 交互式 REPL
ethan

# 单轮对话
ethan -p "帮我看下这个仓库的结构"

# 启动 Web/API 服务(前台)
ethan serve

# 装成开机自启的后台服务(macOS launchd)
ethan server install

# 服务管理
ethan server status      # 查看状态
ethan server restart     # 重启
ethan server stop        # 停止
ethan server uninstall   # 卸载开机自启

服务默认监听 8900。启动后浏览器打开 http://localhost:8900 即可使用 Web 界面。

Docker 部署(服务器 / NAS)

# 从 release 下载部署文件,或用仓库里的 deploy/ 目录
curl -LO https://github.com/llm011/ethan-agent/releases/latest/download/docker-compose.yml
curl -LO https://github.com/llm011/ethan-agent/releases/latest/download/.env.example
cp .env.example .env    # 按需改端口、数据目录

docker compose up -d

镜像:ghcr.io/llm011/ethan-agent:latest(linux/amd64 + linux/arm64)。 deploy/ 下还有 docker-compose.nas.yml(群晖等 NAS)与 docker-compose.searxng.yml(自带搜索后端)。

ethan serve 与 ethan server 是两件事: serve 在前台跑 API 服务(子命令只有 stop); server 管理 macOS launchd 后台服务(install / uninstall / restart / stop / status)。


🧠 多内核

内核决定「由谁执行这一轮对话」。原生内核用 Ethan 的全部能力;外部内核把执行权 交给对应 CLI(Claude Code / Codex / OpenCode / Antigravity / DSH / Pi),各有自己的模型与工具。

内核需要可用 Ethan 的工具
ethan内置✅ 原生
claude_codeclaude CLI✅ 经 MCP 注入
dshdsh CLI✅ 经 ACP mcp_servers 注入
opencodeopencode CLI✅ 经 ACP mcp_servers 注入
antigravityagy CLI✅ 经 ACP mcp_servers 注入
codexcodex CLI❌ 仅自带工具
pipi CLI❌ 仅自带工具

「可用 Ethan 的工具」是什么意思:外部内核保留自己的大脑(规划/推理),但通过 /kernel-tools 这个 MCP 端点拿到 Ethan 的 58 个工具——搜索、知识库、文件、OCR、 技能与记忆(skill_list / skill_read / recall_memory / memory_write)等。 于是它既能用自己擅长的能力,又能用 Ethan 的手脚干活。

光把工具挂上去还不够:外部内核看不到 Ethan 的系统提示词,不知道「有这些技能」 「该在什么时候召回记忆」。所以派发时还会前置:

  1. 简报表与每轮技能匹配:技能索引 + 按 Skill frontmatter(trigger / modes / channels / category)每轮自动匹配并注入 <relevant_skills> 或 <matched_skills_brief> + 「涉及个人上下文先调 ethan_recall_memory」+「值得长期记住的事调 ethan_memory_write」。没共享工具的内核(Codex / Pi)不带这部分,免得教它们调不存在的工具。
  2. 分层上下文注入(defaults.kernel.inject_context):默认 rules_profile 注入 soul.md(主人权限/安全红线/密钥铁律)、user_profile.md(我的画像)与 <behavioral_guidelines>(纠错准则),保留外部内核原生语气;也可在设置页切为 full(连同 identity.md 与模式人设一起注入)或 off(关闭)。

附图:外部内核的 ACP 传输层基本都声明 promptCapabilities.image=false(dsh 实测直接拒收 inline 图片),所以图片不走 base64,而是存盘后附本地绝对路径。 只给位置,不指定用什么工具读——拒收的是传输格式,不是模型不能识图。

注入不污染用户环境:mcp_servers 是 ACP new_session() 的每次调用参数, 不写入 ~/.dsh / ~/.claude。DSH 自带的工具全部保留,只多出 mcp__ethan__* 前缀的那批。

切换内核:设置页「AI 内核」标签,或

curl -X POST localhost:8900/api/kernels/select \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind": "dsh"}'

依赖缺失时自动安装;装不上则拒绝切换并保留原内核(返回 409)。

详见 内核架构。


🧬 记忆体系

memory.db 是用户事实的唯一事实源,不是简单向量库:

  • 增量提取:短会话(<3 轮)即时提取;之后每 3 轮提取带 原文 quote 佐证的候选 (quote 必须是用户消息的精确子串,防止模型臆造)
  • 确定性准入:explicit(用户明说)立即生效;observed(观察推断)需 ≥2 个独立 session 复证才晋升
  • 分层维度:preference.tools / decision.chosen / activity.project / methodology.execution_workflow 这类点分维度(实测在用 80+ 个),带置信度与重要度
  • 可回溯:evidence_level 区分 explicit / inferred / corrected; 支持 TTL 过期、supersede 纠正链(改了哪条、什么时候改的)、遗忘脱敏

记忆不是塞进 prompt 就完事——召回经过语义路由,只取当前问题相关的部分。

详见 记忆 · 语义路由。


🎭 模式

模式是人格/语气切换,与内核正交:

  • 工作助手(默认)
  • 精简模式
  • 法律专家
  • 苏念 · 陪伴倾听

🛠️ 工具

内置 60+ 工具,按需广播(fast / full 路由档)。

类别工具
搜索web_search(searxng → deepseek → tavily → duckduckgo → bing)、web_fetch、image_search
文件file_read / file_write / file_edit / file_list / deliver_file
文档doc_save / doc_list / doc_read
知识库knowledge_search / knowledge_add / knowledge_update
记忆memory_write / memory_search / profile_update
日程schedule_create / schedule_list / dida_*
编程code_read / code_write / code_analyze / code_run / code_assistant
浏览器browser_session / browser_tab / browser_page / browser_client
桌面computer_use / desktop_notify / desktop_countdown
多模态ocr_extract_text / generate_chart / read_image
其他get_weather / lunar_calendar / ui_card / ask_user

工具输出超过 4000 字符会自动压缩,但含 ID/路径/结构化数据的工具(no_compress) 原样透传——压缩会把 ID 搅成散文,模型就没法用了。

详见 工具系统。


🗣️ 语音

TTS / ASR 后端可配置:

  • edge-tts — 在线,零安装,跨平台
  • ethan-tts — 本地,离线、可克隆音色,需要 Apple Silicon + MLX

选本地后端时会先做系统预检:非 Apple Silicon 直接拒绝,零安装动作。 服务启动由选择动作触发,不需要敲命令。

详见 语音。


🔌 渠道

  • Web — 内置,浏览器直接访问
  • Desktop — Tauri 2 应用,支持自动更新
  • Android — APK,与 Web/Desktop 共享后端
  • 飞书 — 机器人,需 lark-cli
  • 微信 — iLink 协议
  • CLI — REPL 交互
  • ACP — stdio JSON-RPC,供编辑器/IDE 拉起

📡 API

所有接口在 /api 下(表中的路径需加此前缀):

GET  /health                      # 健康检查
GET  /models                      # 可用模型列表
POST /chat                        # 对话(stream: true 开启 SSE 流式)
GET  /sessions                    # 会话列表
GET  /sessions/{session_id}       # 会话详情(含消息历史)
GET  /memory/facts                # 记忆列表,分页(limit/offset/total)
GET  /memory/records              # 结构化记忆,分页(可按 type/domain/status 过滤)
GET  /memory/records/search       # 结构化记忆检索
GET  /skills                      # Skill 列表
POST /skills                      # 创建 Skill
POST /skills/evolve               # 手动触发 Skill 自动更新
GET  /schedule                    # 定时任务列表
GET  /system-prompt-preview       # 当前 system prompt 预览
GET  /channels                    # 渠道列表
GET  /knowledge/search            # 语义检索
GET  /ui-resources                # MCP Apps UI 资源:列出
GET  /ui-resources/read?uri=      # MCP Apps UI 资源:读取 HTML + _meta
GET  /kernels                     # 内核列表与可用性
POST /kernels/select              # 切换内核
POST /kernels/context-mode        # 设置外部内核上下文注入档位(off/rules_profile/full)
GET  /tts/backends                # 语音后端可用性
POST /tts/select                  # 切换语音后端

交互式文档:服务启动后访问 /docs。


⚙️ 配置

全部在 ~/.ethan/config.yaml,也可用 ethan setup 交互式配置。

defaults:
  model: provider/model-id
  kernel:
    default: ""                    # "" = 原生 Ethan;可选 dsh / claude_code / opencode / antigravity / codex / pi
    task_rules: {}                 # {"coding": "claude_code"} 按任务类型选内核
    share_tools: all               # all | readonly | off —— 外部内核能用多少 Ethan 的工具
    inject_context: rules_profile  # off | rules_profile | full —— 外部内核上下文注入粒度

network:
  auth_token: "..."        # Web/API 认证
  base_url: ""             # 对外可达地址(内核注入工具时用)

tts:
  backend: edge-tts        # edge-tts | ethan-tts

数据目录 ~/.ethan/:

config.yaml          配置文件
db/sessions.db       会话与消息
db/memory.db         长期记忆
system/              tools.md / soul.md / agent.md 等提示词文件
memory/              user_profile.md / playbook.json
skills/              自定义技能
knowledge/           知识库

🧪 开发

git clone https://github.com/llm011/ethan-agent
cd ethan-agent
uv sync --extra dev

pytest tests/ -q          # 1880+ 测试
ruff check .              # lint
python -m tests.bench_prompt_size   # prompt 体积护栏

前端(Web / Desktop 双端必须同步):

pnpm install
pnpm build:web            # Next.js 静态导出 → ethan/web_dist
pnpm --dir desktop build  # Desktop 前端
pnpm --dir desktop tauri build   # 打桌面安装包

⚠️ 改了 web/ 之后必须重新 build 并替换 ethan/web_dist,否则新前端路由不会生效—— 这个目录在 .gitignore 里、不随代码走。典型症状:代码已合并新路由,但点进会话详情页一片空白 (后端数据完好、前端也不报错)。服务启动时会自检产物是否落后于 web/ 源码并打 WARNING。

Android:

cd app/android
./gradlew assembleDebug   # 产物:app/build/outputs/apk/debug/

详见 贡献与开发。


🗺️ Roadmap

已完成

  • 多模型 Provider(Anthropic + OpenAI 兼容:DeepSeek、Gemini、Ollama、聚合网关等)
  • ReAct agent loop + 流式输出 + 工具时间线
  • 两档路由 fast / full;工具结果超长自动压缩;轮次内去重缓存
  • Prompt Caching(Anthropic 稳定层 cache_control,命中部分成本 0.1×)
  • 分层记忆(工作记忆压缩 → 结构化 fact → 叙事画像)+ 语义召回
  • Skill 系统(内置 + 用户自定义 + 渠道过滤)
  • 多内核运行时(7 个内核,DSH / Claude Code / OpenCode / Antigravity 可共享 Ethan 工具)
  • 定时任务、心跳、后台任务
  • 多渠道(Web / Desktop / Android / 飞书 / 微信 / CLI / ACP)
  • TTS / ASR 可配置后端(在线 edge-tts / 本地 ethan-tts)

待办

  • tools.md 结构性拆分(当前全文注入,占 prompt 六成)
  • Codex / Pi 的 Ethan 工具共享(各自有硬阻碍,详见内核文档)
  • Android 端真机验证

📖 文档


📄 License

MIT License - 详见 LICENSE


版本: 1.0.0b6 维护: Ethan Team

Ver o original no GitHub

Bom para

Relacionados