@peiyanlu/release 1.3.1 → 2.1.0

package/README.md

@@ -1,4 +1,4 @@
-# Release Project
+# @peiyanlu/release
 
 
 [![module](https://img.shields.io/badge/package-ESM--only-FFE536.svg?logo=npm)](https://nodejs.org/api/esm.html)
@@ -11,408 +11,321 @@
 [![build](https://img.shields.io/github/actions/workflow/status/peiyanlu/release/test.yaml?branch=master&logo=github)](https://github.com/peiyanlu/release/actions)
 [![coverage](https://coveralls.io/repos/github/peiyanlu/release/badge.svg?branch=master)](https://coveralls.io/github/peiyanlu/release?branch=master)
 
-🚀 **一个用于自动化版本管理与包发布的通用 CLI 工具**
+一个基于 [Conventional Commits](https://www.conventionalcommits.org/) 自动升级版本、生成变更日志并完成发布的工具。
 
-提供完整的发布工作流自动化：
+- 📄 使用 [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) 分析提交记录、计算下一个版本并生成变更日志。
+- 🧩 提供通用的项目与托管扩展接口，可支持自定义项目类型、清单格式和 Git 托管平台。
+- 📦 内置 `package.json`、Node.js GitHub Action 项目类型，以及 npm/pnpm 发布和 workspace monorepo 支持。
+- 🚀 提供 CLI 和 [GitHub Action](https://github.com/peiyanlu/release) 两种发布入口，支持本地及 CI 自动化发布。
 
-- [**Bump 版本号**][1]
-- [**自动生成 Changelog**][2]
-- [**Git**：暂存 → 提交 → 打 Tag → 推送][3]
-- [**发布到 npm**][4]
-- [**GitHub**：创建 Release][5]
-- [**Monorepo**][6]
+## 功能与扩展点
 
-## 安装
+提供通用扩展接口，并内置项目与发布实现：
 
-```bash
-npm install -D @peiyanlu/release
-# 或
-yarn add -D @peiyanlu/release
-# 或
-pnpm add -D @peiyanlu/release
-```
+| 能力                       | 内置实现                                                                     |
+|----------------------------|------------------------------------------------------------------------------|
+| 抽象扩展接口               | `Project`、`MonorepoProject`、`ProjectManifest`、`GitRepositoryHosting`      |
+| `package.json` 项目        | `PackageJsonProject`、`PackageJsonMonorepoProject`                           |
+| 项目清单                   | `PackageJsonManifest`、`ComposedProjectManifest`                             |
+| GitHub 托管                | `GithubHosting`                                                              |
+| npm / pnpm 发布支持        | `NpmProject`、`PnpmProject`、`NpmWorkspacesProject`、`PnpmWorkspacesProject` |
+| Node.js GitHub Action 项目 | `NodeGithubActionProject`                                                    |
+| 发布入口                   | `ReleaserCli`、`ReleaserGithubAction`                                        |
 
-## CLI
-
-```bash
-release [release-type] [options]
-```
+单包项目可使用 `NpmProject` 或 `PnpmProject`；多包项目可使用对应的 workspace 实现。通过 `Project`、`MonorepoProject`、`ProjectManifest` 和 `GitRepositoryHosting`，也可扩展其他项目类型、清单格式和托管平台。
 
-`release-type` 用于指定版本升级类型，支持：
+## 环境要求
 
-- `patch`：Bug 修复版本（默认）
-- `minor`：向后兼容的新功能
-- `major`：不向后兼容的破坏性更新
+- Node.js 22.18+
+- Git 仓库
+- npm 发布需要可用的 npm 身份验证；GitHub API 操作需要 GitHub token
 
-当未传入 `release-type` 时，默认使用 `patch`
-
-```bash
-pnpm release minor --ci
-```
+## 安装
 
-### 通用参数
-
-| 参数                                    | 说明                                                         |
-|---------------------------------------|------------------------------------------------------------|
-| `-v, --version`                       | 输出当前 CLI 版本并退出                                             |
-| `-h, --help`                          | 显示帮助信息                                                     |
-| `-n, --dry-run`                       | 空跑模式，展示将要执行的发布流程但不做任何修改                                    |
-| `--show-release`                      | 打印即将发布的版本号并退出                                              |
-| `--show-changelog`                    | 打印生成的 Changelog 并退出                                        |
-| `--ci`                                | 启用 CI 模式：禁用交互提示，缺少必要参数时直接失败；GitHub Actions 等 CI/CD 环境中默认启用 |
-| `-r, --release-count <count>`         | 生成多少个版本的变更日志                                               |
-| `--include-hidden`                    | 生成 CHANGELOG 时包含默认隐藏的 commit 类型                            |
-| `--only-changelog`                    | 仅更新 CHANGELOG                                              |
-| `-C, --no-require-clean-working-tree` | 是否要求工作目录保持干净（无未提交的更改）                                      |
-| `--skip-git`                          | 跳过 git、github 环境检查以及后续操作                                   |
-| `--skip-npm`                          | 跳过 npm 环境检查以及后续操作                                          |
-| `--skip-github`                       | 跳过 github 环境检查以及后续操作                                       |
-
-### Prepare 相关参数
-
-| 参数          | 说明                       |
-|-------------|--------------------------|
-| `--prepare` | 仅仅变更版本、提交代码、创建 Tag、推送到远程 |
-
-```bash
-pnpm release minor --prepare --ci --package pkg-a
+```sh
+pnpm add -D @peiyanlu/release
+# 或 npm install --save-dev @peiyanlu/release
 ```
 
-> 后续可以通过 tag 进行 npm 发布和创建 GitHub release
-
-### Monorepo / CI 相关参数
-
-| 参数                    | 说明                               |
-|-----------------------|----------------------------------|
-| `-m, --is-monorepo`   | Monorepo 项目                      |
-| `-p, --package <pkg>` | 指定要发布的子包名称（仅用于 Monorepo 的 CI 场景） |
+## CLI
 
-```bash
-pnpm release minor --ci --package pkg-a
+```sh
+release [release-type] [options]
 ```
 
-### npm 发布相关参数
+不指定 `release-type` 时，会根据提交记录推断并预选升级类型；CI 模式下自动采用该类型。可指定 `major`、`minor`、`patch` 或 `prerelease`。
 
-| 参数             | 说明                             |
-|----------------|--------------------------------|
-| `--otp <code>` | npm 发布时使用的一次性验证码（用于开启 2FA 的账户） |
+```sh
+pnpm exec release --dry-run
+pnpm exec release minor --dry-run
+pnpm exec release --ci
+```
 
-> 当使用 **Trusted Publishing（OIDC）** 时，通常无需提供 `--otp`。
+常用选项：
 
+| 选项             | 说明                                               |
+|------------------|----------------------------------------------------|
+| `-n, --dry-run`  | 预览发布步骤，不写入变更                           |
+| `--ci`           | CI 模式，关闭交互式流程                            |
+| `--skip-bump`    | 跳过项目版本更新                                   |
+| `--skip-git`     | 跳过 Git 提交、标签、推送；版本推断仍读取 Git 历史 |
+| `--skip-publish` | 跳过项目发布                                       |
+| `--skip-release` | 跳过仓库托管服务上创建发布                         |
+| `-v, --version`  | 显示版本                                           |
+| `-h, --help`     | 显示完整帮助                                       |
 
 ## 配置
 
-发布流程可以通过配置文件进行自定义。  
-如果项目中**未提供配置文件**，工具会自动使用**内置默认配置**。
-
-默认配置适用于 **单仓库（Single Repo）** 项目。  
-当项目为 **Monorepo** 结构时，**必须显式提供配置文件**，并开启 Monorepo 模式以正确识别各个子包。
-
-支持的配置文件格式：
-
-```
-release.config.{ts,mts,js,mjs}
-```
+CLI 会从当前项目根目录加载第一个存在的 `release.config.ts`、`.mts`、`.js` 或 `.mjs` 文件。CLI 要求配置文件提供 `project` 和 `hosting`；GitHub Action 只要求配置文件提供 `project`，提供的 `hosting` 将被忽略。
 
-示例配置：
+下面的单包配置使用 pnpm 项目，并提供 GitHub 托管功能：
 
 ```ts
 // release.config.ts
-import { defineConfig } from '@peiyanlu/release'
+import { defineConfig, GithubHosting, PnpmProject } from '@peiyanlu/release'
 
 
 export default defineConfig({
-  isMonorepo: false,
-  packages: [],
-  getPkgDir: (pkg) => `.`,
-  toTag: (pkg: string, version: string) => `v${ version }`,
-  changelog: {
-    tagPrefix: undefined,
-  },
-  
-  git: {
-    commit: true,
-    tag: true,
-    push: true,
-    commitMessage: 'chore(release): ${tag}',
-    tagMessage: '${tag}',
-  },
-  npm: {
-    publish: true,
-  },
-  github: {
-    release: true,
-    releaseName: '${tag}',
-  },
+  project: new PnpmProject(),
+  hosting: new GithubHosting({
+    token: process.env.GITHUB_TOKEN,
+  }),
+  bump: { prerelease: 'beta' },
+  commit: { sign: false },
+  publish: { tag: 'latest' },
 })
 ```
 
-### Monorepo 配置
+`defineConfig` 接受 `project`、可选的 `hosting`，以及 `checkout`、`bump`、`commit`、`tag`、`push`、`publish`、`release`、`pullRequest` 等步骤选项。项目和步骤选项的 TypeScript 类型可用于编辑器提示。
 
-在 Monorepo 场景下，需要显式声明仓库结构、子包列表以及 Tag / Changelog 的生成规则。
+### pnpm workspace monorepo
 
-示例配置：
+当 pnpm workspace 用于管理多个包时，可使用 `PnpmWorkspacesProject`。`mode` 为 `fixed` 时所有包共用版本；`independent` 时各包可单独升级。workspace 包由根目录 `pnpm-workspace.yaml` 中的 `packages` 模式发现。
 
 ```ts
 // release.config.ts
-import { defineConfig } from '@peiyanlu/release'
+import { defineConfig, GithubHosting, PnpmWorkspacesProject } from '@peiyanlu/release'
 
 
 export default defineConfig({
-  isMonorepo: true,
-  packages: [ 'demo-a', 'demo-b' ],
-  getPkgDir: (pkg) => `packages/${ pkg }`,
-  toTag: (pkg: string, version: string) => `${ pkg }@${ version }`,
-  changelog: {
-    tagPrefix: (pkg: string) => `${ pkg }@`,
-  },
-  
-  git: {
-    commit: true,
-    tag: true,
-    push: true,
-    commitMessage: 'chore(release): ${tag}',
-    tagMessage: '${tag}',
-  },
-  npm: {
-    publish: true,
-  },
-  github: {
-    release: true,
-    releaseName: '${tag}',
-  },
+  project: new PnpmWorkspacesProject({ mode: 'fixed' }),
+  hosting: new GithubHosting({
+    token: process.env.GITHUB_TOKEN,
+  }),
 })
 ```
 
-### 使用 CLI 生成配置文件
-
-工具内置 `init` 子命令，可用于快速生成发布配置文件。
-
-```bash
-release init
-```
-
-#### init 参数说明
-
-| 参数               | 说明                  |
-|------------------|---------------------|
-| `-f, --force`    | 覆盖已存在的配置文件          |
-| `-m, --monorepo` | 生成 Monorepo 项目的配置模板 |
-| `-a, --add`      | 自动暂存配置文件            |
-
-#### 行为说明
-
-- 自动检测项目模块类型（ESM / CJS）
-- 自动检测是否使用 TypeScript
-- 根据检测结果生成对应格式的配置文件：
-    - `release.config.ts`
-    - `release.config.mts`
-    - `release.config.js`
-    - `release.config.mjs`
-- 若配置文件已存在且未使用 `--force`，将终止并提示错误
-
-## Bump 版本号
-
-工具内置语义化版本（Semantic Versioning）管理能力，可自动更新`package.json` 中的版本号：
-
-- 支持标准版本类型：
-    - `major`：不兼容的重大变更（1.x.x → 2.0.0）
-    - `minor`：向后兼容的新功能（1.1.x → 1.2.0）
-    - `patch`：向后兼容的 Bug 修复（1.1.1 → 1.1.2）
-- 支持**预发布版本**：
-    - `alpha`、`beta`、`rc` 等（如 `1.2.0-alpha.1`）
-- 支持**自定义版本号**：
-    - 可直接指定目标版本（如 `1.3.0`）
-- 支持 **--show-release** 预览：
-    - 在不修改文件的情况下查看即将升级到的版本
-
-版本更新后，工具会自动同步到后续的 Git Tag、GitHub Release 与 npm 发布流程。
-
-## Changelog
-
-基于 Git **Conventional Commits** 规范提交历史自动生成结构化 Changelog
-
-COMMIT_TYPES：
-
-- 默认：`feat | feature | fix | perf | revert | docs | style | chore | refactor | test | build | ci`
-- 自定义：`config | deps | security | i18n | ux | hotfix`
-
-| Effect          | Types                                                          | 说明                                |
-|-----------------|----------------------------------------------------------------|-----------------------------------|
-| **`bump`**      | `feat`, `feature`, `fix`, `perf`, `revert`                     | 影响版本号（Minor/Patch），同时写入 CHANGELOG |
-| **`changelog`** | `docs`, `refactor`, `deps`, `security`, `hotfix`, `i18n`, `ux` | 不影响版本号，仅写入 CHANGELOG              |
-| **`hidden`**    | `style`, `chore`, `test`, `build`, `ci`, `config`, `tool`      | 不影响版本号，也不会写入 CHANGELOG            |
-
-支持 **--show-changelog** 预览模式：
-
-- 仅展示用于生成 Changelog 的 Commits
-- 不会修改任何文件或提交历史
-
-## Git 自动化
-
-自动执行标准发布流程：
-
-**stage → commit → tag → push**
-
-并支持推送到**任意 Git 远程仓库**，适配单仓库与多仓库场景。
-
-
-## npm 发布（Trusted Publishing）
-
-工具会根据 `package.json` 中的 `publishConfig` 配置，将包发布到对应的 npm 仓库。
-
-```json
-{
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  }
-}
-```
-
-自 **2025 年 7 月** 起，GitHub CI 已支持 npm 的 **Trusted Publishing（可信发布）** + **OIDC**：
+## GitHub Action
 
-- ✅ 无需长期有效的 npm Token
-- ✅ 使用 OpenID Connect 进行身份验证
-- ✅ 自动生成 provenance（来源证明）
+本仓库也可作为 Action 使用。Action 要求配置文件定义 `project`，并使用 `github-token` 访问 GitHub API。`workflow` 的默认值为 `full`。
 
-适用于 CI/CD 场景下的**安全、无 Token** 自动化发布。
+```yaml
+name: Release
 
-支持配置发布前清理：
+on:
+  issue_comment:
+    types: [ created, deleted ]
+  push:
+    branches:
+      - master
 
-- 移除 `package.json` 中对发布无意义的字段
-- `README.md` 只保留主要内容
+permissions:
+  contents: write
+  pull-requests: write
 
-```ts
-// 默认配置
-export default defineConfig({
-  npm: {
-    cleanup: {
-      packageJson: true,
-      readme: false,
-      removeTempDir: true,
-    }
-  },
-})
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      
+      - uses: pnpm/action-setup@v6
+        with:
+          version: 12
+      
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org/
+          package-manager-cache: false
+      
+      - run: pnpm install --frozen-lockfile
+      
+      - uses: peiyanlu/release@master
+        with:
+          workflow: full
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          npm-token: ${{ secrets.NPM_TOKEN }}
 ```
 
-## GitHub Releases
-
-GitHub Release 可基于 Git Tag 自动创建，并支持附带：
-
-- **Release Notes（发布说明）**
-- **构建产物（Assets）**
-
-支持两种创建方式：
-
-1. **自动化方式**：使用 `GITHUB_TOKEN` 直接创建
-2. **手动方式**：通过 GitHub Web UI 创建（工具预填充字段）
-
-## Monorepo
-
-工具默认配置偏向于 **单仓库（Single Repo）** 项目，但是可以通过配置使其支持 **Monorepo**
-
-## 流程拆分
-
-### 本地准备 Release（仅创建 Tag）
-
-在本地完成版本确认与变更准备：
-
-- 确定下一个版本
-- 更新 `package.json` / `CHANGELOG`
-- 创建发布提交
-- 创建并推送 git 标签
-
-### CI/CD 自动发布（由 Tag 触发）
-
-当 Tag 推送到远端后，CI/CD 自动执行：
+确保仓库中已提交 `release.config.ts`，Action 会从检出的项目中加载该文件。若发布到 npm，将 `npm-token` 配置为仓库 secret；它会作为 `NODE_AUTH_TOKEN` 提供给发布步骤。也可在仓库配置 npm Trusted Publishing。
 
-- 发布到 npm
-- 创建 GitHub Release
+### npm Trusted Publishing
 
-### 示例用法
+[npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/) 使用 GitHub Actions 的 OIDC 身份发布 npm 包，不需要长期有效的 `NPM_TOKEN`。
 
-- 发布到 npm
+1. **确认条件**：包已至少发布过一个版本，使用公开 npm registry 和 GitHub 托管的 runner。Trusted Publisher 按包和 workflow 文件分别注册。
+2. **在 npm 注册发布者**：打开 [npmjs.com](https://www.npmjs.com/) 上对应包的 **Settings → Trusted Publisher → GitHub Actions**：填写 GitHub 用户或组织名、仓库名和 workflow 文件名（例如 `release.yml`）。
+   如果 workflow 使用 GitHub environment，也填写相同的 environment 名称。
+3. **调整发布 job**：在发布 job 中授予 `id-token: write` 权限，使用 Node.js 22.14.0 或更高版本，以确保 npm 版本为 11.5.1 或更高版本，并从 `actions/setup-node` 移除 `registry-url`（v7 以下），从 Action step 输入中移除 `npm-token`。例如：
 
-```ts
-// publishCI.ts
-
-import { publishTagToNpm } from '@peiyanlu/release'
-
-
-await publishTagToNpm({})
-```
+```yaml
+name: Release
 
-```json5
-// package.json
+on:
+  issue_comment:
+    types: [ created, deleted ]
+  push:
+    branches:
+      - master
 
-{
-  "scripts": {
-    "ci-publish": "tsx src/publishCI.ts"
-  }
-}
-```
-
-```yaml
-# .github/workflows/publish.yml
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write                                              # 新增
 
 jobs:
-  publish:
-    name: Publish
+  release:
     runs-on: ubuntu-latest
-    
     steps:
-      - name: Publish
-        run: npm i -g npm@^11.5.2 && pnpm run ci-publish "$REF_NAME"
-        env:
-          REF_NAME: ${{ github.ref_name }}
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      
+      - uses: pnpm/action-setup@v6
+        with:
+          version: 12
+      
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24                                     # npm 11.5.1+
+          registry-url: https://registry.npmjs.org/            # v7 以下移除
+          package-manager-cache: false
+      
+      - run: pnpm install --frozen-lockfile
+      
+      - uses: peiyanlu/release@master
+        with:
+          workflow: full
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          #npm-token: ${{ secrets.NPM_TOKEN }}                 # 移除
 ```
 
-- 创建 GitHub Release
+配置正确后，npm/pnpm 会自动通过 OIDC 认证，公开仓库发布的版本还会自动附带 provenance（来源证明），无需额外开启。
+
+若出现 `ENEEDAUTH`：
+核对 npm 包是否已存在、注册的仓库和 workflow 文件名、GitHub environment，以及发布 job 是否有 `id-token: write` 并使用满足版本要求的 npm CLI。
+
+### Snapshots
+
+为 `workflow_dispatch` 添加 `snapshot` 字符串输入：手动运行时输入非空值会执行快照 job；push 和 issue comment 事件没有该输入，因此仍按原有流程执行。
 
 ```yaml
-# .github/workflows/release.yml
+name: Release
+
+on:
+  issue_comment:
+    types: [ created, deleted ]
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+    inputs:
+      snapshot:
+        description: Snapshot publish tag.
+        type: string
 
 jobs:
+  check:
+    if: inputs.snapshot == ''
+    # 保留现有 check job 的其余配置
+  
+  pull-request:
+    needs: check
+    if: needs.check.outputs.workflow == 'pull-request'
+    # 保留现有 pull-request job 的其余配置
+  
   release:
-    name: Release
+    needs: check
+    if: needs.check.outputs.workflow == 'release'
+    # 保留现有 release job 的其余配置
+  
+  snapshot:
+    if: inputs.snapshot != ''
+    name: Snapshot
     runs-on: ubuntu-latest
-    
+    permissions:
+      contents: read
+      id-token: write
     steps:
-      - name: Release
-        uses: peiyanlu/release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      
+      - uses: pnpm/action-setup@v6
+        with:
+          version: 12
+      
+      - uses: actions/setup-node@v7
         with:
-          tag_name: ${{ github.ref_name }}
-          release_name: Release ${{ github.ref_name }}
-          body: |
-            Please refer to [CHANGELOG.md](./CHANGELOG.md) for details.
-          draft: false
+          node-version: 24
+          registry-url: https://registry.npmjs.org/
+          package-manager-cache: false
+      
+      - run: pnpm install --frozen-lockfile
+      
+      - uses: peiyanlu/release@master
+        with:
+          workflow: snapshot
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          bump-snapshot: ${{ inputs.snapshot }}
 ```
 
-## Dry Run
-
-```bash
-pnpm release --dry-run
-```
+在 GitHub Actions 页面手动运行 workflow 并填写 snapshot 为 canary：此时 `check`、`pull-request` 和 `release` 不执行，快照 job 发布 `1.2.0-canary.<timestamp>`。
 
-可以**完整展示发布流程，但不会执行任何实际修改**，适合调试和验证配置。
+Trusted Publisher 注册绑定到具体 workflow 文件。要让快照发布也使用同一注册，建议将快照 job 放在已注册的 workflow 中，而不是另建 workflow。
 
+### 参数
 
-## 相关链接
+`workflow` 支持：
 
-- [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers)
-- [GitHub Releases 官方文档](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases)
+| 值             | 行为                                              |
+|----------------|---------------------------------------------------|
+| `full`         | 创建发布 Pull Request，并在发布提交上执行发布     |
+| `pull-request` | 创建或更新发布 Pull Request                       |
+| `release`      | 执行发布提交对应的发布流程                        |
+| `snapshot`     | 发布临时快照版本                                  |
+| `check`        | 检查事件上下文，并输出是否继续及应执行的 workflow |
 
-[1]: #bump-版本号
+主要 Action 输入：
 
-[2]: #changelog
+| 输入                         | 说明                                                |
+|------------------------------|-----------------------------------------------------|
+| `github-token`               | 必填，GitHub API token                              |
+| `npm-token`                  | 可选，npm token                                     |
+| `workflow`                   | 工作流，默认 `full`                                 |
+| `checkout-branch`            | 发布分支，默认 `release-branch`                     |
+| `bump-version`               | 指定版本号                                          |
+| `bump-as`                    | 版本类型：`major`、`minor`、`patch` 或 `prerelease` |
+| `bump-prerelease`            | 预发布标识，如 `beta`                               |
+| `bump-snapshot`              | 快照版本标识                                        |
+| `bump-first-release`         | 是否按首次发布处理                                  |
+| `bump-skip`                  | 跳过版本升级                                        |
+| `bump-by-project`            | monorepo 各项目的版本升级选项 JSON                  |
+| `maintenance-branch-enabled` | 是否创建维护分支                                    |
+| `publish-skip`               | 跳过项目发布                                        |
+| `publish-access`             | npm access：`public` 或 `restricted`                |
+| `publish-tag`                | npm dist-tag 或 Action 发布别名                     |
 
-[3]: #git-自动化
+## Conventional Commits 与版本
 
-[4]: #npm-发布trusted-publishing
+工具根据提交历史和 Conventional Commits 生成变更日志并计算版本。通常 `feat` 触发 minor，`fix`、`perf` 等触发 patch，破坏性变更触发 major；文档、测试、构建等不一定产生版本升级。可使用 `--dry-run` 预览结果。
 
-[5]: #github-releases
+## 许可证
 
-[6]: #monorepo
+[MIT](./LICENSE)