ulthon_admin/AGENTS.md

智能体协作规范（Ulthon Admin）

• AGENTS.md（本文件）：协作规则入口与导航
• .agents/：工作流（skills）、零散规则（rules）与补充文档
• .agents/PROJECT.md：项目业务总览（项目概述 + 业务规则索引），由开发者按项目实际情况编写；本文件管"怎么用框架"，PROJECT.md 管"这个项目在做什么业务、怎么跑、怎么部署"
• .agents/rules/：模块级/场景级零散规则，按文件独立存放（详见「零散规则」章节）
• .agents/skills/：按场景调用的工作流技能，统一以 */SKILL.md 为准（详见「工作流」章节）
• 标准开发流程：见「标准开发流程」表格，操作细节见对应技能文件

规则导航

本项目规则分两层，智能体进入项目时应先了解全局：

• 框架规则（ulthon- 前缀）：本文件 + .agents/rules/ulthon-*，管"怎么用框架"
• 项目规则（project- 前缀）：.agents/PROJECT.md + .agents/rules/project-*，管"这个项目在做什么业务、怎么开发/运行/部署"

两层规则缺一不可。本文件提供框架通用约束，但具体项目的业务语境、实际采用的技术栈与部署模式，都以 PROJECT.md 及其索引的业务规则为准。涉及业务逻辑或环境操作前，应先查阅 PROJECT.md。

完整索引位置：

• 框架内置规则索引：见本文件「零散规则」章节
• 项目业务规则索引：见 .agents/PROJECT.md 的「规则索引」章节

涉及具体模块/场景前，先查阅对应索引，确认是否有专属规则。

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

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

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

• 技术栈：ThinkPHP 8.x；PHP 8.0+；MySQL 5.7+；Layui 2.x；模板引擎：ThinkPHP 内置模板引擎
• 命名规范（必读）：ulthon-naming-convention.md
• 代码风格（必读）：遵循项目根目录 .php-cs-fixer.php
• 表结构设计规范（必读）：ulthon-scheme-definition（含特殊字段约定、字段后缀、组件类型、关联表参数）
• 项目文档主页（在线）：https://doc.ulthon.com/read/augushong/ulthon_admin/home/zh-cn/2.x.html

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

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

默认身份是框架使用者：严禁修改 extend/base/ 下任何文件，所有开发只在 app/ 进行；扩展框架内置能力时只改 app/ 下对应入口类（必要时 extends 对应 *Base，保持方法签名一致）。

仅在任务明确涉及 extend/base/ 时切换为框架作者身份，需额外遵守依赖倒置（Base 内部调用走 app/ 入口类）、Base/App 同步提供、稳定性与通用性优先等约束。

完整规则、文件级覆盖机制、目录映射与常见误区：ulthon-base-app-architecture

其他规则

• 数据库：表结构优先 Scheme（app/admin/scheme/）；避免 ENUM；tools:db 用于调试，不用于"设计表结构"
• 前端：视图与脚本同名配对（*.html + 同名 *.js），并按模块维护 _common.js
• 权限：基于 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/rules/ulthon-* 为唯一权威；默认不随任务动态增长
• 使用者补充规则：.agents/PROJECT.md（项目概述 + 规则索引）+ .agents/rules/project-*（具体业务规则），由开发者维护
• 维护约束：框架作者新增/调整规则前须与开发者确认；使用者身份发现需记录的约束时，优先记录到对应位置
• 管理技能：ulthon-rules-manager

零散规则

模块级/场景级的专属知识（约束、约定、设计决策），不适合在全局展开，存放在 .agents/rules/ 目录下，每条规则一个独立文件。

• 命名约定：ulthon- 前缀为框架内置规则，project- 前缀为使用者业务规则

框架内置规则索引

规则文件	作用域	说明
ulthon-naming-convention.md	命名规范	目录命名与 PHP 文件命名约定
ulthon-controller-url.md	控制器路由	URL 与控制器/方法的映射规则
ulthon-controller-response-throw.md	控制器响应	success/error/result/redirect 是 throw 不是 return，try-catch 内调用的陷阱与正确范式
ulthon-deploy-environment.md	部署与命令执行	部署栈模式与 Docker/宿主机命令判断
ulthon-source-directory.md	source/ 目录	子项目/多端代码的目录约定与安全要求
ulthon-file-override-mechanism.md	文件加载机制	app/ 覆盖 extend/base/ 的三类文件级覆盖机制与反例
ulthon-system-config.md	系统配置（sysconfig）	后台可变配置的存储、读取、保存、视图扩展规范

使用者业务规则索引见 .agents/PROJECT.md 的「规则索引」章节。

工作流（Skills）

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

• 技能命名约定：ulthon- 前缀为框架内置技能，project- 前缀为项目业务技能。新增业务技能时使用 project- 前缀。
• Base/App 架构与扩展指南（含身份分章节）：ulthon-base-app-architecture
• Scheme + CURD 工作流：ulthon-scheme-curd-workflow
• Scheme 定义指南（含表结构规范：特殊字段、字段后缀、组件类型、关联表参数）：ulthon-scheme-definition
• 后台表格机制与定制（按钮/字段/搜索/页面分类 A/B/C/D）：ulthon-admin-table
• 数据库调试命令（tools:db）：ulthon-db-tools-debug
• HTTP 调用工具（tools:http:call）：ulthon-tools-http-call
• 内置定时器与定时任务扩展（含多节点协调、run_type 调度）：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
• 测试工作流（设计哲学/决策/约束/运行/编写/回归保护）：ulthon-testing
• 页面验证 AI 自测（零项目依赖，6 步 checklist）：ulthon-page-qa
• 框架更新工作流（admin:update 同步上游）：ulthon-update-workflow
• 零散规则管理（新增/维护 .agents/rules/）：ulthon-rules-manager

日志查看走通用命令 php think tools:log:show，详见 快速命令参考。

项目结构速览

ulthon_admin/
├── app/                    # 应用层（业务代码唯一入口）
│   ├── admin/              # 后台管理模块（控制器、模型、视图、Scheme）
│   ├── common/             # 公共代码（命令、服务、工具类）
│   └── tools/              # 工具控制器（定时任务等）
├── extend/
│   ├── base/               # 框架内核（*Base.php，禁止业务修改）
│   └── think/              # ThinkPHP 扩展（存储驱动、日志、迁移）
├── config/                 # ThinkPHP 配置
├── public/                 # Web 入口 + 静态资源
├── view/                   # 视图覆盖层
├── route/                  # 路由定义
├── database/               # 数据库迁移与种子
├── tests/                  # 测试目录
├── source/                 # 主工程外内容统一目录（多端代码/资料/附件/各类子项目）
│   ├── assets/             # 静态资源
│   ├── attachments/        # 附件
│   ├── clients/            # 客户端工程
│   │   └── uniapp/         # uni-app 前端工程
│   ├── docker/             # Docker 相关配置
│   ├── docs/               # 文档
│   ├── projects/           # 子项目
│   ├── stack/              # 部署栈
│   └── README.md           # source 目录说明
└── .agents/                 # 智能体协作资源
    ├── skills/              # 工作流技能（按场景调用）
    ├── rules/               # 零散规则（按模块/场景拆分）
    └── PROJECT.md           # 项目业务总览与规则索引

快速命令参考

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