用 HarmonyOS Dev Assistant 做 ohpm-lint:把中心仓审核口径变成一条命令
目录
- 安装与登录 Dev Assistant
- Dev Assistant 能做什么
- 背景:一次驳回等于一轮返工
- 第一步:让它先判断该不该做
- 第二步:把四份文档变成一份 SPEC
- 第三步:让它写实现、写测试、写文档
- 成果验证:扫了 60 个热门包
- 人必须接的那部分
- 验收清单
- 参考资料
摘要:
ohpm prepublish通过,不等于能过中心仓审核。官方对「什么能上架」有成文要求,但本地没有工具检查这些要求,于是每次提交都像开盲盒。这篇记录怎么让 HarmonyOS Dev Assistant 把这件事做完:它先花 295 秒做调研、判断这个方向值不值得做,再读四份官方文档、把要求抄成一份可执行的 SPEC,接着写 36 条规则、11 组测试样本、31 个测试用例,最后自己跑了 60 个热门包的扫描。产物是
ohpm-lint——一条能在本地跑的检查命令。读完能拿到的不只是一个工具,还有一套做法:怎么把一个含糊的「要不要被拒」,拆成有官方出处、可机器检查的条目。
安装与登录 Dev Assistant
三种 IDE 都能装
按自己的环境选一个即可:
| 开发环境 | 安装方式 | 环境要求 |
|---|---|---|
| DevEco Studio | Plugins 里搜索安装;或下载离线包后 File > Settings > Plugins → 齿轮菜单 → Install Plugin from Disk… → 选插件包(无需解压) | DevEco Studio 6.1 及以上 |
| VS Code | 扩展市场搜索 HarmonyOS Dev Assistant for VS Code → Install → Trust Publisher & Install | — |
| HBuilderX | DCloud 插件市场搜索 HarmonyOS Dev Assistant 下载,按 HBuilderX 插件方式安装 | HBuilderX 5.07+、Node.js 18.x(推荐 20.x LTS) |
装好后打开插件面板(DevEco Studio 在右侧边栏,VS Code 在左侧活动栏),用已实名认证的华为开发者账号登录。未实名的账号登不进去,这是最容易卡住的一步。
本文用的是 DevEco Studio 26 + DevEco Studio 插件这条路径。
Dev Assistant 能做什么
后面的每件事都是它做的,所以先把工具交代清楚。
HarmonyOS Dev Assistant 是装在 IDE 里的 AI 助手,官方定位是编码、调试、排错、查询四类活。在实际使用里,它的工作方式是对话式的:我们在面板里说一句需求,它自己去读工程、查文档、执行命令、产出文件。人负责「说要什么」和「判断对不对」。
这件事从头到尾都是这么干的。两张截图是它在同一天里的两次工作记录:

(原图:10-调研选题.png)

(原图:11-实测实证.png)
左图是调研:一句话「调研其他值得做三方库适配贡献 ohpm 的内容,可先检索工作区有无相关调研」,它检索工作区已有文档、逐个判断是否覆盖本题,跑了 295 秒,产出 318 行调研文档。
右图是实测:让它「构造 4 个最小 HAR 实测 ohpm prepublish」,它建了四个样本、逐个跑、把结果列成表。
把这两张图放在开头,是想说明一件事:本文后面的调研、读文档、写 SPEC、写代码、写测试、跑扫描,全是它在做,人只做判断。
下面按「第一步、第二步、第三步」记录这个过程。
背景:一次驳回等于一轮返工
先把问题说准。
官方对三方库上架有成文要求:必须有哪些文件、README 里必须写什么、description 多长、license 什么格式。这些要求写在帮助中心的四个页面里,缺了会怎样也写得很清楚:上架失败。
但本地工具不检查这些:
| 官方要求(缺了会怎样) | ohpm prepublish 是否拦 |
|---|---|
必须包含 oh-package.json5、README.md、CHANGELOG.md、LICENSE,缺失即上架失败 | ❌ 不拦 |
README.md 必须含 ohpm install <包名> 或 ohpm i <包名> | ❌ 不拦 |
CHANGELOG.md 必须包含当前版本号 | ❌ 不拦 |
description 6 到 512 字符、author 必须带 email 或 url、开源包必须有 repository 和 license | ❌ 不拦 |
包内必须有 package/ 目录,.so 必须在 package/libs/,禁 .exe | ❌ 不拦 |
SemVer 格式、main 字段、3 个 SDK 字段、源码泄漏 | ✅ 拦(仅这几项) |
这张表不是我们整理的,是官方 README 自己列的对照(图1)。

