---
name: "agent-hook-lifecycle"
version: "1.2.0"
origin: "captured"
generation: 0
parent_skill_ids: []
status: "stable"
description: "Agent 动作生命周期钩子注册表。定义 PreAction/PostAction 钩子规则，当 Agent 执行特定操作（文件修改、代码生成、切片路由）前后自动触发检查。借鉴 OpenHarness PreToolUse/PostToolUse 机制，在 Prompt 层实现声明式守卫。"
trigger_phases: ["all"]
applicable_agents: ["Copilot Orchestrator", "Copilot Implementation", "Copilot Architect", "Copilot Code Review"]
priority: 1
---

# Agent Hook Lifecycle — 动作生命周期钩子

> **来源**：OpenHarness `hooks/` 子系统的 PreToolUse/PostToolUse 生命周期事件。
> **实现方式**：Prompt 层声明式钩子（非运行时拦截），由 Agent 在执行动作前后自行检查并遵守。

## 何时触发

| 触发条件 | 说明 |
|---|---|
| Orchestrator 路由到实施/验证类 Agent 时 | Orchestrator 在路由指令中附带适用的钩子清单 |
| Agent 执行写操作（create_file / replace_string / run_in_terminal）前 | Agent 自行检查 PreAction 钩子 |
| Agent 完成一轮实质性输出后 | Agent 自行检查 PostAction 钩子 |

## 谁来调用

| Agent | 职责 |
|---|---|
| **Copilot Orchestrator** | 在路由指令中声明当前切片适用的钩子集合 |
| **所有实施/验证类 Agent** | 执行动作前后自查钩子合规 |

---

## §1 钩子注册表（Hook Registry）

### 1.1 PreAction 钩子

Agent 在执行对应操作**之前**必须检查的规则。

| Hook ID | 钩子名称 | 触发条件 | 检查内容 | 适用 Agent |
|---|---|---|---|---|
| **PRE-01** | PreCodeGen | Code Gen Specialist 开始生成代码前 | Entity 继承规则（TenantEntity/BaseEntity/Serializable）、ID 类型合规（Long/BIGINT 默认）、公共字段存在 | Code Gen Specialist |
| **PRE-02** | PreImplementation | Implementation Agent 开始编码前 | ① 确认 Planner 切片范围已接收 ② 有状态模块：确认约束前置三板斧已接收（失败矩阵 + 守卫清单 + 跨层契约表）③ 有前端页面：确认字段覆盖矩阵 + UI handoff + 字段分组方案已接收 | Implementation |
| **PRE-03** | PreDocModify | 任何 Agent 修改 `M-DOC/**` 下文件前 | ① 确认修改范围在当前切片边界内 ② 记录修改前的文档版本摘要 | PM, Architect, Documentation |
| **PRE-04** | PreSchemaChange | 修改 DDL / Entity / DTO 前 | ① 确认 Schema Guardian pre-check 已通过 ② 确认 ID/FK 类型契约一致 | Code Gen, Implementation |
| **PRE-05** | PreQA | QA Automation 开始执行测试前 | ① Playwright 配置存在 ② 前端自动化运行时就绪 ③ 测试脚本路径可达 | QA Automation |
| **PRE-06** | PreFrontendWrite | 创建/修改 `src/views/**` 页面文件前 | ① 确认不使用 avue-crud ② 确认使用 `<script setup>` Composition API ③ 确认无硬编码中文（使用 `t()` i18n） | Implementation |
| **PRE-07** | PreSkillEvolution | `skill-evolution-protocol` 启动演进流程前 | ① 演进候选有充足数据支撑（FIX: ≥5 refs, DERIVED: ≥8 refs）② 反循环守卫通过（单会话单次、最小间隔 3 切片）③ `skill-safety-scanner` POST-EVOLUTION 扫描通过（无 CRITICAL）④ trial 状态 Skill 不可作为演进触发源 | Orchestrator |
| **PRE-08** | PreContextLoad | Agent 通过 `read_file` 加载项目 markdown 上下文文件前 | ① 运行 `skill-safety-scanner` SS-05 上下文文件注入检测 ② 运行 Unicode 不可见字符快速扫描 ③ BLOCK → 不加载该文件，向用户警告注入风险 | 所有 Agent |

### 1.2 PostAction 钩子

