从 Skill 到 Hook：自动化闭环验证的工程实践

2026-06-15 | OODER A2UI 团队 | Trae IDE Hooks 实测

​

一、背景与动机

OODER A2UI 是一个低代码平台，核心流程是从自然语言输入（NLP）到代码生成的完整闭环：LLM-Chat → 四分离设计 → JSON-2-UIModule → genCode → Build。这个闭环涉及 5 个阶段、7 个限界上下文、10+ 种场景类型，任何一环出错都会导致生成的代码无法编译或运行。

在引入 Trae Hooks 之前，我们面临三个核心痛点：

• 上下文丢失：每次新会话开始，AI 助手对项目结构、服务状态、Maven 配置一无所知，需要反复手动提供
• 误操作无保护：AI 助手可能绕过核心构建流程（AggRootBuild）、直接编辑 .cls 文件、或静默忽略编译错误
• 闭环验证缺失：任务结束时没有自动校验生成代码的完整性，经常出现"报告成功但代码无法编译"的情况

Trae Hooks 的 5 种事件类型（SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop）恰好能覆盖这三个痛点。

二、Hook 设计与实现

2.1 整体架构

我们设计了 7 个 Hook，分布在 5 种 Trae 事件上：

2.2 hooks.json 配置

配置文件位于 E:\github\a2ui\.trae\hooks.json，遵循 Trae 官方规范：

{
  "hooks": {
    "SessionStart": [{
      "name": "ooder-project-context",
      "enabled": true,
      "command": "powershell -ExecutionPolicy Bypass -File .trae/hooks/session-start.ps1"
    }],
    "UserPromptSubmit": [{
      "name": "ooder-nlp-intent-guard",
      "enabled": true,
      "matcher": "",
      "command": "powershell -ExecutionPolicy Bypass -File .trae/hooks/nlp-intent-guard.ps1"
    }],
    "PreToolUse": [{
      "name": "ooder-protect-aggbuilder",
      "enabled": true,
      "matcher": "Edit|Write",
      "command": "powershell -ExecutionPolicy Bypass -File .trae/hooks/protect-aggbuilder.ps1"
    }, {
      "name": "ooder-protect-cls-files",
      "enabled": true,
      "matcher": "Edit|Write",
      "command": "powershell -ExecutionPolicy Bypass -File .trae/hooks/protect-cls-files.ps1"
    }],
    "PostToolUse": [{
      "name": "ooder-verify-ftl-change",
      "enabled": true,
      "matcher": "Edit|Write",
      "command": "powershell -ExecutionPolicy Bypass -File .trae/hooks/verify-ftl-change.ps1"
    }],
    "Stop": [{
      "name": "ooder-nlp-loop-validation",
      "enabled": true,
      "loop_limit": 3,
      "command": "powershell -ExecutionPolicy Bypass -File .trae/hooks/nlp-loop-validation.ps1"
    }],
    "Notification": [{
      "name": "ooder-build-notify",
      "enabled": true,
      "matcher": "*",
      "command": "powershell -ExecutionPolicy Bypass -File .trae/hooks/build-notify.ps1"
    }]
  }
}

三、实测场景与结果

3.1 场景一：SessionStart 自动注入上下文

痛点：每次新会话，AI 助手不知道项目结构、Studio 是否在运行、Maven 仓库在哪，需要反复手动说明。

Hook 行为

会话创建后、第一轮对话前，session-start.ps1 自动执行：

1. 检测 Studio（8099）和 AIServer（9004）端口状态
2. 检测 Maven 可用性
3. 向 $TRAE_ENV_FILE 写入环境变量（OODER_STUDIO_ALIVE、OODER_MAVEN_REPO 等）
4. 通过 stdout 输出纯文本上下文，作为附加上下文注入模型

实测输出示例

[OODER A2UI Project Context]
- Project Root: E:\github\a2ui
- Studio (port 8099): RUNNING
- AIServer (port 9004): RUNNING
- Maven: Available at D:\maven\apache-maven-3.9.10
- Maven Repo: D:\maven\.m2
- sceneGroup Mechanism: ENABLED (sceneGroupId = projectName, 1:1 binding)

[Module Structure]
- ouc/ouc-core: Core engine (D2CGenerator, AggRootBuild, FTL templates)
- ooder-pro: Studio application (NlpOrchestrator, NlpDesignService)
- scene-engine: Scene engine (NlpPipeline, SceneGroup, SceneGroupManager)

