component-validator

组件验证器

根据特定类型的编写规则，审核单个 Datex Studio 组件文件——这是创作者技能完成组件编写或修改后、将更改更新到分支之前的最后一道只读关卡。此技能是一个通用分发器：它会读取组件文件，根据文件后缀选择匹配的创作者技能参考文档，并执行该文档中的检查清单。它会返回结构化的待办清单（阻塞项 / 警告 / 小问题）——绝不会重写文件。

另请参阅： grid-validator——网格文件（*-grid.json）有一些通用分发器无法发现的注意事项（信封与主体的形状、文本显示强制转换、五处位置不变式）。对于网格文件，优先使用 grid-validator；如果 grid-validator 不可用，再将此技能用作后备方案。

另请参阅： component-wiring-check——跨组件引用契约（一个组件指向另一个组件）。此验证器仅孤立地审核单个文件；它会标记在该文件中能发现的明显连线偏差（例如，configParameters 块与文件自身的 inParams 不一致），但不会追查外部引用。

CAC 说明： 自定义 Angular 组件（configurationTypeId: 36，即 dxs ng 工作文件夹——包含 manifest.json 和带有 //#region __COMPONENT_TYPES__/__COMPONENT_BODY__ 的 app.<ref>.component.ts）不是单个 JSON 主体，因此此技能的后缀分发机制不适用。请按照 custom-angular-component-creator 自带的预检清单进行审核。

参考资料

• ../datex-studio-conventions/file-format.md — configurationTypeId 表、单行压缩 JSON 规则、TypeScript 表达式编码
• ../datex-studio-conventions/naming-conventions.md — 后缀表、referenceName 与文件名主干规则、snake_case 与 camelCase 使用指南
• ../datex-studio-conventions/defaults.md — 默认 accessModifier、description 长度上限、默认包规则
• 创作者技能参考文档（此验证器分发到其中的规则手册；参见下方子 Agent 部分中的后缀表）

依赖项

• 创作者技能（action-creator、function-creator、grid-creator、hub-creator、form-creator、editor-creator、selector-creator、storage-creator、type-definition-creator、backend-test-creator、datasource-creator）——每个技能的 references/<type>.md 文档都是此验证器根据文件后缀分发到的规则手册。更新这些文档后，此验证器会自动采用新规则。
• custom-angular-component-creator 技能——CAC（configurationTypeId: 36）工作文件夹不会按后缀分发（见下方子 Agent 表中的 CAC 行）；此验证器会改为指向该技能自带的预检清单作为规则手册。
• datex-studio-conventions 技能——适用于所有组件（无论后缀为何）的通用横切规则（文件格式、命名、默认值）。
• datex-studio-shared / datex-studio-runtime 技能——各类型规则文档中引用的分支设置基础项和平台运行时全局变量。
• tailoring-overlay 技能——当文件是定制覆盖变体而非基础组件时，会调用其中的覆盖专用阴影标记规则。
• component-wiring-check 技能——当待办清单指出连线偏差，且父级希望进一步追查时，会调用此技能进行跨组件审核。

工作流

此技能通常由创作者技能在编写流程结束时调用；用户也可以直接使用“合并前审核此文件”来调用。调用方式是通过 Task 工具分派子 Agent——将下方 ## 子 Agent 部分中的提示词模板连同目标文件路径一起提供给子 Agent。

调用（编排器侧）

1. 确定目标正文 — 父级刚刚创建或修改的组件。分支是事实来源，因此目标是以下之一：(a) 创建器技能即将执行 dxs configuration upsert 的暂存草稿 body.json（推送前审计），或 (b) 从分支重新获取的文件 — dxs source explore config <referenceName> --branch <id>，或 dxs configuration get <type> <id> -b <id> -O envelope.json && jq .json envelope.json > body.json。切勿把持久的本地 src/ 副本当作权威文件来审计。将该单个草稿 / 获取的 JSON 文件路径传给子 Agent。
2. 派发子 Agent — 使用 Task 工具，并采用 ## Sub-agent 部分中的提示词模板。子 Agent 可以使用 Read、Grep、Glob；它不会编辑文件。
3. 处理待办清单 — 子 Agent 会返回一份按严重程度分组的 Markdown 待办清单。按以下方式处理每项发现：
   • 阻塞项 — 必须在执行 upsert 前修复。将修复交由相应的创建器技能处理。
   • 警告 — 审查并决定如何处理。可能是有意为之；子 Agent 不会擅自推断意图。
   • 小建议 — 可选的清理。除非父级本来就在修改相关区域，否则可暂缓处理。
4. 修复后重新验证 — 如果修复了阻塞项，再运行一次验证器。验证器开销很低（读取一次规则文档并执行一次 Grep），应作为推送前的最后一步。

范围约束（验证器职责）

• 验证器只负责读取；不会编辑。父级负责修复。
• 验证器返回的是待办清单；不会返回改写后的内容。
• 验证器只审计一个文件；不会追踪跨组件引用（这属于 component-wiring-check 的职责）。
• 验证器不会加载原始 OData 架构文档。如果文件是需要根据实时架构验证实体 / 属性的数据源，验证器会建议父级单独调用 schema-explorer。
• 验证器不会揣测意图。如果某项规则违规可能是有意为之，则会作为警告标记并附注，而不是标记为阻塞项。

子 Agent

以下提示词模板供编排器传递给 Task 工具，用于派发子 Agent。子 Agent 只读（Read、Grep、Glob）。

---

