ulthon_admin/.agents/rules/ulthon-deploy-environment.md

部署环境与命令执行

来源：框架内置（ulthon-） 作用域：部署配置、命令执行环境判断 触发条件：执行 php think 命令、配置部署模式、切换运行环境时加载

部署栈模式

• source/stack/ 为模式文件统一目录（含 default/ 与各模式目录）
• default/ 必须与代码库默认行为一致
• 默认行为相关文件变更时需同步更新 source/stack/default/ 对应文件

运行模式判断（B-route 工作流）

执行 php think 命令前，必须先判断当前运行模式。B-route 工作流下，模式由"当前所在目录"决定，不再覆盖仓库根目录。

判断方式：检查仓库根目录是否含 Docker 文件（Dockerfile / docker-compose.yaml）。

• 根目录无 Docker 文件（default 模式）：宿主机直接执行 php think。
  • 默认基线行为是 php think run（ThinkPHP 内置服务器）。
  • 启动开发服务器：在仓库根目录执行 php think run。
• 需要 Docker 模式：进入对应模式目录启动栈。
  • 启动：cd source/stack/<mode> 后 docker compose up -d。
  • 模式目录内的 docker-compose.yaml 是该模式的栈定义，bind mount 通常指向仓库根目录。
  • 在容器外执行 php think：docker compose -f source/stack/<mode>/docker-compose.yaml exec <service> php think ...，或在模式目录内 docker compose exec <service> php think ...。
  • 示例：docker compose -f source/stack/docker-dev/docker-compose.yaml exec ulthon_admin php think tools:http:call。
• 可用模式见 source/stack/README.md（default / docker-serve / docker-dev / docker-dev-sync / full / author 等）。
• 判断技巧：如果不确定当前是否处于容器内，看 pwd 是否在仓库根、根目录有无 Dockerfile、docker ps 是否有相关容器在跑。容器内执行 php think 不需要前缀。

记录义务

当开发者确定/选择了项目的运行方式（无论是否使用框架预设的 stack 模式），智能体应当确认 .agents/rules/project-dev-runtime-deploy.md 中是否已记录该选择。如果未记录或内容仍为模板占位符，提醒开发者补充或协助填写。

记录内容不限定格式，开发者用一两句话写清楚"本项目用 xxx 方式运行"即可，无需详细参数列表。但必须包含两个关键信息：

1. 命令执行方式——即 php think 等命令应当在哪里执行。例如：

   • Docker 模式：命令在容器内执行（docker compose exec <service> php think ...），不是宿主机直接 php think
   • 宿主机模式：命令直接在仓库根目录执行
   • 宝塔/其他：按实际环境的执行路径记录

2. 非默认端口——如果修改了框架模板的默认端口（如 HTTP 8000、MySQL 13306、Redis 16379 等），必须记录实际端口。否则智能体调试时（如 tools:http:call）会用默认端口连接，导致失败。

目的是让后续会话中的智能体能从规则文件快速了解项目的实际运行方式、命令执行入口和访问地址，而不需要重新询问或猜测。

多环境 .env 管理

ThinkPHP 通过仓库根目录的 .env 文件读取环境配置（数据库连接、调试开关等）。多环境（测试 / 演示 / 正式等）的做法是：

• 各环境的配置文件都放在仓库根目录，命名为 .env.<环境>（如 .env.test、.env.prod、.env.demo）
• .env 是当前生效的文件，不提交到 git（已在 .gitignore 中排除）
• 部署时通过流水线（CI/CD）将目标环境的文件覆盖为 .env，例如 cp .env.prod .env

代码完全一样，只有 .env 不同。