easysoft 发布 zentao-api
从仓库根目录执行流程，遵守项目 AGENTS.md，仅使用 Bun 管理依赖和运行项目脚本。尊重用户指定的执行范围；用户要求完整发布时，执行下述本地准备流程。不要擅自丢弃已有改动、推送远端或发布 npm 包。
1. 检查发布前状态
- 运行
git rev-parse --show-toplevel，确认正在操作zentao-api仓库根目录。 - 运行
git status --short --branch，记录分支和工作区状态。 - 如存在未提交或未跟踪文件，列出它们并暂停；请用户先提交、暂存或明确授权把哪些改动纳入发布。不要自行暂存、覆盖或丢弃这些改动。
- 确认当前提交包含值得发布的变更；如上个发布 tag 后没有实际变更，停止并说明。
2. 收集版本和变更范围
- 运行
git describe --tags --abbrev=0获取最近 tag。没有 tag 时，以全部历史为范围。 - 对有 tag 的仓库运行
git log <最近-tag>..HEAD --oneline；没有 tag 时运行git log --oneline。 - 同时检查提交正文、变更统计和必要的源码差异，不能只根据提交标题判断是否存在破坏性变更。
- 读取
package.json的当前版本，并检查CHANGES.md的既有格式和措辞。
3. 确认新版本号
- 用户已指定版本号时，校验它是合法、递增且尚未被使用的 SemVer；
package.json使用裸版本号，tag 使用v<版本号>。 - 用户未指定版本号时，按实际影响推荐版本：
- 存在不兼容的公共 API 变更：递增 major。
- 存在向下兼容的新功能、新模块或新公共能力：递增 minor。
- 仅包含向下兼容的修复、文档、测试、内部重构或维护：递增 patch。
- 不要只依赖
feat、fix等提交前缀；以代码和用户可见行为为准。 - 用户未预先指定版本时，展示“当前版本 → 推荐版本”、变更依据和 SemVer 理由，并等待明确确认后再修改文件。
- 修改前确认
v<版本号>不存在；如版本或 tag 已存在，停止处理冲突。
4. 更新版本和变更日志
仅修改
package.json的version字段，不手工修改src/version.ts；构建脚本会从package.json注入VERSION。在
CHANGES.md的# 变更日志标题后插入最新条目：## <版本号> - <YYYY-MM-DD> ### 新增 - ... ### 修复 - ... ### 变更 - ... ### 测试 - ... ### 文档 - ...只保留有实际内容的分类。使用简洁中文描述用户影响，合并重复提交，忽略纯发布 housekeeping，并沿用现有日志风格。
不手工编辑
docs/reference/或docs/zentao-api/的生成文件。
5. 重新生成并验证
依次运行：
bun run docs:generate
bun run docs:build
bun run check
要求所有命令成功。bun run check 中的构建和 smoke test 必须确认导出的 VERSION 与 package.json 一致。命令失败时先诊断并修复根因，不要创建发布提交或 tag。
随后检查 git status --short 和完整 diff：
- 确认
package.json、CHANGES.md和生成的docs/变更正确。 - 将生成的文档变更与发布修改放在同一个提交中。
- 如出现不属于本次发布的变化，暂停并说明，不要擅自纳入。
6. 创建发布提交和 tag
- 仅暂存确认过的发布文件：
git add package.json CHANGES.md docs。 - 运行
git diff --cached --check，再检查暂存 diff 和统计；有错误或意外文件时先处理。 - 使用项目约定提交：
git commit -m "* release v<版本号>"。 - 提交成功后运行
git tag v<版本号>创建 tag。 - 不自动推送。报告新版本号、变更日志摘要、验证结果、提交和 tag，并提示用户可执行
git push && git push --tags。
7. 可选发布到 npm
只有用户明确要求或确认发布 npm 包后才继续。需要认证时运行 npm login，随后运行：
bun publish
发布成功后报告 zentao-api npm 包；发布失败时保留本地提交和 tag，说明失败步骤，不重复发布或改写版本历史。