171 lines
8.9 KiB
Markdown
171 lines
8.9 KiB
Markdown
---
|
||
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 小时。
|