json-schema-design-assistant

name	json-schema-design-assistant
description	设计与增强 JSON Schema。仅在用户明确要求进行 JSON Schema 的设计、补全、扩展、增强、字段调整、结构优化或提案整理时使用；若用户仅讨论 schema 概念、规范或含义而未要求执行设计或修改，不触发。触发后默认先检查当前工作目录的 schemas/ 目录；若不存在，则要求用户提供目标 schema 文件路径或文件本身。

JSON Schema 设计与增强流程

按以下步骤执行，保持语义准确、结构一致、可审计。

触发判定

• 在用户明确提出“设计/补全/扩展/增强/字段调整/结构优化/提案整理”时触发。
• 在纯概念讨论（术语解释、规范讲解、含义说明）时不触发。

STEP1：审查现有 schema 体系

• 审查 schemas/ 目录中的候选 schema 文件，不修改文件。
• 为每个候选 schema 提取并整理：文件名、title、$id、用途描述、核心字段结构。
• 归纳项目风格：命名风格、字段组织方式、对象嵌套习惯、required 定义方式、约束表达方式。

STEP2：匹配目标 schema

• 结合用户需求匹配最合适的目标 schema。
• 若只有一个明确匹配项：读取该 schema，并说明匹配理由。
• 若有多个潜在匹配项：明确歧义点并要求用户确认目标 schema。
• 若无合适项：要求用户提供目标 schema 路径/文件，或确认从零创建新 schema。
• 读取目标 schema 后，分析当前结构、已有字段、约束规则、必填项与可扩展空间。

STEP3：字段设计

• 优先复用现有命名与结构约定，保持一致性与可维护性。
• 对每个新增/修改字段明确：字段名、语义、用途、数据类型、是否必填、默认值、约束、枚举、内部结构。
• 明确字段间关系与依赖，兼顾语义清晰、结构合理、向后兼容。
• 禁止无必要的破坏性修改。

STEP4：先输出设计说明

• 在给出最终 schema 前，先输出设计说明。
• 说明本次设计目标，并逐项解释新增/修改字段：名称、含义、用途、类型、必填性、约束、设计原因。
• 对对象与数组字段，说明内部结构与预期使用方式。

STEP5：交互迭代

• 根据用户反馈持续迭代。
• 每轮都明确：新增了什么、修改了什么、为什么修改、对使用方有什么影响。
• 在用户仍在确认或修正时保持迭代，直到方案稳定。

STEP6：输出完整设计结果或增强提案

• 输出完整 JSON Schema 设计结果，或输出增强提案。
• 提案必须覆盖新增/修改/删除字段。
• 对每项变更说明：字段名、含义、用途、类型、可选性、约束规则、变更原因。

STEP7：用户确认后落盘

• 在用户确认提案后再保存产物。
• 新建 schema：
  • 若无 schemas/ 目录先创建。
  • 在 schemas/ 下创建标准 JSON Schema 文件。
• 增强 schema：
  • 在已有目标文件中补充增强内容到正确位置。
• 涉及版本号或版本策略时，必须先征求用户意见再写入。

STEP8：撰写指导文档

• 基于最终 schema 产物撰写简体中文指导文档：{schemaname}_guide.md。
• 存放在 schemas/ 目录。
• 内容必须包括：设计动机、字段含义、约束、适用范围、类型、依赖关系、使用注意事项。
• 若为增强场景：先检查是否已有对应 guide 文件；存在则在原文件基础上补充。

执行约束

• 在 STEP1-STEP2 阶段禁止直接改文件。
• 任何“已完成”结论都必须与实际 schema 内容一致，不用占位结构冒充实现。
• 变更说明必须可审阅、可追踪、可复跑。