| name | init-release-base-relizy-and-bumpp |
| description | Use when 需要为 pnpm monorepo 从零接入 relizy + bumpp 组合发版方案，或处理 init relizy、init bumpp、接入发版、monorepo 发版初始化、relizy + bumpp、 relizy.config、bump.config、changelog.config、独立版本、GitHub Release 自动化。 |
| user-invocable | true |
| metadata | {"version":"3.0.2"} |
Init Release Base — Relizy + Bumpp Monorepo 发版配置落地技能
本技能是执行型工作流：为 pnpm monorepo 一次性接入 relizy（子包）+ bumpp（根包） 的组合发版方案，从仓库体检、配置落盘、依赖对齐、故障预检，到 dry-run 验证与文档同步，覆盖完整接入链路。
设计理念
- 本地控制 tag 生成：开发者在本地运行
pnpm release 一条命令完成所有版本管理
- 云端负责 GitHub Release：GitHub Actions 检测到 tag 推送后，自动从 CHANGELOG.md 提取内容创建 Release
- 单次 push：串行主链路中的所有 tags（子包 + 根包）在一次
git push --follow-tags 中推送
- 根包有两种合法入口：串行主链路使用
release:root + --no-push；单独根包发版使用 release:bumpp + --push
- 两工具协作：relizy 负责子包（independent 模式），bumpp 负责根包，各司其职
与 package-linter 的关系
若同时新建或规范化子包，请先或并行参考仓库内 package-linter 技能，保证 package.json / tsup / tsconfig 与 monorepo 约定一致；本技能聚焦发版域的配置与决策。
Runner：必须使用 @ruan-cat/utils 的 relizy-runner（禁止自建脚本）
兼容层（Windows GNU 工具补齐 + independent 基线 tag 自动准备）由 @ruan-cat/utils 包实现，通过 relizy-runner bin 调用。不得在目标仓库内新建 scripts/relizy-runner.ts 或任何本地 runner 副本。
- 权威说明：以安装到目标仓库的
relizy-runner --help 与 @ruan-cat/utils 包内 relizy-runner 文档为准。
- 调用约定：须使用
package.json 的 bin（如 npx relizy-runner … / pnpm exec relizy-runner …），禁止使用 tsx @ruan-cat/utils/relizy-runner 等绕过 exports 的写法。
- baseline 行为：
release / bump 在缺少 independent 基线 tag 时，会按当前 package.json 版本创建 annotated bootstrap tags。带 --no-push 时只保留本地 tag，后续 git push --follow-tags 会携带；不带 --no-push 时使用 atomic push 推送本轮 tags。
- 禁写行为：
--dry-run 或 --no-commit 下不会创建 tag，缺少基线时只打印手工兜底命令并停止。
--yes 与非交互发版
relizy 在 release / bump 等流程中可能弹出交互；在无 TTY 或 CI 下会挂起。串行主链路中的 release:sub 与 release:root 须显式写出 --yes，包括 package.json 脚本、README、验证命令。单独入口 release:bumpp 默认保留 bumpp 的交互式版本选择，并通过 --push 立即推送根 tag；若目标仓库确实需要全非交互，再自行显式追加 --yes。
发版流程架构
pnpm release
│
├── 1. pnpm run release:sub（relizy）
│ ├── 必要时创建本地 annotated baseline tags（--no-push 下不推送）
│ ├── 分析各子包 commits → bump → CHANGELOG → commit → tag
│ └── 不 push（--no-push）
│
├── 2. pnpm run release:root（bumpp）
│ ├── bump 根包 patch → changelogen → commit → tag
│ └── 不 push（--no-push）
│
└── 3. pnpm run git:push
└── git push --follow-tags（一次性推送）
详细架构说明见 references/release-workflow-architecture.md。
单独根包发版时使用：
pnpm run release:bumpp
├── bumpp 交互式选择根包版本
├── 生成根包 commit + tag
└── 立即 push（--push）
一次性落盘的配置文件
依赖清单
接入时须安装以下 devDependencies（版本以 registry 最新为准）：
pnpm add -D bumpp changelogen changelogithub relizy @ruan-cat/commitlint-config @ruan-cat/utils @types/node pnpm-workspace-yaml
根包 scripts 模板
详见 templates/package-scripts.md。关键命令：
{
"release": "pnpm run release:sub && pnpm run release:root && pnpm run git:push",
"release:sub": "relizy-runner release --no-publish --no-provider-release --no-push --yes",
"release:root": "bumpp --no-push --yes --release patch",
"release:bumpp": "bumpp --push",
"changelog:root": "changelogen --output CHANGELOG.md",
"git:push": "git push --follow-tags"
}
三层目录
| 层级 | 路径 | 用途 |
|---|
| 流程与清单 | SKILL.md（本文件） | 阶段划分、阻断条件、索引 |
| 可复制片段与模板 | templates/ | 配置文件模板、侦察输出、确认清单、scripts 模板 |
| 原理与决策依据 | references/ | 决策树、陷阱、验证矩阵、故障预检、架构说明 |
非目标（必须遵守）
- 不默认执行
npm publish、不默认开启 provider release。
- 不把本技能写成某个私有或固定仓库的专用脚本。
- 在
private 策略未确认、兼容策略未决 时，不盲目落盘。
- 禁止在目标仓库内新建本地 runner 脚本。
- 不将
selective 与「各包独立版本线」混为一谈。
标准六阶段流程
Task Progress:
- [ ] 阶段 1 — 侦察：收集工作区、锁文件、现有发版工具、tag、private、README/CHANGELOG 边界（用 templates/workspace-discovery.md）
- [ ] 阶段 2 — 确认：仅对高风险项确认（versionMode、全量纳管、private、兼容策略）（用 templates/package-eligibility.md）
- [ ] 阶段 3 — 故障预检：检查是否存在 commit-and-tag-version、conventional-changelog-cli 等遗留根包发版工具（见 references/dependency-conflict-precheck.md）
- [ ] 阶段 4 — 落盘：依赖安装、5 个配置文件写入、根 scripts 配置、必要时最小 tsconfig（用 templates/config-writer.md + 各 templates/*.ts）
- [ ] 阶段 5 — 验证：help、changelog dry-run、release dry-run（见 references/verification-matrix.md）
- [ ] 阶段 6 — 收尾：修改清单、破坏性说明、残余风险、下一步（用 templates/docs-sync.md）
显式阻断条件（不得跳过）
以下任一成立时，停止自动落盘，改为只输出方案与用户确认：
- 用户要求「各子包独立版本」，却拟使用
selective 充当独立版本方案。
- 拟纳入 relizy 的包涉及
private: true 变更，但未获确认。
- 确认不使用
relizy-runner，但未完成手工 baseline tag 确认。
- Windows 下已观测到
grep / head / sed 类失败，但未选择兼容策略。
- 检测到遗留根包发版工具（如
commit-and-tag-version、conventional-changelog-cli、standard-version、release-it），但尚未确认是删除还是隔离（见 references/dependency-conflict-precheck.md）。
核心决策（速查）
- versionMode：「每包独立版本线」→
independent；「只 bump 变更包且共享一次发布语义」≠ 独立版本线。
- 兼容策略：首选
relizy-runner（Windows GNU 工具 + baseline tag 自动准备）。
- 文档边界：
rootChangelog 与 README 更新是两条链路；formatCmd 不应宽到误改 README。
- 根包发版：由 bumpp 独立负责，
bump.config.ts 不写死 push；串行入口 release:root 用 --no-push，单独入口 release:bumpp 用 --push，并通过 execute 函数调用 changelogen --output CHANGELOG.md -r <newVersion>。
- GitHub Release：由 CI 使用
gh release create 从 CHANGELOG.md 提取，不依赖 changelogithub / relizy provider-release。
templates/ 索引
references/ 索引
验证命令基线（根目录执行）
详见 references/verification-matrix.md。
relizy 子包验证（使用 relizy-runner）：
pnpm exec relizy-runner --help
pnpm exec relizy-runner changelog --dry-run --yes
pnpm exec relizy-runner release --dry-run --no-publish --no-provider-release --no-push --no-commit --no-clean --yes
bumpp 根包验证：
pnpm exec bumpp --help
pnpm exec bumpp --dry-run --release patch
pnpm exec changelogen --output CHANGELOG.md -r 0.0.1
git ls-remote --tags origin "v0.0.1"
期望根包 changelog 生成版本标题 ## v0.0.1，而不是区间标题 ## v0.0.0...main。
若本地已有根包 tag，但 GitHub Actions 的 release.yaml 未触发，应先检查远程 tag 是否存在，而不是第一时间怀疑工作流的 CHANGELOG 提取逻辑。
若 release:dry 或验证矩阵中的 dry-run 提示缺少 independent 基线 tags，这是预期的禁写保护：dry-run 不会创建 tag。首次接入时应通过真实 release:sub --no-push 自动创建本地 annotated baseline tags，或按提示手工创建后再重新 dry-run。
若输出为「无可 bump 包」且无配置/跨平台错误，应解释为验证通过但当前无变更可发。
