feat(rules): 新增零散规则管理机制

- 新增 .agents/rules/ 目录,存放模块级/场景级独立规则文件
- 新增 ulthon-rules-manager 技能,指导规则的新增/索引/格式
- 新增 ulthon-timer-multi-node 规则文件(从 PROJECT.md 迁移)
- AGENTS.md 新增「零散规则」章节,含框架级规则索引表
- PROJECT.md 新增「规则索引」章节,含全量规则索引表
- 命名约定:ulthon- 前缀为框架内置,project- 前缀为使用者业务
This commit is contained in:
augushong
2026-06-01 21:26:16 +08:00
parent 5941a61b80
commit f867c42a72
5 changed files with 225 additions and 19 deletions

View File

@@ -47,6 +47,7 @@
- `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 或临时脚本
@@ -78,9 +79,24 @@
- 智能体以“框架作者”身份开发时,如需新增/调整规则,必须先与开发者确认是否记录、记录位置与具体写法,并按确认结果落到对应规则文件。
- 智能体以“使用框架的开发者”身份执行任务时,如发现需要记录或调整的项目约束,应更新到对应规则文件(业务侧约束优先记录到 `.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` 为准。
Skills 是"按场景调用的工作流说明",统一以 `.agents/skills/*/SKILL.md` 为准。
- 技能命名约定:`ulthon-` 前缀为框架内置技能,`project-` 前缀为项目业务技能。新增业务技能时使用 `project-` 前缀。
@@ -121,7 +137,10 @@ ulthon_admin/
├── database/ # 数据库迁移与种子
├── source/ # 主工程外内容统一目录(多端代码/资料/附件/各类子项目)
│ └── clients/uniapp/ # uni-app 前端工程
└── .agents/ # 智能体技能与规则
└── .agents/ # 智能体协作资源
├── skills/ # 工作流技能(按场景调用)
├── rules/ # 零散规则(按模块/场景拆分)
└── PROJECT.md # 项目业务总览与规则索引
```
## 快速命令参考