diff --git a/README.md b/README.md
index 5228f3e..2d49824 100644
--- a/README.md
+++ b/README.md
@@ -1,78 +1,122 @@
 # yoyuzh.xyz
 
-个人站点项目，包含前端门户、Spring Boot 后端、个人网盘、快传模块和后台管理台。
+一个基于 React + Spring Boot 构建的个人站点项目，包含个人网盘、浏览器快传、账号系统与后台管理台。
 
-## 项目特性
+## 项目简介
 
-- 用户注册、登录、JWT 鉴权
-- 邀请码注册，邀请码单次使用后自动轮换
+这个仓库是 `yoyuzh.xyz` 的完整源码。
+
+它不是一个单页 Demo，而是一个持续迭代中的全栈个人网站，覆盖了前端门户、后端 API、文件存储、账号体系和管理功能。
+
+## 功能特性
+
+### 用户系统
+
+- 用户注册与登录
+- 邀请码注册
 - 同账号仅允许一台设备同时登录
-- 个人网盘：上传、下载、重命名、删除、移动、复制、分享
-- 快传：取件码、分享链接、浏览器间 P2P 传输、接收后存入网盘
-- 管理台：用户管理、文件管理、邀请码查看与复制
+- 个人资料管理
+
+### 网盘
+
+- 文件上传、文件夹上传
+- 下载、重命名、删除
+- 文件与文件夹移动
+- 文件与文件夹复制
+- 树状目录浏览
+- 分享链接生成与导入
+
+### 快传
+
+- 取件码分享
+- 分享链接打开
+- 浏览器间 P2P 传输
+- 接收端可选择部分文件接收
+- 支持整包 ZIP 下载
+- 支持接收后直接存入网盘
+
+### 管理台
+
+- 用户管理
+- 文件管理
+- 注册邀请码查看
 
 ## 技术栈
 
-- 前端：Vite 6、React 19、TypeScript、Tailwind CSS v4
-- 后端：Spring Boot 3.3、Java 17、Maven
-- 数据库：MySQL 8.x
-- 对象存储：本地文件系统或阿里云 OSS
-- 部署：前端 OSS 静态发布，后端 jar + systemd
+### 前端
+
+- React 19
+- TypeScript
+- Vite 6
+- Tailwind CSS v4
+
+### 后端
+
+- Java 17
+- Spring Boot 3.3
+- Spring Security
+- Spring Data JPA
+- Maven
+
+### 存储与基础设施
+
+- MySQL 8.x
+- 本地文件系统 / 阿里云 OSS
+- OSS 静态资源发布
 
 ## 仓库结构
 
 ```text
 .
-├── front/      前端站点
-├── backend/    Spring Boot 后端
-├── docs/       计划与文档
-├── scripts/    部署与辅助脚本
-├── 模板/       页面参考模板
-└── data/       本地数据或辅助文件
+├── backend/      Spring Boot 后端
+├── front/        React 前端
+├── docs/         计划与文档
+├── scripts/      部署与辅助脚本
+├── data/         本地数据或辅助文件
+└── 模板/         页面参考模板
 ```
 
-## 核心页面
+## 快速开始
 
-- `/overview` 总览页
-- `/files` 网盘
-- `/transfer` 快传
-- `/games` 小游戏
-- `/admin/*` 管理台
+### 环境要求
 
-## 本地开发
+- Node.js
+- npm
+- JDK 17+
+- Maven 3.9+
+- MySQL 8.x
 
 ### 1. 启动后端
 
-进入 `backend/` 后运行：
-
 ```bash
-APP_JWT_SECRET=<至少32字节的随机密钥> mvn spring-boot:run
+cd backend
+APP_JWT_SECRET=<至少32字节的密钥> mvn spring-boot:run
 ```
 
-如果需要本地开发环境：
+如果要使用本地开发配置：
 
 ```bash
-APP_JWT_SECRET=<至少32字节的随机密钥> mvn spring-boot:run -Dspring-boot.run.profiles=dev
+cd backend
+APP_JWT_SECRET=<至少32字节的密钥> mvn spring-boot:run -Dspring-boot.run.profiles=dev
 ```
 
 说明：
 
-- `dev` 环境默认使用 H2
-- 默认端口是 `8080`
-- Swagger 地址是 `http://localhost:8080/swagger-ui.html`
+- 默认端口：`8080`
+- Swagger：`http://localhost:8080/swagger-ui.html`
+- `dev` 环境默认使用 H2，更适合本地联调
 
 ### 2. 启动前端
 
