@icebreakers/monorepo-templates 0.0.0

package/templates/unbuild/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@icebreakers/unbuild-template",
+  "type": "module",
+  "version": "0.0.0",
+  "description": "unbuild package template",
+  "author": "ice breaker <1324318532@qq.com>",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sonofmagic/monorepo-template.git",
+    "directory": "templates/unbuild"
+  },
+  "bugs": {
+    "url": "https://github.com/sonofmagic/monorepo-template/issues"
+  },
+  "keywords": [],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "unbuild --stub",
+    "build:watch": "unbuild --watch --sourcemap",
+    "build": "unbuild",
+    "test": "vitest run",
+    "test:dev": "vitest",
+    "release": "pnpm publish",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "publishConfig": {}
+}

package/templates/unbuild/src/index.ts

@@ -0,0 +1,9 @@
+export function foo() {
+  return 'bar'
+}
+
+export function getDirname() {
+  return __dirname
+}
+
+export { format } from '@/utils'

package/templates/unbuild/src/utils.ts

@@ -0,0 +1,3 @@
+export function format(str: string) {
+  return str.replaceAll(/[a-z]/g, s => s.toUpperCase())
+}

package/templates/unbuild/test/index.test.ts

@@ -0,0 +1,18 @@
+import { foo, format, getDirname } from '@/index'
+
+describe('index', () => {
+  it('foo bar', () => {
+    expect(foo()).toBe('bar')
+  })
+
+  it('format uppercases alphabetical characters', () => {
+    expect(format('abc-123')).toBe('ABC-123')
+  })
+
+  it('getDirname exposes template directory path', () => {
+    const dirname = getDirname()
+    expect(typeof dirname).toBe('string')
+    expect(dirname.length).toBeGreaterThan(0)
+    expect(dirname).toContain('unbuild')
+  })
+})

package/templates/unbuild/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": [
+        "src/*"
+      ]
+    }
+  },
+  "include": [
+    "src",
+    "test"
+  ]
+}

package/templates/unbuild/vitest.config.ts

@@ -0,0 +1,15 @@
+import path from 'node:path'
+import { defineProject } from 'vitest/config'
+
+export default defineProject({
+  test: {
+    alias: [
+      {
+        find: '@',
+        replacement: path.resolve(__dirname, './src'),
+      },
+    ],
+    globals: true,
+    testTimeout: 60_000,
+  },
+})

package/templates/vitepress/.vitepress/config.ts

@@ -0,0 +1,93 @@
+import Tailwindcss from '@tailwindcss/vite'
+import { defineConfig } from 'vitepress'
+import { withMermaid } from 'vitepress-plugin-mermaid'
+// https://vitepress.dev/reference/site-config
+export default withMermaid(defineConfig({
+  outDir: '../../dist',
+  title: 'icebreaker\'s monorepo',
+  description: 'icebreaker\'s monorepo. upgrade your monorepo',
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: '使用手册', link: '/' },
+      { text: '一些思考', link: '/thinking' },
+    ],
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/sonofmagic/monorepo-template' },
+    ],
+    outline: {
+      label: '目录',
+      level: [2, 3],
+    },
+    logo: '/logo.jpg',
+    sidebar: {
+      '/': [
+        { text: '使用手册', link: '/' },
+        { text: '一些思考', link: 'thinking' },
+        {
+          text: 'npm 发包',
+          base: '/why/',
+          items: [
+            { text: '如何复用 js 代码', link: '/how-to-reuse-js-code' },
+            { text: 'JS 文件的各种后缀', link: '/js-cjs-mjs' },
+            { text: 'CJS和ESM关键字/全局变量对比', link: '/js-keywords' },
+            { text: '什么是 npm 包', link: '/what-is-npm-package' },
+            { text: '如何发布 npm 包', link: '/publish-basic-npm-package' },
+            {
+              text: '改进并发布现代 npm 包',
+              link: 'index',
+              base: 'why/modern/',
+              items: [
+                { text: 'package entry points 字段', link: '/package-entry-points' },
+                { text: '添加 DTS', link: '/dts' },
+                { text: 'ESM vs CJS', link: '/esm-vs-cjs' },
+                { text: '使用 TypeScript', link: '/typescript' },
+                { text: '使用打包器', link: '/bundlers' },
+              ],
+            },
+          ],
+        },
+        {
+          text: 'Monorepo',
+          base: '/monorepo/',
+          items: [
+            { text: '为什么往 monorepo 方向演进', link: '/' },
+            { text: '如何管理 monorepo', link: '/manage' },
+            { text: 'monorepo 发包生成变更日志', link: '/publish' },
+          ],
+        },
+        {
+          text: '相关的工具',
+          base: '/tools/',
+          items: [
+            { text: 'pnpm', link: '/pnpm' },
+            { text: 'turborepo', link: '/turborepo' },
+            { text: 'changeset', link: '/changeset' },
+            { text: 'husky', link: '/husky' },
+            { text: 'lint-staged', link: '/lint-staged' },
+            { text: 'renovate', link: '/renovate' },
+          ],
+        },
+      ],
+    },
+    editLink: {
+      pattern: 'https://github.com/sonofmagic/monorepo-template/edit/main/apps/website/:path',
+      text: '为此页提供修改建议',
+    },
+  },
+  vite: {
+    plugins: [
+      // @ts-ignore
+      Tailwindcss(),
+    ],
+    // server: {
+    //   hmr: {
+    //     overlay: false,
+    //   },
+    // },
+  },
+  mermaid: {
+
+  },
+}),
+)

