---
name: Agent 自检报告机制
overview: 通过 **Rule（强制收尾）+ Skill（报告模板与步骤）+ Hook/脚本（可自动化的硬检查）** 三层配合，让 Agent 写完 PHP 后端代码后自动跑检测并输出结构化报告；不是单靠 Skill 或单靠 Hook 就能完全覆盖。
todos:
  - id: create-skill
    content: 新建 ~/.cursor/skills/slot-backend-completion-report/SKILL.md（步骤 + 报告模板；php -l 按工作区/git 仓库动态映射容器 -w，不写死 slot-xxx）
    status: completed
  - id: update-gate-rule
    content: 更新 agent-completion-gate.mdc：收尾必须执行 Skill 并输出检测报告章节
    status: completed
  - id: extend-verify-script
    content: （可选）verify-slot-backend.sh 增加 const 注释检查 + 修复 grep pipefail
    status: completed
  - id: project-copy
    content: （可选）复制 Skill 到 www/ray/.cursor/skills/ 供仓库共享
    status: completed
isProject: false
---

# Agent 写完代码后自动自检出报告：怎么配

## 你现在已经有什么

你其实**已经有一半机制**，只是还没有「结构化报告」这一层：

| 机制 | 文件 | 现在做什么 | 缺什么 |
|------|------|------------|--------|
| **Rule（alwaysApply）** | [`~/.cursor/rules/agent-completion-gate.mdc`](/Users/ray/.cursor/rules/agent-completion-gate.mdc) | 要求收尾前跑 `verify-slot-backend.sh`、回复里贴 `PASS/FAIL`、写 `PHPDoc: checked` | 没规定报告格式（表格、分层检查、语法检查） |
| **Rule** | [`~/.cursor/rules/php-clean-code.mdc`](/Users/ray/.cursor/rules/php-clean-code.mdc) | §8 自查清单（常量注释、Logic 编排等） | 靠 Agent **自觉对照**，脚本不检查 |
| **Hook（stop）** | [`~/.cursor/hooks.json`](/Users/ray/.cursor/hooks.json) → `verify-slot-backend.sh` | Agent **结束时会自动跑**门禁脚本；`FAIL` 会注入 followup 要求继续修 | 只输出 `PASS/FAIL`，不会生成你看到的 Markdown 报告 |
| **脚本** | [`~/.cursor/hooks/verify-slot-backend.sh`](/Users/ray/.cursor/hooks/verify-slot-backend.sh) | 扫 git diff：banlist、BaseController、RuntimeException 等 | **不检查** PHPDoc、常量注释、Vue 改动 |

所以你上面看到的那种报告，主要是 Agent **按 Rule 手动执行 + 人工对照规范**，不是某个 Skill 或 Hook 自动生成的。

```mermaid
flowchart TB
    subgraph now [当前]
        WriteCode[Agent 写代码]
        RuleGate[agent-completion-gate Rule]
        HookStop[stop Hook 跑 verify 脚本]
        ManualReport[Agent 自觉出 Markdown 报告]
        WriteCode --> RuleGate
        WriteCode --> HookStop
        RuleGate --> ManualReport
    end

    subgraph target [目标]
        WriteCode2[Agent 写代码]
        SkillReport[completion-report Skill]
        ScriptHard[verify 脚本硬检查]
        RuleMust[Rule 强制用 Skill 收尾]
        WriteCode2 --> SkillReport
        SkillReport --> ScriptHard
        RuleMust --> SkillReport
        SkillReport --> StructuredReport[固定格式检测报告]
    end
```

---

## 三种方式分别适合什么

### 1. Rule —— 适合「必须做，否则不能说完成」

- **作用**：每次对话都生效，Agent 不能跳过
- **适合写**：「收尾前必须跑 X」「最终回复必须含 Y 格式的报告」
- **不适合**：很长的操作步骤（会占 context、难维护）

你已有 [`agent-completion-gate.mdc`](/Users/ray/.cursor/rules/agent-completion-gate.mdc)，只需**加一条**：收尾章节必须按 `slot-backend-completion-report` Skill 输出。

### 2. Skill —— 适合「怎么做 + 报告长什么样」

- **作用**：Agent 在收尾阶段读取，按步骤跑命令、填模板
- **适合写**：
  - 执行顺序（verify → docker php -l → 对照 §8 自查）
  - **固定报告模板**（就是你上面看到的：门禁脚本 / 语法 / PHPDoc / 分层 / 结论）
  - 按改动类型分支（只改 Vue / 只改 Logic / 改 Model 等）
- **路径建议**：`~/.cursor/skills/slot-backend-completion-report/SKILL.md`（个人全局）或 `www/ray/.cursor/skills/...`（项目共享）

Skill **不会自动执行**，需要 Rule 或用户说「按规范检测」触发。

### 3. Hook + 脚本 —— 适合「能机器判定的硬规则」

- **作用**：Agent 结束时自动跑（你已有 `stop` hook）
- **适合写**：git diff 里新增 `const` 无上一行 `/**`、新增 public 方法无 PHPDoc 等
- **不适合**：Logic 是否编排清晰、命名是否达意（需 Agent 读代码判断）

Hook 只能 **FAIL 并追问**，不能像 Skill 那样输出完整 Markdown 报告。

---

## 推荐方案（三层，不重复造轮子）

### 层 1：新建 Skill（报告模板 + 步骤）

