From c5ebf86ad9f01d936e36f89feeeebef56a50af23 Mon Sep 17 00:00:00 2001 From: augushong Date: Mon, 1 Jun 2026 21:48:27 +0800 Subject: [PATCH] =?UTF-8?q?refactor(rules):=20=E7=B2=BE=E7=AE=80=20AGENTS.?= =?UTF-8?q?md=EF=BC=8C=E4=B8=8B=E6=B2=89=E6=A8=A1=E5=9D=97=E7=BA=A7?= =?UTF-8?q?=E8=A7=84=E5=88=99=EF=BC=8C=E8=BF=81=E7=A7=BB=20skill=20?= =?UTF-8?q?=E4=B8=BA=20rule?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .agents/rules/ulthon-controller-url.md | 46 ++++++++++++++++ .agents/rules/ulthon-deploy-environment.md | 23 ++++++++ .agents/rules/ulthon-source-directory.md | 25 +++++++++ .../skills/tp-controller-url-rules/SKILL.md | 53 ------------------- .agents/skills/ulthon-rules-manager/SKILL.md | 20 ++++++- AGENTS.md | 31 ++++------- 6 files changed, 123 insertions(+), 75 deletions(-) create mode 100644 .agents/rules/ulthon-controller-url.md create mode 100644 .agents/rules/ulthon-deploy-environment.md create mode 100644 .agents/rules/ulthon-source-directory.md delete mode 100644 .agents/skills/tp-controller-url-rules/SKILL.md diff --git a/.agents/rules/ulthon-controller-url.md b/.agents/rules/ulthon-controller-url.md new file mode 100644 index 0000000..a77f086 --- /dev/null +++ b/.agents/rules/ulthon-controller-url.md @@ -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` 中手动定义路由规则 diff --git a/.agents/rules/ulthon-deploy-environment.md b/.agents/rules/ulthon-deploy-environment.md new file mode 100644 index 0000000..53f31bb --- /dev/null +++ b/.agents/rules/ulthon-deploy-environment.md @@ -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` 了解所有可用模式及其说明。 diff --git a/.agents/rules/ulthon-source-directory.md b/.agents/rules/ulthon-source-directory.md new file mode 100644 index 0000000..11d9a1e --- /dev/null +++ b/.agents/rules/ulthon-source-directory.md @@ -0,0 +1,25 @@ +# source/ 目录约定 + +> 来源：框架内置（ulthon-） +> 作用域：所有涉及 source/ 目录的操作 +> 触发条件：新增子项目、存放多端代码、管理部署配套文件时加载 + +## 定位 + +`source/` 是主工程之外的配套内容统一目录，不影响当前主工程运行与发布。包括： + +- 多端代码（客户端、大屏端等） +- 子项目工程（可为 PHP 或其他技术栈） +- 项目资料、附件 +- 部署配套文件 + +## 目录约定 + +- 各子目录（客户端、大屏端、各类子项目等）独立管理 +- 若子目录下存在 `AGENTS.md`，则该子工程规则以该文件为准 +- 目录约定与安全要求见 `source/README.md` + +## 安全要求 + +- 禁止提交构建产物 +- 禁止提交依赖目录（node_modules、vendor 等） diff --git a/.agents/skills/tp-controller-url-rules/SKILL.md b/.agents/skills/tp-controller-url-rules/SKILL.md deleted file mode 100644 index ba0e033..0000000 --- a/.agents/skills/tp-controller-url-rules/SKILL.md +++ /dev/null @@ -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` 中手动定义路由规则，以提供更友好的访问地址。 - diff --git a/.agents/skills/ulthon-rules-manager/SKILL.md b/.agents/skills/ulthon-rules-manager/SKILL.md index b694fd0..e470993 100644 --- a/.agents/skills/ulthon-rules-manager/SKILL.md +++ b/.agents/skills/ulthon-rules-manager/SKILL.md @@ -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，因为其核心价值在"指导如何操作"。 ## 目录结构 diff --git a/AGENTS.md b/AGENTS.md index d3a12cf..fd88095 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,13 +43,8 @@ ### 其他规则 -- 数据库：表结构优先 Scheme（`app/admin/scheme/`）；避免 ENUM；tools:db 用于调试，不用于“设计表结构” +- 数据库：表结构优先 Scheme（`app/admin/scheme/`）；避免 ENUM；tools:db 用于调试，不用于"设计表结构" - 前端：视图与脚本同名配对（`*.html` + 同名 `*.js`），并按模块维护 `_common.js` -- 主工程之外的配套内容统一放在 `source/`：包括多端代码、子项目工程（可为 PHP 或其他技术栈）、项目资料、附件与部署配套文件；不影响当前主工程运行与发布；目录约定与安全要求见 `source/README.md`（禁止提交构建产物、依赖目录等） -- `source/` 下各子目录（客户端、大屏端、各类子项目等）：若目录下存在 `AGENTS.md`，则该子工程规则以该文件为准 -- 部署栈模式：`source/stack/` 为模式文件统一目录（含 `default/` 与各模式目录）；`default/` 必须与代码库默认行为一致；默认行为相关文件变更时需同步更新 `source/stack/default/` 对应文件 -- 命令执行环境：执行 `php think` 命令前，需判断当前运行模式（Docker 模式下宿主机可能没有 PHP，不能依赖 `php think` 来检测）。判断方式：检查仓库根目录是否存在 `docker-compose.yaml` — 存在则为 Docker 模式；也可读取 `source/stack/stack.json` 了解所有可用模式及其说明。Docker 模式下所有 `php think` 命令前缀改为 `docker compose exec ulthon_admin`（如 `docker compose exec ulthon_admin php think tools:http:call`）；非 Docker 模式直接在宿主机执行 -- 零散规则：特定模块/场景的约束存放在 `.agents/rules/`（详见「零散规则」章节），新增/维护规则见技能：[ulthon-rules-manager](./.agents/skills/ulthon-rules-manager/SKILL.md) - 权限：基于 `auth` 注解生成节点与鉴权；以角色为中心管理（角色、角色权限、用户角色）；命令行使用见技能：[ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md) - 临时文件：智能体在任务中产生的临时文件（脚本、日志、缓存、产物等）统一输出到 `runtime/agents/`（可按智能体/任务再分子目录），不要放在仓库根目录；除非任务明确要求或框架约定位置属于根目录 - 调试与验证：优先使用框架内置命令行工具（tools:http:call、tools:db:*、tools:log:*、admin:menu:*、admin:permission:*），不需要借助外部数据库 MCP 或临时脚本 @@ -69,30 +64,27 @@ | 7. 功能配套 | 菜单（`admin:menu:*`）、权限节点（`admin:permission:nodes`）、角色分配 | [ulthon-admin-menu-cli](./.agents/skills/ulthon-admin-menu-cli/SKILL.md)、[ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md) | | 8. 最终检查 | 页面路径可用、命令行验证通过、代码规范自查 | - | -## 规则维护机制（框架基础 / 使用者补充） +## 规则维护机制 -本仓库的规则分两类： - -- **框架基础规则（稳定）**：根目录 `AGENTS.md`（本文件）中的「项目级规则」为唯一权威；默认不随任务动态增长。 -- **使用者补充规则（业务侧）**：开发中用户/开发者补充的“项目规则/团队偏好/临时约束”，统一记录到 [.agents/PROJECT.md](./.agents/PROJECT.md)。 - -维护约束（必须遵守）： - -- 智能体以“框架作者”身份开发时，如需新增/调整规则，必须先与开发者确认是否记录、记录位置与具体写法，并按确认结果落到对应规则文件。 -- 智能体以“使用框架的开发者”身份执行任务时，如发现需要记录或调整的项目约束，应更新到对应规则文件（业务侧约束优先记录到 `.agents/PROJECT.md` 的「增量规则记录」章节），并可按开发者要求随时调整。 +- **框架基础规则**：`AGENTS.md`（本文件）+ `.agents/rules/ulthon-*` 为唯一权威；默认不随任务动态增长 +- **使用者补充规则**：`.agents/PROJECT.md` + `.agents/rules/project-*`，由开发者维护 +- **维护约束**：框架作者新增/调整规则前须与开发者确认；使用者身份发现需记录的约束时，优先记录到对应位置 +- **管理技能**：[ulthon-rules-manager](./.agents/skills/ulthon-rules-manager/SKILL.md) ## 零散规则 -针对特定模块/场景的约束，不适合在全局展开，存放在 `.agents/rules/` 目录下，每条规则一个独立文件。 +模块级/场景级的专属知识（约束、约定、设计决策），不适合在全局展开，存放在 `.agents/rules/` 目录下，每条规则一个独立文件。 - 命名约定：`ulthon-` 前缀为框架内置规则，`project-` 前缀为使用者业务规则 -- 管理技能：[ulthon-rules-manager](./.agents/skills/ulthon-rules-manager/SKILL.md) ### 框架内置规则索引 | 规则文件 | 作用域 | 说明 | |---------|--------|------| -| [ulthon-timer-multi-node.md](./.agents/rules/ulthon-timer-multi-node.md) | 定时任务相关 | 多节点协调规则 | +| [ulthon-controller-url.md](./.agents/rules/ulthon-controller-url.md) | 控制器路由 | URL 与控制器/方法的映射规则 | +| [ulthon-deploy-environment.md](./.agents/rules/ulthon-deploy-environment.md) | 部署与命令执行 | 部署栈模式与 Docker/宿主机命令判断 | +| [ulthon-source-directory.md](./.agents/rules/ulthon-source-directory.md) | source/ 目录 | 子项目/多端代码的目录约定与安全要求 | +| [ulthon-timer-multi-node.md](./.agents/rules/ulthon-timer-multi-node.md) | 定时任务相关 | 多节点协调规则与设计 | > 使用者业务规则索引见 `.agents/PROJECT.md` 的「规则索引」章节。 @@ -113,7 +105,6 @@ Skills 是"按场景调用的工作流说明"，统一以 `.agents/skills/*/SKIL - 登录认证（Session + Token）：[ulthon-auth-session-token](./.agents/skills/ulthon-auth-session-token/SKILL.md) - 权限与角色管理（RBAC CLI）：[ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md) - 菜单管理（admin:menu:\* CLI）：[ulthon-admin-menu-cli](./.agents/skills/ulthon-admin-menu-cli/SKILL.md) -- ThinkPHP 控制器 URL 规则：[tp-controller-url-rules](./.agents/skills/tp-controller-url-rules/SKILL.md) ## 智能体指导