双许可证 · 开源采用 AGPL-3.0，闭源采用 专属许可（需书面授权）。 商业合作：contact@nagaagent.com / bilibili【柏斯阔落】

更新日志

目录

1. 快速开始
2. 功能导览（主面板）
3. 对话
4. 记忆云海
5. 技能工坊
6. 娜迦网络
7. 枢机集市
8. 终端设置
9. 音律坊
10. 悬浮球
11. 全局功能
12. 后端架构
13. 可选配置
14. 端口一览
15. 故障排除

快速开始

环境要求

• Python 3.11（>=3.11, <3.12）
• 可选：uv — 加速依赖安装
• 可选：Neo4j — 本地知识图谱记忆

安装

git clone https://github.com/Xxiii8322766509/NagaAgent.git
cd NagaAgent


#前端安装
cd frontend
npm install
cd..


#后端安装
# 方式一：setup 脚本（自动检测环境、创建虚拟环境、安装依赖）
python setup.py

# 方式二：uv
uv sync

# 方式三：手动
python -m venv .venv
source .venv/bin/activate   # Windows: .\.venv\Scripts\activate
pip install -r requirements.txt

最小配置

复制 config.json.example 为 config.json，填入 LLM API 信息：

{
  "api": {
    "api_key": "your-api-key",
    "base_url": "https://api.deepseek.com",
    "model": "deepseek-v3.2"
  }
}

支持所有 OpenAI 兼容 API（DeepSeek、通义千问、OpenAI、Ollama 等）。

启动

cd frontend && npm run dev （配置了一键启动）

功能导览（主面板）

启动后进入主面板（PanelView），采用 3D 视差效果（鼠标移动触发透视旋转）。 所有功能从主面板的八个入口按钮展开：

1. 对话 · MessageView

流式工具调用

对话引擎通过 SSE 流式输出，同时实时送达前端显示与 TTS 分句播放。 工具调用不依赖 OpenAI Function Calling API，LLM 在文本中以 ```tool``` 代码块嵌入 JSON，任何 OpenAI 兼容提供商均可使用。

单轮工具调用流程：

LLM 流式输出 ──SSE──▶ 前端实时显示
       │
       ▼
parse_tool_calls_from_text()
  ├─ Phase 1: 提取 ```tool``` 代码块
  └─ Phase 2: 兜底提取裸 JSON
       │
       ▼
  按 agentType 路由
  ├─ "mcp"      → MCPManager.unified_call()
  ├─ "openclaw" → Agent Server /openclaw/send
  └─ "live2d"   → UI 动画通知
       │
       ▼
  asyncio.gather() 并行执行所有工具
       │
       ▼
  结果注入 messages，进入下一轮 LLM 调用（最多 5 轮）

• 文本解析：json5 容错解析，全角字符自动标准化
• SSE 格式：data: {"type":"content"|"reasoning","text":"..."}\n\n（直接 JSON，不含 base64）
• 循环上限：max_loop_stream = 5（可配置）

源码：apiserver/agentic_tool_loop.py

上下文压缩

会话 token 超过 100k 时自动触发压缩，避免上下文溢出：

摘要结构（6 分区）：关键事实 / 用户偏好 / 重要决定 / 待办事项 / 背景信息 / 最近状态。 <compress> 标签持久化到会话文件，不计入 LLM token 统计。

DeepSeek 推理链展示

使用 DeepSeek 时，reasoning 字段通过 SSE 实时推送，前端以独立样式展示思考过程。

2. 记忆云海 · MindView

GRAG 知识图谱记忆

GRAG（Graph-RAG）从对话中自动提取五元组并存入 Neo4j，对话时自动检索作为 LLM 上下文。

五元组结构：(主体, 主体类型, 谓词, 客体, 客体类型)

提取流程：

1. 结构化提取（优先）：beta.chat.completions.parse() + Pydantic QuintupleResponse，temperature=0.3，重试 3 次
2. JSON 党底：解析失败时提取首个 [ 到末尾 ] 的内容
3. 过滤规则：只保留事实（行为、关系、状态、偏好），过滤隐喻、假设、纯情感

