@icebreakers/monorepo-templates 1.1.0 → 1.2.1

package/templates/vitepress/zh/ai/llms-txt.md

@@ -0,0 +1,42 @@
+---
+description: 使用 llms.txt 为大语言模型提供更易读取的 repoctl 文档入口。
+---
+
+# AI 文档入口：llms.txt
+
+`llms.txt` 是面向大语言模型的文档入口文件。它把站点中的关键页面整理成更适合模型读取的 Markdown 索引，便于 AI 工具在回答 repoctl、pnpm workspace、Turborepo 和模板用法相关问题时快速定位上下文。
+
+本站通过 `vitepress-plugin-llms` 在构建阶段自动生成这些文件：
+
+| 文件             | 用途                             |
+| ---------------- | -------------------------------- |
+| `/llms.txt`      | 文档索引，列出可供模型读取的页面 |
+| `/llms-full.txt` | 把站点文档合并成单个文本文件     |
+| 页面 `.md` 文件  | 保留每个页面内容的 Markdown 版本 |
+
+## 1. 使用方式
+
+访问 `https://repo.icebreaker.top/llms.txt` 可以获取当前文档的 LLM 索引。如果需要一次性提供完整上下文，可以使用 `https://repo.icebreaker.top/llms-full.txt`。
+
+当你在 Cursor、Claude Code、Codex 或其他 AI 编程工具里引用 repoctl 文档时，优先提供 `llms.txt`，再按需要补充具体页面链接。
+
+## 2. 维护约定
+
+新增重要文档页面时，在 frontmatter 中补充 `description`。构建插件会把描述写入 `llms.txt` 的链接说明中，让模型更容易判断每个页面的用途。
+
+```md
+---
+description: 说明这个页面解决的问题和适用场景。
+---
+```
+
+## 3. 页面组织建议
+
+AI 入口应该保持显眼，但不要替代正常文档结构：
+
+| 页面类型                               | 推荐位置                             |
+| -------------------------------------- | ------------------------------------ |
+| repoctl 命令、校验、诊断、报告         | `/repoctl/`                          |
+| monorepo 和 npm 包基础知识             | `/knowledge/`、`/monorepo/`、`/why/` |
+| pnpm、Turborepo、versioning 等工具专题 | `/tools/`                            |
+| llms.txt 和 AI 工具读取约定            | `/ai/`                               |

package/templates/vitepress/zh/getting-started.md

@@ -0,0 +1,40 @@
+# 新手使用指南
+
+这篇旧入口已经收敛到 repoctl 主线。新读者建议直接阅读：
+
+- [repoctl 快速开始](./repoctl/getting-started.md)
+- [repoctl 命令速查](./repoctl/commands.md)
+- [repoctl 配置文件](./repoctl/config.md)
+
+## 先这样用
+
+```bash
+pnpm add -D repoctl
+pnpm exec repo init
+pnpm exec repo doctor
+pnpm exec repo new
+pnpm exec repo check
+```
+
+模板生成仓库里可以使用更短的根脚本：
+
+```bash
+pnpm run repo:init
+pnpm doctor
+pnpm new
+pnpm check
+```
+
+## 知识点保留
+
+理解工具前，先理解这几个边界：
+
+| 命令           | 解决的问题                                            |
+| -------------- | ----------------------------------------------------- |
+| `repo init`    | 补齐仓库默认脚本、workspace patterns 和基础工具链入口 |
+| `repo doctor`  | 判断仓库当前是否可用，并输出可保存的诊断报告          |
+| `repo new`     | 从内置模板创建包、应用、服务、文档站或 CLI            |
+| `repo check`   | 预览或执行提交前推荐校验                              |
+| `repo upgrade` | 同步模板最新标准资产                                  |
+
+如果你是在学习 monorepo 的基础概念，可以继续看 [为什么往 monorepo 方向演进](./monorepo/index.md)。

