LessUp · LessUp · May 22, 2026 · May 22, 2026
diff --git a/docs/zh/algorithms/brotli.md b/docs/zh/algorithms/brotli.md
@@ -6,6 +6,14 @@ Brotli 常用于 Web 内容压缩，尤其适合静态文本资源。它在压
 
 Brotli 结合字典、上下文建模和熵编码，并内置静态字典来改善常见文本内容的压缩效果。
 
+## 为什么它在 Web 文本上常见
+
+Brotli 的优势很大程度来自它对文本场景的优化：
+
+- 针对常见词片段和模式有静态字典。
+- 对 HTML、CSS、JS 这类结构化文本通常更友好。
+- 在“预压缩静态资源”场景里，压缩慢一点往往可以接受。
+
 ## 工程取舍
 
 | 维度 | 特点 |
@@ -16,12 +24,29 @@ Brotli 结合字典、上下文建模和熵编码，并内置静态字典来改
 | 内存 | 依质量级别变化 |
 | 流式 | 支持 |
 
+## 常见工程特征
+
+- 很适合在构建阶段提前压好静态资源。
+- 在动态实时压缩场景里，要谨慎评估高级别开销。
+- 与 Web 分发、CDN、浏览器生态结合较紧密。
+
 ## 适用场景
 
 - Web 静态资源
 - 文本内容分发
 - 对传输体积敏感的 HTTP 场景
 
+## 调参时通常先看什么
+
+1. 是离线预压缩还是在线实时压缩。
+2. 质量级别是否值得拉高。
+3. 资源类型是否确实偏文本而不是二进制块数据。
+
+## 使用时的常见坑
+
+- 把高质量级别直接用在实时请求路径。
+- 用它去处理本就不适合文本字典优化的数据，再得出“Brotli 不行”的结论。
+
 ## C++ 示例
 
 查看 [Brotli C++ 示例](/zh/examples/brotli)。
diff --git a/docs/zh/algorithms/bsc.md b/docs/zh/algorithms/bsc.md
@@ -6,6 +6,17 @@ BSC 是一个适合学习块排序和上下文建模思想的压缩库。它的
 
 BSC 通常围绕块级处理、排序变换和后续编码展开，让相似上下文聚集后再压缩。
 
+## 为什么它适合拿来学习
+
+和很多“直接把重复找出来”的库不同，BSC 更容易让人看到这样一种思路：
+
+```text
+先通过变换让数据局部结构更明显
+  -> 再交给后续模型和编码处理
+```
+
+它非常适合帮助建立“压缩不只是找重复，也可以先重排数据”的认知。
+
 ## 工程取舍
 
 | 维度 | 特点 |
@@ -16,12 +27,24 @@ BSC 通常围绕块级处理、排序变换和后续编码展开，让相似上
 | 内存 | 块大小越大占用越高 |
 | 流式 | 更偏块处理 |
 
+## 常见工程特征
+
+- 对块大小比较敏感，块越大通常越有利于压缩率，但也越吃内存。
+- 更适合离线处理和实验，而不是极低延迟路径。
+- 在工程上经常需要额外关注构建方式和平台适配。
+
 ## 适用场景
 
 - 学习块排序压缩
 - 对特定数据集做实验性比较
 - 离线批处理
 
+## 使用时的常见坑
+
+- 把它当作“通用默认算法”通常不合适。
+- 忽略块大小带来的内存影响，会低估运行成本。
+- 在没有真实数据集验证前，很难单靠直觉判断它是否优于其他库。
+
 ## C++ 示例
 
 查看 [BSC C++ 示例](/zh/examples/bsc)。如果当前平台无法自动构建 BSC，示例工程会把它作为可选目标处理。
diff --git a/docs/zh/algorithms/lz4.md b/docs/zh/algorithms/lz4.md
@@ -6,6 +6,18 @@ LZ4 是一个以速度为核心目标的无损压缩算法，常用于实时系
 
 LZ4 使用轻量级字典匹配，格式和实现都偏向快速压缩与快速解压。
 
+## 可以怎样理解它的设计哲学
+
+LZ4 的重点不是“把每一个字节都压到极致”，而是：
+
+```text
+尽快找到可接受的重复
+  -> 尽快编码
+  -> 尽快恢复
+```
+
+因此它常常在系统热路径、缓存、流式传输、临时中间结果里非常有价值。
+
 ## 工程取舍
 
 | 维度 | 特点 |
