mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-09-05 23:35:31 +08:00
docs(rules): 新增文件级覆盖机制规则并修正索引职责互斥
- 新增 ulthon-file-override-mechanism.md:阐述 app/ 覆盖 extend/base/ 的三类机制(视图模板、include 标签、app_file_path)与不支持覆盖的反例清单 - ulthon-base-app-architecture:升格原孤立描述为独立小节"5. 文件级覆盖机制" - ulthon-timer:在 app_file_path 覆盖说明处增加规则引用 - AGENTS.md:登记新规则到框架内置规则索引 - ulthon-rules-manager:修订索引职责(AGENTS.md 仅 ulthon-、PROJECT.md 仅 project-,互斥不重复维护);索引格式从 4 列改为 3 列与项目实际一致;维护规则补充对称约束;泛化"迁移现有内容"章节
This commit is contained in:
@@ -127,21 +127,23 @@ Rules 可包含以下类型的内容:
|
||||
|
||||
新增规则后,必须同步更新两处索引:
|
||||
|
||||
**AGENTS.md(框架级索引)**:
|
||||
在「零散规则」章节的索引表中新增一行(仅 `ulthon-` 前缀的规则)。
|
||||
**AGENTS.md(框架规则索引)**:
|
||||
在「零散规则」章节的「框架内置规则索引」表中新增一行(仅 `ulthon-` 前缀的规则)。
|
||||
|
||||
**PROJECT.md(全量索引)**:
|
||||
在「规则索引」章节的索引表中新增一行(所有前缀的规则)。
|
||||
**PROJECT.md(项目业务规则索引)**:
|
||||
在「规则索引」章节的索引表中新增一行(仅 `project-` 前缀的规则)。
|
||||
|
||||
### 5. 迁移现有内容
|
||||
两个索引职责互斥:`ulthon-` 前缀只进 AGENTS.md,`project-` 前缀只进 PROJECT.md。框架更新(操作 `ulthon-*`)不污染项目业务索引,项目维护(操作 `project-*`)不污染框架索引。
|
||||
|
||||
如果规则内容原本记录在 `PROJECT.md` 的「增量规则记录」章节,迁移后应将该章节的对应内容替换为指向规则文件的引用(而非直接删除,保留历史痕迹)。
|
||||
### 5. 迁移现有内容(如适用)
|
||||
|
||||
如果规则内容原本以其他形式散落记录(如 AGENTS.md / PROJECT.md 的内联描述、聊天记录、issue 等),抽取为独立规则文件后,应在原位置替换为指向规则文件的引用,保留可追溯性。
|
||||
|
||||
## 读取规则
|
||||
|
||||
智能体在以下场景应主动查阅 `.agents/rules/`:
|
||||
|
||||
1. 首次接触项目时,通过 `AGENTS.md` 或 `PROJECT.md` 的索引了解有哪些规则
|
||||
1. 首次接触项目时,先看 `AGENTS.md` 的「框架内置规则索引」了解框架规则,再看 `.agents/PROJECT.md` 的「规则索引」了解项目业务规则
|
||||
2. 涉及特定模块开发时,查找该模块是否有对应的规则文件
|
||||
3. 用户提到某个模块有特殊约束时,查找对应规则
|
||||
|
||||
@@ -149,15 +151,21 @@ Rules 可包含以下类型的内容:
|
||||
|
||||
- 规则内容变更时,同步更新文件内容和索引中的说明列
|
||||
- 规则过期时,标记为"已废弃"或直接删除,并从索引中移除
|
||||
- 框架更新时,只操作 `ulthon-` 前缀的规则文件,不动 `project-` 前缀的文件
|
||||
- 框架更新时,只操作 `ulthon-` 前缀的规则文件与 AGENTS.md 的索引,不动 `project-` 前缀的文件与 PROJECT.md 的索引
|
||||
- 项目业务规则维护时,只操作 `project-` 前缀的规则文件与 PROJECT.md 的索引,不动 `ulthon-` 前缀的文件与 AGENTS.md 的索引
|
||||
|
||||
## 索引格式
|
||||
|
||||
索引表统一使用以下格式:
|
||||
索引表统一使用以下格式(3 列;"来源"通过文件名前缀 `ulthon-`/`project-` 已表达,不单列):
|
||||
|
||||
```markdown
|
||||
| 规则文件 | 来源 | 作用域 | 说明 |
|
||||
|---------|------|--------|------|
|
||||
| ulthon-timer-multi-node.md | 框架 | 定时任务相关 | 多节点协调规则 |
|
||||
| project-order-stock-lock.md | 业务 | 订单模块 | 库存锁定规则 |
|
||||
| 规则文件 | 作用域 | 说明 |
|
||||
|---------|--------|------|
|
||||
| [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/...`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user