ulthon_admin/AGENTS.md

智能体协作规范（Ulthon Admin）

• AGENTS.md（本文件）：协作规则入口与导航
• .agents/：工作流（skills）与补充文档（含业务侧规则：.agents/AGENTS.md）
• 标准开发流程：见「标准开发流程」表格，操作细节见对应技能文件

项目级规则（最高优先级 / 唯一权威）

与其他文档、聊天内容、或智能体建议冲突时，一律以本节为准。 除非明确要求，按照框架使用者的规则进行开发。

通用基础规范（所有开发者必须遵守）

• 技术栈：ThinkPHP 8.x；PHP 8+；MySQL 8+；Layui 2.x；模板引擎：ThinkPHP 内置模板引擎
• 命名规范（必读）：https://doc.ulthon.com/read/augushong/ulthon_admin/64fbcf8830640/zh-cn/2.x.html
• 代码风格（必读，遵循 .php-cs-fixer.php）：https://doc.ulthon.com/read/augushong/ulthon_admin/64360c249d66a/zh-cn/2.x.html
• 表结构设计规范（必读）：https://doc.ulthon.com/read/augushong/ulthon_admin/619efc9d7af62/zh-cn/2.x.html
• 项目文档主页：https://doc.ulthon.com/read/augushong/ulthon_admin/home/zh-cn/2.x.html

代码分层铁律（不可协商）

框架采用 Base/App 双层架构。根据当前任务的开发者身份，遵守对应约束：

所有身份通用：

• extend/base/ 是框架内核（*Base），app/ 是业务代码入口，目录路径一一对应

框架使用者（默认身份，除非明确说"修内核/改框架"）：

• 严禁修改 extend/base/ 下任何文件
• 所有开发只在 app/ 目录进行；新写业务能力直接在 app/ 下实现即可
• 扩展内置能力时，只改 app/ 下对应入口类（必要时 extends 对应 *Base），保持方法签名一致

框架作者（仅当任务涉及 extend/base/ 时）：

• 每新增一个 Base 类，必须同时在 app/ 提供入口类（可为空类继承 Base）
• Base 内部禁止直接引用/调用 extend/base/ 下的类（含内部互调），必须引用 app/ 下的入口类
• 例外：app/common.php 引用 extend/base/helper.php 是全局辅助函数的唯一特许
• 核心层维护原则：稳定性优先（保证向下兼容）；通用性优先（不引入具体业务逻辑）

详细架构说明与操作流程：ulthon-base-app-architecture

其他规则

• 数据库：表结构优先 Scheme（app/admin/scheme/）；避免 ENUM；tools:db 用于调试，不用于“设计表结构”
• 前端：视图与脚本同名配对（*.html + 同名 *.js），并按模块维护 _common.js
• 配套资源与多端代码：统一放在 source/；不影响现有 PHP/ThinkPHP 主工程运行与发布；目录约定与安全要求见 source/README.md（禁止提交构建产物、依赖目录等）
• 部署栈模式：source/stack/ 为模式文件统一目录（含 default/ 与各模式目录）；default/ 必须与代码库默认行为一致；默认行为相关文件变更时需同步更新 source/stack/default/ 对应文件
• 命令执行环境：执行 php think 命令前，通过 php think admin:stack:mode current 检测当前模式；若为 docker-dev，所有 php think 命令前缀改为 docker compose exec ulthon_admin（如 docker compose exec ulthon_admin php think tools:http:call）；其他模式（default/full/base-build）直接在宿主机执行 php think，不做转换
• 权限：基于 auth 注解生成节点与鉴权；以角色为中心管理（角色、角色权限、用户角色）；命令行使用见技能：ulthon-permission-cli
• 临时文件：智能体在任务中产生的临时文件（脚本、日志、缓存、产物等）统一输出到 runtime/agents/（可按智能体/任务再分子目录），不要放在仓库根目录；除非任务明确要求或框架约定位置属于根目录
• 调试与验证：优先使用框架内置命令行工具（tools:http:call、tools:db:、tools:log:、admin:menu:、admin:permission:），不需要借助外部数据库 MCP 或临时脚本

标准开发流程（Scheme + CURD，默认必须执行）

