docs: 更新 agent 规则并新增项目约束文档

.agents/PROJECT.md

@@ -1,34 +1,24 @@
 # 项目业务总览（PROJECT）
 
-> 本文件记录项目的业务上下文，帮助智能体快速理解"这个项目在做什么"。
+> 项目规则入口。框架使用规则见根目录 `AGENTS.md`。
-> 框架使用规则见根目录 `AGENTS.md`。
 
-## 项目定位
+## 项目概述
 
-（待填写。用一两句话描述项目是做什么的。）
+（用简短的语言讲清楚这个项目是做什么的——服务于谁、解决什么问题、核心能力是什么。
 
-## 核心业务模块
+**以精简为原则，一两段话为宜**。仅在项目确实复杂、需要更多语境时才适当展开。这段话是智能体理解业务语境的起点，请务必填写，不要留空。具体的业务细节（模块清单、约束、技术栈、开发偏好等）请拆分到下方索引的子规则中，本段落只做整体勾勒。
 
-（待填写。列出主要业务模块及其对应目录。）
+示例：
 
-## 业务约束
+> 本项目是面向 xx 行业经销商的进销存管理系统，核心提供采购、库存、销售、财务对账四大能力，强调多门店协同与移动端审批。基于 ThinkPHP 8 + Layui，采用 Docker 部署。）
-
-（待填写。框架不涉及但业务必须遵守的规则。）
-
-## 技术选型与外部依赖
-
-（待填写。项目中使用的特殊技术或外部服务。）
-
-## 开发偏好
-
-（待填写。团队或开发者的个性化偏好。）
-
-## 增量规则记录
-
-（待填写。开发过程中补充的业务规则、团队偏好与临时约束。规则应可执行、可复现、可验证。
-如需独立规则文件，参考技能：[ulthon-rules-manager](skills/ulthon-rules-manager/SKILL.md)）
 
 ## 规则索引
 
-（待填写。使用者业务规则索引，仅记录 `project-` 前缀的规则。
+本项目业务规则（`project-` 前缀）。框架内置规则（`ulthon-` 前缀）见 `AGENTS.md` 的「零散规则」章节。
-框架内置规则（`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) | 全局 | 不可协商的业务硬约束（可选，有则记） |

.agents/rules/project-business-constraints.md

@@ -0,0 +1,24 @@
+# 业务约束
+
+> 来源：使用者业务（project-）
+> 作用域：全局（业务逻辑实现）
+> 触发条件：智能体实现或修改业务逻辑前
+
+本项目业务层面的**硬约束**——不可协商的业务铁律。这些约束散落在代码逻辑中，智能体无法从代码结构直接推断，必须显式记录。
+
+## 约束清单
+
+（**只记录不可协商的业务铁律**——违反会导致数据损坏、资损或安全事故的约束。不要记录业务流程描述、状态机、字段清单等易变内容，这些在代码中已有，记录后容易脱节。
+
+每条应可执行、可验证。示例：
+
+- 库存扣减必须在数据库事务内完成，不允许超卖
+- 支付回调必须验证签名后再处理
+
+按项目实际情况增删。无硬约束时可保留本文件为空或删除本文件。）
+
+## 相关数据表
+
+（约束涉及的核心数据表，便于智能体定位。
+
+示例：`ul_order`、`ul_order_item`、`ul_stock_log`。）

.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`），并在本文件中引用

.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. 确定命名与来源
 

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)
 

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}}