Imported from zaigie/palworld-server-tool (
AGENTS.md). Install upstream withnpx skills add zaigie/palworld-server-tool. Copyright stays with the author.
AGENTS.md
沟通约定
- 始终使用简体中文回复。
Release 发布流程
除非维护者明确要求采用其他方式,否则发布正式版本时遵循以下流程。
1. 发布前检查
-
所有待发布改动先提交到
dev,不要直接在main上开发。 -
确认工作树干净,并确保 Git LFS 对象已经上传:
git switch dev git pull --ff-only origin dev git status git lfs status git push origin dev -
验证地图瓦片完整,不能包含未展开的 LFS 指针:
python3 script/verify_map.py -
创建
dev -> main的正式 PR。PR 描述应覆盖相较于main的全部变更、影响范围和验证结果。 -
Review 没有阻塞问题后合并 PR。合并到
main不应触发发布构建;正式构建只由版本 tag 触发。
2. 创建正式版本 tag
只有已经进入 main 的提交才能打正式 tag。tag 格式必须为 v<major>.<minor>.<patch>,例如 v0.12.0。
仓库历史版本使用轻量 tag,继续采用相同格式:
git fetch origin --tags
git switch main
git pull --ff-only origin main
VERSION=v0.12.0
git tag "$VERSION"
git push origin "$VERSION"
不要在 PR 合并前打 tag。工作流会验证 tag 指向的 commit 是否属于 origin/main;不满足时发布会失败。
3. 自动执行的工作流
推送正式 tag 后,GitHub Actions 会自动运行:
Native Build and Release- 构建 Linux amd64、Linux arm64、Windows amd64 和 macOS arm64 原生文件。
- 自动创建或更新对应的 GitHub Release。
- 自动生成
SHA256SUMS.txt。
PST Docker Image CI- 发布
jokerwho/palworld-server-tool:<version>和latest。 - Docker 版本标签会去掉开头的
v,例如v0.12.0对应0.12.0。
- 发布
PST-Agent Docker Image CI- 发布
jokerwho/palworld-server-tool-agent:<version>和latest。
- 发布
仅合并到 main 不会运行以上三条发布工作流。
Native Build and Release 会先将各平台文件保存为临时 Actions artifacts;最后的 release job 会自动下载这些文件、生成校验和,并将全部文件上传为 GitHub Release assets。不要在 tag 推送后手工执行 gh release create,也不需要在网页中选择构建文件,以免产生草稿、重复 Release 或资产缺失。
4. Release 资产检查
正式 Release 应包含以下 9 个资产:
pst-agent_<version>_darwin_aarch64pst-agent_<version>_linux_aarch64pst-agent_<version>_linux_x86_64pst-agent_<version>_windows_x86_64.exepst_<version>_darwin_aarch64.tar.gzpst_<version>_linux_aarch64.tar.gzpst_<version>_linux_x86_64.tar.gzpst_<version>_windows_x86_64.zipSHA256SUMS.txt
检查 Release:
gh release view "$VERSION" --repo zaigie/palworld-server-tool
gh release view "$VERSION" \
--repo zaigie/palworld-server-tool \
--json assets \
--jq '.assets[].name'
5. Docker 多架构检查
两个正式镜像都必须包含 linux/amd64 和 linux/arm64:
DOCKER_VERSION="${VERSION#v}"
docker buildx imagetools inspect \
"jokerwho/palworld-server-tool:${DOCKER_VERSION}"
docker buildx imagetools inspect \
"jokerwho/palworld-server-tool-agent:${DOCKER_VERSION}"
同时检查对应版本标签与 latest 是否指向同一个顶层 manifest digest。
6. Release 说明
工作流默认生成 GitHub 自动发布说明。需要保持中英双语说明时,等待 Release 自动创建完成,再准备 RELEASE_NOTES.md 并更新:
gh release edit "$VERSION" \
--repo zaigie/palworld-server-tool \
--title "$VERSION" \
--notes-file RELEASE_NOTES.md
说明至少应包含中文变更、English changes 和相较于上一版本的 Full Changelog 链接。
7. 失败恢复
- 网络波动或单个 job 失败时,在 GitHub Actions 页面选择
Re-run failed jobs。 - 不要为了重试而重复创建 Release,也不要随意删除或移动已经公开的 tag。
- 原生 Release 成功、Docker 失败时,只重跑失败的 Docker workflow。
- Docker 成功、原生构建失败时,只重跑
Native Build and Release的失败任务。 - 本机磁盘空间有限,不要默认在本地执行完整双架构镜像构建;优先使用 GitHub Actions。
- Docker Hub 登录依赖仓库 secrets:
DOCKER_HUB_USERNAME和DOCKER_HUB_PWD。
仅测试 PST Docker 镜像
需要验证 Dockerfile、但不能创建 Release 或覆盖正式镜像标签时,手动运行:
gh workflow run docker-image.yml \
--repo zaigie/palworld-server-tool \
--ref dev
手动运行只发布 manual-<short-sha> 标签,不更新 edge、语义版本标签或 latest,也不会触发原生 Release 和 PST-Agent 构建。
