diff --git a/AGENTS.md b/AGENTS.md index 5b183fb..ae9dd81 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,168 +1,82 @@ # 智能体协作规范（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.1+；MySQL 5.7+；Layui 2.x；模板引擎：ThinkPHP 内置模板引擎 -- 命名规范（必读）：[ulthon-naming-convention.md](./.agents/rules/ulthon-naming-convention.md) -- 代码风格（必读）：遵循项目根目录 `.php-cs-fixer.php` -- 表结构设计规范（必读）：[ulthon-scheme-definition](./.agents/skills/ulthon-scheme-definition/SKILL.md)（含特殊字段约定、字段后缀、组件类型、关联表参数） -- 项目文档主页（在线）： - -### 代码分层铁律（不可协商） +## 代码分层铁律（Base/App 双层架构） 框架采用 Base/App 双层架构：`extend/base/` 是框架内核（`*Base` 类），`app/` 是业务代码入口，两者目录路径一一对应。 -默认身份是**框架使用者**：严禁修改 `extend/base/` 下任何文件，所有开发只在 `app/` 进行；扩展框架内置能力时只改 `app/` 下对应入口类（必要时 `extends` 对应 `*Base`，保持方法签名一致）。 +- 严禁修改 `extend/base/` 下任何文件，所有开发只在 `app/` 进行 +- 扩展框架内置能力时只改 `app/` 下对应入口类（必要时 `extends` 对应 `*Base`，保持方法签名一致） +- `app/` 可文件级覆盖 `extend/base/` 的三类文件（见 [ulthon-file-override-mechanism.md](./.agents/rules/ulthon-file-override-mechanism.md)） +- 默认身份是框架使用者；仅当任务明确涉及 `extend/base/` 时切换为框架作者身份 +- 完整规则、目录映射与项目结构总览：[ulthon-base-app-architecture](./.agents/skills/ulthon-base-app-architecture/SKILL.md) -仅在任务明确涉及 `extend/base/` 时切换为**框架作者**身份，需额外遵守依赖倒置（Base 内部调用走 `app/` 入口类）、Base/App 同步提供、稳定性与通用性优先等约束。 +## 其他框架规则 -完整规则、文件级覆盖机制、目录映射与常见误区：[ulthon-base-app-architecture](./.agents/skills/ulthon-base-app-architecture/SKILL.md) +- 技术栈：ThinkPHP 8.x / PHP 8.1+ / MySQL 5.7+ / Layui 2.x；代码风格遵循根目录 `.php-cs-fixer.php` +- 命名规范（必读）：[ulthon-naming-convention.md](./.agents/rules/ulthon-naming-convention.md) +- 表结构设计（必读）：[ulthon-scheme-definition](./.agents/skills/ulthon-scheme-definition/SKILL.md)；表结构优先 Scheme（`app/admin/scheme/`），避免 ENUM；tools:db 仅用于调试，不用于设计表结构 +- 前端：视图与脚本同名配对（`*.html` + 同名 `*.js`），按模块维护 `_common.js` +- 权限：基于 `auth` 注解动态扫描节点与鉴权，以角色为中心管理（CLI 见 [ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md)） +- 临时文件统一输出到 `runtime/agents/`（可按任务再分子目录），不放仓库根目录 +- 调试与验证优先框架内置命令行工具（见下方快速命令），不借助外部数据库 MCP 或临时脚本 +- 项目运行方式未在上方说明时，执行命令前先按 [ulthon-deploy-environment.md](./.agents/rules/ulthon-deploy-environment.md) 判断环境（如根目录有 Docker 编排文件则勿直接宿主机执行 `php think`） +- 在线文档： -### 其他规则 +## 规则与技能 -- 数据库：表结构优先 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 或临时脚本 +- `.agents/rules/`（零散规则）与 `.agents/skills/`（场景技能）按前缀区分维护者：`ulthon-` 为框架分发，`project-` 为本项目自建 +- 涉及具体模块/场景前，先查对应目录是否有专属文件 +- 新增零散规则的操作流程见 [ulthon-rules-manager](./.agents/skills/ulthon-rules-manager/SKILL.md) -### 标准开发流程（Scheme + CURD，默认必须执行） +框架规则速览（一行一条，完整内容见文件）： -> 完整操作细节见对应技能文件，本节仅列出流程骨架与核心约束。 +| 规则文件 | 说明 | +|---------|------| +| [ulthon-naming-convention.md](./.agents/rules/ulthon-naming-convention.md) | 目录与 PHP 文件命名约定 | +| [ulthon-controller-url.md](./.agents/rules/ulthon-controller-url.md) | URL 与控制器/方法映射 | +| [ulthon-controller-response-throw.md](./.agents/rules/ulthon-controller-response-throw.md) | success/error/result/redirect 是 throw 不是 return | +| [ulthon-deploy-environment.md](./.agents/rules/ulthon-deploy-environment.md) | 部署栈模式与运行环境判断 | +| [ulthon-source-directory.md](./.agents/rules/ulthon-source-directory.md) | source/ 目录约定与安全要求 | +| [ulthon-file-override-mechanism.md](./.agents/rules/ulthon-file-override-mechanism.md) | app/ 覆盖 extend/base/ 的三类文件 | +| [ulthon-system-config.md](./.agents/rules/ulthon-system-config.md) | sysconfig 的存储/读取/扩展 | -| 步骤 | 说明 | 对应技能 | -|------|------|----------| -| 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. 最终检查 | 页面路径可用、命令行验证通过、代码规范自查 | - | +## 标准开发流程（Scheme + CURD） -## 规则维护机制 +| 步骤 | 对应技能 | +|------|----------| +| 1. 初始化环境（依赖、`.env`、数据库、`php think` 可用） | - | +| 2. 设计表结构（`app/admin/scheme/`） | [ulthon-scheme-definition](./.agents/skills/ulthon-scheme-definition/SKILL.md) | +| 3. 同步 Scheme 与 DB（`scheme:sync` / `scheme:make`，生成前必须一致） | [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-admin-table](./.agents/skills/ulthon-admin-table/SKILL.md)、[ulthon-page-api-dual-mode](./.agents/skills/ulthon-page-api-dual-mode/SKILL.md) | +| 6. 功能验证 | [ulthon-tools-http-call](./.agents/skills/ulthon-tools-http-call/SKILL.md) | +| 7. 功能配套（菜单/权限/角色） | [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-naming-convention.md](./.agents/rules/ulthon-naming-convention.md) | 命名规范 | 目录命名与 PHP 文件命名约定 | -| [ulthon-controller-url.md](./.agents/rules/ulthon-controller-url.md) | 控制器路由 | URL 与控制器/方法的映射规则 | -| [ulthon-controller-response-throw.md](./.agents/rules/ulthon-controller-response-throw.md) | 控制器响应 | success/error/result/redirect 是 throw 不是 return，try-catch 内调用的陷阱与正确范式 | -| [ulthon-deploy-environment.md](./.agents/rules/ulthon-deploy-environment.md) | 部署与命令执行 | 部署栈模式与 Docker/宿主机命令判断 | -| [ulthon-source-directory.md](./.agents/rules/ulthon-source-directory.md) | source/ 目录 | 子项目/多端代码的目录约定与安全要求 | -| [ulthon-file-override-mechanism.md](./.agents/rules/ulthon-file-override-mechanism.md) | 文件加载机制 | app/ 覆盖 extend/base/ 的三类文件级覆盖机制与反例 | -| [ulthon-system-config.md](./.agents/rules/ulthon-system-config.md) | 系统配置（sysconfig） | 后台可变配置的存储、读取、保存、视图扩展规范 | - -> 使用者业务规则索引见 `.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) -- 后台表格机制与定制（按钮/字段/搜索/页面分类 A/B/C/D）：[ulthon-admin-table](./.agents/skills/ulthon-admin-table/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) -- 内置定时器与定时任务扩展（含多节点协调、run_type 调度）：[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) -- 内置 MCP Server（密钥/授权/客户端配置/命令行联调）：[ulthon-mcp](./.agents/skills/ulthon-mcp/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) -- 测试工作流（设计哲学/决策/约束/运行/编写/回归保护）：[ulthon-testing](./.agents/skills/ulthon-testing/SKILL.md) -- 页面验证 AI 自测（零项目依赖，6 步 checklist）：[ulthon-page-qa](./.agents/skills/ulthon-page-qa/SKILL.md) -- 框架更新工作流（admin:update 同步上游）：[ulthon-update-workflow](./.agents/skills/ulthon-update-workflow/SKILL.md) -- 零散规则管理（新增/维护 `.agents/rules/`）：[ulthon-rules-manager](./.agents/skills/ulthon-rules-manager/SKILL.md) - -> 日志查看走通用命令 `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` | +| 场景 | 命令 | +|------|------| +| 同步表结构（代码→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` |