企业官网建设流程全解析

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/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"：

这些命令在 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/）时，下面这组命令构成从校验、修复到打分的闭环：

详细工作流参见 AGENTS.md 与 docs/rule-structure.md。

3.1 底层契约：规则正文的机器可检测结构

为什么validate:rule-structure有能力强制"章节顺序与最后的## Verification标题"？答案在 docs/rule-structure.md 定义的单一机器可检测正文契约中：

1. 任何 H2 之前必须有导语段落
2. ## Code Example或## Code Examples
3. ## Why It Matters
4. 可选的实现/指引章节
5. ## 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同时支持--flag=value与--flag value两种传参写法，并复用lib/rule-structure的analyzeRuleStructure做章节分析，再结合OPTIONAL_RULE_SECTION_TAXONOMY报告未知标题——这解释了 README 中"validator 会报告分类外的标题，防止一次性新章节名悄然扩散"的机制。

3.2 评分维度：分数从哪来

score-rules.ts 的注释给出了完整参数面：默认--min 50（DEFAULT_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/的检查与测试

实现文件位于 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 数据后，需要重新生成衍生产物：

实现上：generate:skills对应 generate-skills.ts，generate: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 来源、证据元数据与包一致性

实现位于 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 质量与技能质量

入口脚本集中在 scripts/audit/：mcp-audit.ts、mcp-impact-benchmark.ts、skills-quality-audit.ts。从根 package.json 可以看到mcp:audit:security实际执行的是pnpm dlx mcp-security-auditor@latest scan packages/mcp/src --fail-on critical——即以 critical 级别为失败阈值的临时下载扫描。MCP 包本体位于 packages/mcp/，其设计说明见 packages/mcp/SPEC.md。

8. 预提交检查器（validation）：lefthook 自动执行，也可手动运行

Lefthook 会自动运行这些检查器，但 README 明确它们也可手动单独执行：

这些钩子在 lefthook.yml 中的pre-commit段有完整对应：除上述检查器外，还串入pnpm biome check --write（格式化/静态检查并自动stage_fixed）、基于正则的密钥泄漏扫描（如sk_live_、ghp_、AKIA...等模式）、500KB 大文件拦截、package.json 排序、web 相关测试与覆盖率检查。pre-push阶段则运行apps/web的测试与turbo build --filter=web构建检查，commit-msg阶段用 commitlint 约束提交信息格式。这套配置完整呈现了"提交前质量网"的层次：内容规则（generate/validate/score）→ 代码风格（biome/各 check-*）→ 安全（密钥/大文件）→ 测试（test-modified/check-coverage）。

9. 测试命令

从根 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 与各脚本头部注释，以下是常用命令的参数面汇总（供实际使用参考）：

11. 如何接入这套流程

仓库使用 pnpm 工作区（见根 package.json 的workspaces与 pnpm-workspace.yaml，packageManager: pnpm@10.33.0，Node 要求>=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