ulthon_admin/AGENTS.md

智能体协作规范（Ulthon Admin）

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

项目信息

---

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

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

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

其他框架规则

• 技术栈：ThinkPHP 8.x / PHP 8.1+ / MySQL 5.7+ / Layui 2.x；代码风格遵循根目录 .php-cs-fixer.php
• 命名规范（必读）：ulthon-naming-convention.md
• 表结构设计（必读）：ulthon-scheme-definition；表结构优先 Scheme（app/admin/scheme/），避免 ENUM；tools:db 仅用于调试，不用于设计表结构
• 前端：视图与脚本同名配对（*.html + 同名 *.js），按模块维护 _common.js
• 权限：基于 auth 注解动态扫描节点与鉴权，以角色为中心管理（CLI 见 ulthon-permission-cli）
• 临时文件统一输出到 runtime/agents/（可按任务再分子目录），不放仓库根目录
• 调试与验证优先框架内置命令行工具（见下方快速命令），不借助外部数据库 MCP 或临时脚本
• 项目运行方式未在上方说明时，执行命令前先按 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

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

规则文件	说明
ulthon-naming-convention.md	目录与 PHP 文件命名约定
ulthon-controller-url.md	URL 与控制器/方法映射
ulthon-controller-response-throw.md	success/error/result/redirect 是 throw 不是 return
ulthon-deploy-environment.md	部署栈模式与运行环境判断
ulthon-source-directory.md	source/ 目录约定与安全要求
ulthon-file-override-mechanism.md	app/ 覆盖 extend/base/ 的三类文件
ulthon-system-config.md	sysconfig 的存储/读取/扩展
ulthon-init-data-migration.md	初始化数据变更必须同提交配套数据型 migration

标准开发流程（Scheme + CURD）

步骤	对应技能
1. 初始化环境（依赖、.env、数据库、php think 可用）	-
2. 设计表结构（app/admin/scheme/）	ulthon-scheme-definition
3. 同步 Scheme 与 DB（scheme:sync / scheme:make，生成前必须一致）	ulthon-scheme-curd-workflow
4. 生成 CURD（curd -t {table}，字段变更可 -r 安全重生成）	ulthon-scheme-curd-workflow
5. 业务定制（仅改 app/）	ulthon-admin-table、ulthon-page-api-dual-mode
6. 功能验证	ulthon-tools-http-call
7. 功能配套（菜单/权限/角色）	ulthon-admin-menu-cli、ulthon-permission-cli
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