实体类型： person / location / organization / item / concept / time / event / activity

任务管理器：

• 3 个 asyncio worker 消费 asyncio.Queue(maxsize=100)
• SHA-256 去重：相同文本的重复任务自动跳过
• 每小时清理超过 24h 的已完成任务

双重存储：

• 本地：logs/knowledge_graph/quintuples.json
• 云端：Neo4j 图数据库，graph.merge() upsert

RAG 检索： 关键词提取 → Cypher 查询 → 格式化为 主体(类型) —[谓词]→ 客体(类型) 注入上下文

远程记忆： 登录用户优先使用 NagaMemory 云端；未登录时可使用本地 GRAG。为避免性能损耗，云端链路不再自动回退本地 Neo4j。

源码：summer_memory/

意识海 3D 可视化

Canvas 2D + 手写 3D 投影（非 WebGL），球面坐标相机，透视除法 700 / depth。

7 层渲染顺序： 背景渐变 → 地面网格 → 水面平面 → 体积光（3 束光柱）→ 粒子系统（3 层 125 颗）→ 生物荧光浮游生物（10 个带拖尾）→ 知识图谱节点与边（深度排序）

图谱映射： subject/object → 节点，predicate → 有向边，度中心性 → 节点高度权重，上限 100 节点

交互： 拖拽旋转、中键平移、滚轮缩放、节点点选/拖拽、关键词搜索过滤

3. 技能工坊 · SkillView

内置 MCP Agent

基于 Model Context Protocol 的可插拔工具架构，每个工具以独立 Agent 运行：

注册与发现： mcp_registry.py glob 扫描 **/agent-manifest.json，importlib.import_module 动态实例化。

MCP 管理 UI

前端 McpAddDialog.vue 提供图形化 MCP 工具管理界面，支持在线添加 / 删除工具（无需重启）。

社区 Skill 安装

技能工坊支持一键安装社区发布的 Skill（Agent Browser、Brainstorming、Context7、Firecrawl Search 等）。 后端接口：GET /openclaw/market/items、POST /openclaw/market/items/{id}/install

源码：mcpserver/

4. 娜迦网络 · 论坛社区

社区论坛

从主面板"娜迦网络"区块进入，内嵌完整社区功能：

源码：frontend/src/forum/

积分好感度系统

登录用户专属的游戏化互动体系：

相关 API（通过 API Server 代理至 Naga 门户）：/api/checkin、/api/affinity、/api/credits

5. 枢机集市 · MarketView

枢机集市整合了所有资源获取与管理入口，分为七个 Tab：

6. 终端设置 · ConfigView

设置页三合一重构，原分散配置集中在单一页面的三个 Tab：

角色卡系统

characters/ 目录管理可切换的 AI 角色，每个角色以 JSON 配置文件描述：

{
  "ai_name": "娜杰日达",
  "user_name": "用户",
  "live2d_model": "NagaTest2/NagaTest2.model3.json",
  "prompt_file": "conversation_style_prompt.txt",
  "portrait": "Naga.png",
  "bio": "由开发者柏斯阔落亲手创造的AI助手，简称娜迦。"
}

• 每个角色目录包含独立的对话风格提示词、Live2D 模型资源、立绘图像
• 激活角色后，AI 名称与 Live2D 模型由角色 JSON 统一管理，不可在界面手动覆盖
• 默认角色：娜杰日达

源码：characters/

7. 音律坊 · MusicView

独立音乐播放器，与主界面 BGM 共享同一播放实例（统一 BGM 架构）：

• 歌单编辑（MusicEditView）：管理曲目列表，保存后实时同步至全局播放器
• 播放状态同步：播放 / 暂停图标与音频事件实时联动
• 列表循环：当前曲目结束后自动播放下一首
• Live2D 口型同步：TTS 播放期间，AdvancedLipSyncEngineV2 以 60FPS 驱动 Live2D 嘴形

8. 悬浮球 · FloatingView