(原图:07-README对比表.png)
四个最小 HAR 的实测
光看文档还不够。我们让 Dev Assistant 去实际验证:给它一句「构造 4 个最小 HAR 实测 ohpm prepublish」,它建了四个样本、逐个跑、把结果列成表。
| 构造 | ohpm prepublish 结果 |
|---|---|
缺 LICENSE + 缺 CHANGELOG | ✅ succeed(只警告源码泄漏) |
| 无 scope、无 license、无 description、无 author、无 README | ✅ succeed |
version: "1.0"(非法 SemVer) | ❌ Invalid Version |
缺 main | ❌ Field Empty Error |
四组里两组几乎什么都没填,prepublish 依然放行。 它真正拦的只有两样:SemVer 格式、关键字段为空。完整过程见图2。
这一步的意义是把假设变成事实。不先验证,很容易写出一个「我以为审核会拦」的工具,最后发现拦的东西人家根本不管。
代价不是多等几天
代价是实打实的返工:改 README、补 CHANGELOG、调 description,重新打包、重新上传、重新排队。如果是给别人用的库,还要再发一个版本号。
更麻烦的是它不可预测:不知道会不会被拒、会被哪条规则拒。这种「开盲盒」式的提交流程,是三方库开发里最消耗耐心的一环。
所以要做的事很明确:把「提交前该检查什么」从人的记忆里,挪到一条能跑的命令里。
第一步:让它先判断该不该做
动手前先回答一个问题:这个方向值不值得做?
我们给 Dev Assistant 一句话:
调研其他值得做三方库适配贡献 ohpm 的内容,可先检索工作区有无相关调研
它跑了 295 秒,产出一份 318 行的调研文档,并自己判断出哪些方向已被覆盖、哪些还是空白(过程见图1)。
调研的结论是:现成的文档要么讲「怎么把 GLES 着色器移植」(只针对单个项目),要么讲「OHPM 怎么发布」(流程层面),没有一份回答「一个包凭什么能过审」。
这就是空位。
为什么先做这一步
因为它把「我觉得应该有用」变成了「确实没人做」。
这一步的判据很简单:这个方向,已有的文档讲到哪一层?
- 如果讲的是「怎么做某个具体项目」,那是案例,不是方法——换个项目就不适用;
- 如果讲的是「流程怎么走」,那是操作手册,不解决「凭什么能过审」;
- 只有当没有任何一份文档回答核心问题时,才算空位。
按这个判据,我们筛掉了两个候选:一个是「再写一遍着色器移植」,已有文档覆盖且更完整;另一个是「OHPM 发布流程」,网上教程已经够多。剩下的空位就是这里:没人说清楚「一个包凭什么能过审」。
顺带说一件小事:这个坑是我们自己踩过的。之前发布 shaderport 时,同样缺了「权限 / 接口 / 约束与限制 / 目录结构」四项,被驳回过。所以工具的第一个用户,就是自己后面的每个包——这不是情怀,是需求真实性的保证。
第二步:把四份文档变成一份 SPEC
这一步是整件事的地基,也是最容易被跳过的。
直觉做法是「让 AI 直接写个检查工具」。这样做的结果是:规则凭印象编、级别拍脑袋定、官方文档里没写的东西也敢拦,最后工具比审核还严,反而添乱。
正确的顺序是先写 SPEC,再写实现。我们让 Dev Assistant 读四份官方文档:
三方库发布的必要文件 ohpm.openharmony.cn/#/cn/help/publishrequirefile
OHPM 发包规则汇总 ohpm.openharmony.cn/#/cn/help/publishrules
三方库名称指南 ohpm.openharmony.cn/#/cn/help/guidename
创建及发布三方库 ohpm.openharmony.cn/#/cn/help/createandpublish
读完它要做三件事:
- 把 21 条成文要求整理成结构化清单;
- 每条要求标注官方出处(形如
§7.1); - 判断每条该是什么级别。
定级原则:工具不比审核更严
第三条是整件事最关键的地方,也最不能交给 AI 自己拍板。
我们给它的约束是一句话:
官方写明「会导致上架失败」→
error;官方仅打印警告 →warn;官方用「建议」措辞或属质量建议 →warn或info。工具不比审核更严。
为什么这条这么重要?因为 error 意味着阻断发布,一旦误报就是在拦人。
所以配套还有一条硬要求:代码里每条规则必须带 officialRef,review 时逐条比对官方原话。没有官方出处的规则,不许进代码。

