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: 模式 A — 取單一 block by id（指定後其他 filter 都忽略）
    page_name:
      type: string
      description: 模式 B — 按 page_name 查列表（可疊 type / source / user_id filter）
    type:
      type: string
      description: filter — block type（如 wiki-page / wiki-paragraph / triplet / note）
    source:
      type: string
      description: filter — block source（如 km-writer-direct / ai-canon-wiki）
    user_id:
      type: string
      description: filter — block user_id（如 inkstone_mira_tools）
    limit:
      type: integer
      description: 列表模式 limit，預設 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: "沒給任何查詢條件"
    given: '{"api_key":"pk_live_x"}'
    then_contains: '{"success":false'
  - scenario: "用 type filter 列 wiki-page"
    given: '{"api_key":"ak_x","type":"wiki-page"}'
    then_contains: 'blocks'
tags: [data, storage, kbdb, get, query, filter, primitive]
description: "從 KBDB 讀 block。三種模式：(A) block_id 取單一；(B) page_name 取列表（可疊 filter）；(C) 純 type / source / user_id filter（不需 page_name）。透過 host function http_request 呼叫 KBDB GET /blocks 或 /blocks/:id。Mira wiki_synthesis / feed watcher / 各 source workflow 都走這條。"
config_example: |
  read_schema:                # 模式 A — 單一 block by id
    api_key: "{{api_key}}"
    block_id: "26c51776-d07c-4490-9836-95e554d64549"
  read_drafts:                # 模式 B — page_name 列表
    api_key: "{{api_key}}"
    page_name: "{{prev.entity_name}}"
    limit: 100
  list_unprocessed_raws:      # 模式 C — 純 filter（mira_feed_watcher 用）
    api_key: "{{api_key}}"
    source: "km-writer-direct"
    type: "note"
    user_id: "inkstone_mira_post"
    limit: 50