package/templates/vitepress/zh/index.md

@@ -0,0 +1,66 @@
+---
+layout: home
+
+hero:
+  name: repoctl
+  text: 让 pnpm monorepo 的日常操作更短、更稳
+  tagline: 用一套 CLI 管理初始化、诊断、创建模板、提交前校验和模板资产同步。
+  image:
+    src: /logo.jpg
+    alt: repoctl logo
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /zh/repoctl/getting-started
+    - theme: alt
+      text: 命令速查
+      link: /zh/repoctl/commands
+    - theme: alt
+      text: AI 文档入口
+      link: /zh/ai/
+
+features:
+  - title: 从已有仓库开始
+    details: 安装 repoctl 后运行 setup 和 doctor，先把 workspace、根脚本、配置冲突和提交链路检查清楚。
+  - title: 用模板创建包和应用
+    details: repo new 支持交互式创建、指定模板、dry-run、JSON 输出和创建计划落盘。
+  - title: 把质量门禁变成日常命令
+    details: repo check 统一预览和执行 lint、typecheck、build、test、tsd 等推荐校验。
+  - title: 给 AI 工具的文档入口
+    details: 构建时自动生成 llms.txt、llms-full.txt 和页面 Markdown，让 AI 编程工具更容易读取 repoctl 文档。
+---
+
+## 最短路径
+
+```bash
+pnpm add -D repoctl
+pnpm exec repo init
+pnpm exec repo doctor
+pnpm exec repo new
+pnpm exec repo check
+```
+
+在由 repoctl 创建或初始化的仓库里，同一套工作流会暴露成更短的根脚本：
+
+```bash
+pnpm run repo:init
+pnpm run repo:doctor
+pnpm run repo:new
+pnpm run repo:check
+```
+
+## 你可以继续阅读
+
+- [repoctl 概览](./repoctl/index.md)
+- [快速开始](./repoctl/getting-started.md)
+- [接入已有仓库](./repoctl/adopt-existing.md)
+- [按场景选命令](./repoctl/scenarios.md)
+- [执行模型](./repoctl/execution-model.md)
+- [命令速查](./repoctl/commands.md)
+- [校验链路](./repoctl/checks.md)
+- [doctor 诊断](./repoctl/doctor.md)
+- [配置文件](./repoctl/config.md)
+- [模板与创建](./repoctl/templates.md)
+- [模板资产治理](./repoctl/template-assets.md)
+- [工作流与 CI](./repoctl/workflows.md)
+- [报告与自动化输出](./repoctl/reports.md)

package/templates/vitepress/zh/knowledge/index.md

