01_项目搭建指南：从零开始的 Windows 开发环境配置

准备工作：打开管理员权限的终端

在 Windows 上，我们需要一个强大的命令行工具。

点击键盘上的 Win + X 键。
选择 终端（管理员） 或 PowerShell（管理员）。
确保你看到的是蓝底或黑底的窗口，且标题栏写着"管理员"。

第一阶段：安装核心工具（你的"生产力外挂"）

我们将安装两个 2026 年最流行的工具：uv （负责 Python 后端，比 pip 快 100 倍）和 pnpm（负责前端，节省磁盘空间的利器）。

1.1 安装 uv (Python 管理器)

uv 是由 Rust 编写的，它能自动帮你管理 Python 版本，再也不用担心环境配置报错了。在 PowerShell 中粘贴并回车：

powershell 复制代码

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

1.2 安装 pnpm (前端包管理器)

为了管理 Next.js 16 项目，我们需要高效的 pnpm。继续粘贴：

powershell 复制代码

iwr https://get.pnpm.io/install.ps1 -useb | iex

1.3 激活自动补全（可选但推荐）

这能让你的命令行变聪明。运行以下指令：

powershell 复制代码

if (!(Test-Path -Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force }
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

注意：安装完成后，建议重启终端以使设置生效。

第二阶段：初始化 KnoSphere 项目骨架

我们要构建的是一个 Monorepo（单体大库） 结构。这意味着你的前端代码、后端代码和公用组件都在这一个大文件夹里，但又保持整洁。

2.1 创建项目文件夹

在终端里输入：

powershell 复制代码

mkdir KnoSphere
cd KnoSphere

2.2 初始化前端管理环境

执行 pnpm init 来生成项目的"身份证"文件：

powershell 复制代码

pnpm init

2.3 搭建"两层楼"结构

根据 2026 年的最佳实践，我们将项目分为 apps（存放具体的应用）和 packages（存放共享的工具或配置）：

powershell 复制代码

mkdir apps, packages

2.4 配置工作空间 (pnpm-workspace.yaml)

这一步最关键，它告诉系统这是一个整体。在 KnoSphere 根目录下创建一个名为 pnpm-workspace.yaml 的文件，内容如下：

yaml 复制代码

packages:
  - 'apps/*'
  - 'packages/*'

提示：你可以用 VS Code 打开文件夹来创建这个文件，或者直接在 PowerShell 里运行 notepad pnpm-workspace.yaml 粘贴进去再保存。

第三阶段：后端引擎冷启动

现在，我们要利用 uv 在 apps 文件夹里初始化你的 Python 后端。

进入应用目录 ：
powershell 复制代码
```
cd apps
```
初始化基于 Python 3.14 的后端 ：
uv 会自动为你下载并配置 Python 3.14 运行时。
powershell 复制代码
```
uv init api --python 3.14
```
进入 api 目录并安装第一批"神装" ：
我们要安装 FastAPI（接口框架）和常用的 AI 开发库：
powershell 复制代码
```
cd api
uv add fastapi sqlmodel redis celery langchain-openai langgraph
```

检查点：你现在拥有了什么？

如果你按部就班地完成了，你的项目目录应该是这样的：

复制代码

KnoSphere/                      (根目录)
├── pnpm-workspace.yaml         (整体管家)
├── apps/
│   └── api/                    (后端引擎，Python 3.14 已就绪)
│       └── pyproject.toml      (后端依赖清单)
└── packages/                   (未来存放共享代码的地方)

避坑小贴士 ：在 Windows 上开发时，如果遇到文件路径过长的问题，uv 的 copy 模式能帮你规避很多奇怪的报错。你可以先记住这个命令：$env:UV_LINK_MODE="copy"。