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:
augushong
2026-07-19 00:30:05 +08:00
parent 073172473b
commit 46f0d62852
5 changed files with 130 additions and 14 deletions

View File

@@ -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/...`