@icebreakers/monorepo-templates 1.0.15 → 1.2.0

package/templates/vitepress/why/modern/typescript.md

@@ -1,155 +1,7 @@
-# 使用 TypeScript 编写代码
+# TypeScript Packages
 
-既然我们需要写多份文件，然后再发布到 `npm` 包，不如只写一份 `typescript` 文件
+Use TypeScript to validate source and to publish a precise consumer contract.
 
-然后其他的格式 (`cjs`/`esm`)，还有 `d.ts` 产物都自动生成，这不是就非常方便吗?
+Keep the source typecheck separate from artifact generation, enable strict settings appropriate for libraries, and avoid path aliases that cannot be resolved by consumers. Vue packages should run `vue-tsc`; non-Vue TypeScript packages should run `tsc`.
 
-## 改造项目
-
-安装 `typescript` 以及完成初始化创建 `tsconfig.json`
-
-```bash
-npm i -D typescript # 安装 typescript
-npx tsc --init # 创建 tsconfig.json
-```
-
-添加 `src` 目录，在里面创建 `index.ts` 文件
-
-```ts
-export function sayHello() {
-  const message = 'hello world typescript'
-  console.log(message)
-  return message
-}
-
-console.log(`load package icebreaker-npm-basic-package`)
-```
-
-## 调整 `tsconfig.json`
-
-```jsonc
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "rootDir": "./src",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "resolveJsonModule": true, // 支持 import json
-    "strict": true, // 严格模式
-    "declaration": true, // 生成 dts
-    "declarationMap": true, // dts 的 sourcemap
-    "outDir": "./dist", // 生成 dts 的目录
-    "sourceMap": true, // 生成 sourcemap
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "skipLibCheck": true
-  },
-  "include": ["src"]
-}
-```
-
-更多的配置 https://www.typescriptlang.org/tsconfig/
-
-## 创建 `cjs` 和 `esm` 各自格式的 `tsconfig.json`
-
-:::code-group
-
-```jsonc [tsconfig.esm.json]
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "module": "ESNext",
-    "outDir": "./dist/esm"
-  }
-}
-```
-
-```jsonc [tsconfig.cjs.json]
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "module": "commonjs",
-    "moduleResolution": "node10",
-    "outDir": "./dist/cjs"
-  }
-}
-```
-
-:::
-
-## 开始编译
-
-在 `package.json` 的 `scripts` 中添加脚本
-
-```jsonc
-{
-  "build:cjs": "tsc --project tsconfig.cjs.json && node rename-ext.js dist/cjs .js .cjs && node rename-ext.js dist/cjs .js.map .cjs.map",
-  "build:esm": "tsc --project tsconfig.esm.json",
-  "build": "npm run build:cjs && npm run build:esm"
-}
-```
-
-为什么这里还需要执行 `rename-ext`? 因为你安装使用一个 `npm` 包的时候，默认情况下会使用 `package.json` 中的 `type` 字段去决定这个包 `js` 代码模块加载器
-
-通常 `nodejs` 中会存在 `2` 个模块加载器:
-
-- [Modules: CommonJS modules](https://nodejs.org/docs/latest/api/modules.html)
-- [Modules: ECMAScript modules](https://nodejs.org/docs/latest/api/esm.html)
-
-假如你声明了 `"type": "module"`，那么 `nodejs` 会使用 `ESM` 模块加载器，去加载这个包下面的所有 `.js`
-
-反之，则使用 `CJS` 模块加载器，去加载这个包下面的所有 `.js`
-
-但是有 `2` 个后缀是特例，`.cjs` 和 `.mjs` , 他们在 `js` 前面加了 `c` 和 `m` 代表指定 `cjs`/`esm` 模块加载器，去加载这个 `js` 代码
-
-而我们这个包，已经被声明了 `"type": "module"`，所以是无法直接运行后缀是 `.js` 的 `cjs` 文件的，必须把后缀从 `.js` 转变为 `.cjs`
-
-## 更改 `package.json` 中模块入口点
-
-```jsonc
-{
-  "name": "icebreaker-npm-basic-package",
-  "type": "module",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/esm/index.d.ts",
-        "default": "./dist/esm/index.js"
-      },
-      "require": {
-        "types": "./dist/cjs/index.d.ts",
-        "default": "./dist/cjs/index.cjs"
-      }
-    }
-  },
-  "files": [
-    "dist" // [!code highlight]
-  ]
-}
-```
-
-给不同的引入方式，设置不同的模块入口，和不同的类型提示。
-
-同时也要注意这里我们添加了 `files` 字段，因为此时 `src` 目录下的源代码是不需要发布到 `npmjs` 上去的
-
-你也可以通过执行 `npm pack --dry-run` 查看当前哪些文件会在发布的时候，被上传到 `npmjs` 上去
-
-## 调试项目
-
-### 利用 `sourcemap` 调试项目
-
-`source map`（源码映射） 是一种用来 把编译/打包/压缩后的代码映射回原始代码 的技术
-
-它是用来解决 生成的代码和原始代码不一样, 无法直接调试源代码，这样一个问题。
-
-使用方式，在打开 `sourcemap` 选项后，生成对应的 `sourcemap` 文件，然后就可以在 `ts` 代码中打上断点，直接调试源代码了。
-
-### 直接运行 `typescript` 调试项目
-
-过去我们使用 `ts-node` 来直接运行 `ts`，随着时代的发展，`ts-node` 已经逐渐被 `tsx` 所取代
-
-当然市面上直接转译运行 `typescript` 的工具还是非常多的，比如 `tsx` 和 `bundle-require` 都是基于 `esbuild`
-
-`jiti` 这种基于 `babel` 的，还有 `swc-node` 这种基于 `swc` 的， `@oxc-node/core` 这种基于 `oxc` 的
-
-当然，在不使用 `emitDecoratorMetadata` 这种 `typescript` 的装饰器的高级用法的情况下，使用 `tsx` 是比较好的选择
+Public type behavior belongs in `tsd` tests. Runtime tests should import built output so module resolution matches delivery.

package/templates/vitepress/why/publish-basic-npm-package.md

@@ -1,146 +1,19 @@
-# 如何发布 npm 包
-
-其实发布基础的 `npm` 包非常非常简单
-
-## 创建目录
-
-随便创建一个目录，在创建目录之后执行 `npm init` 输入一些你的包的元数据之后，一个 `package.json` 就被创建了出来
-
-假如你懒得写，那就执行 `npm init -y` ，反正后续都是可以更改的，此时你得到的 `package.json` 如下
-
-```jsonc
-{
-  "name": "icebreaker-npm-basic-package",
-  "version": "1.0.0",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "author": "",
-  "license": "ISC",
-  "description": ""
-}
-```
-
-> 你操作到这里，`package.json` 的 `name` 一定要换成你自己的，因为这个包我已经发布了，所以名字已经被我占据了你用不了
-
-## 创建一个 `index.js`
-
-在你的 `package.json` 同目录下创建一个 `index.js`，内容如下
-
-```js
-console.log(`load ${__filename}`)
-
-function sayHello() {
-  console.log('hello world')
-}
-
-module.exports = {
-  sayHello
-}
-```
-
-> 按照现代包的要求，其实是优先 esm 格式的，但是上面的例子还是用的 cjs，这个会在下个章节提到
-
-## 发包到 npmjs
-
-然后你在 `package.json` 同级目录下，执行 `npm publish`
-
-然后恭喜你，你失败了！
-
-为什么失败？你连 `npmjs` 账号都还没有注册呢！
-
-执行 `npm publish` 是需要先 `npm login` 登录你的 `npmjs` 账号的
-
-赶紧去 [`www.npmjs.com`](https://www.npmjs.com/) 右上角注册一个账号吧！
-
-## 获取 Access Token
-
-注册好一个账号之后，再执行 `npm login`, 你就可以在弹出来的页面中，登录你的账号
-
-登录成功之后，默认情况下，他会给你去生成一个 `Access Token` 作为你的发包凭证
-
-此时会写入到你全局 `.npmrc` 的文件中，类似于下面一行
-
-```txt
-registry.npmjs.org/:_authToken=npm_hashhashhashhashhashhashhashhashhash
-```
-
-假如这一行存在，说明你本地的 `npm Access Token` 就设置好了，然后你才有发包的权限。
-
-> 你也可以在 `https://www.npmjs.com/settings/<你的用户名>/tokens` 中管理你的 `token`，给不同的 `token` 设置不同的作用域，有效期（目前最长 90 天）和 `ip` 限制，帮助你适配正常开发，`CI/CD`，`Token` 分发的各种场景；如需避免手动轮换，CI 场景推荐使用 npm 官方的 OIDC 方案获取临时 `NODE_AUTH_TOKEN`，并在工作流开启 `id-token: write` 权限。
-
-同样发私有源包也是同理:
-
-```txt
-//npm.icebreaker.top/:_authToken=npm_hashhashhashhashhashhashhashhashhash
-```
-
-你必须有这个凭证，你才有这个权限。
-
-## 成功发包
-
-配置好 `npm Access Token` 执行 `npm publish` 然后就能发包成功了
-
-```sh
-npm notice
-npm notice 📦  icebreaker-npm-basic-package@1.0.0
-npm notice Tarball Contents
-npm notice 120B index.js
-npm notice 187B package.json
-npm notice Tarball Details
-npm notice name: icebreaker-npm-basic-package
-npm notice version: 1.0.0
-npm notice filename: icebreaker-npm-basic-package-1.0.0.tgz
-npm notice package size: 326 B
-npm notice unpacked size: 307 B
-npm notice shasum: fc4624e7bddd96a6ffac505f672b62de55898d6b
-npm notice integrity: sha512-2UtWkYX5tEUyu[...]ZFF64Wvq+Vw0Q==
-npm notice total files: 2
-npm notice
-npm notice Publishing to https://registry.npmjs.org/ with tag latest and default access
-+ icebreaker-npm-basic-package@1.0.0
+# Publishing An npm Package
+
+1. Define explicit runtime and type entrypoints.
+2. Build the package and run tests against built artifacts.
+3. Inspect `pnpm pack` output.
+4. Record a change intent and verify the version plan.
+5. Publish with provenance and the intended access level.
+
+```bash
+pnpm build
+pnpm lint
+pnpm typecheck
+pnpm tsd
+pnpm test
+pnpm pack
+pnpm change
 ```
 
-然后你就发现你的包可以通过访问 `https://www.npmjs.com/package/<你的包名>` 获取到了
-
-比如我这个包就能通过 `https://www.npmjs.com/package/icebreaker-npm-basic-package` 直接访问
-
-## 安装调用
-
-你可以执行 `npm i <你的包名>` 直接获取到你的包，进行调用了。
-
-> 假如你没有使用官方的 `registry.npmjs.org`，反而使用的是 `npmmirror.com` 这种国内的淘宝镜像源，那么你的包同步到国内镜像源，可能需要一段时间
->
-> 你可以通过 `npm i -g cnpm`, `cnpm sync <你的包名>` 进行手动同步，加快这个流程。
-
-安装好之后，使用 `nodejs` 执行代码:
-
-```js
-const { sayHello } = require('icebreaker-npm-basic-package')
-
-sayHello()
-```
-
-出现
-
-```txt
-load /your/path/to/node_modules/icebreaker-npm-basic-package/index.js
-hello world
-```
-
-证明你安装调用成功了！实际上很简单吧！
-
-## 更进一步
-
-恭喜你，你已经踏出了你的第一步，你已经来到了 `Nodejs` 这座高山的山脚下准备进行攀登。
-
-山上云雾缭绕，看不到顶，攀登的路上, 险象环生，爬的越高越感觉举步维艰。
-
-但是也用不着害怕，正如荀子在《劝学》篇所写下的: `不积跬步,无以至千里。不积小流,无以成江海`。
-
-量变促成质变，等你到达那个质变的点，你就会发现自己看待代码的眼光已经完全改变了，从新的角度去看，很容易一眼看出问题的本质。
-
-所以，多看优秀的代码，多去调试开源项目的源代码，多写代码多思考，你就成长了！
-
-接下来让我们改进一下这个包，让他更加的现代化。
+Never publish template source workspaces that are intentionally marked `private: true`.

package/templates/vitepress/why/what-is-npm-package.md

@@ -1,162 +1,7 @@
----
-outline: [2, 4]
----
+# What Is An npm Package?
 
-# 什么是 npm 包
+An npm package is a directory described by `package.json`. It can expose runtime code, types, command-line bins, assets, or configuration.
 
-在 `Node.js` 中，**npm 包（npm package）** 是指一个通过 [npm（Node Package Manager）](https://www.npmjs.com/) 发布和管理的可重用 `JavaScript` 模块。它可以是一个库、工具、框架、命令行工具，甚至是一个完整的应用程序。
+The public contract includes the package name, version, `exports`, `types`, `bin`, supported runtimes, files included in the tarball, and semantic versioning behavior. Treat these fields as API design, not publishing metadata afterthoughts.
 
-## 什么是 npm？
-
-**npm（Node Package Manager）** 是 Node.js 的官方包管理工具，用于：
-
-- 安装依赖库；
-- 管理项目依赖；
-- 发布自己的模块到 npm 生态。
-
-命令行工具：`npm install`, `npm update`, `npm publish` 等。
-
-同样 `yarn` / `pnpm` 也是 **npm（Node Package Manager）**，不过他们是非 `Nodejs` 官方的
-
-他们的出现或多或少的解决了官方 `npm` 的很多问题，完全可以作为官方 `npm` 工具的平替，在社区里备受推崇，展现出 `Nodejs` 社区旺盛的生命力。
-
-尤其是 `pnpm`，比官方 `npm` 好用太多，目前大家把很多对 `npm` 包管理器的期望都寄托在他身上。
-
-> `pnpm` 对于 `Nodejs`，地位类似于 [`uv`](https://github.com/astral-sh/uv) 对于 `Python` 他们都不是官方项目，但是却逐渐成为了主流
-
-<!-- `deno` / `bun` -->
-
----
-
-## 什么是一个 npm 包？
-
-一个 **npm 包** 通常具有以下结构：
-
-```txt
-my-package/
-├── package.json     // 包的元数据（名字、版本、依赖等）
-├── index.js         // 主文件（或其它入口）
-└── lib/             // 模块代码
-```
-
-`package.json` 是核心文件，定义了：
-
-- `name`：包的名称（唯一，不能与其它包冲突）
-- `version`：版本号（如 `1.0.0`）
-- `main`：主入口文件（默认是 `index.js`）
-- `dependencies`：依赖的其他 npm 包
-- `files`: 哪些文件应该被上传，用于忽略掉不需要的文件类型
-
-> 更多字段，可以查看 [`configuring-npm/package-json`](https://docs.npmjs.com/cli/v11/configuring-npm/package-json)
-
-### npm 包关系类型
-
-#### **公共包**
-
-来自 [npmjs.com](https://www.npmjs.com/) ，如 `lodash`, `react`, `axios`
-
-[yarnpkg.com](https://yarnpkg.com/), [npmmirror(淘宝源)](https://npmmirror.com/) 这种本质上都是 [npmjs.com](https://www.npmjs.com/) 的镜像源，定期从 [npmjs.com](https://www.npmjs.com/) 同步包到他们的源上 (所以 `npmmirror` 有 `cnpm sync` 命令和 `同步功能` 就是为了在自动同步不及时的时候，手动同步的)
-
-假如我们要发 **公共包**，那肯定把包发到 [npmjs.com](https://www.npmjs.com/) 上的，因为发其他公共源没有意义。
-
-#### **私有包**
-
-企业内部发布的包，需配置私有 `npm registry`。
-
-注册源可以在用户本地 `User` 全局的 `.npmrc`, 或者是项目中的 `.npmrc` 进行配置
-
-比如:
-
-```txt
-registry=https://registry.npmmirror.com/
-@ice:registry=http://npm.icebreaker.top
-```
-
-就代表所有 `@ice/xxx` 这种包都从 `http://npm.icebreaker.top` 这里获取，其他包从 `https://registry.npmmirror.com/`
-
-假如你不设置 `registry` 默认从最官方的源 `https://registry.npmjs.org/` 中获取包
-
-假如你对 `npm私有源` 的搭建感兴趣，可以看看我写的这篇文章 [使用 Verdaccio 私有化 npm 源指南](https://juejin.cn/post/7357016488698839050)
-
-#### **本地包**
-
-可直接从 `文件夹`, `Git 仓库`, `monorepo workspace` 安装的包
-
-因为其实我们在 `dependencies` 和 `devDependencies` 注册的包，协议可以是多种多样的，比如:
-
-```jsonc
-{
-  "dependencies": {
-    // npm 注册源上拿
-    "foo": "1.0.0 - 2.9999.9999",
-    "bar": ">=1.0.2 <2.1.2",
-    "baz": ">1.0.2 <=2.3.4",
-    "boo": "2.0.1",
-    "qux": "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",
-    "til": "~1.2",
-    "elf": "~1.2.3",
-    "two": "2.x",
-    "thr": "3.3.x",
-    "lat": "latest",
-    // http 协议拿
-    "asd": "http://npmjs.com/example.tar.gz",
-    // git 协议拿
-    "xxx": "git+ssh://git@github.com:npm/cli#semver:^5.0",
-    // 从 github 拿
-    "express": "expressjs/express",
-    "mocha": "mochajs/mocha#4727d357ea",
-    "module": "npm/example-github-repo#feature/branch",
-    // 本地文件协议拿
-    "dyl": "file:../dyl",
-    "kpg": "file:../foo/bar",
-    // monorepo workspace
-    "xya": "workspace:*"
-  }
-}
-```
-
-详见官方文档 [dependencies详解](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#dependencies)
-
-### 注意点
-
-值得注意的是，这个包的类型只和它的来源还有和当前包的关系有关，也就是说一个包，既可以是公共包，也可以是私有包，也可以是本地包。
-
-比如在本 `monorepo` 中，`@icebraekers/monorepo` 是公共包，因为它已经发布到了 `https://www.npmjs.com` 上了
-
-同时它也是一个本地包，因为本 `monorepo` 中，其他项目使用 `workspace` 的方式直接使用了这个包。
-
-它也可以是一个私有包，比如你在公司内部网络，快速使用 [verdaccio](https://www.npmjs.com/package/verdaccio) 搭建一个私有源, 然后把 `@icebraekers/monorepo` 发布上去，那它就变成一个内网里的私有包了。
-
-### 使用 npm 包的示例
-
-这里我以一个最简单的一个 `cowsay` 包为例，这个包作用就是输出一个牛说话的字符画
-
-- **安装第三方包：**
-
-```bash
-npm install cowsay
-```
-
-- **在代码中使用：**
-
-```js
-const cowsay = require('cowsay')
-
-console.log(cowsay.say({
-  text: '我爱中国!',
-  e: 'oO',
-  T: 'U '
-}))
-```
-
-- **在 CLI 中使用 ：**
-
-```bash
-npx cowsay 我爱中国!
-```
-
-> `npx` 是 Node.js 提供的一个命令行工具，用来直接运行 npm 包，无需全局安装。
-
----
-
-接下来，就让我们开始 `npm` 包的发布之旅吧
+Use `pnpm pack` to inspect the exact artifact before publishing.

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

@@ -0,0 +1,33 @@
+---
+description: repoctl 文档站的 AI 文档入口，说明如何为 AI 编程工具提供 llms.txt 和页面 Markdown。
+---
+
+# AI 文档
+
+AI 文档入口用于给 Cursor、Claude Code、Codex 和其他 AI 编程工具提供更容易读取的上下文。它和工具专题分开维护，避免 llms.txt 被埋在普通工具列表里。
+
+## 1. 推荐入口
+
+| 入口                           | 用途                                             |
+| ------------------------------ | ------------------------------------------------ |
+| `/llms.txt`                    | 轻量文档索引，适合先交给 AI 工具判断要读哪些页面 |
+| `/llms-full.txt`               | 合并后的完整文档，适合需要一次性提供上下文的场景 |
+| [llms.txt 说明](./llms-txt.md) | 维护约定、访问方式和页面 frontmatter 要求        |
+
+## 2. 在 AI 工具里怎么用
+
+优先把 `https://repo.icebreaker.top/llms.txt` 作为入口提供给 AI 工具。只有当工具不能继续抓取链接，或者你需要离线提供完整上下文时，再使用 `https://repo.icebreaker.top/llms-full.txt`。
+
+```txt
+先给 llms.txt
+  -> AI 选择相关页面
+  -> 必要时补充 llms-full.txt
+```
+
+## 3. 维护原则
+
+| 维护动作                          | 原因                                     |
+| --------------------------------- | ---------------------------------------- |
+| 新增重要页面时写 `description`    | 让 llms 索引更容易被模型理解             |
+| 页面标题保持具体                  | 避免 AI 只看到泛化标题，无法判断页面用途 |
+| repoctl、知识库、工具专题分开组织 | 让 AI 工具能按任务类型检索上下文         |

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)