{"id":45609448,"url":"https://github.com/rtgs2017/nagaagent","last_synced_at":"2026-03-08T22:00:55.593Z","repository":{"id":288858562,"uuid":"969373000","full_name":"RTGS2017/NagaAgent","owner":"RTGS2017","description":"A simple yet powerful agent framework for personal assistants, designed to enable intelligent interaction, multi-agent collaboration, and seamless tool integration.","archived":false,"fork":false,"pushed_at":"2026-03-05T10:39:30.000Z","size":236607,"stargazers_count":1444,"open_issues_count":0,"forks_count":158,"subscribers_count":17,"default_branch":"main","last_synced_at":"2026-03-05T13:52:01.610Z","etag":null,"topics":["agentic-ai","agents","mcp","mcp-client","openai","openclaw","toolcall"],"latest_commit_sha":null,"homepage":"https://space.bilibili.com/266938091","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RTGS2017.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-20T02:02:50.000Z","updated_at":"2026-03-05T10:49:10.000Z","dependencies_parsed_at":"2025-05-18T03:23:50.664Z","dependency_job_id":"c8497359-62b4-4c3d-a74f-eaa308c869ba","html_url":"https://github.com/RTGS2017/NagaAgent","commit_stats":null,"previous_names":["xxiii8322766509/naga-llm-mcp","xxiii8322766509/nagaagent","rtgs2017/nagaagent"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/RTGS2017/NagaAgent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RTGS2017%2FNagaAgent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RTGS2017%2FNagaAgent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RTGS2017%2FNagaAgent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RTGS2017%2FNagaAgent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RTGS2017","download_url":"https://codeload.github.com/RTGS2017/NagaAgent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RTGS2017%2FNagaAgent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30274876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T20:45:49.896Z","status":"ssl_error","status_checked_at":"2026-03-08T20:45:49.525Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agents","mcp","mcp-client","openai","openclaw","toolcall"],"created_at":"2026-02-23T17:00:33.712Z","updated_at":"2026-03-08T22:00:55.582Z","avatar_url":"https://github.com/RTGS2017.png","language":"Python","funding_links":[],"categories":["Chatbots"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\r\n\r\n# NagaAgent\r\n\r\n**你的超级AI秘书**\r\n\r\n流式工具调用 · 知识图谱记忆 · Live2D 虚拟形象 · 语音交互 · 娜迦网络社区\r\n\r\n[简体中文](README3.md) | [English](README_en.md)\r\n\r\n![NagaAgent](https://img.shields.io/badge/NagaAgent-5.1.0-blue?style=for-the-badge\u0026logo=python\u0026logoColor=white)\r\n![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-green?style=for-the-badge)\r\n![License](https://img.shields.io/badge/License-AGPL%203.0%20%7C%20Proprietary-yellow?style=for-the-badge)\r\n![Python](https://img.shields.io/badge/Python-3.11-blue?style=for-the-badge\u0026logo=python)\r\n\r\n[![Stars](https://img.shields.io/github/stars/Xxiii8322766509/NagaAgent?style=social)](https://github.com/Xxiii8322766509/NagaAgent)\r\n[![Forks](https://img.shields.io/github/forks/Xxiii8322766509/NagaAgent?style=social)](https://github.com/Xxiii8322766509/NagaAgent)\r\n[![Issues](https://img.shields.io/github/issues/Xxiii8322766509/NagaAgent)](https://github.com/Xxiii8322766509/NagaAgent/issues)\r\n\r\n**[QQ 机器人联动：Undefined QQbot](https://github.com/69gg/Undefined/)**\r\n\r\n\u003c/div\u003e\r\n\r\n---\r\n\r\n**双许可证** · 开源采用 [AGPL-3.0](LICENSE)，闭源采用 [专属许可](LICENSE-CLOSED-SOURCE)（需书面授权）。\r\n商业合作：contact@nagaagent.com / bilibili【柏斯阔落】\r\n\r\n---\r\n\r\n## 更新日志\r\n\r\n| 日期 | 版本 | 内容 |\r\n|------|------|------|\r\n| 🎆 2026-02-26 | 5.1.0 | 娜迦网络社区论坛上线；设置三合一重构；旅行模式；积分配额页；枢机集市与主面板更新 |\r\n| ⚡ 2026-02-25 | 5.1.0 | TTS 全链路修复（CORS / asyncio）；build.py 跨平台构建；上下文压缩持久化；角色系统更新；提示词注入架构重构 |\r\n| 🎵 2026-02-24 | — | Neo4j 连接超时修复；统一 BGM 播放器；音律坊歌单编辑；MCP 管理 UI；悬浮球透明窗口 + 悬停亮度 |\r\n| 🏗️ 2026-02-23 | — | 跨平台构建完善；版本号统一 pyproject.toml 管理；提示词/截图/视觉优化；角色文件打包迁移 |\r\n| 💕 2026-02-22 | — | 积分好感度系统（签到 / 好感度 / 积分）；悬浮球阴影与拖拽修复；登录自动恢复；OpenClaw hooks 修复 |\r\n| 🎶 2026-02-21 | — | 音律坊图标更新；MCP Agents 更新；悬浮球小按钮 |\r\n| 🗜️ 2026-02-20 | — | 上下文压缩三级重构（`\u003ccompress\u003e` 标签 / 跨会话继承）；MCP 管理 UI；悬浮球透明窗口；音律坊功能修正 |\r\n| 🔄 2026-02-19 | — | SSE 去除 base64 直接 JSON 传输；移除冗余后台意图分析器；config_manager 自动检测编码 |\r\n| 🔧 2026-02-17 | — | 悬浮球序列帧路径改为相对路径，修复打包后头像不显示 |\r\n| 🚀 2026-02-16 | 5.0.0 | NagaModel 网关统一接入；DeepSeek 推理链实时展示；记忆云海 UI 自适应修复 |\r\n| 🧠 2026-02-15 | — | 统一附加知识块 + 消除历史污染；LLM 流式重试；七天自动登录；开机自启动 |\r\n| 🌊 2026-02-14 | — | NagaMemory 云端远程记忆；意识海 3D 重写；启动粒子动画；版本更新检查弹窗；用户使用协议 |\r\n| ✨ 2026-02-13 | — | 悬浮球 4 状态模式；截屏多模态视觉切换；技能工坊重构；Live2D 表情通道独立 |\r\n| 🎨 2026-02-12 | — | NagaCAS 认证；Live2D 4 通道正交动画架构；Agentic Tool Loop；明日方舟风格启动界面 |\r\n| 📦 2026-02-11 | — | 嵌入式 OpenClaw 打包；启动自动从模板生成配置文件 |\r\n| 🛠️ 2026-02-10 | — | 后端打包优化；技能工坊 MCP 状态修复；去除冗余 Agent/MCP 仅保留 OpenClaw |\r\n| 🌱 2026-02-09 | — | 前端重构；Live2D 禁用眼睛追踪；OpenClaw 更名为 AgentServer |\r\n\r\n---\r\n\r\n## 目录\r\n\r\n1. [快速开始](#快速开始)\r\n2. [功能导览（主面板）](#功能导览主面板)\r\n3. [对话](#1-对话--messagerview)\r\n4. [记忆云海](#2-记忆云海--mindview)\r\n5. [技能工坊](#3-技能工坊--skillview)\r\n6. [娜迦网络](#4-娜迦网络--论坛社区)\r\n7. [枢机集市](#5-枢机集市--marketview)\r\n8. [终端设置](#6-终端设置--configview)\r\n9. [音律坊](#7-音律坊--musicview)\r\n10. [悬浮球](#8-悬浮球--floatingview)\r\n11. [全局功能](#全局功能)\r\n12. [后端架构](#后端架构)\r\n13. [可选配置](#可选配置)\r\n14. [端口一览](#端口一览)\r\n15. [故障排除](#故障排除)\r\n\r\n---\r\n\r\n## 快速开始\r\n\r\n### 环境要求\r\n\r\n- Python 3.11（`\u003e=3.11, \u003c3.12`）\r\n- 可选：[uv](https://github.com/astral-sh/uv) — 加速依赖安装\r\n- 可选：Neo4j — 本地知识图谱记忆\r\n\r\n### 安装\r\n\r\n```bash\r\ngit clone https://github.com/Xxiii8322766509/NagaAgent.git\r\ncd NagaAgent\r\n\r\n\r\n#前端安装\r\ncd frontend\r\nnpm install\r\ncd..\r\n\r\n\r\n#后端安装\r\n# 方式一：setup 脚本（自动检测环境、创建虚拟环境、安装依赖）\r\npython setup.py\r\n\r\n# 方式二：uv\r\nuv sync\r\n\r\n# 方式三：手动\r\npython -m venv .venv\r\nsource .venv/bin/activate   # Windows: .\\.venv\\Scripts\\activate\r\npip install -r requirements.txt\r\n```\r\n\r\n### 最小配置\r\n\r\n复制 `config.json.example` 为 `config.json`，填入 LLM API 信息：\r\n\r\n```json\r\n{\r\n  \"api\": {\r\n    \"api_key\": \"your-api-key\",\r\n    \"base_url\": \"https://api.deepseek.com\",\r\n    \"model\": \"deepseek-v3.2\"\r\n  }\r\n}\r\n```\r\n\r\n支持所有 OpenAI 兼容 API（DeepSeek、通义千问、OpenAI、Ollama 等）。\r\n\r\n### 启动\r\n\r\n```bash\r\ncd frontend \u0026\u0026 npm run dev （配置了一键启动）\r\n```\r\n\r\n---\r\n\r\n## 功能导览（主面板）\r\n\r\n启动后进入**主面板（PanelView）**，采用 3D 视差效果（鼠标移动触发透视旋转）。\r\n所有功能从主面板的八个入口按钮展开：\r\n\r\n| # | 入口 | 路由 | 功能概要 |\r\n|---|------|------|----------|\r\n| 1 | **对话** | `/chat` | AI 对话、流式工具调用、上下文压缩 |\r\n| 2 | **记忆云海** | `/mind` | 知识图谱 3D 可视化与 GRAG 记忆管理 |\r\n| 3 | **技能工坊** | `/skill` | MCP 工具管理与社区 Skill 安装 |\r\n| 4 | **娜迦网络** | `/forum` / `/forum/quota` | 社区论坛、积分好感度 |\r\n| 5 | **枢机集市** | `/market` | 背景、音乐、角色、记忆迁移、充值 |\r\n| 6 | **终端设置** | `/config` | 模型连接、记忆连接、音画配置（三合一） |\r\n| 7 | **音律坊** | `/music` | BGM 播放器与歌单管理 |\r\n| 8 | **悬浮球** | — | 进入轻量悬浮球窗口模式 |\r\n\r\n---\r\n\r\n## 1. 对话 · MessageView\r\n\r\n### 流式工具调用\r\n\r\n对话引擎通过 SSE 流式输出，同时实时送达前端显示与 TTS 分句播放。\r\n工具调用不依赖 OpenAI Function Calling API，LLM 在文本中以 ` ```tool``` ` 代码块嵌入 JSON，**任何 OpenAI 兼容提供商均可使用**。\r\n\r\n**单轮工具调用流程：**\r\n\r\n```\r\nLLM 流式输出 ──SSE──▶ 前端实时显示\r\n       │\r\n       ▼\r\nparse_tool_calls_from_text()\r\n  ├─ Phase 1: 提取 ```tool``` 代码块\r\n  └─ Phase 2: 兜底提取裸 JSON\r\n       │\r\n       ▼\r\n  按 agentType 路由\r\n  ├─ \"mcp\"      → MCPManager.unified_call()\r\n  ├─ \"openclaw\" → Agent Server /openclaw/send\r\n  └─ \"live2d\"   → UI 动画通知\r\n       │\r\n       ▼\r\n  asyncio.gather() 并行执行所有工具\r\n       │\r\n       ▼\r\n  结果注入 messages，进入下一轮 LLM 调用（最多 5 轮）\r\n```\r\n\r\n- 文本解析：`json5` 容错解析，全角字符自动标准化\r\n- SSE 格式：`data: {\"type\":\"content\"|\"reasoning\",\"text\":\"...\"}\\n\\n`（直接 JSON，不含 base64）\r\n- 循环上限：`max_loop_stream = 5`（可配置）\r\n\r\n源码：[`apiserver/agentic_tool_loop.py`](apiserver/agentic_tool_loop.py)\r\n\r\n### 上下文压缩\r\n\r\n会话 token 超过 100k 时自动触发压缩，避免上下文溢出：\r\n\r\n| 阶段 | 触发时机 | 行为 |\r\n|------|----------|------|\r\n| **启动压缩** | 会话加载时 | 历史超阈值则立即压缩前段消息 |\r\n| **运行时压缩** | 每轮对话后 | 超限则压缩并注入 `\u003ccompress\u003e` 标签 |\r\n| **跨会话继承** | 新会话启动 | 读取上次摘要，滚动累积上下文 |\r\n\r\n摘要结构（6 分区）：关键事实 / 用户偏好 / 重要决定 / 待办事项 / 背景信息 / 最近状态。\r\n`\u003ccompress\u003e` 标签持久化到会话文件，不计入 LLM token 统计。\r\n\r\n### DeepSeek 推理链展示\r\n\r\n使用 DeepSeek 时，`reasoning` 字段通过 SSE 实时推送，前端以独立样式展示思考过程。\r\n\r\n---\r\n\r\n## 2. 记忆云海 · MindView\r\n\r\n### GRAG 知识图谱记忆\r\n\r\nGRAG（Graph-RAG）从对话中自动提取五元组并存入 Neo4j，对话时自动检索作为 LLM 上下文。\r\n\r\n**五元组结构：**`(主体, 主体类型, 谓词, 客体, 客体类型)`\r\n\r\n**提取流程：**\r\n\r\n1. 结构化提取（优先）：`beta.chat.completions.parse()` + Pydantic `QuintupleResponse`，`temperature=0.3`，重试 3 次\r\n2. JSON 兜底：解析失败时提取首个 `[` 到末尾 `]` 的内容\r\n3. 过滤规则：只保留事实（行为、关系、状态、偏好），过滤隐喻、假设、纯情感\r\n\r\n**实体类型：** `person` / `location` / `organization` / `item` / `concept` / `time` / `event` / `activity`\r\n\r\n**任务管理器：**\r\n- 3 个 asyncio worker 消费 `asyncio.Queue(maxsize=100)`\r\n- SHA-256 去重：相同文本的重复任务自动跳过\r\n- 每小时清理超过 24h 的已完成任务\r\n\r\n**双重存储：**\r\n- 本地：`logs/knowledge_graph/quintuples.json`\r\n- 云端：Neo4j 图数据库，`graph.merge()` upsert\r\n\r\n**RAG 检索：** 关键词提取 → Cypher 查询 → 格式化为 `主体(类型) —[谓词]→ 客体(类型)` 注入上下文\r\n\r\n**远程记忆：** 登录用户自动使用 NagaMemory 云端，退出或离线时回退本地 GRAG。\r\n\r\n源码：[`summer_memory/`](summer_memory/)\r\n\r\n### 意识海 3D 可视化\r\n\r\nCanvas 2D + 手写 3D 投影（非 WebGL），球面坐标相机，透视除法 `700 / depth`。\r\n\r\n**7 层渲染顺序：**\r\n背景渐变 → 地面网格 → 水面平面 → 体积光（3 束光柱）→ 粒子系统（3 层 125 颗）→ 生物荧光浮游生物（10 个带拖尾）→ 知识图谱节点与边（深度排序）\r\n\r\n**图谱映射：** `subject/object` → 节点，`predicate` → 有向边，度中心性 → 节点高度权重，上限 100 节点\r\n\r\n**交互：** 拖拽旋转、中键平移、滚轮缩放、节点点选/拖拽、关键词搜索过滤\r\n\r\n---\r\n\r\n## 3. 技能工坊 · SkillView\r\n\r\n### 内置 MCP Agent\r\n\r\n基于 [Model Context Protocol](https://modelcontextprotocol.io/) 的可插拔工具架构，每个工具以独立 Agent 运行：\r\n\r\n| Agent | 功能 |\r\n|-------|------|\r\n| `weather_time` | 天气查询 / 预报、系统时间、自动城市 / IP 检测 |\r\n| `open_launcher` | 扫描系统已安装应用，自然语言启动程序 |\r\n| `game_guide` | 游戏策略问答、伤害计算、配队推荐、自动截图注入 |\r\n| `online_search` | 基于 SearXNG 的网络搜索 |\r\n| `crawl4ai` | 基于 Crawl4AI 的网页内容提取 |\r\n| `playwright_master` | 基于 Playwright 的浏览器自动化 |\r\n| `vision` | 截图分析与视觉问答 |\r\n| `mqtt_tool` | MQTT 协议 IoT 设备控制 |\r\n| `office_doc` | docx / xlsx 内容提取 |\r\n\r\n**注册与发现：** `mcp_registry.py` glob 扫描 `**/agent-manifest.json`，`importlib.import_module` 动态实例化。\r\n\r\n### MCP 管理 UI\r\n\r\n前端 `McpAddDialog.vue` 提供图形化 MCP 工具管理界面，支持在线添加 / 删除工具（无需重启）。\r\n\r\n### 社区 Skill 安装\r\n\r\n技能工坊支持一键安装社区发布的 Skill（Agent Browser、Brainstorming、Context7、Firecrawl Search 等）。\r\n后端接口：`GET /openclaw/market/items`、`POST /openclaw/market/items/{id}/install`\r\n\r\n源码：[`mcpserver/`](mcpserver/)\r\n\r\n---\r\n\r\n## 4. 娜迦网络 · 论坛社区\r\n\r\n### 社区论坛\r\n\r\n从主面板\"娜迦网络\"区块进入，内嵌完整社区功能：\r\n\r\n| 视图 | 路由 | 功能 |\r\n|------|------|------|\r\n| `ForumListView` | `/forum` | 帖子列表、分类筛选 |\r\n| `ForumPostView` | `/forum/post/:id` | 帖子详情浏览（当前版本为只读，不提供前端评论与“想要认识”操作） |\r\n| `ForumMessagesView` | `/forum/messages` | 私信消息 |\r\n| `ForumMyPostsView` | `/forum/my-posts` | 我的发帖 |\r\n| `ForumMyRepliesView` | `/forum/my-replies` | 我的回复 |\r\n| `ForumQuotaView` | `/forum/quota` | 积分配额与探索入口 |\r\n\r\n源码：[`frontend/src/forum/`](frontend/src/forum/)\r\n\r\n### 积分好感度系统\r\n\r\n登录用户专属的游戏化互动体系：\r\n\r\n| 维度 | 说明 |\r\n|------|------|\r\n| **积分 (Credits)** | 签到 / 连签奖励积累，用于兑换模型额度 |\r\n| **好感度 (Affinity)** | 每次签到增长，反映与娜迦的关系深度 |\r\n| **每日签到** | 用户菜单一键签到，连续签到触发额外奖励 |\r\n\r\n相关 API（通过 API Server 代理至 Naga 门户）：`/api/checkin`、`/api/affinity`、`/api/credits`\r\n\r\n---\r\n\r\n## 5. 枢机集市 · MarketView\r\n\r\n枢机集市整合了所有资源获取与管理入口，分为七个 Tab：\r\n\r\n| Tab | 说明 |\r\n|-----|------|\r\n| **界面背景** | 切换应用主题背景 |\r\n| **音之巷** | 购买 / 解锁音乐专辑（当前：沙之书） |\r\n| **角色注册** | 绑定 / 切换 AI 角色（需登录） |\r\n| **记忆云迁** | 云端记忆数据迁移与管理 |\r\n| **MCP 工具** | MCP 工具图形化管理 |\r\n| **智能体技能** | 社区 Skill 一键安装 |\r\n| **模型充值** | Naga 门户积分充值 |\r\n\r\n---\r\n\r\n## 6. 终端设置 · ConfigView\r\n\r\n设置页三合一重构，原分散配置集中在单一页面的三个 Tab：\r\n\r\n| Tab | 内容 |\r\n|-----|------|\r\n| **模型连接** | LLM API Key、Base URL、模型选择 |\r\n| **记忆连接** | Neo4j 连接参数、NagaMemory 云端配置 |\r\n| **音画配置** | 角色档案、Live2D 模型与 SSAA、TTS 声音、聊天字号 |\r\n\r\n### 角色卡系统\r\n\r\n`characters/` 目录管理可切换的 AI 角色，每个角色以 JSON 配置文件描述：\r\n\r\n```json\r\n{\r\n  \"ai_name\": \"娜杰日达\",\r\n  \"user_name\": \"用户\",\r\n  \"live2d_model\": \"NagaTest2/NagaTest2.model3.json\",\r\n  \"prompt_file\": \"conversation_style_prompt.txt\",\r\n  \"portrait\": \"Naga.png\",\r\n  \"bio\": \"由开发者柏斯阔落亲手创造的AI助手，简称娜迦。\"\r\n}\r\n```\r\n\r\n- 每个角色目录包含独立的对话风格提示词、Live2D 模型资源、立绘图像\r\n- 激活角色后，AI 名称与 Live2D 模型由角色 JSON 统一管理，不可在界面手动覆盖\r\n- 默认角色：**娜杰日达**\r\n\r\n源码：[`characters/`](characters/)\r\n\r\n---\r\n\r\n## 7. 音律坊 · MusicView\r\n\r\n独立音乐播放器，与主界面 BGM **共享同一播放实例**（统一 BGM 架构）：\r\n\r\n- **歌单编辑**（`MusicEditView`）：管理曲目列表，保存后实时同步至全局播放器\r\n- **播放状态同步**：播放 / 暂停图标与音频事件实时联动\r\n- **列表循环**：当前曲目结束后自动播放下一首\r\n- **Live2D 口型同步**：TTS 播放期间，`AdvancedLipSyncEngineV2` 以 60FPS 驱动 Live2D 嘴形\r\n\r\n---\r\n\r\n## 8. 悬浮球 · FloatingView\r\n\r\n点击主面板\"悬浮\"按钮进入轻量悬浮球窗口模式，四种状态循环切换：\r\n\r\n```\r\nball（100×100 圆球）→ compact（420×100 折叠条）→ full（420×N 展开）→ classic（正常窗口）\r\n```\r\n\r\n**外观与动效：**\r\n- 序列帧眨眼动画：5 帧（睁眼 → 半闭 → 闭眼 → 半闭 → 睁眼），70ms / 帧，随机间隔触发\r\n- 生成回复时：球体光晕脉冲特效\r\n- 悬停时：亮度提升效果\r\n- 透明无边框窗口，支持自由拖拽定位\r\n\r\n**功能：**\r\n- 悬浮状态下可直接输入对话，历史消息在 compact / full 状态下可回溯\r\n- 截图捕获面板：选取屏幕窗口作为图像附件\r\n- 文件上传支持\r\n- 右键菜单通过 Electron 原生菜单实现（避免小窗口裁剪）\r\n\r\n---\r\n\r\n## 全局功能\r\n\r\n### 语音交互\r\n\r\n**TTS（语音合成）**\r\n\r\n- 引擎：Edge-TTS，OpenAI 兼容接口 `/v1/audio/speech`\r\n- 架构：3 线程流水线 — 分句队列 → TTS 调用（Semaphore(2) 并发）→ pygame 播放\r\n- Live2D 口型同步：60FPS 提取 5 参数（mouth_open / mouth_form / mouth_smile / eye_brow_up / eye_wide）\r\n- 端口清理：启动时自动检测并释放占用端口\r\n\r\n**ASR（语音识别）**\r\n\r\n- 本地引擎：FunASR，支持 VAD 端点检测与 WebSocket 实时流\r\n- 三模式自动切换：`LOCAL`（FunASR）→ `END_TO_END`（Qwen Omni）→ `HYBRID`\r\n\r\n**实时语音对话**（需 DashScope API Key）\r\n\r\n- 基于 Qwen Omni 的全双工 WebSocket 语音交互\r\n- 回声抑制、VAD 检测、音频分块（200ms）、会话冷却控制\r\n\r\n```json\r\n{\r\n  \"voice_realtime\": {\r\n    \"enabled\": true,\r\n    \"provider\": \"qwen\",\r\n    \"api_key\": \"your-dashscope-key\",\r\n    \"model\": \"qwen3-omni-flash-realtime\"\r\n  }\r\n}\r\n```\r\n\r\n源码：[`voice/`](voice/)\r\n\r\n---\r\n\r\n### Live2D 虚拟形象\r\n\r\n使用 **pixi-live2d-display** + **PixiJS WebGL** 渲染 Cubism Live2D 模型。\r\nSSAA 超采样抗锯齿：Canvas 按 `width × ssaa` 渲染，CSS `transform: scale(1/ssaa)` 缩放。\r\n\r\n**4 通道正交动画系统**（`live2dController.ts`）：\r\n\r\n| 通道 | 控制内容 | 特性 |\r\n|------|----------|------|\r\n| **体态 (State)** | idle / thinking / talking 循环 | hermite 平滑插值，从 `naga-actions.json` 加载 |\r\n| **动作 (Action)** | 点头 / 摇头等头部动作 | FIFO 队列，单一执行 |\r\n| **表情 (Emotion)** | `.exp3.json` 表情文件 | Add / Multiply / Overwrite 三种混合模式，指数衰减过渡 |\r\n| **追踪 (Tracking)** | 鼠标视线跟随 | 可配延迟启动，`tracking_hold_delay_ms` |\r\n\r\n合并顺序：体态 → 嘴形 → 动作 → 手动覆盖 → 表情混合 → 追踪混合\r\n\r\n---\r\n\r\n### OpenClaw 电脑控制\r\n\r\n对接 OpenClaw Gateway（端口 18789），通过自然语言调度 AI 编程助手执行本地任务。\r\n\r\n- **三级回退启动：** 打包内嵌 → 全局 `openclaw` 命令 → 自动 `npm install -g openclaw`\r\n- 支持 sessionKey hooks（2026.2.17+），可配置自定义 hooks 路径\r\n- `POST /openclaw/send` 发送指令，最长等待 120 秒\r\n\r\n**任务调度器（`TaskScheduler`）：**\r\n- 任务步骤记录（目的 / 内容 / 输出 / 分析 / 成功与否）\r\n- 自动提取\"关键发现\"标记\r\n- 内存压缩：步骤数超阈值时调用 LLM 生成 `CompressedMemory`（key_findings / failed_attempts / current_status / next_steps）\r\n- `schedule_parallel_execution()` 通过 `asyncio.gather()` 并行执行任务列表\r\n\r\n源码：[`agentserver/`](agentserver/)\r\n\r\n---\r\n\r\n### 启动动画\r\n\r\n| 阶段 | 内容 |\r\n|------|------|\r\n| **标题阶段** | 黑色遮罩 + 40 颗金色上升粒子 + 标题图片 2.4s CSS keyframe；标题出现时自动播放唤醒语音 |\r\n| **进度阶段** | Neural Network 粒子背景 + Live2D 透出框 + 金色进度条（`requestAnimationFrame` 插值，最低速度 0.5 兜底） |\r\n| **停滞检测** | 3 秒无进度变化显示重启提示；进度 25% 后每秒轮询后端 `/health` |\r\n| **唤醒** | 进度 100% 后显示\"点击唤醒\"脉冲提示 |\r\n\r\n---\r\n\r\n## 后端架构\r\n\r\nNagaAgent 由四个独立微服务组成，`main.py` 统一编排启动：\r\n\r\n```\r\n┌─────────────────────────────────────────────────────────┐\r\n│                   Electron / PyQt5 前端                   │\r\n│  Vue 3 + Vite + UnoCSS + PrimeVue + pixi-live2d-display │\r\n│                                                         │\r\n│  PanelView · MessageView · MindView · SkillView         │\r\n│  MarketView · ConfigView · MusicView · FloatingView     │\r\n│  ForumListView · ForumPostView · ForumQuotaView …       │\r\n└──────────┬─────────────┬──────────────┬─────────────────┘\r\n           │             │              │\r\n   ┌───────▼──────┐ ┌────▼────┐  ┌─────▼──────┐\r\n   │  API Server  │ │  Agent  │  │   Voice    │\r\n   │   :8000      │ │  Server │  │  Service   │\r\n   │              │ │  :8001  │  │   :5048    │\r\n   │ 对话 / SSE   │ │         │  │            │\r\n   │ 工具调用     │ │ 任务调度│  │ TTS / ASR  │\r\n   │ 上下文压缩   │ │ OpenClaw│  │ 实时语音   │\r\n   │ 文档上传     │ │         │  │            │\r\n   │ 认证代理     │ └────┬────┘  └────────────┘\r\n   │ 记忆 API     │      │\r\n   │ Skill 市场   │  ┌───▼──────────┐\r\n   │ 配置管理     │  │  OpenClaw    │\r\n   └──────┬───────┘  │  Gateway    │\r\n          │          │  :18789     │\r\n   ┌──────▼──────┐   └─────────────┘\r\n   │ MCP Server  │\r\n   │   :8003     │\r\n   │ 工具注册    │\r\n   │ Agent 发现  │\r\n   │ 并行调度    │\r\n   └──────┬──────┘\r\n          │\r\n  ┌───────┴───────────────────────┐\r\n  │      MCP Agents（可插拔）      │\r\n  │ 天气 | 搜索 | 抓取 | 视觉     │\r\n  │ 启动器 | 攻略 | 文档 | MQTT   │\r\n  └───────────────────────────────┘\r\n          │\r\n   ┌──────▼──────┐\r\n   │    Neo4j    │\r\n   │   :7687     │\r\n   │  知识图谱   │\r\n   └─────────────┘\r\n```\r\n\r\n### 目录结构\r\n\r\n```\r\nNagaAgent/\r\n├── main.py                   # 统一入口，编排所有服务\r\n├── build.py                  # 跨平台构建脚本\r\n├── config.json               # 运行时配置（从 config.json.example 复制）\r\n├── pyproject.toml            # 版本 5.1.0，项目元数据与依赖\r\n│\r\n├── apiserver/                # API Server（:8000）\r\n│   ├── api_server.py         #   FastAPI 主应用\r\n│   ├── agentic_tool_loop.py  #   多轮工具调用循环\r\n│   ├── llm_service.py        #   LiteLLM 统一 LLM 调用\r\n│   └── streaming_tool_extractor.py  # 流式分句 + TTS 分发\r\n│\r\n├── agentserver/              # Agent Server（:8001）\r\n│   ├── agent_server.py\r\n│   └── task_scheduler.py     #   任务编排 + 压缩记忆\r\n│\r\n├── mcpserver/                # MCP Server（:8003）\r\n│   ├── mcp_server.py\r\n│   ├── mcp_registry.py       #   manifest 扫描 + 动态注册\r\n│   ├── mcp_manager.py        #   unified_call() 路由\r\n│   ├── agent_weather_time/\r\n│   ├── agent_open_launcher/\r\n│   ├── agent_game_guide/\r\n│   ├── agent_online_search/\r\n│   ├── agent_crawl4ai/\r\n│   ├── agent_playwright_master/\r\n│   ├── agent_vision/\r\n│   ├── agent_mqtt_tool/\r\n│   └── agent_office_doc/\r\n│\r\n├── summer_memory/            # GRAG 知识图谱记忆\r\n│   ├── quintuple_extractor.py\r\n│   ├── quintuple_graph.py\r\n│   ├── quintuple_rag_query.py\r\n│   ├── task_manager.py\r\n│   ├── memory_manager.py\r\n│   └── memory_client.py      #   NagaMemory 远程客户端\r\n│\r\n├── voice/                    # 语音服务（:5048）\r\n│   ├── output/               #   TTS + 口型同步\r\n│   └── input/                #   ASR + 实时语音\r\n│\r\n├── characters/               # 角色配置目录\r\n│   └── 娜杰日达/             #   prompt / Live2D 模型 / 立绘\r\n│\r\n├── frontend/                 # Electron + Vue 3 前端\r\n│   ├── electron/             #   主进程\r\n│   │   └── modules/          #   backend / hotkeys / menu / tray / updater / window\r\n│   └── src/\r\n│       ├── views/            #   所有页面视图\r\n│       ├── forum/            #   论坛模块\r\n│       ├── components/       #   通用组件\r\n│       ├── composables/      #   useAuth / useBackground / useAudio …\r\n│       └── utils/            #   live2dController / session / config\r\n│\r\n├── system/                   # 配置加载、环境检测、系统提示词\r\n├── guide_engine/             # 游戏攻略引擎\r\n└── logs/                     # 运行日志、知识图谱文件\r\n```\r\n\r\n---\r\n\r\n## 可选配置\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e\u003cb\u003e知识图谱记忆（Neo4j）\u003c/b\u003e\u003c/summary\u003e\r\n\r\n安装 Neo4j（[Docker](https://hub.docker.com/_/neo4j) 或 [Neo4j Desktop](https://neo4j.com/download/)），配置 `config.json`：\r\n\r\n```json\r\n{\r\n  \"grag\": {\r\n    \"enabled\": true,\r\n    \"neo4j_uri\": \"neo4j://127.0.0.1:7687\",\r\n    \"neo4j_user\": \"neo4j\",\r\n    \"neo4j_password\": \"your-password\"\r\n  }\r\n}\r\n```\r\n\r\n不配置 Neo4j 时，GRAG 仅使用本地 JSON 文件存储，功能不受影响。\r\n\u003c/details\u003e\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e\u003cb\u003e语音交互（TTS / ASR）\u003c/b\u003e\u003c/summary\u003e\r\n\r\n```json\r\n{\r\n  \"system\": { \"voice_enabled\": true },\r\n  \"tts\": {\r\n    \"port\": 5048,\r\n    \"default_voice\": \"zh-CN-XiaoxiaoNeural\"\r\n  }\r\n}\r\n```\r\n\r\n实时全双工语音对话（需通义千问 DashScope API Key）：\r\n\r\n```json\r\n{\r\n  \"voice_realtime\": {\r\n    \"enabled\": true,\r\n    \"provider\": \"qwen\",\r\n    \"api_key\": \"your-dashscope-key\",\r\n    \"model\": \"qwen3-omni-flash-realtime\"\r\n  }\r\n}\r\n```\r\n\u003c/details\u003e\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e\u003cb\u003eLive2D 虚拟形象（自定义模型）\u003c/b\u003e\u003c/summary\u003e\r\n\r\n```json\r\n{\r\n  \"web_live2d\": {\r\n    \"ssaa\": 2,\r\n    \"model\": {\r\n      \"source\": \"./models/your-model/model.model3.json\",\r\n      \"x\": 0.5,\r\n      \"y\": 1.3,\r\n      \"size\": 6800\r\n    },\r\n    \"face_y_ratio\": 0.13,\r\n    \"tracking_hold_delay_ms\": 100\r\n  }\r\n}\r\n```\r\n\r\n启用角色卡后，`ai_name` 与 `model.source` 由角色 JSON 自动覆盖，无需手动修改。\r\n\u003c/details\u003e\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e\u003cb\u003eMQTT 物联网控制\u003c/b\u003e\u003c/summary\u003e\r\n\r\n```json\r\n{\r\n  \"mqtt\": {\r\n    \"enabled\": true,\r\n    \"broker\": \"mqtt-broker-address\",\r\n    \"port\": 1883,\r\n    \"topic\": \"naga/agent/topic\",\r\n    \"client_id\": \"naga-agent-client\"\r\n  }\r\n}\r\n```\r\n\u003c/details\u003e\r\n\r\n---\r\n\r\n## 端口一览\r\n\r\n| 服务 | 端口 | 说明 |\r\n|------|------|------|\r\n| API Server | 8000 | 主接口：对话、配置、认证、Skill 市场 |\r\n| Agent Server | 8001 | 任务调度、OpenClaw |\r\n| MCP Server | 8003 | MCP 工具注册与调度 |\r\n| Voice Service | 5048 | TTS / ASR |\r\n| Neo4j | 7687 | 知识图谱（可选） |\r\n| OpenClaw Gateway | 18789 | AI 电脑控制（可选） |\r\n\r\n---\r\n\r\n## 故障排除\r\n\r\n| 问题 | 解决方案 |\r\n|------|----------|\r\n| Python 版本报错 | 必须使用 Python 3.11；推荐用 uv 自动管理版本 |\r\n| 端口被占用 | 检查 8000、8001、8003、5048 是否可用 |\r\n| Neo4j 连接超时 / 挂起 | 已在 2.24 修复；确认 Neo4j 服务已启动 |\r\n| TTS 无声音 / CORS 报错 | 已在 2.25 修复；确认 `voice_enabled: true` |\r\n| 启动卡在进度条 | 检查 API Key 是否正确；等待 3 秒后出现重启提示 |\r\n| 悬浮球头像不显示 | 已在 2.17 修复序列帧路径；确认使用最新打包版本 |\r\n| config.json 乱码 | 已在 2.19 修复：config_manager 自动检测文件编码 |\r\n| OpenClaw 启动失败 | 已在 2.24 修复全局模式缺少配置文件的问题 |\r\n\r\n```bash\r\npython main.py --check-env --force-check  # 完整环境诊断\r\npython main.py --quick-check              # 快速检查\r\npython update.py                          # 自动 git pull + 依赖同步\r\n```\r\n\r\n---\r\n\r\n## 贡献\r\n\r\n欢迎提交 Issue 和 Pull Request。如有问题，可加入 QQ 频道 **nagaagent1**。\r\n\r\n---\r\n\r\n## Star History\r\n\r\n[![Star History Chart](https://api.star-history.com/svg?repos=RTGS2017/NagaAgent\u0026type=date\u0026legend=top-left)](https://www.star-history.com/#RTGS2017/NagaAgent\u0026type=date\u0026legend=top-left)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frtgs2017%2Fnagaagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frtgs2017%2Fnagaagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frtgs2017%2Fnagaagent/lists"}