@@ -16,13 +28,30 @@ LZ4 使用轻量级字典匹配，格式和实现都偏向快速压缩与快速
 | 内存 | 低 |
 | 流式 | 支持 |
 
+## 常见工程特征
+
+- 实现简单，部署和调试成本较低。
+- 解压通常也非常快，这对读路径很重要。
+- 更像“用 CPU 换最小延迟”，而不是“用 CPU 换更高压缩率”。
+
 ## 适用场景
 
 - 实时传输
 - 内存缓存
 - 日志热路径
 - 对延迟敏感的数据处理
 
+## 调参时通常先看什么
+
+1. 是否直接用默认快速模式。
+2. 是否需要 frame 格式而不是裸 block 接口。
+3. 数据本身是否值得压缩；对高度随机数据它往往意义不大。
+
+## 使用时的常见坑
+
+- 把它和高压缩率算法直接比“最终文件大小”，容易误判它的定位。
+- 忽略整体延迟收益，只盯着压缩率，会错过它最核心的价值。
+
 ## C++ 示例
 
 查看 [LZ4 C++ 示例](/zh/examples/lz4)。
diff --git a/docs/zh/algorithms/lzma.md b/docs/zh/algorithms/lzma.md
@@ -6,6 +6,16 @@ LZMA 常见于 xz/7z 生态，追求较高压缩率，代价是压缩速度和
 
 LZMA 使用大窗口字典匹配和范围编码，并通过上下文建模提升压缩率。
 
+## 可以怎样理解它的内部流程
+
+LZMA 的思路更偏“强模型”：
+
+```text
+更深的匹配搜索 -> 更大的窗口 -> 更强的概率建模 -> 范围编码
+```
+
+这也是它常常能拿到较高压缩率，但压缩端更慢、内存更高的原因。
+
 ## 工程取舍
 
 | 维度 | 特点 |
@@ -16,12 +26,30 @@ LZMA 使用大窗口字典匹配和范围编码，并通过上下文建模提升
 | 内存 | 可较高 |
 | 流式 | liblzma 支持流式接口 |
 
+## 常见工程特征
+
+- 经常出现在 `xz` / `7z` 这类偏归档生态中。
+- 对窗口大小、字典大小、预设级别比较敏感。
+- 更适合“写一次、读多次，但写可以慢”的任务。
+
 ## 适用场景
 
 - 软件包发布
 - 长期归档
 - 对压缩率更敏感而非压缩速度的场景
 
+## 调参时通常先看什么
+
+1. **预设级别**：先决定压缩率与资源消耗的大致区间。
+2. **字典 / 窗口大小**：越大通常越有利于长距离重复，但也更耗内存。
+3. **流式还是一次性 buffer API**：取决于集成方式和数据规模。
+
+## 使用时的常见坑
+
+- 在内存受限环境下直接使用高预设，容易让体验失控。
+- 把它用于极度延迟敏感路径，通常得不偿失。
+- 只看压缩率，不看压缩时间，容易在 CI、构建链路、离线任务里造成明显拖慢。
+
 ## C++ 示例
 
 查看 [LZMA C++ 示例](/zh/examples/lzma)。
diff --git a/docs/zh/algorithms/zlib.md b/docs/zh/algorithms/zlib.md
@@ -6,6 +6,14 @@ zlib 是 DEFLATE 生态中最常见的工程库之一。它不是最新的算法
 
 DEFLATE 结合 LZ77 字典匹配和 Huffman 编码。zlib 提供稳定、广泛可用的接口。
 
+## 为什么它到现在还很重要
+
+很多时候，zlib 的价值不在于“最强”，而在于“几乎到处都能用”：
+
+- 大量现有协议、格式和工具默认支持它。
+- 构建依赖轻，跨平台历史长。
+- 对很多业务来说，兼容性和稳定性比极限指标更重要。
+
 ## 工程取舍
 
 | 维度 | 特点 |
@@ -16,12 +24,29 @@ DEFLATE 结合 LZ77 字典匹配和 Huffman 编码。zlib 提供稳定、广泛
 | 内存 | 较低 |
 | 流式 | 支持 |
 
