refactor(rules): 精简 AGENTS.md,下沉模块级规则,迁移 skill 为 rule

- tp-controller-url-rules skill 迁移为 rule ulthon-controller-url.md
- AGENTS.md「其他规则」中的 source/ 约定下沉为 ulthon-source-directory.md
- AGENTS.md「其他规则」中的部署栈+命令执行环境下沉为 ulthon-deploy-environment.md
- AGENTS.md 精简:其他规则从 10 条减至 5 条,规则维护机制从 10 行减至 4 行
- ulthon-rules-manager 技能增加 rules/skills 边界判定说明
- rules 定位拓宽:约束、约定、设计决策均可作为 rule
This commit is contained in:
augushong
2026-06-01 21:48:27 +08:00
parent 6d2963a9a4
commit c5ebf86ad9
6 changed files with 123 additions and 75 deletions

View File

@@ -43,13 +43,8 @@
### 其他规则
- 数据库:表结构优先 Scheme`app/admin/scheme/`);避免 ENUMtools:db 用于调试,不用于设计表结构
- 数据库:表结构优先 Scheme`app/admin/scheme/`);避免 ENUMtools: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 或临时脚本
@@ -69,30 +64,27 @@
| 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.md`(本文件)+ `.agents/rules/ulthon-*` 为唯一权威;默认不随任务动态增长
- **使用者补充规则**`.agents/PROJECT.md` + `.agents/rules/project-*`,由开发者维护
- **维护约束**:框架作者新增/调整规则前须与开发者确认;使用者身份发现需记录的约束时,优先记录到对应位置
- **管理技能**[ulthon-rules-manager](./.agents/skills/ulthon-rules-manager/SKILL.md)
## 零散规则
针对特定模块/场景的约束,不适合在全局展开,存放在 `.agents/rules/` 目录下,每条规则一个独立文件。
模块/场景级的专属知识(约束、约定、设计决策),不适合在全局展开,存放在 `.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) | 定时任务相关 | 多节点协调规则 |
| [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` 的「规则索引」章节。
@@ -113,7 +105,6 @@ Skills 是"按场景调用的工作流说明",统一以 `.agents/skills/*/SKIL
- 登录认证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)
## 智能体指导