# JsonLogic
用於處理 JsonLogic 的技能。
[JsonLogic](https://jsonlogic.com) 是一種小巧、可攜帶的格式,用於將條件邏輯表達為 JSON。
JsonLogic 標準是通用的規則格式,並定義其語義。此層級的規則是語言無關的。請參閱 [references/jsonlogic.md](references/jsonlogic.md) 和
[references/operations.md](references/operations.md)。
特定函式庫是在特定語言中執行 JsonLogic 的程式碼,例如 **JavaScript** 的 **json-logic-js** 或 **Ruby** 的 **json-logic-rb**。不同函式庫所支援的操作、API 形式以及錯誤處理方式可能有所不同。
## 執行 JsonLogic
### 函式庫
如果指定了特定的實作,例如 **json-logic-js**,請使用該確切實作。僅有語言名稱,例如 **"in Python"**,表示使用 [references/libraries.md](references/libraries.md) 中該語言的函式庫。如果既未指定函式庫也未指定語言,則預設使用 [scripts/jsonlogic.rb](scripts/jsonlogic.rb)。
### 支援
一條規則可能是有效的 JsonLogic,但仍不受所選函式庫或其當前版本支援。請標記不受支援的操作。切勿只因某個函式庫無法執行就改寫有效的 JsonLogic 規則。請指出限制所在的層級,並提供真實的選項:
- 自訂操作
- 如果特定實作中不支援該操作,更換不同的函式庫
- 變更邏輯
## Playground 構件
每當涉及具體規則(建立、說明、修正或執行)時,請將其即時呈現,而不僅以文字描述:使用該規則和資料初始化 [assets/playground.html](assets/playground.html)
,然後使用 Artifact 工具發布它。此操作在安裝此技能的使用者環境下執行 — 每次發布呼叫都會在該使用者自己的帳戶下建立構件,因此對每個安裝者來說運作方式相同,無需分享步驟。該構件預設為私有,此處發布僅會更新同一個 URL,因此無需每次都做出單獨的決定。
兩個檔案,一個是靜態的,一個是模板化的:[assets/jsonlogic-core.js](assets/jsonlogic-core.js)
是 JsonLogic 直譯器 — 它在每次調用之間不會改變,因此請在每次對話中發布一次(透過 Artifact 工具的 `files` 參數),之後不再發布。
[assets/playground.html](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 自身的 truthy/falsy 規則;只有 Ruby 不同)。如果尚未決定語言 → 保持不變,會回退到 `"jsonlogic"`。
4. 將 `__VERIFY_LIB_LABEL__` 替換為**執行 JsonLogic → 函式庫**(上文)中為此任務解析出的相同函式庫 — 這就是頁面 "Verify in chat" 按鈕在請求驗證實際實作時所使用的名稱,因此它必須匹配,而不只是因為這是該檔案自身的回退值就預設使用 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](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
**第一步:取得資料形狀**
在建立新規則之前,務必詢問如何取得資料的欄位名稱。將此呈現為選擇題。當可用時,使用用戶端的結構化提問機制,例如按鈕或選取器。否則,以純文字形式呈現選項。
問題:「如何取得您資料的欄位名稱?」。提供三個選項:
- 選項 **Schema** — 「我會貼上一個 schema — JSON Schema、OpenAPI 或其他任何格式。」
- 選項 **範例資料** — 「我會貼上一個真實的 JSON 範例。」
- 選項 **直接猜測** — 「根據我的描述推斷欄位名稱。」
對話僅用於選擇方法。實際答案仍然作為普通的後續訊息傳入,不會在對話本身內部傳遞。
**第二步:建立表達式**
使用第一步中的欄位名稱撰寫規則。
在編寫新規則之前,請查看 [references/operations.md](references/operations.md)
以取得完整的支援清單,並查看 [examples/](examples/) 以取得已完成的模式。如需每個運算子的真實上游測試案例,請參閱 [references/tests/](references/tests/)。
#### 自訂
不要期望 JsonLogic 包含所有專門的操作。它被刻意設計得小巧,並且不是一種程式語言。它永遠無法做到所有事情。但是 JsonLogic 支援擴展。在尋求自訂解決方案之前,請先看看是否可以使用支援的操作(內建)來表達您的邏輯。通常,只需改變一下觀點,就能使用現有功能完成任務。
**第三步:解釋其作用**
涵蓋:
- 正在編碼的需求
- 所使用的操作以及每個操作的作用
- 預期的輸入形狀
- 規則的回傳值
- 值得標記的邊界情況(缺少欄位、型別強制轉換、空陣列)
跳過不適用的項目。
### 缺少資訊
如果業務條件不明確 – 您應該詢問規則需要檢查什麼,但不要詢問那些您已經可以從上下文解決的事情。
## 驗證 JsonLogic
根據 [references/jsonlogic.md](references/jsonlogic.md)、
[references/operations.md](references/operations.md) 或
[scripts/validate_skill.rb](scripts/validate_skill.rb) 檢查形狀僅能確認規則的形狀符合 JsonLogic。
真正的驗證意味著撰寫測試案例並透過
[scripts/jsonlogic.rb](scripts/jsonlogic.rb) 執行它們。請參閱
[references/testing.md](references/testing.md) 以了解如何選取它們。涵蓋正常情況和邊界情況,但尤其要側重於邊界情況:缺少欄位、空陣列、意料之外的型別。沒有測試案例的規則無法安全移交 — 無法保證其行為符合預期。
對於規則使用的各個運算子,請先檢查
[references/tests/](references/tests/) — 核心規範(`core.json`)和社群擴展(`community/`)的真實上游案例,已本地捆綁。在從頭編寫新案例之前,重用匹配的案例作為合理性檢查;這些測試了運算子的隔離行為,而不是規則的實際業務邏輯,因此仍然需要在此基礎上添加規則特定的案例。
## 除錯 JsonLogic
**第一步:重現問題**
使用**執行 JsonLogic** 並帶入報告中的規則和資料。
在診斷任何問題之前,先親自查看實際輸出。
**第二步:找出真正原因**
直接指出真正原因,而不僅僅是症狀 — 常見元兇:型別強制轉換、
缺少欄位、運算子誤用。
**第三步:修正並驗證**
提供修正後的規則,然後使用修正後的規則重新執行第一步,以確認新輸出是
正確的。如果需要將修正後的規則作為可執行碼交回,請繼續執行下面的**執行 JsonLogic**。
## 任何操作之後
### 驗證執行
請參閱上面的**執行 JsonLogic** 來實際執行規則。如果手邊還沒有資料範例,請先建立一個具有代表性的範例。驗證需要真實的輸入來執行,而不僅僅是對規則應執行操作的描述。
### 標記疑慮
不要僅僅因為它是 JSON 就聲稱 JsonLogic 是「安全的」。
## 參考檔案
根據需要閱讀這些檔案,而不是一次性全部載入:
- [references/jsonlogic.md](references/jsonlogic.md) — 核心
語義:truthiness、型別強制轉換、`var` 路徑解析、缺少資料時的行為、什麼是「合規」。
- [references/operations.md](references/operations.md) — 每個標準操作:
語法以及值得注意的行為說明(短路求值、三個參數比較、`reduce` 的 `current`/`accumulator` 等等)。
- [references/libraries.md](references/libraries.md) —
跨語言的函式庫概況:發現了什麼、驗證了什麼、沒有驗證什麼。在撰寫任何語言特定的程式碼之前閱讀,包括未列出的語言 — 先在那裡檢查,而不是假設不存在。
- [references/testing.md](references/testing.md) — 如何驗證規則或
實作,以及如何在給定的答案中誠實地說明「已驗證」的含義。
- [references/tests/](references/tests/) — 捆綁的上游測試案例(核心規範 +
社群擴展),用於驗證各個運算子。
- [examples/](examples/) — 已完成的範例:
- [basic-rules.json](examples/basic-rules.json)
- [conditions.json](examples/conditions.json)