ok

2026-05-29 11:21:40 +08:00
parent 5d6d482efe
commit f71a5c59af
447 changed files with 32245 additions and 116 deletions
--- a/plans/docker_环境_cursor_规则_ae19913d.plan.md
+++ b/plans/docker_环境_cursor_规则_ae19913d.plan.md
@@ -0,0 +1,121 @@
+---
+name: Docker 环境 Cursor 规则
+overview: 建议把 Docker 开发环境信息写成 Cursor 规则，但单独一条、尽量简短；优先放在 slot 项目级规则，只有跨多个仓库共用同一套 Docker 时才放到用户级规则。
+todos:
+  - id: decide-scope
+    content: 确认 Docker 规则放项目级 (slot) 还是用户级 (~/.cursor/rules)
+    status: completed
+  - id: confirm-php-container
+    content: 确认 slot 后端默认容器 php82 与各服务 working_dir
+    status: completed
+  - id: create-dev-rule
+    content: 新建 dev-environment.mdc（15–30 行，含 compose 路径、容器名、端口、exec 示例）
+    status: completed
+isProject: false
+---
+
+# Docker 环境是否写入 Cursor 规则
+
+## 结论
+
+**值得写进 Cursor 规则**，但**不必**和 [`backend-layering.mdc`](/Users/ray/.cursor/rules/backend-layering.mdc) 混在同一条里，也**不必**默认全部塞进「用户级 + alwaysApply」。
+
+原因：Agent 在帮你跑 `php`、`composer`、`artisan`、迁移、单测、连 Redis/MySQL 时，若不知道服务在容器里，常会错误地在宿主机执行，或连错端口（例如 MySQL 映射是 `3309:3306`）。
+
+---
+
+## 用户级 vs 项目级：怎么选
+
+| 放置位置 | 路径 | 适用场景 |
+| --- | --- | --- |
+| **项目级（推荐）** | 例如在 slot 多根工作区根目录建 [`.cursor/rules/dev-environment.mdc`](file:///Users/ray/Documents/project/www/slot/.cursor/rules/dev-environment.mdc) | 只有 slot / `www/slot` 相关仓库用这套 Docker |
+| **用户级** | [`~/.cursor/rules/dev-environment.mdc`](/Users/ray/.cursor/rules/dev-environment.mdc) | 多个不相关项目都共用 [`/Users/ray/Documents/project/docker/docker-compose.yml`](file:///Users/ray/Documents/project/docker/docker-compose.yml) |
+
+你当前用户级只有分层规范一条，且 `alwaysApply: true`。Docker 信息属于**运行环境**，和编码规范是不同关注点：
+
+- **分层规则**：继续 `alwaysApply: true`（跨项目仍有用）
+- **Docker 规则**：建议 `alwaysApply: false`，或仅在 slot 工作区用项目级规则；避免在写前端、文档、Figma 时也占用上下文
+
+当前 slot 工作区下**没有** [`.cursor/rules/`](file:///Users/ray/Documents/project/www/slot/.cursor/rules)，更适合为 slot 单独加一条 `dev-environment.mdc`。
+
+---
+
+## 规则里应写什么（可操作、短）
+
+根据你的 [`docker-compose.yml`](file:///Users/ray/Documents/project/docker/docker-compose.yml)，建议只写 Agent **执行命令时必需** 的信息：
+
+1. **Compose 位置**：`/Users/ray/Documents/project/docker/docker-compose.yml`
+2. **容器名 → 用途**（执行命令用 `docker exec`，不要用宿主机 PHP/CLI）：
+   - `php82` — PHP 8.2（slot 后端主环境，按你实际版本确认）
+   - `php72` — PHP 7.2（若有老项目）
+   - `goMysql` — MySQL 8（容器内 `3306`，宿主机 **`3309`**）
+   - `redis` — `6379`；`goredis` — 宿主机 `6378`
+3. **挂载路径**：宿主机 `/Users/ray/Documents/project` → 容器内 `/app`（项目在容器内路径如 `/app/www/slot/backend`）
+4. **命令约定**（示例，按你项目真实入口改）：
+   - PHP：`docker exec -w /app/www/slot/backend php82 php ...`
+   - Composer / artisan：同样在 `php82` 内、对应 `working_dir` 执行
+   - MySQL CLI：`docker exec -it goMysql mysql -uroot -proot ...`（或注明用宿主机 `127.0.0.1:3309`）
+5. **明确禁止/避免**：不要在 macOS 宿主机直接跑 `php`/`composer`（除非已确认本机也有同版本环境）
+
+**不建议写进规则的内容**：
+
+- 完整 `docker-compose.yml` 复制（冗长、易过期）
+- 所有服务密码细节（compose 里已有；规则里写「以 compose 为准」即可）
+- RabbitMQ、Milvus 等与当前 slot 任务无关的服务（除非经常用到）
+
+---
+
+## 与现有文档的关系
+
+- **Cursor 规则**：给 Agent 的「默认假设」，每次对话自动带上（按 `alwaysApply` / `globs`）
+- **仓库 README / `docs/dev-setup.md`**：给人看的完整说明；规则可写一句「详细步骤见 xxx」
+
+两者可并存：规则 15–30 行，文档可更长。
+
+---
+
+## 建议的规则骨架（项目级示例）
+
+```markdown
+---
+description: Slot 本地 Docker 开发环境（PHP / MySQL / Redis）
+alwaysApply: true
+---
+
+# Local Dev (Docker)
+
+- Compose: `/Users/ray/Documents/project/docker/docker-compose.yml`
+- Host project root: `/Users/ray/Documents/project` → container `/app`
+- Run PHP/Composer/Artisan inside container `php82`, not on macOS host.
+- MySQL: container `goMysql`; from host use `127.0.0.1:3309`.
+- Redis: container `redis`, host port `6379`.
+- Example: `docker exec -w /app/www/slot/backend php82 php artisan ...`
+```
+
+若放在**用户级**，把 `alwaysApply` 改为 `false`，或标题改成「Project docker (ray)」以免污染非 slot 项目。
+
+---
+
+## 推荐决策
+
+```mermaid
+flowchart TD
+  Q[多个仓库共用同一套 Docker?]
+  Q -->|是| UserRule["~/.cursor/rules/dev-environment.mdc\nalwaysApply: false"]
+  Q -->|否 仅 slot| ProjRule["www/slot/.cursor/rules/dev-environment.mdc\nalwaysApply: true 在该工作区"]
+  Both[保留 backend-layering 在用户级 alwaysApply]
+  UserRule --> Both
+  ProjRule --> Both
+```
+
+**对你当前情况**：slot 多仓库工作区 + Docker 在 `project/docker`，**优先项目级规则**；仅当你打开的其他 Cursor 工作区（非 slot）也依赖同一 compose 时，再复制一份到用户级。
+
+---
+
+## 下一步（你确认后可执行）
+
+1. 在 [`www/slot/.cursor/rules/`](file:///Users/ray/Documents/project/www/slot/.cursor/rules) 新建 `dev-environment.mdc`（约 20 行）
+2. 确认 slot 后端默认用 `php82` 还是 `php72`，以及各子服务在容器内的 `working_dir`
+3. 可选：在 [`docs/`](file:///Users/ray/Documents/project/www/slot/docs) 增加 `dev-setup.md` 供人查阅，规则里链过去
+
+无需修改现有的 `backend-layering.mdc`。