convez.ai
AgenteAutomaçãoAvançado
huangqianqian120

NexusAgent

huangqianqian120/NexusAgent

Framework robusto para agentes IA com memória inteligente e UI web

Ver no GitHub
BomPluginScore · de 0 a 100

Framework de desenvolvimento de agentes IA em código aberto baseado na arquitetura Claude Code, com sistemas aprimorados de memória (modelo de duas camadas), gestão de habilidades dinâmicas e observabilidade web em tempo real. Inclui UI web moderna, 43+ ferramentas integradas e suporte a arquitetura multi-agentes.

Instalação

$npx convez-ai huangqianqian120/NexusAgent

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
9
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
3

Casos de uso

  • Desenvolvimento de agentes autônomos com memória persistente e contexto inteligente
  • Automação de tarefas complexas com orchestração multi-agentes (Swarm)
  • Prototipagem rápida de assistentes IA via Web UI com hot-reload de habilidades
  • Observabilidade e debugging de comportamentos de agentes em tempo real

Veredito

Projeto sólido e maduro (265 testes passando) que estende Claude Code com camadas práticas: memória de dupla camada reduz redundância de context window, Web UI elimina fricção de experimentação, e sistema de habilidades dinâmicas é verdadeiro diferencial. Ideal para quem quer agentes atualizáveis em produção, mas exige domínio sólido de Python e conceitos de agent design.

README

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

NexusAgent

NexusAgent 是基于 Claude Code 架构的开源 AI Agent 开发框架,在原版基础上增强了记忆管理、技能系统和 Web 可观测性。

⚠️ 本项目基于 Claude Code 和 OpenHarness 构建。

核心特性

🧠 记忆系统(新增)

  • 双层记忆模型 — Header(快速召回)+ Content(完整内容,按需加载)
  • 混合召回 — lexical + recency + priority + graph 多维度评分
  • Token 预算控制 — 可配置召回 budget,默认 2000 tokens
  • 自动 Consolidation — 优先级衰减、去重、TTL 归档
  • 类型分类 — fact / episode / preference / procedure 四种记忆类型

⚡ 技能系统

  • 兼容 anthropics/skills — 生态兼容
  • 运行时动态加载 — 可通过 Web UI 上传/编辑/删除
  • 技能市场 — 技能注册表管理

🔧 工具系统

  • 43+ 内置工具 — 文件操作、Shell、搜索、Web、MCP 协议
  • MCP 协议支持 — Model Context Protocol 扩展
  • 权限钩子 — PreTool/PostTool 钩子,精细控制

🌐 Web UI(新增)

  • 实时对话界面 — Socket.IO 双向通信
  • 会话管理 — 跨会话恢复、历史记录
  • 记忆面板 — 可视化查看/搜索记忆
  • 技能面板 — Web UI 管理技能
  • 多 Provider 切换 — 一键切换后端模型

🤖 多智能体协作

  • Subagent 派生 — 动态创建子 Agent
  • Swarm 团队协作 — CLAUDE_CODE_* 环境变量配置
  • 后台任务 — 长时间运行任务管理

快速开始

方式一:命令行(CLI)

# 克隆仓库
git clone git@github.com:huangqianqian120/NexusAgent.git
cd NexusAgent

# 安装依赖
uv sync

# 配置环境变量(根据你的 Provider 选择)
export OPENAI_BASE_URL=<your-provider-base-url>   # 例:https://api.openai.com/v1
export ANTHROPIC_API_KEY=<your-api-key>
export OPENAI_MODEL=<your-model>                  # 例:gpt-4o、claude-sonnet-4-20250514

# 交互模式
uv run nexus

# 单次查询
uv run nexus -p "解释这段代码"

方式二:Web UI

推荐使用一键启动脚本:

# 一键启动(自动检测依赖和端口)
./start.sh

# 一键停止
./stop.sh

# 访问 http://localhost:5173(端口被占用时自动切换)

或手动启动:

# 启动后端 API 服务(必须设置 CORS_ORIGINS)
CORS_ORIGINS="http://localhost:5173,http://localhost:5174,http://localhost:3000" uv run python -m nexus.web.server &

# 启动前端(另一个终端)
cd frontend/web
npm run dev

# 访问 http://localhost:5173(端口被占用时自动切换到 5174/5175...)

Web UI 功能:

  • 实时对话(Socket.IO 双向通信)
  • 记忆面板(侧边栏 Brain 按钮)
  • 技能面板(侧边栏 Skills 按钮)
  • 会话历史(侧边栏 历史会话 按钮)
  • 设置面板(Provider/Model 切换)

架构

NexusAgent 实现了完整的 Agent Harness 模式:

┌─────────────────────────────────────────────────────────┐
│                      Web UI / CLI                      │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                    Agent Loop                           │
│  ┌─────────┐    ┌──────────┐    ┌───────────────┐   │
│  │ Memory  │ +  │ Skills   │ +  │ Tool Registry │   │
│  │ System  │    │ System   │    │ (43+ tools)   │   │
│  └─────────┘    └──────────┘    └───────────────┘   │
│                           │                           │
│  ┌─────────────────────────────────────────────────┐  │
│  │              API Client (Multi-Provider)         │  │
│  └─────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

模型负责"思考",Harness 负责"执行"——安全、高效、可观测。

项目结构

NexusAgent/
├── src/nexus/              # 核心 Python 包
│   ├── memory/             # 记忆系统(双层模型)
│   ├── skills/             # 技能系统(兼容 anthropics/skills)
│   ├── tools/              # 工具注册表(43+ 工具)
│   ├── services/compact/   # 紧凑压缩(微压缩 + 全量压缩 + 辅助函数)
│   ├── web/                # Web 服务端
│   │   └── routes/         # API 路由(内存/会话/技能/工具/Provider)
│   ├── swarm/              # 多 Agent 协作
│   ├── mcp/                # MCP 协议客户端
│   └── channels/           # IM 渠道集成(Slack/Telegram/Discord/飞书)
├── frontend/web/           # React 前端
│   └── src/
│       ├── components/     # UI 组件
│       ├── hooks/          # WebSocket 等 Hooks
│       └── lib/            # API 客户端
├── tests/                  # 测试(265 用例)
├── scripts/                # 安装 & E2E 脚本
└── .github/workflows/      # CI 流水线(ruff + pytest 矩阵)

开发

环境配置

# 安装依赖(含开发工具)
uv sync --extra dev

# 安装 pre-commit hooks
pre-commit install

代码质量

# 代码检查
uv run ruff check src/ tests/ scripts/

# 代码格式化
uv run ruff format src/ tests/ scripts/

# 类型检查
uv run mypy src/

运行测试

# 全部测试(265 个用例)
uv run pytest tests/ -v

# 指定模块
uv run pytest tests/test_compact.py -v

CI 会在 push 到 main 分支时自动运行 ruff 检查和 Python 3.10/3.11/3.12 测试矩阵。

鸣谢

License

MIT

Ver o original no GitHub

Bom para

Relacionados