<div align="center">

NagaAgent

你的二次元超能AI助手

流式工具调用 · 知识图谱记忆 · Live2D 虚拟形象 · 语音交互 · 娜迦网络社区

《娜迦协议》包括对话、记忆、MCP、skills、openclaw集成，以打造丰富且易用的ai工具为核心，成为用户端侧的二次元超能ai助手。

软件包含如下功能：①一键登陆自动配置所有apikey，与具备Live2d形象的娜迦进行鼠标互动和亲切对话；②通过内置openclaw快速探索自己需要的知识领域，或是列出任务方向让其自动探索执行；③根据对话历史自动构建三维记忆云海，并将记忆注入后续对话；④通过对话之余留下的线索碎片，探索娜迦网络中的神秘娜迦世界；⑤内置游戏攻略功能，可通过交互或自动识别游戏画面，了解到游戏正在进行的细节信息，并给出建议。可通过MAA等游戏操作插件来自动打游戏；⑥还具有自我配置、浏览器操纵、音乐盒等丰富组件。

娜迦的一切未来，等你探索。

简体中文 | English | 日本語

QQ 机器人联动：Undefined QQbot

</div>

---

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

---

更新日志

| 日期 | 版本 | 内容 | |------|------|------| | 🛰️ 2026-03-14 | — | 干员通讯录升级为设置弹窗（名称 / 人设 / 引擎 / 灵魂文档 / 专有 MCP·Skill）；技能工坊接入 NagaHub 与通用 MCP 预热；探索链路新增 QQ / 飞书完成通知；云端记忆优先时不再回退本地 Neo4j | | 🧩 2026-03-13 | — | OpenClaw 编排链路与打包集成继续扩展；后端 spec 修复 Windows 控制台 Unicode 输出报错 | | 🧱 2026-03-11 | — | OpenClaw Skill 自动执行；干员独立 workspace；模型选择器与定价显示接入 Default / Deepseek-V3.2 / Kimi-K2.5 | | 🛠️ 2026-03-09 | — | 深度集成 OpenClaw vendor 源码编译与统一配置；论坛未登录 401 风暴修复；Windows 托盘图标修复 | | 📦 2026-03-08 | — | naga-backend.spec 持续修正；应用扫描器支持环境变量与 macOS；工具结果默认折叠；枢机集市移除记忆云迁 / MCP 工具 / 智能体技能三板块 | | 🚦 2026-03-07 | — | Node.js 与 uv 运行时随包分发；MCP 命令解析器统一；OpenClaw Gateway 启动诊断增强；打包版音乐 / 唤醒语音 / 记忆云海等问题修复 | | 🧰 2026-03-06 | — | GitHub Actions 构建发布流水线；Electron 自动更新替换旧补丁系统；CI 构建资源与 charset_normalizer 打包修复；论坛与积分轮询细节优化 | | 🔊 2026-03-05 | — | TTS 开关、消息队列与串行发送重构；RAG 记忆召回增强；Gemini / 自动 Function Calling 支持；充值界面与远程记忆稳定性修复 | | 🧠 2026-03-04 | — | 迁移到原生 Function Calling；DogTag 接管 heartbeat / proactive vision；前后端热补丁系统与 4 层安全防护；流式文本与渐进式 TTS 优化 | | 🔎 2026-03-03 | — | web_search 直接接入 NagaBusiness 搜索代理；论坛连接、TTS 流式播放与 OpenClaw 轮询降级修复；Live2D 与 Electron 稳定性修复 | | ❤️ 2026-03-02 | — | Heartbeat v3 事件驱动重构；naga_control 自编排工具；打包时嵌入 agent-browser；启动诊断、健康检查与 OpenClaw 配置路径修复 | | 🌐 2026-03-01 | — | 已登录走 NagaBusiness、未登录走 Brave / OpenClaw 的搜索代理成型；OpenClaw 工具直调与自动启动完善；游戏攻略与角色音色配置更新 | | 🗂️ 2026-02-28 | — | 持久化存储统一迁移到 ~/.naga 用户目录；ForumQuotaView 网络探索控制中心；旅行模块与语音交互全面升级 | | 🎙️ 2026-02-27 | — | 接入 ASR 语音识别（MediaRecorder + NagaBusiness 代理）；会话风格、Electron 背景、MCP vision 与服务器配置整理 | | 🎆 2026-02-26 | 5.1.0 | 娜迦网络社区论坛上线；设置三合一重构；旅行模式；积分配额页；枢机集市与主面板更新 | | ⚡ 2026-02-25 | 5.1.0 | TTS 全链路修复（CORS / asyncio）；build.py 跨平台构建；上下文压缩持久化；角色系统更新；提示词注入架构重构 | | 🎵 2026-02-24 | — | Neo4j 连接超时修复；统一 BGM 播放器；音律坊歌单编辑；MCP 管理 UI；悬浮球透明窗口 + 悬停亮度 | | 🏗️ 2026-02-23 | — | 跨平台构建完善；版本号统一 pyproject.toml 管理；提示词/截图/视觉优化；角色文件打包迁移 | | 💕 2026-02-22 | — | 积分好感度系统（签到 / 好感度 / 积分）；悬浮球阴影与拖拽修复；登录自动恢复；OpenClaw hooks 修复 | | 🎶 2026-02-21 | — | 音律坊图标更新；MCP Agents 更新；悬浮球小按钮 | | 🗜️ 2026-02-20 | — | 上下文压缩三级重构（<compress> 标签 / 跨会话继承）；MCP 管理 UI；悬浮球透明窗口；音律坊功能修正 | | 🔄 2026-02-19 | — | SSE 去除 base64 直接 JSON 传输；移除冗余后台意图分析器；config_manager 自动检测编码 | | 🔧 2026-02-17 | — | 悬浮球序列帧路径改为相对路径，修复打包后头像不显示 | | 🚀 2026-02-16 | 5.0.0 | NagaModel 网关统一接入；DeepSeek 推理链实时展示；记忆云海 UI 自适应修复 | | 🧠 2026-02-15 | — | 统一附加知识块 + 消除历史污染；LLM 流式重试；七天自动登录；开机自启动 | | 🌊 2026-02-14 | — | NagaMemory 云端远程记忆；意识海 3D 重写；启动粒子动画；版本更新检查弹窗；用户使用协议 | | ✨ 2026-02-13 | — | 悬浮球 4 状态模式；截屏多模态视觉切换；技能工坊重构；Live2D 表情通道独立 | | 🎨 2026-02-12 | — | NagaCAS 认证；Live2D 4 通道正交动画架构；Agentic Tool Loop；明日方舟风格启动界面 | | 📦 2026-02-11 | — | 嵌入式 OpenClaw 打包；启动自动从模板生成配置文件 | | 🛠️ 2026-02-10 | — | 后端打包优化；技能工坊 MCP 状态修复；去除冗余 Agent/MCP 仅保留 OpenClaw | | 🌱 2026-02-09 | — | 前端重构；Live2D 禁用眼睛追踪；OpenClaw 更名为 AgentServer |