Agent 完成对应操作**之后**必须执行的检查。

| Hook ID | 钩子名称 | 触发条件 | 检查内容 | 适用 Agent |
|---|---|---|---|---|
| **POST-01** | PostCodeGen | Code Gen Specialist 生成代码后 | ① 输出 UI handoff contract（字段分类、FK selector 契约）② 触发 Schema Guardian pre-check 建议 | Code Gen Specialist |
| **POST-02** | PostImplementation | Implementation Agent 完成编码后 | ① 执行自检清单 ② 确认字段覆盖矩阵中每个字段至少在一个页面状态中可见 ③ 触发 Schema Guardian post-check 建议 ④ 运行当前切片必要的编译/健康检查 ⑤ 当 `phaseMode=DevelopmentCompileGate` 时输出 Dev Handoff Pack + QA backlog，且不得声明 QA_PASS ⑥ 输出 Execution Metrics | Implementation |
| **POST-03** | PostDocModify | `M-DOC/**` 下文件被修改后 | ① 自动建议运行 `design-doc-completeness-check`（文档完整性校验）② 若涉及 2+ 文档，自动建议运行 `cross-doc-consistency-check` | PM, Architect, Documentation |
| **POST-04** | PostCodeReview | Code Review 完成审查后 | ① 确认失败矩阵覆盖率 ≥ 80%（有状态模块）② 触发 Invariant Sentinel post-impl 建议（有状态机模块）③ 输出 Execution Metrics | Code Review |
| **POST-05** | PostQA | QA Automation 完成测试后 | ① 确认失败矩阵中每个场景都有测试 ② 验证成功路径 + 失败路径均覆盖 ③ 仅成功路径通过 → 标记 INCOMPLETE（非 PASS）④ 仅在 `phaseMode=FullQAGate` / 测试任务 / 发版签收中输出 final QA verdict ⑤ 输出 Execution Metrics | QA Automation |
| **POST-06** | PostFrontendWrite | 前端页面文件创建/修改后 | ① 检查 `var(--im-*)` 设计令牌使用（禁止硬编码色值）② 检查中英文双语 i18n 资源完整 ③ 检查 NativeSearchTable 列配置与 option 工厂函数一致 ④ 执行前端健康检查（语法、图标、API import-export 联通性、禁止新增 `@/mock` 依赖），默认使用 `tools/blade/check-frontend-health.sh` / `BladeX: Frontend Health Check`，不以前端 build 作为默认 gate | Implementation |
| **POST-07** | PostSkillEvolution | Skill 演进（FIX/DERIVED/CAPTURED）完成后 | ① 验证 SKILL.md 结构完整性（SS-04 规则）② 验证 frontmatter 与 SKILL-REGISTRY.md 条目一致 ③ 更新 `skill-version-registry` 注册表 ④ 重置该 Skill 在 `skill-effectiveness-tracker` 中的计数器 ⑤ 标记 Skill 状态为 trial | Orchestrator |
| **POST-08** | PostSliceClosure | 切片 closure 阶段完成时 | ① 触发 `structured-execution-recording` 归档（session recordings → agentLog）② 触发 `post-execution-analysis` 分析 ③ 触发 `skill-effectiveness-tracker` 指标累积更新 ④ 更新 Slice Snapshot 最终状态 | Orchestrator |
| **POST-09** | PostComplexTask | Agent 完成 5+ 工具调用链的任务后 | ① 回顾工具调用链和决策路径 ② 评估是否存在可复用模式（无现有 Skill 覆盖） ③ 高复用性 → 向用户建议 CAPTURED 演进 + 输出模式摘要（问题/方案/工具链/结果） ④ 中复用性 → 仅记录到 session memory，等第 2 次观察后再建议 ⑤ 低复用性 → 无操作 | Implementation, Architect |
| **POST-10** | PostSkillDeviation | Agent 使用 Skill 但发现其指令过时/错误/缺失时 | ① 记录偏差详情到 `/memories/session/skill-deviations.md`（Skill 名、偏差类型、绕过方式、影响等级） ② CRITICAL 偏差（阻断工作） → 立即建议 FIX 演进 ③ MEDIUM 偏差（需要绕过） → 累积到 `skill-effectiveness-tracker`，达阈值后触发 FIX 建议 | 所有实施/验证类 Agent |