点击主面板"悬浮"按钮进入轻量悬浮球窗口模式，四种状态循环切换：

ball（100×100 圆球）→ compact（420×100 折叠条）→ full（420×N 展开）→ classic（正常窗口）

外观与动效：

• 序列帧眨眼动画：5 帧（睁眼 → 半闭 → 闭眼 → 半闭 → 着眼），70ms / 帧，随机间隔触发
• 生成回复时：球体光晕脉冲特效
• 悬停时：亮度提升效果
• 透明无边框窗口，支持自由拖拽定位

功能：

• 悬浮状态下可直接输入对话，历史消息在 compact / full 状态下可回溯
• 截图捕获面板：选取屏幕窗口作为图像附件
• 文件上传支持
• 右键菜单通过 Electron 原生菜单实现（避免小窗口裁剪）

全局功能

语音交互

TTS（语音合成）

• 引擎：Edge-TTS，OpenAI 兼容接口 /v1/audio/speech
• 架构：3 线程流水线 — 分句队列 → TTS 调用（Semaphore(2) 并发）→ pygame 播放
• Live2D 口型同步：60FPS 提取 5 参数（mouth_open / mouth_form / mouth_smile / eye_brow_up / eye_wide）
• 端口清理：启动时自动检测并释放占用端口

ASR（语音识别）

• 本地引擎：FunASR，支持 VAD 端点检测与 WebSocket 实时流
• 三模式自动切换：LOCAL（FunASR）→ END_TO_END（Qwen Omni）→ HYBRID

实时语音对话（需 DashScope API Key）

• 基于 Qwen Omni 的全双工 WebSocket 语音交互
• 回声抑制、VAD 检测、音频分块（200ms）、会话冷却控制

{
  "voice_realtime": {
    "enabled": true,
    "provider": "qwen",
    "api_key": "your-dashscope-key",
    "model": "qwen3-omni-flash-realtime"
  }
}

源码：voice/

Live2D 虚拟形象

使用 pixi-live2d-display + PixiJS WebGL 渲染 Cubism Live2D 模型。 SSAA 超采样抗锯齿：Canvas 按 width × ssaa 渲染，CSS transform: scale(1/ssaa) 缩放。

4 通道正交动画系统（live2dController.ts）：

合并顺序：体态 → 嘴形 → 动作 → 手动覆盖 → 表情混合 → 追踪混合

OpenClaw 电脑控制

对接 OpenClaw Gateway（端口 18789），通过自然语言调度 AI 编程助手执行本地任务。

• 三级回退启动： 打包内嵌 → 全局 openclaw 命令 → 自动 npm install -g openclaw
• 支持 sessionKey hooks（2026.2.17+），可配置自定义 hooks 路径
• POST /openclaw/send 发送指令，最长等待 120 秒

任务调度器（TaskScheduler）：

• 任务步骤记录（目的 / 内容 / 输出 / 分析 / 成功与否）
• 自动提取"关键发现"标记
• 内存压缩：步骤数超阈值时调用 LLM 生成 CompressedMemory（key_findings / failed_attempts / current_status / next_steps）
• schedule_parallel_execution() 通过 asyncio.gather() 并行执行任务列表

源码：agentserver/

启动动画

后端架构

NagaAgent 由四个独立微服务组成，main.py 统一编排启动：

