canonical_id: "kbdb_patch_block"
display_name: "KBDB Block 部分更新"
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, block_id]
  properties:
    api_key:
      type: string
      description: KBDB partner key（pk_live_xxx 或 ak_xxx）
    block_id:
      type: string
      description: 要更新的 block UUID
    content:
      type: string
      description: 新內容（傳入則覆寫；不傳則不動）
    tags:
      type: array
      items: { type: string }
      description: tags 陣列（完整覆寫；不傳則不動）
    refs:
      type: array
      items: { type: string }
      description: refs 陣列（完整覆寫；不傳則不動）
    source:
      type: string
      description: 來源標記（傳入則覆寫）
    metadata_json:
      type: object
      description: 任意附加資料（完整覆寫）
    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
    data:
      type: object
      description: KBDB 回傳的更新後 block
    error:
      type: string
gherkin_tests:
  - scenario: "缺 block_id"
    given: '{"api_key":"pk_live_x"}'
    then_contains: '{"success":false'
  - scenario: "至少要一個欄位"
    given: '{"api_key":"pk_live_x","block_id":"b_x"}'
    then_contains: '{"success":false'
  - scenario: "改 content"
    given: '{"api_key":"pk_live_x","block_id":"b_x","content":"new"}'
    then_contains: 'success'
tags: [data, storage, kbdb, patch, edit, primitive]
description: "PATCH 一個既有 KBDB block 的欄位（content / tags / refs / source / metadata_json）。透過 host function 呼叫 KBDB PATCH /blocks/:id。Mira 前端 inline edit 與 AI 自我修正使用，本零件為 P0 必備。"
config_example: |
  patch_block:
    api_key: "{{secret.kbdb_key}}"
    block_id: "{{previous_node.output.block_id}}"
    content: "新內容"
    tags: ["news", "ai"]