mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-07-10 03:42:49 +08:00
c5ebf86ad9
- 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
143 lines
5.4 KiB
Markdown
143 lines
5.4 KiB
Markdown
---
|
||
name: "ulthon-rules-manager"
|
||
description: "零散规则管理技能。指导智能体在 `.agents/rules/` 目录下新增、维护模块级/场景级规则文件，并同步更新 AGENTS.md 与 PROJECT.md 的规则索引。触发词包括"记录规则"、"新增规则"、"写条规则"、"这个模块有约束"、"记录约束"等。"
|
||
---
|
||
|
||
# 零散规则管理（Rules Manager）
|
||
|
||
## 核心概念
|
||
|
||
**零散规则（Rules）** 是模块级/场景级的专属知识，不适合放在全局 `AGENTS.md` 中展开。存放在 `.agents/rules/` 目录下，每条规则一个独立文件，通过索引被智能体发现和引用。
|
||
|
||
Rules 可包含以下类型的内容：
|
||
- **约束**：不能怎么做、必须怎么做（如命名约定、分层铁律）
|
||
- **约定**：惯例、默认行为（如目录结构、文件配对）
|
||
- **设计决策**：某个功能的设计方案与背景（如多节点协调方案、认证架构选型）
|
||
|
||
## Rules 与 Skills 的边界
|
||
|
||
| 维度 | Rule（规则） | Skill（技能） |
|
||
|------|-------------|---------------|
|
||
| 核心问题 | "是什么""不能做什么""为什么这样设计" | "怎么做""一步步如何完成" |
|
||
| 知识形态 | 静态声明（A 对应 B、禁止 C） | 动态流程（第 1 步...第 2 步...） |
|
||
| 触发时机 | 涉及某模块时需先了解其规则 | 需要执行某操作时按步骤调用 |
|
||
| 典型例子 | URL 映射规则、目录约定、多节点设计 | CURD 生成流程、定时任务配置、菜单创建 |
|
||
|
||
**判断方法**：如果内容主要是"告知性"的（让智能体知道某个事实/约束/设计），放 Rule。如果内容主要是"操作性"的（让智能体按步骤完成某件事），放 Skill。
|
||
|
||
**灰色地带处理**：部分内容混合了规则和操作（如 Base/App 架构文档既有铁律又有场景指南），此时保留为 Skill，因为其核心价值在"指导如何操作"。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
.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 | 业务 | 订单模块 | 库存锁定规则 |
|
||
```
|