@@ -0,0 +1,50 @@
+---
+description: repoctl 文档站的知识库入口，汇总 monorepo 管理、现代 npm 包和 JavaScript 模块化基础。
+---
+
+# 知识库
+
+知识库用于解释 repoctl 背后的工程背景。这里不放命令速查，而是回答为什么要这样组织仓库、包、构建和发布流程。
+
+## 1. monorepo 主题
+
+| 页面                                               | 适合解决的问题                     |
+| -------------------------------------------------- | ---------------------------------- |
+| [为什么往 monorepo 方向演进](../monorepo/index.md) | 判断多包仓库是否值得合并管理       |
+| [如何管理 monorepo](../monorepo/manage.md)         | 理解 workspace、任务编排和依赖边界 |
+| [发包与变更日志](../monorepo/publish.md)           | 设计 pnpm intent、版本和发布链路   |
+| [monorepo 命令参考](../monorepo/commands.md)       | 查看通用 monorepo 操作命令         |
+| [monorepo 模板体系](../monorepo/templates.md)      | 理解模板如何减少重复初始化         |
+| [monorepo 排障](../monorepo/troubleshooting.md)    | 排查依赖、构建、类型和发布问题     |
+
+## 2. 现代 npm 包主题
+
+| 页面                                                   | 适合解决的问题                     |
+| ------------------------------------------------------ | ---------------------------------- |
+| [如何复用 js 代码](../why/how-to-reuse-js-code.md)     | 从复制文件演进到发布包             |
+| [什么是 npm 包](../why/what-is-npm-package.md)         | 理解 package.json、入口和安装方式  |
+| [如何发布 npm 包](../why/publish-basic-npm-package.md) | 走通最小 npm 发布流程              |
+| [改进并发布现代 npm 包](../why/index.md)               | 把普通包升级成更规范的现代包       |
+| [现代包指南](../why/modern/index.md)                   | 汇总类型、入口、模块格式和构建工具 |
+
+## 3. 阅读顺序
+
+如果你第一次接触 monorepo，建议按下面顺序阅读：
+
+```txt
+为什么 monorepo
+  -> 如何管理 monorepo
+  -> 什么是 npm 包
+  -> 现代包指南
+  -> 发包与变更日志
+```
+
+如果你已经在维护仓库，可以直接从具体问题进入：
+
+| 你遇到的问题                  | 建议入口                                        |
+| ----------------------------- | ----------------------------------------------- |
+| workspace 包互相引用不清楚    | [如何管理 monorepo](../monorepo/manage.md)      |
+| 不确定 CJS、ESM、types 怎么配 | [现代包指南](../why/modern/index.md)            |
+| 发布后使用方拿不到类型        | [类型声明](../why/modern/dts.md)                |
+| 包入口太多、导入路径混乱      | [包入口](../why/modern/package-entry-points.md) |
+| CI 和发版流程容易漂移         | [发包与变更日志](../monorepo/publish.md)        |

package/templates/vitepress/zh/monorepo/commands.md

@@ -0,0 +1,21 @@
+# 命令速查
+
+repoctl 现在是这套文档的主线。完整命令说明请阅读：
+
+- [repoctl 命令速查](../repoctl/commands.md)
+- [repoctl 模板与创建](../repoctl/templates.md)
+- [repoctl 排障与报告](../repoctl/troubleshooting.md)
+
+## monorepo 知识点：为什么要统一命令入口
+
+monorepo 的难点通常不是“能不能跑某个工具”，而是团队成员是否能稳定地用同一套入口完成日常动作。
+
+repoctl 把命令分成三层：
+
+| 层级     | 示例                                         | 适合场景             |
+| -------- | -------------------------------------------- | -------------------- |
+| 根脚本   | `pnpm run repo:doctor` / `pnpm run repo:new` | 日常开发和团队教程   |
+| 主 CLI   | `pnpm exec repo doctor`                      | CI、脚本、排障和文档 |
+| 分组命令 | `repo ws ls` / `repo env support`            | 维护者和自动化       |
+
+保留这个旧页面，是为了让已有链接继续可用，同时把读者导向新的 repoctl 命令文档。

package/templates/vitepress/zh/monorepo/index.md