┌─────────────────────────────────────────────────────────┐
│                   Electron / PyQt5 前端                   │
│  Vue 3 + Vite + UnoCSS + PrimeVue + pixi-live2d-display │
│                                                         │
│  PanelView · MessageView · MindView · SkillView         │
│  MarketView · ConfigView · MusicView · FloatingView     │
│  ForumListView · ForumPostView · ForumQuotaView …       │
└──────────┬─────────────┬──────────────┬─────────────────┘
           │             │              │
   ┌───────▼──────┐ ┌────▼────┐  ┌─────▼──────┐
   │  API Server  │ │  Agent  │  │   Voice    │
   │   :8000      │ │  Server │  │  Service   │
   │              │ │  :8001  │  │   :5048    │
   │ 对话 / SSE   │ │         │  │            │
   │ 工具调用     │ │ 任务调度│  │ TTS / ASR  │
   │ 上下文压缩   │ │ OpenClaw│  │ 实时语音   │
   │ 文档上传     │ │         │  │            │
   │ 认证代理     │ └────┬────┘  └────────────┘
   │ 记忆 API     │      │
   │ Skill 市场   │  ┌───▼──────────┐
   │ 配置管理     │  │  OpenClaw    │
   └──────┬───────┘  │  Gateway    │
          │          │  :18789     │
   ┌──────▼──────┐   └─────────────┘
   │ MCP Server  │
   │   :8003     │
   │ 工具注册    │
   │ Agent 发现  │
   │ 并行调度    │
   └──────┬──────┘
          │
  ┌───────┴───────────────────────┐
  │      MCP Agents（可插拔）      │
  │ 天气 | 搜索 | 抓取 | 视觉     │
  │ 启动器 | 攻略 | 文档 | MQTT   │
  └───────────────────────────────┘
          │
   ┌──────▼──────┐
   │    Neo4j    │
   │   :7687     │
   │  知识图谱   │
   └─────────────┘

目录结构

NagaAgent/
├── main.py                   # 统一入口，编排所有服务
├── build.py                  # 跨平台构建脚本
├── config.json               # 运行时配置（从 config.json.example 复制）
├── pyproject.toml            # 版本 5.1.0，项目元数据与依赖
│
├── apiserver/                # API Server（:8000）
│   ├── api_server.py         #   FastAPI 主应用
│   ├── agentic_tool_loop.py  #   多轮工具调用循环
│   ├── llm_service.py        #   LiteLLM 统一 LLM 调用
│   └── streaming_tool_extractor.py  # 流式分句 + TTS 分发
│
├── agentserver/              # Agent Server（:8001）
│   ├── agent_server.py
│   └── task_scheduler.py     #   任务编排 + 压缩记忆
│
├── mcpserver/                # MCP Server（:8003）
│   ├── mcp_server.py
│   ├── mcp_registry.py       #   manifest 扫描 + 动态注册
│   ├── mcp_manager.py        #   unified_call() 路由
│   ├── agent_weather_time/
│   ├── agent_open_launcher/
│   ├── agent_game_guide/
│   ├── agent_online_search/
│   ├── agent_crawl4ai/
│   ├── agent_playwright_master/
│   ├── agent_vision/
│   ├── agent_mqtt_tool/
│   └── agent_office_doc/
│
├── summer_memory/            # GRAG 知识图谱记忆
│   ├── quintuple_extractor.py
│   ├── quintuple_graph.py
│   ├── quintuple_rag_query.py
│   ├── task_manager.py
│   ├── memory_manager.py
│   └── memory_client.py      #   NagaMemory 远程客户端
│
├── voice/                    # 语音服务（:5048）
│   ├── output/               #   TTS + 口型同步
│   └── input/                #   ASR + 实时语音
│
├── characters/               # 角色配置目录
│   └── 娜杰日达/             #   prompt / Live2D 模型 / 立绘
│
├── frontend/                 # Electron + Vue 3 前端
│   ├── electron/             #   主进程
│   │   └── modules/          #   backend / hotkeys / menu / tray / updater / window
│   └── src/
│       ├── views/            #   所有页面视图
│       ├── forum/            #   论坛模块
│       ├── components/       #   通用组件
│       ├── composables/      #   useAuth / useBackground / useAudio …
│       └── utils/            #   live2dController / session / config
│
├── system/                   # 配置加载、环境检测、系统提示词
├── guide_engine/             # 游戏攻略引擎
└── logs/                     # 运行日志、知识图谱文件

可选配置

{
  "grag": {
    "enabled": true,
    "neo4j_uri": "neo4j://127.0.0.1:7687",
    "neo4j_user": "neo4j",
    "neo4j_password": "your-password"
  }
}

