post-edit-verification

编辑后验证

编辑组件文件后，通常会想重新通读整个文件，确认编辑已生效。**默认不要这样做。**组件 JSON 文件是经过压缩的单行文档，通常有 20–100 KB，每次编辑后重新读取都会消耗实际工作所需的上层对话上下文。还有几种更轻量的信号可以完成同样的工作——请按以下顺序应用。

**Hook 替代方案的背景。**Mitch 的仓库中有一个 PostToolUse hook（hooks/validate-component.py），它会自动阻止对受跟踪组件后缀文件执行的任何 Edit/Write 操作，条件是 description 为 null、为空、超过 100 个字符，或 JSON 无法解析。Datex Skills 仓库没有 PostToolUse 机制——技能不会因工具事件而自动调用。本技能是替代方案：每个组件创建技能都会以 “编辑后，调用 post-edit-verification” 结束，因此能在技能层集中强制执行同样的两项平台不变量（DRY），而不是在 harness 层执行。如果某个环境安装了 harness 层的保存门禁 hook（会阻止不合格组件保存的 PostToolUse 验证器），请将 hook 未报错视为积极信号——说明这些门禁已在 harness 层通过——而不是认为没有反馈；以下技能检查仍是可移植的最低保障。

平台不变量（最低检查要求）

这两条规则对每个组件文件都不可妥协。它们是先前 hook 执行的规则，也是本技能的最低要求——每次调用都必须确认这两项，无论编辑看起来多么简单。

1. **必须存在 description，且长度不得超过平台限制。**顶层 description 必须非 null、非空，且长度 ≤ 100 个字符。Footprint 平台将 description 存储在上限为 100 个字符的 SQL 列中；超过限制时，导入会因 SQL 截断错误而失败。规范的“描述为必填”规则请参见 ../datex-studio-conventions/defaults.md，100 个字符的 SQL 限制请参见 ../datex-studio-conventions/file-format.md。如果该字段缺失或过长，请在同一轮编辑中修复——不要询问是否要补上，只需撰写一条不超过 100 个字符的描述（用户之后可以像修改任何自行填写的值一样调整措辞）。

2. **JSON 必须能够正确解析。**编辑后，文件必须仍是有效 JSON。运行 python -c "import json; json.load(open(r'<path>')); print('OK')"。括号不匹配、多余的引号或无效的转义序列都会在这里显现。该操作免费，不消耗上层上下文。对同一文件的一系列编辑完成后运行一次即可，无需每次编辑后都运行。

如果任一不变量未通过，编辑就尚未完成。请修复问题并重新验证，然后再声称已完成或继续下一步。

验证流程（按成本从低到高）

1. Edit 工具的成功消息。 工具会报告“文件 ... 已成功更新。”该消息意味着 old_string 已匹配并被原样替换。如果你编写了精确的 old_string，且工具报告成功，则文本编辑已完成。剩下的问题是结果在结构和语义上是否有效——接下来的验证层会对此进行检查。

2. JSON 解析检查。 python -c "import json; json.load(open(r'<path>')); print('OK')"。确认编辑没有破坏 JSON 外层结构（括号不匹配、引号多余、转义错误）。免费，不消耗父上下文。对同一文件的一系列编辑完成后运行一次，而不是每次编辑后都运行。这是平台不变量 #2。

3. Description 检查。 JSON 解析通过后，确认 description 非 null、非空且不超过 100 个字符：

   python -c "import json; d=json.load(open(r'<path>'))['description']; assert d and len(d) <= 100, (d, len(d) if d else 0); print('OK', len(d))"
   

   这是平台不变量 #1。 如果断言失败，请在同一编辑周期中修复该字段。

4. 使用 -C 上下文运行 Grep。 要确认特定编辑出现在预期位置，应按名称定位已更改的部分，而不是搜索整个文件：

   • Grep "while \(pickTasks" -C 30 会返回循环附近约 60 行，而不是整个 30 KB 的文件。
   • Grep "concurrency_limit" -C 5 可确认已添加 inParam，而无需输出整个架构。
   • 上下文量级减少，同时不牺牲精确度。

5. component-validator 子 Agent。 对于非平凡重构后的重要结构验证——类似最终关卡审查所做的审计，但按文件进行——请调用 component-validator。该子 Agent 会在自己的上下文中读取文件；只有问题清单会返回给父级。对于网格，请改用 grid-validator——它会检查通用调度器无法发现的网格特有问题（外层结构、文本显示强制转换、五处位置不变量）。

6. 重新读取整个文件（最后手段）。 只有在确实需要从头到尾查看完整结构，且还不知道该搜索什么时，才使用 Read——例如追查隐蔽的布局问题，或调试验证器的问题清单为空但仍觉得不对劲的情况。应将其作为最后采用的信号，而不是第一个。

何时委派给 component-validator Agent

在以下情况下委派：

• 你已完成单个组件文件中的非平凡编辑（循环重构、架构更改、多步骤修复）。
• 文件经压缩后超过 20 KB（大多数组件文件都如此）。
• 你需要结构化的问题清单，而不是自行随意抽查。
• 更改涉及 description、inParams / outParams、accessModifier，或该类型的 Pre-Flight Checklist 涵盖的其他契约字段。

在以下情况下不要委派：

• 编辑只是单字符或单行调整。使用 Grep -C 更快。
• 你还在编辑过程中，需要决定下一步改什么。父级需要保留局部上下文。
• 更改纯粹是格式或空白调整（验证器没有相关规则）。
• 你已在之前的编辑后调用验证器，之后只做了小幅更改。

对于网格文件（*-grid.json），优先使用 grid-validator，而不是 component-validator——无论编辑规模如何，网格文件都必须使用它，因为通用调度器无法发现网格特有问题（外层结构、动态筛选器镜像漂移、lookupcode/id 部分同步）。

与风险成比例的验证

验证成本应与更改的风险范围成比例。平台不变量（上文的 #1 和 #2）是最低要求——适用于每一行。右侧列出最低要求之外的额外检查。

编辑类型	验证（不包括两项平台不变量）
单字符修复／注释修复	信任 Edit 成功消息——无需更多操作。
非契约字段中的单块内容更改	（仅需满足最低要求。）
架构或契约更改（inParams / outParams / accessModifier）	对更改的架构进行定向 Grep -C。
同一文件中的多处编辑重构	在序列末尾使用 component-validator 子 Agent，而不是每次编辑后都使用。
跨组件更改（协调修改多个文件）	在末尾对每个文件使用 component-validator，并使用 component-wiring-check 技能。
网格文件（*-grid.json）——任何编辑	使用 grid-validator 子 Agent（强制要求；网格文件不使用通用验证器）。

验证是保险，而非确认。让验证成本与风险相匹配——但绝不可跳过最低要求。

参考资料

• ../datex-studio-conventions/defaults.md — 规范的“描述为必填项”规则（非 null、非空且不超过 100 个字符）。
• ../datex-studio-conventions/file-format.md — 规范的文件格式规则，包括 description 的 100 字符 SQL 限制和单行压缩 JSON 约定。
• ../datex-studio-conventions/universal-checklist.md — 本技能两项不变量最低要求之外、更全面的跨领域检查清单。本技能强制执行最低要求（描述 + JSON 解析）；升级处理时，component-validator 会检查完整清单。
• component-validator — 通用的按类型审计分发器；非简单编辑的升级处理目标。
• grid-validator — 网格专用审计；无论编辑规模大小，对 *-grid.json 均为强制要求。