cursor/plans/agent_自检报告机制_bf9d9dde.plan.md

name, overview, todos, isProject

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

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

你现在已经有什么

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

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

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

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，只需加一条：收尾章节必须按 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，内容包括：

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 统一跑 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。

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

在 agent-completion-gate.mdc 增加：

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

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

在 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 小时。