mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-08-30 12:45:32 +08:00
e392db007a
- AGENTS.md 代码分层铁律精简为入口摘要，链接指向技能详情 - 合并 ulthon-timer-multi-node 规则到 ulthon-timer 技能（多节点协调章节） - 合并 ulthon-database-design 规则到 ulthon-scheme-definition 技能（含字段约定、组件类型） - 合并 ulthon-testing 规则到 ulthon-testing 技能（含设计哲学、决策树、测试约束） - rules-manager 边界原则从规则/技能二分改为按主题单一文档 - AGENTS.md 通用基础规范中表结构规范链接改向技能 - 工作流索引中三个技能描述扩充（明确承载原规则内容）
189 lines
9.3 KiB
Markdown
189 lines
9.3 KiB
Markdown
---
|
||
name: "ulthon-rules-manager"
|
||
description: "零散规则管理技能。指导智能体在 `.agents/rules/` 目录下新增、维护模块级/场景级规则文件，并同步更新 AGENTS.md 与 PROJECT.md 的规则索引。触发词包括"记录规则"、"新增规则"、"写条规则"、"这个模块有约束"、"记录约束"等。"
|
||
---
|
||
|
||
# 零散规则管理（Rules Manager）
|
||
|
||
## 核心概念
|
||
|
||
**零散规则（Rules）** 是模块级/场景级的专属知识，不适合放在全局 `AGENTS.md` 中展开。存放在 `.agents/rules/` 目录下，每条规则一个独立文件，通过索引被智能体发现和引用。
|
||
|
||
Rules 可包含以下类型的内容：
|
||
- **约束**：不能怎么做、必须怎么做（如命名约定、分层铁律）
|
||
- **约定**：惯例、默认行为（如目录结构、文件配对）
|
||
- **设计决策**：某个功能的设计方案与背景（如多节点协调方案、认证架构选型）
|
||
|
||
## Rules 与 Skills 的边界
|
||
|
||
### 核心原则：按主题单一文档
|
||
|
||
**默认情况下，一个主题只应有一个文档**。如果某个主题既有设计决策（"为什么"、"约束"），又有操作流程（"怎么做"），应合并为一个文档，避免分散维护导致的重复和遗漏。
|
||
|
||
合并方向：**优先合并到 Skill**。Skill 作为"按场景调用"的入口更符合实际触发逻辑——智能体在执行任务时按需打开，单文件就能完整理解。
|
||
|
||
### 何时保留独立的 Rule
|
||
|
||
只有满足以下条件之一时，才创建独立的 Rule 文件：
|
||
|
||
- **纯静态声明**：内容只有约束/约定/设计决策，没有"按步骤操作"的流程（如命名约定、URL 映射规则、目录约定、文件级覆盖机制）
|
||
- **跨多个 Skill 共享**：约束被多个技能共同引用，独立出来更便于复用
|
||
- **不依附于任何具体操作场景的全局铁律**
|
||
|
||
### 反例：不要为同一主题拆分 Rule + Skill
|
||
|
||
例如「测试」主题：
|
||
- 错误做法：Rule 讲"设计哲学 + 4 层模型"，Skill 讲"如何运行测试"——读者需要打开两个文件才能完整理解，且边界容易模糊导致重复
|
||
- 正确做法：合并为一个 Skill，"设计哲学"作为开篇章节，"如何运行"作为操作章节
|
||
|
||
### 归属判断表
|
||
|
||
| 内容性质 | 归属 | 例子 |
|
||
|---------|------|------|
|
||
| 纯约束/约定/设计决策（无操作流程） | Rule | 命名规范、URL 映射、目录约定、文件级覆盖机制 |
|
||
| 操作流程（含必要的设计背景） | Skill | 测试工作流（含设计哲学）、Scheme 定义（含字段约定）、定时器（含多节点设计） |
|
||
| 致命铁律（如架构分层） | Skill 中的独立章节 | Base/App 架构铁律（在 ulthon-base-app-architecture 技能里） |
|
||
|
||
## PROJECT.md 与子规则的关系
|
||
|
||
`PROJECT.md` 是项目规则的**精简入口**，只包含两部分：
|
||
|
||
1. 一段项目概述（服务于谁、解决什么问题、核心能力）——智能体理解业务语境的起点
|
||
2. `project-*` 规则索引（导航到具体业务规则）
|
||
|
||
稳定的业务约束和模式决策**拆分到 `project-*` 子规则文件**，不在 PROJECT.md 中展开。易变的状态描述（模块清单、依赖列表、技术栈等）**不记录为规则**，让智能体从代码/配置中读取——强行记录只会导致规则与代码脱节。
|
||
|
||
**必备子规则**：`project-dev-runtime-deploy.md`（记录本项目实际采用的开发/运行/部署模式）。每个项目都应有此文件，因为智能体需要知道"这个项目怎么跑"才能正确执行命令、调试、部署。该文件为**开放式骨架**——不限于框架预设的 stack，WAMP、宝塔、Docker、源码直传等任何实际模式都如实记录。
|
||
|
||
**可选子规则**：`project-business-constraints.md`（记录不可协商的业务硬约束，如数据一致性、安全强制、合规要求）。仅当项目有此类铁律时才创建。
|
||
|
||
**模式子规则的灵活性**：默认合并为一个 `project-dev-runtime-deploy.md`（三章节：开发方式 / 运行方式 / 部署方式）。若某一方面内容过于复杂（如部署涉及多套流程、多环境差异），可拆分为独立子规则（如 `project-deploy-detail.md`），并在原文件中引用指向。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
.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` 的「项目概述」段落（保持精简）
|
||
- 如果是易变的状态描述（模块清单、依赖列表等）→ **不记录为规则**，让智能体从代码/配置中读取
|
||
- 如果是稳定的业务硬约束或模式决策 → 创建 `project-*` 子规则文件，并在 PROJECT.md 的索引中登记
|
||
|
||
### 2. 确定命名与来源
|
||
|
||
- 框架内置规则：`ulthon-{模块}-{场景}.md`
|
||
- 使用者业务规则：`project-{模块}-{场景}.md`
|
||
|
||
### 3. 编写规则文件
|
||
|
||
在 `.agents/rules/` 下创建文件，按格式模板填写。
|
||
|
||
规则内容要求：
|
||
- **可执行**：智能体能直接据此行动
|
||
- **可验证**：有明确的对/错判断标准
|
||
- **有边界**：明确写出作用域，避免被误用到其他模块
|
||
|
||
### 4. 更新索引（必须）
|
||
|
||
新增规则后，必须同步更新两处索引：
|
||
|
||
**AGENTS.md（框架规则索引）**：
|
||
在「零散规则」章节的「框架内置规则索引」表中新增一行（仅 `ulthon-` 前缀的规则）。
|
||
|
||
**PROJECT.md（项目业务规则索引）**：
|
||
在「规则索引」章节的索引表中新增一行（仅 `project-` 前缀的规则）。
|
||
|
||
两个索引职责互斥：`ulthon-` 前缀只进 AGENTS.md，`project-` 前缀只进 PROJECT.md。框架更新（操作 `ulthon-*`）不污染项目业务索引，项目维护（操作 `project-*`）不污染框架索引。
|
||
|
||
### 5. 迁移现有内容（如适用）
|
||
|
||
如果规则内容原本以其他形式散落记录（如 AGENTS.md / PROJECT.md 的内联描述、聊天记录、issue 等），抽取为独立规则文件后，应在原位置替换为指向规则文件的引用，保留可追溯性。
|
||
|
||
## 读取规则
|
||
|
||
智能体在以下场景应主动查阅 `.agents/rules/`：
|
||
|
||
1. 首次接触项目时，先看 `AGENTS.md` 的「框架内置规则索引」了解框架规则，再看 `.agents/PROJECT.md` 的「规则索引」了解项目业务规则
|
||
2. 涉及特定模块开发时，查找该模块是否有对应的规则文件
|
||
3. 用户提到某个模块有特殊约束时，查找对应规则
|
||
|
||
## 维护规则
|
||
|
||
- 规则内容变更时，同步更新文件内容和索引中的说明列
|
||
- 规则过期时，标记为"已废弃"或直接删除，并从索引中移除
|
||
- 框架更新时，只操作 `ulthon-` 前缀的规则文件与 AGENTS.md 的索引，不动 `project-` 前缀的文件与 PROJECT.md 的索引
|
||
- 项目业务规则维护时，只操作 `project-` 前缀的规则文件与 PROJECT.md 的索引，不动 `ulthon-` 前缀的文件与 AGENTS.md 的索引
|
||
|
||
## 索引格式
|
||
|
||
索引表统一使用以下格式（3 列；"来源"通过文件名前缀 `ulthon-`/`project-` 已表达，不单列）：
|
||
|
||
```markdown
|
||
| 规则文件 | 作用域 | 说明 |
|
||
|---------|--------|------|
|
||
| [ulthon-timer-multi-node.md](./.agents/rules/ulthon-timer-multi-node.md) | 定时任务相关 | 多节点协调规则 |
|
||
| [project-order-stock-lock.md](./.agents/rules/project-order-stock-lock.md) | 订单模块 | 库存锁定规则 |
|
||
```
|
||
|
||
链接路径以索引文件自身位置为基准写相对路径：
|
||
- AGENTS.md 在项目根目录，用 `./.agents/rules/...`
|
||
- PROJECT.md 在 `.agents/`，用 `./rules/...`
|
||
|