refactor(rules): 精简 AGENTS.md,下沉模块级规则,迁移 skill 为 rule

- 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
This commit is contained in:
augushong
2026-06-01 21:48:27 +08:00
parent 6d2963a9a4
commit c5ebf86ad9
6 changed files with 123 additions and 75 deletions

View File

@@ -0,0 +1,46 @@
# ThinkPHP 8 控制器 URL 访问规则
> 来源框架内置ulthon-
> 作用域所有涉及控制器路由、URL 构造的场景
> 触发条件:编写/调试控制器路由、URL 报错、配置路由时加载
## 大驼峰命名转换规则
ThinkPHP 8 默认开启 URL 自动转换(`url_convert`。大驼峰命名CamelCase的控制器和方法在 URL 中转换为小写+下划线snake_case
- **控制器类名**`UserGroup` -> URL`user_group`
- **操作方法名**`public function editInfo()` -> URL`edit_info`
示例:控制器 `app\admin\controller\UserGroup.php` 中的 `editInfo` 方法:
访问路径:`/admin/user_group/edit_info`
## 多级控制器访问规则
控制器存放在子目录中时URL 使用 `.`(点号)连接目录名和控制器名。
- **目录结构**`app/admin/controller/system/Config.php`
- **访问路径**`/admin/system.config/index`
注意:
- 子目录名建议使用全小写
- 如果子目录名也是大驼峰,同样遵循转换规则
## 混合使用示例
| 控制器文件路径 | 类名 | 方法名 | 对应 URL 路径 |
|---|---|---|---|
| `controller/Index.php` | `Index` | `index` | `/admin/index/index` |
| `controller/UserGroup.php` | `UserGroup` | `add` | `/admin/user_group/add` |
| `controller/system/Admin.php` | `Admin` | `login` | `/admin/system.admin/login` |
| `controller/mall/GoodsCate.php` | `GoodsCate` | `getList` | `/admin/mall.goods_cate/get_list` |
## 常见问题排查
- **404 错误**:检查是否漏掉了多级控制器的 `.` 分隔符
- **大小写敏感**URL 无法识别下划线时,检查 `config/route.php``url_convert` 是否为 `false`
- **多应用影响**多应用模式下URL 第一段是应用名(如 `admin`),后续才是控制器和方法
## 开发者建议
- 代码中使用大驼峰命名,前端请求/模板链接中明确指向转换后的路径,或使用系统助手函数自动生成
- 复杂 URL 建议在 `route/*.php` 中手动定义路由规则

View File

@@ -0,0 +1,23 @@
# 部署环境与命令执行
> 来源框架内置ulthon-
> 作用域:部署配置、命令执行环境判断
> 触发条件:执行 php think 命令、配置部署模式、切换运行环境时加载
## 部署栈模式
- `source/stack/` 为模式文件统一目录(含 `default/` 与各模式目录)
- `default/` 必须与代码库默认行为一致
- 默认行为相关文件变更时需同步更新 `source/stack/default/` 对应文件
## 运行模式判断
执行 `php think` 命令前,必须先判断当前运行模式。
**判断方式**:检查仓库根目录是否存在 `docker-compose.yaml`
- **存在**Docker 模式。宿主机可能没有 PHP不能依赖 `php think` 来检测。所有 `php think` 命令前缀改为 `docker compose exec ulthon_admin`
- 示例:`docker compose exec ulthon_admin php think tools:http:call`
- **不存在**:宿主机模式。直接执行 `php think`
也可读取 `source/stack/stack.json` 了解所有可用模式及其说明。

View File

@@ -0,0 +1,25 @@
# source/ 目录约定
> 来源框架内置ulthon-
> 作用域:所有涉及 source/ 目录的操作
> 触发条件:新增子项目、存放多端代码、管理部署配套文件时加载
## 定位
`source/` 是主工程之外的配套内容统一目录,不影响当前主工程运行与发布。包括:
- 多端代码(客户端、大屏端等)
- 子项目工程(可为 PHP 或其他技术栈)
- 项目资料、附件
- 部署配套文件
## 目录约定
- 各子目录(客户端、大屏端、各类子项目等)独立管理
- 若子目录下存在 `AGENTS.md`,则该子工程规则以该文件为准
- 目录约定与安全要求见 `source/README.md`
## 安全要求
- 禁止提交构建产物
- 禁止提交依赖目录node_modules、vendor 等)

View File

