ulthon/ulthon_admin
1
0
Fork 0
mirror of https://gitee.com/ulthon/ulthon_admin.git synced 2026-07-01 15:32:48 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
4d05a739492a1e65bf47092d8e80b9cff6f2d110
ulthon_admin/AGENTS.md
augushong f867c42a72 feat(rules): 新增零散规则管理机制 
- 新增 .agents/rules/ 目录，存放模块级/场景级独立规则文件
- 新增 ulthon-rules-manager 技能，指导规则的新增/索引/格式
- 新增 ulthon-timer-multi-node 规则文件（从 PROJECT.md 迁移）
- AGENTS.md 新增「零散规则」章节，含框架级规则索引表
- PROJECT.md 新增「规则索引」章节，含全量规则索引表
- 命名约定：ulthon- 前缀为框架内置，project- 前缀为使用者业务
2026-06-01 21:26:16 +08:00

159 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 智能体协作规范（Ulthon Admin）
- `AGENTS.md`（本文件）：协作规则入口与导航
- `.agents/`：工作流（skills）与补充文档（含项目业务总览：`.agents/PROJECT.md`）
- `.agents/PROJECT.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`
- 主工程之外的配套内容统一放在 `source/`：包括多端代码、子项目工程（可为 PHP 或其他技术栈）、项目资料、附件与部署配套文件；不影响当前主工程运行与发布；目录约定与安全要求见 `source/README.md`（禁止提交构建产物、依赖目录等）
- `source/` 下各子目录（客户端、大屏端、各类子项目等）：若目录下存在 `AGENTS.md`，则该子工程规则以该文件为准
- 部署栈模式：`source/stack/` 为模式文件统一目录（含 `default/` 与各模式目录）；`default/` 必须与代码库默认行为一致；默认行为相关文件变更时需同步更新 `source/stack/default/` 对应文件
- 命令执行环境：执行 `php think` 命令前，需判断当前运行模式（Docker 模式下宿主机可能没有 PHP，不能依赖 `php think` 来检测）。判断方式：检查仓库根目录是否存在 `docker-compose.yaml` — 存在则为 Docker 模式；也可读取 `source/stack/stack.json` 了解所有可用模式及其说明。Docker 模式下所有 `php think` 命令前缀改为 `docker compose exec ulthon_admin`（如 `docker compose exec ulthon_admin php think tools:http:call`）；非 Docker 模式直接在宿主机执行
- 零散规则：特定模块/场景的约束存放在 `.agents/rules/`（详见「零散规则」章节），新增/维护规则见技能：[ulthon-rules-manager](./.agents/skills/ulthon-rules-manager/SKILL.md)
- 权限：基于 `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/PROJECT.md](./.agents/PROJECT.md)。
维护约束（必须遵守）：
- 智能体以“框架作者”身份开发时，如需新增/调整规则，必须先与开发者确认是否记录、记录位置与具体写法，并按确认结果落到对应规则文件。
- 智能体以“使用框架的开发者”身份执行任务时，如发现需要记录或调整的项目约束，应更新到对应规则文件（业务侧约束优先记录到 `.agents/PROJECT.md` 的「增量规则记录」章节），并可按开发者要求随时调整。
## 零散规则
针对特定模块/场景的约束，不适合在全局展开，存放在 `.agents/rules/` 目录下，每条规则一个独立文件。
- 命名约定：`ulthon-` 前缀为框架内置规则，`project-` 前缀为使用者业务规则
- 管理技能：[ulthon-rules-manager](./.agents/skills/ulthon-rules-manager/SKILL.md)
### 框架内置规则索引
| 规则文件 | 作用域 | 说明 |
|---------|--------|------|
| [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)
- 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/ # 主工程外内容统一目录（多端代码/资料/附件/各类子项目）
│ └── 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` |
Reference in New Issue View Git Blame Copy Permalink