Communitygithub.com

jsonlogic

处理 JsonLogic 业务规则——一种基于 JSON 的条件逻辑格式 (jsonlogic.com)。适用于用户需要将业务需求转换为 JsonLogic 规则、解释或调试现有 JsonLogic 表达式、验证规则有效性、在特定语言(JavaScript、TypeScript、Python、Ruby、Java、PHP、Go、C# 等)中执行 JsonLogic、选择或比较 JsonLogic 库,或将 JsonLogic 集成到应用程序中的场景。当提到 JsonLogic、json-logic、形如 {"var": ...} 的 JSON 规则对象,或要求将条件和业务规则表达为可移植 JSON 时触发。不适用于不涉及 JsonLogic 格式的通用编程任务。

jsonlogic 是什么?

该技能专门用于处理 JsonLogic——一种基于 JSON 的可移植条件逻辑格式。它帮助开发者将业务需求转换为 JsonLogic 规则、解释和调试现有表达式、验证规则有效性,并在多种编程语言中执行 JsonLogic,包括 JavaScript、TypeScript、Python、Ruby、Java、PHP、Go、C# 等。技能通过读取本地参考资料和脚本,自动选择合适的语言库,并支持创建交互式 playground 工件,让用户可以在浏览器中实时编辑规则和数据并查看结果。在编写新规则前,技能会询问数据字段名的获取方式(架构、示例数据或根据描述推断),并参考操作文档和示例来构建正确的表达式。验证不仅检查语法形状,还通过编写测试用例并使用本地脚本运行来保证规则的行为符合预期。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/valeryia-piatrova/jsonlogic-skill/tree/main

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

jsonlogic 是做什么的?

用于处理 JsonLogic 的技能。

JsonLogic 是一种小巧、可移植的格式,用于将条件逻辑表达为 JSON。

JsonLogic 标准是通用规则格式,并定义了其语义。此级别的规则与语言无关。请参阅 references/jsonlogic.md 和 references/operations.md。

特定库是在特定语言中执行 JsonLogic 的代码,例如用于 JavaScript 的 json-logic-js 或用于 Ruby 的 json-logic-rb。不同库在支持的操作以及 API 结构和错误处理方面可能存在差异。

运行 JsonLogic

库

如果指定了具体的实现,例如 json-logic-js,则使用该确切的实现。仅指定语言名称,例如 “in Python”,意味着使用 references/libraries.md 中该语言的库。如果既未指定库也未指定语言,则默认使用 scripts/jsonlogic.rb。

支持

规则可以是有效的 JsonLogic,但仍然不被所选库或其当前版本支持。应标记不支持的操作。切勿仅仅因为某个库无法运行就重写有效的 JsonLogic 规则。应说明限制所在的层级,并提供真实选项:

  • 自定义操作
  • 如果特定实现不支持该操作,则使用不同的库
  • 逻辑更改

Playground 工件

每当涉及具体规则(创建、解释、修复或执行)时,应以实时方式呈现,而不仅仅用文本描述:使用该规则和数据填充 assets/playground.html,然后通过 Artifact 工具发布。该操作在安装该技能的用户下运行——每次发布调用都会在该用户自己的账户下创建工件,因此对每个安装者来说工作方式相同,无需共享步骤。工件默认是私有的,此处发布只是更新相同的 URL,因此无需每次都做出单独的检查决定。

两个文件,一个静态,一个模板化:assets/jsonlogic-core.js 是 JsonLogic 解释器——它在不同调用之间从不改变,因此每个对话只发布一次(通过 Artifact 工具的 files 参数),之后不再发布。assets/playground.html 是包含以下占位符的薄页面;它是唯一需要重新模板化并在每次更改时重新发布的文件。

  1. 读取 assets/playground.html。它是一个固定设计的页面(规则、实时结果、数据)——切勿手动编辑其 CSS/布局;每次调用时只有以下占位符会更改。
  2. 将 __INITIAL_RULE__ 和 __INITIAL_DATA__ 替换为规则/数据对象,每个对象作为 JS/JSON 字面量(JSON.stringify(...) 的输出,可直接放入)。尚无具体规则 → 保持两者不变,模板会回退到内置默认值。
  3. 当目标语言是 Ruby 时,将 __CURRENT_LANG_MODE__ 替换为 "ruby",否则替换为 "jsonlogic"(此处显示的所有其他语言都遵循 JsonLogic 自身的真/假规则;只有 Ruby 有所不同)。尚未确定语言 → 保持原样,回退到 "jsonlogic"。
  4. 将 __VERIFY_LIB_LABEL__ 替换为与此任务解析的 运行 JsonLogic → 库(上文)相同的库——这是页面上的 "在聊天中验证" 按钮在请求对照实际实现进行确认时使用的名称,因此必须匹配,不要仅仅因为这是文件自身的回退就默认使用 Ruby:
    • Ruby → "json-logic-rb (scripts/jsonlogic.rb)"
    • JavaScript / TypeScript → "json-logic-js"
    • Python → "maykin-json-logic-py"
    • Java → "json-logic-java"
    • PHP → "json-logic-php (jwadhams/json-logic-php)"
    • Go → "diegoholiveira/jsonlogic"
    • C# / .NET → "JsonLogic (json-everything)"
    • references/libraries.md 中的任何其他语言 → 该库在那里给出的名称。 尚未决定语言/库 → 保持原样,回退到 Ruby 的 "json-logic-rb (scripts/jsonlogic.rb)",匹配此技能自身的默认值。
  5. 将结果写入工作文件并发布——对话中 首次:Artifact 工具,action:"publish",该文件的路径,title:"JSON Logic Playground",icon:"code",加上 files:{"jsonlogic-core.js":"assets/jsonlogic-core.js"},以便解释器原封不动地附带发布。
  6. 稍后在同一个对话中,当规则、数据或语言发生变化时,使用新值重新执行步骤 1–4,并使用 相同的文件路径 和相同的 url 再次发布——但这次省略 files,因为 jsonlogic-core.js 从不改变,省略的文件会保持原样。这将在原地更新同一个工件,而不是创建新工件。

对于不会产生具体规则的请求(例如 "missing 是做什么的"),跳过此步骤。

用户可以直接在工件中编辑规则/数据进行测试——这正是其目的,它会实时重新计算。切勿在手动编辑后重新发布。仅当用户在聊天中要求新规则或更改规则/条件时才重新发布。

编写 JsonLogic

第 1 步:获取数据形状

在创建新规则之前,始终询问如何获取数据的字段名称。将此作为选择呈现。如果可用,使用客户端的结构化提问机制,例如按钮或选择器。否则,以纯文本形式呈现选项。

问题:“如何获取数据字段名称?”提供三个选项:

  • 选项 Schema — “我会粘贴一个架构——JSON Schema、OpenAPI 或任何格式。”
  • 选项 示例数据 — “我会粘贴一个真实的 JSON 示例。”
  • 选项 直接猜测 — “根据我的描述推断字段名称。”

对话框仅选择方法。实际答案仍以正常的后续消息形式出现,而不是在对话框内部。

第 2 步:构建表达式

使用第 1 步中的字段名称编写规则。

在编写新规则之前,请检查 references/operations.md 以获取完整的支持列表,以及 examples/ 以查看工作模式。要查看每个运算符的官方上游测试用例,请参阅 references/tests/。

自定义

不要期望 JsonLogic 包含所有专用操作。它故意设计得小巧,不是编程语言。它永远不会做所有事情。但 JsonLogic 支持扩展。在寻求定制解决方案之前,请查看是否可以使用支持的操作(内置)来表达你的逻辑。通常,只需改变一下视角,就可以使用已有的操作完成任务。

第 3 步:解释其作用

涵盖:

  • 正在编码的需求
  • 使用的操作以及每个操作的作用
  • 预期的输入形状
  • 规则返回的内容
  • 值得标记的边缘情况(缺失字段、类型强制、空数组)

跳过不适用的项目。

信息缺失

如果业务条件不明确——你应该询问规则应检查什么,但不要询问你已经可以从上下文中解决的问题。

验证 JsonLogic

对照 references/jsonlogic.md、references/operations.md 或 scripts/validate_skill.rb 检查形状只能确认规则在结构上像 JsonLogic。

真正的验证意味着编写测试用例并通过 scripts/jsonlogic.rb 运行它们。有关如何选择测试用例,请参阅 references/testing.md。覆盖正常情况和边界情况,但尤其要侧重于边缘情况:缺失字段、空数组、意外类型。没有测试用例的规则在交付时并不安全——无法保证其行为符合预期。

对于规则使用的单个运算符,首先检查 references/tests/ ——官方上游用例,既包括核心规范 (core.json) 也包括社区扩展 (community/),已本地打包。在从头开始编写新用例之前,先重用匹配的用例作为健全性检查;这些用例单独测试运算符,而不是测试规则的实际业务逻辑,因此仍需在此基础上添加特定于规则的用例。

调试 JsonLogic

第 1 步:重现问题

使用 运行 JsonLogic 和所报告的规则与数据。在诊断问题之前,自己查看实际输出。

第 2 步:找到真正原因

首先指出真正原因,而不仅仅是症状——常见原因:类型强制、缺失字段、运算符误用。

第 3 步:修复并验证

给出更正后的规则,然后使用修复重新执行第 1 步以确认新输出正确。如果修复需要作为可运行的代码交回,请继续执行下面的 执行 JsonLogic。

之后任何操作

验证运行

参见上面的 运行 JsonLogic 来实际执行规则。如果手头还没有数据示例,请先创建一个代表性的示例。验证需要真实的输入来运行,而不仅仅是关于规则应做什么的描述。

标记注意事项

不要仅仅因为 JsonLogic 是 JSON 就说它“安全”。

参考文件

根据需要读取这些文件,而不是一次性全部加载:

  • references/jsonlogic.md —— 核心语义:真值、类型强制、var 路径解析、缺失数据的处理方式,“合规”的含义。
  • references/operations.md —— 每个标准操作:语法以及值得注意的行为说明(短路、三参数比较、reduce 的 current/accumulator 等)。
  • references/libraries.md —— 跨语言的库全景:找到了什么,验证了什么,未验证什么。在编写任何特定语言的代码之前阅读,包括未列出的语言——先在此处检查,而不是假设不存在。
  • references/testing.md —— 如何验证规则或实现,以及如何在给定答案中诚实地说明“已验证”的含义。
  • references/tests/ —— 捆绑的官方上游测试用例(核心规范 + 社区扩展),用于验证单个运算符。
  • examples/ —— 工作示例:

相关技能