nekodemy

项目架构与目录结构

深入了解 Project N.E.K.O. 项目的整体架构、模块组织和代码结构，为后续开发打下坚实基础。

📋 目录

项目概览

Project N.E.K.O. 是一个 AI 伙伴项目，采用前后端分离架构：

💡 提示：关于环境搭建、项目克隆和依赖安装，请参考 环境搭建指南。关于 Git 和 GitHub 操作，请参考 Git 与 GitHub 完整指南。

目录结构详解

核心服务器文件

N.E.K.O/
├── launcher.py                  # 🚀 启动器（统一启动入口）
├── main_server.py               # 🌐 主服务器（FastAPI）
├── memory_server.py             # 🧠 记忆服务器
├── monitor.py                   # 📊 监控服务
├── pyproject.toml               # Python 项目配置
├── requirements.txt             # Python 依赖
├── requirements_monitor.txt     # 监控服务依赖
├── uv.lock                      # UV 锁文件
└── README.MD                    # 项目说明

后端核心模块

AI 智能体模块 (brain/)

brain/
├── analyzer.py                  # 对话分析器
├── planner.py                  # 任务规划器
├── processor.py                # 任务处理器
├── computer_use.py             # 计算机操作（键鼠控制）
├── mcp_client.py               # MCP 协议客户端
├── deduper.py                  # 去重处理
├── task_executor.py            # 任务执行器
├── s2_5/                       # S2.5 版本智能体
│   ├── agents/                 # 智能体实现
│   ├── core/                   # 核心引擎
│   ├── memory/                 # 程序记忆
│   └── utils/                  # 工具函数
└── s3/                         # S3 版本智能体
    ├── agents/                 # 智能体实现
    ├── bbon/                   # 行为叙述器
    ├── core/                   # 核心引擎
    ├── memory/                 # 程序记忆
    └── utils/                  # 工具函数

核心对话模块 (main_helper/)

main_helper/
├── core.py                     # 核心对话逻辑
├── cross_server.py             # 跨服务器通信
├── omni_realtime_client.py     # 实时 API 客户端
├── omni_offline_client.py      # 文本 API 客户端
└── tts_helper.py               # 🔊 TTS 引擎适配器

记忆管理模块 (memory/)

memory/
├── store/                      # 记忆数据存储
├── recent.py                   # 近期记忆
├── router.py                   # 记忆路由
├── semantic.py                 # 语义搜索
├── settings.py                 # 记忆设置
└── timeindex.py                # 时间索引

工具模块 (utils/)

utils/
├── api_config_loader.py        # API 配置加载器
├── audio.py                    # 音频处理
├── config_manager.py           # 配置管理器
├── frontend_utils.py           # 前端工具
├── logger_config.py            # 日志配置
├── preferences.py              # 偏好设置
├── web_scraper.py              # 网页爬虫
└── workshop_utils.py           # 工坊工具

前端模块

React 前端 (frontend/)

frontend/
├── packages/                   # 前端包
│   ├── common/                 # 公共模块
│   ├── components/             # React 组件库
│   ├── request/                # 请求客户端（含测试）
│   │   ├── __tests__/          # 单元测试
│   │   └── coverage/           # 测试覆盖率报告
│   └── web-bridge/             # 桥接层（暴露组件到 window）
├── src/                        # 源码
│   └── web/                    # Web 应用入口
├── scripts/                    # 构建脚本
├── vendor/                     # 第三方库
├── index.html                  # HTML 入口
├── package.json                # 前端依赖
├── tsconfig.json               # TypeScript 配置
└── vite.web.config.ts          # Vite 配置

静态资源 (static/)

static/
├── icons/                      # 图标资源
├── libs/                       # 第三方库
│   ├── live2d.min.js           # Live2D 库
│   ├── pixi.min.js             # PixiJS 库
│   └── i18next.min.js          # 国际化库
├── locales/                    # 国际化资源
├── mao_pro/                    # Live2D 模型
├── *.js                        # JavaScript 文件
└── *.png                       # 图片资源

HTML 模板 (templates/)

templates/
├── index.html                  # 主页面
├── api_key_settings.html       # API 密钥设置
├── chara_manager.html          # 角色管理
├── l2d_manager.html            # Live2D 管理
├── live2d_emotion_manager.html # 表情管理
├── live2d_parameter_editor.html # 参数编辑器
├── memory_browser.html          # 记忆浏览器
├── steam_workshop_manager.html  # Steam 工坊管理
├── subtitle.html               # 字幕页面
├── viewer.html                 # 查看器
└── voice_clone.html            # 语音克隆

配置和资源

配置管理 (config/)

config/
├── api_providers.json          # API 服务商配置
├── prompts_chara.py            # 角色提示词
└── prompts_sys.py              # 系统提示词

资源文件 (assets/)

assets/
├── demo.mp4                    # 演示视频
├── framework.drawio.svg        # 架构图
├── icon.ico                    # 图标
└── neko_logo.jpg               # 项目 Logo

