项目四：前端规范 CLI 与研发效能平台

资料中的“企业级前端编码规范工程化”项目包含多包管理、ESLint/Stylelint/Commitlint/Markdownlint、Prettier、Husky、脚手架接入、存量扫描修复、CHANGELOG 和静态文档站点。本文把它整理成可在团队中渐进落地的治理项目；示例中的效率/成本数字均不作为既定成果。

1. 背景与目标

当团队从一个项目扩展到多个 React、Vue、Node 或文档仓库时，规范问题会从个人习惯变成协作成本：

不同项目复制出多份规则，修复一个误报要改很多仓库。
新成员接入依赖手工安装，配置文件和 Node 版本不一致。
存量代码一次性全量格式化会产生巨大 diff，难以审查和回滚。
只在本地 pre-commit 检查会被跳过；只在 CI 检查又反馈过慢。
规则过严会制造噪声，规则过松又无法阻止新问题。

项目目标是提供一个“共享配置包 + 交互式 CLI + 增量门禁 + 可回滚发布”的工具链：新项目能快速接入，老项目能按目录和规则逐步迁移，规范结果可在本地、CI 和发布系统中复现。

2. 产品边界

规范包（规则与共享配置）
       ^
CLI（检测项目类型、安装依赖、生成配置、扫描/修复）
       ^
Git hooks / CI（增量门禁与报告）
       ^
项目仓库（JS/TS/React/Vue/Node/Markdown/CSS）

能力	负责	明确不负责
共享规范包	规则、默认配置、版本和迁移说明	业务架构和代码自动重构的一切决策
CLI 初始化	检测项目、选择 preset、安装依赖、生成配置	覆盖用户已有配置而不备份
扫描/修复	输出问题、自动修复确定性规则、生成报告	静默改写语义不明确的代码
Git hooks	对暂存文件做快速增量检查	把完整构建和所有 E2E 塞进提交钩子
CI 门禁	在干净环境复跑类型/Lint/测试/构建	只信任本地检查结果
文档站点	规则解释、示例、迁移和变更日志	把文档示例当成项目实际通过证据

规范工具不会自动提升所有业务指标；它主要降低不一致和回归风险，结果要由代码质量、CI 失败类型、缺陷和开发反馈共同证明。

3. 多包仓库与版本边界

可以用 pnpm workspace（历史项目也可能使用 Lerna）组织多个包：

packages/
  eslint-config-acme/
  stylelint-config-acme/
  commitlint-config-acme/
  markdownlint-config-acme/
  eslint-plugin-acme/
  cli/
docs/

每个包声明自己的依赖、Node 支持范围和公开入口，锁文件由仓库统一管理。配置包与插件分开，便于消费者只安装需要的能力；CLI 不应把自身运行时依赖偷偷写入业务依赖。

发布契约至少包含：

exports、类型声明和可执行 bin 入口明确且可从干净消费者项目安装。
语义化版本和弃用周期；规则新增、修复和破坏性默认行为分别记录。
CHANGELOG 说明规则变化、影响文件类型、自动修复风险和回滚方式。
Node、包管理器、配置格式和插件 API 的兼容矩阵。
发布产物绑定 commit 和构建环境，同一版本号不能覆盖不同内容。

4. CLI 接入流程

交互式 CLI 可以按以下步骤运行：

detect -> choose preset -> inspect existing config
       -> install dependencies -> write files with backup
       -> run dry-run -> apply incremental fixes -> report

检测项目时读取 package.json、tsconfig 和已有配置，但不执行任意项目脚本。生成 .eslintrc、.stylelintrc、commitlint.config、.markdownlint、.prettierrc、.editorconfig 等文件前：

检查目标文件是否存在，默认只合并明确字段，不覆盖未知配置。
对自动写入留备份或生成可回滚 patch，打印实际变更。
根据 JavaScript/TypeScript/React/Vue/Node 选择 preset；跨项目共享的规则放包内。
依赖安装失败、版本不兼容或规则解析失败时返回可读错误，不留下半配置状态。
支持 --dry-run、--files、--fix、--format 和退出码约定，方便 CI 调用。