@@ -0,0 +1,115 @@
+# 为什么往 monorepo 方向演进
+
+选择 monorepo，不是为了“更先进”，而是为了把多包协作里最常见的重复劳动砍掉。
+
+当你的仓库里同时存在应用、类库、CLI、文档站，或者多个团队要共享同一套类型、配置、脚手架时，monorepo 的收益会很快超过它的管理成本。
+
+## repoctl 面向的真实问题
+
+### 1. 依赖和脚本不再分散
+
+在 polyrepo 里，最常见的问题不是代码本身，而是：
+
+- 每个仓库都要单独装依赖
+- 每个仓库都维护一套 lint / typecheck / test 脚本
+- 同样的工具链升级要重复做很多次
+- 团队成员很难判断哪个仓库的规范才是“当前标准”
+
+在 monorepo 里，这些东西可以收敛到一个根目录。
+
+### 2. 跨包改动可以原子提交
+
+如果一个接口变更同时影响：
+
+- `packages/types`
+- `packages/sdk`
+- `apps/web`
+- `apps/server`
+
+那么在 monorepo 里，一次提交就能把它们一起改完、一起验证、一起回滚。对重构和版本审计都更友好。
+
+### 3. 构建与测试更容易增量化
+
+`pnpm` 负责 workspace 依赖管理，`turborepo` 负责任务编排和缓存，结果就是：
+
+- 没改动的包不需要重复构建
+- CI 可以按依赖图只跑受影响任务
+- 大仓库也能保持比较稳定的反馈速度
+
+## repoctl 的工程立场
+
+这不是一个“什么都能配”的框架，而是一套偏实战、偏收敛的默认值：
+
+| 维度     | 默认选择                                |
+| -------- | --------------------------------------- |
+| 包管理   | `pnpm workspace`                        |
+| 任务编排 | `turborepo`                             |
+| 语言     | TypeScript 优先                         |
+| 校验链路 | ESLint + Stylelint + typecheck + Vitest |
+| 提交规范 | Husky + lint-staged + commitlint        |
+| 发包     | pnpm versioning                         |
+| 命令入口 | `repo` 为主，`repoctl` 为完整包名入口   |
+
+这些选择的目的只有一个：减少“每个项目重新想一遍”的成本。
+
+## 什么时候适合用 monorepo
+
+下面这些情况，适合直接上：
+
+- 你要同时维护多个 npm 包
+- 你有前后端、CLI、文档站共用一套类型或工具
+- 你希望升级脚本、工程化配置时一次同步全仓
+- 你有持续重构、跨包联动改动的需求
+
+下面这些情况，不一定值得上：
+
+- 只有一个很小的应用，没有共享代码需求
+- 团队还没有接受统一规范的准备
+- 构建链路本身还不稳定，先统一仓库只会放大问题
+
+## repoctl 提供的补位能力
+
+单纯有 monorepo 还不够，真正难的是“如何让它易用”。repoctl 补充了三层能力：
+
+### 1. 更短的日常命令
+
+```bash
+pnpm exec repo init
+pnpm exec repo doctor
+pnpm run repo:new
+pnpm run repo:check
+```
+
+不用先背完整 CLI，先把日常路径跑顺。
+
+### 2. `repo doctor` 这种面向新人的诊断命令
+
+它会直接回答这些问题：
+
+- 你是不是站在仓库根目录
+- `pnpm-workspace.yaml` 在不在
+- Node 版本对不对
+- 有没有安装 CLI 依赖
+- 根脚本齐不齐
+- 是否仍残留已废弃的 `monorepo.config.ts`
+- Husky / lint-staged 链路是不是半残状态
+
+### 3. `repo upgrade` 这种面向存量仓库的同步命令
+
+当受管默认值变化时，你不需要手抄配置，只要选择性同步标准资产。
+
+## 实际收益通常体现在这里
+
+| 场景         | Polyrepo 常见成本  | Monorepo 常见收益      |
+| ------------ | ------------------ | ---------------------- |
+| 工具链升级   | 多仓重复改配置     | 一次升级，多包受益     |
+| 共享类型变更 | 多仓分别发版联调   | 一次改动，一次验证     |
+| CI 反馈      | 每仓重复跑全量     | 利用缓存和依赖图做增量 |
+| 新人接手     | 先理解多个仓库差异 | 先理解一套统一约定     |
+
+## 继续阅读
+
+- [如何管理 monorepo](./manage.md)
+- [命令速查](./commands.md)
+- [排障指南](./troubleshooting.md)
+- [发包与变更日志](./publish.md)

package/templates/vitepress/zh/monorepo/manage.md

