mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-07-07 18:42:49 +08:00
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
@@ -27,25 +27,18 @@
|
||||
|
||||
开发过程中补充的业务规则、团队偏好与临时约束，按条新增。规则应可执行、可复现、可验证。
|
||||
|
||||
> 已迁移为独立规则文件的条目保留引用，不再在此处展开内容。
|
||||
|
||||
### 2026-05-26: 定时任务多节点协调
|
||||
|
||||
新增功能：
|
||||
- 多节点定时任务协调（数据库为主协调中心）
|
||||
- run_type 调度：auto/main/all/manual
|
||||
- 主节点自动选举 + 手动切换
|
||||
- 执行日志记录与查看
|
||||
- 定时任务配置管理 UI
|
||||
- 日志清理命令 `php think admin:timer:log:clean`
|
||||
已迁移至独立规则文件：[ulthon-timer-multi-node.md](rules/ulthon-timer-multi-node.md)
|
||||
|
||||
新增数据表：
|
||||
- ul_system_timer_config
|
||||
- ul_system_timer_log
|
||||
- ul_system_host 新增 is_master 字段
|
||||
## 规则索引
|
||||
|
||||
新增命令：
|
||||
- admin:timer:log:clean [--days=30]
|
||||
本项目的零散规则存放在 `.agents/rules/` 目录下，每条规则一个独立文件。
|
||||
|
||||
新增管理页面：
|
||||
- 定时器配置管理 (/admin/system.timer_config/index)
|
||||
- 定时器执行日志 (/admin/system.timer_log/index)
|
||||
- 主机列表增强（主节点标识、切换主节点）
|
||||
| 规则文件 | 来源 | 作用域 | 说明 |
|
||||
|---------|------|--------|------|
|
||||
| [ulthon-timer-multi-node.md](rules/ulthon-timer-multi-node.md) | 框架 | 定时任务相关 | 多节点协调规则 |
|
||||
|
||||
> 新增/维护规则请参考技能：[ulthon-rules-manager](skills/ulthon-rules-manager/SKILL.md)
|
||||
|
||||
35
.agents/rules/.README
Normal file
35
.agents/rules/.README
Normal file
@@ -0,0 +1,35 @@
|
||||
# 零散规则目录
|
||||
|
||||
本目录存放按模块/场景拆分的独立规则文件，避免全局规则膨胀。
|
||||
|
||||
## 命名约定
|
||||
|
||||
- `ulthon-` 前缀：框架内置规则，框架作者维护
|
||||
- `project-` 前缀：使用者业务规则，开发者维护
|
||||
|
||||
## 文件格式
|
||||
|
||||
每个规则文件包含以下章节：
|
||||
|
||||
```markdown
|
||||
# 规则名称
|
||||
|
||||
> 来源：框架内置（ulthon-）或使用者业务（project-）
|
||||
> 作用域：适用的模块/文件/场景
|
||||
> 触发条件：智能体何时应加载此规则
|
||||
|
||||
## 规则内容
|
||||
（具体的可执行规则）
|
||||
|
||||
## 相关文件 / 相关数据表 / 相关命令
|
||||
（关联的代码路径、配置路径等）
|
||||
```
|
||||
|
||||
## 索引
|
||||
|
||||
- 框架级规则索引：根目录 `AGENTS.md` 的「零散规则」章节
|
||||
- 全量规则索引：`.agents/PROJECT.md` 的「规则索引」章节
|
||||
|
||||
## 管理技能
|
||||
|
||||
新增/维护规则时，参考技能：[ulthon-rules-manager](../skills/ulthon-rules-manager/SKILL.md)
|
||||
33
.agents/rules/ulthon-timer-multi-node.md
Normal file
33
.agents/rules/ulthon-timer-multi-node.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# 定时任务多节点协调
|
||||
|
||||
> 来源：框架内置（ulthon-）
|
||||
> 作用域：定时任务相关模块（TimerConfig、TimerLog、Host）
|
||||
> 触发条件：涉及定时任务开发、多节点部署、主节点选举等场景时加载
|
||||
|
||||
## 规则内容
|
||||
|
||||
- 多节点定时任务协调以数据库为主协调中心
|
||||
- run_type 调度模式：auto / main / all / manual
|
||||
- 支持主节点自动选举与手动切换
|
||||
- 执行日志必须记录，支持查看与清理
|
||||
- 定时任务配置管理通过 UI 管理
|
||||
|
||||
## 相关数据表
|
||||
|
||||
- ul_system_timer_config
|
||||
- ul_system_timer_log
|
||||
- ul_system_host（含 is_master 字段）
|
||||
|
||||
## 相关命令
|
||||
|
||||
- `php think admin:timer:log:clean [--days=30]` — 清理过期执行日志
|
||||
|
||||
## 相关管理页面
|
||||
|
||||
- 定时器配置管理：/admin/system.timer_config/index
|
||||
- 定时器执行日志：/admin/system.timer_log/index
|
||||
- 主机列表增强（主节点标识、切换主节点）
|
||||
|
||||
## 相关技能
|
||||
|
||||
- [ulthon-timer](../skills/ulthon-timer/SKILL.md)
|
||||
126
.agents/skills/ulthon-rules-manager/SKILL.md
Normal file
126
.agents/skills/ulthon-rules-manager/SKILL.md
Normal file
@@ -0,0 +1,126 @@
|
||||
---
|
||||
name: "ulthon-rules-manager"
|
||||
description: "零散规则管理技能。指导智能体在 `.agents/rules/` 目录下新增、维护模块级/场景级规则文件，并同步更新 AGENTS.md 与 PROJECT.md 的规则索引。触发词包括"记录规则"、"新增规则"、"写条规则"、"这个模块有约束"、"记录约束"等。"
|
||||
---
|
||||
|
||||
# 零散规则管理（Rules Manager）
|
||||
|
||||
## 核心概念
|
||||
|
||||
**零散规则**是针对特定模块或场景的约束，不适合放在全局 `AGENTS.md` 中展开。它们存放在 `.agents/rules/` 目录下，每条规则一个独立文件，通过索引被智能体发现和引用。
|
||||
|
||||
**和 Skills 的区别**：Skills 是"按场景调用的工作流说明"（怎么做），Rules 是"特定模块的约束/约定"（不能怎么做 / 必须遵守什么）。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
.agents/rules/
|
||||
├── .README # 目录说明与格式规范
|
||||
├── ulthon-timer-multi-node.md # 框架内置规则示例
|
||||
├── project-xxx.md # 使用者业务规则示例
|
||||
└── ...
|
||||
```
|
||||
|
||||
## 命名约定
|
||||
|
||||
| 前缀 | 含义 | 维护者 | 约束 |
|
||||
|------|------|--------|------|
|
||||
| `ulthon-` | 框架内置规则 | 框架作者 | 随框架更新分发 |
|
||||
| `project-` | 使用者业务规则 | 开发者 | 不被框架更新影响 |
|
||||
|
||||
文件名使用小写英文 + 短横线，语义清晰，例如：
|
||||
- `ulthon-timer-multi-node.md`
|
||||
- `ulthon-upload-storage.md`
|
||||
- `project-order-stock-lock.md`
|
||||
- `project-wechat-auth.md`
|
||||
|
||||
## 规则文件格式模板
|
||||
|
||||
```markdown
|
||||
# 规则名称
|
||||
|
||||
> 来源：框架内置（ulthon-）或 使用者业务（project-）
|
||||
> 作用域：适用的模块/文件/场景
|
||||
> 触发条件：智能体何时应加载此规则
|
||||
|
||||
## 规则内容
|
||||
|
||||
（具体的可执行规则，每条应可验证）
|
||||
|
||||
## 相关文件
|
||||
|
||||
（关联的代码路径、配置路径等）
|
||||
|
||||
## 相关技能
|
||||
|
||||
（如有对应的 Skill，用相对链接引用）
|
||||
```
|
||||
|
||||
必填章节：`规则内容`
|
||||
按需章节：`相关文件`、`相关数据表`、`相关命令`、`相关技能`
|
||||
|
||||
## 新增规则流程
|
||||
|
||||
### 1. 判断是否需要新增规则
|
||||
|
||||
满足以下条件之一时，应建议新增规则：
|
||||
- 某个模块有独特的开发约束，不适合写在全局 `AGENTS.md`
|
||||
- 开发过程中发现了可复用的约定，值得记录
|
||||
- 用户明确要求"记录这条规则"/"这个模块有约束"
|
||||
|
||||
不满足条件时：
|
||||
- 如果是全局性规则 → 记录到 `AGENTS.md`（需框架作者身份确认）
|
||||
- 如果是项目业务概述 → 记录到 `.agents/PROJECT.md`
|
||||
|
||||
### 2. 确定命名与来源
|
||||
|
||||
- 框架内置规则：`ulthon-{模块}-{场景}.md`
|
||||
- 使用者业务规则：`project-{模块}-{场景}.md`
|
||||
|
||||
### 3. 编写规则文件
|
||||
|
||||
在 `.agents/rules/` 下创建文件，按格式模板填写。
|
||||
|
||||
规则内容要求：
|
||||
- **可执行**：智能体能直接据此行动
|
||||
- **可验证**：有明确的对/错判断标准
|
||||
- **有边界**：明确写出作用域，避免被误用到其他模块
|
||||
|
||||
### 4. 更新索引（必须）
|
||||
|
||||
新增规则后，必须同步更新两处索引：
|
||||
|
||||
**AGENTS.md（框架级索引）**：
|
||||
在「零散规则」章节的索引表中新增一行（仅 `ulthon-` 前缀的规则）。
|
||||
|
||||
**PROJECT.md（全量索引）**：
|
||||
在「规则索引」章节的索引表中新增一行（所有前缀的规则）。
|
||||
|
||||
### 5. 迁移现有内容
|
||||
|
||||
如果规则内容原本记录在 `PROJECT.md` 的「增量规则记录」章节，迁移后应将该章节的对应内容替换为指向规则文件的引用（而非直接删除，保留历史痕迹）。
|
||||
|
||||
## 读取规则
|
||||
|
||||
智能体在以下场景应主动查阅 `.agents/rules/`：
|
||||
|
||||
1. 首次接触项目时，通过 `AGENTS.md` 或 `PROJECT.md` 的索引了解有哪些规则
|
||||
2. 涉及特定模块开发时，查找该模块是否有对应的规则文件
|
||||
3. 用户提到某个模块有特殊约束时，查找对应规则
|
||||
|
||||
## 维护规则
|
||||
|
||||
- 规则内容变更时，同步更新文件内容和索引中的说明列
|
||||
- 规则过期时，标记为"已废弃"或直接删除，并从索引中移除
|
||||
- 框架更新时，只操作 `ulthon-` 前缀的规则文件，不动 `project-` 前缀的文件
|
||||
|
||||
## 索引格式
|
||||
|
||||
索引表统一使用以下格式：
|
||||
|
||||
```markdown
|
||||
| 规则文件 | 来源 | 作用域 | 说明 |
|
||||
|---------|------|--------|------|
|
||||
| ulthon-timer-multi-node.md | 框架 | 定时任务相关 | 多节点协调规则 |
|
||||
| project-order-stock-lock.md | 业务 | 订单模块 | 库存锁定规则 |
|
||||
```
|
||||
Reference in New Issue
Block a user