FreeTodo 安装流程

想要快速上手 FreeTodo？请查看我们的 快速开始指南 🚀

系统要求

在安装 FreeTodo 之前，请确保你的系统满足以下要求：

操作系统

• Windows 10/11
• macOS 10.14+

软件依赖

后端:

• Python 3.12
• Git (用于克隆仓库)

前端:

• Node.js 20+
• pnpm 包管理器

硬件要求

• 内存：建议 4GB 以上
• 硬盘：至少 10GB 可用空间
• 处理器：支持多核处理器
• 可选：CUDA 支持（用于 GPU 加速）

安装步骤

1. 克隆项目仓库

首先，从 GitHub 克隆 FreeTodo 项目：

git clone https://github.com/FreeU-group/FreeTodo.git
cd FreeTodo

2. 安装依赖包

本项目使用 uv 进行快速可靠的依赖管理。

安装 uv:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

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

注意：安装完成后，uv 可能无法在当前终端中立即使用。要在当前会话中激活它：

• Windows (PowerShell)：运行 $env:Path = "$env:USERPROFILE\.local\bin;$env:Path" 来刷新 PATH
• macOS/Linux：运行 exec $SHELL 来重新初始化 shell 会话，或重新打开终端

或者，您也可以直接打开一个新的终端窗口，uv 将自动可用。

安装依赖并同步环境:

# 从 pyproject.toml 和 uv.lock 同步依赖
uv sync

# 激活虚拟环境
# macOS/Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

3. 启动后端服务

注意：首次运行时，如果 config.yaml 不存在，系统会自动从 default_config.yaml 创建。您可以通过编辑 lifetrace/config/config.yaml 来自定义设置。

启动服务器：

python -m lifetrace.server

自定义提示词：如果您想修改不同功能的 AI 提示词，可以编辑 lifetrace/config/prompt.yaml 文件。

后端服务会自动从 8001 端口（构建版为 8100）开始查找可用端口。如果默认端口被占用，会自动使用下一个可用端口，并在控制台显示实际使用的端口。

• 默认后端端口: http://localhost:8001
• API 文档: 实际 API 文档地址会在控制台显示（通常为 http://localhost:8001/docs）

4. 启动前端服务

前端是使用 FreeTodo 的必需组件。启动前端开发服务器：

cd free-todo-frontend

pnpm install
pnpm dev

前端开发服务器会：

• 自动从 3001 端口（开发版默认端口）开始查找可用端口
• 通过检查 /health 端点自动检测运行中的 FreeTodo 后端端口
• 自动设置 API 代理指向检测到的后端端口

实际的前端地址和后端连接状态会在控制台显示。服务启动后，在浏览器中访问控制台显示的前端地址（通常为 http://localhost:3001）开始使用 FreeTodo！🎉

注意：如果端口被占用，前端和后端都会自动查找下一个可用端口。控制台会显示实际使用的端口。

下一步

安装完成后，请查看 使用方法 了解如何使用 FreeTodo。