部署指南：从零开始运行 Agency OS

本指南旨在为完全没有编程经验的用户提供一个“傻瓜式”的本地部署教程，让您能够轻松地在自己的电脑上运行 Agency OS。

Agency OS 是一个基于现代 Web 技术（React, Vite）构建的应用程序，它在您的浏览器中运行，并将所有数据存储在本地。部署过程本质上就是将项目的源代码转换为浏览器可以运行的最终文件。

1. 环境准备：您需要什么？

在开始之前，您需要确保您的电脑上安装了两个核心工具：Git 和 Node.js。

工具	作用	推荐版本	检查方法
Git	用于下载项目源代码（克隆仓库）	最新稳定版	在命令行输入 git --version
Node.js	用于运行项目构建和开发服务器	20.19 或更高	在命令行输入 node -v

1.1. 安装 Git

Git 是一个版本控制工具，我们将用它来获取 Agency OS 的代码。

1. 访问 Git 官方网站：https://git-scm.com/
2. 根据您的操作系统（Windows/macOS/Linux）下载并安装。
3. 安装过程中，全部选择默认选项即可。
4. 安装完成后，打开您的命令行工具（Windows 用户搜索“PowerShell”或“命令提示符”，macOS 用户搜索“终端”），输入以下命令并按回车：

   git --version

   如果显示了版本号（例如 git version 2.43.0），则表示安装成功。

如果你不想安装git，这一步也可以直接从 github 代码仓库中直接下载 main 分支的代码压缩包。

1.2. 安装 Node.js

Node.js 是运行 JavaScript 代码的环境，它包含了 npm（Node Package Manager，节点包管理器），我们将用它来安装项目所需的依赖。

1. 访问 Node.js 官方网站：https://nodejs.org/zh-cn/
2. 强烈建议下载并安装左侧的 LTS（长期支持）版本。
3. 重要提示：Agency OS 使用的构建工具 Vite 推荐 Node.js 版本在 20.19 或更高 [1]。请确保您的版本符合要求。
4. 安装过程中，全部选择默认选项即可。
5. 安装完成后，打开命令行工具，输入以下命令并按回车：

   node -v

   如果显示了版本号（例如 v20.19.0），则表示安装成功。

2. 获取项目代码

现在，我们来下载 Agency OS 的源代码。

1. 选择一个文件夹：在您的电脑上选择一个您想存放项目的文件夹（例如 D:\Projects 或 ~/Documents/Projects）。
2. 打开命令行：进入该文件夹，并在地址栏输入 cmd 或 powershell（Windows）或右键选择“在新终端打开”（macOS/Linux），打开命令行工具。
3. 克隆仓库：在命令行中输入以下命令，将项目代码下载到本地：

   git clone https://github.com/shakugannosaints/AgencyOS.git

   您会看到命令行开始滚动下载信息。下载完成后，您的文件夹中会出现一个名为 AgencyOS 的新文件夹。
4. 进入项目目录：

   cd AgencyOS

3. 运行项目

进入项目目录后，部署过程就非常简单了。

3.1. 安装依赖

项目需要一些“零件”才能运行，我们使用 npm 来安装它们。

在 AgencyOS 文件夹的命令行中，输入：

npm install

这个过程可能需要几分钟，取决于您的网络速度。当命令行停止滚动，并显示类似 added XXX packages 的信息时，表示安装完成。

3.2. 启动开发服务器（推荐）

如果您只是想快速运行起来看看效果，或者想在本地进行一些修改，可以使用开发服务器。

在命令行中输入：

npm run dev

项目将开始编译并启动一个本地服务器。您会看到类似以下的信息：

  > Local: http://localhost:5173/
  > Network: use --host to enable

现在，您只需要在浏览器中打开显示的本地地址（通常是 http://localhost:5173），就可以开始使用 Agency OS 了！

3.3. 构建生产包（用于部署到服务器）

如果您想将 Agency OS 部署到自己的 Web 服务器（例如 Nginx、GitHub Pages 或 Vercel），您需要先构建一个“生产包”。

在命令行中输入：

npm run build

构建完成后，所有最终的网页文件、JavaScript 文件和 CSS 文件都会被放在一个名为 dist 的文件夹中。

您可以将 dist 文件夹中的所有内容上传到您的 Web 服务器上，即可完成部署。

---