CLI 自身也要有单元和黑盒测试：空项目、已有冲突配置、monorepo、Windows 路径、pnpm/npm/yarn、无网络和权限不足都应覆盖。

5. 规则设计与自动修复

规则优先级按风险和确定性分层：

层级	示例	策略
必须阻断	语法错误、危险 API、类型错误、提交格式无效	本地快速反馈，CI 必须通过
可自动修复	缩进、引号、排序、确定性格式	只改语义等价内容，输出 diff
建议项	命名、复杂度、可维护性提示	默认 warning，团队确认后再升级
需人工判断	大规模重构、业务约定、旧 API 替换	只报告，不自动写入

自定义 ESLint 插件应使用 AST 访问节点并返回位置、规则 ID、消息和可选 fix；fix 必须幂等，重复执行不应继续产生 diff。对 TypeScript 类型信息规则要说明解析成本和 tsconfig 边界，避免把所有 lint 都升级成慢速类型检查。

不要把“规则数量”当项目价值。每条规则都要有触发样例、误报样例、修复说明、owner 和弃用计划。

6. 存量迁移与增量门禁

老项目最稳妥的策略是“新代码不新增问题，旧问题按目录/规则分批还债”：

基线快照 -> 按风险排序 -> 选择目录/团队 -> dry-run 报告
         -> 自动修复确定性问题 -> 人工审查 -> 更新基线
         -> CI 只阻断新增问题 -> 定期缩小豁免范围

基线文件必须记录生成版本、规则版本、文件范围和责任人，不能把全仓库 eslint-disable 当永久垃圾桶。每个豁免要有原因、期限和 issue；过期自动提醒。自动修复前保存 patch，并在 CI 中跑类型、测试和构建，防止格式化工具改变语义。

新项目的 pre-commit 只检查暂存文件，commit-msg 检查提交格式；完整检查放在 CI。钩子被跳过、脚本超时或开发机环境不一致时，CI 仍是最终门禁。

7. CI/CD 与文档交付

PR -> 安装锁定依赖 -> lint/typecheck/test -> 生成报告
   -> 构建规范包与 CLI -> 包内容/exports 检查
   -> 预发布消费者验证 -> 发布版本与 CHANGELOG
   -> 文档站点部署 -> 监控失败/回滚

文档站点要展示规则的背景、错误示例、修复示例、配置覆盖方式和迁移路径。文档与包从同一 commit 构建，避免“文档说已支持、发布包却缺少规则”。发布前用最小消费者项目验证：安装、执行 bin、解析配置、导入类型、运行 lint 和执行 --fix。

自动生成 CHANGELOG 只能提供草稿；破坏性规则、默认级别变化和自动修复风险必须人工确认。发布失败时保留上一稳定版本，禁止复用同一版本号覆盖坏产物。

8. 安全与可靠性边界

CLI 读取项目文件时限制工作区路径，不跟随不可信软链接写出工作区。
不执行配置文件中的任意函数，不把仓库内容上传到未授权服务。
报告和日志中脱敏本地路径、令牌、环境变量和业务代码片段。
依赖和插件固定版本并做供应链扫描；规则包本身应尽量无网络副作用。
配置写入采用临时文件 + 原子替换，进程中断时不留下半文件。
规则解析超时或内存异常时给出退出码和恢复方式，不阻塞业务提交。

9. 失败场景与复盘

