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

- `AGENTS.md`（本文件）：协作规则入口与导航
- `.agents/`：工作流（skills）、零散规则（rules）与补充文档
- `.agents/PROJECT.md`：项目业务总览（定位、核心模块、业务约束），由开发者按项目实际情况编写，智能体首次接触项目时应主动读取
- `.agents/rules/`：模块级/场景级零散规则，按文件独立存放（详见「零散规则」章节）
- `.agents/skills/`：按场景调用的工作流技能，统一以 `*/SKILL.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](./.agents/skills/ulthon-base-app-architecture/SKILL.md)

### 其他规则

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

## 零散规则

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

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

### 框架内置规则索引

| 规则文件 | 作用域 | 说明 |
|---------|--------|------|
| [ulthon-controller-url.md](./.agents/rules/ulthon-controller-url.md) | 控制器路由 | URL 与控制器/方法的映射规则 |
| [ulthon-deploy-environment.md](./.agents/rules/ulthon-deploy-environment.md) | 部署与命令执行 | 部署栈模式与 Docker/宿主机命令判断 |
| [ulthon-source-directory.md](./.agents/rules/ulthon-source-directory.md) | source/ 目录 | 子项目/多端代码的目录约定与安全要求 |
| [ulthon-timer-multi-node.md](./.agents/rules/ulthon-timer-multi-node.md) | 定时任务相关 | 多节点协调规则与设计 |

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

## 工作流（Skills）

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


- 技能命名约定：`ulthon-` 前缀为框架内置技能，`project-` 前缀为项目业务技能。新增业务技能时使用 `project-` 前缀。
- 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)

## 智能体指导

使用命令可以将内置智能体规则应用到各类智能体中。设计规则时以 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/                 # 主工程外内容统一目录（多端代码/资料/附件/各类子项目）
│   └── clients/uniapp/     # uni-app 前端工程
└── .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`                |