质量门禁质量门禁是本项目交付闭环的最后一道防线。它由本地门禁make test和CI 门禁GitHub Actions两层构成共 8 项自动化检查确保每一次提交都满足文档结构、链接完整性、元数据一致性和 AI 引用准确性四类约束。对于高级开发者而言理解门禁的分层架构和每项检查的内部逻辑是高效通过 CI 并在本地快速定位问题的前提。架构总览质量门禁采用本地优先、CI 兜底的双层策略。开发者在提交前通过make test在本地执行全部 7 项同步检查推送后 GitHub Actions 在markdown-lintjob 中复现同样的 7 项检查并在link-checkerjob 中补充外部链接验证。两层共享同一套脚本和配置消除了“本地通过但 CI 失败”的环境差异问题。门禁检查项详解1. Markdown 格式检查make lint由npx --yes markdownlint-cli0.48.0执行固定版本号以避免跨环境行为差异。规则配置集中管理于.github/lint_config.jsonCI 和本地共享同一份配置文件。当前配置采用白名单策略——default: true启用所有规则随后逐项禁用不适用的规则如 MD001/MD013/MD025 等保留项目实际需要的子集。检查范围覆盖全仓库**/*.md但排除.history和tools/external目录。lint 规则的增删必须同时修改.github/lint_config.json因为Makefile和 CI 都引用该文件。不要在命令行通过--rule参数覆盖否则会导致本地/CI 行为不一致。2. 本地链接与锚点检查check-links脚本 check-local-links.py 遍历仓库内所有 Markdown 文件提取两种模式的链接标准 Markdown 链接和 HTML 属性href.../src...。对于每个非外部链接执行两项验证文件存在性解析目标路径确认文件在仓库内存在锚点存在性如果目标包含#fragment提取目标文件的全部锚点集合包括a id...手动锚点和通过github_slug()算法从标题自动生成的锚点确认 fragment 在集合中脚本内置了代码围栏感知strip_fenced_code避免误报代码块内的链接。跳过目录包括.git、.history、node_modules、.github/wiki、tools/external和tools/chat-vault。3. 折叠块结构检查check-details脚本 check-markdown-details.py 验证所有details块的结构完整性执行三项检查每个details必须有对应的/details关闭标签每个details块内必须包含summary标签每个summary标签内容必须包含“点击展开/收起”提示文字同一details块内不允许重复的summary标签错误输出格式为MARKDOWN_DETAILS_ERRORS附带文件路径和行号。4. 文档结构检查check-doc-structure脚本 check-doc-structure.py 是最复杂的门禁项它通过scripts/lib/taxonomy.py读取metadata/taxonomy.yml中定义的文档分类体系对docs/下的线性 README 执行多层约束验证。核心检查包括四个维度标准块顺序验证每个 docs README 必须按固定顺序包含五个标准块——顶部标题块、## 字多不看、## 快速导航、完整细粒度目录details折叠块、## 使用方式。H1 标题和## 字多不看之间禁止插入任何内容。同时检查是否包含禁止标题如“和其他目录的边界”、“维护规则”。主锚点顺序验证从 taxonomy 获取每个文档的expected_anchors验证这些锚点在 README 中的出现顺序与 taxonomy 定义一致且全部存在。目录覆盖验证提取顶部导航和折叠细粒度目录中的所有#anchor链接确认所有主锚点和以主锚点为前缀的手动锚点都在目录中有对应条目。重复锚点检测对全仓库所有 Markdown 文件排除 skip 列表进行a id...重复锚点扫描确保每个手动锚点全局唯一。5. 目录文档覆盖检查check-directory-docs脚本 check-directory-docs.py 维护一个硬编码的REQUIRED_DIRS列表约 35 个目录验证每个目录都包含必需的文档文件。默认要求同时存在README.md和AGENTS.md.github/目录例外仅要求AGENTS.md避免 GitHub 首页误展示平台配置说明。脚本还会自动发现仓库中未被REQUIRED_DIRS列表覆盖的新目录排除 symlink、vendor subtree 和生成目录确保新目录不会遗漏文档。6. 元数据路径与锚点检查check-metadata脚本 check-metadata.py 验证metadata/taxonomy.yml和metadata/redirects.yml中所有引用的本地路径和锚点是否有效。对于taxonomy.yml解析path:、entry:、agent_guide:字段值以及-列表项中的路径引用对于redirects.yml额外执行三项专项检查重定向源路径是否仍然存在于仓库中存在则说明迁移未完成重定向源是否映射到自身no-op redirect重定向源是否重复定义当 taxonomy 或 redirects 发生修改时先运行make check-metadata验证路径有效性再运行完整make test。元数据错误通常表现为“missing metadata target”或“missing metadata anchor”。7. AI 引用语料检查check-ai-citation脚本 check-ai-citation.py 覆盖两个 AI 入口文件llms.txt和assets/ai-citation/llms-full.txt以及assets/ai-citation/*.md目录下的所有 Markdown 文件。验证机制与check-local-links.py类似但使用更宽泛的PATH_PATTERN正则以捕获非链接格式的路径引用如纯文本中的docs/concepts/README.md。额外验证llms-full.txt是否覆盖了 taxonomy 中定义的所有文档路径确保 AI 完整上下文入口的完整性。8. 外部链接检查CI link-checker在 CI 层ci.yml 中的link-checkerjob 使用lycheeverse/lychee-actionv2.8.0检查仓库内所有 Markdown 文件中的外部链接有效性。此检查仅在 CI 中运行不在make test中包含因为它需要网络访问且耗时较长。配置文件为.lychee.toml。检查项全览| |:--|:------|:---------|:-----|:--------|:--------|| 1 | Markdown 格式 |make lint|npx markdownlint-cli|.history,tools/external| markdownlint 原生输出 || 2 | 本地链接/锚点 |make check-links|check-local-links.py|.git,.history,node_modules,.github/wiki,tools/external,tools/chat-vault|MISSING_LINKS,MISSING_ANCHORS|| 3 | 折叠块结构 |make check-details|check-markdown-details.py|.git,.history,node_modules,.github/wiki,tools/external|MARKDOWN_DETAILS_ERRORS|| 4 | 文档结构 |make check-doc-structure|check-doc-structure.py|.git,.history,node_modules,.github/wiki,tools/external|DOC_STRUCTURE_ERRORS|| 5 | 目录文档覆盖 |make check-directory-docs|check-directory-docs.py| symlink, vendor subtree |DIRECTORY_DOC_ERRORS|| 6 | 元数据路径 |make check-metadata|check-metadata.py| 无 |METADATA_ERRORS|| 7 | AI 引用路径 |make check-ai-citation|check-ai-citation.py| 无 |AI_CITATION_ERRORS|| 8 | 外部链接 | CI only | lychee-action | 由.lychee.toml控制 | lychee 原生输出 |CI 触发与流水线GitHub Actions 工作流定义于 .github/workflows/ci.yml在以下三种条件下触发push到develop或master分支pull_request目标为develop或master分支手动workflow_dispatch触发流水线包含两个并行 jobmarkdown-lint7 项同步检查和link-checker外部链接。两个 job 都使用actions/checkoutv6并启用submodules: recursive确保外部 submodule 中的文件也被纳入检查范围。辅助工具sync-doc-tocmake sync-doc-toc执行 sync-doc-toc.py根据metadata/taxonomy.yml和文档中的实际锚点自动重建 docs 线性 README 的折叠细粒度目录块。脚本从 taxonomy 获取每个文档的main_anchors扫描文档中a id...锚点只收集主锚点及其子前缀锚点提取锚点后紧跟的标题行渲染为层级目录最后原地替换details块内容。当修改了 docs README 的章节锚点后必须先运行make sync-doc-toc再运行make test否则check-doc-structure会因目录未同步而报错。执行流程与开发者工作流推荐的完整提交前检查序列格式校验make lint— 确保 Markdown 格式合规目录同步仅当修改了 docs README 时make sync-doc-toc— 重建细粒度目录全量门禁make test— 执行全部 7 项本地检查差异审查git diff— 确认无临时文件或敏感信息混入推送并观察git push origin develop— 观察 GitHub Actions 结果错误诊断速查错误前缀含义典型修复MISSING_LINKS仓库内引用的文件不存在检查路径拼写或补全缺失文件MISSING_ANCHORS锚点在目标文件中不存在检查锚点拼写或目标文件标题是否变更MARKDOWN_DETAILS_ERRORSdetails/summary结构异常补充缺失的关闭标签或summaryDOC_STRUCTURE_ERRORSdocs README 结构违反契约调整标准块顺序、补充缺失锚点、运行sync-doc-tocDIRECTORY_DOC_ERRORS目录缺少必需的 README/AGENTS在对应目录下创建缺失文件METADATA_ERRORStaxonomy/redirects 中引用失效修正 metadata YAML 中的路径或锚点AI_CITATION_ERRORSAI 入口文件引用路径漂移更新llms.txt或 AI 引用语料中的路径扩展阅读深入了解 CI 流水线的完整配置参见 CI Quality Gate System了解 docs README 的结构契约细节参见docs/目录下的 AGENTS.md了解开发流程中门禁所处的位置参见 Workflow And Development Process了解 AI 代码质量门禁的应用场景参见 AI Code Quality Gates返回五层框架总览参见 Architecture Overview下一章问题解决框架
深入解析：质量门禁
质量门禁质量门禁是本项目交付闭环的最后一道防线。它由本地门禁make test和CI 门禁GitHub Actions两层构成共 8 项自动化检查确保每一次提交都满足文档结构、链接完整性、元数据一致性和 AI 引用准确性四类约束。对于高级开发者而言理解门禁的分层架构和每项检查的内部逻辑是高效通过 CI 并在本地快速定位问题的前提。架构总览质量门禁采用本地优先、CI 兜底的双层策略。开发者在提交前通过make test在本地执行全部 7 项同步检查推送后 GitHub Actions 在markdown-lintjob 中复现同样的 7 项检查并在link-checkerjob 中补充外部链接验证。两层共享同一套脚本和配置消除了“本地通过但 CI 失败”的环境差异问题。门禁检查项详解1. Markdown 格式检查make lint由npx --yes markdownlint-cli0.48.0执行固定版本号以避免跨环境行为差异。规则配置集中管理于.github/lint_config.jsonCI 和本地共享同一份配置文件。当前配置采用白名单策略——default: true启用所有规则随后逐项禁用不适用的规则如 MD001/MD013/MD025 等保留项目实际需要的子集。检查范围覆盖全仓库**/*.md但排除.history和tools/external目录。lint 规则的增删必须同时修改.github/lint_config.json因为Makefile和 CI 都引用该文件。不要在命令行通过--rule参数覆盖否则会导致本地/CI 行为不一致。2. 本地链接与锚点检查check-links脚本 check-local-links.py 遍历仓库内所有 Markdown 文件提取两种模式的链接标准 Markdown 链接和 HTML 属性href.../src...。对于每个非外部链接执行两项验证文件存在性解析目标路径确认文件在仓库内存在锚点存在性如果目标包含#fragment提取目标文件的全部锚点集合包括a id...手动锚点和通过github_slug()算法从标题自动生成的锚点确认 fragment 在集合中脚本内置了代码围栏感知strip_fenced_code避免误报代码块内的链接。跳过目录包括.git、.history、node_modules、.github/wiki、tools/external和tools/chat-vault。3. 折叠块结构检查check-details脚本 check-markdown-details.py 验证所有details块的结构完整性执行三项检查每个details必须有对应的/details关闭标签每个details块内必须包含summary标签每个summary标签内容必须包含“点击展开/收起”提示文字同一details块内不允许重复的summary标签错误输出格式为MARKDOWN_DETAILS_ERRORS附带文件路径和行号。4. 文档结构检查check-doc-structure脚本 check-doc-structure.py 是最复杂的门禁项它通过scripts/lib/taxonomy.py读取metadata/taxonomy.yml中定义的文档分类体系对docs/下的线性 README 执行多层约束验证。核心检查包括四个维度标准块顺序验证每个 docs README 必须按固定顺序包含五个标准块——顶部标题块、## 字多不看、## 快速导航、完整细粒度目录details折叠块、## 使用方式。H1 标题和## 字多不看之间禁止插入任何内容。同时检查是否包含禁止标题如“和其他目录的边界”、“维护规则”。主锚点顺序验证从 taxonomy 获取每个文档的expected_anchors验证这些锚点在 README 中的出现顺序与 taxonomy 定义一致且全部存在。目录覆盖验证提取顶部导航和折叠细粒度目录中的所有#anchor链接确认所有主锚点和以主锚点为前缀的手动锚点都在目录中有对应条目。重复锚点检测对全仓库所有 Markdown 文件排除 skip 列表进行a id...重复锚点扫描确保每个手动锚点全局唯一。5. 目录文档覆盖检查check-directory-docs脚本 check-directory-docs.py 维护一个硬编码的REQUIRED_DIRS列表约 35 个目录验证每个目录都包含必需的文档文件。默认要求同时存在README.md和AGENTS.md.github/目录例外仅要求AGENTS.md避免 GitHub 首页误展示平台配置说明。脚本还会自动发现仓库中未被REQUIRED_DIRS列表覆盖的新目录排除 symlink、vendor subtree 和生成目录确保新目录不会遗漏文档。6. 元数据路径与锚点检查check-metadata脚本 check-metadata.py 验证metadata/taxonomy.yml和metadata/redirects.yml中所有引用的本地路径和锚点是否有效。对于taxonomy.yml解析path:、entry:、agent_guide:字段值以及-列表项中的路径引用对于redirects.yml额外执行三项专项检查重定向源路径是否仍然存在于仓库中存在则说明迁移未完成重定向源是否映射到自身no-op redirect重定向源是否重复定义当 taxonomy 或 redirects 发生修改时先运行make check-metadata验证路径有效性再运行完整make test。元数据错误通常表现为“missing metadata target”或“missing metadata anchor”。7. AI 引用语料检查check-ai-citation脚本 check-ai-citation.py 覆盖两个 AI 入口文件llms.txt和assets/ai-citation/llms-full.txt以及assets/ai-citation/*.md目录下的所有 Markdown 文件。验证机制与check-local-links.py类似但使用更宽泛的PATH_PATTERN正则以捕获非链接格式的路径引用如纯文本中的docs/concepts/README.md。额外验证llms-full.txt是否覆盖了 taxonomy 中定义的所有文档路径确保 AI 完整上下文入口的完整性。8. 外部链接检查CI link-checker在 CI 层ci.yml 中的link-checkerjob 使用lycheeverse/lychee-actionv2.8.0检查仓库内所有 Markdown 文件中的外部链接有效性。此检查仅在 CI 中运行不在make test中包含因为它需要网络访问且耗时较长。配置文件为.lychee.toml。检查项全览| |:--|:------|:---------|:-----|:--------|:--------|| 1 | Markdown 格式 |make lint|npx markdownlint-cli|.history,tools/external| markdownlint 原生输出 || 2 | 本地链接/锚点 |make check-links|check-local-links.py|.git,.history,node_modules,.github/wiki,tools/external,tools/chat-vault|MISSING_LINKS,MISSING_ANCHORS|| 3 | 折叠块结构 |make check-details|check-markdown-details.py|.git,.history,node_modules,.github/wiki,tools/external|MARKDOWN_DETAILS_ERRORS|| 4 | 文档结构 |make check-doc-structure|check-doc-structure.py|.git,.history,node_modules,.github/wiki,tools/external|DOC_STRUCTURE_ERRORS|| 5 | 目录文档覆盖 |make check-directory-docs|check-directory-docs.py| symlink, vendor subtree |DIRECTORY_DOC_ERRORS|| 6 | 元数据路径 |make check-metadata|check-metadata.py| 无 |METADATA_ERRORS|| 7 | AI 引用路径 |make check-ai-citation|check-ai-citation.py| 无 |AI_CITATION_ERRORS|| 8 | 外部链接 | CI only | lychee-action | 由.lychee.toml控制 | lychee 原生输出 |CI 触发与流水线GitHub Actions 工作流定义于 .github/workflows/ci.yml在以下三种条件下触发push到develop或master分支pull_request目标为develop或master分支手动workflow_dispatch触发流水线包含两个并行 jobmarkdown-lint7 项同步检查和link-checker外部链接。两个 job 都使用actions/checkoutv6并启用submodules: recursive确保外部 submodule 中的文件也被纳入检查范围。辅助工具sync-doc-tocmake sync-doc-toc执行 sync-doc-toc.py根据metadata/taxonomy.yml和文档中的实际锚点自动重建 docs 线性 README 的折叠细粒度目录块。脚本从 taxonomy 获取每个文档的main_anchors扫描文档中a id...锚点只收集主锚点及其子前缀锚点提取锚点后紧跟的标题行渲染为层级目录最后原地替换details块内容。当修改了 docs README 的章节锚点后必须先运行make sync-doc-toc再运行make test否则check-doc-structure会因目录未同步而报错。执行流程与开发者工作流推荐的完整提交前检查序列格式校验make lint— 确保 Markdown 格式合规目录同步仅当修改了 docs README 时make sync-doc-toc— 重建细粒度目录全量门禁make test— 执行全部 7 项本地检查差异审查git diff— 确认无临时文件或敏感信息混入推送并观察git push origin develop— 观察 GitHub Actions 结果错误诊断速查错误前缀含义典型修复MISSING_LINKS仓库内引用的文件不存在检查路径拼写或补全缺失文件MISSING_ANCHORS锚点在目标文件中不存在检查锚点拼写或目标文件标题是否变更MARKDOWN_DETAILS_ERRORSdetails/summary结构异常补充缺失的关闭标签或summaryDOC_STRUCTURE_ERRORSdocs README 结构违反契约调整标准块顺序、补充缺失锚点、运行sync-doc-tocDIRECTORY_DOC_ERRORS目录缺少必需的 README/AGENTS在对应目录下创建缺失文件METADATA_ERRORStaxonomy/redirects 中引用失效修正 metadata YAML 中的路径或锚点AI_CITATION_ERRORSAI 入口文件引用路径漂移更新llms.txt或 AI 引用语料中的路径扩展阅读深入了解 CI 流水线的完整配置参见 CI Quality Gate System了解 docs README 的结构契约细节参见docs/目录下的 AGENTS.md了解开发流程中门禁所处的位置参见 Workflow And Development Process了解 AI 代码质量门禁的应用场景参见 AI Code Quality Gates返回五层框架总览参见 Architecture Overview下一章问题解决框架
