Imported from windwolf/wibotstudio (
.github/skills/scenario-json-authoring/SKILL.md). Install upstream withnpx skills add windwolf/wibotstudio --skill scenario-json-authoring. Copyright stays with the author.
Scenario JSON Authoring
根据需求编写、修改或审查 circalc 场景配置 JSON，并确保配置可通过项目校验。
何时使用
- 需要新增一个场景配置文件到
public/configs/。 - 需要调整已有场景的
groups、输入参数或公式计算项。 - 需要修复配置校验错误（ID、单位、公式、分组条件、重复定义等）。
- 需要把自然语言需求转换为合法场景 JSON。
核心原则
docs/config-guide.md是唯一事实源（Single Source of Truth）。- 不在本技能中复制字段表、单位族表、公式能力清单或模板细节。
- 每次执行先读取
docs/capbilities/calculator/config-guide.md，按其当前内容实现。 - 输入参数和计算项
id在满足规范前提下应优先保持短小、清晰、可读，避免无信息增益的超长前缀。 - 如果示例配置与指南冲突，以指南为准。
- 只有在运行目录、校验命令、或技能触发目标发生变化时，才需要修改本技能。
输入期望
用户通常会提供以下信息（可不完整）：
- 场景目标与业务背景
- 需要输入的物理量与单位偏好
- 期望输出（计算项）与公式关系
- 是否包含互斥方法（
choice+activeWhen） - 文件名或场景 ID 偏好
工作流程
- 读取并对齐规范
- 先读取
docs/config-guide.md。 - 提取当前版本要求的结构、ID 规则、单位规则、公式规则、校验命令。
- 建模场景结构
- 先确定
id、name、description和分组划分。 - 按页面展示顺序组织
groups。
- 编写输入参数
- 显式区分
number与choice输入。 - 为数值输入设置合法
unit/defaultUnit，并按基础单位写value。
- 编写计算项
- 所有计算项显式使用
type: "formula"。 - 公式仅引用已定义且在当前上下文可用的数值
id。
- 处理条件分支（如有）
- 用
choice输入表达方法选择。 - 用
activeWhen控制互斥分组启用。 - 需要共享输出契约时，确保同名
id仅出现在互斥分组，且单位兼容。
- 执行自检
- 按指南逐项检查：重复 ID、非法变量名、缺失
defaultUnit、单位不匹配、公式可解析性、循环依赖与非有限值风险。 - 复查公式可读性：在不牺牲语义清晰度前提下，确保用于计算的变量
id没有冗长命名。
- 执行校验
- 默认必须运行指南中的单文件校验命令验证目标 JSON。
- 改动较大时运行
bun test进行回归验证。
- 交付结果
- 输出最终 JSON 变更。
- 简要说明关键设计选择、假设和已执行校验。
决策分支
- 如果需求缺少关键变量或公式：先提问补全，再生成配置。
- 如果需要多种方法：优先建模为
choice+ 互斥activeWhen分组。 - 如果同名
id可能同时激活：改名或重构分组，避免重复定义。 - 如果单位表达不清：先确认单位族，再决定
defaultUnit。 - 如果公式引用存在上下文不确定：重构分组或补齐覆盖分支。
完成标准
- JSON 可被 schema 解析并通过
validateScenario。 - 结构、字段、ID、单位、公式全部符合
docs/config-guide.md。 - 用于公式计算的
id简洁一致，公式表达清晰，避免不必要的长变量名。 - 场景在运行时可加载，互斥分支行为符合预期。
- 输出说明包含：改动内容、假设点、验证结果。
资源
- 规范文档：
docs/config-guide.md - 示例配置：
public/configs/与examples/
