From fc5c592fba2f8660aae5bce0bdcdde64661095ad Mon Sep 17 00:00:00 2001 From: augushong Date: Mon, 7 Sep 2026 23:55:36 +0800 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E5=88=A0=E9=99=A4=E5=BA=9F?= =?UTF-8?q?=E5=BC=83=E6=A8=A1=E6=9D=BF=E6=96=87=E4=BB=B6=EF=BC=8Crules?= =?UTF-8?q?=E7=9B=AE=E5=BD=95=E6=96=87=E6=A1=A3=E6=94=B9=E6=8C=87AGENTS.md?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E4=BF=A1=E6=81=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/PROJECT.md | 25 -------- .agents/rules/.README | 4 +- .agents/rules/project-business-constraints.md | 24 ------- .agents/rules/project-dev-runtime-deploy.md | 63 ------------------- .agents/rules/project-update-strategy.md | 42 ------------- .agents/rules/ulthon-deploy-environment.md | 4 +- 6 files changed, 4 insertions(+), 158 deletions(-) delete mode 100644 .agents/PROJECT.md delete mode 100644 .agents/rules/project-business-constraints.md delete mode 100644 .agents/rules/project-dev-runtime-deploy.md delete mode 100644 .agents/rules/project-update-strategy.md diff --git a/.agents/PROJECT.md b/.agents/PROJECT.md deleted file mode 100644 index dc56f05..0000000 --- a/.agents/PROJECT.md +++ /dev/null @@ -1,25 +0,0 @@ -# 项目业务总览（PROJECT） - -> 项目规则入口。框架使用规则见根目录 `AGENTS.md`。 - -## 项目概述 - -（用简短的语言讲清楚这个项目是做什么的——服务于谁、解决什么问题、核心能力是什么。 - -**以精简为原则，一两段话为宜**。仅在项目确实复杂、需要更多语境时才适当展开。这段话是智能体理解业务语境的起点，请务必填写，不要留空。具体的业务细节（模块清单、约束、技术栈、开发偏好等）请拆分到下方索引的子规则中，本段落只做整体勾勒。 - -示例： - -> 本项目是面向 xx 行业经销商的进销存管理系统，核心提供采购、库存、销售、财务对账四大能力，强调多门店协同与移动端审批。基于 ThinkPHP 8 + Layui，采用 Docker 部署。） - -## 规则索引 - -本项目业务规则（`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) | 全局 | 不可协商的业务硬约束（可选，有则记） | -| [project-update-strategy.md](./rules/project-update-strategy.md) | 框架更新 | admin:update 执行策略（默认对比更新无需创建，切换到按需手动更新时启用） | diff --git a/.agents/rules/.README b/.agents/rules/.README index 8f5c355..0bfc8fa 100644 --- a/.agents/rules/.README +++ b/.agents/rules/.README @@ -27,8 +27,8 @@ ## 索引 -- 框架级规则索引：根目录 `AGENTS.md` 的「零散规则」章节 -- 全量规则索引：`.agents/PROJECT.md` 的「规则索引」章节 +- 框架规则速览：根目录 `AGENTS.md` 的「其他框架规则」章节 +- 项目规则索引：根目录 `AGENTS.md` 的「项目信息」节 ## 管理技能 diff --git a/.agents/rules/project-business-constraints.md b/.agents/rules/project-business-constraints.md deleted file mode 100644 index e97f77f..0000000 --- a/.agents/rules/project-business-constraints.md +++ /dev/null @@ -1,24 +0,0 @@ -# 业务约束 - -> 来源：使用者业务（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 deleted file mode 100644 index 294757b..0000000 --- a/.agents/rules/project-dev-runtime-deploy.md +++ /dev/null @@ -1,63 +0,0 @@ -# 本项目开发/运行/部署模式 - -> 来源：使用者业务（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/rules/project-update-strategy.md b/.agents/rules/project-update-strategy.md deleted file mode 100644 index 2d73dbf..0000000 --- a/.agents/rules/project-update-strategy.md +++ /dev/null @@ -1,42 +0,0 @@ -# 框架更新策略 - -> 来源：使用者业务（project-） -> 作用域：框架更新流程（admin:update 命令的执行策略） -> 触发条件：智能体执行或协助 admin:update 前 - - - -本项目框架更新（`php think admin:update`）的执行策略记录。用于在标准对比更新不适用时，明确本项目的更新方式。 - -更新命令的通用操作流程见 [ulthon-update-workflow](../skills/ulthon-update-workflow/SKILL.md)。 - -## 当前策略 - -`对比更新` - -（可选值： - -- `对比更新`：标准 `admin:update`。**默认策略，无需创建本文件。** -- `按需手动更新`：使用 `--fetch-only` 拉取上游代码到本地，由 AI 或开发者选择性合并。适用于定制极多、不信任自动冲突策略的项目。 - -## 采用原因 - -（切换到"按需手动更新"时填写。例如：app/ 定制量大、历史上强制覆盖丢失过定制等。未切换则留空。） - -## 注意事项 - -（记录策略层面的长期约束，例如： - -- 已深度定制、上游变更需特别谨慎的文件或目录 -- 合并偏好（如 extend/base/ 一律接受覆盖，定制通过 app/ 扩展层实现） - -未切换策略时留空即可。） - -## 相关技能 - -- [ulthon-update-workflow](../skills/ulthon-update-workflow/SKILL.md) diff --git a/.agents/rules/ulthon-deploy-environment.md b/.agents/rules/ulthon-deploy-environment.md index 41acfbe..c5f6303 100644 --- a/.agents/rules/ulthon-deploy-environment.md +++ b/.agents/rules/ulthon-deploy-environment.md @@ -29,7 +29,7 @@ ## 记录义务 -当开发者确定/选择了项目的运行方式（无论是否使用框架预设的 stack 模式），智能体应当确认 `.agents/rules/project-dev-runtime-deploy.md` 中是否已记录该选择。如果未记录或内容仍为模板占位符，提醒开发者补充或协助填写。 +当开发者确定/选择了项目的运行方式（无论是否使用框架预设的 stack 模式），智能体应当确认根 `AGENTS.md` 的「项目信息」节是否已记录运行方式。如果未记录，提醒开发者补充或协助填写。 记录内容不限定格式，开发者用一两句话写清楚"本项目用 xxx 方式运行"即可，无需详细参数列表。但必须包含两个关键信息： @@ -40,7 +40,7 @@ 2. **非默认端口**——如果修改了框架模板的默认端口（如 HTTP 8000、MySQL 13306、Redis 16379 等），必须记录实际端口。否则智能体调试时（如 `tools:http:call`）会用默认端口连接，导致失败。 -目的是让后续会话中的智能体能从规则文件快速了解项目的实际运行方式、命令执行入口和访问地址，而不需要重新询问或猜测。 +目的是让后续会话中的智能体能从「项目信息」节快速了解项目的实际运行方式、命令执行入口和访问地址，而不需要重新询问或猜测。 ## 多环境 .env 管理