From 46df098b9c812672030f1de54938133ae9bb3ac5 Mon Sep 17 00:00:00 2001
From: haeyupi <hhz101925@gmail.com>
Date: Sat, 30 May 2026 01:03:41 +0800
Subject: [PATCH] docs: polish readme style

---
 CHANGELOG.md |  1 +
 README.md    | 74 +++++++++++++++++++++++++++++-----------------------
 2 files changed, 43 insertions(+), 32 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b6cd7da..53ad9b9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,3 +4,4 @@
 
 - Added a project disclaimer to the root README.
 - Added a Linux Do friendly link and GitHub star history chart.
+- Refined the root README wording and structure for an open source project style.
diff --git a/README.md b/README.md
index 9733c2b..f775a0b 100644
--- a/README.md
+++ b/README.md
@@ -1,60 +1,78 @@
 # douyin-sparkflow
 
-Douyin SparkFlow 是一个用于自动续火花的 Web 管理版部署包。推荐用 Docker Compose 部署，启动后在浏览器里完成管理员密码、扫码登录、目标好友勾选和发送窗口设置。
+Douyin SparkFlow 提供一个面向个人自用场景的抖音火花维护工具。项目包含 Web 管理面板、登录桌面、定时任务和代理配置模板，默认通过 Docker Compose 部署。
+
+## 功能特性
+
+- Web 面板管理账号、目标好友和发送窗口。
+- 浏览器扫码登录并保存本地登录态。
+- 定时执行续火花任务，支持手动触发和日志查看。
+- 可选 Mihomo/Clash 代理订阅配置。
+- Docker Compose 编排 Web、登录桌面、定时器、任务和代理服务。
 
 ## GitHub Star 趋势
 
 [![GitHub Star 趋势图](https://api.star-history.com/svg?repos=halfwaystudent/douyin-sparkflow&type=Date)](https://star-history.com/#halfwaystudent/douyin-sparkflow&Date)
 
-## 一键部署到服务器
+## 快速开始
 
-适合 Ubuntu/Debian/CentOS 类服务器：
+在服务器上运行：
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/halfwaystudent/douyin-sparkflow/main/deploy/install-server.sh | bash
 ```
 
-也可以指定安装目录或代理订阅：
+指定安装目录或代理订阅：
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/halfwaystudent/douyin-sparkflow/main/deploy/install-server.sh | APP_ROOT=/opt/douyin-sparkflow PROXY_SUB_URL='你的 Mihomo/Clash 订阅链接' bash
 ```
 
-部署完成后打开：
+部署完成后访问：
 
 - Web 面板：`http://服务器IP:8787`
-- 扫码登录桌面：Web 面板里的“登录桌面”入口，默认端口 `8788`
+- 登录桌面：Web 面板中的“登录桌面”入口，默认端口 `8788`
 
-首次使用流程：
+首次使用：
 
-1. 创建管理员账号密码。
-2. 打开登录桌面，扫码登录抖音。
+1. 创建管理员账号。
+2. 打开登录桌面并扫码登录抖音。
 3. 保存登录态。
-4. 刷新好友列表，勾选要续火花的目标好友。
+4. 刷新好友列表并选择目标好友。
 5. 设置发送窗口，例如 `10:00-18:00/10m`。
 
-## 本地部署
+## 本地运行
 
-Windows 本地需要先启动 Docker Desktop，然后运行：
+Windows 需要先启动 Docker Desktop：
 
 ```powershell
 .\deploy\install-local.ps1
 ```
 
-带代理订阅：
+如需配置代理订阅：
 
 ```powershell
 .\deploy\install-local.ps1 -ProxySubUrl "你的 Mihomo/Clash 订阅链接"
 ```
 
-脚本会创建 `.env`、运行态目录和默认代理配置，然后执行 `docker compose up -d --build` 并打开 Web 面板。
-
-Linux/macOS 本地可以运行：
+Linux/macOS：
 
 ```bash
 ./deploy/install-local.sh
 ```
 
+本地脚本会创建 `.env`、运行态目录和默认代理配置，并执行 `docker compose up -d --build`。
+
+## 配置说明
+
+如果 `.env` 中的 `PROXY_SUB_URL` 为空，项目会使用 `proxy/config.example.yaml` 生成直连代理配置。
+
+首次构建需要拉取 Playwright 基础镜像。默认 `.env.example` 使用国内同步源；如果同步源不可用，可以将 `.env` 中的 `PLAYWRIGHT_BASE_IMAGE` 改为：
+
+```bash
+PLAYWRIGHT_BASE_IMAGE=mcr.microsoft.com/playwright/python:v1.56.0-jammy
+```
+
 ## 常用命令
 
 ```bash
@@ -72,25 +90,17 @@ docker compose down
 docker compose restart proxy
 ```
 
-如果 `.env` 里的 `PROXY_SUB_URL` 为空，系统会使用 `proxy/config.example.yaml` 生成一个直连配置。
-
-首次构建会拉取较大的 Playwright 基础镜像。默认 `.env.example` 使用国内同步源以加速下载；如果同步源不可用，可以把 `.env` 里的 `PLAYWRIGHT_BASE_IMAGE` 改回：
-
-```bash
-PLAYWRIGHT_BASE_IMAGE=mcr.microsoft.com/playwright/python:v1.56.0-jammy
-```
-
-## 目录结构
+## 项目结构
 
 - `DouYinSparkFlow/`：核心应用、Web UI、登录桌面和发送任务。
-- `docker-compose.yml`：统一容器编排入口，包含 Web、登录桌面、定时器、任务和代理服务。
-- `deploy/`：服务器和本地一键部署脚本。
-- `proxy/config.example.yaml`：安全的代理配置模板。
+- `docker-compose.yml`：容器编排入口。
+- `deploy/`：服务器和本地部署脚本。
+- `proxy/config.example.yaml`：代理配置模板。
 - `.env.example`：部署环境变量模板。
 
-## 不提交的运行态文件
+## 安全与隐私
 
-这些内容包含账号、登录态、日志或本机配置，不应提交到 GitHub：
+以下文件可能包含账号、登录态、日志或本机配置，请勿提交到公开仓库：
 
 - `.env`
 - `state/`
@@ -103,9 +113,9 @@ PLAYWRIGHT_BASE_IMAGE=mcr.microsoft.com/playwright/python:v1.56.0-jammy
 
 ## 免责声明
 
-本项目只是为了方便个人管理和自用，不是抖音、字节跳动或相关平台的官方工具，也未获得其授权、背书或关联。
+本项目仅用于个人学习、研究和自用场景，不是抖音、字节跳动或相关平台的官方工具，也未获得其授权、背书或关联。
 
-使用本项目时，请遵守所在地法律法规、抖音平台规则和相关服务协议。请不要将本项目用于商业用途、批量营销、骚扰他人、刷量引流、规避平台风控，或任何可能损害平台、他人账号及第三方权益的行为。
+使用本项目时，请遵守所在地法律法规、抖音平台规则和相关服务协议。请勿将本项目用于商业用途、批量营销、骚扰他人、刷量引流、规避平台风控，或任何可能损害平台、他人账号及第三方权益的行为。
 
 本项目会在使用者授权登录后，按照使用者配置的账号、好友和发送窗口执行自动化操作。由此产生的账号异常、限流、封禁、数据丢失、服务中断、消息误发、隐私泄露或其他损失，均由使用者自行承担。项目作者和贡献者不对使用本项目产生的任何直接或间接后果负责。