[Three-Phase Split API]
- Phase 1 (design-only): POST /api/nlp/design-only
- Phase 2 (generate-repository): POST /api/nlp/generate-repository
- Phase 3 (integrate-full): POST /api/nlp/integrate-full

效果评估

通过 AI 助手从第一轮对话就知道 Studio 在运行、Maven 仓库在 D:\maven\.m2、三阶段 API 端点是什么。不再需要手动重复提供这些信息。

3.2 场景二：PreToolUse 保护 AggRootBuild

痛点：AI 助手在遇到 AggRootBuild 编译错误时，倾向于"绕过"------用 buildCustomModule 或直接生成代码替代。这违反了 OODER 的核心约束：AggRootBuild 是唯一合法的构建机制。

Hook 行为

当 AI 助手执行 Edit 或 Write 工具修改 Java 文件时，protect-aggbuilder.ps1 自动检查新代码是否包含危险模式：

• buildCustomModule --- 绕过 AggRootBuild 的替代构建方法
• skipAggRootBuild --- 显式跳过构建
• bypassBuild --- 绕过构建
• 在 NlpProjectIntegrator 中移除 executeAggRootBuild 调用

实测：拦截绕过尝试

AI 助手尝试在 NlpProjectIntegrator 中用 buildCustomModule() 替代 executeAggRootBuild()：

// AI 尝试的修改
aggRootBuildSPI.buildCustomModule();  // 绕过 AggRootBuild

Hook 拦截结果：

{
  "permissionDecision": "deny",
  "reason": "Detected bypass of AggRootBuild: 'buildCustomModule'. 
   AggRootBuild is the core build mechanism and must NOT be bypassed."
}

效果评估

拦截成功 AI 助手被阻止执行此修改，stderr 中的原因被附加到模型上下文，AI 助手转而分析 AggRootBuild 的真正问题并正确修复。

3.3 场景三：PreToolUse 保护 .cls 文件

痛点：AI 助手有时直接编辑 .cls 文件（JSON 格式的模块定义），绕过 NLP Pipeline。但 .cls 文件必须通过 NlpDesignService → NlpDesignBridgeService → saveModule 流程生成，直接编辑会导致状态不一致。

实测：拦截直接编辑

AI 助手尝试编辑 NavigationVerification.cls：

{
  "permissionDecision": "deny",
  "reason": ".cls files must be generated through NLP Pipeline 
   (NlpDesignService -> NlpDesignBridgeService -> saveModule), 
   not edited directly. Use POST /api/nlp/design-only to regenerate."
}

效果评估

拦截成功 AI 助手转而通过正确的 API 端点重新生成 .cls 文件，保持了状态一致性。

3.4 场景四：PostToolUse FTL 语法验证

痛点：修改 FTL 模板后，经常出现标签未闭合、函数未定义等语法错误，直到运行时才被发现。

Hook 行为

当 Edit/Write 工具修改 .ftl 文件后，verify-ftl-change.ps1 自动检查：

• <#if> / </#if> 标签闭合
• <#list> / </#list> 标签闭合
• <#switch> / </#switch> 标签闭合
• DB 模板中 isPersistable() 函数是否已定义

实测：检测未闭合标签

修改 ddd-repository-db-impl.ftl 时遗漏了一个 </#if>：

[FTL Syntax Warning] Unclosed <#if> tags: found 8 <#if> but 7 </#if>

Hook 以 exit code 2 退出（PostToolUse 事件中，exit 2 将 stderr 传递给模型但不阻止操作），AI 助手收到警告后立即补上了遗漏的闭合标签。

效果评估

通过 FTL 语法错误在修改时即被发现，而不是等到运行时。从"运行时发现"提前到"编辑时发现"，效率提升显著。

3.5 场景五：Stop 闭环验证

痛点：最严重的问题------AI 助手报告"任务完成"，但生成的代码缺少关键文件（如 Repository、DBImpl），导致编译失败。这种"虚假汇报"在之前的会话中反复出现。

Hook 行为

当 AI 助手准备结束任务时，nlp-loop-validation.ps1 自动执行：

1. 检测当前是否是 NLP 相关任务
2. 检查生成目录下的 Java 文件数量（≥4）
3. 检查关键文件是否存在：Entity、Repository、API、APIImpl
4. 检查 DBImpl 中是否有不安全的 ResultModel 类型转换
5. 检查 Studio 是否在运行

实测：拦截不完整的代码生成

AI 助手报告"阶段二生成成功"，但实际只生成了 4 个文件（缺少 Repository/DBImpl/Aggregate）：

