@icebreakers/monorepo-templates 1.1.0 → 1.2.0

package/templates/vitepress/why/modern/package-entry-points.md

@@ -1,128 +1,17 @@
----
-outline: [2, 4]
----
+# Package Entry Points
 
-# package.json 中的 entry point 字段
-
-在 `package.json` 中，定义模块的入口点 (`entry point`) 字段是及其重要的
-
-## package.json 代码示例
-
-```jsonc
-{
-  "name": "icebreaker-npm-basic-package",
-  "version": "1.0.0",
-  "type": "module",
-  "main": "./index.cjs", // CommonJS 主入口（用于 Node require）
-  "module": "./index.mjs", // 非标准，但很多构建工具支持（ESM）
-  "types": "./index.d.ts", // TypeScript 类型定义
-  "exports": {
-    ".": {
-      "types": "./index.d.ts", // TypeScript 类型定义
-      "require": "./index.cjs", // Node require 使用 CommonJS
-      "import": "./index.mjs" // Node import 使用 ESM
-    }
-  }
-}
-```
-
-### 📝 字段说明：
-
-| 字段               | 说明                                             |
-| ------------------ | ------------------------------------------------ |
-| `"type": "module"` | 默认将 `.js` 文件视为 ESM                        |
-| `"main"`           | Node 中 `require('pkg')` 会使用 CommonJS 文件    |
-| `"module"`         | 给打包工具提供 ESM 入口，非标准，但有用          |
-| `"exports"`        | 更现代且明确的方式，指明模块格式，兼容 Node >=12 |
-| `"types"`          | 给 TypeScript 指明类型定义文件的位置             |
-
----
-
-官方文档: [package-entry-points](https://nodejs.org/api/packages.html#package-entry-points)
-
-## 为什么说 module 是非标准的?
-
-在 `package.json` 中，`"module"` 字段是一个 **非标准的字段**，但在现代前端工具（如 Webpack、Rollup、Vite 等）中被广泛使用，用于指向 **ES Module 格式的入口文件**，以便这些工具能够做更好的静态分析与 tree-shaking。
-
-下面是不同工具/环境下可能会读取 `"module"` 字段的情况：
-
----
-
-### ✅ **什么情况下会加载 `"module"` 字段？**
-
-#### **打包工具（Webpack、Rollup、Vite、Snowpack, Parcel 等）**
-
-- 当你使用这些工具打包代码时，它们会优先尝试读取：
-  1. `"exports"` 字段（如果存在，优先于其他字段）
-  2. `"module"` 字段（通常表示 ESM 格式）
-  3. `"main"` 字段（通常表示 CommonJS 格式）
-
-示例：
-
-```js
-// 在 Webpack 中引入某个 npm 包时，如果该包的 package.json 有 module 字段
-// Webpack 会优先使用这个字段所指向的 ESM 文件
-import foo from 'icebreaker-npm-basic-package'
-```
-
-> `Vite、Snowpack, Parcel` 这些工具天生以 ESM 为主，会优先读取 `"module"` 字段。
-
----
-
-### 🚫 **不会加载 `"module"` 字段的情况**
-
-#### **Node.js 本身**
-
-- Node.js 并不识别 `"module"` 字段，加载模块时它依赖的是：
-  - `"type"` 字段（决定是否为 ESM 模式）
-  - `"main"` 字段（默认入口）
-  - 或者直接通过 `"exports"` 字段（推荐现代做法）
-
-例如，在你的 `package.json` 中：
+Use the `exports` field to define the package's supported public paths.
 
 ```json
-{
-  "type": "module",
-  "main": "index.cjs",
-  "module": "index.js"
-}
-```
-
-- 你运行 `node .` 时，Node 会根据 `"main"` 加载 `index.cjs`
-- 如果你运行 `node index.js`，它会根据文件扩展名和 `"type": "module"` 以 ESM 模式运行，但并不会自动从 `"module"` 字段寻找入口
-
----
-
-### 推荐现代做法（如要兼容多种环境）：
-
-可以使用 `exports` 字段更明确地配置入口文件：
-
-```jsonc
 {
   "exports": {
     ".": {
-      "types": "./index.d.ts",
-      "require": "./index.cjs",
-      "import": "./index.js"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
-    "./xxx": {
-      "types": "./xxx.d.ts",
-      "require": "./xxx.cjs",
-      "import": "./xxx.js"
-    }
+    "./package.json": "./package.json"
   }
 }
 ```
 
-这样，Node.js 和打包工具都能正确识别和区分 ESM 和 CommonJS。
-
----
-
-### 总结：
-
-| 环境/工具      | 是否使用 `"module"` 字段 | 说明                          |
-| -------------- | ------------------------ | ----------------------------- |
-| Node.js        | ❌ 不会使用              | 使用 `"main"` 或 `"exports"`  |
-| Webpack/Rollup | ✅ 会使用                | 优先用来加载 ESM 版本         |
-| Vite/Snowpack  | ✅ 会使用                | 用于选择 ESM 格式             |
-| TypeScript     | ❌ 不直接使用            | 会用 `"types"` 字段找类型声明 |
+Do not rely on consumers reaching into undeclared internal files. Every exported path should have runtime output, types where applicable, and a compatibility test.

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 工具能按任务类型检索上下文         |