變更記錄

兩者各自演進:資料版本會定期推進(詞條擴充、標註校正), 介面版本則刻意保持穩定。你的整合會受哪一種影響,取決於你依賴的是結構還是內容。

以下變更視為相容,恕不另行預告:

• 回應新增欄位。請以「忽略未知欄位」的方式解析,不要用嚴格 schema 驗證擋下。
• 新增端點、新增選用參數。
• 資料內容更新:詞條增減、標註校正、關係補完。
• 結果筆數與排序內的相對次序,可能因資料更新而變動 —— 請勿把特定查詢的 total 或第 N 筆寫進測試斷言。

以下變更視為不相容,會事先通知並提供過渡期:

• 移除或改名既有欄位、參數或端點。
• 既有參數的語義改變(例如預設值由 tagged 改為 all)。
• 錯誤狀態碼的語義改變。

{
  "active": "v20260816",
  "meta": {
    "tag": "v20260816",
    "rows": 237191,
    "stats": {
      "words": 230317,
      "word_relations": 836004,
      "syn": 475888,
      "ant": 360116,
      "categories": 49,
      "reading_coverage": 1.0,
      "source_dist": { "cow": 89010, "llm": 746994 }
    }
  }
}

• 建議在部署時記錄一次 active,並在監控中比對 —— 資料版本推進時,你的黃金測試若出現差異,可立刻歸因。
• stats 是完整統計,可用於自動偵測異常 (例如某次更新後 word_relations 大幅下跌)。
• 此端點不計速率限制,可安心用於健康檢查。

curl -s -H "Authorization: Bearer $WRITERHK_API_KEY" \
  https://api.writer.hk/api/lexicon/version | jq -r .active

若你的產品需要「線上行為完全不因資料更新而變動」—— 例如已上架的內容須可重現、或有合規上的可稽核需求 —— 版本鎖定屬 Enterprise 按需求訂製項目:為該客戶保留指定版本的索引常駐, 並約定升版時程。

一般方案共用同一份最新資料索引。實務上,把上述/version 監控接進部署流程,已足以應付絕大多數情況。

需要鎖定或其他資料授權安排,請來信洽談。

平台整體(非 API)的更新,見更新日誌。