package/templates/vitepress/.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme'
+import './tailwind.css'
+
+export default DefaultTheme

package/templates/vitepress/.vitepress/theme/tailwind.css

@@ -0,0 +1 @@
+@import 'tailwindcss';

package/templates/vitepress/gitignore

@@ -0,0 +1 @@
+.vitepress/cache

package/templates/vitepress/index.md

@@ -0,0 +1,127 @@
+---
+layout: doc
+---
+
+# icebreaker's monorepo 模板
+
+整套模板围绕 **pnpm + Turborepo + TypeScript** 打造，帮助团队快速落地一个可维护、可编排、可持续迭代的 `monorepo` 工程。这里我们把使用方式拆成几个核心模块，方便你按需查阅。
+
+## 核心能力
+
+- **工作区管理**：`pnpm` workspace + Turborepo 任务编排，内置缓存和过滤能力。
+- **全链路 TypeScript**：所有模板（应用、类库、CLI）均使用 TS，并自带基础测试脚手架（`vitest`）。
+- **质量与规范**：集成 `eslint`、`stylelint`、`husky`、`commitlint`、`lint-staged`，开箱即用。
+- **自动化发布**：`changesets` + GitHub Actions + Dockerfile 模板，实现语义化发版和部署。
+- **命令行助手**：`@icebreakers/monorepo` CLI 提供创建、同步、升级、镜像等常用命令，可通过 `monorepo.config.ts` 自定义行为。
+
+## 快速上手
+
+1. **拉取模板**：[GitHub](https://github.com/sonofmagic/monorepo-template) 右上角 `Use this template`，或克隆源码。
+2. **安装依赖**：在 `pnpm-workspace.yaml` 所在目录执行 `pnpm install`（需要 Node.js ≥ 20，推荐 `npm i -g pnpm`）。
+3. **可选清理**：直接运行 `npx -y @icebreakers/monorepo@latest clean` 远程执行清理，移除演示包后再执行 `pnpm install`（避免依赖本地构建 `monorepo`）；如已安装依赖，也可使用 `pnpm script:clean`。
+4. **初始化元数据**：`pnpm script:init` 会批量更新 `package.json`、`README.md` 等公共信息。
+
+## 仓库结构速览
+
+| 目录                  | 描述                             |
+| --------------------- | -------------------------------- |
+| `templates/cli`       | TypeScript 编写的 CLI 模板       |
+| `templates/client`    | Vue 3 + Vite 客户端示例          |
+| `templates/server`    | 基于 Hono 的服务端模板           |
+| `templates/vitepress` | VitePress 文档站（即本网站源码） |
+| `templates/tsup`      | 使用 `tsup` 打包的库模板         |
+| `templates/unbuild`   | 使用 `unbuild` 打包的库模板      |
+| `templates/vue-lib`   | Vue 组件库模板                   |
+| `packages/monorepo`   | CLI 及配置同步工具，支持独立升级 |
+
+## 常用脚本
+
+| 命令                 | 说明                                                |
+| -------------------- | --------------------------------------------------- |
+| `pnpm script:clean`  | 清理演示仓库，保留最小模板                          |
+| `pnpm script:init`   | 同步初始化 `package.json`、`README.md` 等基础信息   |
+| `pnpm script:sync`   | 使用 `cnpm` 同步所有包到 npmmirror（需预装 `cnpm`） |
+| `pnpm script:mirror` | 为 VS Code 终端写入国内镜像环境变量                 |
+
+更多脚本可在根目录 `package.json` 中查看，命令介绍详见 [工具区](./tools/turborepo.md)。
+
+## CLI 命令概览
+
+```bash
+npx monorepo new           # 创建子包/应用
+npx -y @icebreakers/monorepo@latest clean  # 远程清理已勾选的子项目，避免依赖本地构建
+npx monorepo sync          # 同步所有包到 npmmirror
+npx monorepo mirror        # 写入 VS Code 镜像配置
+npx monorepo up            # 从最新模板同步配置文件
+npx monorepo ai create     # 生成 Agentic 任务提示词模板（支持输出到文件，可用别名 ai new）
+```
+
+示例：`npx monorepo ai create -o agentic-task.md -f`，可直接生成 Markdown 模板并覆盖旧文件。默认会写入 `agentic/prompts/<timestamp>/prompt.md`，同时生成一个按时间排序的目录，并会提示你确认或修改目录名称，方便后续补充图片等素材；也可以用别名 `npx monorepo ai new`.
+
+多文件场景：
+
+- `npx monorepo ai create --name checkout` 自动落盘到 `agentic/prompts/checkout.md`（默认目录可改）。
+- `npx monorepo ai create --tasks agentic/tasks.json -f` 读取 JSON 数组批量生成，适合多人协作收口任务。
+
+所有命令都支持在 `monorepo.config.ts` 中覆写默认行为，例如新增模板、修改同步命令、跳过 README 初始化等。配置示例见下文和 [配置中心说明](./monorepo/manage.md#使用-monorepo-configts-定制命令行为)。
+
+## 自定义配置：`monorepo.config.ts`
+
+```ts
+import { defineMonorepoConfig } from '@icebreakers/monorepo'
+
+export default defineMonorepoConfig({
+  commands: {
+    ai: {
+      baseDir: 'agentic/custom-prompts',
+      format: 'json',
+      force: true,
+      tasksFile: 'agentic/tasks.json',
+    },
+    create: {
+      defaultTemplate: 'cli',
+      renameJson: true,
+    },
+    clean: {
+      autoConfirm: true,
+      ignorePackages: ['docs'],
+    },
+    upgrade: {
+      skipOverwrite: true,
+      targets: ['.github', 'monorepo.config.ts'],
+    },
+  },
+})
+```
+
+更多可配置项详见 [管理指南](./monorepo/manage.md)。
+
+## 依赖与版本升级
+
+```bash
+pnpm up -rLi
+```
+
+- `-r`：递归遍历所有 workspace
+- `-L`：升级到最新版本
+- `-i`：交互式选择（推荐查看差异后再确认）
+
+## 自动化发布
+
+模板默认集成 [`changesets`](https://github.com/changesets/changesets) 与推荐的 GitHub Actions 工作流：
+
+1. 安装 [changeset-bot](https://github.com/apps/changeset-bot)。
+2. 在仓库设置中开启 `Actions` 的 `Read and write permissions` 并勾选允许创建 PR。
+3. 在 `Repository secrets` 中配置 `NPM_TOKEN`（若需要 Codecov 也可配置 `CODECOV_TOKEN`）。
+4. 运行 `pnpm changeset`、`pnpm changeset version`、`pnpm changeset publish` 完成发布；或交由 CI 自动执行。
+
+具体操作指南参见 [发包流程](./monorepo/publish.md)。
+
+## 更多资源
+
+- [为什么选择 monorepo？](./monorepo/index.md)
+- [pnpm workspaces 与 Turborepo 组合的优势](./monorepo/manage.md)
+- [工具链介绍](./tools/turborepo.md)
+- [常见思考与 FAQ](./thinking.md)
+
+> 欢迎结合自己的业务场景对模板做进一步裁剪与扩展，建议在自定义后保留 `monorepo.config.ts` 以便集中管理命令默认值。

package/templates/vitepress/monorepo/index.md

@@ -0,0 +1,46 @@
+# 为什么选择 Monorepo？
+
+随着项目复杂度提升，Node.js 团队越来越倾向于把多套服务、组件库、CLI 工具放在同一个仓库里。Monorepo 的核心价值在于 **集中管理依赖与流程**，从而让重构、协作、发布都更高效。
+
+## Monorepo 的主要收益
+
+| 维度     | 收益                                                               |
+| -------- | ------------------------------------------------------------------ |
+| 依赖管理 | `pnpm` 等工具会共享缓存、避免重复安装；严格依赖隔离杜绝“幽灵依赖”  |
+| 构建效率 | 借助 Turborepo 的缓存与依赖图，仅构建真正改动的包，CI 时间显著降低 |
+| 原子提交 | 一个提交即可跨多个模块同步改动，便于回滚与审计                     |
+| 协作体验 | 同一仓库统一配置、脚本与规范，减少跨项目跳转和环境差异             |
+| 可复用性 | 公共库、UI 组件、工具函数在 workspace 内即可本地引用并共享         |
+
+## 与 Polyrepo 的对比
+
+| Polyrepo 常见痛点                | Monorepo 的解决方式                                |
+| -------------------------------- | -------------------------------------------------- |
+| 每个仓库单独装依赖、重复维护脚本 | Workspace 共享依赖与脚本，一次配置多处使用         |
+| 同步多个仓库中的接口或配置       | 原子提交 + Turborepo 构建，修改一次即可全仓库生效  |
+| CI/CD 配置分散、发布流程冗长     | 基于 changesets 和统一仓库配置快速搭建自动化流水线 |
+| 大规模重构成本高                 | 搜索范围集中，易于批量修改、验证与回滚             |
+
+## 常见落地场景
+
+- **多端同仓**：Web、Server、CLI 共存，代码共享严格受控。
+- **组件库/工具链**：公共 API 与内部应用一起维护，避免版本漂移。
+- **微服务集成**：多个服务共享协议、类型定义，发布与部署流程统一。
+- **巨石拆分**：将原有大型项目拆成多个 package，逐步抽象并复用。
+
+## 迁移建议
+
+1. **先集中依赖**：把最常见的公共依赖和脚本统一到根目录，利用 `pnpm workspace` 管理版本。
+2. **逐步迁移模块**：按照业务领域或团队边界迁移子模块，保留原 CI 作为兜底。
+3. **引入构建缓存**：配置 Turborepo，使用 `turbo run <task> --filter=<scope>` 控制任务范围。
+4. **接入 changesets**：在迁移过程中就开始记录版本与变更，养成可发布的节奏。
+5. **通过 monorepo.config.ts 定制命令**：按团队习惯调整 `create` 模板、`clean` 行为、`upgrade` 目标等，提高可维护性。
+
+## 进一步阅读
+
+- [仓库管理实践](./manage.md) —— 如何将 pnpm + Turborepo + monorepo.config 协同使用。
+- [发包与变更日志](./publish.md) —— 使用 changesets 管理版本、自动化发布。
+- [工具专题](../tools/turborepo.md) —— 常用工具的配置与技巧。
+- [常见思考](../thinking.md) —— 关于模块拆分、包结构的经验分享。
+
+> Monorepo 不是银弹，但在需要大量复用、自动化、跨团队协作的场景下，它能显著提升工程效率。关键是配合合适的工具与规范，让拆分后的每个模块都有清晰的职责与边界。

package/templates/vitepress/monorepo/manage.md

@@ -0,0 +1,129 @@
+# 如何管理 monorepo
+
+本节结合模板实践，总结一套围绕 **pnpm + Turborepo + monorepo.config** 的管理方法：从依赖安装、任务调度到命令覆写，帮助团队高效协作。
+
+## 基础设施速览
+
+| 能力           | 工具                 | 要点                                                                        |
+| -------------- | -------------------- | --------------------------------------------------------------------------- |
+| Workspace 管理 | `pnpm`               | 内容寻址、硬链接，安装速度快、占用小；严格依赖隔离杜绝“幽灵依赖”            |
+| 任务编排       | `turborepo`          | 基于依赖图调度任务，支持并行与缓存，`turbo run build --filter=...` 精准执行 |
+| 命令自定义     | `monorepo.config.ts` | 使用 `c12` 加载，可对 create/clean/sync/upgrade/init/mirror 覆写默认行为    |
+
+## 日常操作流程
+
+### 1. 管理依赖
+
+```bash
+# 安装/更新
+pnpm install
+pnpm up -rLi
+
+# 查看依赖图
+pnpm ls --depth 2
+```
+
+- `pnpm install` 自动按 workspace 复用依赖。
+- `pnpm up -rLi` 交互式升级所有包，`-L` 为最新版本，`-i` 逐项确认。
+
+### 2. 调度构建与测试
+
+```bash
+# 全量构建 / 测试
+pnpm build
+pnpm test
+
+# 只构建受影响的包
+pnpm build --filter={templates/client}
+
+# 观察执行计划
+pnpm exec turbo run build --dry=json | jq '.'
+```
+
+Turborepo 会缓存任务输出：
+
+| 构建场景       | 全量（首次） | 增量（未改动） |
+| -------------- | ------------ | -------------- |
+| 传统脚本       | 120s         | 120s           |
+| Turbo 本地缓存 | 120s         | **≈5s**        |
+| Turbo 远程缓存 | 120s         | **≈2s**        |
+
+> 建议在 CI 中启用远程缓存（Vercel/Turbo Cloud 或自建存储）进一步缩短时间。
+
+### 3. 自定义命令行为
+
+使用 `defineMonorepoConfig` 即可集中覆写：
+
+```ts
+import { defineMonorepoConfig } from '@icebreakers/monorepo'
+
+export default defineMonorepoConfig({
+  commands: {
+    create: {
+      templatesDir: './custom-templates',
+      templateMap: {
+        'cloud-function': {
+          source: 'functions/cloud',
+          target: 'apps/functions/cloud',
+        },
+      },
+      choices: [
+        { value: 'cli', name: 'CLI 模板' },
+        { value: 'cloud-function', name: '云函数模板' },
+      ],
+    },
+    sync: {
+      command: 'cnpm sync {name}',
+      concurrency: 4,
+    },
+    clean: {
+      autoConfirm: true,
+      pinnedVersion: '^2.0.0',
+    },
+  },
+})
+```
+
+常用配置项：
+
+| 命令      | 可覆盖字段                                                                         | 说明                                                                                        |
+| --------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `create`  | `templatesDir` / `templateMap` / `choices` / `defaultTemplate`                     | 扩展模板来源、修改提示内容                                                                  |
+| `clean`   | `autoConfirm` / `ignorePackages` / `includePrivate` / `pinnedVersion`              | 控制交互、过滤包、锁定依赖版本                                                              |
+| `sync`    | `concurrency` / `command` / `packages`                                             | 定义同步命令与并发度                                                                        |
+| `upgrade` | `targets` / `mergeTargets` / `scripts` / `skipChangesetMarkdown` / `skipOverwrite` | 改写配置同步策略                                                                            |
+| `init`    | `skipReadme` / `skipPkgJson` / `skipChangeset`                                     | 按需跳过初始化步骤                                                                          |
+| `mirror`  | `env`                                                                              | 注入镜像环境变量                                                                            |
+| `ai`      | `output` / `format` / `force` / `baseDir` / `tasksFile`                            | 预设 Agentic 模板输出目录、格式与批量任务，默认写入 `agentic/prompts/<timestamp>/prompt.md` |
+
+更多细节可参考 CLI 命令文档或源码中的 `commands/*`。
+
+### 4. 依赖升级 / 配置同步
+
+```bash
+npx monorepo up           # 使用本地 CLI
+npx @icebreakers/monorepo@latest up  # 直接使用远端 CLI
+
+# 常用参数
+# -c, --core  仅同步核心配置，排除 GitHub 相关文件
+# -i          以交互方式筛选文件
+# -s          跳过新增，仅覆盖已存在文件
+```
+
+升级 CLI 后再执行 `up`，可以同步获得模板最新的工作流、脚手架与配置。
+
+## 常见问题与建议
+
+- **依赖冲突**：使用 `pnpm why <pkg>` 定位冲突来源，优先升级上游依赖或将共享依赖提升到顶层。
+- **缓存命中率低**：确认是否使用了 `turbo run <task> --filter` 以及 `dependsOn` 配置是否准确，必要时开启远程缓存。
+- **CI 时间长**：结合 `pnpm fetch` 预拉取依赖，配合 `turbo` 缓存，通常能把 pipeline 压缩到原来的 1/3。
+- **命令行为差异**：将所有自定义行为写入 `monorepo.config.ts`，避免脚本散落多处难以维护。
+
+## 进一步阅读
+
+- [为什么越来越多团队迁移到 monorepo？](./index.md)
+- [changesets 发包指南](./publish.md)
+- [工具篇：pnpm、Turborepo、Changesets 等](../tools/turborepo.md)
+- [常见思考与实践](../thinking.md)
+
+> 小提示：在迁移现有项目时，可以先把最常变的模块放进 monorepo，再逐步收拢其它仓库，配合 `monorepo.config.ts` 就能实现平滑衔接。

package/templates/vitepress/monorepo/publish.md

@@ -0,0 +1,142 @@
+# monorepo 发包与变更日志
+
+本模板推荐使用 [`changesets`](https://github.com/changesets/changesets) 管理版本、生成 `CHANGELOG` 并发布 npm 包。它针对 monorepo 场景设计，维护活跃，易于与 CI/CD 集成。
+
+## 为什么选 changesets？
+
+| 场景         | changesets 能力                                               |
+| ------------ | ------------------------------------------------------------- |
+| 精确记录改动 | 每次变更生成独立的 changeset 文件，说明影响的包与语义版本类型 |
+| 自动生成日志 | 基于 changeset 内容生成结构化的 `CHANGELOG.md`                |
+| 语义化版本   | 支持 `major` / `minor` / `patch`，并处理依赖联动升级          |
+| 自动化发布   | 可在 CI 中自动创建版本 PR 或直接发布到 npm                    |
+
+## 推荐流程
+
+> 以下命令默认在仓库根目录执行。
+
+### 1. 初始化
+
+```bash
+pnpm add -D @changesets/cli
+pnpm changeset init
+```
+
+生成 `.changeset/` 目录，用于存放配置与变更记录。
+
+### 2. 记录变更
+
+```bash
+pnpm changeset
+```
+
+按照提示：
+
+1. 选择受影响的包。
+2. 指定版本类型（`patch` / `minor` / `major`）。
+3. 填写 changelog 描述。
+
+示例输出：
+
+```md
+---
+"@my/utils": minor
+"@my/ui": patch
+---
+
+- feat(utils): 新增时间处理工具
+- fix(ui): 修复按钮颜色
+```
+
+### 3. 升级版本并生成 changelog
+
+```bash
+pnpm changeset version
+```
+
+命令会自动：
+
+- 更新受影响包的 `package.json` 版本。
+- 调整内部依赖引用。
+- 为每个包写入或追加 `CHANGELOG.md`。
+
+### 4. 发布到 npm
+
+```bash
+pnpm changeset publish
+```
+
+changesets 会只发布有改动的包，并按照依赖顺序执行。
+
+### 5. GitHub Actions 自动化（可选）
+
+结合 `changesets/action` 实现自动创建发布 PR 或直接发布：
+
+```yaml
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+  id-token: write
+
+env:
+  HUSKY: 0
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          # 这是为了使用新版本的 npm, 只有 npm@11.5.x 以上版本才支持 OIDC
+          # 否则你就必须使用 npm i -g npm@latest 来升级 npm 版本
+          node-version: 24
+          cache: pnpm
+          registry-url: https://registry.npmjs.org
+      - run: pnpm install
+      - name: Create Release Pull Request or Publish to npm
+        uses: changesets/action@v1
+        with:
+          publish: pnpm publish-packages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # npm/action-oidc-auth 会设置 NODE_AUTH_TOKEN 供 publish 使用
+```
+
+`pnpm publish-packages` 为模板内脚本，可替换为自定义构建+发布流程。
+
+> 说明：npm 现行 token 默认 90 天过期，推荐在 CI 中使用 OIDC（如上）动态获取 `NODE_AUTH_TOKEN`，无需手动传入 `NPM_TOKEN`。若使用自托管或其他 CI，需要确保工作流具备 `id-token: write` 权限。
+
+## 与其他方案对比
+
+| 能力 / 工具    | changesets | lerna 经典模式 | 手写脚本 |
+| -------------- | ---------- | -------------- | -------- |
+| 支持多包       | ✅         | ✅             | ❌       |
+| 自动 changelog | ✅         | 部分支持       | ❌       |
+| 逐条记录变更   | ✅         | ❌             | ❌       |
+| 维护活跃度     | 高         | 低             | 需自养   |
+| CI/CD 集成     | 简单       | 相对繁琐       | 完全手工 |
+
+## 常见问题 FAQ
+
+- **是否可与 `monorepo.config.ts` 联动？** 配置文件主要用于 CLI 行为定制，发布流程仍由 changesets 主导，两者互不冲突。
+- **为何 `CHANGELOG` 没生成？** 确认是否执行了 `pnpm changeset version` 并提交了 `.changeset` 文件。
+- **如何避免发布某些包？** 在创建 changeset 时不勾选即可，或将包标记为 `private: true`。
+
+## 相关资源
+
+- [changesets 官方文档](https://github.com/changesets/changesets)
+- [模板中的发布工作流示例](https://github.com/sonofmagic/monorepo-template/blob/main/.github/workflows/release.yml)
+- [管理指南：pnpm + Turborepo + monorepo.config](./manage.md)
+
+> 小提示：在 PR 合并前先执行 `pnpm changeset version` 并提交结果，可以在代码审查阶段提前暴露发布影响，避免遗漏。