feat: 发布智能体版

AGENTS.md

@@ -1,26 +1,198 @@
-## Agent 工作约束（Ulthon Admin）
+# 智能体协作规范（Ulthon Admin）
 
-本仓库的开发规范以两类信息为准：
+- `AGENTS.md`（本文件）：协作规则入口与导航
+- `.agent/`：工作流（skills）与补充文档（含业务侧规则：`.agent/AGENTS.md`）
+- 开发规范与标准流程：已整合到本文件「项目级规则」中
 
-1. **规则（必须始终遵守）**：见 [.trae/rules/project_rules.md](./.trae/rules/project_rules.md) 与 [CODERULE.md](./CODERULE.md)。
-2. **技能（按场景调用的工作流）**：见 `.trae/skills/*/SKILL.md`。
+## 项目级规则（最高优先级 / 唯一权威）
 
-在线文档（参考）：https://doc.ulthon.com/read/augushong/ulthon_admin/home/zh-cn/2.x.html
+与其他文档、聊天内容、或智能体建议冲突时，一律以本节为准。
+除非明确要求，按照框架使用者的规则进行开发。
 
-## 不应该做的事情
+### 通用基础规范（所有开发者必须遵守）
 
-1. 一般不需要直接修改开发环境（除非安装 composer 依赖或开发相关资源）。不要自行安装 Docker、MySQL、Redis 等基础环境，这些由开发者维护。
-2. 一般不需要修改环境配置文件（如 `.env`）。发现配置缺失或错误时，应提示开发者完善相关配置。
-3. 一般不需要自行启动或常驻运行项目程序（开发者会提前运行以便调试）；除非用户明确要求执行运行/调试命令。
+- 技术栈：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>
 
-## 框架内置能力速查
+### 代码分层（3 层）
 
-本段只保留入口与触发条件，细节以对应技能为准，包括但不限于以下内容：
+- ThinkPHP 层：框架本身；通过 Provider 机制可以替换/扩展 ThinkPHP 的行为（配置通常在 `app/provider.php`，例如绑定核心类实现、注册中间件等）
+- ulthon\_admin 层：框架内核与默认实现，主要位于 `extend/base/`（\*Base）与 `extend/think/`（对 ThinkPHP 行为的适配/替换）
+- App 层：业务代码与系统唯一调用入口，位于 `app/`（包含：用于覆盖框架默认实现的入口类；以及：业务自行新增的普通类）
 
