AgentNexus 发布全本地 ReAct 智能体 CLI，用 FSM 与 7 层工具治理保障安全

中文 | English

A production-grade, fully local AI agent with FSM-driven safety and 329 test files.

AgentNexus is a ReAct (Thought→Action→Observe) single-agent CLI tool that runs entirely on your machine. No cloud dependency. No data leakage. Your vectors, memory, and trace logs never leave your device.

Unlike prompt-only agents, AgentNexus uses a formal finite state machine (6 states, 14 transition rules) to govern every reasoning loop — making agent behavior deterministic and auditable.

User → CLI/TUI/Desktop → ReAct Agent (FSM + 3-tier LLM Strategy)
       → Tool Gateway (7 Security Gates) → 15 Built-in Tools + MCP
       → Local Storage: ChromaDB | SQLite | JSONL

Why AgentNexus?

Dimension	AgentNexus	Typical Agent Tools
Data Privacy	100% local — vectors, memory, traces on-device	Cloud-dependent, data leaves your machine
Security Model	7-layer tool governance (RBAC, schema, rate-limit, timeout, risk, HITL, audit)	Basic or no tool-level security
Agent Control	FSM-driven loop — 6 states, 14 deterministic transitions	Prompt-driven, unpredictable behavior
Code Sandbox	tiered degradation: bubblewrap/Seatbelt/Low-IL → Docker → local	Single sandbox or none
Security Tests	229 tests across 13 attack surfaces	Ad-hoc or no security testing
Observability	6-layer system: trace + drift detection + fault attribution + alerting + health checks + improvement loop	Basic logging
Evaluation	9 built-in evaluators (agent, trajectory, hallucination, RAG, code, memory...)	Manual or none
Interface	TUI + Desktop (Electron) + API server	Single interface

Features

Capability	Description
🗣️ Conversation & Tasks	TUI interface with ReAct loop: plan→execute→observe
🧠 Local Memory	STM compression pyramid + LTM (SQLite+ChromaDB, score-based eviction)
📚 Knowledge Base RAG	Hybrid retrieval (dense+sparse+RRF+rerank), 8 file formats
🌐 Browser Automation	Via external MCP server — bring your own Playwright/CDP browser toolset
📖 Wiki System	Hybrid Wiki + RAG knowledge management, Karpathy's LLM Wiki pattern, mechanical verification, confidence-based routing
🔒 Security Sandbox	Workspace path sandbox with one-click out-of-bounds approval; shell chain: bubblewrap/Seatbelt/Low-IL → Docker → local fallback
🛡️ Tool Audit	7 security gates (RBAC/Schema/Rate-limit/Timeout/Risk/HITL/Audit)
📈 Observability	6-layer system: JSONL Trace + drift detection + tool fault attribution + alerting + health checks + improvement loop
📊 Evaluation	9 evaluators (Agent/Trajectory/Hallucination/RAG/Code/Memory, etc.)
🎭 Persona System	Agent identity, behavioral principles (stance/autonomy/accountability), and user-defined mission map
🎯 Skill System	Reusable workflow templates, TF-IDF + learned reranker routing
🔌 MCP Integration	Import external tools via stdio/HTTP, full governance
🤖 Sub-agent Delegation	Agent-in-Agent isolated subtask execution
🕸️ Code Knowledge Graph	Semantic search, relationship queries, context retrieval

Quick Start

# Install
pip install -e ".[dev,eval]"

# Initialize (interactive setup)
nexus init

# Start chatting
nexus tui

That's it. No API keys required for local models — just configure your LLM provider during nexus init.

More Commands

nexus kb add ./docs              # Add documents to knowledge base
nexus wiki init default          # Initialize wiki for a RAG namespace
nexus wiki ingest ./doc.md       # Ingest source document into wiki
nexus wiki query "what is X?"    # Query wiki with confidence-based routing
nexus serve                      # Start HTTP/WebSocket API server for desktop GUI
nexus stats --days 7             # View token cost & task metrics
nexus health                     # Run system health checks
nexus alerts --days 7            # View alert history
nexus audit --limit 20           # View tool audit log
nexus eval agent --days 1        # Run agent quality evaluation