{
  "system": { "voice_enabled": true },
  "tts": {
    "port": 5048,
    "default_voice": "zh-CN-XiaoxiaoNeural"
  }
}

{
  "voice_realtime": {
    "enabled": true,
    "provider": "qwen",
    "api_key": "your-dashscope-key",
    "model": "qwen3-omni-flash-realtime"
  }
}

{
  "web_live2d": {
    "ssaa": 2,
    "model": {
      "source": "./models/your-model/model.model3.json",
      "x": 0.5,
      "y": 1.3,
      "size": 6800
    },
    "face_y_ratio": 0.13,
    "tracking_hold_delay_ms": 100
  }
}

{
  "mqtt": {
    "enabled": true,
    "broker": "mqtt-broker-address",
    "port": 1883,
    "topic": "naga/agent/topic",
    "client_id": "naga-agent-client"
  }
}

端口一览

故障排除

python main.py --check-env --force-check  # 完整环境诊断
python main.py --quick-check              # 快速检查
python update.py                          # 自动 git pull + 依赖同步

贡献

欢迎提交 Issue 和 Pull Request。如有问题，可加入 QQ 频道 nagaagent1。

Star History

NagaAgent 快速上手指南

NagaAgent 是一款具备 Live2D 虚拟形象、知识图谱记忆及流式工具调用能力的二次元超能 AI 助手。本指南将帮助您快速在本地部署并运行该工具。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Windows / macOS / Linux
• Python 版本：必须为 Python 3.11 (要求 >=3.11, <3.12)
• Node.js：用于前端构建（建议最新 LTS 版本）
• 可选依赖：
  • uv：推荐安装，可大幅加速 Python 依赖安装过程。
  • Neo4j：如需使用本地知识图谱记忆功能，需安装并运行 Neo4j 数据库。

2. 安装步骤

第一步：克隆项目

打开终端或命令行工具，执行以下命令下载源码：

git clone https://github.com/Xxiii8322766509/NagaAgent.git
cd NagaAgent

第二步：安装前端依赖

进入前端目录并安装 Node.js 依赖：

cd frontend
npm install
cd ..

提示：国内用户若遇到 npm 下载缓慢，可临时切换镜像源： npm config set registry https://registry.npmmirror.com

第三步：安装后端依赖

您可以选择以下任一方式安装 Python 后端环境：

方式 A：使用自动脚本（推荐） 自动检测环境、创建虚拟环境并安装依赖：

python setup.py

方式 B：使用 uv（极速） 如果您已安装 uv：

uv sync

方式 C：手动安装

python -m venv .venv
# Windows:
.\.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

pip install -r requirements.txt

提示：国内用户使用 pip 时建议指定清华或阿里镜像源： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 基本配置

在运行前，需要配置大模型 API 信息。

1. 在项目根目录下，将示例配置文件复制为正式配置文件：

   cp config.json.example config.json
   

   (Windows PowerShell 用户请使用 Copy-Item config.json.example config.json)

2. 编辑 config.json，填入您的 API Key 和模型信息。NagaAgent 支持所有 OpenAI 兼容接口（如 DeepSeek、通义千问、OpenAI 等）：

{
  "api": {
    "api_key": "your-api-key",
    "base_url": "https://api.deepseek.com",
    "model": "deepseek-v3.2"
  }
}

4. 启动运行

完成上述步骤后，即可启动应用。项目已配置一键启动脚本，直接在根目录或前端目录运行均可（推荐在前端目录启动以同时拉起前后端服务）：

cd frontend
npm run dev

启动成功后，系统将自动打开浏览器窗口进入 主面板（PanelView）。您将看到具备 3D 视差效果的界面，并通过左侧导航栏体验以下核心功能：

• 对话：与 Live2D 娜迦进行流式语音/文字交互。
• 记忆云海：查看基于知识图谱的 3D 记忆可视化。
• 技能工坊：管理 MCP 工具与安装社区技能。
• 悬浮球：点击主面板“悬浮”按钮，可切换至桌面轻量级悬浮窗模式。