鸿蒙三方库适配读懂 `README_zh.md`：中文适配说明里每段在说什么？

前言

在 OpenHarmony / lycium 三方库目录里，README_zh.md 通常承担 「给中文读者看的说明书」 ：用自然语言说明 这是什么库、编出来在哪、怎么编、怎么测 ，不必像 HPKBUILD 那样写成 Shell 脚本。

本仓库的 thirdparty/AES/README_zh.md 对应 包名 AES、上游 tiny-AES-c 。下面按 原文章节顺序 ，把 每段话的用途、背后的约定、和别的文件怎么对照 讲清楚，方便新人 5 分钟建立全局印象 ，需要细节时再翻 HPKBUILD 或 docs/HPKBUILD解读.md。

整体结构一览（对应原文标题）

原文章节	主要回答的问题
简介	谁家的库、叫什么、能干什么、和上游差在哪、适配时改了什么。
产物与用法	编完文件在哪、应用怎么链接、头文件和宏要注意什么。
依赖说明	还要不要别的库、构建机要装什么。
编译	一条命令怎么触发构建。
测试	为什么在设备上测、进哪个目录、ctest 还是直接跑二进制。
参考	上游链接、lycium 模板去哪看。

标题：`AES（tiny-AES-c）OpenHarmony 适配说明`

通俗理解：

AES 是 lycium 里的名字 （目录名、pkgname、./build.sh AES）。
tiny-AES-c 是 GitHub 上的上游项目名 。
括号把两者绑在一起，避免读者以为「AES」是 OpenSSL 那种全家桶，这里只是 tiny-AES-c 的 OHOS 适配包。

「简介」在说什么？

原文三段信息可以拆成：

溯源

上游是 kokke/tiny-AES-c ，版本 v1.0.0 。读者知道 issue、license、算法说明 要去上游仓库看。
能力边界
纯 C 、默认 AES-128 ，模式 ECB / CBC / CTR 。文档里提醒：AES192/AES256 要在 aes.h 里改宏 ，本适配 没有替你改 密钥长度------意思是 默认行为与上游一致，别误以为 OHOS 版自动开了 256。
适配做了什么

上游 CMake 的 include 路径错了 ，也 没配好安装和测试 。所以我们在 HPKBUILD 的 prepare() 里 重写 CMake ，得到 静态库 libtiny-aes.a 、tiny_aes_test ，并挂上 CTest （和 HPKCHECK 里 ctest 对应）。

和 HPKBUILD 的关系： 简介是结论；HPKBUILD 是实现。读不懂简介里的某句时，去 docs/HPKBUILD解读.md 找同名概念即可。

「产物与用法」在说什么？

那张路径表

$LYCIUM_ROOT ：一般指 你本机 lycium 工程根目录 （由 lycium/build.sh 设置）。$ARCH ：armeabi-v7a 或 arm64-v8a。

原文「类型」	实际文件	用途
静态库	`lib/libtiny-aes.a`	链接进你的 native 模块。
头文件	`include/aes.h`	`#include` 与 API 声明。
测试程序	`bin/tiny_aes_test`	设备上跑自测（可选拷贝）。

路径模式 usr/AES/<ARCH>/... 是 lycium 约定俗成的安装树 ，和 HPKBUILD 的 package() 一致。

链接示例那几行

-I / -L / -ltiny-aes：

编译器找 头文件 、链接器找 libtiny-aes.a （-l 名字是 tiny-aes ，对应 libtiny-aes.a ）。
把 $LYCIUM_ROOT 和 $ARCH 换成你本机真实路径即可。

关于 `ECB` / `CBC` / `CTR`

上游 aes.h 里可以用宏 开关模式 。你的工程若要用某种模式，需在 包含 aes.h 之前 或 编译参数 -D 里定义，与上游文档一致。README 里点出：test.c 在包含头文件前把三个都设为 1 ，是告诉你 官方自测默认全开，你写业务代码时可以只开需要的。

「依赖说明」在说什么？

