nekodemy

环境搭建指南

本教程将帮助你从零开始配置 N.E.K.O. 项目的开发环境，支持 Windows 和 macOS 系统。

📋 目录

Windows 环境搭建
macOS 环境搭建
验证安装
常见问题

Windows 环境搭建

1. 安装 Git

访问 Git 官网
下载 Git for Windows
运行安装程序，使用默认设置即可
验证安装：

git --version

2. 克隆项目

使用 Git 克隆 N.E.K.O 项目到本地：

# 克隆项目
git clone https://github.com/Project-N-E-K-O/N.E.K.O.git

# 进入项目目录
cd N.E.K.O

3. 安装 uv（Python 包管理器）

uv 是一个极速的 Python 包管理器和项目管理工具，N.E.K.O 项目推荐使用它来管理依赖。重要： uv 可以自动安装和管理 Python 版本，因此无需先手动安装 Python。

在 PowerShell 中运行：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

验证安装

uv --version

4. 配置 Python 项目环境

在项目目录下，使用 uv 来管理项目依赖，它会自动检测并安装所需的 Python 版本（N.E.K.O 项目需要 Python 3.11 或 3.12）：

# 确保在项目目录下（如果不在，先执行 cd N.E.K.O）
# 同步依赖（会自动安装 Python 3.11/3.12、创建虚拟环境并安装所有依赖）
uv sync

如果系统没有安装所需的 Python 版本，uv 会自动下载并安装。

激活虚拟环境（如果需要手动激活）

# PowerShell
.\.venv\Scripts\Activate.ps1

# CMD
.venv\Scripts\activate.bat

注意：

uv sync 会根据项目的 pyproject.toml 和 uv.lock 文件自动安装所有依赖，无需手动创建虚拟环境
uv 会自动管理 Python 版本，无需手动安装 Python

5. 启动服务器

在项目根目录下，需要启动以下服务器（建议在不同的终端窗口中分别运行）：

启动 Memory Server（记忆服务器）

# 确保在项目根目录下
uv run python memory_server.py

启动 Main Server（主服务器）

# 在新的终端窗口中，确保在项目根目录下
uv run python main_server.py

启动 Agent Server（可选，非必须）

# 在新的终端窗口中，确保在项目根目录下
uv run python agent_server.py

提示：

如果已激活虚拟环境，可以直接使用 python 命令代替 uv run python
Memory Server 默认运行在端口 48912
Main Server 默认运行在端口 48911
Agent Server（如果启动）默认运行在端口 48915

访问 Web 界面

启动 Main Server 后，在浏览器中访问：

http://localhost:48911

首次访问需要配置 API Key，可以在 Web 界面中完成配置。

6. 安装代码编辑器

Visual Studio Code（推荐）

访问 VS Code 官网
下载并安装
安装推荐扩展：Python、Pylance、GitLens、ESLint（前端开发需要）、Prettier（代码格式化）

Cursor（AI 辅助编程）

Cursor 是基于 VS Code 的 AI 辅助编程编辑器，非常适合 AI 项目开发：

访问 Cursor 下载页面下载对应系统的安装包
运行安装程序完成安装
Cursor 内置了 AI 功能，无需额外配置即可使用

提示： Cursor 与 VS Code 使用相同的扩展系统，上述 VS Code 的推荐扩展同样适用于 Cursor。

7. 安装 Node.js（前端开发需要）

版本要求： 最低支持 Node.js 18.x，推荐使用 Node.js 20.x 或 22.x（最新 LTS 版本）

访问 Node.js 官网
下载最新的 LTS 版本（推荐 20.x 或 22.x）
运行安装程序
验证安装：

node --version
npm --version

注意： 确保 Node.js 版本 ≥ 18.0.0，否则项目可能无法正常运行。

macOS 环境搭建

1. 安装 Homebrew（包管理器）

打开终端（Terminal），运行：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. 安装 Git

# macOS 通常已预装 Git，但建议更新到最新版本
brew install git

# 验证安装
git --version

3. 克隆项目

使用 Git 克隆 N.E.K.O 项目到本地：

# 克隆项目
git clone https://github.com/Project-N-E-K-O/N.E.K.O.git

# 进入项目目录
cd N.E.K.O

4. 安装 uv（Python 包管理器）

# 使用官方安装脚本（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或者使用 Homebrew 安装
brew install uv

# 验证安装
uv --version

安装完成后，可能需要重启终端或运行 source $HOME/.cargo/env 来使 uv 命令生效。

5. 配置 Python 项目环境

在项目目录下，使用 uv 来管理项目依赖，它会自动检测并安装所需的 Python 版本（N.E.K.O 项目需要 Python 3.11 或 3.12）：

# 确保在项目目录下（如果不在，先执行 cd N.E.K.O）
# 同步依赖（会自动安装 Python 3.11/3.12、创建虚拟环境并安装所有依赖）
uv sync

如果系统没有安装所需的 Python 版本，uv 会自动下载并安装。

激活虚拟环境（如果需要手动激活）

source .venv/bin/activate

注意：

