今日实践手记：两个文档 Issue 背后的阅读笔记（鸿蒙月光邮局 / AI 面试天团）

今天在华为云开发者成长中心做日常任务时，顺手给两个实践中心的代码仓各提了一个文档建议 Issue，记录一下发现过程。

一、鸿蒙月光邮局：字体接口要求 API 18，但兼容声明是 API 12

月光邮局（HarmonyOS-APP-Moonlight-Post）是鸿蒙开发实践中心的中秋祝福短片生成案例。今天给它点 Star 后读了 README，发现“工程配置”一节写明：targetSdkVersion 为 26.0.0，compatibleSdkVersion 声明为 5.0.0（12）；同一节又写“本项目使用的字体接口存在 API 18 要求，API 12–17 尚未验证”。而“开始之前”只要求“可调试的 HarmonyOS 手机模拟器或真机”，没有给出最低 API 提示；“检查记录与已知限制”里也把“低版本兼容性”列为待验证项。

我提的 Issue 建议：在“开始之前”补一行最低设备要求（例如建议 API 18 及以上，或明确 API 12–17 暂不保证），并在“检查记录”里登记后续验证结论。这样新手在 API 12–17 的设备上遇到字体问题时，至少知道先去看版本要求。

二、AI 面试天团：飞书配置是“可选”，验证清单却没标

第二个 Issue 提给了 AI Agent 开发实践中心的 ai-interview-swarm 仓。它的《AI 面试天团 — 快速部署指南》第 3 节“环境前提”写着“飞书企业自建应用（可选，也可用 Web 界面）”，但第 11 节“验证清单”里“飞书 enabled:true 且凭证已填”这一项没有标明“仅飞书渠道适用”，第 12 节 FAQ 的“飞书无响应”一条也一样。新手按清单逐项核对时，很容易以为飞书配置是必做项，白白多花时间去注册企业自建应用。

我的建议是：在第 11、12 节的相关条目后补“（仅使用飞书渠道时）”，并在第 7 节开头说明“本节仅在使用飞书渠道时需要；仅用 Web 界面可跳过”。

总结

两个 Issue 都是“文档少了一句限定词”的小问题，改动不到三行字，但能省下新手不少试错时间。提 Issue 时顺手把原文出处和建议写法都贴上，维护者处理起来也更快。