{
  "decision": "block",
  "reason": "[NLP Loop Validation] Code generation incomplete: 
   Only 4 Java files generated (expected >= 4 for complete repository layer); 
   Missing Repository interface file. 
   Please fix these issues before completing the task."
}

AI 助手被阻止结束任务，收到失败原因后继续分析根因------发现 buildLevel 未设置导致 Repository 类型降级为 CRUD 级别。

效果评估

拦截成功 这是最有价值的 Hook。它直接解决了"虚假汇报"问题，确保 AI 助手不会在代码不完整时声称任务完成。配合 loop_limit: 3，最多阻止 3 次停止尝试，避免无限循环。

四、sceneGroup 机制的 Hook 协同

五、实测数据汇总

Hook	触发次数	拦截/阻止	误拦截	实测结果
session-start	1（每次会话）	0	0	通过
nlp-intent-guard	12	0（全部 allow）	0	通过
protect-aggbuilder	28	1	0	通过
protect-cls-files	28	1	0	通过
verify-ftl-change	6	1（exit 2 警告）	0	通过
nlp-loop-validation	3	2（block）	0	通过
build-notify	5	0	0	通过

六、关键发现与经验

6.1 Stop Hook 是最有价值的 Hook

在所有 Hook 中，Stop 事件的 loop-validation 价值最高。它直接解决了"AI 助手虚假汇报"的问题------在我们的实测中，它 2 次阻止了 AI 助手在代码不完整时结束任务，迫使 AI 助手继续分析根因并修复。

关键数据 ：Stop Hook 阻止 2 次后，AI 助手发现了 buildLevel 未设置的根因，修复后生成文件从 4 个增加到 9 个（Entity、Repository、DBImpl、CLIImpl、Aggregate、API、APIImpl 等）。

6.2 PreToolUse 的 matcher 精准度很重要

我们最初将 protect-aggbuilder 的 matcher 设为 *（匹配所有工具），导致每次工具调用都触发检查，性能开销较大。改为 Edit|Write 后，只在实际修改文件时触发，效率显著提升。

6.3 PostToolUse 的 exit 2 机制

PostToolUse 事件中，exit code 2 的行为是"将 stderr 传递给模型但不阻止操作"。这非常适合 FTL 语法验证------我们不希望阻止修改（可能只是部分修改），但希望 AI 助手知道有语法问题并立即修复。

6.4 SessionStart 的环境变量注入

通过 $TRAE_ENV_FILE 写入的环境变量，不仅在后续 Hook 中可用，还在 RunCommand 工具调用中生效。这意味着 AI 助手执行 mvn 命令时也能读取到 OODER_MAVEN_REPO 等变量。

6.5 loop_limit 防止无限循环

Stop Hook 的 loop_limit: 3 设置非常重要。在实测中，如果代码生成存在结构性问题（如子模块 Repository 缺失），AI 助手可能无法在 3 次内修复。此时 loop_limit 会放行，避免 AI 助手陷入无限循环。

七、从 Skill 到 Hook 的演进

在引入 Hooks 之前，我们使用 SKILL.md 文件定义规范。两者的区别：

维度	Skill (SKILL.md)	Hook (hooks.json)
触发方式	AI 助手主动读取	事件自动触发
执行力	建议性（AI 可忽略）	强制性（可 deny/block）
上下文注入	需要 AI 主动查询	自动注入（SessionStart）
验证时机	AI 自行决定	固定时机（Stop/PostToolUse）
保护能力	无（纯文档）	有（PreToolUse deny）

两者是互补关系：Skill 定义"应该做什么"（规范），Hook 确保"必须这样做"（执行）。

八、总结

Trae Hooks 为 OODER A2UI 的 NLP 闭环验证提供了三层自动化保护：

1. 上下文层（SessionStart + UserPromptSubmit）：确保 AI 助手始终拥有项目上下文
2. 保护层（PreToolUse）：防止 AI 助手绕过核心流程或直接编辑受保护文件
3. 验证层（PostToolUse + Stop）：确保修改质量和任务完成度

实测结果表明，7 个 Hook 全部按预期工作，0 次误拦截，最关键的 Stop Hook 成功阻止了 2 次"虚假汇报"，迫使 AI 助手深入分析根因并完成正确的代码生成。

核心结论：Trae Hooks 将 OODER NLP 闭环从"AI 自觉遵守规范"升级为"系统强制执行规范"，显著提升了代码生成的可靠性和完整性。

OODER A2UI 团队 | Trae Hooks 实测报告 | 2026-06-15

项目地址：E:\github\a2ui | Hook 配置：E:\github\a2ui.trae\hooks.json