Skip to content

Commit c9433dc

Browse files
JusterZhuclaude
JusterZhu
and
claude
authored
docs: update Core & Differential docs and sync i18n across all locales (#87)
* docs: update Core & Differential docs and sync i18n across all locales - Expand SetSource signature to include all 9 parameters (authScheme, basicUsername, basicPassword, installPath) - Add AuthScheme, BasicUsername, BasicPassword fields to UpdateRequest config table - Add SetAuthScheme, SetBasicUsername, SetBasicPassword methods to UpdateRequestBuilder - Update BrotliCompressionProvider description to reflect conditional compilation implementation - Sync all changes to English (i18n/en) and Chinese (i18n/zh-Hans) translations - Replace outdated zh-Hans i18n overrides with current structured API reference format Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix: remove redundant zh-Hans i18n overrides causing MDX build failure The zh-Hans locale is the default locale in Docusaurus config, so docs/doc/ serves zh-Hans content directly. The i18n/zh-Hans/ overrides are unnecessary and were causing MDX compilation errors during website build. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix: remove <br> tags in SetSource table row causing MDX compilation error The <br> HTML tags inside markdown table cells were being interpreted as JSX elements by the MDX parser (mdast-util-mdx-jsx), causing the Docusaurus website build to fail. Replaced with comma-separated format. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix: remove .md suffix from all internal Docusaurus links Docusaurus resolves internal doc links without the .md extension. Links with .md suffix break when the target document's i18n override is removed (Docusaurus falls back to docs/ but can't match the .md suffix). This was pre-existing but masked by zh-Hans i18n overrides for Core and Differential docs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 5e800c7 commit c9433dc

27 files changed

Lines changed: 103 additions & 1745 deletions

‎website/docs/doc/GeneralUpdate.Bowl.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -417,4 +417,4 @@ MyApp/
417417

