canonical_id: "kbdb_get"
display_name: "KBDB 讀取"
category: "data"
version: "v1"
wasi_target: "preview1"
stability: "floating"
runtime_compat:
  - "cf-workers"
  - "workerd"
  - "wazero"
constraints:
  max_size_kb: 2048
  max_cold_start_ms: 50
  no_network_syscall: false
  no_filesystem_syscall: true
  io_model: "stdin_stdout_json"
input_schema:
  type: object
  required: [api_key]
  properties:
    api_key:
      type: string
      description: KBDB partner key（pk_live_xxx 或 ak_xxx）
    block_id:
      type: string
      description: 取單一 block。給 block_id 走 GET /blocks/{id}，與 page_name 二擇一
    page_name:
      type: string
      description: 按 page_name 查列表。走 GET /blocks?page_name=...&limit=N
    limit:
      type: integer
      description: page_name 模式下的最大筆數，預設 50
      default: 50
    kbdb_url:
      type: string
      description: KBDB API base（選填，預設 https://kbdb.finally.click）
      default: "https://kbdb.finally.click"
output_schema:
  type: object
  properties:
    success:
      type: boolean
    blocks:
      type: array
      description: page_name 模式回多個 block；block_id 模式回 1 個（仍包成陣列方便下游 foreach）
      items:
        type: object
    count:
      type: integer
      description: blocks.length
    error:
      type: string
gherkin_tests:
  - scenario: "缺 api_key"
    given: '{"page_name":"x"}'
    then_contains: '{"success":false'
  - scenario: "block_id 與 page_name 都沒給"
    given: '{"api_key":"pk_live_x"}'
    then_contains: '{"success":false'
tags: [data, storage, kbdb, get, query, primitive]
description: "從 KBDB 讀 block。支援兩種模式：(1) block_id 取單一 block；(2) page_name 取列表。透過 host function http_request 呼叫 KBDB GET /blocks 或 /blocks/:id。Mira wiki 合成 / 各 source workflow 讀草稿 / 查 wiki schema 都走這條。"
config_example: |
  read_schema:                # 取單一 block
    api_key: "{{secret.kbdb_key}}"
    page_name: "mira-wiki-schema"
  read_drafts:                # 取列表
    api_key: "{{secret.kbdb_key}}"
    page_name: "{{prev.entity_name}}"
    limit: 100