uv sync 会根据项目的 pyproject.toml 和 uv.lock 文件自动安装所有依赖，无需手动创建虚拟环境
uv 会自动管理 Python 版本，无需手动安装 Python

6. 启动服务器

在项目根目录下，需要启动以下服务器（建议在不同的终端窗口中分别运行）：

启动 Memory Server（记忆服务器）

# 确保在项目根目录下
uv run python memory_server.py

启动 Main Server（主服务器）

# 在新的终端窗口中，确保在项目根目录下
uv run python main_server.py

启动 Agent Server（可选，非必须）

# 在新的终端窗口中，确保在项目根目录下
uv run python agent_server.py

提示：

如果已激活虚拟环境，可以直接使用 python 命令代替 uv run python
Memory Server 默认运行在端口 48912
Main Server 默认运行在端口 48911
Agent Server（如果启动）默认运行在端口 48915

访问 Web 界面

启动 Main Server 后，在浏览器中访问：

http://localhost:48911

首次访问需要配置 API Key，可以在 Web 界面中完成配置。

7. 安装代码编辑器

Visual Studio Code（推荐）

# 使用 Homebrew 安装
brew install --cask visual-studio-code

或访问 VS Code 官网下载。

安装推荐扩展：Python、Pylance、GitLens、ESLint、Prettier

Cursor（AI 辅助编程）

Cursor 是基于 VS Code 的 AI 辅助编程编辑器，非常适合 AI 项目开发：

# 使用 Homebrew 安装
brew install --cask cursor

或访问 Cursor 下载页面下载 macOS 版本。

提示： Cursor 与 VS Code 使用相同的扩展系统，上述 VS Code 的推荐扩展同样适用于 Cursor。

8. 安装 Node.js（前端开发需要）

版本要求： 最低支持 Node.js 18.x，推荐使用 Node.js 20.x 或 22.x（最新 LTS 版本）

# 使用 Homebrew 安装最新 LTS 版本（推荐）
brew install node

# 或者安装特定版本（如需要）
brew install node@20

# 验证安装
node --version
npm --version

注意： 确保 Node.js 版本 ≥ 18.0.0，否则项目可能无法正常运行。

验证安装

完成环境搭建后，运行以下命令验证所有工具是否正确安装：

Windows

uv --version
uv python list
git --version
node --version
npm --version

macOS

uv --version
uv python list
git --version
node --version
npm --version

注意： 使用 uv python list 可以查看 uv 管理的 Python 版本，无需单独验证系统 Python。

所有命令都应该显示版本号。

常见问题

Q: 需要先安装 Python 吗？

不需要！ uv 可以自动安装和管理 Python 版本。当你运行 uv sync 时，如果系统没有所需的 Python 版本，uv 会自动下载并安装。

使用 uv 管理的 Python 版本通常更可靠，因为它们是独立管理的，不会与系统 Python 冲突。推荐让 uv 自动管理 Python 版本，无需手动安装。

Q: Python 命令找不到？

如果你使用 uv 管理的 Python，可以通过虚拟环境来使用：

# 激活虚拟环境后，python 命令即可用
.\.venv\Scripts\Activate.ps1  # Windows PowerShell
source .venv/bin/activate     # macOS/Linux

# 或者直接使用 uv 运行 Python
uv run python --version

Q: uv 命令找不到？

Windows:

确保已正确安装 uv，可以尝试重新运行安装脚本
检查环境变量 PATH 是否包含 uv 的安装路径

macOS/Linux:

运行 source $HOME/.cargo/env 或重启终端
如果使用 Homebrew 安装，确保 Homebrew 的 bin 目录在 PATH 中

Q: uv sync 失败？

uv 会自动安装所需的 Python 版本，无需手动安装
检查网络连接，uv 需要从 PyPI 下载包和 Python 安装包
如果网络较慢，可以配置国内镜像（见下方）
确保有足够的磁盘空间，Python 安装包和依赖包需要一定空间

Q: 虚拟环境激活失败？

Windows PowerShell:

可能需要设置执行策略：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

使用 uv 时，虚拟环境位于 .venv 目录，而不是 venv

macOS/Linux:

确保使用 source .venv/bin/activate（注意是 .venv 而不是 venv）

Q: npm 安装包很慢？

可以使用国内镜像：

npm config set registry https://registry.npmmirror.com

Q: pip 安装包很慢？

可以使用国内镜像：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

Q: uv 下载包很慢？

可以配置 uv 使用国内镜像：

Windows:

# 创建配置文件
mkdir -p $env:APPDATA\uv
echo '[[index]]' > $env:APPDATA\uv\uv.toml
echo 'url = "https://pypi.tuna.tsinghua.edu.cn/simple/"' >> $env:APPDATA\uv\uv.toml
echo 'default = true' >> $env:APPDATA\uv\uv.toml

macOS/Linux:

# 创建配置文件
mkdir -p ~/.config/uv
cat > ~/.config/uv/uv.toml << EOF
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
default = true
EOF

下一步

环境搭建完成后，继续学习：

Git 与 GitHub 完整指南 - 学习如何获取和管理代码

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