---

## §2 文件模式触发器（File Pattern Triggers）

> 对应 OpenHarness A2 思想：文件变更自动触发检查。

当 Agent 修改匹配特定路径模式的文件时，自动触发关联检查。

| 文件模式 | 触发的钩子/检查 | 说明 |
|---|---|---|
| `M-DOC/**/*.md` | POST-03 → `design-doc-completeness-check` | 设计文档变更自动触发完整性校验 |
| `M-DOC/**/*.md` (2+ files) | POST-03 → `cross-doc-consistency-check` | 多文档变更自动触发一致性校验 |
| `blade-service-api/**/entity/**` | PRE-04 + POST-01 | Entity 变更触发 Schema 前检 + handoff 更新 |
| `blade-service-api/**/vo/**`, `**/dto/**` | PRE-04 | VO/DTO 变更触发契约一致性检查 |
| `src/views/**/*.vue` | PRE-06 + POST-06 | 前端页面变更触发规范合规检查 |
| `src/option/**/*.js` | POST-06 | 列配置变更触发字段覆盖检查 |
| `script/**/*.sql` | PRE-04 | DDL/DML 变更触发 Schema 合规 |

---

## §3 钩子执行协议

### 3.1 Orchestrator 路由附带钩子声明

Orchestrator 在路由到下游 Agent 时，应在指令中包含适用的钩子 ID 列表：

```
Route to: Copilot Implementation
Slice: EAM-Slice-2
Phase: implementation
Applicable Hooks: PRE-02, PRE-06, POST-02, POST-06
Hook Context:
  - phaseMode: DevelopmentCompileGate → POST-02 输出 DEV_READY/COMPILE_READY + Dev Handoff Pack，不要求 QA_PASS
  - 有状态模块: YES → PRE-02 要求约束前置三板斧
  - 有前端页面: YES → PRE-06, POST-06 前端规范
  - 失败矩阵已接收: YES (12 scenarios)
```

### 3.2 Agent 自查执行格式

Agent 在输出中显式声明钩子检查结果：

```markdown
### Hook Compliance
| Hook | Status | Evidence |
|---|---|---|
| PRE-02 | ✅ PASS | 三板斧已接收：失败矩阵(12条) + 守卫清单(8条) + 契约表(已对齐) |
| PRE-06 | ✅ PASS | script setup + i18n t() + 无 avue-crud |
| POST-02 | ✅ PASS | 自检清单 17/17 通过，字段覆盖 32/34（2 项延后标记） |
| POST-06 | ✅ PASS | 设计令牌 100%，中英文双语资源完整 |
```

### 3.3 钩子违规处理

| 违规级别 | 处理方式 |
|---|---|
| PreAction 钩子未通过 | **BLOCKED** — Agent 不得继续执行，向 Orchestrator 报告缺失项 |
| PostAction 钩子未通过 | **WARNING** — Agent 在输出中标记 ⚠️，由 Orchestrator 决定是否回退 |
| 文件模式触发器命中但未执行检查 | **DEFERRED** — 记录在 Slice Snapshot 的延后项中，closure 前必须补齐 |

---

## §4 钩子扩展规则

1. 新增钩子必须在本 Skill 的 §1 注册表中添加条目，包含：Hook ID、名称、触发条件、检查内容、适用 Agent。
2. 钩子 ID 格式：`PRE-{NN}` / `POST-{NN}`，编号递增。
3. 每个钩子必须有明确的"通过"和"不通过"标准，不允许模糊判定。
4. 钩子不得引入新的 Agent 间依赖（钩子是 Agent 内部自查，不是跨 Agent 调用）。
5. PRE-07/POST-07/POST-08 为学习闭环钩子，仅 Orchestrator 在 closure 阶段执行，不传递给下游 Agent。
6. PRE-08 为安全守卫钩子，所有 Agent 在加载项目 markdown 文件时自查，与 `skill-safety-scanner` SS-05 联动。
7. POST-09/POST-10 为技能自主演进钩子：POST-09 在复杂任务后自动评估可复用模式，POST-10 在 Skill 偏差发现后记录并建议修复。两者均为**非阻断**钩子，仅建议不强制。
8. POST-09 的建议频率控制：同一模式在同一会话内仅建议一次；中复用性模式需跨 2+ 次观察才触发建议。