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 是包含以下占位符的薄页面;它是唯一需要重新模板化并在每次更改时重新发布的文件。
- 读取
assets/playground.html。它是一个固定设计的页面(规则、实时结果、数据)——切勿手动编辑其 CSS/布局;每次调用时只有以下占位符会更改。 - 将
__INITIAL_RULE__和__INITIAL_DATA__替换为规则/数据对象,每个对象作为 JS/JSON 字面量(JSON.stringify(...)的输出,可直接放入)。尚无具体规则 → 保持两者不变,模板会回退到内置默认值。 - 当目标语言是 Ruby 时,将
__CURRENT_LANG_MODE__替换为"ruby",否则替换为"jsonlogic"(此处显示的所有其他语言都遵循 JsonLogic 自身的真/假规则;只有 Ruby 有所不同)。尚未确定语言 → 保持原样,回退到"jsonlogic"。 - 将
__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)",匹配此技能自身的默认值。
- Ruby →
- 将结果写入工作文件并发布——对话中 首次:Artifact 工具,
action:"publish",该文件的路径,title:"JSON Logic Playground",icon:"code",加上files:{"jsonlogic-core.js":"assets/jsonlogic-core.js"},以便解释器原封不动地附带发布。 - 稍后在同一个对话中,当规则、数据或语言发生变化时,使用新值重新执行步骤 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/ —— 工作示例: