tacbench-schema-validator-designer

name	tacbench-schema-validator-designer
description	Design or update Tacbench schemas and validators. Use when defining beginner-mode fields, advanced-mode source editing, required or deprecated fields, validation rules, or compatibility handling for guns, attachments, ammo, blocks, and melee plugins.

Tacbench Schema And Validator Designer

适用于 Tacbench 的 schema 与校验规则设计。

Use this skill when

• 要定义枪、配件、弹药、方块或近战模块的字段模型。
• 要把样本枪包结构转成基础模式与高级模式。
• 要新增或修改 validator。
• 要标记必填字段、兼容字段、废弃字段、推断字段。

Read first

• Tacbench V1 plan
• AGENTS.md
• ../../../packages/core/src/types.ts
• ../../../packages/core/src/resource-graph.ts
• ../../../packages/validation/src/

Design rules

• 优先基于真实样本和 TACZ 源码行为，不凭空发明字段。
• 基础模式只暴露高价值字段；高级模式必须保留原始 JSONC/Lua。
• validator 既要识别错误，也要识别风险和兼容性提醒。
• 不覆盖未知字段，不强制把所有资源类型塞进同一 schema。
• melee 走插件 schema，不污染 gun 核心模块。
• schema-backed 文档的字段知识优先来自 schema + 默认枪包 JSONC 注释 + 少量 curated override，不要再靠手写关键字段列表硬撑全局。
• 原始 asset 文件（animation / model / sound / texture）不强行伪装成 schema 字段卡片；它们继续走资源图和源码诊断链。

Workflow

1. 先明确资源类型、文件分布和引用关系。
2. 列出用户真正需要可视化的字段组。
3. 区分：
   • 必填字段
   • 推荐字段
   • 隐藏或高级字段
   • 已废弃或兼容字段
4. 为每条规则定义：
   • 触发条件
   • 严重级别
   • 消息格式
   • 修复建议
5. 指明这些规则应挂到哪个模块或验证入口。

Current diagnostics authoring rules

当任务涉及校验文案、诊断详情、字段解释或报错优化方案时，优先按这些规则设计：

1. ValidationIssue 是原始规则输出，UI 真源应映射到 DiagnosticRecord，不要把展示文案直接散落在组件里。
2. 详细诊断模板至少应包含：
   • Problem
   • Output
   • Debug
   • why
   • evidence
   • fixes
3. 需要逐字段解释的诊断，优先挂接：
   • resourceType
   • documentRole
   • jsonPath
   • FieldKnowledgeCatalog
4. 不要把不同语义的问题混成一个规则：
   • 缺失语言键
   • 缺失引用
   • 逻辑 ID 冲突
   • 孤立资源
   • 默认包覆盖风险
   • 编码异常 应各自有独立 issue code 和修复建议。

Current encoding and runtime issue rules

1. 编码问题是工作区级诊断输入，不是编辑器里的零散提示。
2. 当前编码规则应优先覆盖：
   • encoding-unreadable
   • encoding-text-binary-mismatch
   • encoding-non-utf
3. UTF-8 BOM 默认只展示元数据，不自动升成噪音 warning，除非需求明确要求。
4. 运行时异常、F12 未捕获错误、native error 也应能映射成详细诊断，但不要和 schema validator 规则混成同一来源枚举。

Output expectations

• 给字段分组，而不是扔一整坨扁平字段表。
• 给 validator 代码落点和 issue code 命名。
• 明确哪些规则是硬错误，哪些只是警告或信息提示。
• 如果规则会进入 IDE 工作台，顺手给出“它应落在问题 / 输出 / 调试的哪一条链路”。