@@ -1,53 +0,0 @@
---
name: "tp-controller-url-rules"
description: "解释 ThinkPHP 8 多级控制器与大驼峰控制器的 URL 访问规则。当用户询问如何访问控制器、URL 报错或需要配置路由时调用。"
---
# ThinkPHP 8 控制器 URL 访问规则
本 Skill 指导如何在 ThinkPHP 8 框架中正确访问多级控制器以及采用大驼峰命名的控制器和方法。
## 1. 大驼峰命名转换规则
ThinkPHP 8 默认开启了 URL 自动转换(`url_convert`。大驼峰命名CamelCase的控制器和方法在 URL 中会被转换为小写+下划线snake_case
- **控制器类名**`UserGroup` → URL`user_group`
- **操作方法名**`public function editInfo()` → URL`edit_info`
**示例:**
控制器 `app\admin\controller\UserGroup.php` 中的 `editInfo` 方法:
访问路径:`/admin/user_group/edit_info`
## 2. 多级控制器访问规则
当控制器存放在子目录中时URL 访问需要使用 `.`(点号)来连接目录名和控制器名。
- **目录结构**`app/admin/controller/system/Config.php`
- **访问路径**`/admin/system.config/index`
**注意:**
- 子目录名建议使用全小写。
- 如果子目录名也是大驼峰,同样遵循转换规则(取决于具体配置,但通常建议目录名保持简单)。
## 3. 混合使用示例
结合多级目录和大驼峰命名的复杂情况:
| 控制器文件路径 | 类名 | 方法名 | 对应 URL 路径 |
| :--- | :--- | :--- | :--- |
| `controller/Index.php` | `Index` | `index` | `/admin/index/index` |
| `controller/UserGroup.php` | `UserGroup` | `add` | `/admin/user_group/add` |
| `controller/system/Admin.php` | `Admin` | `login` | `/admin/system.admin/login` |
| `controller/mall/GoodsCate.php` | `GoodsCate` | `getList` | `/admin/mall.goods_cate/get_list` |
## 4. 常见问题排查
- **404 错误**:检查是否漏掉了多级控制器的 `.` 分隔符。
- **大小写敏感**:如果 URL 无法识别下划线,检查 `config/route.php` 中的 `url_convert` 是否被设置为 `false`
- **多应用影响**在多应用模式下URL 的第一段通常是应用名(如 `admin`),后续才是控制器和方法。
## 5. 开发者建议
- **统一风格**:在代码中使用大驼峰命名类和方法,但在前端请求、模板链接(如 `{:url('...')}`)中建议明确指向转换后的路径或使用系统助手函数自动生成。
- **路由定义**:对于复杂的 URL建议在 `route/*.php` 中手动定义路由规则,以提供更友好的访问地址。

View File

@@ -7,9 +7,25 @@ description: "零散规则管理技能。指导智能体在 `.agents/rules/` 目
## 核心概念
**零散规则**是针对特定模块或场景的约束,不适合放在全局 `AGENTS.md` 中展开。它们存放在 `.agents/rules/` 目录下,每条规则一个独立文件,通过索引被智能体发现和引用。
**零散规则Rules** 是模块级/场景级的专属知识,不适合放在全局 `AGENTS.md` 中展开。存放在 `.agents/rules/` 目录下,每条规则一个独立文件,通过索引被智能体发现和引用。
**和 Skills 的区别**Skills 是"按场景调用的工作流说明"怎么做Rules 是"特定模块的约束/约定"(不能怎么做 / 必须遵守什么)。
Rules 可包含以下类型的内容:
- **约束**:不能怎么做、必须怎么做(如命名约定、分层铁律)
- **约定**:惯例、默认行为(如目录结构、文件配对)
- **设计决策**:某个功能的设计方案与背景(如多节点协调方案、认证架构选型)
## Rules 与 Skills 的边界
| 维度 | Rule规则 | Skill技能 |
|------|-------------|---------------|
| 核心问题 | "是什么""不能做什么""为什么这样设计" | "怎么做""一步步如何完成" |
| 知识形态 | 静态声明A 对应 B、禁止 C | 动态流程(第 1 步...第 2 步... |
| 触发时机 | 涉及某模块时需先了解其规则 | 需要执行某操作时按步骤调用 |
| 典型例子 | URL 映射规则、目录约定、多节点设计 | CURD 生成流程、定时任务配置、菜单创建 |
**判断方法**:如果内容主要是"告知性"的(让智能体知道某个事实/约束/设计),放 Rule。如果内容主要是"操作性"的(让智能体按步骤完成某件事),放 Skill。
**灰色地带处理**:部分内容混合了规则和操作(如 Base/App 架构文档既有铁律又有场景指南),此时保留为 Skill因为其核心价值在"指导如何操作"。
## 目录结构