(原图:08-规则定级.png)
有了这条约束,后面的工作就变成机械的了:每条规则都要回答「官方在哪说过」。
第三步:让它写实现、写测试、写文档
SPEC 定完,剩下的可以整段交给它。
36 条规则的分工
规则按对象分了八组,编号就是分组前缀:
| 组 | 前缀 | 数量 | 检查什么 |
|---|---|---|---|
| 名称 | NAME | 6 | 包名格式、大小写、与 README 里的安装命令一致 |
| 版本 | VER | 3 | SemVer 格式、CHANGELOG 是否记了当前版本 |
| 元数据 | META | 13 | description 长度、author 需 email 或 url、repository、license、SDK 字段 |
| 文件 | FILE | 7 | 四件套是否存在、是否混入敏感文件 |
| 结构 | STRUCT | 3 | package/ 目录、.so 位置、禁 .exe(仅 har 模式生效) |
| 体积 | SIZE | 5 | 单包与总体积阈值 |
| 文档质量 | DOC | 1 | README 八要素(全是 warn,不冒充官方) |
| 打包 | PKG | 1 | 是否 oh-package.json5 风格 |

(原图:03-规则分布.png)
META 最多,因为元数据字段最容易漏、也最常被驳回。
一个真实矛盾:开发期和发布期结构不一样
写实现时遇到一个必须解决的问题:开发期目录没有 package/ 这一层,发布包才有。
如果开发期就用发布包规则检查,会一路误报。所以工具做了两种模式:
| 模式 | 触发条件 | 检查强度 |
|---|---|---|
dir | 传目录且不含 package/ | 开发期用,STRUCT-* 除 JSON5 外跳过 |
har | 传 .har / .tgz,或目录下有 package/ | 发布前用,全部规则生效 |
退出码要能进 CI
工具最终要给流水线用,所以退出码必须严格分三态:
ohpm-lint <path> # 目录或 .har
--json # 机器可读
--strict # warn → error
--ignore OHPM-NAME-04,OHPM-DOC-01 # 豁免(会在输出里回显)
--config .ohpmlintrc.json5 # 规则开关/阈值
0 无 error;1 存在 error;2 工具自身失败。
分开的理由很实际:2 是「工具没跑起来」(解包失败、JSON5 解析失败),1 是「代码不合规」。CI 里这两件事的处置方式完全不同,前者要修环境,后者要改代码。

(原图:09-CI三态.png)
有一个细节值得记:解析失败本身也算一条 error,但同时以 2 退出。因为「报错」和「没跑起来」不能混。
测试要对着真实失败场景写
31 个测试怎么来的?不是「每个函数配一个」,是照着真实驳回原因反向设计的。
11 组 fixtures 对应 11 类真实问题:缺四件套的、README 没写安装命令的、CHANGELOG 没记当前版本的、description 超长的、author 没 email 的、包里有 .exe 的、.so 放错位置的、体积超阈值的……每一组都是一个曾经被拒过的形状。
这样写的好处是:测试通过 = 真实场景能过,而不是「函数返回了预期值」。工具类项目最怕的就是后者——单测全绿,一上真实包就误报。
产出:一个能直接跑的包
最后它交出来的东西:36 条规则、11 组 fixtures、31 个测试全绿,发布到 npm 为 @quizzyjoy/ohpm-lint,Apache-2.0 开源。
npx @quizzyjoy/ohpm-lint ./path/to/your-library

(原图:05-开源仓首屏.png)
仓库结构也清楚:src/ 按八组分文件、tests/ 放用例、fixtures/ 放样本、SPEC.md 是规则依据、action.yml 供 CI 引用。
非官方工具:本项目与 OpenHarmony、华为无隶属关系。规则依据官方公开文档,如有出入以中心仓现网口径为准。
成果验证:扫了 60 个热门包
工具写完之后,第一个问题自然是:这个东西扫真包会出来什么?
我们让它拿中心仓 popularity 排名前 60 的包跑了一遍(时点 2026-10-21,工具 v0.2.0)。样本是 48 个规范 HAR(含 oh-package.json5)+ 12 个 npm 风格包(只有 package.json,中心仓允许直发但 HAR 规范不适用,单独归类为 OHPM-PKG-01)。
零告警的包,一个都没有
| 指标 | 数值 |
|---|---|
| 规范包 error / warn / info | 8 / 217 / 47 |
| 平均 warn / 包 | 4.52 |
| 零告警包 | 0 |
| warn 分布 | 1 到 3 条:15 个 · 4 到 6 条:25 个 · 7 条以上:8 个 |

(原图:01-warn分布.png)
「零告警 0 个」是这组数据里最刺眼的一格。
不是针对谁:这 48 个包里不少是装机量很高的库,作者都是资深开发者。它说明的是,中心仓的成文要求与实际发布的普遍状态之间,有一道稳定的差距。
这道差距的存在恰恰证明了工具的价值:如果所有包都合规,这个工具就没有存在必要。
8 条 error 全都是元数据
| 问题 | 次数 |
|---|---|
开源包缺 repository | 6 |
author 没有 email / url | 2 |
这 8 条集中在 6 个包,而且这些包都已经上架了。
说明两点:一是人工审核并不总能拦住这些问题,「我已经上架了」不能证明合规;二是这些是随时可能被新规则打到的风险项。
文档质量的缺口更明显
| 缺失项 | 比例 |
|---|---|
README 缺「目录结构」 | 73% |
README 缺「约束与限制」 | 65% |
README 缺「所需权限」 | 54% |
license 不是 SPDX 写法 | 31% |

