SunAdmin 开发文档

主题

🤖 AI Skill 与协作规则 ​

SunAdmin 在仓库内预留了一套面向 AI 工具的协作规则，用于让 AI 编程助手更快理解项目结构、编码风格和常见约定。

这套规则不是业务代码运行依赖，不会影响项目启动或部署；它的作用是为 AI 编程助手提供稳定的项目上下文。

目录结构 ​

项目内建议保留以下通用 AI 协作文件：

text
.ai/
├── PROJECT_RULES.md
├── BACKEND_RULES.md
├── ADMIN_FRONTEND_RULES.md
├── UNIAPP_RULES.md
└── DOCS_RULES.md

AGENTS.md

AGENTS.md 是通用 AI Agent 规则入口。公开结构只维护通用入口和 .ai/ 规则源，工具专用适配入口不作为通用结构跟踪；如需在本地适配特定工具，应只引导工具读取 AGENTS.md 或 .ai/。

文件用途 ​

文件用途
.ai/PROJECT_RULES.md项目总规则入口，描述项目定位、目录结构和通用工作原则。
.ai/BACKEND_RULES.mdLaravel 后端、模块、Dao、Request、路由、迁移等规则。
.ai/ADMIN_FRONTEND_RULES.md管理端 Vue 3、接口路径、分页、列表、组件等规则。
.ai/UNIAPP_RULES.mduni-app Vue 3、TypeScript、Pinia、路由、装修组件等规则。
.ai/DOCS_RULES.md文档写作、同步范围、接口规则变化后的文档维护要求。
AGENTS.md通用 AI Agent 规则入口，提示工具先读取 .ai/PROJECT_RULES.md，再按任务类型读取对应规则。

工作方式 ​

AI 工具入口文件只做“路标”，长期规则统一维护在 .ai/ 目录。

推荐读取顺序：

  1. 先阅读 .ai/PROJECT_RULES.md。
  2. 根据任务类型阅读对应规则文件。
  3. 修改代码时优先遵守当前项目的 canonical 接口、字段、路由和目录结构。
  4. 如果规则与当前代码不一致，先以当前代码为准，再按最小范围更新规则。

工具入口约定 ​

不同 AI 工具可能有自己的入口文件或规则目录。

公开项目的协作入口保持一致：

  • 通用入口看 AGENTS.md。
  • 长期规则看 .ai/。
  • 工具专用适配入口不作为通用结构跟踪。
  • 本地如需保留工具专用入口，只引用 .ai/ 或 AGENTS.md，不复制完整规则。
  • 新增或调整长期约定时，优先更新 .ai/ 目录中的规则文件。

维护建议 ​

  • 新增长期编码约定时，优先写入 .ai 对应规则文件。
  • 不要在多个工具入口里复制完整规则，避免后续维护时内容不一致。
  • 本地工具入口文件只保留简短说明和 .ai 文件索引。
  • 如果接口认证、分页参数、构建路径、模块规范发生变化，应同步更新 .ai 规则和相关文档。
  • 示例路径优先使用相对路径或项目内路径。

适合写入 AI 规则的内容 ​

  • 后端 Controller、Request、Dao、Model scope 的写法约定。
  • admin 与 uni-app 的接口参数、分页参数、路由规范。
  • 模块安装、菜单迁移、Seeder 的长期规则。
  • 异常响应、认证中间件、OpenGet/OpenPost、api.try-auth 等接口约定。
  • 常见联动修改范围，例如后端接口改动后同步 admin、uni-app 和文档。

不适合写入 AI 规则的内容 ​

  • 临时调试结论。
  • 单次问题的偶发修复细节。
  • 已废弃的旧接口兼容方案。
  • 与项目无关的工具使用偏好。
  • 不具备长期约束价值的个人习惯。