---

目录

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 | 对话 | /chat | AI 对话、流式工具调用、上下文压缩 | | 2 | 记忆云海 | /mind | 知识图谱 3D 可视化与 GRAG 记忆管理 | | 3 | 技能工坊 | /skill | MCP 工具管理与社区 Skill 安装 | | 4 | 娜迦网络 | /forum / /forum/quota | 社区论坛、积分好感度 | | 5 | 枢机集市 | /market | 背景、音乐、角色、记忆迁移、充值 | | 6 | 终端设置 | /config | 模型连接、记忆连接、音画配置（三合一） | | 7 | 音律坊 | /music | BGM 播放器与歌单管理 | | 8 | 悬浮球 | — | 进入轻量悬浮球窗口模式 |

---

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 时自动触发压缩，避免上下文溢出：

| 阶段 | 触发时机 | 行为 | |------|----------|------| | 启动压缩 | 会话加载时 | 历史超阈值则立即压缩前段消息 | | 运行时压缩 | 每轮对话后 | 超限则压缩并注入 <compress> 标签 | | 跨会话继承 | 新会话启动 | 读取上次摘要，滚动累积上下文 |

摘要结构（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 运行：

| Agent | 功能 | |-------|------| | weather_time | 天气查询 / 预报、系统时间、自动城市 / IP 检测 | | open_launcher | 扫描系统已安装应用，自然语言启动程序 | | game_guide | 游戏策略问答、伤害计算、配队推荐、自动截图注入 | | online_search | 基于 SearXNG 的网络搜索 | | crawl4ai | 基于 Crawl4AI 的网页内容提取 | | playwright_master | 基于 Playwright 的浏览器自动化 | | vision | 截图分析与视觉问答 | | mqtt_tool | MQTT 协议 IoT 设备控制 | | office_doc | docx / xlsx 内容提取 |

注册与发现： 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. 娜迦网络 · 论坛社区

社区论坛

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

| 视图 | 路由 | 功能 | |------|------|------| | ForumListView | /forum | 帖子列表、分类筛选 | | ForumPostView | /forum/post/:id | 帖子详情浏览（当前版本为只读，不提供前端评论与“想要认识”操作） | | ForumMessagesView | /forum/messages | 私信消息 | | ForumMyPostsView | /forum/my-posts | 我的发帖 | | ForumMyRepliesView | /forum/my-replies | 我的回复 | | ForumQuotaView | /forum/quota | 积分配额与探索入口 |

源码：frontend/src/forum/

积分好感度系统

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

| 维度 | 说明 | |------|------| | 积分 (Credits) | 签到 / 连签奖励积累，用于兑换模型额度 | | 好感度 (Affinity) | 每次签到增长，反映与娜迦的关系深度 | | 每日签到 | 用户菜单一键签到，连续签到触发额外奖励 |

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