docs(agents): 落实按主题单一文档原则,合并规则到对应技能

- AGENTS.md 代码分层铁律精简为入口摘要,链接指向技能详情
- 合并 ulthon-timer-multi-node 规则到 ulthon-timer 技能(多节点协调章节)
- 合并 ulthon-database-design 规则到 ulthon-scheme-definition 技能(含字段约定、组件类型)
- 合并 ulthon-testing 规则到 ulthon-testing 技能(含设计哲学、决策树、测试约束)
- rules-manager 边界原则从规则/技能二分改为按主题单一文档
- AGENTS.md 通用基础规范中表结构规范链接改向技能
- 工作流索引中三个技能描述扩充(明确承载原规则内容)
This commit is contained in:
augushong
2026-07-19 09:07:42 +08:00
parent 1f91abe9d2
commit e392db007a
8 changed files with 340 additions and 430 deletions

View File

@@ -32,28 +32,18 @@
- 技术栈ThinkPHP 8.xPHP 8+MySQL 8+Layui 2.x模板引擎ThinkPHP 内置模板引擎
- 命名规范(必读):[ulthon-naming-convention.md](./.agents/rules/ulthon-naming-convention.md)
- 代码风格(必读):遵循项目根目录 `.php-cs-fixer.php`
- 表结构设计规范(必读):[ulthon-database-design.md](./.agents/rules/ulthon-database-design.md)
- 表结构设计规范(必读):[ulthon-scheme-definition](./.agents/skills/ulthon-scheme-definition/SKILL.md)(含特殊字段约定、字段后缀、组件类型、关联表参数)
- 项目文档主页(在线):<https://doc.ulthon.com/read/augushong/ulthon_admin/home/zh-cn/2.x.html>
### 代码分层铁律(不可协商)
框架采用 Base/App 双层架构。根据当前任务的开发者身份,遵守对应约束:
框架采用 Base/App 双层架构`extend/base/` 是框架内核(`*Base` 类),`app/` 是业务代码入口,两者目录路径一一对应。
**所有身份通用**
- `extend/base/` 是框架内核(`*Base``app/` 是业务代码入口,目录路径一一对应
默认身份是**框架使用者**:严禁修改 `extend/base/` 下任何文件,所有开发只在 `app/` 进行;扩展框架内置能力时只改 `app/` 下对应入口类(必要时 `extends` 对应 `*Base`,保持方法签名一致)。
**框架使用者(默认身份,除非明确说"修内核/改框架"**
- 严禁修改 `extend/base/` 下任何文件
- 所有开发只在 `app/` 目录进行;新写业务能力直接在 `app/` 下实现即可
- 扩展内置能力时,只改 `app/` 下对应入口类(必要时 `extends` 对应 `*Base`),保持方法签名一致
仅在任务明确涉及 `extend/base/` 时切换为**框架作者**身份需额外遵守依赖倒置Base 内部调用走 `app/` 入口类、Base/App 同步提供、稳定性与通用性优先等约束。
**框架作者(仅当任务涉及 `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)
完整规则、文件级覆盖机制、目录映射与常见误区:[ulthon-base-app-architecture](./.agents/skills/ulthon-base-app-architecture/SKILL.md)
### 其他规则
@@ -96,13 +86,10 @@
| 规则文件 | 作用域 | 说明 |
|---------|--------|------|
| [ulthon-naming-convention.md](./.agents/rules/ulthon-naming-convention.md) | 命名规范 | 目录命名与 PHP 文件命名约定 |
| [ulthon-database-design.md](./.agents/rules/ulthon-database-design.md) | 数据库设计 | 表结构设计:特殊字段、字段后缀、注释语法、类型大全 |
| [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-file-override-mechanism.md](./.agents/rules/ulthon-file-override-mechanism.md) | 文件加载机制 | app/ 覆盖 extend/base/ 的三类文件级覆盖机制与反例 |
| [ulthon-timer-multi-node.md](./.agents/rules/ulthon-timer-multi-node.md) | 定时任务相关 | 多节点协调规则与设计 |
| [ulthon-testing.md](./.agents/rules/ulthon-testing.md) | 测试规范 | 测试设计哲学、4层测试模型、该不该写测试、测试库安全、fixture 原则 |
> 使用者业务规则索引见 `.agents/PROJECT.md` 的「规则索引」章节。
@@ -114,15 +101,15 @@ Skills 是"按场景调用的工作流说明",统一以 `.agents/skills/*/SKIL
- 技能命名约定:`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)
- 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)
- 内置定时器与定时任务扩展:[ulthon-timer](./.agents/skills/ulthon-timer/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)
- 权限与角色管理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)
- 测试工作流(设计哲学/决策/约束/运行/编写/回归保护):[ulthon-testing](./.agents/skills/ulthon-testing/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)