AGENTS

本文件定义当前仓库给 AI Agent 的补充约定。

文档系统背景

• agilelabs.mkdocs 是 AgileLabs Framework 的文档系统，但不只是框架本体说明。
• 文档系统的发布与管理方式以根 README.md 中的 mkdocs-net 链接为准；本仓库不维护 GitHub MkDocs 配置。
• 这里同时覆盖框架使用规则、前端规范、前后端交互契约、时间与时区、命名规范、Json 序列化与数据转换、前后端目录架构、数据访问与数据库相关约定，以及 CI/CD 参考。
• 文档里还包含 API 错误码与统一错误处理、EnvelopMessage 封包、IApiExceptionProcessor 异常映射、AutoMapper 注册与映射处理、ClientApp 托管、多前端目录与产物同步等关键工程约定。
• 这套文档的主结构按以下六类理解，不把规范自查、真实用例、包说明、测试或专题补充材料当成独立一级内容结构：
  • 规范：正式规则、默认契约、跨层约定和合规要求的主入口。这里包括前端规范、前后端交互契约、API 错误码处理与统一错误链、时间与时区规范、命名规范、Json/数据转换规范、前后端目录架构规范、数据访问与数据库相关规范，以及 CI 配置参考的边界说明。framework-standards/checks/ 中的内容属于规范的配套自查文档，用于各项目核对是否符合规范。
  • 专题概念：按能力主题解释原理、边界、扩展方式和常见坑的主入口。这里包括 WebAPI、EnvelopMessage、AutoMapper、前端托管、时间与时区、数据访问等主题，也会覆盖 Profile 扫描注册、resolver 扩展、map 处理、统一封包与错误码映射等专题机制。
  • 解决方案：Solution/ 目录对应的可复用方案文档，重点沉淀已经落地、可复查、带适用边界的项目方案，例如认证与授权。
  • 教程：按连续上手路径组织的从零搭建文档，包含前端初始化、后端初始化和配套样例路径。
  • 任务：按“我要做什么”组织的落地入口，例如创建服务、做 WebAPI、托管前端、处理时间、多前端托管等。
  • 参考资料：低频但必要的资料入口，包括包说明、测试、Drone CI/CD、项目案例、数据访问迁移、工具和发布资料。
• 某些模块会附带示例、案例或落地页，但不要把“真实用例”理解成独立一级结构；优先先判断问题属于哪一类内容，再进入对应目录。

检索指引

• 需要正式规则与自查口径，优先进入“规范”。
• 需要理解原理、概念、扩展方式或常见坑，进入“专题概念”。
• 需要查可复用、带边界的项目落地做法，进入“解决方案”。
• 需要从零搭建或按连续路径落地，进入“教程”。
• 需要按当前目标快速找执行入口，进入“任务”。
• 需要查低频资料、包、测试、CI/CD 或工具说明，进入“参考资料”。

文档校验约定

• mkdocs 在这个仓库里是项目名称，不应默认当成需要执行的 CLI 命令。
• 日常文档修改不需要执行 mkdocs、站点构建命令或任何 Python 校验；发布与管理口径参考根 README.md 中的 mkdocs-net 链接。
• 不要把 python3 scripts/check_docs.py、python3 scripts/build_docs.py 或 mkdocs build 当成默认验证步骤。
• 文档改动的默认校验目标是 Markdown 文档本身是否正确，包括：
  • 页面结构是否完整。
  • 标题层级是否正确。
  • 站内相对 .md 链接是否有效。
  • 导航、兼容入口和文档格式是否一致。
• 默认按人工审查口径检查文档内容与链接，不要求本地执行 Python 脚本。

样例代码约定

• /mnt/d 下可以作为样例代码来源目录，需要示例时可优先到这里查找。
• 从 /mnt/d 获取并引用的任何代码、配置或片段，都必须先做脱敏再使用。
• 脱敏范围至少包括：密钥、口令、令牌、域名、IP、邮箱、手机号、用户名、公司名、项目名以及其他可识别真实来源的信息。