双许可证 · 开源采用 AGPL-3.0，闭源采用 专属许可（需书面授权）。 商业合作：[email protected] / 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

Star History Chart