@icebreakers/monorepo-templates 1.1.0 → 1.2.0

package/templates/vitepress/zh/repoctl/templates.md

@@ -0,0 +1,159 @@
+# 模板与创建
+
+repoctl 的模板由 `@icebreakers/monorepo-templates` 维护。CLI、脚手架和文档都复用同一份模板元数据。
+
+更偏维护者视角的模板元数据、健康检查和自定义模板说明见：[模板资产治理](./template-assets.md)。
+
+## 内置模板
+
+| Key           | Category | 默认目录           | 适合场景                    |
+| ------------- | -------- | ------------------ | --------------------------- |
+| `tsdown`      | library  | `packages/tsdown`  | TypeScript 库包             |
+| `vue-lib`     | library  | `packages/vue-lib` | Vue 3 组件库                |
+| `vue-hono`    | app      | `apps/client`      | Vue 3 + Hono 前后端一体应用 |
+| `hono-server` | service  | `apps/server`      | Hono API 服务               |
+| `vitepress`   | docs     | `apps/website`     | VitePress 文档站            |
+| `cli`         | tool     | `apps/cli`         | TypeScript 命令行工具       |
+
+## 查看模板
+
+```bash
+repo templates
+repo templates tsdown
+repo templates --category library
+repo templates --json
+repo templates --markdown --out docs/templates.md
+```
+
+## 创建模板
+
+```bash
+repo new sdk --template tsdown
+repo new ui --template vue-lib
+repo new api --template hono-server
+repo new website --template vitepress
+repo new toolbox --template cli
+```
+
+普通名字会自动放到模板约定的目录里，例如库包进入 `packages/`，应用进入 `apps/`。如果你传入带 `/` 的路径，例如 `packages/shared-utils`，repoctl 会尊重这个路径。
+
+## 按目标选择模板
+
+### 要发布 npm 库
+
+```bash
+repo new sdk --template tsdown
+```
+
+生成后先检查：
+
+- `package.json` 的 `name`、`exports`、`types`。
+- `tsdown.config.ts` 是否符合产物格式。
+- 是否需要补 `tsd` 类型测试。
+
+### 要沉淀 Vue 组件
+
+```bash
+repo new ui --template vue-lib
+```
+
+生成后先检查：
+
+- 组件入口是否只导出稳定 API。
+- 样式是否能通过 Stylelint。
+- 文档站或示例应用是否需要同步创建。
+
+### 要创建应用或服务
+
+```bash
+repo new web --template vue-hono
+repo new api --template hono-server
+```
+
+生成后先检查：
+
+- 运行时环境变量和部署平台约束。
+- `dev`、`build`、`typecheck` 脚本是否接入根任务。
+- 是否需要在 CI 里加入 E2E 或集成测试。
+
+### 要创建文档站
+
+```bash
+repo new docs --template vitepress
+```
+
+生成后先检查：
+
+- 导航和 sidebar 是否围绕产品或包名组织。
+- 是否需要中英文 locale。
+- 是否需要把 `repo templates --markdown` 输出写进文档。
+
+### 要创建 CLI
+
+```bash
+repo new toolbox --template cli
+```
+
+生成后先检查：
+
+- `bin` 字段是否符合最终命令名。
+- 参数解析、退出码和帮助信息是否可测试。
+- 是否需要把命令用法写入 README。
+
+## 创建前预览
+
+```bash
+repo new website --template vitepress --dry-run
+repo new website --template vitepress --json
+repo new website --template vitepress --json --out plans/website.json
+```
+
+`--dry-run` 不写入磁盘，只展示模板、源目录、目标目录、package name 和输出文件。
+
+`--json` 输出同一份创建计划的结构化数据，隐含 `--dry-run`。
+
+`--out <file>` 可以把文本或 JSON 预览写入文件，也隐含 `--dry-run`。
+
+## 固化默认模板
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    create: {
+      defaultTemplate: 'tsdown',
+    },
+  },
+})
+```
+
+之后：
+
+```bash
+repo new utils
+```
+
+会直接创建 `tsdown` 库包。
+
+## 检查模板健康状态
+
+```bash
+repo templates --check
+repo templates --check --json
+```
+
+模板检查会确认：
+
+- 模板 source 和 target 没有重复。
+- 每个模板 source 目录都存在。
+- 每个模板根目录都有 `package.json`。
+- 每个模板都有 category 和 description。
+- 模板源目录里没有会被脚手架过滤掉的临时或生成文件。
+
+## 继续阅读
+
+- [接入已有仓库](./adopt-existing.md)
+- [工作流与 CI](./workflows.md)
+- [配置文件](./config.md)
+- [模板资产治理](./template-assets.md)

package/templates/vitepress/zh/repoctl/troubleshooting.md

@@ -0,0 +1,110 @@
+# 排障与报告
+
+repoctl 的排障重点不是让你猜错在哪里，而是尽量输出可以复现、可以保存、可以发给同事的报告。
+
+## 先跑 doctor
+
+```bash
+repo doctor
+repo doctor --strict
+```
+
+`doctor` 主要检查：
+
+- 当前目录是不是仓库根目录。
+- Node 版本是否满足要求。
+- `pnpm-workspace.yaml` 是否存在。
+- `repoctl` 是否作为 CLI 依赖安装。
+- 根脚本是否齐全。
+- 是否仍残留已废弃的 `monorepo.config.ts`。
+- Husky 与 lint-staged 是否都接上。
+
+## 保存诊断报告
+
+```bash
+repo doctor --json --out reports/doctor.json
+repo doctor --markdown --redact --out reports/doctor.md
+```
+
+推荐把 Markdown 报告贴到 issue 或 PR。`--redact` 会脱敏本机路径。
+
+## 查看校验计划
+
+```bash
+repo check --dry-run
+repo check --json --out reports/check-plan.json
+repo check --markdown --redact --out reports/check-plan.md
+```
+
+当你不确定为什么某个文件触发了 workspace typecheck、pre-push 要跑哪些任务时，先看 check plan。
+
+## 收集环境信息
+
+```bash
+repo env info
+repo env support --markdown --redact --out reports/support.md
+repo env snapshot --json --out reports/snapshot.json
+repo env paths --markdown --redact --out reports/paths.md
+```
+
+这些命令适合排查 Node、pnpm、workspace、Git、路径和 CI 环境差异。
+
+## 先判断问题类型
+
+| 现象                           | 优先命令                                  | 继续阅读                             |
+| ------------------------------ | ----------------------------------------- | ------------------------------------ |
+| 不确定当前目录是不是仓库根目录 | `repo doctor`                             | [doctor 诊断](./doctor.md)           |
+| 不知道 `repo check` 会跑什么   | `repo check --dry-run`                    | [校验链路](./checks.md)              |
+| CI 失败但日志不完整            | `repo env support --markdown --redact`    | [报告与自动化输出](./reports.md)     |
+| 模板创建结果不符合预期         | `repo new <name> --template <key> --json` | [模板资产治理](./template-assets.md) |
+| 模板列表或元数据异常           | `repo templates --check`                  | [模板资产治理](./template-assets.md) |
+
+## 常见问题
+
+### 当前目录不是仓库根目录
+
+切回包含 `pnpm-workspace.yaml` 和根 `package.json` 的目录，再运行：
+
+```bash
+repo doctor
+```
+
+### 同时存在两个配置文件
+
+只保留一个：
+
+```txt
+repoctl.config.ts
+```
+
+`monorepo.config.ts` 已不再加载。旧项目需要改名为 `repoctl.config.ts`。
+
+### `repo new` 提示模板不存在
+
+先查看可用模板：
+
+```bash
+repo templates
+```
+
+显式传入的 `--template` 会先校验。拼错时命令会失败并提示相近 key，不会静默回退。
+
+### 自动化里不希望出现交互
+
+使用非交互参数：
+
+```bash
+repo init --yes
+repo upgrade --no-overwrite
+repo check --json --out reports/check-plan.json
+```
+
+非 TTY 环境下，repoctl 不会弹出交互选择框。
+
+## 继续阅读
+
+- [工作流与 CI](./workflows.md)
+- [命令速查](./commands.md)
+- [doctor 诊断](./doctor.md)
+- [报告与自动化输出](./reports.md)
+- [命令别名](./aliases.md)

package/templates/vitepress/zh/repoctl/workflows.md

@@ -0,0 +1,118 @@
+# 工作流与 CI
+
+repoctl 的命令可以分成两类：给人用的日常入口，以及给 CI、脚本、编辑器用的可保存输出。
+
+## 本地日常工作流
+
+```bash
+pnpm install
+pnpm run repo:doctor
+pnpm run repo:new -- sdk --template tsdown
+pnpm run repo:check
+pnpm build
+```
+
+这条链路适合新成员第一次进入仓库：
+
+| 步骤                   | 判断标准                                         |
+| ---------------------- | ------------------------------------------------ |
+| `pnpm install`         | workspace 依赖和本地链接完整                     |
+| `pnpm run repo:doctor` | 仓库根目录、Node、脚本、配置和提交链路可用       |
+| `pnpm run repo:new`    | 新包由模板创建，目录和 package metadata 符合约定 |
+| `pnpm run repo:check`  | 提交前轻量校验可以复现                           |
+| `pnpm build`           | 全仓构建链路没有明显断点                         |
+
+## 存量仓库接入
+
+```bash
+pnpm add -D repoctl
+pnpm exec repo init --yes
+pnpm exec repo doctor --markdown --out reports/doctor.md
+pnpm exec repo upgrade --no-overwrite
+pnpm exec repo doctor
+```
+
+推荐先用 `--no-overwrite` 保守接入。确认标准资产差异后，再决定是否使用 `--yes` 或 `--overwrite`。
+
+## CI 快速门禁
+
+```bash
+pnpm install --frozen-lockfile
+pnpm exec repo doctor --strict
+pnpm exec repo check --full
+```
+
+适合小仓库或早期项目。`doctor --strict` 会把 warning 也当成失败，能避免配置漂移慢慢积累。
+
+## CI 报告模式
+
+```bash
+pnpm exec repo doctor --json --out reports/doctor.json
+pnpm exec repo check --json --out reports/check-plan.json
+pnpm exec repo env support --markdown --redact --out reports/support.md
+```
+
+这组命令适合想保存构建上下文的 CI：
+
+- `doctor.json` 给脚本判断仓库健康状态。
+- `check-plan.json` 记录本次会跑哪些校验。
+- `support.md` 适合上传为 artifact，或贴进 issue / PR。
+
+## pre-commit 与 pre-push
+
+repoctl 暴露了底层 verify 命令，方便 hook 和脚本复用：
+
+```bash
+repo verify pre-commit
+repo verify staged-typecheck packages/app/src/main.ts
+repo verify commit-msg .git/COMMIT_EDITMSG
+repo verify pre-push
+```
+
+默认建议：
+
+| 阶段       | 推荐行为                                                |
+| ---------- | ------------------------------------------------------- |
+| pre-commit | 聚焦 staged 文件，运行格式、lint 和 workspace typecheck |
+| commit-msg | 校验 Conventional Commit 格式                           |
+| pre-push   | 跑整仓 lint/typecheck，并按变更范围补 build/test/tsd    |
+
+## 自动化创建预览
+
+```bash
+repo new dashboard --template vue-hono --json --out plans/dashboard.json
+repo templates --markdown --out docs/templates.md
+repo ws ls --json --out reports/workspaces.json
+```
+
+这些命令都不会要求人工选择，适合编辑器插件、脚本和 CI bot。
+
+## 推荐流水线拆分
+
+| 阶段 | 命令                                                            | 失败后先看                           |
+| ---- | --------------------------------------------------------------- | ------------------------------------ |
+| 安装 | `pnpm install --frozen-lockfile`                                | lockfile、Node、pnpm 版本            |
+| 诊断 | `repo doctor --strict`                                          | [doctor 诊断](./doctor.md)           |
+| 计划 | `repo check --full --json --out reports/check-plan.json`        | [报告与自动化输出](./reports.md)     |
+| 执行 | `repo check --full`                                             | 失败的 root script 或 workspace 任务 |
+| 留证 | `repo env support --markdown --redact --out reports/support.md` | CI artifact                          |
+
+早期项目可以把计划和执行合并。成熟项目建议保留 `reports/`，方便失败时复盘实际执行路径。
+
+## 非交互参数选择
+
+| 场景               | 推荐参数                                           |
+| ------------------ | -------------------------------------------------- |
+| 初始化时接受默认值 | `repo init --yes`                                  |
+| 同步时保留已有改动 | `repo upgrade --no-overwrite`                      |
+| 明确覆盖标准资产   | `repo upgrade --yes` 或 `repo upgrade --overwrite` |
+| 只看计划不执行     | `--dry-run`                                        |
+| 输出给脚本         | `--json --out <file>`                              |
+| 输出给人看并脱敏   | `--markdown --redact --out <file>`                 |
+
+## 下一步
+
+- 查所有参数：[命令速查](./commands.md)
+- 理解校验链路：[校验链路](./checks.md)
+- 生成排障包：[报告与自动化输出](./reports.md)
+- 看短命令：[命令别名](./aliases.md)

package/templates/vitepress/zh/thinking.md

@@ -0,0 +1,88 @@
+# 我对 monorepo 的一些思考
+
+## 前言
+
+最近在自己的新项目中，我创建并使用了 [monorepo-template](https://github.com/sonofmagic/monorepo-template) 模板，并不断地做了不少改进。
+
+在此，我想借此机会分享一下这个模板的演变过程，以及我对 `monorepo` 的一些思考。
+
+## 它的由来
+
+为了应对越来越多的发包场景，我创建了 [npm-lib-template](https://github.com/sonofmagic/npm-lib-template) 模板
+
+这是一个 `git` 单仓单 `npm` 包模板，使用 `rollup` 进行打包，然后再发布到 `npm` 和 `github`
+
+然而，在后续开发中，我发现单仓库的模式在某些场景下难以应对。
+
+例如，当需要引用其他自己的包，进行单元测试并再次发包时，这时候往往要在多个项目之间进行来回的切换更改，管理复杂度会迅速上升。
+
+`git submodule` 也是另外一条路子，但是我对每次都要同步 `hash` 感到深恶痛绝，遂放弃 (不过某些极其特殊场景的实现，还是只能利用这个功能)。
+
+因此，我决定要创建一个 [monorepo 项目模板](https://github.com/sonofmagic/monorepo-template) ，以应对这些需求。
+
+## 技术选型
+
+### 管理工具
+
+在 `monorepo` 的管理上，我选择了 `pnpm` 和 `turborepo` 这对组合，原因很简单：它们都非常快。
+
+- `pnpm` 又可以节省磁盘空间，又能够链接自特定的内容寻址存储库，是为快也
+- `turborepo` 有构建缓存，是为快也 `too`.
+
+### 语言与打包
+
+我选择使用纯 `TypeScript` 来编写所有类库项目，并统一使用 `tsdown` 进行打包，默认输出格式为 `cjs` 和 `esm`，并利用 `package.json` 中的 `exports` 字段进行分发。
+
+### 直接调试
+
+在直接调试时，我抛弃了 `dist` + `sourcemap` 的调试方式，使用了 `tsx`，它非常适合调试 `TypeScript` 编写的 `CLI` 项目。
+
+### 测试框架
+
+测试方面，我选择了 `vitest`。
+
+它不仅速度快，还很好地支持 `cjs`、`esm` 和 `TypeScript`，同时也适合 `monorepo` 项目。你可以利用 `turbo` 来执行单个的 `vitest` 任务，也可以利用 `vitest.workspace` 来进行多任务测试。
+
+最初我使用的是 `jest` + `ts-jest`，但它对多格式的混合模块的支持不够理想，最终我选择了 `vitest`。
+
+### 代码规范与质量控制
+
+为了保持代码质量，我使用了 `eslint` 和 `stylelint`，并基于自己的配置包 `@icebreakers/eslint-config` 和 `@icebreakers/stylelint-config` 来进行代码格式化和规范化。
+
+我还为 `.vscode` 配置了一些推荐插件和编辑器选项。
+
+此外，通过 `husky` 添加了 `git hook`，配合 `lint-staged` 对提交的代码进行校验。与 `commitlint` 结合使用，以确保 `git` 提交信息符合规范。
+
+### 本地引用与发包替换
+
+利用 `publishConfig` 会在发包的时候替换 `package.json` 字段的方式，在本地包相互引用的时候，都使用 `Typescript` 源文件的方式导出，在 `publishConfig` 里定义的导出为，真正在不同环境中，指向 `dist` 中不同格式的产物地址。
+
+通过这种方式，可以大大加速整个 `monorepo` 的开发测试速度，避免反复通过 `watch` 来构建 `dist` 和 `sourcemap`，也避免一构建出产物，对应的 `Typescript` 文件，就报错的问题。
+
+### 发包流程
+
+现在使用 pnpm 原生 versioning：用 `pnpm change` 记录意图，用 `pnpm version -r` 生成版本和 changelog，再用 `pnpm publish -r` 发布。版本计划保留在 `.changeset/ledger.yaml`，预发布则由 pnpm lanes 管理。
+
+### Github 相关配置
+
+在 `.github` 目录下，我提供了默认的 `CI/CD` 流程配置，以及用户提交 `issue` 时的模板。经过少量配置后，就可以实现自动发布 `npm` 包、创建 `git tag` 以及生成 `GitHub release`。
+
+此外，模板里还有许多为 `GitHub` 显示优化的 `md` 文档。
+
+## 部署
+
+文档网站通过 `netlify.toml` 配置部署在 `Netlify` 上。最初我使用的是 `Vercel`，但由于**国内**访问速度的原因，最终迁移到了 `Netlify`。
+
+而且由于我是开源项目贡献者的原因，`Netlify` 为我 `免费` 提供了 `Pro` 版本的计划 (通常这需要 `$19/per member/month`)
+
+感谢 `Netlify`! 爱你❤️😍。
+
+如果看到这里的哥们，你也有一定影响力的开源项目，也可以通过下方的链接申请。
+
+https://www.netlify.com/legal/open-source-policy/
+
+## 总结
+
+从单仓到 `monorepo` 的转变不仅仅是对工具的选择，更是对项目管理模式的优化。通过采用合适的工具链，能够更高效地管理多包项目的同时，利用 `CI/CD` 确保代码的质量和发布的顺畅。
+
+希望这些思考对你有所帮助，也欢迎大家提出各种建议和意见。

package/templates/vitepress/zh/tools/changeset.md

@@ -0,0 +1,75 @@
+# pnpm Versioning
+
+本模板使用 pnpm 11 原生 versioning 管理 monorepo 的变更意图、版本号、changelog 和发布。变更意图仍然使用 `.changeset/*.md` 格式，因此每次改动可以独立提交，不会直接修改包版本。
+
+## 日常开发
+
+```bash
+pnpm change
+pnpm change status
+```
+
+`pnpm change` 会询问受影响的包、patch/minor/major 类型和 changelog 摘要。脚本或自动化场景可以直接指定：
+
+```bash
+pnpm change --bump patch --summary "修复空输入崩溃" repoctl
+```
+
+变更意图会写入 `.changeset/`，与代码一起提交。`pnpm change status` 只预览计划，不会修改文件。
+
+## 版本与 changelog
+
+在 Release PR 中由 CI 消费变更意图：
+
+```bash
+pnpm version -r --dry-run
+pnpm version -r
+```
+
+`pnpm version -r` 会更新受影响包、传播 workspace 依赖、生成 `CHANGELOG.md`，并把消费记录追加到 `.changeset/ledger.yaml`。仓库配置使用 `versioning.changelog.storage: repository`，所以 changelog 会和版本提交一起审查。
+
+`@icebreakers/monorepo` 与 `repoctl` 属于 pnpm fixed group，任一包需要发布时两者始终使用同一个版本。
+
+## 发布
+
+正式发布由 Release PR 合并后的 main workflow 完成：
+
+```bash
+pnpm publish -r --report-summary --provenance --no-git-checks
+```
+
+pnpm 会跳过 registry 中已经存在的版本，并把新发布包写入 `pnpm-publish-summary.json`。CI 根据 summary 创建 `package@version` Git tag 和 GitHub Release，因此重复执行不会重新发布已存在版本。
+
+本地推荐使用 repoctl 包装命令：
+
+```bash
+pnpm exec repo release stable prepare
+pnpm exec repo release stable publish
+```
+
+## Prerelease lanes
+
+alpha、beta、rc、next 是 pnpm lanes，而不是 Changesets pre 状态：
+
+```bash
+pnpm exec repo release pre enter alpha
+git add pnpm-workspace.yaml && git commit -m "chore(release): enter alpha lane"
+git push
+
+pnpm exec repo release pre publish
+```
+
+退出预发布轨道时执行 `pnpm exec repo release pre exit`，提交 `pnpm-workspace.yaml` 后合并回 main。lane 切换必须覆盖 fixed group 的全部包。
+
+## CI 约定
+
+- 生成的 release workflow 只负责 checkout、安装依赖和权限声明，全部业务统一由 `pnpm exec repo release ci` 执行。
+- main push 先生成或更新 Release PR；Release PR 合并后才发布 npm。
+- alpha、beta、rc、next 分支要求所有可发布包位于对应 lane。
+- npm 发布使用 GitHub OIDC provenance，不需要长期保存 `NPM_TOKEN`。
+- 未发布版本恢复使用 workflow dispatch 的 `publish-unpublished` 模式，并按 package/version 校验后发布。
+- repoctl 通过 GitHub REST API 幂等创建或更新 Release PR、package tag 和 GitHub Release，重复执行不会重复创建元数据。
+
+存量项目首次迁移运行 `pnpm dlx repoctl@latest upgrade --yes`。带有
+`repoctl-managed: release/v2` 的 workflow 会自动升级；未标记的自定义
+workflow 默认保留，可在确认后使用 `repo upgrade --overwrite-release`。

package/templates/vitepress/zh/tools/husky.md

@@ -0,0 +1,130 @@
+# Husky
+
+在 repoctl 体系里，Husky 是 Git hook 触发器；真正的校验逻辑尽量收口到 repoctl 命令，方便本地、CI 和手动复现使用同一套入口。
+
+```bash
+repo verify pre-commit
+repo verify commit-msg .git/COMMIT_EDITMSG
+repo verify pre-push
+```
+
+如果你只想手动复现推荐校验，用：
+
+```bash
+repo check --staged
+repo check --full
+```
+
+继续看：[repoctl 工作流与 CI](../repoctl/workflows.md)。
+
+## 1. 什么是 Husky？
+
+**Husky** 是一个用于在 **Git hooks**（如 `pre-commit`、`pre-push`、`commit-msg` 等）中运行脚本的工具。
+它的作用是让你在提交代码前或推送代码前，自动执行一些校验、格式化或测试，从而保证代码质量和团队规范。
+
+> 简单来说：**Husky = Git hooks 的管理工具**。
+
+## 2. Husky 有什么用？
+
+常见用途：
+
+1. **代码格式化**
+   在提交前运行 `prettier --write .`，确保代码风格一致。
+2. **Lint 检查**
+   在 `pre-commit` 时执行 `eslint`，防止有 lint 错误的代码被提交。
+3. **推送前执行整仓校验**
+   在 `pre-push` 时执行整仓 `lint`、`typecheck`，并按需补跑 `build`、`test`、`tsd`，防止未通过校验的代码被推送。
+4. **Commit 信息校验**
+   在 `commit-msg` hook 中使用 [commitlint](https://github.com/conventional-changelog/commitlint) 强制提交信息符合规范（如 Conventional Commits）。
+
+## 3. 如何使用 Husky？
+
+### 安装
+
+```bash
+npm install husky --save-dev
+```
+
+### 初始化
+
+```bash
+npx husky init
+```
+
+这会生成一个 `.husky` 目录，并在里面创建 `pre-commit` 文件，默认内容可能是：
+
+```bash
+#!/bin/sh
+npm test
+```
+
+### 添加 Hook
+
+假设你想在提交前运行 ESLint，可以这样：
+
+```bash
+npx husky add .husky/pre-commit "npm run lint"
+```
+
+生成的 `.husky/pre-commit` 文件类似：
+
+```bash
+#!/bin/sh
+npm run lint
+```
+
+### 使用 commit-msg 校验提交信息
+
+先装 commitlint：
+
+```bash
+npm install @commitlint/{config-conventional,cli} --save-dev
+```
+
+创建配置文件 `commitlint.config.js`：
+
+```js
+module.exports = { extends: ['@commitlint/config-conventional'] }
+```
+
+添加 hook：
+
+```bash
+npx husky add .husky/commit-msg "npx --no-install commitlint --edit $1"
+```
+
+这样，若提交信息不符合规范，会被拦截。
+
+## 4. 和 lint-staged 搭配
+
+通常 Husky 会和 [lint-staged](https://github.com/okonet/lint-staged) 搭配使用：
+只检查本次改动的文件，而不是全量检查。
+
+示例：
+`package.json` 里加：
+
+```json
+{
+  "lint-staged": {
+    "*.js": "eslint --fix",
+    "*.ts": "eslint --fix"
+  }
+}
+```
+
+然后在 `.husky/pre-commit` 文件中写：
+
+```bash
+npx lint-staged
+```
+
+在本仓库默认实现里，`pre-commit` 和 `pre-push` 的职责拆分是：
+
+- `pre-commit`：只针对 staged 文件执行 `eslint`、`stylelint` 和 workspace `typecheck`
+- `pre-push`：强制执行整仓 `pnpm lint`、`pnpm typecheck`，并根据改动范围补跑 `build`、`test`、`tsd`
+
+## 总结
+
+- **Husky** 是一个 Git hooks 工具，用来在 commit、push 等阶段运行脚本。
+- 主要用于 **代码质量控制**：lint、格式化、测试、commit message 校验等。
+- 使用方式：安装 → 初始化 → 添加 hooks → 编写脚本。