# 智能体协作规范（Ulthon Admin） - `AGENTS.md`（本文件）：协作规则入口与导航 - `.agents/`：工作流（skills）与补充文档（含业务侧规则：`.agents/AGENTS.md`） - 开发规范与标准流程：已整合到本文件「项目级规则」中 ## 项目级规则（最高优先级 / 唯一权威） 与其他文档、聊天内容、或智能体建议冲突时，一律以本节为准。 除非明确要求，按照框架使用者的规则进行开发。 ### 通用基础规范（所有开发者必须遵守） - 技术栈：ThinkPHP 8.x；PHP 8+；MySQL 8+；Layui 2.x；模板引擎：ThinkPHP 内置模板引擎 - 命名规范（必读）： - 代码风格（必读，遵循 `.php-cs-fixer.php`）： - 表结构设计规范（必读）： - 项目文档主页： ### 代码分层铁律（不可协商） 框架采用 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](./.agents/skills/ulthon-base-app-architecture/SKILL.md) ### 其他规则 - 数据库：表结构优先 Scheme（`app/admin/scheme/`）；避免 ENUM；tools:db 用于调试，不用于“设计表结构” - 后端：代码优先使用CURD机制生成。 - 前端：视图与脚本同名配对（`*.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`，不做转换 - 接口：如果需要实现接口能力，需要利用框架的“页面接口同体机制”，框架支持直接所有“页面输出”改为“json输出”。 - 风格：遵循项目命名规范与 PSR；格式化以仓库根目录 `.php-cs-fixer.php` 配置为准（不假设本机已安装工具） - 权限：基于 `auth` 注解生成节点与鉴权；以角色为中心管理（角色、角色权限、用户角色）；命令行使用见技能：[ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md) - 临时文件：智能体在任务中产生的临时文件（脚本、日志、缓存、产物等）统一输出到 `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](./.agents/skills/ulthon-scheme-definition/SKILL.md) | | 3. 同步 Scheme 与 DB | `scheme:sync`（以代码为准）或 `scheme:make`（以 DB 为准）；**CURD 生成前两者必须一致** | [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-page-api-dual-mode](./.agents/skills/ulthon-page-api-dual-mode/SKILL.md) | | 6. 功能验证 | `tools:http:call` 模拟请求跑通增删改查；`tools:log:*` 排查异常 | [ulthon-tools-http-call](./.agents/skills/ulthon-tools-http-call/SKILL.md) | | 7. 功能配套 | 菜单（`admin:menu:*`）、权限节点（`admin:permission:nodes`）、角色分配 | [ulthon-admin-menu-cli](./.agents/skills/ulthon-admin-menu-cli/SKILL.md)、[ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md) | | 8. 最终检查 | 页面路径可用、命令行验证通过、代码规范自查 | - | ## 规则维护机制（框架基础 / 使用者补充） 本仓库的规则分两类： - **框架基础规则（稳定）**：根目录 `AGENTS.md`（本文件）中的「项目级规则」为唯一权威；默认不随任务动态增长。 - **使用者补充规则（业务侧）**：开发中用户/开发者补充的“项目规则/团队偏好/临时约束”，统一记录到 [.agents/AGENTS.md](./.agents/AGENTS.md)。 维护约束（必须遵守）： - 智能体以“框架作者”身份开发时，如需新增/调整规则，必须先与开发者确认是否记录、记录位置与具体写法，并按确认结果落到对应规则文件。 - 智能体以“使用框架的开发者”身份执行任务时，如发现需要记录或调整的项目约束，应更新到对应规则文件（业务侧约束优先记录到 `.agents/AGENTS.md`），并可按开发者要求随时调整。 ## 工作流（Skills） Skills 是“按场景调用的工作流说明”，统一以 `.agents/skills/*/SKILL.md` 为准；`.trae/skills/` 为 Trae 集成的镜像目录（内容保持同步）。 - Base/App 架构与扩展指南（含身份分章节）：[ulthon-base-app-architecture](./.agents/skills/ulthon-base-app-architecture/SKILL.md) - Scheme + CURD 工作流：[ulthon-scheme-curd-workflow](./.agents/skills/ulthon-scheme-curd-workflow/SKILL.md) - Scheme 定义指南：[ulthon-scheme-definition](./.agents/skills/ulthon-scheme-definition/SKILL.md) - 数据库调试命令（tools:db）：[ulthon-db-tools-debug](./.agents/skills/ulthon-db-tools-debug/SKILL.md) - HTTP 调用工具（tools:http:call）：[ulthon-tools-http-call](./.agents/skills/ulthon-tools-http-call/SKILL.md) - 日志命令（tools:log）：[ulthon-tools-log](./.agents/skills/ulthon-tools-log/SKILL.md) - 内置定时器与定时任务扩展：[ulthon-timer](./.agents/skills/ulthon-timer/SKILL.md) - 页面 / 接口同体：[ulthon-page-api-dual-mode](./.agents/skills/ulthon-page-api-dual-mode/SKILL.md) - 登录认证（Session + Token）：[ulthon-auth-session-token](./.agents/skills/ulthon-auth-session-token/SKILL.md) - 权限与角色管理（RBAC CLI）：[ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md) - 菜单管理（admin:menu:\* CLI）：[ulthon-admin-menu-cli](./.agents/skills/ulthon-admin-menu-cli/SKILL.md) - ThinkPHP 控制器 URL 规则：[tp-controller-url-rules](./.agents/skills/tp-controller-url-rules/SKILL.md) ## 智能体指导 使用命令可以将内置智能体规则应用到各类智能体中。设计规则时以 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` |