完整操作细节见对应技能文件，本节仅列出流程骨架与核心约束。

步骤	说明	对应技能
1. 初始化环境	依赖安装、.env 配置、数据库初始化、确保 php think 可用	-
2. 设计表结构	在 app/admin/scheme/ 中编写 Scheme 类；遵循表结构设计规范	ulthon-scheme-definition
3. 同步 Scheme 与 DB	scheme:sync（以代码为准）或 scheme:make（以 DB 为准）；CURD 生成前两者必须一致	ulthon-scheme-curd-workflow
4. 生成 CURD 代码	curd -t {table}；后续字段变更可安全重新生成（-r 临时目录对比合并，不覆盖已改造的业务代码）	ulthon-scheme-curd-workflow
5. 业务定制	仅改 app/；逐页调整按钮/字段/表单/交互；接口需求用页面接口同体机制	ulthon-page-api-dual-mode
6. 功能验证	tools:http:call 模拟请求跑通增删改查；tools:log:* 排查异常	ulthon-tools-http-call
7. 功能配套	菜单（admin:menu:*）、权限节点（admin:permission:nodes）、角色分配	ulthon-admin-menu-cli、ulthon-permission-cli
8. 最终检查	页面路径可用、命令行验证通过、代码规范自查	-

规则维护机制（框架基础 / 使用者补充）

本仓库的规则分两类：

• 框架基础规则（稳定）：根目录 AGENTS.md（本文件）中的「项目级规则」为唯一权威；默认不随任务动态增长。
• 使用者补充规则（业务侧）：开发中用户/开发者补充的“项目规则/团队偏好/临时约束”，统一记录到 .agents/AGENTS.md。

维护约束（必须遵守）：

• 智能体以“框架作者”身份开发时，如需新增/调整规则，必须先与开发者确认是否记录、记录位置与具体写法，并按确认结果落到对应规则文件。
• 智能体以“使用框架的开发者”身份执行任务时，如发现需要记录或调整的项目约束，应更新到对应规则文件（业务侧约束优先记录到 .agents/AGENTS.md），并可按开发者要求随时调整。

工作流（Skills）

Skills 是“按场景调用的工作流说明”，统一以 .agents/skills/*/SKILL.md 为准。

• Base/App 架构与扩展指南（含身份分章节）：ulthon-base-app-architecture
• Scheme + CURD 工作流：ulthon-scheme-curd-workflow
• Scheme 定义指南：ulthon-scheme-definition
• 数据库调试命令（tools:db）：ulthon-db-tools-debug
• HTTP 调用工具（tools:http:call）：ulthon-tools-http-call
• 日志命令（tools:log）：ulthon-tools-log
• 内置定时器与定时任务扩展：ulthon-timer
• 页面 / 接口同体：ulthon-page-api-dual-mode
• 登录认证（Session + Token）：ulthon-auth-session-token
• 权限与角色管理（RBAC CLI）：ulthon-permission-cli
• 菜单管理（admin:menu:* CLI）：ulthon-admin-menu-cli
• ThinkPHP 控制器 URL 规则：tp-controller-url-rules

智能体指导

使用命令可以将内置智能体规则应用到各类智能体中。设计规则时以 AGENTS.md 和 .agents/ 目录为主。

php think tools:agent:publish

项目结构速览

ulthon_admin/
├── app/                    # 应用层（业务代码唯一入口）
│   ├── admin/              # 后台管理模块（控制器、模型、视图、Scheme）
│   ├── common/             # 公共代码（命令、服务、工具类）
│   └── tools/              # 工具控制器（定时任务等）
├── extend/
│   ├── base/               # 框架内核（*Base.php，禁止业务修改）
│   └── think/              # ThinkPHP 扩展（存储驱动、日志、迁移）
├── config/                 # ThinkPHP 配置
├── public/                 # Web 入口 + 静态资源
├── view/                   # 视图覆盖层
├── route/                  # 路由定义
├── database/               # 数据库迁移与种子
├── source/                 # 多端客户端代码（uni-app、Vue）
│   └── clients/uniapp/     # uni-app 前端工程
└── .agents/                 # 智能体技能与规则

快速命令参考

场景	命令
同步表结构（代码→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