Add more warnings for Code Download Zip

People download zip files from the Github Code Download Zip file option, which is bad.

Added more warning to make it obvious.

Author: t41372

docs/faq.md

@@ -151,6 +151,9 @@ Error calling the chat endpoint
 ## 网页/客户端相关
 
 ### Web 显示 `{"detail": "Not Found"}` 怎么办
+
+![](img/faq/detail-not-found.jpg)
+
 - 前端代码没有被拉取到本地。出现这个报错说明你没有获取到完整的项目代码。请在项目目录下运行 `git submodule update --init --recursive` 来拉取项目代码。
 - 详细请参考 [快速开始/1. 获取项目代码](quick-start#1-获取项目代码) 中提到的两种获取项目代码的方式。
 

docs/img/faq/detail-not-found.jpg

@@ -257,7 +257,7 @@ source ~/.zshrc   # 如果使用 zsh
 
 更多 uv 安装方法参考：[Installing uv](https://docs.astral.sh/uv/getting-started/installation/)
 
-## 手动部署指南
+## 部署指南
 
 ### 1. 获取项目代码
 
@@ -271,7 +271,11 @@ source ~/.zshrc   # 如果使用 zsh
 
 <Tabs groupId="code-clone-method">
   <TabItem value="release" label="下载稳定的 release 包">
-  前往最新的 [release 页面](https://github.com/Open-LLM-VTuber/Open-LLM-VTuber/releases)，下载长得像 `Open-LLM-VTuber-v1.x.x.zip` 的 zip 文件。
+  从项目的 [**Release 页面**](https://github.com/Open-LLM-VTuber/Open-LLM-VTuber/releases)，下载长得像 `Open-LLM-VTuber-v1.x.x.zip` 的 zip 文件。
+
+  :::warning
+  注意，是 Release 页面，**不是**项目主页上面那个 Code 按钮的 "Download ZIP" 选项。请不要用 "Download ZIP" 按钮下载项目代码。
+  :::
 
   如果你想要使用桌宠模式或是桌面版本，你可以顺手再下载以 `open-llm-vtuber-electron` 开头的文件。windows 用户下载 exe，macOS 用户下载 dmg文件。这个是桌面版本的客户端。之后等后端配置完成并启动之后，这个electron 版前端可以启动桌宠模式。
 
@@ -281,8 +285,10 @@ source ~/.zshrc   # 如果使用 zsh
   使用 git 拉取时，请确保网络畅通。中国大陆用户可能需要开启代理。
   :::
 
-  :::info
-  自 `v1.0.0` 开始，前端代码 (用户界面) 已被拆分到独立仓库中。我们建立了构建流程，并通过 git submodule 将前端代码链接到主仓库的 `frontend` 目录下，因此在克隆仓库时要像下面这样添加 `--recursive`。
+  :::warning
+  git clone 命令后面必须加上 `--recursive` flag。
+  
+  这是因为自 `v1.0.0` 开始，前端代码 (用户界面) 已被拆分到独立仓库中。我们建立了构建流程，通过 git submodule 将前端代码链接到主仓库的 `frontend` 目录下，因此在克隆仓库时要添加 `--recursive` 的 flag，否则会缺失前端代码，造成 [浏览器显示 Detail Not Found 的错误](faq.md#web-显示-detailnotfound-怎么办)。
   :::
 
   ```bash
@@ -297,6 +303,17 @@ source ~/.zshrc   # 如果使用 zsh
 
   </TabItem>
 
+  <TabItem value="git-zip" label="不要从 Code 按钮下载 zip">
+  ![don't do this](./img/git-code-zip.jpg)
+
+  请 **不要** 从 GitHub 主页上，那个绿色的 "Code" 按钮那边，下载 Zip 文件，或是直接用那边提供的克隆命令，获取项目代码。
+
+  为什么不能从 Code 按钮下载 Zip 文件?
+  - 从 Code 按钮中获取的 Zip 文件 **不包含 Git 信息**。这是 Github 自己生成的，我没法控制。
+  - 本项目前端由 submodule 链接，如果你从这个按钮下载 Zip 文件，你会拿不到前端代码，导致 [浏览器显示 Detail Not Found 的错误](faq.md#web-显示-detailnotfound-怎么办)
+  - 本项目更新机制依赖 Git，因此缺失 Git 信息**会导致你无法使用更新功能**。
+  </TabItem>
+
 </Tabs>
 
 

docs/img/git-code-zip.jpg

@@ -138,6 +138,9 @@ If you absolutely must run two Open-LLM-VTuber backends simultaneously, or if an
 ## Web/Client Related
 
 ### What to do if Web displays `{"detail": "Not Found"}`?
+
+![](img/faq/detail-not-found.jpg)
+
 - The frontend code hasn't been pulled to local. This error appears when you haven't obtained the complete project code. Please run `git submodule update --init --recursive` in the project directory to pull the project code.
 - For details, please refer to the two ways of obtaining project code mentioned in [Quick Start/1. Get Project Code](quick-start#1-get-project-code).
 

docs/quick-start.md

@@ -242,15 +242,19 @@ brew install uv
 
 For more uv installation methods, refer to: [Installing uv](https://docs.astral.sh/uv/getting-started/installation/)
 
-## Manual Deployment Guide
+## Deployment Guide
 
 ### 1. Get the Project Code
 
 There are two methods to acquire the project code.
 
 <Tabs groupId="code-clone-method">
   <TabItem value="release" label="Download Stable Release from GitHub">
-  Visit the latest [release page](https://github.com/Open-LLM-VTuber/Open-LLM-VTuber/releases) and download the ZIP file named similar to `Open-LLM-VTuber-v1.x.x.zip`.
+  Go to our [**Release page**](https://github.com/Open-LLM-VTuber/Open-LLM-VTuber/releases) and download the ZIP file that looks like `Open-LLM-VTuber-v1.x.x.zip` from the **release page**.
+
+  :::warning
+  Note that you need to download from the **Release Page**, **NOT the "Download ZIP" option from the "Code" button on the GitHub main page**. Don't do that!
+  :::
 
   If you want Desktop Pet Mode or desktop client version, you can also download files starting with `open-llm-vtuber-electron` - Windows users download the exe file, while the macOS users download the dmg file. This desktop client can launch Pet Mode after you configured backend and successfully start the backend server.
 
@@ -260,8 +264,10 @@ There are two methods to acquire the project code.
   Ensure stable network connection when using Git. Mainland China users may need to use a proxy.
   :::
 
-  :::info
-  Starting from `v1.0.0`, frontend code (user interface) has been moved to a separate repository. We've established build workflows and linked frontend code via git submodule to the `frontend` directory. Adding the `--recursive` flag is therefore required in git clone command.
+  :::warning
+  The `--recursive` flag is REQUIRED for the git clone command.
+
+  This is because, starting from `v1.0.0`, frontend code (user interface) has been moved to a separate repository. We've established build workflows and linked frontend code via git submodule to the `frontend` directory. Adding the `--recursive` flag is therefore required in git clone command. Without the `--recursive` flag, you will run into the problem that [the web displays "Detail: Not found"](faq.md#what-to-do-if-web-displays-detail-not-found)
   :::
 
   ```bash
@@ -275,6 +281,18 @@ There are two methods to acquire the project code.
   For Desktop Pet Mode or desktop client, visit [Open-LLM-VTuber-Web Releases](https://github.com/Open-LLM-VTuber/Open-LLM-VTuber-Web/releases/latest) and download `open-llm-vtuber-electron` files - Windows users download the exe file, while the macOS users download the dmg file. This desktop client can launch Pet Mode after you configured backend and successfully start the backend server.
 
   </TabItem>
+  
+  <TabItem value="git-zip" label="Don't download the ZIP from the Code button">
+  ![don't do this](./img/git-code-zip.jpg)
+
+  Please **DO NOT** download the ZIP file from the green "Code" button on the GitHub main page, nor use the clone command provided there to get the project code.
+
+  Why can't I download the ZIP file from the Code button?
+  - The ZIP file obtained from the Code button **does not contain Git information**. This is generated by GitHub, and I have no control over it.
+  - The front end of this project is linked by submodules. If you download the ZIP file from this button, you will not get the front-end code, which will cause [the browser to display a "Detail Not Found" error](faq.md#what-to-do-if-the-web-shows-detailnotfound).
+  - The update mechanism of this project relies on Git, so missing Git information **will prevent you from using the update function**.
+  </TabItem>
+
 </Tabs>