ulthon_admin/AGENTS.md

# 智能体协作规范（Ulthon Admin）

> 上方「项目信息」由本项目开发者维护，下方为框架规则。进入项目先看项目信息。

## 项目信息

<!-- 由开发者维护：写任何智能体必须先知道的项目特有信息，格式不限、按需增删，不限于建议项。
建议涵盖：
- 项目概述（做什么的、服务于谁）
- 运行与命令执行方式（命令在哪执行、怎么启动、有无非默认端口，按实际情况描述）
- 不可协商的业务铁律
- 自定义规则索引（.agents/rules/project-*.md 清单）
- 框架更新策略（默认对比更新，无需写） -->

---

## 代码分层铁律（Base/App 双层架构）

框架采用 Base/App 双层架构：`extend/base/` 是框架内核（`*Base` 类），`app/` 是业务代码入口，两者目录路径一一对应。

- 严禁修改 `extend/base/` 下任何文件，所有开发只在 `app/` 进行
- 扩展框架内置能力时只改 `app/` 下对应入口类（必要时 `extends` 对应 `*Base`，保持方法签名一致）
- `app/` 可文件级覆盖 `extend/base/` 的三类文件（见 [ulthon-file-override-mechanism.md](./.agents/rules/ulthon-file-override-mechanism.md)）
- 默认身份是框架使用者；仅当任务明确涉及 `extend/base/` 时切换为框架作者身份
- 完整规则、目录映射与项目结构总览：[ulthon-base-app-architecture](./.agents/skills/ulthon-base-app-architecture/SKILL.md)

## 其他框架规则

- 技术栈：ThinkPHP 8.x / PHP 8.1+ / MySQL 5.7+ / Layui 2.x；代码风格遵循根目录 `.php-cs-fixer.php`
- 命名规范（必读）：[ulthon-naming-convention.md](./.agents/rules/ulthon-naming-convention.md)
- 表结构设计（必读）：[ulthon-scheme-definition](./.agents/skills/ulthon-scheme-definition/SKILL.md)；表结构优先 Scheme（`app/admin/scheme/`），避免 ENUM；tools:db 仅用于调试，不用于设计表结构
- 前端：视图与脚本同名配对（`*.html` + 同名 `*.js`），按模块维护 `_common.js`
- 权限：基于 `auth` 注解动态扫描节点与鉴权，以角色为中心管理（CLI 见 [ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md)）
- 临时文件统一输出到 `runtime/agents/`（可按任务再分子目录），不放仓库根目录
- 调试与验证优先框架内置命令行工具（见下方快速命令），不借助外部数据库 MCP 或临时脚本
- 项目运行方式未在上方说明时，执行命令前先按 [ulthon-deploy-environment.md](./.agents/rules/ulthon-deploy-environment.md) 判断环境（如根目录有 Docker 编排文件则勿直接宿主机执行 `php think`）
- 在线文档：<https://doc.ulthon.com/read/augushong/ulthon_admin/home/zh-cn/2.x.html>

## 规则与技能

- `.agents/rules/`（零散规则）与 `.agents/skills/`（场景技能）按前缀区分维护者：`ulthon-` 为框架分发，`project-` 为本项目自建
- 涉及具体模块/场景前，先查对应目录是否有专属文件
- 新增零散规则的操作流程见 [ulthon-rules-manager](./.agents/skills/ulthon-rules-manager/SKILL.md)

框架规则速览（一行一条，完整内容见文件）：

| 规则文件 | 说明 |
|---------|------|
| [ulthon-naming-convention.md](./.agents/rules/ulthon-naming-convention.md) | 目录与 PHP 文件命名约定 |
| [ulthon-controller-url.md](./.agents/rules/ulthon-controller-url.md) | URL 与控制器/方法映射 |
| [ulthon-controller-response-throw.md](./.agents/rules/ulthon-controller-response-throw.md) | success/error/result/redirect 是 throw 不是 return |
| [ulthon-deploy-environment.md](./.agents/rules/ulthon-deploy-environment.md) | 部署栈模式与运行环境判断 |
| [ulthon-source-directory.md](./.agents/rules/ulthon-source-directory.md) | source/ 目录约定与安全要求 |
| [ulthon-file-override-mechanism.md](./.agents/rules/ulthon-file-override-mechanism.md) | app/ 覆盖 extend/base/ 的三类文件 |
| [ulthon-system-config.md](./.agents/rules/ulthon-system-config.md) | sysconfig 的存储/读取/扩展 |

## 标准开发流程（Scheme + CURD）

| 步骤 | 对应技能 |
|------|----------|
| 1. 初始化环境（依赖、`.env`、数据库、`php think` 可用） | - |
| 2. 设计表结构（`app/admin/scheme/`） | [ulthon-scheme-definition](./.agents/skills/ulthon-scheme-definition/SKILL.md) |
| 3. 同步 Scheme 与 DB（`scheme:sync` / `scheme:make`，生成前必须一致） | [ulthon-scheme-curd-workflow](./.agents/skills/ulthon-scheme-curd-workflow/SKILL.md) |
| 4. 生成 CURD（`curd -t {table}`，字段变更可 `-r` 安全重生成） | [ulthon-scheme-curd-workflow](./.agents/skills/ulthon-scheme-curd-workflow/SKILL.md) |
| 5. 业务定制（仅改 `app/`） | [ulthon-admin-table](./.agents/skills/ulthon-admin-table/SKILL.md)、[ulthon-page-api-dual-mode](./.agents/skills/ulthon-page-api-dual-mode/SKILL.md) |
| 6. 功能验证 | [ulthon-tools-http-call](./.agents/skills/ulthon-tools-http-call/SKILL.md) |
| 7. 功能配套（菜单/权限/角色） | [ulthon-admin-menu-cli](./.agents/skills/ulthon-admin-menu-cli/SKILL.md)、[ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md) |
| 8. 最终检查（页面可用、命令行验证、规范自查） | - |

## 快速命令

| 场景 | 命令 |
|------|------|
| 同步表结构（代码→DB） | `php think scheme:sync` |
| 生成 Scheme（DB→代码） | `php think scheme:make -t {table}` |
| CURD 代码生成 | `php think curd -t {table}` |
| 模拟 HTTP 请求 | `php think tools:http:call` |
| 查看日志 | `php think tools:log:show` |
| 数据库查询 | `php think tools:db:query "SELECT ..."` |
| 查看权限节点 | `php think admin:permission:nodes` |
| 菜单管理 | `php think admin:menu:*` |
| 框架更新 | `php think admin:update` |