-- 扩展内置能力（不改 base）：[ulthon-core-extend-pattern](./.trae/skills/ulthon-core-extend-pattern/SKILL.md)
-- Scheme + CURD 工作流：[ulthon-scheme-curd-workflow](./.trae/skills/ulthon-scheme-curd-workflow/SKILL.md)
-- 数据库调试命令（tools:db）：[ulthon-db-tools-debug](./.trae/skills/ulthon-db-tools-debug/SKILL.md)
-- 页面 / 接口同体（同一控制器 HTML+JSON）：[ulthon-page-api-dual-mode](./.trae/skills/ulthon-page-api-dual-mode/SKILL.md)
-- 登录认证（Session + Token）：[ulthon-auth-session-token](./.trae/skills/ulthon-auth-session-token/SKILL.md)
+### 身份与职责（2 种）
+
+一句话讲清楚：
+
+- 框架作者：代码写在 `extend/base/`，但系统调用入口必须在 `app/`（保证使用者可在 `app/` 继承重写）
+- 框架使用者：内置能力要改就改 `app/` 的对应入口类；自己新增的业务代码直接写 `app/`，不需要关心 Base/App 双层机制
+
+#### ulthon\_admin 框架作者（维护框架/内核）
+
+- 新增通用能力：实现写到 `extend/base/`（必要时通过 Provider 机制扩展 ThinkPHP 行为）
+- 同时在 `app/` 下建立对应入口类（可为空类继承 Base），作为系统唯一调用入口
+- Base 内部引用模型/服务/控制器时，一律引用 `app/` 下的类（保证业务层扩展始终生效）
+- 静态文件/模板/配置支持分层加载：优先加载 `app/`，不存在时再回落到框架默认实现（例如 `app_file_path`）
+- Base层代码一般以 `*Base.php` 命名，放在 `extend/base/` 下
+- Base层代码和app层代码的文件路径和名称一般是对应的。
+- 核心层维护原则：稳定性优先（保证向下兼容）；通用性优先（不引入具体业务逻辑）
+
+**Base 层文件分类**：
+
+- `*Base.php`：控制器/模型/服务/命令基类（被 App 层继承）
+- `helper.php`：全局辅助函数（通过 app/common.php 引用）
+- `adminInitData/`：框架核心初始化数据（带 @internal-framework 注解标记）
+- `adminUpdateCodeData/`：框架版本更新代码（带 @internal-framework 注解标记）
+
+#### 使用框架的开发者（做业务）
+
+- 严禁修改 `extend/base/` 下任何文件
+- 业务逻辑一般放在 `app/` 下（优先 `app/admin/`）
+- 修改/扩展框架内置能力：只改 `app/` 下对应入口类（必要时 `extends` 对应 `*Base`）；仍严禁直接改动 `extend/base/`
+- 新写业务能力：直接在 `app/` 下实现即可；不需要、也不应该在 `extend/base/` 新建任何 `*Base.php`
+- 公共代码放在 `app/common/`（工具类、基础类等）
+- 命令类特殊一些，放在 `app/common/command/`（不放在 `app/admin/command/`）
+- 重写规范：保持方法签名一致；可用 `parent::method()` 复用父类逻辑，或复制父类代码后自行实现
+- 其他无任何特殊要求，可以按照任意方式写代码，以上只是对base层作说明。但框架仍然规定了大量的开发规范，需要参考在线文档。
+- 尽量按框架的规范、内置规则、内置技能进行开发，避免违反框架的设计初衷。
+
+### Base/App 双层机制调用红线（内核开发约束）
+
+- `extend/base/` 为框架内核实现（`*Base`），仅作为 `app/` 的继承基类使用，不作为系统调用入口
+- 在实现通用能力/内核代码时，禁止直接引用或调用 `extend/base/` 下的类（包括 `extend/base/` 内部互相调用）
+- 模型/服务/控制器/命令的引用与调用必须指向 `app/` 下的对应入口类（保证覆盖/重写始终生效）
+- 例外：
+  1. 允许在 `app/` 下类定义中使用 `extends` 继承对应 `*Base` 类
+  2. `app/common.php` 中包含 `include App::getRootPath() . '/extend/base/helper.php';`，这是全局辅助函数文件的引用特例
+     - `extend/base/helper.php` 仅包含**全局辅助函数**（非类），属于框架内核能力的一部分
+     - 这些函数需要在整个应用范围内可用（如 `__url()`, `password()`, `sysconfig()`, `auth()`, `app_file_path()` 等）
+     - 该引用为框架设计要求的合理例外，不影响 Base/App 双层机制原则
+
+### Base/app 双层机制目录映射示例（常见）
+
+- `extend/base/admin/controller/system/AdminBase.php` → `app/admin/controller/system/Admin.php`
+- `extend/base/admin/model/SystemAdminBase.php` → `app/admin/model/SystemAdmin.php`
+- `extend/base/common/service/SmsBase.php` → `app/common/service/Sms.php`
+- `extend/base/common/command/admin/role/AdminRoleCreateBase.php` → `app/common/command/admin/role/AdminRoleCreate.php`
+
+### 其他规则
+
+- 数据库：表结构优先 Scheme（`app/admin/scheme/`）；避免 ENUM；tools:db 用于调试，不用于“设计表结构”
+- 后端：代码优先使用CURD机制生成。
+- 前端：视图与脚本同名配对（`*.html` + 同名 `*.js`），并按模块维护 `_common.js`
+- 配套资源与多端代码：统一放在 `source/`；不影响现有 PHP/ThinkPHP 主工程运行与发布；目录约定与安全要求见 `source/README.md`（禁止提交构建产物、依赖目录等）
+- 接口：如果需要实现接口能力，需要利用框架的“页面接口同体机制”，框架支持直接所有“页面输出”改为“json输出”。
+- 风格：遵循项目命名规范与 PSR；格式化以仓库根目录 `.php-cs-fixer.php` 配置为准（不假设本机已安装工具）
+- 权限：基于 `auth` 注解生成节点与鉴权；以角色为中心管理（角色、角色权限、用户角色）；命令行使用见技能：[ulthon-permission-cli](./.agent/skills/ulthon-permission-cli/SKILL.md)
+- 临时文件：智能体在任务中产生的临时文件（脚本、日志、缓存、产物等）统一输出到 `runtime/agent/`（可按智能体/任务再分子目录），不要放在仓库根目录；除非任务明确要求或框架约定位置属于根目录
+- 调试与验证：框架内置了完善的功能验证能力，可以通过命令行实现数据库操作、控制器的请求（页面接口同体机制）、模拟用户请求（直接获得用户登录状态）、日志管理、菜单管理、权限管理等等，具体查看命令说明和agents技能。你可以利用这些机制直接实现功能的测试和验证，无需借助各类数据库MCP、命令行脚本等方式。
+
+### 标准开发流程（Scheme + CURD，默认必须执行）
+
+1. 初始化开发环境（必须提前完成）
+   - 按项目文档完成：依赖安装、`.env` 配置、数据库连接与基础数据初始化、确保 `php think` 可用
+   - 需要命令行联调与验证时，确保本地 CLI 与服务端使用同一套环境配置（尤其是缓存与数据库）
+2. 设计/调整表结构（Scheme）
+   - 严格遵循表结构设计规范
+   - 优先通过 Scheme 机制在 `app/admin/scheme/` 代码化维护表结构（避免 ENUM）
+3. 同步并确保一致（Scheme <-> DB）
+   - 以代码为准（推荐）：`php think scheme:sync`
+   - 以数据库为准：`php think scheme:make -t {table}`
+   - 生成 CURD 前，Scheme 与数据库结构必须完全一致，否则会被拒绝
+   - 数据调试仅用于排错：`php think tools:db:*`（不要用来“设计表结构”）
+4. 生成基础代码（CURD），重要，只要是数据库表的功能开发，必须使用CURD机制生成代码。
+   - 推荐先生成到临时目录确认：`php think curd -t {table} -r`
+   - 确认无误后再正式生成/覆盖：`php think curd -t {table}` / `php think curd -t {table} -f`
+   - 一旦开始在生成代码上做业务改造，后续结构变更默认走“临时生成 + 按需合并”，避免 `-f` 覆盖丢失业务修改
+   - CURD 命令详解：<https://doc.ulthon.com/read/augushong/ulthon_admin/curd-command/zh-cn/2.x.html>
+5. 业务代码定制（仅改 `app/`）
+   - 在生成代码基础上进行修改，仅操作 `app/` 目录
+   - CURD 页面不仅包含列表表格页，还会生成若干配套页面/脚本；需要结合业务逐页检查与调整：按钮、字段展示、搜索项、表单校验、交互流程等
+   - 如涉及接口输出或客户端（uni-app / Vue 等）调用，优先使用“页面 / 接口同体机制”，并确保同一路由在 HTML 与 JSON 两种模式下都符合预期
+6. 用内置 tools 与 CLI 完成功能验证（把增删改查跑通）
+   - 用 `php think tools:http:call` 在命令行模拟已登录管理员请求，验证列表/详情/新增/编辑/删除链路与返回结构
+   - 必要时用 `php think tools:log:*` 定位异常、追踪请求链路与数据变化
+7. 完成功能配套（按需）
+   - 菜单管理：新增/调整菜单（`php think admin:menu:*`），并与页面路径/节点保持一致
+   - 权限管理：基于 `auth` 注解生成/核对节点（`php think admin:permission:nodes`），为角色分配节点并为用户分配角色（`php think admin:role:*` / `php think admin:user:role:*`）
+   - 数据库排错：必要时使用 `php think tools:db:*` 做只读检查或最小化变更
+8. 最终检查与交付（完成“新功能开发”的定义）
+   - 后台页面：列表/表单/详情/删除等核心路径可用，交互与权限符合预期
+   - 命令行验证：接口增删改查已通过 tools 命令跑通，关键异常可通过日志命令回溯
+   - 代码规范：按仓库根目录 `.php-cs-fixer.php` 约束自查，避免引入不符合规范的写法
+
+## 规则维护机制（框架基础 / 使用者补充）
+
+本仓库的规则分两类：
+
+- **框架基础规则（稳定）**：根目录 `AGENTS.md`（本文件）中的「项目级规则」为唯一权威；默认不随任务动态增长。
+- **使用者补充规则（业务侧）**：开发中用户/开发者补充的“项目规则/团队偏好/临时约束”，统一记录到 [.agent/AGENTS.md](./.agent/AGENTS.md)。
+
+维护约束（必须遵守）：
+
+- 智能体以“框架作者”身份开发时，如需新增/调整规则，必须先与开发者确认是否记录、记录位置与具体写法，并按确认结果落到对应规则文件。
+- 智能体以“使用框架的开发者”身份执行任务时，如发现需要记录或调整的项目约束，应更新到对应规则文件（业务侧约束优先记录到 `.agent/AGENTS.md`），并可按开发者要求随时调整。
+
+## 工作流（Skills）
+
+Skills 是“按场景调用的工作流说明”，统一以 `.agent/skills/*/SKILL.md` 为准；`.trae/skills/` 为 Trae 集成的镜像目录（内容保持同步）。
+
+- 扩展内置能力（继承与重写）：[ulthon-core-extend-pattern](./.agent/skills/ulthon-core-extend-pattern/SKILL.md)
+- Base/App 架构指南：[ulthon-base-app-architecture](./.agent/skills/ulthon-base-app-architecture/SKILL.md)
+- CLI 命令参考文档：[ulthon-cli-reference](./.agent/skills/ulthon-cli-reference/SKILL.md)
+- Scheme + CURD 工作流：[ulthon-scheme-curd-workflow](./.agent/skills/ulthon-scheme-curd-workflow/SKILL.md)
+- Scheme 定义指南：[ulthon-scheme-definition](./.agent/skills/ulthon-scheme-definition/SKILL.md)
+- 数据库调试命令（tools:db）：[ulthon-db-tools-debug](./.agent/skills/ulthon-db-tools-debug/SKILL.md)
+- HTTP 调用工具（tools:http:call）：[ulthon-tools-http-call](./.agent/skills/ulthon-tools-http-call/SKILL.md)
+- 日志命令（tools:log）：[ulthon-tools-log](./.agent/skills/ulthon-tools-log/SKILL.md)
+- 内置定时器与定时任务扩展：[ulthon-timer](./.agent/skills/ulthon-timer/SKILL.md)
+- 页面 / 接口同体：[ulthon-page-api-dual-mode](./.agent/skills/ulthon-page-api-dual-mode/SKILL.md)
+- 登录认证（Session + Token）：[ulthon-auth-session-token](./.agent/skills/ulthon-auth-session-token/SKILL.md)
+- 权限与角色管理（RBAC CLI）：[ulthon-permission-cli](./.agent/skills/ulthon-permission-cli/SKILL.md)
+- 菜单管理（admin:menu:\* CLI）：[ulthon-admin-menu-cli](./.agent/skills/ulthon-admin-menu-cli/SKILL.md)
+- ThinkPHP 控制器 URL 规则：[tp-controller-url-rules](./.agent/skills/tp-controller-url-rules/SKILL.md)
+
+## 智能体指导
+
+使用命令可以将内置智能体规则应用到各类智能体中。设计规则时以 AGENTS.md 和 `.agent/` 目录为主。
+
+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 前端工程
+└── .agent/                 # 智能体技能与规则
+```
+
+## 快速命令参考
+
+| 场景               | 命令                                      |
+| ---------------- | --------------------------------------- |
+| 同步表结构（代码→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`                |
 
-命令行通用参数：多数命令支持 `--force-force`（`-ff`）跳过交互确认。