177 lines
7.5 KiB
Markdown
177 lines
7.5 KiB
Markdown
---
|
||
name: Slot 硬规则落地
|
||
overview: 在用户级 `~/.cursor` 强化分层/PHPDoc 规则为可执行 checklist，并新增 Cursor Hooks：拦截宿主机 php/composer、在 Agent 结束前自动跑仓库校验脚本，未通过则注入 follow-up 要求继续修复。
|
||
todos:
|
||
- id: hooks-scripts
|
||
content: 新建 ~/.cursor/hooks.json、block-host-php.sh、verify-slot-backend.sh 并 chmod +x
|
||
status: completed
|
||
- id: rules-mdc
|
||
content: 扩展 backend-layering.mdc；php-doc alwaysApply；新增 agent-completion-gate.mdc
|
||
status: completed
|
||
- id: plan-dod
|
||
content: 每日返水 plan 追加 Definition of Done（与脚本检查项一致）
|
||
status: completed
|
||
- id: verify-hooks
|
||
content: 手动验证：宿主机 php 拦截、docker php 放行、verify 脚本 PASS/FAIL
|
||
status: in_progress
|
||
isProject: false
|
||
---
|
||
|
||
# Slot 后端硬规则落地
|
||
|
||
## 目标
|
||
|
||
把当前「软约束」升级为三层：
|
||
|
||
| 层级 | 手段 | 效果 |
|
||
|------|------|------|
|
||
| 上下文 | 规则 `alwaysApply` + 完成前 MUST | 每条对话强制可见 |
|
||
| 行为 | Agent 必须跑校验脚本并贴输出 | 可审计、可复查 |
|
||
| 机器 | Cursor Hooks `failClosed` | 违反则阻断或自动续跑修复 |
|
||
|
||
不依赖各 slot 仓库已有 CI（目前无 `.github/workflows`、无 pre-commit），**先落在用户级 `~/.cursor`**，对你当前多根工作区（`slot_console`、`backend/slot_admin` 等）全部生效。
|
||
|
||
## 1. 强化 Cursor Rules（`~/.cursor/rules/`）
|
||
|
||
### 1.1 扩展 [backend-layering.mdc](file:///Users/ray/.cursor/rules/backend-layering.mdc)
|
||
|
||
在文末新增 **「Agent 完成前 MUST」**（短、可验证）：
|
||
|
||
- **重命名/删除类**：对本次 diff 中删除的 `*.php`，提取类名，在 `~/Documents/project/www/slot` 下 `rg` 引用数为 **0**。
|
||
- **新建/大改 `app/api/controller/*`**：必须 `extends \slotLib\basic\BaseController`，构造注入对应 `*Logic` + `*Validator`；参照 [FreeCreditsController.php](file:///Users/ray/Documents/project/www/slot/slot_console/app/api/controller/FreeCreditsController.php)。
|
||
- **禁止 Logic 型 Service**：不得新建以单业务用例编排为主、仅转发 Model/Logic 的 `app/service/*Service`（`DailyRebateCalcService` 这类**公共计算**除外）。
|
||
- **声称完成前**：必须执行 `~/.cursor/hooks/verify-slot-backend.sh`，在最终回复粘贴脚本输出（`PASS` 或 `FAIL` 明细）。
|
||
|
||
### 1.2 调整 [php-doc.mdc](file:///Users/ray/.cursor/rules/php-doc.mdc)
|
||
|
||
- `alwaysApply: false` → **`alwaysApply: true`**
|
||
- 在「Agent 执行要求」增加：**最终回复必须含一行 `PHPDoc: checked` 或列出例外文件**
|
||
|
||
与 layering 规则叠加后，PHPDoc 不再因 glob 未命中而漏掉。
|
||
|
||
### 1.3 新增 [agent-completion-gate.mdc](file:///Users/ray/.cursor/rules/agent-completion-gate.mdc)
|
||
|
||
`alwaysApply: true`，仅 15～20 行，避免与 layering 重复：
|
||
|
||
- 引用校验脚本路径与 Hooks 行为
|
||
- 禁止在未跑脚本前写「已完成 / 可以合并」
|
||
- 多仓库任务：脚本会扫描 `slot_*` 与 `backend` 下有 git 的目录
|
||
|
||
## 2. Cursor Hooks（用户级，真正「硬」）
|
||
|
||
新建：
|
||
|
||
- [~/.cursor/hooks.json](file:///Users/ray/.cursor/hooks.json)
|
||
- [~/.cursor/hooks/block-host-php.sh](file:///Users/ray/.cursor/hooks/block-host-php.sh)
|
||
- [~/.cursor/hooks/verify-slot-backend.sh](file:///Users/ray/.cursor/hooks/verify-slot-backend.sh)
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
shell[Agent_Shell_command]
|
||
blockHook[block-host-php.sh]
|
||
edit[PHP_file_edits]
|
||
stop[Agent_stop]
|
||
verify[verify-slot-backend.sh]
|
||
shell --> blockHook
|
||
blockHook -->|deny_naked_php_composer| block[permission_deny]
|
||
blockHook -->|docker_exec| allow[permission_allow]
|
||
stop --> verify
|
||
verify -->|FAIL| followup[followup_message_continue_fix]
|
||
verify -->|PASS| done[session_ends]
|
||
```
|
||
|
||
### 2.1 `beforeShellExecution` — 落实 [dev-environment.mdc](file:///Users/ray/.cursor/rules/dev-environment.mdc)
|
||
|
||
**`block-host-php.sh`**（`failClosed: true`）：
|
||
|
||
- 若命令以 `php` / `composer` 开头且**不包含** `docker exec` → `permission: deny`
|
||
- 允许：`docker exec ... php`、`docker exec ... composer`
|
||
- 其它命令 → `allow`
|
||
|
||
这样宿主机误跑 PHP 会被 Hook **直接拦住**，不依赖模型记忆。
|
||
|
||
### 2.2 `stop` — 分层与调用方收尾
|
||
|
||
**`verify-slot-backend.sh`**（`failClosed: false`，失败时返回 `followup_message` 让 Agent 继续改）：
|
||
|
||
扫描根目录：`/Users/ray/Documents/project/www/slot` 下各子仓库（存在 `.git` 的 `slot_*`、`backend`）：
|
||
|
||
| 检查 | 逻辑 |
|
||
|------|------|
|
||
| 删除类无残留引用 | `git diff --diff-filter=D --name-only` 的 PHP → 解析 `class X` → `rg '\bX\b'` 全 slot 根，非 0 则 FAIL |
|
||
| API Controller 结构 | `git diff --name-only` 命中 `app/api/controller/*.php` → 文件须含 `extends \slotLib\basic\BaseController`（无则 FAIL，除非文件头有 `@layering-exempt`） |
|
||
| 禁止符号回归 | 内置 banlist（首项 `DailyRebateService`），`rg` 命中即 FAIL |
|
||
| 可选轻量 PHPDoc | 对 diff 中新增的 `public function`，上一行非 `/**` 则 WARN（不阻断，避免历史债） |
|
||
|
||
输出格式固定：
|
||
|
||
```
|
||
=== verify-slot-backend ===
|
||
PASS
|
||
```
|
||
|
||
或 `FAIL` + 逐条原因；`stop` hook 解析到 `FAIL` 时返回 `followup_message`：「校验未通过，按明细修复后重跑脚本」。
|
||
|
||
脚本依赖：`bash`、`git`、`rg`（你本机已有）；不依赖 `jq`（用 grep/sed 解析 stdin，降低 hook 环境差异）。
|
||
|
||
### 2.3 `hooks.json` 草案
|
||
|
||
```json
|
||
{
|
||
"version": 1,
|
||
"hooks": {
|
||
"beforeShellExecution": [
|
||
{
|
||
"command": "./hooks/block-host-php.sh",
|
||
"matcher": "^\\s*(php|composer)\\b",
|
||
"failClosed": true
|
||
}
|
||
],
|
||
"stop": [
|
||
{
|
||
"command": "./hooks/verify-slot-backend.sh",
|
||
"failClosed": false
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
路径相对 **`~/.cursor/`**（用户 hook 约定）。创建后 `chmod +x` 两个脚本。
|
||
|
||
**验证步骤**（实施后手动测一次）：
|
||
|
||
1. Agent 尝试 `php -v` → 应被拦截
|
||
2. `docker exec ... php -v` → 应放行
|
||
3. 故意留 `DailyRebateService` 引用 → `stop` 应触发 follow-up
|
||
|
||
## 3. 每日返水 Plan 补 DoD（可选，与硬规则对齐）
|
||
|
||
在 [每日返水活动化改造_dd1575a1.plan.md](file:///Users/ray/.cursor/plans/每日返水活动化改造_dd1575a1.plan.md) 末尾加 **Definition of Done** 小节（与脚本检查项一致），便于人工对照：
|
||
|
||
- `rg DailyRebateService` → 0
|
||
- `DailyRebateController` 对齐 `FreeCreditsController`
|
||
- 删除 orphan `dailyRebateTierConfig/*`
|
||
- `verify-slot-backend.sh` → PASS
|
||
|
||
（仅更新 plan 文档，不执行业务代码。）
|
||
|
||
## 4. 不纳入首期的项（避免过度工程）
|
||
|
||
- 各仓库 CI / pre-commit：可后续把 `verify-slot-backend.sh` 拷到 `scripts/` 进 pipeline
|
||
- `DailyRebateTierValidateService` 迁到 Validate 层：属代码重构，单独 PR
|
||
- `afterFileEdit` 每次保存都跑校验：太吵，先用 `stop` + 规则要求手动跑脚本
|
||
|
||
## 5. 实施顺序
|
||
|
||
1. 写两个 hook 脚本 + `hooks.json`，本地 chmod + 试跑脚本
|
||
2. 改/增三个 `.mdc` 规则文件
|
||
3. 更新每日返水 plan 的 DoD（若你同意）
|
||
4. 重启 Cursor 或确认 Hooks 面板已加载
|
||
|
||
## 风险与说明
|
||
|
||
- **Hooks 是 Cursor 产品能力**：需 Cursor 版本支持 `hooks.json`；若 `stop` 的 stdin 字段与文档不一致，首版脚本以「扫描 git diff」为主，不依赖复杂 JSON 字段。
|
||
- **硬 ≠ 100%**：模型仍可能不写 follow-up 前的脚本输出；`stop` hook 是兜底。二者叠加后明显严于仅 Rules。
|
||
- **多根工作区**：脚本按 `~/Documents/project/www/slot/*/git` 遍历，不依赖当前打开哪个 folder。
|