agilelabs-fx-docs main README.md

AgileLabs Framework 文档系统

agilelabs.mkdocs 是 AgileLabs Framework 的统一文档仓库，同时服务于 /agilelabs 与 /agilelabs.aspnet。这套文档既面向开发者阅读，也面向 AI Agent 检索、补充和维护，最终发布到 MkDocs 站点。

发布地址

先从哪里开始

  1. 第一次进入站点，先看 开始。
  2. 想按完整主线从零搭建，进入 教程。
  3. 想先看教程配套代码长什么样，进入 教程配套代码总览。
  4. 现在手头有明确任务，直接进 任务入口。
  5. 需要确认正式规则、边界和默认契约，进入 框架规范。
  6. 需要做审查、核对项目是否符合规范，进入 检查。
  7. 需要理解主题原理和扩展方式，进入 主题手册。
  8. 想看真实项目怎么落地，进入 真实用例。
  9. 需要查包、测试、升级与工具，进入 参考资料。

文档结构

适用对象

  • 维护 AgileLabs Framework 的开发者。
  • 在 /agilelabs 与 /agilelabs.aspnet 中开发、排障、扩展功能的工程师。
  • 需要稳定检索文档并继续维护文档体系的 AI Agent。

设计原则

  • 左侧导航优先按任务组织，减少首次查找成本。
  • 需要连续上手路径的内容单独收敛到 tutorials/，避免散落在旧教程和任务页之间。
  • 正式规则统一收敛到 框架规范/，避免同一规则散落在多个目录。
  • 检查入口独立放在 checks/，让审查和阅读规则各走一条清晰路径。
  • 高频主题收敛到单页聚合，避免同一主题分散在多个目录。
  • 案例从任务页和主题页就近进入，同时保留案例总览。
  • 低频内容统一收纳到参考区，避免主导航过长。
  • 教程配套代码统一收敛到 samples/tutorials/，并在教程正文显式链接。
  • 站点导航以 mkdocs.yml 为唯一可执行来源。

兼容入口

旧目录仍保留作为兼容路径，例如 guides/、standards/、cases/、fundamentals/、features/、tutorial/。新的主阅读路径以上面的主入口为准。

维护与校验

  • 导航与发布结构以 mkdocs.yml 为准。
  • 人工可读导航索引保留在 navmenu.md。
  • 第一次在本地构建站点前先执行 pip install -r requirements.txt。
  • 提交前运行 python3 scripts/check_docs.py，检查 H1、相对链接、兼容页长度和主模板段落。
  • 需要校验站点渲染时，再执行 python3 scripts/build_docs.py。该脚本会生成临时包装配置，在保留当前仓库结构的前提下调用 mkdocs build --strict。

相关页面