From ce8a0c795bdb7d84076d5184d706585a922f32a3 Mon Sep 17 00:00:00 2001 From: augushong Date: Sat, 18 Jul 2026 23:35:04 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20agent=20=E8=A7=84?= =?UTF-8?q?=E5=88=99=E5=B9=B6=E6=96=B0=E5=A2=9E=E9=A1=B9=E7=9B=AE=E7=BA=A6?= =?UTF-8?q?=E6=9D=9F=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/PROJECT.md | 38 +++++-------- .agents/rules/project-business-constraints.md | 24 ++++++++ .agents/rules/project-dev-runtime-deploy.md | 57 +++++++++++++++++++ .agents/skills/ulthon-rules-manager/SKILL.md | 23 +++++++- AGENTS.md | 18 +++++- tests/.phpunit.cache/test-results | 1 + 6 files changed, 134 insertions(+), 27 deletions(-) create mode 100644 .agents/rules/project-business-constraints.md create mode 100644 .agents/rules/project-dev-runtime-deploy.md create mode 100644 tests/.phpunit.cache/test-results diff --git a/.agents/PROJECT.md b/.agents/PROJECT.md index 49f1077..8deeaf0 100644 --- a/.agents/PROJECT.md +++ b/.agents/PROJECT.md @@ -1,34 +1,24 @@ # 项目业务总览（PROJECT） -> 本文件记录项目的业务上下文，帮助智能体快速理解"这个项目在做什么"。 -> 框架使用规则见根目录 `AGENTS.md`。 +> 项目规则入口。框架使用规则见根目录 `AGENTS.md`。 -## 项目定位 +## 项目概述 -（待填写。用一两句话描述项目是做什么的。） +（用简短的语言讲清楚这个项目是做什么的——服务于谁、解决什么问题、核心能力是什么。 -## 核心业务模块 +**以精简为原则，一两段话为宜**。仅在项目确实复杂、需要更多语境时才适当展开。这段话是智能体理解业务语境的起点，请务必填写，不要留空。具体的业务细节（模块清单、约束、技术栈、开发偏好等）请拆分到下方索引的子规则中，本段落只做整体勾勒。 -（待填写。列出主要业务模块及其对应目录。） +示例： -## 业务约束 - -（待填写。框架不涉及但业务必须遵守的规则。） - -## 技术选型与外部依赖 - -（待填写。项目中使用的特殊技术或外部服务。） - -## 开发偏好 - -（待填写。团队或开发者的个性化偏好。） - -## 增量规则记录 - -（待填写。开发过程中补充的业务规则、团队偏好与临时约束。规则应可执行、可复现、可验证。 -如需独立规则文件，参考技能：[ulthon-rules-manager](skills/ulthon-rules-manager/SKILL.md)） +> 本项目是面向 xx 行业经销商的进销存管理系统，核心提供采购、库存、销售、财务对账四大能力，强调多门店协同与移动端审批。基于 ThinkPHP 8 + Layui，采用 Docker 部署。） ## 规则索引 -（待填写。使用者业务规则索引，仅记录 `project-` 前缀的规则。 -框架内置规则（`ulthon-` 前缀）见 `AGENTS.md` 的「零散规则」章节。） +本项目业务规则（`project-` 前缀）。框架内置规则（`ulthon-` 前缀）见 `AGENTS.md` 的「零散规则」章节。 + +> 以下为建议的子规则项，按项目实际情况增删。`project-dev-runtime-deploy.md` 为每个项目必备项，其余按需创建。无实际内容的子规则可保留模板骨架或删除。 + +| 规则文件 | 作用域 | 说明 | +|---------|--------|------| +| [project-dev-runtime-deploy.md](./rules/project-dev-runtime-deploy.md) | 全局 | 本项目开发/运行/部署的实际模式（必备） | +| [project-business-constraints.md](./rules/project-business-constraints.md) | 全局 | 不可协商的业务硬约束（可选，有则记） | diff --git a/.agents/rules/project-business-constraints.md b/.agents/rules/project-business-constraints.md new file mode 100644 index 0000000..e97f77f --- /dev/null +++ b/.agents/rules/project-business-constraints.md @@ -0,0 +1,24 @@ +# 业务约束 + +> 来源：使用者业务（project-） +> 作用域：全局（业务逻辑实现） +> 触发条件：智能体实现或修改业务逻辑前 + +本项目业务层面的**硬约束**——不可协商的业务铁律。这些约束散落在代码逻辑中，智能体无法从代码结构直接推断，必须显式记录。 + +## 约束清单 + +（**只记录不可协商的业务铁律**——违反会导致数据损坏、资损或安全事故的约束。不要记录业务流程描述、状态机、字段清单等易变内容，这些在代码中已有，记录后容易脱节。 + +每条应可执行、可验证。示例： + +- 库存扣减必须在数据库事务内完成，不允许超卖 +- 支付回调必须验证签名后再处理 + +按项目实际情况增删。无硬约束时可保留本文件为空或删除本文件。） + +## 相关数据表 + +（约束涉及的核心数据表，便于智能体定位。 + +示例：`ul_order`、`ul_order_item`、`ul_stock_log`。） diff --git a/.agents/rules/project-dev-runtime-deploy.md b/.agents/rules/project-dev-runtime-deploy.md new file mode 100644 index 0000000..9cf6fff --- /dev/null +++ b/.agents/rules/project-dev-runtime-deploy.md @@ -0,0 +1,57 @@ +# 本项目开发/运行/部署模式 + +> 来源：使用者业务（project-） +> 作用域：全局环境操作（命令执行、调试、部署、运行环境判断） +> 触发条件：智能体执行命令、调试、部署、判断运行环境前 + +本项目实际采用的开发、运行、部署模式。**完全开放记录，不限于框架预设的 stack**——实际项目可能使用 WAMP、宝塔面板、lnmp 一键包、Docker、源码直传等各种方式，按实际情况描述即可。 + +框架级通用判断规则见 [ulthon-deploy-environment.md](./ulthon-deploy-environment.md)（教智能体如何判断部署栈模式），本文件记录的是"**本项目实际选了哪种**"。 + +## 开发方式 + +（描述本项目的开发模式。例如： + +- 本地 WAMP / XAMPP + 直接修改代码 +- 宿主机 PHP + composer + `php think run` 内置服务器 +- Docker 开发镜像 + bind mount 挂载源码 +- 宝塔面板 + FTP 上传修改 +- 其他任何方式 + +复杂场景可展开多段说明，如开发环境依赖、数据库初始化方式、前端构建流程等。） + +## 运行方式 + +（描述本项目实际如何运行。例如： + +- `php think run` 内置服务器（开发期） +- nginx + php-fpm +- Apache + mod_php +- docker run / docker compose +- 宝塔站点配置 +- 其他 + +如有多环境差异（开发/测试/生产运行方式不同），分别说明。） + +## 部署方式 + +（描述本项目如何部署到生产环境。例如： + +- 源码 `git pull` + `composer install` +- Docker 镜像打包分发 +- rsync 同步代码 +- 宝塔一键部署 / FTP 上传 +- OSS 静态资源 + 源码后端分离部署 +- 其他 + +如涉及数据库迁移、静态资源发布、定时任务部署等，一并说明。） + +## 相关规则 + +- 框架级部署判断规则：[ulthon-deploy-environment.md](./ulthon-deploy-environment.md) + +## 维护说明 + +- 本文件为 `project-` 前缀，不被框架更新（`admin:update`）影响 +- 模式变更时及时更新本文件，避免智能体用过期信息执行命令 +- 若某一章节内容过于复杂（如部署涉及多套流程），可拆分为独立子规则文件（如 `project-deploy-detail.md`），并在本文件中引用 diff --git a/.agents/skills/ulthon-rules-manager/SKILL.md b/.agents/skills/ulthon-rules-manager/SKILL.md index e470993..4721285 100644 --- a/.agents/skills/ulthon-rules-manager/SKILL.md +++ b/.agents/skills/ulthon-rules-manager/SKILL.md @@ -27,6 +27,21 @@ Rules 可包含以下类型的内容： **灰色地带处理**：部分内容混合了规则和操作（如 Base/App 架构文档既有铁律又有场景指南），此时保留为 Skill，因为其核心价值在"指导如何操作"。 +## 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`），并在原文件中引用指向。 + ## 目录结构 ``` @@ -84,9 +99,15 @@ Rules 可包含以下类型的内容： - 开发过程中发现了可复用的约定，值得记录 - 用户明确要求"记录这条规则"/"这个模块有约束" +**判断标准——什么适合做规则**： +- ✅ 适合：稳定的约束、约定、设计决策（选定后很少变化，代码中无直接对应） +- ❌ 不适合：易变的状态描述（模块清单、依赖列表、技术栈清单等）——这些在代码/配置中已有，智能体需要时自行读取，强行记录只会导致规则与代码脱节 + 不满足条件时： - 如果是全局性规则 → 记录到 `AGENTS.md`（需框架作者身份确认） -- 如果是项目业务概述 → 记录到 `.agents/PROJECT.md` +- 如果是项目整体定位 → 记录到 `.agents/PROJECT.md` 的「项目概述」段落（保持精简） +- 如果是易变的状态描述（模块清单、依赖列表等）→ **不记录为规则**，让智能体从代码/配置中读取 +- 如果是稳定的业务硬约束或模式决策 → 创建 `project-*` 子规则文件，并在 PROJECT.md 的索引中登记 ### 2. 确定命名与来源 diff --git a/AGENTS.md b/AGENTS.md index 7e9513a..8fc724a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,11 +2,25 @@ - `AGENTS.md`（本文件）：协作规则入口与导航 - `.agents/`：工作流（skills）、零散规则（rules）与补充文档 -- `.agents/PROJECT.md`：项目业务总览（定位、核心模块、业务约束），由开发者按项目实际情况编写，智能体首次接触项目时应主动读取 +- `.agents/PROJECT.md`：项目业务总览（项目概述 + 业务规则索引），由开发者按项目实际情况编写；本文件管"怎么用框架"，PROJECT.md 管"这个项目在做什么业务、怎么跑、怎么部署" - `.agents/rules/`：模块级/场景级零散规则，按文件独立存放（详见「零散规则」章节） - `.agents/skills/`：按场景调用的工作流技能，统一以 `*/SKILL.md` 为准（详见「工作流」章节） - 标准开发流程：见「标准开发流程」表格，操作细节见对应技能文件 +## 规则导航 + +本项目规则分两层，智能体进入项目时应先了解全局： + +- **框架规则**（`ulthon-` 前缀）：本文件 + `.agents/rules/ulthon-*`，管"怎么用框架" +- **项目规则**（`project-` 前缀）：`.agents/PROJECT.md` + `.agents/rules/project-*`，管"这个项目在做什么业务、怎么开发/运行/部署" + +两层规则缺一不可。本文件提供框架通用约束，但具体项目的业务语境、实际采用的技术栈与部署模式，都以 PROJECT.md 及其索引的业务规则为准。涉及业务逻辑或环境操作前，应先查阅 PROJECT.md。 + +完整索引位置： +- 框架内置规则索引：见本文件「零散规则」章节 +- 项目业务规则索引：见 `.agents/PROJECT.md` 的「规则索引」章节 + +涉及具体模块/场景前，先查阅对应索引，确认是否有专属规则。 ## 项目级规则（最高优先级 / 唯一权威） @@ -67,7 +81,7 @@ ## 规则维护机制 - **框架基础规则**：`AGENTS.md`（本文件）+ `.agents/rules/ulthon-*` 为唯一权威；默认不随任务动态增长 -- **使用者补充规则**：`.agents/PROJECT.md` + `.agents/rules/project-*`，由开发者维护 +- **使用者补充规则**：`.agents/PROJECT.md`（项目概述 + 规则索引）+ `.agents/rules/project-*`（具体业务规则），由开发者维护 - **维护约束**：框架作者新增/调整规则前须与开发者确认；使用者身份发现需记录的约束时，优先记录到对应位置 - **管理技能**：[ulthon-rules-manager](./.agents/skills/ulthon-rules-manager/SKILL.md) diff --git a/tests/.phpunit.cache/test-results b/tests/.phpunit.cache/test-results new file mode 100644 index 0000000..b2e32e5 --- /dev/null +++ b/tests/.phpunit.cache/test-results @@ -0,0 +1 @@ +{"version":1,"defects":[],"times":{"tests\\Feature\\IsolationSmokeTest::test_isolation_probe_rolls_back":0.048,"tests\\Feature\\IsolationSmokeTest::test_refuses_non_test_database":0.004}} \ No newline at end of file