跳到主要内容

仓库与版本约定

软件包通过 Git 仓库分发。本页说明仓库需要满足的约定，这样你的软件包才能被正确安装。

仓库根目录就是软件包​

把你的软件包内容直接放在仓库根目录，不要多套一层文件夹：

你的仓库/
├── .hm.json
├── index.lua
└── ui/
    ├── index.lua
    └── main.lua

安装时，助手会把仓库内容原样复制到 apps/<全名>/。

全名要与目录名一致​

软件包的全名是 作者@名称。它必须与安装后的目录名一致，否则依赖注入与 require 会失效。

  • 发布时全名由「昵称」与「软件包名称」拼成：昵称@软件包名称。
  • 因此 .hm.json 的 作者/名称、apps/ 下的目录名都应对应这个全名。
apps/黑猫@基础库/.hm.json
{
  "名称": "基础库",
  "作者": "黑猫",
  "类型": "函数库",
  "版本": "v1.0"
}

对应目录名应为 黑猫@基础库。

提示

软件包名称不能包含 @（@ 用于分隔昵称与名称）。

版本来自 Git tag​

助手的「版本列表」直接读取仓库的远端 tag；安装时也是按 tag 拉取对应版本。

因此发布一个新版本的标准做法是：

# 1. 提交改动
git add .
git commit -m "feat: 新增功能"
git push

# 2. 打一个 tag 并推送
git tag v1.1
git push origin v1.1
  • tag 名就是版本名，建议使用 v1.0、v1.1 这样的格式。
  • 请同步更新 .hm.json 里的 版本 字段，使其与 tag 保持一致（便于界面展示与识别更新）。
  • 没有 tag 的仓库无法选择版本，也就无法安装。

依赖的版本也必须是 tag​

依赖软件包 中填写的版本会被用来安装依赖，因此它必须是依赖仓库上真实存在的 tag：

{
  "依赖软件包": {
    "黑猫@基础库": "v1.0"
  }
}
注意

如果依赖的版本 tag 不存在，安装会失败。升级依赖后请记得同步修改这里。

仓库地址 的作用​

.hm.json 里的 仓库地址 主要用于界面上的「打开仓库」按钮。真正的安装地址以服务端 登记（发布） 的信息为准，详见 发布与安装。

下一步：发布与安装。