418418
- [Bowl 示例代码](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Bowl)
419419
- [GeneralUpdate 仓库](https://github.com/GeneralLibrary/GeneralUpdate)
420-
- [Dump 指南](../guide/Dump.md)
420+
- [Dump 指南](../guide/Dump)

‎website/docs/doc/GeneralUpdate.Core.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ sidebar_position: 5
143143
| `Cancel()` | 无 | `void` | UI 中提供"取消更新"按钮 | 触发内部 `CancellationTokenSource` |
144144
| `SetConfig(UpdateRequest)` | `configInfo` — 更新配置对象 | `GeneralUpdateBootstrap` | 主程序内显式配置更新参数 | 会调用 `Validate()` 检查关键字段 |
145145
| `SetConfig(string)` | `filePath` — JSON 配置文件路径 | `GeneralUpdateBootstrap` | 从文件读取更新配置 | 支持相对路径和绝对路径；UTF-8 JSON 格式 |
146-
| `SetSource(...)` | `updateUrl`, `appSecretKey`, `reportUrl?`, `scheme?`, `token?` | `GeneralUpdateBootstrap` | 轻配置入口，配合 manifest 使用 | 只提供服务端入口和密钥，身份信息由 manifest 补齐 |
146+
| `SetSource(...)` | `updateUrl`, `appSecretKey`, `reportUrl?`, `scheme?`, `token?`, `authScheme?`, `basicUsername?`, `basicPassword?`, `installPath?` | `GeneralUpdateBootstrap` | 轻配置入口，配合 manifest 使用 | 只提供服务端入口和密钥，身份信息由 manifest 补齐；支持 HMAC / Bearer / Basic 多种认证方式 |
147147
| `SetOption(Option<T>, T)` | `option` — 选项键, `value` — 选项值 | `GeneralUpdateBootstrap` | 设置运行时选项 | 传入 `null` 给可空选项会移除当前设置 |
148148
| `UseDiffPipeline(Action<DiffPipelineBuilder>)` | `configure` — 差分管道配置委托 | `GeneralUpdateBootstrap` | 替换或调整差分补丁管道 | 未调用时使用默认配置 |
149149
| `AddListenerUpdateInfo(...)` | `EventHandler<UpdateInfoEventArgs>` | `GeneralUpdateBootstrap` | 接收服务端版本信息 | 无更新时也会触发（`Info.Code = 404`） |
@@ -197,6 +197,9 @@ sidebar_position: 5
197197
| `SetDriverDirectory(string)` | `path` | `UpdateRequestBuilder` | 设置驱动目录 | — |
198198
| `SetScheme(string)` | `scheme` | `UpdateRequestBuilder` | 设置认证方案 | — |
199199
| `SetToken(string)` | `token` | `UpdateRequestBuilder` | 设置认证令牌 | — |
200+
| `SetAuthScheme(AuthScheme)` | `authScheme` — 认证方案枚举 | `UpdateRequestBuilder` | 设置认证方案（Hmac / Bearer / ApiKey / Basic） | 默认 `Hmac` |
201+
| `SetBasicUsername(string)` | `username` | `UpdateRequestBuilder` | 设置 Basic 认证用户名 | 需配合 `SetAuthScheme(AuthScheme.Basic)` |
202+
| `SetBasicPassword(string)` | `password` | `UpdateRequestBuilder` | 设置 Basic 认证密码 | 需配合 `SetAuthScheme(AuthScheme.Basic)` |
200203
| `SetFiles(List<string>)` | `files` | `UpdateRequestBuilder` | 设置跳过文件列表 | — |
201204
| `SetFormats(List<string>)` | `formats` | `UpdateRequestBuilder` | 设置跳过扩展名列表 | — |
202205
| `SetDirectories(List<string>)` | `dirs` | `UpdateRequestBuilder` | 设置跳过目录列表 | — |
@@ -1007,5 +1010,5 @@ var failedVersion = Environments.Get("UpgradeFail");
10071010
- [GeneralUpdate 仓库](https://github.com/GeneralLibrary/GeneralUpdate)
10081011
- [Samples 示例代码](https://github.com/GeneralLibrary/GeneralUpdate-Samples)
10091012
- [GeneralUpdate.Tools](https://github.com/GeneralLibrary/GeneralUpdate.Tools)
1010-
- [入门实战手册](../quickstart/Beginner%20cookbook.md)
1011-
- [组件文档](./GeneralUpdate.Core.md)
1013+
- [入门实战手册](../quickstart/Beginner%20cookbook)
1014+
- [组件文档](./GeneralUpdate.Core)

‎website/docs/doc/GeneralUpdate.Differential.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ sidebar_position: 6
1010

1111
### 1.1 组件概述
1212

13-
**GeneralUpdate.Differential** 是 GeneralUpdate 的二进制差分组件，专注解决"一个旧文件 + 一个补丁文件 = 一个新文件"的问题。它提供可替换的文件级差分算法（BSDIFF 4.0 / Streaming HDiff）、补丁压缩抽象（BZip2 / Deflate / Brotli 预留）和 BSDIFF 兼容补丁读写能力。
13+
**GeneralUpdate.Differential** 是 GeneralUpdate 的二进制差分组件，专注解决"一个旧文件 + 一个补丁文件 = 一个新文件"的问题。它提供可替换的文件级差分算法（BSDIFF 4.0 / Streaming HDiff）、补丁压缩抽象（BZip2 / Deflate，源码中预留 .NET 6+ Brotli）和 BSDIFF 兼容补丁读写能力。
1414

1515
目录级对比、批量补丁生成、并行调度、删除文件处理和更新流程编排由 `GeneralUpdate.Core` 的 `DiffPipeline` 或 `GeneralUpdate.Tools` 承担。
1616

@@ -21,7 +21,7 @@ sidebar_position: 6
2121
| 文件级差分生成 | `CleanAsync(oldFile, newFile, patchFile)` — 对比新旧文件生成 `.patch` 补丁 |
2222
| 文件级差分应用 | `DirtyAsync(oldFile, newFile, patchFile)` — 旧文件 + 补丁 → 新文件 |
2323
| 可替换差分算法 | `BsdiffDiffer`（BSDIFF 4.0，后缀排序）和 `StreamingHdiffDiffer`（块哈希索引） |
24-
| 可替换压缩格式 | BZip2 (0x00)、Deflate (0x01)，源码中预留 .NET 6+ Brotli (0x02) |
24+
| 可替换压缩格式 | BZip2 (0x00)、Deflate (0x01)，源码中通过 `#if NET6_0_OR_GREATER` 条件编译预留 Brotli (0x02) |
2525
| BSDIFF 兼容格式 | 写入 33 字节扩展头（32 字节 BSDIFF40 + 1 字节压缩格式），兼容 32 字节旧头 |
2626
| 线程安全 | 内置 differ 和压缩提供器均支持并发调用 |
2727

@@ -93,7 +93,7 @@ Differential 本身是底层库，不提供配置类。所有参数通过构造
9393
| --- | --- | --- | --- |
9494
| `BZip2CompressionProvider` | `0x00` | 完全可用 | BSDIFF 旧补丁兼容，解压成本较高 |
9595
| `DeflateCompressionProvider` | `0x01` | 完全可用 | 解压速度更友好，适合客户端批量应用 |
96-
| `BrotliCompressionProvider` | `0x02` | 仅 .NET 6+ 编译（源码预留） | 生产不建议使用 |
96+
| `BrotliCompressionProvider` | `0x02` | 仅 .NET 6+ 编译（源码中为完整实现，通过 `#if NET6_0_OR_GREATER` 条件编译） | 当前 `netstandard2.0` 包中不包含，生产不建议使用 |
9797

9898
### 3.2 实例方法
9999

@@ -363,5 +363,5 @@ await new GeneralUpdateBootstrap()
363363

364364
- [GeneralUpdate 仓库](https://github.com/GeneralLibrary/GeneralUpdate)
365365
- [Samples 差分示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Hub/Samples/DifferentialSample.cs)
366-
- [Core DiffPipeline 文档](GeneralUpdate.Core.md)
367-
- [Tools 打包指南](../guide/Packaging.md)
366+
- [Core DiffPipeline 文档](GeneralUpdate.Core)
367+
- [Tools 打包指南](../guide/Packaging)

‎website/docs/doc/GeneralUpdate.Drivelution.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -554,4 +554,4 @@ GeneralTracer.SetTracingEnabled(true);
554554

555555
- [驱动更新示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Hub/Samples/ImDiskQuickInstallSample.cs)
556556
- [GeneralUpdate 仓库](https://github.com/GeneralLibrary/GeneralUpdate)
557-
- [GeneralUpdate.Drivelution 组件文档](../doc/GeneralUpdate.Drivelution.md)
557+
- [GeneralUpdate.Drivelution 组件文档](../doc/GeneralUpdate.Drivelution)

‎website/docs/doc/GeneralUpdate.Extension.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -676,4 +676,4 @@ report-extension_1.0.0.zip
676676

677677
- [扩展管理示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/tree/main/src/Hub/Samples/ExtensionSample.cs)
678678
- [GeneralUpdate 仓库](https://github.com/GeneralLibrary/GeneralUpdate)
679-
- [打包指南](../guide/Packaging.md)
679+
- [打包指南](../guide/Packaging)

‎website/docs/doc/UpgradeHub.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -363,4 +363,4 @@ await new GeneralClientBootstrap()
363363

364364
- **示例代码：** [查看 GitHub 示例](https://github.com/GeneralLibrary/GeneralUpdate-Samples/blob/main/src/Push/Program.cs)
365365
- **主仓库：** [GeneralUpdate 项目](https://github.com/GeneralLibrary/GeneralUpdate)
366-
- **相关组件：** [GeneralUpdate.Core](./GeneralUpdate.Core.md) | [GeneralUpdate.Core](./GeneralUpdate.Core.md)
366+
- **相关组件：** [GeneralUpdate.Core](./GeneralUpdate.Core) | [GeneralUpdate.Core](./GeneralUpdate.Core)

‎website/docs/guide/FAQ.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -332,7 +332,7 @@ await new GeneralClientBootstrap()
332332

333333
## 相关资源
334334

335-
- **[GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)** — 核心更新引擎
336-
- **[入门实战手册](../quickstart/Beginner%20cookbook.md)** — 从零跑通更新闭环
337-
- **[GeneralUpdate.Tools](../quickstart/GeneralUpdate.PacketTool.md)** — 打包工具
338-
- **[GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl.md)** — 崩溃监控与回滚
335+
- **[GeneralUpdate.Core](../doc/GeneralUpdate.Core)** — 核心更新引擎
336+
- **[入门实战手册](../quickstart/Beginner%20cookbook)** — 从零跑通更新闭环
337+
- **[GeneralUpdate.Tools](../quickstart/GeneralUpdate.PacketTool)** — 打包工具
338+
- **[GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl)** — 崩溃监控与回滚

‎website/docs/guide/Packaging.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ await new GeneralUpdateBootstrap()
120120
**避免 C 盘权限问题：**
121121

122122
- 建议默认安装到 `%LOCALAPPDATA%` 而非 `C:\Program Files\`
123-
- 如必须安装在 C 盘，参考 [权限指南](./Permission.md) 配置注册表降权
123+
- 如必须安装在 C 盘，参考 [权限指南](./Permission) 配置注册表降权
124124

125125
**Windows 发布命令：**
126126

@@ -280,6 +280,6 @@ jobs:
280280
## 相关资源
281281

282282
- **[GeneralUpdate.Tools](../quickstart/GeneralUpdate.PacketTool)** — 补丁包和配置生成工具
283-
- **[权限指南](./Permission.md)** — Windows UAC 权限处理
284-
- **[入门实战手册](../quickstart/Beginner%20cookbook.md)** — 从零跑通更新闭环
285-
- **[GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)** — 核心更新引擎架构
283+
- **[权限指南](./Permission)** — Windows UAC 权限处理
284+
- **[入门实战手册](../quickstart/Beginner%20cookbook)** — 从零跑通更新闭环
285+
- **[GeneralUpdate.Core](../doc/GeneralUpdate.Core)** — 核心更新引擎架构

‎website/docs/quickstart/Beginner cookbook.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,12 @@ title: 入门实战手册
1111

1212
| 角色 | 在样例中的位置 | 负责什么 | 深入阅读 |
1313
| --- | --- | --- | --- |
14-
| Hub | `src\Hub` | 交互式示例浏览器，通过菜单选择并运行各类更新场景 | [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md) |
15-
| Server | `src\Server` | 返回版本信息、接收更新报告、提供补丁下载 | [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md) |
16-
| Packet | `src\Server\wwwroot\packages` | 可下载的 `.zip` 更新包和 `versions.json` 元数据 | [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md) |
17-
| Tools | GeneralUpdate.Tools 仓库 | 生成补丁包、Hash、OSS 清单、manifest 和仿真报告 | [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md) |
18-
| Bowl | Hub Samples 中集成 | 监控进程异常并导出失败信息 | [GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl.md) |
19-
| Differential | Hub Samples + Core 默认集成 | 对 old/new 文件生成差分，并在更新阶段应用 | [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential.md) |
14+
| Hub | `src\Hub` | 交互式示例浏览器，通过菜单选择并运行各类更新场景 | [GeneralUpdate.Core](../doc/GeneralUpdate.Core) |
15+
| Server | `src\Server` | 返回版本信息、接收更新报告、提供补丁下载 | [GeneralUpdate.Core](../doc/GeneralUpdate.Core) |
16+
| Packet | `src\Server\wwwroot\packages` | 可下载的 `.zip` 更新包和 `versions.json` 元数据 | [GeneralUpdate.Tools](./GeneralUpdate.PacketTool) |
17+
| Tools | GeneralUpdate.Tools 仓库 | 生成补丁包、Hash、OSS 清单、manifest 和仿真报告 | [GeneralUpdate.Tools](./GeneralUpdate.PacketTool) |
18+
| Bowl | Hub Samples 中集成 | 监控进程异常并导出失败信息 | [GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl) |
19+
| Differential | Hub Samples + Core 默认集成 | 对 old/new 文件生成差分，并在更新阶段应用 | [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential) |
2020

2121
## Step 1：准备仓库和运行环境
2222

@@ -239,11 +239,11 @@ Hub 提供了 9 个内置样例，覆盖了 GeneralUpdate 的主要使用场景
239239

240240
跑通这条链路后，建议按顺序阅读：
241241

242-
1. [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)：更新策略、事件通知、静默更新、manifest 极简配置。
243-
2. [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md)：补丁包、Hash、OSS Config、Simulation。
244-
3. [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential.md)：差分算法、并行处理和 Clean/Dirty。
245-
4. [GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl.md)：崩溃监控、备份和失败恢复。
246-
5. [GeneralUpdate.Tools](./GeneralUpdate.PacketTool.md)：补丁包、Hash、OSS Config、Simulation。
242+
1. [GeneralUpdate.Core](../doc/GeneralUpdate.Core)：更新策略、事件通知、静默更新、manifest 极简配置。
243+
2. [GeneralUpdate.Tools](./GeneralUpdate.PacketTool)：补丁包、Hash、OSS Config、Simulation。
244+
3. [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential)：差分算法、并行处理和 Clean/Dirty。
245+
4. [GeneralUpdate.Bowl](../doc/GeneralUpdate.Bowl)：崩溃监控、备份和失败恢复。
246+
5. [GeneralUpdate.Tools](./GeneralUpdate.PacketTool)：补丁包、Hash、OSS Config、Simulation。
247247

248248
## Sample UI
249249

‎website/docs/quickstart/GeneralUpdate.PacketTool.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,7 @@ dotnet run --project GeneralUpdate.Tools.csproj
144144

145145
- Extension Host 调用 `ExtensionManager.QueryRemoteExtensionsAsync(...)` 获取扩展列表
146146
- 安装时下载 ZIP，读取 `manifest.json` 进行兼容性检查和依赖解析
147-
- 详见 [GeneralUpdate.Extension](../doc/GeneralUpdate.Extension.md)
147+
- 详见 [GeneralUpdate.Extension](../doc/GeneralUpdate.Extension)
148148

149149
---
150150

@@ -189,7 +189,7 @@ dotnet run --project GeneralUpdate.Tools.csproj
189189

190190
- 将 `oss_config.json` 上传到 OSS bucket 或静态文件服务器
191191
- OSS 客户端读取此文件发现可用版本，下载后校验 Hash
192-
- 详见 [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md) OSS 更新策略
192+
- 详见 [GeneralUpdate.Core](../doc/GeneralUpdate.Core) OSS 更新策略
193193

194194
---
195195

@@ -349,7 +349,7 @@ Generate Sample 额外输出：
349349

350350
## 关联文档
351351

352-
- [GeneralUpdate.Core](../doc/GeneralUpdate.Core.md)：Client/Upgrade 更新主流程
353-
- [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential.md)：差分算法 Clean/Dirty 模式
354-
- [GeneralUpdate.Extension](../doc/GeneralUpdate.Extension.md)：扩展包安装与版本管理
355-
- [入门实战手册](./Beginner%20cookbook.md)：从零跑通完整更新闭环
352+
- [GeneralUpdate.Core](../doc/GeneralUpdate.Core)：Client/Upgrade 更新主流程
353+
- [GeneralUpdate.Differential](../doc/GeneralUpdate.Differential)：差分算法 Clean/Dirty 模式
354+
- [GeneralUpdate.Extension](../doc/GeneralUpdate.Extension)：扩展包安装与版本管理
355+
- [入门实战手册](./Beginner%20cookbook)：从零跑通完整更新闭环

0 commit comments

Comments
 (0)