(原图:02-文档缺口.png)
这四项都不是「上架失败」级的硬要求,但它们决定了别人敢不敢用你的库。
一个没有「约束与限制」的库,使用者不知道它在什么场景会失效;一个没有「所需权限」的库,接入方要自己翻代码看要不要额外申请。这些成本不会消失,只会转嫁给下游。
这组数据怎么用
对库作者:拿自己的包跑一遍,看落在分布的哪一段。7 条以上告警的 8 个包,就是改善空间最大的那部分。
对工具本身:这 217 条 warn 是真实分布。如果某条 warn 在 60 个包里命中 55 个,要么是规则太严,要么是这个生态普遍不重视。两种情况都值得回头看规则定义。
接进 CI 也很简单:
- name: Lint OHPM package
uses: quizzyjoy/ohpm-lint@v0
with:
path: ./build/default/outputs/default/library.har
strict: true
一个坑要提醒:不要用 || true 吞掉退出码。很多团队为了让流水线先跑通会这么写,结果是检查形同虚设,几个月后才发现一次都没生效过。存量问题应该用 --ignore 显式豁免,看得见的豁免比看不见的跳过安全得多。
人必须接的那部分
它能做的,开头两张图已经证明过了。这里只说它做不了的。
第一是定级。「这条算 error 还是 warn」不是技术问题,是产品判断。error 意味着阻断发布,误报就是在拦人。所以每条 error 都必须能指到官方原话,这个要求本身只能由人定。
举个真实判例:官方规定 description 必须 6 到 512 字符。这条是明确的数量约束,超了属于字段不合规,我们定 error。而「README 应该包含目录结构」这类,官方用的是建议措辞,我们定 warn——不冒充官方把它升成阻断。
两条规则的差别不在技术上(都是「检查一个字段」),在官方原话的强度上。这个强度只有人能读出来。
第二是边界的取舍。 工具最终有三个「不做」:
| 不做 | 理由 |
|---|---|
| 不做代码风格检查 | 交给 DevEco CodeLinter,专业工具已经做得很好 |
不替代 ohpm prepublish | 两者互补:prepublish 管「能不能打包」,lint 管「会不会被拒」 |
| 不做联网校验 | 包名唯一性、版本重复要查服务器,联网会让 CI 不可靠 |
三个「不做」都是取舍,不是能力问题。AI 倾向于「多做一些」,而好的工具需要「明确不做一些」。
推荐顺序是三步:ohpm prepublish → ohpm-lint → ohpm publish。顺序不能反,前者失败时后者没有意义。

(原图:04-发布三步.png)
一句话总结
让 Dev Assistant 做规则的搬运工,而不是规则的制定者。
搬运的意思是:把官方文档里的要求,一字不改地搬到可执行代码里。制定规则是官方的事,工具只负责忠实执行。
验收清单
三方库工具做完,按这份清单逐项过一遍(括号里是本次做法):
- 每条规则有官方出处(代码里带
officialRef,形如§7.1,review 时逐条比对) - error 能指到原话(每个阻断级规则都能在官方文档里找到明确表述)
- 不冒充官方(建议项一律 warn,不升级为阻断)
- 两种模式分开(开发期
dir模式跳过发布包结构检查,避免一路误报) - 退出码可被 CI 消费(0/1/2 三态,工具失败与代码问题分开)
- 豁免要回显(
--ignore跳过的规则在输出里列出来,不静默) - 边界写进文档(三个「不做」明确写在 SPEC 与 README 里)
- 有真实数据支撑(60 个热门包的扫描结果,不是「我们测了一下能用」)
- 测试覆盖真实失败场景(11 组 fixtures 对应真实上架包的常见问题)
最容易漏的是第四条和第二条:两种模式不分开,开发期就会被发布包规则淹没;error 没有官方出处,工具就会越来越严,最后没人敢用。
参考资料
官方文档
- 三方库发布的必要文件 — 四件套与结构要求
- OHPM 发包规则汇总 — 21 条成文规则
- 三方库名称指南 — 包名与安装命令一致性
- 创建及发布三方库 — 完整发布流程
- HarmonyOS Dev Assistant 简介 — 能力概览与适用场景
本文案例项目
- ohpm-lint 开源仓库(GitHub) — 36 条规则、11 组 fixtures、31 个测试
- ohpm-lint npm 包 —
npx @quizzyjoy/ohpm-lint ./your-library - 生态质量扫描报告 — 60 个热门包的完整数据
更多推荐
所有评论(0)