-进入 `front/` 后运行：
-
 ```bash
+cd front
 npm run dev
 ```
 
 说明：
 
-- 默认端口是 `3000`
-- 本地前端通过 `front/vite.config.ts` 里的代理访问后端
+- 默认端口：`3000`
+- 本地前端代理配置位于 `front/vite.config.ts`
 
 ## 常用命令
 
@@ -98,29 +142,22 @@ mvn test
 mvn package
 ```
 
-注意：
-
-- 不要在仓库根目录执行 `npm` 命令，这里没有根 `package.json`
-- 前端的 `npm run lint` 实际执行的是 `tsc --noEmit`
-
 ## 环境变量
 
-### 后端
-
-至少需要：
+### 后端必填
 
 ```env
-APP_JWT_SECRET=<至少32字节的随机密钥>
+APP_JWT_SECRET=<至少32字节的密钥>
 ```
 
-可选：
+### 后端可选
 
 ```env
 APP_ADMIN_USERNAMES=admin1,admin2
 APP_AUTH_REGISTRATION_INVITE_CODE=<初始化邀请码种子>
 ```
 
-如果启用 OSS：
+### OSS 相关
 
 ```env
 YOYUZH_STORAGE_PROVIDER=oss
@@ -130,16 +167,16 @@ YOYUZH_OSS_ACCESS_KEY_ID=...
 YOYUZH_OSS_ACCESS_KEY_SECRET=...
 ```
 
-### 前端
+### 前端发布配置
 
-前端生产发布脚本会读取 `.env.oss.local` 或环境变量中的 OSS 配置。
+前端发布脚本会从环境变量或 `.env.oss.local` 中读取 OSS 配置。
 
 参考文件：
 
 - `.env.oss.example`
 - `.env.oss.local`
 
-## 发布方式
+## 部署
 
 ### 前端发布
 
@@ -149,7 +186,7 @@ YOYUZH_OSS_ACCESS_KEY_SECRET=...
 node scripts/deploy-front-oss.mjs
 ```
 
-可选：
+可选参数：
 
 ```bash
 node scripts/deploy-front-oss.mjs --dry-run
@@ -158,46 +195,27 @@ node scripts/deploy-front-oss.mjs --skip-build
 
 ### 后端发布
 
-1. 在 `backend/` 下执行：
+先打包：
 
 ```bash
+cd backend
 mvn package
 ```
 
-2. 将生成的 jar 上传到服务器：
+生成产物：
 
 ```text
 backend/target/yoyuzh-portal-backend-0.0.1-SNAPSHOT.jar
 ```
 
-3. 替换服务器上的运行包并重启 systemd 服务
+然后将 jar 上传到服务器，并按你的 systemd / SSH 流程重启服务。
 
-当前线上流程是：
+## 项目说明
 
-- 远端目录：`/opt/yoyuzh`
-- 运行包：`/opt/yoyuzh/yoyuzh-portal-backend.jar`
-- 服务名：`my-site-api.service`
-
-## 业务说明
-
-### 网盘
-
-- 支持文件和文件夹上传
-- 支持移动到、复制到
-- 支持生成公开分享链接
-- 支持从快传接收结果直接存入网盘
-
-### 快传
-
-- 文件内容默认走浏览器间 P2P DataChannel
-- 后端负责会话、取件码和信令交换
-- 接收端可选择部分文件接收，也可整包 ZIP 下载
-
-### 登录与邀请码
-
-- 注册必须填写邀请码
-- 邀请码会在成功注册后自动刷新
-- 同一账号新设备登录后，旧设备会在下次访问受保护接口时失效
+- 注册需要邀请码
+- 邀请码在成功注册后会自动刷新
+- 同账号新设备登录后，旧设备会在下次访问受保护接口时失效
+- 快传走“后端信令 + 浏览器 P2P 传输”模式
 
 ## 相关文档
 
@@ -206,7 +224,6 @@ backend/target/yoyuzh-portal-backend-0.0.1-SNAPSHOT.jar
 - [AGENTS.md](./AGENTS.md)
 - `docs/superpowers/plans/`
 
-## 备注
+## 当前状态
 
-- `front/README.md` 是历史模板文件，项目当前真实启动与发布方式以本 README 和 `AGENTS.md` 为准
-- 如果需要快速了解当前实现，建议先看 `front/src/pages/` 和 `backend/src/main/java/com/yoyuzh/`
+项目正在持续迭代中，定位是一个真实运行中的个人站点，而不是最小演示项目。