场景	影响	处理与改进
新规则误报过多	团队绕过钩子/关闭规则	先 warning，抽样统计真阳性，补 fixture 后再升级
自动修复改坏语义	大量回滚和信任下降	限定语义等价 fix，先 dry-run，要求类型/测试通过
配置包版本漂移	同一仓库在本地/CI 结果不同	锁版本、兼容矩阵、可复现安装和发布 smoke test
全量迁移 diff 过大	PR 无法审查	基线 + 分目录迁移，保留责任人和期限
pre-commit 太慢	开发者跳过钩子	只查暂存文件，重检查放 CI，记录耗时 P95
CLI 覆盖已有配置	项目无法启动	备份/合并/回滚，生成变更清单和非零退出码
CI 与本地不一致	反馈失真	固定 Node/包管理器、镜像和命令，上传完整日志

复盘要回答：问题是规则错误、配置边界、依赖漂移还是流程设计错误；哪个测试应在发布前捕获；如何让使用者能快速关闭单条高风险规则并恢复工作。

10. 指标与验证

建议将“治理结果”和“开发成本”分开：

维度	指标定义	证据
采用	接入仓库/包数、活跃版本、升级完成率	包下载/仓库清单、CLI 运行记录
质量	新增 lint 问题数、规则真阳性率、回归缺陷	CI 报告、issue 和缺陷单
迁移	每周关闭问题数、基线规模、自动修复回滚率	基线 diff、迁移 PR
交付	CLI 接入耗时、CI 检查耗时 P50/P95、发布失败率	CI/CLI 日志
体验	误报反馈、钩子跳过率、开发者满意度	反馈表、审计日志

测量时固定仓库样本、规则版本、Node 版本和时间窗口；不能把接入包数量或某个示例百分比直接等同于“效率提升”。

11. 面试表达与追问

三分钟版本

多个仓库的规范配置分叉，老项目又无法一次性全量整改。我负责把共享配置、CLI 接入、增量基线和 CI 门禁做成一条可回滚链路。
CLI 先检测项目和已有配置，生成备份并支持 dry-run；规则按阻断、自动修复、建议和人工判断分层，老问题用基线逐步迁移，新代码只阻断新增问题。
pre-commit 只检查暂存文件，完整类型/Lint/测试/构建在 CI 复跑，发布包用干净消费者项目验证 exports、bin 和类型。
一次误报或自动修复问题会通过 fixture、owner、版本和回滚机制复盘；结果以真实接入、缺陷、CI 耗时和迁移记录证明，而不是宣传数字。

高频追问

追问	回答要点	深入阅读
为什么不复制一份配置到每个项目？	共享包统一规则和版本，项目只保留少量覆盖；代价是兼容矩阵和迁移治理	组件库工程化
为什么要基线而不是一次修完？	大 diff 难审查、风险高；基线阻断新增问题并按目录还债，旧豁免有 owner/期限	前端项目架构设计与选型
ESLint fix 是否安全？	只自动修复语义等价规则，先 dry-run/patch，再跑类型和测试；复杂重构只报告	Webpack/Babel AST
pre-commit 被跳过怎么办？	它是快速反馈，不是最终门禁；CI 在干净环境重跑并记录跳过/失败	技术误区与验证
如何证明规范工具有效？	固定样本和版本，分开测新问题、缺陷、迁移和耗时；统计误报及回滚成本	项目亮点总览

12. 交付清单

共享配置/插件/CLI 有包边界、版本和兼容矩阵。
CLI 支持检测、dry-run、备份、增量扫描、自动修复和稳定退出码。
规则有 fixture、真阳性/误报样例、owner 和弃用计划。
老项目采用基线与分批迁移，新代码阻断新增问题。
pre-commit、CI、发布和文档链路职责清晰且可回滚。
干净消费者项目验证包入口、类型、bin 和配置解析。
指标带样本、版本、时间窗口和成本，不使用无法举证的收益数字。

来源：高级前端亮点项目.pdf 第 35-37 页（规范包、CLI、扫描/修复、Husky、文档和 GitHub Actions）；结合 前端架构师工程化思维与编译原理详解.pdf（AST 转换、Babel visitor、Loader/Plugin 生命周期）和 高频真题解析与9月考点预测上.pdf 第 18-30 页（Webpack/AST/Loader/Plugin 构建链路）整理。