构建依赖 ：没有「还要先编另一个 HPK 库」这种事；但要 OHOS SDK、cmake、make 等------具体以 lycium 仓库环境说明 为准。
运行时依赖 ：静态库 链进去后，不依赖再带一份 libtiny-aes.so（除非你自己又做了动态库版本，本 README 描述的是当前 HPK 产物）。

注意： 若未来 depends 里加了别的包，README_zh.md 的依赖节要同步改，否则文档会骗人。

「编译」在说什么？

就一条：在 lycium 根目录执行 ./build.sh AES。

通俗理解：

lycium 根目录 ：放 build.sh 的那一层，不是 thirdparty/AES。
AES ：必须和 thirdparty 下文件夹名 、HPKBUILD 的 pkgname 一致。

若只编部分库且带依赖，社区有时写 ./build.sh dep1 AES ；本库 无 depends ，只写 AES 即可。

「测试」在说什么？

核心就一句：交叉编出来的二进制不能在 Mac/Windows 上直接双击跑 ，要在 OpenHarmony 真机或模拟器 上跑。

原文给了两条路：

整目录推送

把 tiny-AES-c-1.0.0/$ARCH-build （和 HPKBUILD 里 builddir + arm64-v8a-build 这类目录 一致）弄到设备上，且 路径尽量和编译机一致 ，这样 CTest 配置 不容易乱。
只推测试程序

至少要把 tiny_aes_test 及其依赖（静态链上则相对简单）能在设备上跑起来。

ctest ：与 HPKCHECK 相同思路；设备上若装了 lycium-citools ，可把 PATH 配上 cmake 等 （文中 /usr/CIusr/bin 为示例）。
./tiny_aes_test ：直接跑上游自测，退出码 0 表示全过。

「无需 chmod +x」：OpenHarmony 侧常见约定，与 Linux 桌面习惯略有不同；若你环境仍报权限，再按现场策略处理。

「参考」在说什么？

上游仓库 ：算法、issue、Unlicense 全文等。
lycium 模板 ：官方 HPKBUILD / HPKCHECK 空模板，适合对比「最小长什么样」。

若要 开源合规清单 ，应看同目录 README.OpenSource （解读见 docs/README_OpenSource解读.md）。

和仓库里其它文档怎么分工？

文件	更适合谁、干什么
`README_zh.md`	使用者 / 集成方：快速知道产物路径、编译命令、上哪测。
`HPKBUILD`	维护适配的人：改下载地址、CMake、安装路径、打包。
`HPKCHECK`	CI / 设备脚本：自动跑 ctest、写 log。
`docs/HPKBUILD解读.md`	想搞懂为什么 `prepare` 要重写 CMake 、`build` 参数从哪来。
`README.OpenSource`	合规：许可证、版本、Owner、URL。

总结

README_zh.md 是 中文入口文档 ：简介交代上游与适配改动，产物与用法 给路径和链接行，依赖说明不拖别的 HPK，编译一条命令，测试强调 必须上 OHOS 设备 及 ctest / tiny_aes_test 两种方式。
读的时候记住两个名字：lycium 包名 AES vs 上游 tiny-AES-c ；记住一条路径规律：$LYCIUM_ROOT/usr/AES/$ARCH/{lib,include,bin}。
维护时：改 pkgver / 目录结构 / 测试方式 ，要同时改 README_zh.md、HPKBUILD、HPKCHECK、README.OpenSource，避免文档与脚本脱节。

若你希望 README 正文本身 再扩写（例如加「鸿蒙 PC 签名示例」或「HAP 集成链接示例」），可以在 README_zh.md 里加小节，本文解读类文档再跟一节 「扩展阅读」 指向即可。

实战案例：如何编写高质量的 README_zh.md

案例一：新增功能说明

假设你为 AES 库添加了新的加密模式，需要在 README 中说明：

markdown 复制代码

## 新增功能

### GCM 模式支持

本适配在 tiny-AES-c 基础上新增了 GCM (Galois/Counter Mode) 支持：