@@ -0,0 +1,243 @@
+# 如何管理 monorepo
+
+这一页是 repoctl 文档后面的知识库页面。它不再重新解释所有命令参数，而是解释：为什么这些命令能让 monorepo 日常管理变简单。
+
+如果你只想查命令，直接看 [repoctl 工作流与 CI](../repoctl/workflows.md) 或 [repoctl 命令速查](../repoctl/commands.md)。
+
+## 先记住默认工作流
+
+```bash
+pnpm install
+pnpm exec repo doctor
+pnpm run repo:new
+pnpm run repo:check
+pnpm build
+```
+
+大多数场景里，这已经够了。
+
+如果你在接入一个旧仓库，再多加一步：
+
+```bash
+pnpm exec repo init
+```
+
+这个工作流背后的顺序是：
+
+| 阶段 | 目标                                             |
+| ---- | ------------------------------------------------ |
+| 安装 | 让 workspace 依赖和本地包链接完整                |
+| 诊断 | 先确认仓库结构、Node、脚本、配置和提交链路可用   |
+| 创建 | 用模板生成新包，减少手写 package metadata 和配置 |
+| 校验 | 在提交前复现默认 hook 和 workspace typecheck     |
+| 构建 | 最后再跑更重的全仓任务                           |
+
+## 命令分层
+
+repoctl 刻意把日常入口收敛到少量任务型命令。
+
+### 第一层：根脚本
+
+这是最推荐的入口：
+
+```bash
+pnpm exec repo init
+pnpm run repo:new
+pnpm exec repo doctor
+pnpm run repo:check
+```
+
+适合：
+
+- 新人
+- 日常开发
+- 文档教程
+- 团队内部统一约定
+
+### 第二层：主 CLI
+
+当你要明确告诉别人“这是 CLI 行为，不只是 package.json 脚本”时，用：
+
+```bash
+pnpm exec repo init
+pnpm exec repo new
+pnpm exec repo doctor
+pnpm exec repo check
+pnpm exec repo upgrade
+```
+
+### 第三层：分组命令
+
+更细的高级操作保留在分组里：
+
+```bash
+repo workspace upgrade
+repo ws up
+repo tooling init eslint vitest
+repo tg init --all
+repo skills sync --codex
+repo ai prompt create --name checkout
+```
+
+## 日常任务对照表
+
+| 你想做什么             | 推荐命令                        | 说明                                                 |
+| ---------------------- | ------------------------------- | ---------------------------------------------------- |
+| 初始化一个刚接入的仓库 | `pnpm exec repo init`           | 同步推荐的仓库元信息和基础工程化配置                 |
+| 看仓库当前状态是否健康 | `pnpm exec repo doctor`         | 先排根目录、Node、脚本、遗留配置、提交链路           |
+| 创建一个新的包或应用   | `pnpm run repo:new`             | 支持交互式选择，也支持 `-- --template`               |
+| 提交前做本地校验       | `pnpm run repo:check`           | 默认对齐推荐 pre-commit / pre-push 逻辑              |
+| 同步模板最新标准资产   | `pnpm exec repo upgrade`        | 适合模板升级、老仓库补齐                             |
+| 清理演示仓库或非必要包 | `pnpm exec repo ws clean --yes` | 零安装也可以用 `pnpm dlx repo@latest ws clean --yes` |
+
+## `doctor`、`check`、`upgrade` 的边界
+
+这是最容易混淆的三个命令。
+
+### `doctor`
+
+偏“仓库体检”。
+
+它不关心你当前改了什么代码，而是关心：
+
+- 这个仓库是不是完整
+- 当前目录是不是根目录
+- 当前机器的 Node 版本能不能跑
+- 命令入口和配置文件是不是一致
+
+### `check`
+
+偏“提交前校验”。
+
+它更像一个人工触发的推荐检查入口，适合：
+
+- 提交前自查
+- 怀疑 lint / typecheck / hooks 有问题时快速复现
+- 用 `repo check --dry-run`、`repo check --json --out reports/check-plan.json` 或 `repo check --markdown --redact --out reports/check-plan.md` 先确认校验路由
+
+### `upgrade`
+
+偏“模板资产同步”。
+
+它解决的是：
+
+- 模板最新默认脚本要不要补进来
+- 工作流、配置文件、GitHub 资产要不要同步
+- 存量仓库要不要追上现在的标准
+
+## 配置推荐
+
+推荐只保留一个文件：
+
+```ts
+// repoctl.config.ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    create: {
+      defaultTemplate: 'tsdown',
+    },
+    clean: {
+      autoConfirm: true,
+    },
+    upgrade: {
+      skipOverwrite: true,
+    },
+  },
+})
+```
+
+说明：
+
+- 优先使用 `repoctl.config.ts`
+- `monorepo.config.ts` 已不再加载
+- 两者不能同时存在
+
+如果同时存在，现在 CLI 会直接报错，`repo doctor` 也会把它判成阻塞项。
+
+## `new` 的推荐用法
+
+### 交互式
+
+```bash
+pnpm run repo:new
+```
+
+适合第一次使用模板、想先看看有哪些模板可选。
+
+### 直接指定模板
+
+```bash
+pnpm exec repo new docs --template vitepress
+pnpm exec repo new sdk --template tsdown
+```
+
+适合你已经明确知道要创建什么。
+
+### 固化团队默认模板
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    create: {
+      defaultTemplate: 'tsdown',
+    },
+  },
+})
+```
+
+设置后：
+
+```bash
+pnpm exec repo new utils
+```
+
+会直接按默认模板生成，不再额外询问模板类型。
+
+## 默认提交链路
+
+如果你保留模板默认生成的 `.husky` 与 `lint-staged.config.js`，通常会得到这条链路：
+
+| 阶段         | 默认行为                                                                |
+| ------------ | ----------------------------------------------------------------------- |
+| `pre-commit` | 聚焦 staged 文件运行 `stylelint`、`eslint`、workspace `typecheck`       |
+| `pre-push`   | 运行整仓 `lint`、`typecheck`，再补跑受影响包的 `build` / `test` / `tsd` |
+
+这也是为什么：
+
+- `pnpm exec repo doctor` 会检查 Husky 与 lint-staged 是否同时存在
+- `pnpm run repo:check` 会成为最自然的人工入口
+
+## 依赖与构建建议
+
+```bash
+pnpm install
+pnpm up -rLi
+pnpm build
+pnpm test
+```
+
+- `pnpm install`：统一安装 workspace 依赖
+- `pnpm up -rLi`：交互式升级依赖
+- `pnpm build` / `pnpm test`：让 Turborepo 帮你做任务编排与缓存
+
+## 工具层 API 什么时候用
+
+如果你只是要使用默认 CLI，不需要直接碰 `@icebreakers/monorepo/tooling`。
+
+只有下面两种情况建议直接使用：
+
+- 你要在仓库里手写 tooling wrapper 配置
+- 你在维护这套 CLI / 模板本身
+
+其余大多数团队，停留在 `repoctl.config.ts` 这一层就够了。
+
+## 继续阅读
+
+- [repoctl 工作流与 CI](../repoctl/workflows.md)
+- [repoctl 命令速查](../repoctl/commands.md)
+- [repoctl 排障与报告](../repoctl/troubleshooting.md)
+- [发包与变更日志](./publish.md)

package/templates/vitepress/zh/monorepo/publish.md

@@ -0,0 +1,87 @@
+# monorepo 发包与变更日志
+
+repoctl 默认使用 pnpm 原生 versioning。它保留 Changesets 格式的变更意图，同时把版本计算、依赖传播、changelog 和发布收进 pnpm 本身。
+
+## 日常流程
+
+先完成质量校验，再记录变更：
+
+```bash
+pnpm build
+pnpm lint
+pnpm typecheck
+pnpm tsd
+pnpm test
+pnpm change
+pnpm change status
+```
+
+变更意图文件放在 `.changeset/*.md`，描述受影响包和 patch/minor/major。不要手动修改包版本。
+
+## Release PR
+
+main push 会运行：
+
+```bash
+pnpm version -r --dry-run
+pnpm version -r
+```
+
+CI 将版本号、各包 `CHANGELOG.md` 和 `.changeset/ledger.yaml` 提交到 Release PR。合并 Release PR 后，下一次 main push 执行：
+
+```bash
+pnpm publish -r --report-summary --provenance --no-git-checks
+```
+
+pnpm 根据 registry 中已有的版本自动跳过已发布包。CI 读取 `pnpm-publish-summary.json` 创建 `package@version` tag 和 GitHub Release，发布操作可以安全重试。
+
+## Workspace versioning 配置
+
+根 `pnpm-workspace.yaml` 中的关键配置：
+
+```yaml
+versioning:
+  fixed:
+    - ['@icebreakers/monorepo', repoctl]
+  ignore:
+    - '@icebreakers/client'
+  changelog:
+    storage: repository
+```
+
+`fixed` 保证组内包同版本；`ignore` 排除 private 包；`repository` 让 changelog 作为源代码提交。
+
+## Prerelease lanes
+
+预发布使用 pnpm lanes：
+
+```bash
+pnpm exec repo release pre enter beta
+git add pnpm-workspace.yaml && git commit -m "chore(release): enter beta lane"
+git push
+pnpm exec repo release pre publish
+```
+
+预发布版本为 `X.Y.Z-beta.N`，并使用 npm `beta` dist-tag。退出时运行：
+
+```bash
+pnpm exec repo release pre exit
+git add pnpm-workspace.yaml && git commit -m "chore(release): exit prerelease lane"
+```
+
+fixed group 必须整体切换 lane，不能只移动其中一个包。
+
+## 恢复未发布版本
+
+如果版本提交已合并但 npm 发布失败，在 Release workflow 手动选择 `publish-unpublished`，填入 package 和 version。CI 会校验 main 上的 manifest 版本，使用 pnpm 发布并重新生成 tag 和 GitHub Release 元数据。
+
+## repoctl 的边界
+
+生成的 GitHub Actions 只保留环境准备和一个 `pnpm exec repo release ci` 调用。
+repoctl 负责发布前 build/lint/test、lane 一致性检查、Release PR、npm
+发布、package tag 与 GitHub Release；pnpm 负责变更意图、版本计算、changelog、
+ledger 和 registry 发布细节。
+
+存量项目首次迁移运行 `pnpm dlx repoctl@latest upgrade --yes`，后续使用
+`pnpm exec repo upgrade --yes` 即可跟随 repoctl 升级。未标记的自定义 release
+workflow 默认不会被覆盖，确认后可使用 `repo upgrade --overwrite-release`。

package/templates/vitepress/zh/monorepo/templates.md

@@ -0,0 +1,21 @@
+# 模板速查
+
+模板创建已经收敛到 repoctl 文档：
+
+- [repoctl 模板与创建](../repoctl/templates.md)
+- [repoctl 快速开始](../repoctl/getting-started.md)
+
+## monorepo 知识点：模板为什么重要
+
+当仓库里存在多种产物时，模板能把重复选择前置成稳定默认值：
+
+| 产物          | 常见目录                 | 关注点                         |
+| ------------- | ------------------------ | ------------------------------ |
+| TypeScript 库 | `packages/*`             | exports、types、构建和 tsd     |
+| Vue 组件库    | `packages/*`             | SFC、样式校验、类型声明        |
+| 应用          | `apps/*`                 | dev、build、部署资产           |
+| 服务          | `apps/*`                 | API 入口、运行时类型、环境变量 |
+| 文档站        | `apps/*`                 | VitePress 配置、导航、内容结构 |
+| CLI           | `apps/*` 或 `packages/*` | bin 入口、参数解析、发布       |
+
+repoctl 的 `repo templates` 和 `repo new` 负责把这些约定落实到文件系统。