docs: Infima-aligned visual overhaul — admonitions, table styling, and key information highlights (#105)

* docs: Component Intro update, contact page merge, PacketTool encrypt, cookbook notes

- Component Introduction: update feature table — Multi-Language verified,
  add Multi-Protocol Auth, Silent Update, Concurrent Download, File Tree Diff
- Component Introduction: remove section 6 (merged into /contact page)
- contact.js: enrich with QQ groups, GitHub Issues, paid consultation,
  corporate wall, and sponsorship sections
- GeneralUpdate.PacketTool: add encrypted/packed file detection step
  to Patch section (zh+en)
- Beginner cookbook: add encrypted/packed file diff limitation note
  under installation directory notes (zh+en)
- GeneralSpacestation: remove Solutions/Screenshots sections, center logo,
  rename Canary Rollouts, add offline edition note (zh+en)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: Infima-aligned visual overhaul — admonitions, table styling, badges, key info highlights

- Rewrite custom.css with Infima design tokens for admonitions, tables,
  badges, emphasis boxes, compat chips, code blocks, and dark mode
- Add strategic admonitions (tip/info/warning/danger/note) across all
  12 doc pages at key decision/information points
- Sync admonitions and visual enhancements across 3 locales
  (source docs/, i18n/en/, i18n/zh-Hans/)
- Build verified clean — no errors introduced

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: JusterZhu

website/docs/doc/Component Introduction.md

@@ -14,6 +14,9 @@ GeneralUpdate is an open-source cross-platform application automatic update comp
 | -------------------- | ------------------- | --------------------- |
 | ![](imgs\github.png) | ![](imgs\gitee.png) | ![](imgs\gitcode.jpg) |
 
+:::note 一句话理解
+把 Client（你的主程序）、Upgrade（升级进程）、Server（更新服务）和 Tools（打包工具）拆开，通过 manifest + IPC 加密契约串联成一个**全自动的更新闭环**。
+:::
 
 
 ## 2. What does GeneralUpdate offer?
@@ -108,6 +111,10 @@ Before starting to use GeneralUpdate, we need to understand some basic concepts
 | Server              | Server Application                                           | Manages version update information, patch packages, and version verification. (In the Samples, only a simple example is provided and does not fulfill these functions; developers need to implement this themselves or purchase the GeneralSpacestation service). |
 | GeneralUpdate.Tools | Update Patch Creation Tool                                   | A packaging tool provided by this open-source project for generating update patch packages (.zip file format). |
 
+:::tip 更新闭环
+典型的更新流程是：**Client → Server（版本检查）→ 下载补丁包 → 写 IPC 加密契约 → 启动 Upgrade → Upgrade 校验 Hash → 解压覆盖 → 启动新版本 Client**。
+:::
+
 ##### Quick Start
 
 - Quick Start: https://www.justerzhu.cn/docs/quickstart/quikstart
@@ -123,5 +130,3 @@ GeneralUpdate follows [Semantic Versioning](https://semver.org/) core principles
 - NuGet Versioning Guidelines: https://docs.microsoft.com/en-us/nuget/concepts/package-versioning 
 - Assembly Versioning Guidelines: https://docs.microsoft.com/en-us/dotnet/standard/assembly/versioning
 
-
-

website/docs/doc/GeneralSpacestation.mdx

@@ -88,6 +88,10 @@ TSLH™ GeneralSpacestation 是**客户端全生命周期升级管理服务**，
 - **部署模式**：私有化本地部署，数据不出企业内网
 - **核心价值**：降低客户端运维成本、精准控制版本发布范围、完整追溯升级链路
 
+:::note 开源组件 vs 商业服务
+**GeneralUpdate**（开源）解决了"客户端怎么更新"的问题；**GeneralSpacestation**（商业）解决了"服务端怎么管理更新"的问题。前者是客户端 SDK，后者是服务端管理平台。两者配合使用，形成完整的客户端升级管理体系。
+:::
+
 ### 体系构成
 
 | 组件 | 说明 | 是否收费 |

website/docs/doc/GeneralUpdate.Bowl.md

@@ -30,6 +30,10 @@ sidebar_position: 3
 - 开发者缺少崩溃现场信息（Dump、系统环境）来定位"升级后打不开"的问题
 - 需要自动化回滚机制降低升级风险，避免人工介入
 
+:::warning Bowl 不是更新组件，是守护组件
+Bowl **不负责**下载、解压或替换升级包。它的唯一职责是：在新版本文件落地后、主程序启动时，监控目标进程是否在启动阶段崩溃。如果发现崩溃 → 生成诊断信息 → 可选地自动回滚。它应该放在升级流程的**最后一步**——在文件替换完成后才启动守护。
+:::
+
 **业务使用场景：**
 - 桌面应用升级后启动健康检查与自动回滚保护
 - 通用进程启动崩溃监控与诊断信息采集

website/docs/doc/GeneralUpdate.Core.md

@@ -39,6 +39,10 @@ sidebar_position: 5
 - 通过 CDN / OSS 分发更新包的客户端应用
 - 需要差分更新降低带宽消耗的大型客户端
 
+:::info Core 在生态中的定位
+GeneralUpdate.Core 是整个生态的**核心引擎**。它不负责生成补丁（那是 Tools/Differential 的工作），也不负责崩溃后的恢复（那是 Bowl 的工作），而是负责**编排整个更新流程**：从版本检查、下载、校验到启动 Upgrade 进程完成文件替换。
+:::
+
 ### 1.2 环境与依赖
 
 | 项目 | 说明 |
@@ -927,12 +931,17 @@ Core 不依赖全局配置文件，而是通过 `generalupdate.manifest.json` 
 
 ### 配置优先级规则
 
+> **优先级越高，覆盖力越强。** 代码中的显式设置总是优先于 manifest 和默认值。
+
 | 优先级 | 配置来源 | 说明 |
 | --- | --- | --- |
 | 1（最高） | 代码中 `SetConfig(UpdateRequest)` 或 `SetSource(...)` 显式设置的值 | 覆盖所有其他来源 |
 | 2 | `generalupdate.manifest.json` 中的字段 | 自动补齐代码中未显式设置的字段 |
 | 3（最低） | 组件内部默认值 | `UpdateAppName = "Update.exe"`, `InstallPath = BaseDirectory` 等 |
 
+:::tip 最佳实践：用 manifest 存身份，用代码存 secret
+把 `MainAppName`、`ClientVersion`、`UpdateAppName`、`ProductId` 等身份字段放在 manifest 中（由 Tools 自动生成），把 `UpdateUrl`、`AppSecretKey`、`Token` 等敏感信息写在代码里。身份属于项目结构，不应硬编码；secret 属于安全配置，不应落入版本控制。
+:::
 ### Manifest 字段映射
 
 | JSON 字段 | Core 字段 | 说明 |

website/docs/doc/GeneralUpdate.Differential.md

@@ -30,6 +30,10 @@ sidebar_position: 6
 - 不同文件类型和变化模式需要不同的差分策略（细粒度匹配 vs 快速块匹配）
 - 压缩算法的选择影响客户端解压速度和补丁体积的平衡
 
+:::note Differential 是底层库，通常不直接使用
+大多数场景下你不需要直接调用 `IBinaryDiffer`。目录级差分、批量补丁生成、并行调度和更新流程编排由 `GeneralUpdate.Core` 的 `DiffPipeline` 或 `GeneralUpdate.Tools` 承担。Differential 只解决一个原子问题：**一个旧文件 + 一个补丁文件 = 一个新文件**。
+:::
+
 **业务使用场景：**
 - 大型桌面应用（多 DLL、资源文件）的增量更新
 - 固件/驱动包的二进制差分分发

website/docs/doc/GeneralUpdate.Drivelution.md

@@ -34,6 +34,10 @@ sidebar_position: 8
 - 驱动安装需要管理员权限、签名校验、架构兼容性检查等多重保障
 - 驱动安装失败后需要可靠的回滚机制，避免设备不可用
 
+:::danger 驱动更新 ≠ 普通文件替换
+驱动更新会影响内核、设备节点、系统扩展或驱动仓库。**必须关注**：管理员权限、签名可信度、目标系统和 CPU 架构、安装命令返回值、是否需要系统重启以及失败后的恢复路径。生产环境中**永远不要**跳过哈希和签名校验。
+:::
+
 **业务使用场景：**
 - 硬件厂商客户端：网卡、采集卡、USB 设备、虚拟设备驱动随应用一起交付
 - 企业/工业现场：批量扫描驱动包并按清单更新

website/docs/doc/GeneralUpdate.Extension.md

@@ -37,6 +37,10 @@ sidebar_position: 7
 - 扩展之间有依赖关系，需要自动管理依赖的安装和版本兼容性
 - 需要统一的扩展管理框架减少重复开发
 
+:::tip 类比：VS Code 扩展市场
+如果你的产品需要像 VS Code 那样的插件生态——远程查询扩展、一键安装、版本兼容检查、依赖自动安装、失败回滚——`GeneralUpdate.Extension` 提供了完整的底层能力。你只需要在此基础上搭一个"扩展市场"的 UI。
+:::
+
 **业务使用场景：**
 - IDE 类应用的插件市场
 - 企业 ERP/CRM 的行业模块（报表模板、认证方式、数据导出等）

website/docs/doc/UpgradeHub.md

@@ -8,6 +8,10 @@ sidebar_position: 7
 
 **UpgradeHubService** 是基于 SignalR 的实时版本推送服务，集成在 `GeneralUpdate.Core` 中。服务端通过 `UpgradeHub` 向已连接的客户端主动推送版本更新通知，客户端通过 `UpgradeHubService` 订阅并接收消息，支持点对点（一对一）和广播（一对多）两种推送模式。
 
+:::tip UpgradeHub 与 Core 的关系
+`UpgradeHubService` 是 `GeneralUpdate.Core` 的**可选功能**，不依赖它也能完成常规更新。它的价值在于：服务端有紧急版本时可以**主动推送**通知给在线客户端，客户端无需等待下一次轮询就能立即触发更新——特别适合紧急 bug 修复和灰度发布场景。
+:::
+
 **命名空间：** `GeneralUpdate.Core.Hubs`  
 **程序集：** `GeneralUpdate.Core.dll`
 

website/docs/quickstart/Beginner cookbook.md

@@ -7,6 +7,10 @@ title: 入门实战手册
 
 这篇手册面向第一次接触 GeneralUpdate 的开发者。目标不是一次讲完所有 API，而是让你从零开始，写完 Client → 写完 Upgrade → 用 Tools 生成配置 → 启动 Server → 一条命令跑通完整的"发现更新 → 下载 → 应用 → 回到新版本"闭环。
 
+:::info 你将学到什么
+完成这篇手册后，你会拥有一个**可运行的端到端自动更新系统**：一个能检查更新的 Client、一个能应用更新的 Upgrade、一份自动生成的 manifest、以及一个本地测试 Server。
+:::
+
 <iframe
   src="//player.bilibili.com/player.html?bvid=BV12P9dBiEEh&page=1"
   width="100%"
@@ -68,6 +72,10 @@ title: 入门实战手册
 
 ## Phase 1：环境准备
 
+:::caution 开始之前
+所有后续步骤都依赖这两个工具。请先用验证命令确认它们安装正确，否则 Phase 4 的 `dotnet publish` 和 Phase 5 的 Server 启动会失败。
+:::
+
 ### 安装清单
 
 | 项 | 要求 | 验证命令 |
@@ -174,6 +182,10 @@ await new GeneralUpdateBootstrap()
 
 Client 不直接应用更新——下载完成后写 IPC 加密契约 → 启动 Upgrade → 自身退出。
 
+:::tip 关键设计
+Client **只负责发现和下载**，文件替换工作完全交给独立的 Upgrade 进程。这是因为运行中的进程无法覆盖自身的可执行文件——通过 IPC 加密契约把控制权交给 Upgrade，是实现"自己更新自己"的核心架构。
+:::
+
 ---
 
 ## Phase 3：集成 Upgrade 代码
@@ -256,6 +268,10 @@ publish/
 
 > **注意**：`MyApp.Upgrade.exe` 不在根目录，而是在 `update/` 子目录下。框架根据 manifest 的 `updatePath` 字段（默认 `"update/"`）找到并启动它。
 
+:::warning 目录结构错误会导致升级失败
+Upgrade 进程(.exe) **必须**放在 manifest 指定的 `updatePath` 子目录下。如果 Upgrade 不在该位置，Client 将无法找到并启动升级进程，整个更新链路中断。常见错误：把 Upgrade 放在根目录或不同名称的子目录中。
+:::
+
 ### `generalupdate.manifest.json` 示例
 
 ```json
@@ -350,7 +366,8 @@ Client (新版本):
   MyApp v2.0.0.0 ✓
 ```
 
-### 排查清单
+:::tip 排查清单
+Use this table to diagnose common issues quickly. Most failures trace back to one of these five checks.
 
 | 现象 | 检查 |
 | --- | --- |
@@ -359,6 +376,7 @@ Client (新版本):
 | 下载完成但未启动 Upgrade | `MyApp.Upgrade.exe` 是否在 `update/` 子目录下，manifest 的 `updatePath` 是否正确 |
 | Upgrade 报错退出 | 检查目录写入权限、杀毒软件是否拦截 |
 | 端口被占用 | 修改 Server 启动参数 `--Urls http://0.0.0.0:5001`，同步修改 Client 的 `UpdateUrl` |
+:::
 
 ---
 

website/docs/quickstart/GeneralUpdate.PacketTool.md

@@ -6,7 +6,11 @@ sidebar_position: 11
 
 ## 这是什么
 
-GeneralUpdate.Tools 是一个基于 Avalonia 12 开发的跨平台桌面工具（Windows / Linux / macOS），用于在软件发布流程中生成和管理补丁包、扩展包、版本清单以及执行本地更新仿真。它不替代你的 CI/CD 系统，而是把“打包、校验、验证”这些重复劳动收敛到一个可视化工具中。
+GeneralUpdate.Tools 是一个基于 Avalonia 12 开发的跨平台桌面工具（Windows / Linux / macOS），用于在软件发布流程中生成和管理补丁包、扩展包、版本清单以及执行本地更新仿真。它不替代你的 CI/CD 系统，而是把”打包、校验、验证”这些重复劳动收敛到一个可视化工具中。
+
+:::info Tools 与 CI/CD 的关系
+Tools 是**桌面 GUI 工具**，适合开发者在本地交互式地生成补丁、验证更新。如果你需要在 CI/CD 流水线中自动化补丁生成，可以直接调用 `GeneralUpdate.Core.Pipeline.DiffPipeline.CleanAsync()` —— GUI 和脚本走的是同一条代码路径。
+:::
 
 仓库地址：[https://github.com/GeneralLibrary/GeneralUpdate.Tools](https://github.com/GeneralLibrary/GeneralUpdate.Tools)
 
@@ -68,6 +72,11 @@ dotnet run --project GeneralUpdate.Tools.csproj
 
 > **关于加密文件**：加壳工具（Themida、VMProtect 等）、代码混淆或加密的二进制文件，因文件哈希在新旧版本间完全不同，差分算法对其无效。此类文件检测到后将直接以全量形式打包，而不会生成 `.patch` 差分。建议在发布前对原始文件进行去壳/解密处理，以获得最优的补丁体积。
 
+
+:::warning 加密/加壳文件无法差分
+如果你的应用使用了加壳工具（Themida、VMProtect）、代码混淆器或加密二进制文件，**整个文件在新旧版本间会完全不同**，差分算法完全失效，补丁包体积等同于全量文件。如需差分更新，请确保原始发布文件未被加壳或加密。
+:::
+
 底层调用的是 `GeneralUpdate.Core.Pipeline.DiffPipeline.CleanAsync(oldDir, newDir, patchDir)`，和你的 CI 脚本走的是同一条代码路径。
 
 ### 输出