\`\`\`c
#include "aes.h"

// 使用 GCM 模式加密
AES_GCM_encrypt(plaintext, len, key, iv, ciphertext, tag);
\`\`\`

**注意：** GCM 模式需要额外的 16 字节空间存储认证标签。

案例二：添加性能数据

markdown 复制代码

## 性能测试

在 OpenHarmony 设备上的性能测试结果：

| 架构 | 加密速度 (MB/s) | 解密速度 (MB/s) |
| ---- | --------------- | --------------- |
| arm64-v8a | 120 | 118 |
| armeabi-v7a | 85 | 83 |

测试环境：
- 设备：OpenHarmony 4.0
- 数据块大小：4KB
- 模式：AES-128-CBC

案例三：添加故障排查

markdown 复制代码

## 常见问题

### Q: 链接时找不到 libtiny-aes.a

**A:** 检查以下几点：
1. 确认已执行 `./build.sh AES`
2. 检查库文件路径：`ls $LYCIUM_ROOT/usr/AES/arm64-v8a/lib/`
3. 确认链接参数：`-L$LYCIUM_ROOT/usr/AES/arm64-v8a/lib -ltiny-aes`

### Q: 运行测试时提示权限不足

**A:** OpenHarmony 设备上可能需要：
\`\`\`bash
chmod +x tiny_aes_test
./tiny_aes_test
\`\`\`

README_zh.md 结构最佳实践

写作原则

简洁明了：每段话控制在 3-5 行
结构清晰：使用标题和列表
示例完整：代码示例可直接运行
版本明确：说明适用的版本范围

与其他文档的配合

文档分工矩阵

文档	目标读者	主要内容	更新频率
`README_zh.md`	使用者	快速上手	版本更新时
`HPKBUILD`	维护者	构建逻辑	构建改动时
`HPKCHECK`	测试人员	测试逻辑	测试改动时
`docs/*.md`	深入学习者	详细解读	按需更新

更新同步检查清单

当修改 README_zh.md 时，检查是否需要同步更新：

常见错误与修正

错误一：路径不一致

错误示例：

markdown 复制代码

产物位于：`/usr/AES/arm64-v8a/lib/`

问题： 使用了绝对路径，不同机器上路径不同。

修正：

markdown 复制代码

产物位于：`$LYCIUM_ROOT/usr/AES/$ARCH/lib/`

错误二：版本号遗漏

错误示例：

markdown 复制代码

基于 tiny-AES-c 开发

问题： 未说明具体版本。

修正：

markdown 复制代码

基于 tiny-AES-c v1.0.0 开发

错误三：缺少环境说明

错误示例：

markdown 复制代码

执行 `./build.sh AES` 即可编译

问题： 未说明前置条件。

修正：

markdown 复制代码

前置条件：
- 已安装 OpenHarmony SDK
- 已设置 OHOS_SDK 环境变量

执行 `./build.sh AES` 即可编译

国际化考虑

中英文对照

如果需要同时维护中英文 README：

复制代码

README_zh.md  (中文)
README.md     (英文)

同步策略：

先更新主要语言的文档
再翻译到另一语言
使用相同的结构和章节名

术语对照表

中文	英文
交叉编译	cross-compilation
静态库	static library
动态库	shared library / dynamic library
头文件	header file
链接	link

验证与测试

验证 README 内容

bash 复制代码

# 检查链接是否有效
grep -o '\[.*\](.*)' README_zh.md | while read link; do
    url=$(echo $link | grep -o 'http[^)]*')
    if [ -n "$url" ]; then
        curl -sI $url | head -1
    fi
done

# 检查代码块语法
grep '```' README_zh.md | wc -l  # 应为偶数

# 检查标题层级
grep '^#' README_zh.md

测试示例代码

bash 复制代码

# 提取并测试 README 中的示例代码
# 1. 手动复制示例代码
# 2. 在测试环境中运行
# 3. 验证输出是否符合描述

鸿蒙三方库适配读懂 `README_zh.md`：中文适配说明里每段在说什么？