你要根据对应类型的编写规则，验证单个 Datex Studio 组件文件。你不会编辑文件。你会返回一份待办清单。

工作流

1. 根据文件后缀识别组件类型，并加载匹配的规则文档。 创建器技能中的 references/<type>.md 是主要来源；跨领域约定文档也始终适用。

   后缀	主要规则来源（创建器技能）
   *-footprintFlow.json（操作）	../action-creator/references/actions.md
   *-flow.json（函数）	../function-creator/references/functions.md
   *-grid.json	改用 grid-validator——它包含此通用分发器未涵盖的网格专属注意事项。仅当 grid-validator 不可用时，才回退到 ../grid-creator/references/grids.md。
   *-form.json	../form-creator/references/forms.md
   *-editor.json	../editor-creator/references/editors.md
   *-hub.json	../hub-creator/references/hubs.md
   *-storage.json	../storage-creator/references/storage.md
   *-selector.json	../selector-creator/references/selectors.md
   *-customType.json	../type-definition-creator/references/type-definitions.md
   *-backendTest.json	../backend-test-creator/references/backend-tests.md
   *-datasource.json	../datasource-creator/references/odata-datasources.md（如果正文结构由 flow 支持，也需加载 flow-datasources.md）
   *-footprintDatasource.json	../datasource-creator/references/odata-datasources.md、../datasource-creator/references/flow-datasources.md
   CAC 工作文件夹（包含 manifest.json 和 app.<ref>.component.ts，并带有 //#region __COMPONENT_TYPES__/__COMPONENT_BODY__），configurationTypeId: 36	不适用此文件后缀分发规则——CAC 不是单个 JSON 正文。请根据 ../custom-angular-component-creator/SKILL.md 的 Pre-Flight Checklist 和 ../custom-angular-component-creator/references/custom-angular-components.md 进行审核，而不是匹配后缀的规则文档。

   如果后缀与表中任何项目都不匹配，请回复 Cannot validate: unknown component suffix '<suffix>'. Supported: <list>. 并停止。如果文件被识别为定制覆盖项，也要加载 ../tailoring-overlay/ 规则。

2. 完整读取目标正文。 单个文件，读取一次。这是父流程暂存以供 upsert 的临时 JSON（或者刚从分支用 jq .json 获取的 JSON）——它是一次性临时文件，不是持久的事实来源副本。你将依据清单审核的对象，是这个压缩后的 JSON 信封。

3. 阅读匹配规则文档的 Pre-Flight Checklist 部分。 该部分就是规则手册。不要凭记忆重新推导规则——请按文档所述执行。

4. 逐项检查清单。 对每个问题，记录：

   • 严重程度——blocker（静默运行时失败、导入错误、明显违反规则）、warning（偏差或不一致，可能产生影响，也可能不会）、nit（风格、命名或可选的清理项）。
   • 规则——对应的清单条目。
   • 位置——<filename>:<line> 或 JSON 路径（例如 inParams[0].objectTypeDef）。
   • 证据——简短引文或描述。

5. 始终检查通用的跨领域故障模式，即使类型专属清单没有重复列出。这些项目只在 ../datex-studio-conventions/universal-checklist.md 中枚举了一次——请逐项检查（description ≤ 100 chars、已设置 accessModifier、referenceName ↔ stem、单行压缩 JSON、正确的 configurationTypeId、新增 inParams/outParams 的 id 使用 snake_case、新增项使用 id: 0）。对于定制覆盖文件，还需额外遵循 ../tailoring-overlay/ 中的 shadow-marker 规则。

6. 报告。 按严重程度分组，返回简短的 Markdown 问题清单，每项一到两行。不加前言，不重写内容，不提供代码建议（单行指引除外）。如果没有问题，请回复 No issues found.。

范围约束

• 你只阅读，不编辑。
• 你只返回问题清单，不重写内容。
• 不追查跨组件引用——这是 component-wiring-check 的职责。如果从单个文件中就能明显看出接线问题（例如 configParameters 块与文件自身的 inParams 不匹配），请将其标记为警告，并由上级决定是否进一步委派。
• 不加载原始 OData 架构文档。如果组件是需要验证实体／属性的数据源，请建议上级另行调用 schema-explorer 技能。
• 不揣测意图。如果规则违规可能是有意为之，请附注标记为警告，而非阻断项。
• 生成器输出优先于参考骨架。如果某个值来自 dxs … generate 命令，且与文档中的骨架不同，只有规则文档明确指出会导致具体故障（导入／验证错误、代码生成故障）时，才报告为阻断项。否则，请将其作为指出不匹配的细微问题，并保留该值。

输出格式

## Blockers
- [`description`] is `null` (defaults.md requires non-empty).
- [`inParams[3].objectType`] references `Allocations.i_unknown_type` — type file not present in the package.

## Warnings
- [`outParams[0].id` = "alertList"] camelCase; new params should be snake_case.

## Nits
- [`title`] equals `referenceName`; a human-readable title is more discoverable in Datex Studio listings.

省略任何内容为空的类别。如果三个类别都为空，则返回 No issues found.。

捆绑的保存门禁钩子（可选）

scripts/validate-component.py 是 Claude Code 的 PostToolUse 钩子，在工具框架层面强制执行两项成本最低的基础检查（JSON 有效，且描述存在并且不超过 100 个字符），在任何技能运行前阻止错误保存。请按 scripts/INSTALL.md 中的说明安装。此钩子只是基础门槛，不能替代本技能的审查。