文档 (docs/)

docs/
├── README_en.md                # 英文文档
└── README_ja.md                # 日文文档

集成和部署

Steam 集成 (steamworks/)

steamworks/
├── interfaces/                 # Steam API 接口
│   ├── apps.py                # 应用接口
│   ├── friends.py             # 好友接口
│   ├── workshop.py             # 创意工坊接口
│   └── ...                     # 其他接口
├── enums.py                    # 枚举定义
├── exceptions.py               # 异常定义
├── methods.py                  # 方法定义
└── structs.py                  # 结构体定义

Docker 部署 (docker/)

docker/
├── Dockerfile                  # Docker 镜像构建
├── docker-compose.yml          # Docker Compose 配置
├── entrypoint.sh               # 启动脚本
├── env.template                # 环境变量模板
├── config/                     # Docker 配置
│   └── core_config.json.example
└── README_Docker.md            # Docker 文档

打包配置 (specs/)

specs/
├── launcher.spec               # 启动器打包配置
└── monitor_build.spec          # 监控器打包配置

核心模块说明

1. 服务器模块

main_server.py - 主服务器

memory_server.py - 记忆服务器

launcher.py - 启动器

💡 提示：关于如何启动服务器，请参考 环境搭建指南 - 启动服务器。

monitor.py - 监控服务

2. Brain 模块（AI 智能体）

位于 brain/ 目录，负责 AI 的”思考”过程：

3. Main Helper 模块（核心对话）

位于 main_helper/ 目录，处理对话核心逻辑：

4. Memory 模块（记忆管理）

位于 memory/ 目录，管理 AI 的记忆：

5. Config 模块（配置管理）

位于 config/ 目录：

注意：核心配置（API Key 等）通过环境变量或 Docker 配置管理，不再使用 core_config.json 文件。

6. Frontend 模块（前端）

位于 frontend/ 目录，基于 TypeScript + React 的前端架构：

7. Utils 模块（工具函数）

位于 utils/ 目录，提供各种工具函数：

8. Steamworks 模块（Steam 集成）

位于 steamworks/ 目录，提供 Steam API 集成：

9. Docker 模块（容器化部署）

位于 docker/ 目录，提供容器化部署支持：

数据流向

基本对话流程

用户输入
  ↓
前端 (React/TypeScript 或 HTML/JS)
  ↓
main_server.py (FastAPI)
  ↓
main_helper/core.py
  ↓
API 客户端 (omni_realtime_client.py / omni_offline_client.py)
  ↓
LLM API (外部服务)
  ↓
返回响应
  ↓
memory_server.py (存储记忆)
  ↓
前端显示

智能体任务流程

用户请求复杂任务
  ↓
main_server.py (FastAPI)
  ↓
brain/task_executor.py
  ↓
brain/analyzer.py (分析意图)
  ↓
brain/planner.py (规划步骤)
  ↓
brain/processor.py (执行任务)
  ↓
brain/computer_use.py (如需要，控制计算机)
  ↓
brain/s2_5/ 或 brain/s3/ (智能体实现)
  ↓
返回结果

开发入口点

后端开发

  1. 主服务器：main_server.py
    • 添加新的 API 端点
    • 修改路由处理
  2. 对话逻辑：main_helper/core.py
    • 修改对话流程
    • 添加新的处理逻辑
  3. AI 智能体：brain/ 目录
    • 扩展 AI 能力
    • 添加新的工具

前端开发

  1. TypeScript + React 应用：frontend/
    • 添加新组件：frontend/packages/components/src/
    • 添加公共模块：frontend/packages/common/
    • 修改请求客户端：frontend/packages/request/
    • 修改桥接层：frontend/packages/web-bridge/
    • 修改 Web 应用：frontend/src/web/
    • 运行测试：cd frontend/packages/request && npm test
  2. 传统前端：static/ 和 templates/
    • 修改 HTML：templates/
    • 修改 JS：static/*.js
    • Live2D 相关：static/live2d-*.js

配置文件说明

config/api_providers.json

定义可用的 API 服务商：

{
  "core": {
    "stepfun": { ... },
    "qwen": { ... }
  }
}

config/prompts_chara.py

角色人设提示词，定义 AI 的性格和行为。

config/prompts_sys.py

系统提示词，定义 AI 的系统行为。

pyproject.toml

Python 项目配置文件，定义项目元数据和依赖：

💡 提示：关于如何使用 uv 管理依赖和 pyproject.toml，请参考 环境搭建指南 - 配置 Python 项目环境。

Docker 配置

Docker 相关配置位于 docker/ 目录：

打包配置

位于 specs/ 目录：

相关文档

在深入了解项目结构之前，建议先阅读：

下一步

了解项目结构后，可以开始开发：

遇到问题？ 在 GitHub Issues 提交你的问题，我们会及时解答！