+## 常见工程特征
+
+- 适合与 gzip / zlib 包装格式生态协同工作。
+- 既可以做简单 buffer 压缩，也可以做流式压缩。
+- 是许多“先上一个可靠方案”场景里的保守默认值。
+
 ## 适用场景
 
 - 需要广泛兼容的文件或网络格式
 - gzip/zlib 生态集成
 - 老系统和跨平台组件
 
+## 调参时通常先看什么
+
+1. 压缩级别是否需要从默认值提高。
+2. 是否需要流式接口配合网络或文件读写。
+3. 是否真正需要兼容 gzip / zlib 外层格式。
+
+## 使用时的常见坑
+
+- 用它和 Brotli、ZSTD 比较时忘记它的兼容性红利。
+- 认为“不是最新算法就不值得用”，忽略了部署现实。
+
 ## C++ 示例
 
 查看 [zlib C++ 示例](/zh/examples/zlib)。
diff --git a/docs/zh/algorithms/zstd.md b/docs/zh/algorithms/zstd.md
@@ -6,6 +6,16 @@ Zstandard 是一个面向通用场景的现代无损压缩算法，目标是在
 
 ZSTD 结合字典匹配和熵编码。它支持多个压缩级别，低级别适合实时数据管道，高级别适合归档。
 
+## 可以怎样理解它的内部流程
+
+可以把 ZSTD 粗略看成：
+
+```text
+查找重复片段 -> 生成序列 -> 熵编码 -> 打包成 frame
+```
+
+它的优势不只是“压得不错”，而是允许你在一套生态里，从偏实时到偏归档做连续调节。
+
 ## 工程取舍
 
 | 维度 | 特点 |
@@ -16,13 +26,31 @@ ZSTD 结合字典匹配和熵编码。它支持多个压缩级别，低级别适
 | 内存 | 随压缩级别增加 |
 | 流式 | 支持 |
 
+## 常见工程特征
+
+- 支持 frame 格式，适合文件和流式处理。
+- 支持字典训练，特别适合大量相似小对象。
+- 低级别常被用作系统默认压缩方案，因为总体平衡感很好。
+
 ## 适用场景
 
 - 日志压缩
 - 数据管道
 - 本地缓存
 - 可调压缩级别的归档任务
 
+## 调参时通常先看什么
+
+1. **压缩级别**：最直接的速度 / 压缩率旋钮。
+2. **是否启用字典**：对小文本、短消息收益可能非常大。
+3. **是否流式**：会影响缓冲区和集成方式。
+
+## 使用时的常见坑
+
+- 用默认级别测一次就下结论，容易低估它的可调空间。
+- 用已经压缩过的数据做对比，结果常常没有参考价值。
+- 忽略字典训练，会错过它在“小而相似的数据”上的优势。
+
 ## C++ 示例
 
 查看 [ZSTD C++ 示例](/zh/examples/zstd)。
diff --git a/docs/zh/comparisons/matrix.md b/docs/zh/comparisons/matrix.md
@@ -11,9 +11,27 @@
 | zlib | 中 | 中 | 中到快 | 低 | 很高 | 兼容性优先 |
 | Brotli | 高 | 中到慢 | 快 | 中 | 高 | Web 文本资源 |
 
+## 这些列应该怎么理解
+
+- **压缩率**：不是绝对值，而是相对直觉；不同数据集差异非常大。
+- **压缩速度**：更多影响写链路、构建链路、离线任务。
+- **解压速度**：更多影响读链路、服务启动、请求响应。
+- **兼容性**：不仅是“能不能用”，还包括周边工具、协议和默认支持程度。
+
 ## 阅读方式
 
 - 如果解压速度最重要，优先比较 LZ4 和 ZSTD。
 - 如果压缩率最重要，优先比较 LZMA、ZSTD 高级别和 Brotli。
 - 如果生态兼容性最重要，优先考虑 zlib。
 - 如果目标是学习压缩变换，BSC 值得单独研究。
