SuperAPI AI 工具集

check

编程与开发

查看项目

更新于 10-16 05:58

技能介绍

Check — 变更验证与规则演进

Check 通过将 git diff 与 .hoyeon/rules/ 规则目录进行比对,捕捉遗漏的级联改动,并在检测到新的未匹配模式时提出规则更新建议。

前提条件:项目必须具有 .hoyeon/rules/ 目录,其中包含带有 YAML frontmatter 的规则文件。如果 .hoyeon/rules/ 不存在,需引导用户创建:mkdir -p .hoyeon/rules,然后帮助其按照 ${baseDir}/references/rules-authoring.md 编写第一个规则文件。

采用两阶段结构:

阶段一(始终执行):验证变更,生成 PASS/WARN 结果

阶段二(条件触发):仅在存在未匹配模式时,提出规则更新建议

阶段一:变更验证

  1. 收集变更文件

收集已提交 + 未提交的变更

git diff --name-only HEAD~1..HEAD git diff --name-only --cached git diff --name-only

去重后存储为 CHANGED_FILES。

  1. 构建规则图并匹配

读取所有 .hoyeon/rules/*.md 文件的 YAML frontmatter 来构建规则图。frontmatter 结构参见 references/rules-authoring.md 的“Structure”部分。

匹配顺序:

将 CHANGED_FILES 中的每个文件与每条规则的 triggers 模式进行 Glob 匹配

沿匹配规则的 depends_on 边引入相关规则(仅 1 层深度)

确定最终生效的规则集

将未匹配的文件单独存储为 UNMATCHED_FILES(供阶段二使用)

注意:元文档(例如 RULES.md)不参与匹配。

  1. 并行子代理验证

使用 Agent 工具(subagent_type="general-purpose")为每条生效规则启动一个子代理,并并行运行。

向每个子代理传入:

CHANGED_FILES 列表

规则文件正文(检查清单内容)

变更文件的实际 diff(git diff)

每个子代理需要:

将检查清单项应用于 CHANGED_FILES

识别出某个文件被修改但相关文件未被修改的情况

读取 WARN 项的实际 diff,判断遗漏是否为真实遗漏

返回分类为 PASS / WARN / Not Applicable 的结果

  1. 汇总并输出结果

收集所有子代理结果,按类别分组输出:先是 domain 规则,然后是 concern 规则,最后是 pipeline 规则。

阶段一:验证结果

PASS(N 项)

domain

  • [billing] schema.ts 已变更 -> 迁移文件已创建

concern

  • [infra] .env 已变更 -> terraform 已同步

pipeline

  • [api-codegen] swagger 已变更 -> 类型已重新生成

WARN(N 项)

concern

  • [ux] en.json 已变更 -> ko.json 未更新

Not Applicable(N 项)

  • [docs] 无 docs/ 变更
  1. 执行 agents/commands

如果生效规则具有 agents 或 commands 字段:

agents:通过 Agent 工具自动运行以进行额外验证。将代理结果中的 WARN 合并到阶段一的 WARN 列表中。

commands:将命令呈现给用户手动执行(例如 pnpm generate:api)。

  1. 处理 WARN

针对每个 WARN 项:

读取变更的代码,判断是否确实需要改动

区分有意省略与意外遗漏

对于真实遗漏,明确指出需要修改的具体文件与位置

阶段二:规则更新提案(条件触发)

阶段二触发条件——满足以下任一条件即执行阶段二:

UNMATCHED_FILES 包含至少一个有意义源文件(.ts、.tsx、.json、.yaml、.tf 等)——排除元文件(.md、锁文件等)

阶段一中有任一 WARN 表明存在规则缺口(而非规则违规)

跳过条件:如果 UNMATCHED_FILES 为空且没有 WARN 表明规则缺口,则跳过阶段二,直接进入后续操作(第 9 步)。

区分规则缺口与规则违规:如果某个 WARN 是由于违反了现有检查清单项导致的,则属于规则违规(在阶段一处理)。如果任何地方都不存在可提前捕获该 WARN 的检查清单项,则属于规则缺口——触发阶段二。

  1. 分析模式并交叉比对规则

分析 UNMATCHED_FILES 和阶段一 WARN 结果,识别:

未覆盖的变更模式——未被任何规则 triggers 匹配的文件变更

接近命中的级联变更——多处存在重复逻辑,但仅部分被更新

新发现的同步点——修改一处需要更新另一处的关系

阅读 references/rules-authoring.md 获取编写指南,然后对发现进行分类:

现有规则需新增条目——建议要添加到规则文件中的具体条目

需要新规则文件——现有规则未覆盖的全新模式;包含 category 字段(domain | concern | pipeline)

  1. 输出规则更新提案

阶段二:规则更新提案

  1. [subscriptions.md] 为 3 个应用中的 URL 检测函数添加同步检查
    • 原因:isSubstackUrl() 在 3 处重复,仅 2 处更新
  2. [新文件:webhook.md] 为 webhook 事件变更添加同步检查
    • category: domain
    • 原因:新领域,现有规则未覆盖

使用 AskUserQuestion 确认每个提案:

“Add”——将条目应用到规则文件

“Edit & Add”——添加前调整内容

“Skip”——不必要,跳过此项

将批准的条目应用到对应规则文件。对于新规则文件,使用 frontmatter 创建(category 和 triggers 为必填)。

添加或修改规则后,验证 frontmatter 的 triggers 模式能正确匹配合适的文件。

  1. 后续操作

将阶段一的 WARN 与阶段二的规则更新合并为后续变更列表。

如果存在一个或多个 WARN 项,呈现列表并使用 AskUserQuestion 询问用户:

“Fix All”——自动修复所有 WARN 项

“Select”——选择特定项修复(multiSelect)

“Ignore & Proceed”——视为有意省略,不做改动直接完成

当选择“Fix All”或“Select”时,按顺序应用修复并显示更新后的结果。

附加资源

参考文件

${baseDir}/references/rules-authoring.md——规则编写原则、frontmatter 结构、类别分类及抽象层级指南。在创建或更新规则时查阅。