mirror of https://gitee.com/ulthon/ulthon_admin.git synced 2026-07-09 19:42:47 +08:00

Files

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

- 新增 .agents/rules/ 目录，存放模块级/场景级独立规则文件
- 新增 ulthon-rules-manager 技能，指导规则的新增/索引/格式
- 新增 ulthon-timer-multi-node 规则文件（从 PROJECT.md 迁移）
- AGENTS.md 新增「零散规则」章节，含框架级规则索引表
- PROJECT.md 新增「规则索引」章节，含全量规则索引表
- 命名约定：ulthon- 前缀为框架内置，project- 前缀为使用者业务

2026-06-01 21:26:16 +08:00

4.3 KiB

Raw Blame History

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

规则文件格式模板

# 规则名称

> 来源：框架内置（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/：

首次接触项目时，通过 AGENTS.md 或 PROJECT.md 的索引了解有哪些规则
涉及特定模块开发时，查找该模块是否有对应的规则文件
用户提到某个模块有特殊约束时，查找对应规则

维护规则

规则内容变更时，同步更新文件内容和索引中的说明列
规则过期时，标记为"已废弃"或直接删除，并从索引中移除
框架更新时，只操作 ulthon- 前缀的规则文件，不动 project- 前缀的文件

索引格式

索引表统一使用以下格式：

| 规则文件 | 来源 | 作用域 | 说明 |
|---------|------|--------|------|
| ulthon-timer-multi-node.md | 框架 | 定时任务相关 | 多节点协调规则 |
| project-order-stock-lock.md | 业务 | 订单模块 | 库存锁定规则 |

4.3 KiB Raw Blame History Unescape Escape