+
+## 不同算法最容易被忽略的价值
+
+| 算法 | 容易被忽略的点 |
+| --- | --- |
+| ZSTD | 它的价值不只是“平衡”，而是可调范围很大 |
+| LZMA | 适合归档，不适合所有热路径 |
+| BSC | 更适合作为学习与实验对象，而非默认基础设施组件 |
+| LZ4 | 真正优势往往体现在系统延迟而不是压缩比 |
+| zlib | 兼容性本身就是工程价值 |
+| Brotli | 更适合文本和静态分发，不代表所有数据都优 |
diff --git a/docs/zh/comparisons/scenarios.md b/docs/zh/comparisons/scenarios.md
@@ -4,21 +4,45 @@
 
 优先考虑 ZSTD 或 LZ4。ZSTD 提供更好的压缩率和可调级别，LZ4 更适合极低延迟路径。
 
+如果日志需要长期保留但也经常回放，ZSTD 往往是更稳的折中；如果日志只是短期缓冲或跨进程传递，LZ4 更容易获得低延迟收益。
+
 ## 长期归档
 
 优先考虑 LZMA 或 ZSTD 高级别。如果数据偏 Web 文本资源，也可以比较 Brotli。
 
+这里最重要的是确认“写慢一点是否可以接受”。归档任务通常允许更慢压缩，但恢复时间和内存占用仍然要在演练中验证。
+
 ## Web 内容
 
 优先考虑 Brotli 和 zlib。Brotli 更适合现代浏览器环境，zlib/gzip 兼容性更强。
 
+常见做法不是“二选一”，而是保留 gzip 兼容路径，同时为支持 Brotli 的客户端提供更小的资源。
+
 ## 嵌入式或低资源环境
 
 优先关注内存和解压实现复杂度。LZ4 和 zlib 通常比高压缩率算法更容易控制资源。
 
+如果设备端主要负责解压而不是压缩，那么解压代码复杂度、二进制体积和峰值内存常常比理论压缩率更重要。
+
+## 小文件和大量相似对象
+
+这类场景往往值得优先考虑 ZSTD 的字典能力，或者至少专门测试“是否该引入字典训练”。  
+单纯比较“不开字典时的大文件 benchmark”常常会错过真实收益点。
+
 ## 学习算法思想
 
 - 字典匹配：LZ4、zlib、ZSTD、LZMA
 - 熵编码：zlib、ZSTD、Brotli
 - 上下文建模：LZMA、Brotli
 - 块排序：BSC
+
+## 一个简化的场景决策表
+
+| 场景 | 更值得先试的算法 | 主要原因 |
+| --- | --- | --- |
+| 热路径、低延迟 | LZ4 | 极快 |
+| 通用后端服务 | ZSTD | 综合最平衡 |
+| 归档 / 发布包 | LZMA、ZSTD | 更重视压缩率 |
+| 浏览器静态资源 | Brotli、zlib | 文本优化 + 兼容性 |
+| 老系统 / 强兼容 | zlib | 生态成熟 |
+| 学习变换类思路 | BSC | 便于理解块排序 |
diff --git a/docs/zh/examples/cpp-overview.md b/docs/zh/examples/cpp-overview.md
@@ -24,6 +24,29 @@ ratio=...
 verified=true
 ```
 
+## 这些示例刻意保持“最小闭环”
+
+它们不是性能 benchmark，也不是完整 SDK 封装，而是用来帮助你看清三件事：
+
+1. 一个压缩库最基础的 buffer API 长什么样。
+2. 压缩和解压分别需要哪些输入 / 输出缓冲区。
+3. 为什么任何学习示例都应该显式校验 round-trip 正确性。
+
+## 阅读示例时建议关注什么
+
+| 关注点 | 说明 |
+| --- | --- |
+| 输入如何读入 | 示例统一从文件读入字节数组 |
+| 压缩缓冲区如何分配 | 多数库都需要先估算上界 |
+| 解压输出大小如何确定 | 有的库能从 frame 获取，有的需要调用方自己知道 |
+| 错误码如何处理 | 示例统一在失败时直接抛出异常 |
+| 结果如何验证 | 统一比较原始字节和恢复字节 |
+
+## 为什么 BSC 还是占位示例
+
+当前仓库已经支持把 BSC 作为可选目标构建，但文档仍然把它当作“学习构建接入和占位接口”的示例。  
+原因不是它不重要，而是不同平台对上游构建和链接方式更敏感，后续更适合基于真实目标平台继续深化。
+
 ## 示例列表
 
 - [ZSTD](./zstd)