Documentation

Document	Content
🚀 Getting Started	Installation, first run, quick tour
🏠 Wiki Home	Architecture diagram, core capabilities
🏗️ Architecture	System architecture, module boundaries, data flow
🤖 ReAct Agent	FSM state machine, 3-tier LLM strategy, JSON fault tolerance
🔧 Tool Governance	7 security gates, 18 tool parameter tables
🧠 Memory System	STM/LTM architecture, compression pyramid, score eviction
📚 RAG System	Hybrid retrieval pipeline, dual ChromaDB clients
📖 Wiki System	Hybrid Wiki + RAG, Karpathy pattern, confidence routing
📖 Wiki System (Detailed)	Wiki internals, verification pipeline, routing logic
🎭 Persona System	Agent identity, behavioral principles, mission map
⌨️ CLI & TUI	CLI commands, TUI interface, keybindings
🖥️ App Runtime	Desktop app runtime, Electron integration
⚙️ Configuration	All configuration items reference
⌨️ Commands	83 commands reference
📊 Evaluation	9 evaluators, RAG metrics
🔒 Security	PII masking, sandbox escape protection
🎯 Skill System	Skill discovery, routing, workflow execution
🔌 MCP Integration	External tool import, governance fusion
📈 Observability	6-layer observability: trace, drift detection, fault attribution, alerting, health checks, improvement loop
📝 Prompt System	Template categories, variable injection
🛠 Development	Environment setup, testing, CI pipeline
🤝 Contributing	Issue/PR guidelines, testing requirements

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        AgentNexus                                │
├──────────────┬──────────────┬──────────────┬────────────────────┤
│  CLI/TUI     │  Desktop     │  API Server  │  MCP Client        │
│  (Typer)     │  (Electron)  │  (FastAPI)   │  (stdio/HTTP)      │
├──────────────┴──────────────┴──────────────┴────────────────────┤
│                    ReAct Agent Core                              │
│  ┌──────────┐  ┌──────────────┐  ┌────────────────────┐        │
│  │ FSM      │  │ LLM Strategy │  │ Prompt Builder     │        │
│  │ (6→14)   │  │ (3-tier)     │  │ (templates)        │        │
│  └──────────┘  └──────────────┘  └────────────────────┘        │
├─────────────────────────────────────────────────────────────────┤
│               Tool Gateway (7 Security Gates)                   │
│  RBAC → Schema → Rate-limit → Timeout → Risk → HITL → Audit    │
├─────────────────────────────────────────────────────────────────┤
│                     Tool Execution Layer                         │
│  file_read · file_write · file_list · shell_exec                │
│  grep_search · web_search · web_fetch · kb_search               │
│  memory_search · memory_save · history_search · todo_*          │
│  subagent_run · express_reaction · exit_plan_mode · MCP         │
├──────────┬──────────────┬───────────────────────────────────────┤
│ ChromaDB │   SQLite     │  JSONL Trace Logs                     │
│ (vectors)│  (relational)│  (observability)                      │
└──────────┴──────────────┴───────────────────────────────────────┘

Tech Stack

Backend: Python 3.11+ · OpenAI-compatible + Anthropic Messages codecs · Pydantic · Typer+Rich · FastAPI · ChromaDB · sentence-transformers

Desktop: Electron · React 19 · TypeScript · Vite · TailwindCSS · Zustand

Testing: pytest · 329 test files — 246 unit · 40 performance · 14 integration · 13 security (229 cases) · 9 regression · 4 eval · 3 misc

Contributing

See CONTRIBUTING.md for guidelines. We welcome bug reports, feature requests, and pull requests.