Front-End-Checklist 仓库工程化脚本体系全指南从规则校验、内容生成到 CI 预提交检查【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist导读scripts/是 Front-End-Checklist 仓库面向人类与 AI Agent 的现代 Web 开发清单项目的自动化中枢仓库中 385 条规则 MDX、指南、技能包skills的生成、校验、质量评分与发布前检查全部由这里承载。读完本文你将掌握该仓库完整的脚本分组结构、每条命令的用途与参数、lefthook.yml预提交钩子如何把这些脚本织入开发流程以及如何基于仓库源码理解每个脚本的底层实现逻辑。1. 总览脚本按用途分组统一从仓库根目录运行scripts/目录的顶层说明scripts/README.md明确了一条核心约定脚本按用途分组除特别注明外一律在仓库根目录通过pnpm script运行。所有 npm 脚本别名集中在根 package.json 的scripts字段中例如validate:rule-structure: tsx scripts/rule-structure/validate-rule-structure.ts因此底层是tsx直接执行 TypeScript 脚本无需预先编译。目录分组如下目录用途scripts/lib/规则解析与结构分析的共享工具库被 generate、rule-structure、validate 三组复用不可直接运行scripts/validation/预提交检查器由 lefthook 在暂存文件上执行scripts/generate/从规则 MDX 生成衍生产物skills、hints、support notes、verification splitscripts/guide-structure/校验带类型指南的章节顺序与指南模板规则scripts/rule-structure/校验、修复、规范化、评分与审查规则 MDX 的内联链接机会scripts/validate/校验来源URL与包依赖一致性scripts/audit/MCP 审计工具质量流水线、A/B 影响基准、技能质量评分根目录还有scripts/setup-qmd.sh用于 QMD 环境的 setup/embed通过pnpm qmd:setup/pnpm qmd:embed调用。从实际文件清单看lib/提供了 rule-structure.ts、rule-inline-links.ts、rule-support-data.ts、guide-structure.ts 四个共享模块每个脚本目录下还配套__tests__/测试目录如 rule-structure.test.ts、validate-evidence.test.ts可见共享逻辑放 lib、命令入口独立成文件、测试紧随其后是该脚本体系的组织范式。2. 核心CI / lefthook提交与流水线必须保留的命令这组命令在 CI 或提交时运行是内容质量的红线README 明确要求keep them命令作用使用方pnpm validate:rule-structure校验规则章节顺序与最后的## Verification标题CI、lefthook规则 MDX 变更时pnpm validate:guide-structure按类型how-to或insight校验指南章节顺序CI、指南编写pnpm validate:guides强制指南发布就绪检查封面图、链接、阅读水平、元数据CI、指南编写pnpm score:rules规则评分≥50 通过变更规则低于阈值则提交失败lefthook规则 MDX 变更时pnpm generate:skills从规则 MDX 重新生成skills/lefthook规则 MDX 变更时pnpm generate:readme重新生成 README 清单与生成的目录副本lefthook规则 MDX 变更时pnpm validate:evidence校验规则上的来源质量元数据CI、规则编写这些命令在 lefthook.yml 中的绑定方式非常清晰凡是glob: packages/content/rules/en/**/*.mdx的钩子generate-skills、generate-readme、validate-rule-structure、validate-evidence、score-rules都会在规则文件变更时被触发其中generate-skills和generate-readme还会在成功后执行git add skills/与git add README.md docs/generated/rules-catalog.md把衍生产物自动纳入暂存区——这正是规则即单一事实来源、产物自动同步的设计。3. 规则编写面向packages/content/rules/en/的完整工作流编写或编辑规则存放在packages/content/rules/en/时下面这组命令构成从校验、修复到打分的闭环命令作用pnpm validate:rule-structure检查结构加--report可查看分类漂移category driftpnpm report:v2-gaps等价于validate:rule-structure --report条件性 V2 缺口报告pnpm score:rules规则评分支持--failing、--json、--min 60或直接传文件路径pnpm fix:rule-structure自动修复章节顺序/标题加--write落盘pnpm normalize:rule-structure规范化 Verification 标题与尾部章节加--writepnpm expand:related-rules展开 frontmatter 中的relatedRules加--writepnpm backfill:inline-links用轻量内联链接回填稀疏的规则正文--category、--writepnpm report:rule-links审查内联链接密度、警告与候选内/外部链接--category、--jsonpnpm inject:rule-linksreport:rule-links的已弃用别名只读、不再编辑文件详细工作流参见 AGENTS.md 与 docs/rule-structure.md。3.1 底层契约规则正文的机器可检测结构为什么validate:rule-structure有能力强制章节顺序与最后的## Verification标题答案在 docs/rule-structure.md 定义的单一机器可检测正文契约中任何 H2 之前必须有导语段落## Code Example或## Code Examples## Why It Matters可选的实现/指引章节## Verification必须是最后一个 H2同时有硬性顺序约束## Code Example(s)必须出现在## Why It Matters之前后者又必须出现在## Verification之前。契约 V2 还允许条件性章节## Exceptions针对易误报规则、## Verification内部的### Automated Checks/### Manual Checks分栏、以及## Browser Support/## Support Notes/## Standards。实现上validate-rule-structure.ts 中的getFlagValue同时支持--flagvalue与--flag value两种传参写法并复用lib/rule-structure的analyzeRuleStructure做章节分析再结合OPTIONAL_RULE_SECTION_TAXONOMY报告未知标题——这解释了 README 中validator 会报告分类外的标题防止一次性新章节名悄然扩散的机制。3.2 评分维度分数从哪来score-rules.ts 的注释给出了完整参数面默认--min 50DEFAULT_MIN_SCORE 50支持--failing只看未达标、--json输出结构化结果、自定义阈值与指定文件。评分时不仅检查结构还会用STUB_PATTERNS正则如/^verify if the project adheres to/i、/^update the codebase to align with/i识别模板占位提示词从多个维度结构契约、阈值可见性、来源质量等综合打分低于阈值即标记待改进——这也正是 lefthook 用它拦截低质量规则提交的依据。3.3 内联链接契约report:rule-links/backfill:inline-links背后是 docs/rule-structure.md 的内联链接契约正文散文可含自然内联链接但保持轻触式密度通常每条规则2-5个导语0-1个、主指引章节1-3个、内部规则链接0-1个sources作为权威证据登记处、resources放延伸阅读、relatedRules作为关联发现图不允许出现See also ...这类独立元数据段落。报告工具会根据这些规则给出链接密度、警告与候选链接。4. 指南编写面向packages/content/guides/en/的检查与测试命令作用pnpm validate:guide-structure检查how-to与insight指南的必需章节顺序pnpm validate:guides强制发布就绪必需 frontmatter、封面图、链接、最小深度与可读性pnpm test:guide-structure运行指南结构与校验测试实现文件位于 validate-guide-structure.ts 与 validate-guides.ts共享逻辑在scripts/lib/guide-structure.ts对应的测试入口见 guide-structure.test.ts 与 validate-guides.test.ts根 package.json 中test:guide-structure同时加载这两个测试文件。写作规范参考 docs/guides-authoring.md 与 docs/guide-template.mdx。5. 生成类命令从规则 MDX 产出衍生内容修改规则或更新 hints/support 数据后需要重新生成衍生产物命令作用pnpm generate:skills从规则 MDX 重新生成skills/SKILL.md referencespnpm generate:readme重新生成根 README 清单与生成目录副本pnpm generate:exceptions-hints对缺失## Exceptions章节的规则给出 dry-run 建议pnpm generate:support-notes基于浏览器数据给出 support-note 的 dry-run 建议pnpm generate:verification-split对## Verification的自动/手动拆分给出 dry-run 建议pnpm backfill:sources规范化规则 MDX 的 source id、role 与 authoritypnpm backfill:evidencebackfill:sources的别名旧命令名仍被引用期间的过渡实现上generate:skills对应 generate-skills.tsgenerate:readme对应 generate-readme.ts配套测试 generate-readme.test.ts另有 generate-exceptions-hints.ts、generate-support-notes.ts、generate-verification-split.ts 与 backfill-rule-evidence.ts。注意前三类 generate 命令默认是 dry-run真正写盘需配合脚本自身的写盘开关如--write。6. 校验类命令URL 来源、证据元数据与包一致性命令作用pnpm validate:sources校验规则 frontmatter 中sources、resources的外部 URLpnpm validate:evidence校验来源元数据最少来源数、来源角色、主要来源与分类级来源质量pnpm validate:packages检查 monorepo 内包依赖一致性实现位于 validate-sources.ts、validate-evidence.ts、validate-packages.ts。其中证据校验的判定策略沉淀为可读的配置文件策略来源见 source-validation-policy.ts 与 evidence-policy.ts阈值与规则清单则记录在 source-validation-policy.json、evidence-policy.json 中配套测试 validate-evidence.test.ts 与 source-validation-policy.test.ts 保证策略行为可回归。这种策略文件与实现分离的设计让非开发者也能直接调整质量门槛。7. 审计类命令MCP 质量与技能质量命令作用pnpm mcp:auditMCP 质量流水线单元测试 可选安全扫描详见 docs/mcp-quality.mdpnpm mcp:audit:security对packages/mcp/src运行mcp-security-auditorpnpm mcp:evaluate运行确定性 MCP 质量评估检索、审查准确性、工具契约、改进影响pnpm mcp:impact -- --init dir创建 A/B 基准工作区测试 MCP 访问是否提升 Agent 修复代码的效果pnpm mcp:impact -- --score dir给无 MCP vs 有 MCP 的基准输出打分pnpm mcp:impact -- --self-test用内置固定夹具验证影响基准评分器pnpm skills:audit按 Agent 技能模式给生成的 skills 打分报告高价值缺失规则候选入口脚本集中在 scripts/audit/mcp-audit.ts、mcp-impact-benchmark.ts、skills-quality-audit.ts。从根 package.json 可以看到mcp:audit:security实际执行的是pnpm dlx mcp-security-auditorlatest scan packages/mcp/src --fail-on critical——即以 critical 级别为失败阈值的临时下载扫描。MCP 包本体位于 packages/mcp/其设计说明见 packages/mcp/SPEC.md。8. 预提交检查器validationlefthook 自动执行也可手动运行Lefthook 会自动运行这些检查器但 README 明确它们也可手动单独执行脚本用途check-as-casts.jsTypeScriptas断言校验check-barrel-files.jsBarrel 文件再导出规则check-console-logs.js禁止应用代码中散落的console.logcheck-directory-structure.js强制目录布局check-file-complexity.js文件复杂度上限check-jsdoc.jsJSDoc 规则check-relative-imports.ts在apps/web中强制路径别名禁止深层相对导入这些钩子在 lefthook.yml 中的pre-commit段有完整对应除上述检查器外还串入pnpm biome check --write格式化/静态检查并自动stage_fixed、基于正则的密钥泄漏扫描如sk_live_、ghp_、AKIA...等模式、500KB 大文件拦截、package.json 排序、web 相关测试与覆盖率检查。pre-push阶段则运行apps/web的测试与turbo build --filterweb构建检查commit-msg阶段用 commitlint 约束提交信息格式。这套配置完整呈现了提交前质量网的层次内容规则generate/validate/score→ 代码风格biome/各 check-*→ 安全密钥/大文件→ 测试test-modified/check-coverage。9. 测试命令命令作用pnpm test:rule-structure运行 rule-structure 共享库与评分测试从根 package.json 看该命令为node --import tsx --test scripts/rule-structure/__tests__/*.test.ts scripts/validate/__tests__/*.test.ts即用 Node 原生测试运行器加载两个测试目录下的全部测试包括 rule-inline-links.test.ts、rule-structure.test.ts 等配合 scripts/validate/ 下的证据/来源策略测试共同覆盖规则结构与验证逻辑。10. 常用参数速查综合 README 与各脚本头部注释以下是常用命令的参数面汇总供实际使用参考命令参数说明validate:rule-structure--report/--json/--write-baseline/ 文件路径分类漂移报告、JSON 输出、写回基线、定点检查score:rules--failing/--json/--min n/ 文件路径只看未达标、JSON 输出、自定义最低分默认 50fix:rule-structure/normalize:rule-structure/expand:related-rules--write写盘落盘开关不加则 dry-runbackfill:inline-links--category/--write限定分类、写盘report:rule-links--category/--json限定分类、JSON 输出mcp:impact--init dir/--score dir/--self-test初始化基准、评分、自检11. 如何接入这套流程仓库使用 pnpm 工作区见根 package.json 的workspaces与 pnpm-workspace.yamlpackageManager: pnpm10.33.0Node 要求24.15.0 25。安装依赖后prepare钩子会通过 install-lefthook.mjs 自动安装 lefthook之后每次提交自动执行上文全部检查也可用pnpm lefthook:run手动跑一次 pre-commit 全套。CI 侧根 package.json 的ci:check串起了 lint、typecheck、三组结构/证据校验与全量测试ci:e2e则先构建再跑端到端测试——这两个组合命令可作为团队接入本仓库 CI 的参考模板。结语Front-End-Checklist 的scripts/是一个典型的内容工程化样板以packages/content/rules/en/的 MDX 为单一事实来源通过rule-structure系列的校验/修复/评分保证结构契约通过generate系列同步衍生 skills 与 README通过validate系列守住来源与证据质量再靠 lefthook 把这些检查无感地织入每一次提交。无论你是本仓库的贡献者、希望把规则治理经验迁移到自建内容体系还是想了解人类与 AI Agent 共享同一套内容契约如何落地都可以直接对照本文的命令表在仓库根目录用pnpm script逐个体验。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考