核心精简，扩展无限 —— 微内核 × 声明式插件 × 全栈流式引擎
将 13 个顶尖开源项目的精华融于一炉，为您呈现一个具备多模型、多 Agent 编排、三层记忆、语音交互与全渠道接入能力的智能体平台。
NexOS 是一款基于微内核 + 声明式插件架构的新一代 AI Agent 平台。它并非又一个"聊天机器人"，而是一个智能体操作系统：以极致精简的内核承载无限扩展的插件生态，用全栈流式引擎驱动毫秒级的实时交互，以工程化的安全体系守护每一次自主执行。
无论是个人效率助手、企业级智能客服，还是面向大工程的编码代理，NexOS 都能以一套统一架构从容应对。它深度剖析并吸收了 Claude Code、Hermes Agent、OpenClaw、M-flow 等 13 个顶尖开源项目的核心优势，站在巨人的肩膀上重新定义了 AI Agent 的能力边界。
🎯 一句话：把 AI Agent 的能力边界，交给想象力。
| 维度 | 我们的答案 |
|---|---|
| 🏛️ 架构 | 微内核 < 5000 行 + 插件化扩展，核心永远精简，功能无限生长 |
| ⚡ 体验 | AsyncGenerator 全栈流式处理，背压控制 + 延迟隐藏，响应快人一步 |
| 🧠 记忆 | 三层 LanceDB 记忆 + 知识图谱 + 混合检索，越用越懂你 |
| 🎙️ 交互 | 全双工语音管线，支持打断、唤醒词与流式合成，对话如真人 |
| 🌐 触达 | 12+ 消息平台一键接入，你的 Agent 无处不在 |
| 🔒 安全 | 39+ 危险命令防护、Docker 沙箱、RBAC 权限引擎，Fail-Closed 默认安全 |
| 🚀 扩展 | 声明式插件 SDK，一个装饰器即可注册工具、渠道与技能 |
| 🏭 工程 | 20+ 架构质量门禁、Pyright strict、80+ 测试，架构自治理永不退化 |
graph TB
subgraph Clients["🖥️ 多端入口"]
Desktop["桌面客户端<br/>PyQt6"]
Web["Web 管理面板<br/>Vue 3 + 16 视图"]
CLI["命令行<br/>CLI"]
Channels["消息平台<br/>Telegram/Discord/飞书…"]
end
subgraph API["🌐 API 网关层"]
Gateway["FastAPI + Uvicorn"]
REST["27+ REST 路由"]
WS["WebSocket / SSE 流式"]
MW["中间件: 鉴权/限流/追踪/安全头"]
end
subgraph Kernel["🧬 微内核层（< 5000 行）"]
Engine["流式引擎<br/>AsyncGenerator"]
Orchestrator["Director + Worker<br/>双层编排"]
Coordinator["Coordinator<br/>多 Agent 协调"]
Compressor["5 层上下文压缩"]
Guard["循环检测 + 错误恢复"]
Security["审批 + RBAC 权限"]
end
subgraph Plugins["🔌 插件层（声明式扩展）"]
Providers["LLM Providers<br/>6 模型 + 故障转移"]
Tools["23+ 内置工具"]
Memory["三层记忆<br/>LanceDB + 图谱"]
Voice["语音管线<br/>Whisper + TTS"]
Skills["技能系统<br/>自改进"]
Tasks["任务引擎 + 提醒"]
Search["Web 搜索 + 代码检索"]
Coding["LSP 代码智能"]
MCP["MCP 客户端/服务端"]
end
subgraph Infra["🏗️ 基础设施层"]
PG[("PostgreSQL")]
Redis[("Redis Streams")]
Lance[("LanceDB 向量库")]
Obs["OpenTelemetry + Prometheus"]
end
Clients --> API
API --> Kernel
Kernel --> Plugins
Plugins --> Infra
Kernel -.依赖注入.-> Infra
分层依赖约束：schemas → infra → kernel ← plugins，cli / ui / api 仅依赖 kernel —— 由 CI 架构检查强制执行，杜绝架构腐化。
- 极致精简：kernel/ 核心代码控制在 5000 行以内，所有能力通过
plugins/声明式注册 - 全栈流式：AsyncGenerator 贯穿查询、工具调用、语音合成全链路，配合背压控制与延迟隐藏，让首 Token 快人一步
- 5 层渐进式上下文压缩：智能工具结果修剪 → 头尾保留截断 → 消息折叠 → 11 部分结构化摘要 → Token 预算尾部保护（含反抖动 + 熔断器），长会话永不溢出
- 四分支错误恢复：上下文溢出压缩重试 / 瞬时错误指数退避 / 故障转移耗尽优雅终止 / 不可恢复错误即时中止，每次失败都有清晰预案
- 5 维度循环检测：SHA256 哈希指纹 + 相同参数识别 + 未知工具 + 无进展检测 + Ping-pong 识别，外加全局断路器，杜绝 Agent 原地打转
- Director + Worker 双层编排：大工程任务自动拆解为子任务图，支持依赖感知调度、并行执行与动态重规划
- Coordinator 多 Agent 协调：多 Director 协同作战，配合 BudgetPool 统一资源与预算控制
- GOAP 目标规划：基于世界状态的符号化规划器，支持自然语言编译计划、执行验证与自动重规划
- Intent 分类 + 预规划：意图识别 → 计划生成 → 计划验证 → 快照存档，步步可回溯
| Provider | 说明 |
|---|---|
| OpenAI | 官方 SDK 直连 |
| Anthropic | 官方 SDK + Prompt Caching |
| Gemini | 官方 SDK |
| AWS Bedrock | 企业级托管 |
| Groq | 极速推理 |
| Ollama | 本地/私有化部署 |
- FallbackProvider 智能故障转移：15 种故障原因精细分类（限流/超时/认证失败/上下文溢出…），每种错误独立重试策略，多 Provider 自动切换 + 冷却期探测恢复
- 凭证池轮换：多 API Key Round-Robin + 自动冷却，高并发下稳定输出
- Prompt Caching：前缀缓存机制显著降低延迟与费用
- 短期记忆：会话窗口，TTL 24h 自动过期
- 长期记忆：重要性评分持久化，越重要的信息留存越久
- 知识图谱：四层锥形图 + 语义边 + 路径成本评分，实体关系一目了然
- FTS5 + 向量混合检索：全文搜索与向量相似度双通道召回，精准与语义兼得
- auto-recall / auto-capture：会话开始自动召回相关记忆，结束自动捕获新知识
- CRDT 同步：多实例部署时记忆无冲突合并
- 语音管线：Whisper 家族 STT + Edge-TTS 语音合成 + 能量/WebRTC 双 VAD
- 三层状态机：Mic → Turn → Remote 合法转换表约束，状态流转万无一失
- LLM-TTS 流式交织：文本生成与语音播放交替进行，告别"读完才说"
- 打断（barge-in）：开口即可打断，真人对话般的自然体验
- 多唤醒词引擎：Picovoice / OpenWakeWord / 能量检测三选一
- 分块转录：长语音不等录音结束即可开始转录
Telegram、Discord、钉钉、飞书、微信公众号、企业微信、Server 酱、Signal、Matrix、WhatsApp、Email、TUI —— 12+ 消息平台，一套逻辑、全平台触达。配套 DM 配对安全（恒定时间比较 + 配对令牌），陌生人无法冒充你的 Agent。
- Docker 沙箱隔离：危险命令容器化执行，CPU / 内存 / 网络三重限制
- 39+ 危险命令防护：fork 炸弹、
dd、mkfs、chmod 777、curl | sh等完整覆盖 - 审批工作流：approve_once / always_ask / auto_approve / deny_all 四种策略，灵活可控
- RBAC 权限引擎：管理员策略 > 用户角色 > 会话运行时三层模型，Fail-Closed 默认拒绝
- SSRF 防护：外发请求统一校验，杜绝内网探测
| 分类 | 能力 |
|---|---|
| 🖥️ 系统 | Bash 沙箱、守护进程管理、文件读写与发送 |
| 🌐 网络 | Web 搜索、网页抓取（TLS 伪装 + 代理轮换）、浏览器自动化 |
| 💻 编程 | Git 操作、LSP 代码智能、工程脚手架、代码质量检查 |
| 📋 任务 | TODO 管理、GOAP 规划、长期任务引擎、定时提醒 |
| 🧠 记忆 | 记忆检索、知识图谱查询、意图工具 |
| 🎭 编排 | 子 Agent 派发、Worker 协作、计划模式 |
声明式注册：一个装饰器即可新增工具，插件 SDK 让第三方开发者零门槛接入。
- 会话列表 + Markdown 聊天区（代码高亮）+ 工具面板 + 记忆浏览 + 设置的多面板布局
- 设计令牌 + 组件化 QSS 主题系统，Light / Dark / System 三模式一键切换
- qasync 异步桥接，UI 永不卡顿；系统托盘消息提醒，任务状态尽在掌握
- 16 视图页面：Chat / History / Jobs / Kanban / Models / Profiles / Logs / Usage / Skills / Memory / Settings / Gateways / Channels / Terminal / GroupChat / Files
- Vue 3 + Vite + Naive UI，SSE 流式聊天 + WebSocket 实时终端
- 8 种语言国际化，出海无压力
轻量、极速、可脚本化 —— 开发者的效率利器。
| 层级 | 技术选型 |
|---|---|
| 语言 | Python 3.12+ |
| API 框架 | FastAPI + Uvicorn |
| 数据库 | SQLAlchemy (asyncio) + PostgreSQL / SQLite |
| 向量记忆 | LanceDB |
| Schema 验证 | Pydantic v2 + Pydantic Settings |
| 桌面 UI | PyQt6 + QSS 设计令牌主题 |
| Web 前端 | Vue 3 + Vite + Naive UI |
| LLM SDK | OpenAI / Anthropic 官方 SDK |
| 消息队列 | Redis Streams |
| 可观测性 | OpenTelemetry + Prometheus + structlog 结构化 JSON 日志 |
| 测试 | pytest + pytest-asyncio + pytest-cov |
| 类型检查 | Pyright（strict 模式） |
| 代码质量 | Ruff（py312 目标） |
| 构建 | Hatchling + Docker 多阶段构建 |
- Python 3.12+
- pip 或 uv
- Docker（可选）— 沙箱隔离
- Playwright（可选）— 浏览器渲染
# 克隆仓库
git clone <repo-url>
cd nexos
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 安装依赖（按需选择特性分组）
pip install -e .[voice,server,telemetry]
# 配置环境变量
cp .env.example .env
# 编辑 .env，填入 API Key 等配置# 方式一：桌面客户端（PyQt6）
python -m agent_core.ui.main_window # 或 agent-ui / start_UI.bat
# 方式二：CLI 命令行
python -m agent_core.cli.main # 或 agent / start_cli.bat
# 方式三：API 服务器
python -m agent_core.api.app # 或 agent-server / start_sever.batdocker compose up -d自动编排 PostgreSQL + Redis + App 三个服务，健康检查自愈，数据卷持久化。
| 变量 | 说明 | 默认值 |
|---|---|---|
AGENT__DB__URL |
数据库连接串 | postgresql+asyncpg://agent:agent@postgres:5432/agent |
AGENT__REDIS__URL |
Redis 连接串 | - |
AGENT__AUTH__JWT_SECRET |
JWT 签名密钥 | 必填 |
AGENT__DATA_DIR |
数据目录 | ./data |
AGENT__PROMPT_CACHING_ENABLED |
Prompt 前缀缓存开关 | false |
OPENAI_API_KEY |
OpenAI 密钥 | 必填其一 |
ANTHROPIC_API_KEY |
Anthropic 密钥 | 必填其一 |
💡 全部配置遵循
AGENT__<分类>__<字段>命名规范，40+ 个配置领域、261 行完整模板见 .env.example。修改.env后支持热重载，无需重启服务。
nexos/
├── agent_core/
│ ├── kernel/ # 🧬 微内核（< 5000 行）
│ │ ├── engine.py # 流式引擎
│ │ ├── orchestrator.py # Director + Worker 编排
│ │ ├── coordinator.py # 多 Agent 协调
│ │ ├── compressor.py # 5 层上下文压缩
│ │ ├── permissions.py # RBAC 权限引擎
│ │ ├── approval.py # 审批工作流
│ │ ├── hooks.py # 内核钩子系统
│ │ └── goap/ # GOAP 目标规划器
│ ├── plugins/
│ │ ├── providers/ # 🌐 6 模型 Provider + 故障转移
│ │ ├── tools/ # 🧰 23+ 内置工具
│ │ ├── channels/ # 🌍 12+ 消息平台适配器
│ │ ├── memory/ # 🧠 三层记忆 + 知识图谱
│ │ ├── voice/ # 🎙️ 语音管线 + 状态机
│ │ ├── skills/ # ⚡ 技能系统（自改进）
│ │ ├── tasks/ # 📋 长期任务引擎
│ │ ├── reminders/ # ⏰ 定时提醒
│ │ ├── search/ # 🔍 Web 搜索 + 混合检索
│ │ ├── coding/ # 💻 LSP 代码智能
│ │ ├── mcp/ # 🔗 MCP 客户端/服务端
│ │ └── sdk/ # 📦 外部插件 SDK
│ ├── api/ # 🌐 FastAPI 服务（27+ 路由）
│ ├── ui/ # 🖥️ PyQt6 桌面客户端
│ ├── cli/ # ⌨️ 命令行入口
│ ├── reasoning/ # 🤔 推理银行/整合/蒸馏
│ ├── infra/ # 🏗️ 配置/日志/缓存/遥测/SSRF
│ └── schemas/ # 📐 Pydantic 数据模型
├── web/ # 🖼️ Vue 3 Web 管理面板
├── scripts/ # 🛡️ 20+ 质量门禁脚本
├── tests/ # 🧪 80+ 测试文件
├── docs/ # 📚 架构设计与对比分析文档
├── Dockerfile # 🐳 多阶段构建
└── docker-compose.yml # 🐳 一键编排
NexOS 相信：架构不是设计出来的，是治理出来的。
- CI/CD 流水线：GitHub Actions 在 push/PR 时串联架构检查 + Ruff 检查 + pytest 测试，Python 3.11 / 3.12 双版本矩阵验证
- 20+ 质量门禁：循环依赖检测、分层依赖校验、模块大小守卫、类型注解覆盖率、异步反模式扫描、存根/TODO 扫描、安全审计、Schema 演进检查 ——
python scripts/check_all.py一键全检 - 80+ 测试用例：覆盖 API、认证、引擎循环检测、工具注册、插件、记忆、搜索、权限、编排、语音、MCP 等全部核心模块
- 可观测性：OpenTelemetry 分布式追踪 + Prometheus 指标 + structlog 结构化 JSON 日志 + 请求级全链路追踪（X-Request-ID）
- 配置热重载：
.env变更自动感知，EventBus 广播config_reloaded事件，组件无感刷新
| 原则 | 内涵 |
|---|---|
| 🧬 核心精简，扩展无限 | kernel/ < 5000 行，所有功能插件化 |
| ⚡ 流式优先 | AsyncGenerator 贯穿全栈，背压控制 |
| 🔒 安全默认（Fail-Closed） | 工具默认需审批、默认不可并发 |
| 💉 依赖注入 | Container 统一管理组件，禁止全局变量 |
| 🏷️ 声明式注册 | 装饰器 + 清单发现，零配置接入 |
| 🏛️ 架构自治理 | 自动化检查脚本防止架构退化 |
NexOS 深度剖析并吸收了以下 13 个顶尖开源项目的核心优势：
| 项目 | 核心借鉴 |
|---|---|
| Claude Code | AsyncGenerator 流式、5 层压缩、流式工具执行 |
| Hermes Agent | 多凭证轮换、技能自改进、多平台适配 |
| OpenClaw | 清单驱动插件、冷却期探测、架构检查体系 |
| OpenHarness | 多 Agent 集群、Repo Autopilot、Hook 系统 |
| Browser-Harness | 合成器级点击、自编辑工具、领域技能 |
| M-flow | 图路由检索、四层锥形图、语义边 |
| Paseo | Docker-for-Agents、ACP 协议、跨设备客户端 |
| TuriX-CUA | 四角色分离、VLM 桌面操作 |
| Scrapling | 自适应元素定位、TLS 伪装、代理轮换 |
| Agency-Agents | NEXUS 编排、阶段流水线、Reality Checker |
| TryVoice-OSS | 三层 FSM、LLM-TTS 流式交织、分块转录 |
| Portmaster | 模块 Group 状态机、Worker 自愈 |
| Hermes Web UI | 16 视图 Web 面板、BFF 架构、i18n |
详见 docs/ 中的全量对比分析文档。
NexOS — 核心精简，扩展无限 🚀