创建 [`~/.cursor/skills/slot-backend-completion-report/SKILL.md`](~/.cursor/skills/slot-backend-completion-report/SKILL.md)，内容包括：

1. **触发**：修改 `app/**/*.php` 或用户说「按规范检测 / 检测代码」
2. **必跑命令**（路径均**动态解析**，禁止写死 `slot-xxx` 或 `/app/www/ray/...`）：
   - **门禁脚本**：`SLOT_ROOT="${SLOT_ROOT:-$WORKSPACE_ROOT}" ~/.cursor/hooks/verify-slot-backend.sh`
     - `SLOT_ROOT` 默认为**当前 Cursor 工作区根目录**（用户可能在 `www/ray`、`www/slot` 等不同 monorepo 根下工作）
   - **PHP 语法检查**（对每个 git diff 中的改动 `.php`）：
     1. 取该文件所在 git 仓库根：`repo=$(git -C "$(dirname "$f")" rev-parse --show-toplevel)`
     2. 宿主机项目挂载根 → 容器根（见 `dev-environment`）：默认 `SLOT_DOCKER_HOST_ROOT=/Users/ray/Documents/project`，`SLOT_DOCKER_CONTAINER_ROOT=/app`
     3. 容器内工作目录：`container_wd="${SLOT_DOCKER_CONTAINER_ROOT}${repo#$SLOT_DOCKER_HOST_ROOT}"`
     4. 执行：`docker exec -w "$container_wd" php82 php -l "${f#$repo/}"`
   - 示例（工作区在 `www/ray`、改 `slot-admin` 时）：`-w /app/www/ray/slot-admin`；工作区在 `www/slot`、改 `slot_wallet` 时：`-w /app/www/slot/slot_wallet`——**由当前仓库路径推导，不手写服务名**。
3. **必做人工对照**（写进报告表格）：
   - `php-clean-code` §3 常量规则、§8 自查
   - 改 Logic 时：§3 参数与日志、聚合 DTO
   - `backend-layering` 分层
4. **固定输出模板**（与你看到的报告一致）：
   - 门禁脚本完整输出
   - PHPDoc / 常量 / 分层 / 结论
   - 末行 `PHPDoc: checked`

可选：Skill 内引用 [`scripts/report.sh`](/Users/ray/.cursor/skills/slot-backend-completion-report/scripts/report.sh) 统一跑 verify + php -l。脚本职责：
- 读取 `WORKSPACE_ROOT` / `SLOT_ROOT`（当前工作区）
- 从 git diff 收集改动 PHP，按上文规则计算 `container_wd`
- 输出结构化片段供 Agent 粘贴进报告

**用户级 Skill 约束**：不得假设固定 monorepo 路径（如 `www/ray`）；所有宿主机/容器路径通过「工作区 + git 仓库根 + Docker 挂载映射」推导；挂载根可在 Skill 中 documented 为可配置 env，默认对齐 [`dev-environment.mdc`](/Users/ray/.cursor/rules/dev-environment.mdc)。

### 层 2：改 Rule（强制收尾用 Skill）

在 [`agent-completion-gate.mdc`](/Users/ray/.cursor/rules/agent-completion-gate.mdc) 增加：

- 改动 PHP 后，收尾前 **必须读取并执行** `slot-backend-completion-report` Skill
- 最终回复 **必须包含** Skill 规定的「检测结果」章节，不得只写「已完成」

### 层 3：增强 verify 脚本（可选，提高自动化比例）

在 [`verify-slot-backend.sh`](/Users/ray/.cursor/hooks/verify-slot-backend.sh) 追加（仅扫 diff 新增行）：

- 新增 `const` 前一行不是 `/** ... */` → FAIL
- 修复已知 bug：`diff_added_lines` 在纯删除 diff 时 `grep` 退出导致脚本 silent fail（你之前遇到过）

这样 Hook 的 `stop` 能拦住**常量无注释**；PHPDoc 方法级仍靠 Skill + Agent 报告。

---

## 不是 Skill  alone，也不是 Hook alone

| 你想要的效果 | 用什么 |
|--------------|--------|
| 每次写完必跑 verify | 已有 Rule + stop Hook |
| 固定格式的 Markdown 报告 | **Skill + Rule 强制引用** |
| 常量/PHPDoc 等硬规则自动 FAIL | **扩展 verify 脚本** |
| Logic 可读性、分层是否合理 | Skill 里的 §8 自查 + Agent 表格 |

---

## 你怎么用

配置完成后：

1. **默认**：Agent 改 PHP 后收尾会自动读 Skill、跑脚本、出报告（Rule 驱动）
2. **手动**：任意对话里说「按规范检测代码」→ Agent 读同一 Skill 即可
3. **Hook 兜底**：即使 Agent 忘了说完成，`stop` 仍会跑 verify；FAIL 会再追问一轮

---

## 实施顺序（若你确认要做）

1. 新建 `slot-backend-completion-report` Skill（模板 + 命令 + 自查表）
2. 更新 `agent-completion-gate.mdc` 指向该 Skill
3. （可选）扩展 `verify-slot-backend.sh`：常量注释 + 修复 pipefail
4. （可选）项目级复制 Skill 到 `www/ray/.cursor/skills/` 便于团队共享

**工作量**：Skill + Rule 约 30 分钟；脚本增强约 1–2 小时。